/**
 * IDOP Runtime API 1.0 — types for `globalThis.idop`.
 *
 * Specification: https://idoplabs.com/spec/idop/1.0/#11-runtime-api
 * Error codes:   https://idoplabs.com/spec/idop/1.0/errors/
 *
 * Use it from plain JavaScript with `// @ts-check` and a reference:
 *
 *   /// <reference path="./idop-runtime.d.ts" />
 *
 * or copy it into a TypeScript project. Licence: MIT OR Apache-2.0.
 */

declare namespace Idop {
  /** Every failure rejects with this: branch on `code`, never on `message`. */
  interface RuntimeError extends Error {
    readonly name: 'IdopRuntimeError';
    /** A stable code such as `IDOP-STORAGE-NOT-FOUND`. */
    readonly code: string;
  }

  interface Quota {
    readonly limitBytes: number;
    readonly usedBytes: number;
    readonly fileLimit: number;
    readonly filesUsed: number;
  }

  /** `memory`: not yet written to storage; `session`: in storage, not yet in the file; `file`: saved. */
  type SaveState = 'memory' | 'session' | 'file';

  interface WriteResult {
    readonly written: true;
    readonly saveState: SaveState;
    readonly quota: Quota;
  }

  type StorageOperation =
    | { readonly op: 'write'; readonly path: string; readonly data: string | Uint8Array | ArrayBuffer }
    | { readonly op: 'delete'; readonly path: string };

  interface Storage {
    /** UTF-8 text. `IDOP-STORAGE-NOT-FOUND` on a first run is normal. */
    read(path: string): Promise<{ readonly text: string }>;
    write(path: string, text: string): Promise<WriteResult>;
    /** Any bytes. */
    readBytes(path: string): Promise<Uint8Array>;
    writeBytes(path: string, bytes: Uint8Array | ArrayBuffer): Promise<WriteResult>;
    delete(path: string): Promise<{ readonly deleted: true; readonly saveState: SaveState }>;
    list(): Promise<{ readonly paths: readonly string[] }>;
    /** All or nothing. */
    transaction(
      operations: readonly StorageOperation[]
    ): Promise<{ readonly committed: true; readonly saveState: SaveState; readonly quota: Quota }>;
  }

  interface NetworkRequest {
    /** The `id` of a network capability declared in `idop.json` and granted by the user. */
    readonly capability: string;
    readonly url: string;
    readonly method?: string;
    readonly headers?: Readonly<Record<string, string>>;
    readonly body?: string | Uint8Array | ArrayBuffer;
    readonly responseType?: 'text' | 'bytes';
    readonly timeoutMs?: number;
  }

  interface NetworkResponse<Body> {
    /** A non-2xx status is a response, not an error. */
    readonly status: number;
    readonly headers: Readonly<Record<string, string>>;
    readonly body: Body;
  }

  interface Network {
    request(request: NetworkRequest & { readonly responseType: 'bytes' }): Promise<NetworkResponse<Uint8Array>>;
    request(request: NetworkRequest): Promise<NetworkResponse<string>>;
  }

  interface UserFile {
    readonly name: string;
    readonly type: string;
    readonly size: number;
    readonly bytes: Uint8Array;
  }

  interface UserInterface {
    /** Shows the Reader's own Save control; the decision stays with the user. */
    requestSave(): Promise<unknown>;
    /** Shows the Reader's configuration (connections, settings). */
    requestConfiguration(): Promise<{ readonly shown: true }>;
    /** Offers a file; the user saves it in the Reader's dialog. `IDOP-UI-CANCELLED` if not. */
    saveFile(file: {
      readonly name: string;
      readonly data: string | Uint8Array | ArrayBuffer;
      readonly type?: string;
    }): Promise<{ readonly saved: true; readonly size: number }>;
    /** Asks the user for one file. `accept`: extensions (".csv") or media types. */
    openFile(options?: { readonly accept?: readonly string[] }): Promise<UserFile>;
    /** Prints what the document shows now. */
    print(): Promise<{ readonly printed: true }>;
    /** Needs a click or key press. */
    requestFullscreen(): Promise<{ readonly fullscreen: true }>;
    exitFullscreen(): Promise<{ readonly fullscreen: false }>;
    /** Writes the clipboard (never reads it). Needs a click or key press. */
    copyText(text: string): Promise<{ readonly copied: true }>;
  }

  interface Host {
    /** The file a viewer document was opened to display. `IDOP-HOST-NO-INPUT` otherwise. */
    getInputFile(): Promise<{
      readonly name: string;
      readonly extension: string;
      readonly size: number;
      readonly bytes: Uint8Array;
    }>;
    /** Hands an edited copy of that file back; the user's Save decides where it goes. */
    putOutputFile(bytes: Uint8Array): Promise<{ readonly accepted: true; readonly size: number }>;
  }

  interface Runtime {
    getInfo(): Promise<{
      readonly runtimeApiVersion: string;
      /** The capability ids the user granted for this session. */
      readonly availableCapabilities: readonly string[];
    }>;
  }

  interface Api {
    readonly runtime: Runtime;
    readonly storage: Storage;
    readonly env: { get(id: string): Promise<{ readonly value: string }> };
    readonly network: Network;
    readonly ui: UserInterface;
    readonly host: Host;
  }
}

declare const idop: Idop.Api;