declare namespace VieunitePicker {
  const version: "1.0.0";
  const protocolVersion: 2;

  type ResourceType = "artwork" | "collection";
  type SelectionMode = "single" | "multiple";
  type Presentation = "modal" | "popup";
  type PickerState = "idle" | "opening" | "open" | "redeeming" | "destroyed";
  /** Opaque, server-issued key for one selectable artwork version, including resize-only derivatives. */
  type RenditionKey = string;

  interface ArtworkReferenceBase {
    provider: string;
    type: "artwork";
    id: string;
    label?: string;
    artist_name?: string | null;
    version?: number;
    updated_at?: string;
  }

  interface CanonicalArtworkReference extends ArtworkReferenceBase {
    rendition: RenditionKey;
    ratio?: never;
  }

  /** @deprecated Legacy selections may contain a ratio until they are reselected. */
  interface LegacyArtworkReference extends ArtworkReferenceBase {
    rendition?: never;
    ratio: string;
  }

  type ArtworkReference = CanonicalArtworkReference | LegacyArtworkReference;

  interface CollectionReference {
    provider: string;
    type: "collection";
    id: string;
    rendition?: never;
    ratio?: never;
    label?: string;
    version?: number;
    updated_at?: string;
  }

  type SelectedReference = ArtworkReference | CollectionReference;

  /**
   * Browser-to-CMS discovery request. Host capabilities are intentionally
   * absent: the trusted CMS backend adds them when creating the Vieunite session.
   */
  interface PickerSessionRequest {
    allowed_types: ResourceType[];
    selection_mode: SelectionMode;
    max_selection: number;
    default_filters: Record<string, unknown>;
    expires_in: number;
    callback_origin: string;
  }

  interface PickerHostCapabilities {
    credit_display: boolean;
  }

  /** CMS-backend-to-Vieunite request. Never construct this request in browser code. */
  interface PickerApiSessionCreateRequest extends PickerSessionRequest {
    host_capabilities: PickerHostCapabilities;
  }

  interface PickerSessionCreated {
    session_id: string;
    picker_url: string;
    expires_at?: string;
  }

  interface PickerRedemptionRequest {
    session_id: string;
    selection_code: string;
  }

  interface PickerSelectionRedeemed {
    session_id?: string;
    selection: SelectedReference[];
  }

  type ApiEnvelope<T> = T | { data: T };

  interface PickerConfig {
    /** CMS same-origin BFF endpoint. Never point this at a token-authenticated API from the browser. */
    sessionEndpoint?: string;
    /** CMS same-origin BFF endpoint. The BFF redeems with the persistent tenant token server-side. */
    redeemEndpoint?: string;
    createSession?: (request: Readonly<PickerSessionRequest>) => Promise<ApiEnvelope<PickerSessionCreated>>;
    redeemSelection?: (request: Readonly<PickerRedemptionRequest>) => Promise<ApiEnvelope<PickerSelectionRedeemed>>;
    /** Exact trusted origin for picker_url. Defaults to the SDK script origin. */
    pickerOrigin?: string;
    presentation?: Presentation;
    credentials?: RequestCredentials;
    headers?: Record<string, string>;
    fetch?: typeof fetch;
    popup?: { width?: number; height?: number };
  }

  interface OpenOptions {
    allowedTypes?: ResourceType[];
    selectionMode?: SelectionMode;
    /** 0 means unlimited for multiple mode; the server still applies its hard completion limit. */
    maxSelection?: number;
    /** Initial discovery filters only. These are not authorization or selection constraints. */
    initialFilters?: Record<string, unknown>;
    expiresIn?: number;
    signal?: AbortSignal;
  }

  interface SelectedResult {
    status: "selected";
    protocolVersion: 2;
    sessionId: string;
    selection: SelectedReference[];
  }

  interface CancelledResult {
    status: "cancelled";
    reason: "user_closed" | "programmatic" | "aborted";
    sessionId: string | null;
    selection: readonly [];
  }

  type PickerResult = SelectedResult | CancelledResult;

  interface PickerEvent {
    type: string;
    state?: PickerState;
    sessionId?: string | null;
    error?: PickerError;
  }

  class PickerError extends Error {
    readonly code: string;
    readonly cause?: unknown;
  }

  interface PickerClient {
    readonly state: PickerState;
    readonly isOpen: boolean;
    open(options?: OpenOptions): Promise<PickerResult>;
    focus(): boolean;
    close(): boolean;
    cancel(): boolean;
    destroy(): void;
    on(event: "statechange" | "complete" | "cancel" | "error", handler: (event: PickerEvent) => void): () => void;
    off(event: string, handler: (event: PickerEvent) => void): void;
  }

  function create(options: PickerConfig): PickerClient;
}

export as namespace VieunitePicker;
export = VieunitePicker;