/**
 * Declares what a link provider implements. `rich-content-service.ts` asks its
 * providers in turn and fetches a link's preview from the first that matches.
 *
 * @module
 */

import type { RichContent } from "../../../shared/dump.ts";

/**
 * Implemented by each file of `remote/providers/`, and listed in priority order
 * by `rich-content-service.ts`.
 */
export interface RichContentProvider {
  name: string;
  /** Called on a URL that `isValidHttpUrl` accepted; never throws. */
  matches(url: string): boolean;
  /**
   * Returns the preview of `url`, which ends up in the dump's `rich_content` or
   * the create form's preview. It rejects when the page can't be fetched, and
   * the service then falls back to a stub. A page that isn't HTML yields a
   * preview without metadata.
   */
  fetch(url: string): Promise<RichContent>;
}