/**
 * Lets each kind of site have its own link previews. A provider implements this
 * interface, and `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 or
   * answers with an error status, and the service then falls back to a stub.
   * A page that isn't HTML yields a preview without metadata. The service
   * tidies what it returns, so a provider leaves text as the page wrote it.
   */
  fetch(url: string): Promise<RichContent>;
}