/** Which end of a page's capture history a listing starts from. */
export type CaptureOrder = "newest" | "oldest";
export interface ArchiveOptions {
  limit?: number;
  signal?: AbortSignal;
  /**
   * Earliest capture to list. Inclusive; Wayback-style digits (YYYY through
   * YYYYMMDDhhmmss) or an ISO 8601 date, and a partial stamp covers the whole
   * period it names. Providers that can narrow their own query do, the rest
   * are filtered after the fact, so the window holds across a fan-out.
   */
  from?: string;
  /** Latest capture to list; the window's other inclusive edge, same formats. */
  to?: string;
  /**
   * Which end of one page's history `limit` keeps, listed in that order. The target is a URL
   * with its scheme: a bare domain lists by URL, not time, and `snapshots()` throws for one.
   */
  order?: CaptureOrder;
  cache?: boolean;
  ttl?: number;
  concurrency?: number;
  batchSize?: number;
  timeout?: number;
  retries?: number;
  apiKey?: string;
}
export interface ArchiveMetadata {
  [key: string]: unknown;
  timestamp?: string;
  status?: number;
}
export interface WaybackMetadata extends ArchiveMetadata {
  timestamp: string;
  status: number;
  /** Base32 SHA-1 of the archived body, the value `filter: "digest:…"` matches. */
  digest?: string;
  mime?: string;
  /** Size of the stored WARC or ARC record, compressed, in bytes. */
  length?: string;
  provider: string;
}
export interface ArquivoMetadata extends ArchiveMetadata {
  timestamp: string;
  status: number;
  mime?: string;
  digest?: string;
  length?: string;
  provider: "arquivo";
}
export interface WebarchivMetadata extends ArchiveMetadata {
  timestamp: string;
  status?: number;
  mime?: string;
  digest?: string;
  length?: string;
  provider: "webarchiv";
}
export interface VefsafnMetadata extends ArchiveMetadata {
  timestamp: string;
  status?: number;
  mime?: string;
  digest?: string;
  provider: "vefsafn";
}
export interface OszkMetadata extends ArchiveMetadata {
  timestamp: string;
  status?: number;
  mime?: string;
  digest?: string;
  length?: string;
  provider: "oszk";
}
export interface NlnzMetadata extends ArchiveMetadata {
  timestamp: string;
  status?: number;
  mime?: string;
  digest?: string;
  provider: "nlnz";
}
export interface CommonCrawlMetadata extends ArchiveMetadata {
  timestamp: string;
  status: number;
  digest?: string;
  mime?: string;
  length?: string;
  collection: string;
  provider: string;
}
export interface PermaccMetadata extends Omit<ArchiveMetadata, "status"> {
  guid: string;
  title?: string;
  status?: string;
  created_by?: string;
}
export interface ArchiveTodayMetadata extends ArchiveMetadata {
  hash: string;
  raw_date?: string;
  position?: number;
}
export interface MementoMetadata extends ArchiveMetadata {
  provider: "memento";
  archive: string;
  datetime: string;
}
export interface WebCiteMetadata extends ArchiveMetadata {
  requestId: string;
  position?: number;
}
export interface ArchivedPage {
  url: string;
  timestamp: string;
  snapshot: string;
  _meta: ArchivedPageMetadata;
}
export interface ArchivedPageMetadata {
  timestamp?: string;
  status?: number | string;
  provider?: string;
  source?: string;
  /** `pinned`: read without the index. `after`: the capture postdates the time asked for. */
  selection?: "pinned" | "after";
  [key: string]: unknown;
}
export interface UnsupportedProviderRecord {
  provider: string;
  reason: string;
}
export interface ArchiveContentOptions extends ArchiveOptions {
  /**
   * Capture to read, as archive digits or an ISO 8601 date. Omitted, the newest.
   * Nothing that old? The closest later capture comes back with `_meta.selection: "after"`.
   */
  timestamp?: string;
  maxBytes?: number;
  /** Also return the bytes read as `body`. Such a read skips the cache. */
  body?: boolean;
}
/** One capture and its body as text. `body: true` adds the bytes the text was decoded from. */
export interface ArchivedContent {
  url: string;
  timestamp: string;
  snapshot: string;
  content: string;
  mime?: string;
  bytes: number;
  /** Hex SHA-256 of those bytes, taken before charset decoding. */
  sha256?: string;
  truncated: boolean;
  /** Those bytes themselves, present only when the read asked for `body`. */
  body?: Uint8Array;
  _meta: ArchivedPageMetadata;
}
export interface ArchiveContentResponse {
  success: boolean;
  content?: ArchivedContent;
  error?: string;
  unsupported?: boolean;
  unsupportedReason?: string;
  _meta?: ResponseMetadata;
  fromCache?: boolean;
}
/** Rendering applied before two archived bodies are compared. */
export type ArchiveDiffFormat = "text" | "raw";
/** Bounds and rendering controls for {@link diffArchivedContent}. */
export interface ArchiveDiffOptions {
  /** Compare visible text by default, or decoded markup/source verbatim. */
  format?: ArchiveDiffFormat;
  /** Unchanged lines kept around each hunk. Defaults to 3. */
  context?: number;
  /** Elapsed time budget for the line diff algorithm. Defaults to 1000 ms. */
  timeout?: number;
  /** Maximum line edit distance considered before aborting. Defaults to 10 000. */
  maxEditLength?: number;
}
/** Capture identity retained beside a derived diff without copying its body. */
export interface ArchivedContentSummary {
  url: string;
  timestamp: string;
  snapshot: string;
  mime?: string;
  bytes: number;
  truncated: boolean;
  provider: string;
  /** Underlying archive host when the provider is an aggregator such as Memento. */
  archive?: string;
  /** The capture's own `_meta.selection`, so a diff can't hide a late `before`. */
  selection?: ArchivedPageMetadata["selection"];
}
/** A bounded line diff between two archived captures that preserves provenance. */
export interface ArchivedContentDiff {
  before: ArchivedContentSummary;
  after: ArchivedContentSummary;
  patch: string;
  additions: number;
  deletions: number;
  identical: boolean;
  /** True when either archived body was truncated before comparison. */
  partial: boolean;
  format: ArchiveDiffFormat;
  context: number;
}
export interface ResponseMetadata {
  source: string;
  provider: string;
  errorDetails?: unknown;
  errorName?: string;
  queryParams?: Record<string, string>;
  unsupportedProviders?: UnsupportedProviderRecord[];
  [key: string]: unknown;
}
export interface ArchiveResponse {
  success: boolean;
  pages: ArchivedPage[];
  error?: string;
  unsupported?: boolean;
  unsupportedReason?: string;
  _meta?: ResponseMetadata;
  fromCache?: boolean;
}
export interface ArchiveProvider {
  name: string;
  slug?: string;
  /**
   * Initialization options the provider was created with. The aggregator reads
   * the listing window from them, because a provider without a window-aware
   * index has no way to apply its own init-level bounds.
   */
  readonly options?: ArchiveOptions;
  cacheKey?: (options?: ArchiveOptions) => string | undefined;
  snapshots: (domain: string, options?: ArchiveOptions) => Promise<ArchiveResponse>;
  /**
   * Read the body of one archived capture.
   *
   * Optional: a provider that serves captures only through its own UI has no
   * such endpoint, and an aggregator reports a missing method the same way it
   * reports an explicit unsupported response.
   */
  content?: (url: string, options?: ArchiveContentOptions) => Promise<ArchiveContentResponse>;
}
/** A provider instance or the lazy provider promise accepted by an archive. */
export type ProviderReference = ArchiveProvider | Promise<ArchiveProvider>;
/**
 * Interface for Archive instances.
 * Defines the public API that all archive implementations must provide.
 */
export interface ArchiveInterface {
  readonly options?: ArchiveOptions;
  snapshots(domain: string, options?: ArchiveOptions): Promise<ArchiveResponse>;
  getPages(domain: string, options?: ArchiveOptions): Promise<ArchivedPage[]>;
  content(url: string, options?: ArchiveContentOptions): Promise<ArchiveContentResponse>;
  getContent(url: string, options?: ArchiveContentOptions): Promise<ArchivedContent>;
  use(provider: ProviderReference): Promise<ArchiveInterface>;
  useAll(providers: readonly ProviderReference[]): Promise<ArchiveInterface>;
}