/**
 * Dumps — the links and files users post — their link previews, and the bodies
 * that post and edit them.
 *
 * @module
 */

/** What a link's page says about itself, as its preview card shows it. */
export interface RichContent {
  /**
   * Which provider read it: `youtube`, `bandcamp`, `soundcloud` or `generic`.
   */
  type: string;
  /** The link the preview is of. */
  url: string;
  /** The site's name. */
  siteName?: string;
  /** The page's title. */
  title?: string;
  /** The page's description. */
  description?: string;
  /**
   * A real preview image (og:image, a large content image, a video still).
   * Never a favicon — an absent value means "this page offers no artwork",
   * which is what makes the generated placeholder possible.
   */
  thumbnailUrl?: string;
  /** The page's own icon, used as the placeholder's glyph. */
  faviconUrl?: string;
  /** The page's declared brand color, normalized to `#rrggbb`. */
  accentColor?: string;
  /** The YouTube video's id, for a YouTube link. */
  videoId?: string;
  /** The URL of the page's embeddable player, if it has one. */
  embedUrl?: string;
}

/** A dump: a link or a file a user posted. */
export interface Dump {
  /** The dump's id. */
  id: string;
  /** `url` for a link, `file` for an upload. */
  kind: "url" | "file";
  /** The dump's title. */
  title: string;
  /** The dump's URL slug. */
  slug?: string;
  /** The poster's description, in Markdown. */
  comment?: string;
  /** The poster's id. */
  userId: string;
  /** When the dump was posted. */
  createdAt: Date;
  /** When the dump was last edited, if ever. */
  updatedAt?: Date;
  /** The link, for a URL dump. */
  url?: string;
  /** The link's preview, for a URL dump. */
  richContent?: RichContent;
  /** The uploaded file's name, for a file dump. */
  fileName?: string;
  /** The uploaded file's type, for a file dump. */
  fileMime?: string;
  /** The uploaded file's size in bytes, for a file dump. */
  fileSize?: number;
  /** How many users upvoted the dump. */
  voteCount: number;
  /** How many comments it has, not counting deleted ones. */
  commentCount: number;
  /** Whether only the poster sees the dump. */
  isPrivate: boolean;
  /** The uploaded thumbnail's type, undefined without one. */
  thumbnailMime?: string;
  /** The ids of the categories it is filed under. */
  categoryIds?: string[];
}

/**
 * An existing dump pointing at the same URL, as shown by the create form's
 * duplicate hint (`GET /api/dumps/by-url`). Display-only projection — see
 * `findDumpsByUrl`.
 */
export interface DumpUrlMatch {
  /** The dump's id. */
  id: string;
  /** The dump's URL slug. */
  slug?: string;
  /** The dump's title. */
  title: string;
  /** The poster's name. */
  username: string;
  /** When the dump was posted. */
  createdAt: Date;
  /** How many users upvoted the dump. */
  voteCount: number;
  /** How many comments it has. */
  commentCount: number;
}

/**
 * `GET /api/preview`. `reached` is separate because a failed fetch still yields
 * a usable stub (hostname only): without it the create form can't tell "this
 * page has no preview" from "this link is dead".
 */
export interface LinkPreview {
  /** Whether the page could be fetched. */
  reached: boolean;
  /** The preview, null when there is none at all. */
  richContent: RichContent | null;
}

/** The JSON body of `POST /api/dumps`, which posts a link. */
export interface CreateUrlDumpRequest {
  /** The link. */
  url: string;
  /** Overrides the title scraped from the page — the poster edited the preview. */
  title?: string;
  /** The poster's description, in Markdown. */
  comment?: string;
  /** Whether only the poster will see it. */
  isPrivate?: boolean;
  /** The ids of the categories to file it under. */
  categoryIds?: string[];
}

/** The body of `PUT /api/dumps/:dumpId`: the fields to change. */
export interface UpdateDumpRequest {
  /** The new link, for a URL dump. */
  url?: string;
  /** The new title. */
  title?: string;
  /** `null` removes the note; leaving it out keeps it. */
  comment?: string | null;
  /** Whether only the poster will see it. */
  isPrivate?: boolean;
  /** The ids of the categories to file it under, replacing the current ones. */
  categoryIds?: string[];
}

/** `POST /api/attachments`: the id the uploaded image is served under. */
export interface AttachmentResponse {
  /** The attachment's id, for `GET /api/attachments/:attachmentId`. */
  id: string;
}