@fkn/lib 0.9.23 → 0.9.25

package/api-CesI0aMl.d.ts

@@ -0,0 +1,677 @@
+import { o as TcpSocketOption, v as UdpSocketOption } from "./wire-Gbo-D74t.js";
+import { A as ProxyFetchInit, C as PackageQuery, D as PickOptions, K as WriteData, O as Placement, P as Resolvers, S as OverlayState, T as PackagesErrorCode, U as UdpDatagram, V as TcpSocketOptions, W as UdpSocketOptions, _ as InstallOptions, a as ConflictChoice, c as ConnectAvailability, i as AdoptState, j as ProxyFetchInput, l as ConnectOptions, m as FrameConsentRequest, o as ConflictRequest, r as AdoptRequest, y as IpFamily, z as TcpSocketListenerOptions } from "./contract-D6ksmIm6.js";
+import { Remote } from "osra";
+//#region src/api-epochs.d.ts
+type EpochListener<T> = (remote: T, epoch: number) => void;
+//#endregion
+//#region src/api.d.ts
+declare const hasTransport: boolean;
+type Api = Remote<Resolvers>;
+/**
+ * The broker api. Settles when the first connection exists, exactly as before, but resolves with a
+ * stable facade that always routes to the NEWEST connection, so holding the resolved value across a
+ * broker replacement is safe. A call in flight at the moment of replacement rejects with a named
+ * error instead of hanging.
+ */
+declare const apiPromise: Promise<Api>;
+/**
+ * `apiPromise` bounded by a deadline, for call sites that must not park forever.
+ *
+ * `apiPromise` NEVER REJECTS: `epochs.first` settles only when a broker connection exists, so a
+ * broker frame that never bridges leaves it pending for the life of the realm. Awaiting it directly
+ * is correct wherever hanging is the honest answer, and wrong wherever the caller owns a socket, a
+ * timer or a UI that has to say something.
+ *
+ * That distinction is not academic. In a WORKER realm the osra transport is `{receive: self,
+ * emit: self}`, which is inert until the page bridges it, so an unbridged worker parks every socket
+ * call here with no `listening`, no `error` and no rejection. The engine then reports a listener
+ * that neither succeeded nor failed, its reopen counters stay at 0 because reopen only runs from an
+ * `error` or `close` that never arrives, and the relay is never contacted at all. That state cost a
+ * long diagnosis: it presents as a transport fault and is invisible from every counter.
+ *
+ * The latch mirrors `storage.ts`: once the broker has missed one deadline, later calls stop paying
+ * the full wait. `net.ts` needs it especially, because its listen path is `bind('::').catch(() =>
+ * bind('0.0.0.0'))`, so an unbounded-then-rejecting version would charge the deadline twice.
+ */
+declare const API_DEADLINE_MS = 8000;
+declare class BrokerUnreachableError extends Error {
+  constructor(what: string, ms: number);
+}
+declare const apiWithin: (what: string) => Promise<Api>;
+/**
+ * Runs for the current broker connection on subscribe (if one exists) and for every later one.
+ * This is the seam every registration that crosses the connection must ride, because callbacks and
+ * subscriptions die with the connection they were sent on.
+ */
+declare const onApiEpoch: (listener: EpochListener<{
+  cloud: {
+    fetch: (input: ProxyFetchInput, init: ProxyFetchInit) => Promise<Response>;
+    quota: () => Promise<{
+      overQuota: boolean;
+      remaining: number;
+      usedBytes: number;
+      limitBytes: number;
+      premium: boolean;
+      bytesPerSecond: number;
+    }>;
+    dns: {
+      lookup: (hostname: string, options?: {
+        all?: boolean | undefined;
+        family?: 0 | 4 | 6;
+      } | undefined) => Promise<{
+        address: string;
+        family: 0 | 4 | 6;
+      }[] | {
+        address: string;
+        family: 0 | 4 | 6;
+      } | undefined>;
+    };
+    fs: {
+      available: () => Promise<boolean>;
+      availability: () => Promise<ConnectAvailability>;
+      list: () => Promise<{
+        path: string;
+        size: number;
+        contentType: string | null;
+        updatedAt: string;
+        encryption: string | null;
+      }[]>;
+      quota: () => Promise<{
+        usedBytes: number;
+        limitBytes: number;
+        remaining: number;
+        objects: number;
+        maxObjects: number;
+      }>;
+      readFile: (path: string) => Promise<Uint8Array<ArrayBufferLike>>;
+      writeFile: (path: string, data: WriteData, contentType: string | null) => Promise<void>;
+      remove: (path: string) => Promise<void>;
+      encryption: () => Promise<{
+        unlocked: boolean;
+        enrolled: boolean;
+        keyEpoch: number | null;
+      }>;
+      unlock: () => Promise<boolean>;
+      promptAdopt: (request: AdoptRequest) => Promise<boolean>;
+      promptConflict: (request: ConflictRequest) => Promise<ConflictChoice>;
+      setAdoptSource: (next: AdoptState | null, run: (() => Promise<void>) | null) => Promise<void>;
+    };
+    webvpn: {
+      tcpSocket: (options: TcpSocketOptions) => Promise<{
+        localAddress: string;
+        localFamily: IpFamily;
+        localPort: number;
+        remoteAddress: string;
+        remoteFamily: IpFamily;
+        remotePort: number;
+        dataReadableStream: ReadableStream<Uint8Array>;
+        dataWritableStream: WritableStream<Uint8Array>;
+        end: () => Promise<void>;
+        destroy: () => Promise<void>;
+        destroySoon: () => Promise<void>;
+        resetAndDestroy: () => Promise<void>;
+        setOption: (option: TcpSocketOption) => Promise<void>;
+      }>;
+      tcpSocketListener: (options: TcpSocketListenerOptions) => Promise<{
+        localAddress: string;
+        localFamily: IpFamily;
+        localPort: number;
+        close: () => Promise<void>;
+      }>;
+      udpSocket: (options: UdpSocketOptions) => Promise<{
+        socketId: number;
+        dataPort: MessagePort | undefined;
+        dataPortAcks: true | undefined;
+        closed: Promise<{
+          reason: string;
+        }>;
+        localAddress: string;
+        localFamily: IpFamily;
+        localPort: number;
+        dataReadableStream: ReadableStream<UdpDatagram>;
+        connect: (options: {
+          remoteAddress: string;
+          remotePort: number;
+        }) => Promise<{
+          local: boolean;
+          address: string;
+          family: IpFamily;
+          port: number;
+        }>;
+        disconnect: () => Promise<void>;
+        send: (options: {
+          message: ArrayBuffer;
+          address?: string;
+          port?: number;
+        }) => Promise<void>;
+        close: () => Promise<void>;
+        setOption: (option: UdpSocketOption) => Promise<void>;
+      }>;
+    };
+  };
+  overlay: {
+    setHost: (push: (state: OverlayState) => unknown, options?: {
+      exactClips?: boolean;
+    } | undefined) => Promise<void>;
+  };
+  installPrompt: {
+    show: (reason?: string | undefined) => Promise<void>;
+    hide: () => Promise<void>;
+  };
+  frameConsent: {
+    ensure: (request: FrameConsentRequest) => Promise<boolean>;
+  };
+  connect: {
+    prompt: (consumerOrigin: string) => Promise<boolean>;
+  };
+  relay: {
+    prompt: () => Promise<string>;
+  };
+  packages: {
+    search: (query: PackageQuery) => Promise<{
+      error: PackagesErrorCode;
+      message: string;
+    } | {
+      results: {
+        uri: string;
+        origin: 'npm';
+        name: string;
+        version: string;
+        description: string;
+        keywords: string[];
+        publisher: string | null;
+        downloadsMonthly: number | null;
+        links: {
+          npm?: string;
+          homepage?: string;
+          repository?: string;
+        };
+        installed: boolean;
+      }[];
+    }>;
+    pick: (query: PackageQuery, options?: PickOptions | undefined) => Promise<{
+      error: PackagesErrorCode;
+      message: string;
+    } | {
+      results: {
+        uri: string;
+        origin: 'npm';
+        name: string;
+        version: string;
+        description: string;
+        keywords: string[];
+        publisher: string | null;
+        downloadsMonthly: number | null;
+        links: {
+          npm?: string;
+          homepage?: string;
+          repository?: string;
+        };
+        installed: boolean;
+      }[];
+      failed: string[];
+    } | {
+      declined: true;
+    }>;
+    install: (uri: string, options?: InstallOptions | undefined) => Promise<{
+      error: PackagesErrorCode;
+      message: string;
+    } | {
+      installed: {
+        uri: string;
+        name: string;
+        version: string | null;
+        installedAt: number;
+      };
+    } | {
+      declined: true;
+    }>;
+    frame: (uri: string) => Promise<{
+      error: PackagesErrorCode;
+      message: string;
+    } | {
+      url: string;
+      origin: string;
+      uri: string;
+      name: string;
+      version: string | null;
+      from: string;
+    }>;
+    list: () => Promise<{
+      results: {
+        uri: string;
+        name: string;
+        version: string | null;
+        installedAt: number;
+      }[];
+    }>;
+    uninstall: (uri: string) => Promise<{
+      error: PackagesErrorCode;
+      message: string;
+    } | {
+      ok: true;
+    }>;
+    connect: (uri: string, options?: ConnectOptions | undefined) => Promise<{
+      error: PackagesErrorCode;
+      message: string;
+    } | {
+      port: MessagePort;
+      closed: Promise<void>;
+    }>;
+    show: (uri: string, placement: Placement) => Promise<{
+      error: PackagesErrorCode;
+      message: string;
+    } | {
+      ok: true;
+    }>;
+    hide: (uri: string) => Promise<{
+      error: PackagesErrorCode;
+      message: string;
+    } | {
+      ok: true;
+    }>;
+  };
+  account: {
+    info: () => Promise<{
+      name: string;
+      image: string | null;
+      premium: boolean;
+      premiumUntil: string | null;
+    } | null>;
+    login: (consumerOrigin: string) => Promise<boolean>;
+    logout: () => Promise<void>;
+    onChange: (listener: () => void) => Promise<() => Promise<void>>;
+  };
+  shell: {
+    updateReady: () => Promise<boolean>;
+    onUpdate: (callback: () => void) => Promise<() => Promise<void>>;
+    onUpdateTaken: (callback: () => void) => Promise<() => Promise<void>>;
+    applyUpdate: () => Promise<boolean>;
+  };
+  proxyFetch: (input: ProxyFetchInput, init: ProxyFetchInit) => Promise<Response>;
+  webVpnTcpSocket: (options: TcpSocketOptions) => Promise<{
+    localAddress: string;
+    localFamily: IpFamily;
+    localPort: number;
+    remoteAddress: string;
+    remoteFamily: IpFamily;
+    remotePort: number;
+    dataReadableStream: ReadableStream<Uint8Array>;
+    dataWritableStream: WritableStream<Uint8Array>;
+    end: () => Promise<void>;
+    destroy: () => Promise<void>;
+    destroySoon: () => Promise<void>;
+    resetAndDestroy: () => Promise<void>;
+    setOption: (option: TcpSocketOption) => Promise<void>;
+  }>;
+  webVpnTcpSocketListener: (options: TcpSocketListenerOptions) => Promise<{
+    localAddress: string;
+    localFamily: IpFamily;
+    localPort: number;
+    close: () => Promise<void>;
+  }>;
+  webVpnUdpSocket: (options: UdpSocketOptions) => Promise<{
+    socketId: number;
+    dataPort: MessagePort | undefined;
+    dataPortAcks: true | undefined;
+    closed: Promise<{
+      reason: string;
+    }>;
+    localAddress: string;
+    localFamily: IpFamily;
+    localPort: number;
+    dataReadableStream: ReadableStream<UdpDatagram>;
+    connect: (options: {
+      remoteAddress: string;
+      remotePort: number;
+    }) => Promise<{
+      local: boolean;
+      address: string;
+      family: IpFamily;
+      port: number;
+    }>;
+    disconnect: () => Promise<void>;
+    send: (options: {
+      message: ArrayBuffer;
+      address?: string;
+      port?: number;
+    }) => Promise<void>;
+    close: () => Promise<void>;
+    setOption: (option: UdpSocketOption) => Promise<void>;
+  }>;
+  dnsLookup: (hostname: string, options?: {
+    all?: boolean | undefined;
+    family?: 0 | 4 | 6;
+  } | undefined) => Promise<{
+    address: string;
+    family: 0 | 4 | 6;
+  }[] | {
+    address: string;
+    family: 0 | 4 | 6;
+  } | undefined>;
+  setOverlayHost: (push: (state: OverlayState) => unknown, options?: {
+    exactClips?: boolean;
+  } | undefined) => Promise<void>;
+  showInstallPrompt: (reason?: string | undefined) => Promise<void>;
+  hideInstallPrompt: () => Promise<void>;
+}>) => () => void;
+declare const currentApiEpoch: () => {
+  remote: {
+    cloud: {
+      fetch: (input: ProxyFetchInput, init: ProxyFetchInit) => Promise<Response>;
+      quota: () => Promise<{
+        overQuota: boolean;
+        remaining: number;
+        usedBytes: number;
+        limitBytes: number;
+        premium: boolean;
+        bytesPerSecond: number;
+      }>;
+      dns: {
+        lookup: (hostname: string, options?: {
+          all?: boolean | undefined;
+          family?: 0 | 4 | 6;
+        } | undefined) => Promise<{
+          address: string;
+          family: 0 | 4 | 6;
+        }[] | {
+          address: string;
+          family: 0 | 4 | 6;
+        } | undefined>;
+      };
+      fs: {
+        available: () => Promise<boolean>;
+        availability: () => Promise<ConnectAvailability>;
+        list: () => Promise<{
+          path: string;
+          size: number;
+          contentType: string | null;
+          updatedAt: string;
+          encryption: string | null;
+        }[]>;
+        quota: () => Promise<{
+          usedBytes: number;
+          limitBytes: number;
+          remaining: number;
+          objects: number;
+          maxObjects: number;
+        }>;
+        readFile: (path: string) => Promise<Uint8Array<ArrayBufferLike>>;
+        writeFile: (path: string, data: WriteData, contentType: string | null) => Promise<void>;
+        remove: (path: string) => Promise<void>;
+        encryption: () => Promise<{
+          unlocked: boolean;
+          enrolled: boolean;
+          keyEpoch: number | null;
+        }>;
+        unlock: () => Promise<boolean>;
+        promptAdopt: (request: AdoptRequest) => Promise<boolean>;
+        promptConflict: (request: ConflictRequest) => Promise<ConflictChoice>;
+        setAdoptSource: (next: AdoptState | null, run: (() => Promise<void>) | null) => Promise<void>;
+      };
+      webvpn: {
+        tcpSocket: (options: TcpSocketOptions) => Promise<{
+          localAddress: string;
+          localFamily: IpFamily;
+          localPort: number;
+          remoteAddress: string;
+          remoteFamily: IpFamily;
+          remotePort: number;
+          dataReadableStream: ReadableStream<Uint8Array>;
+          dataWritableStream: WritableStream<Uint8Array>;
+          end: () => Promise<void>;
+          destroy: () => Promise<void>;
+          destroySoon: () => Promise<void>;
+          resetAndDestroy: () => Promise<void>;
+          setOption: (option: TcpSocketOption) => Promise<void>;
+        }>;
+        tcpSocketListener: (options: TcpSocketListenerOptions) => Promise<{
+          localAddress: string;
+          localFamily: IpFamily;
+          localPort: number;
+          close: () => Promise<void>;
+        }>;
+        udpSocket: (options: UdpSocketOptions) => Promise<{
+          socketId: number;
+          dataPort: MessagePort | undefined;
+          dataPortAcks: true | undefined;
+          closed: Promise<{
+            reason: string;
+          }>;
+          localAddress: string;
+          localFamily: IpFamily;
+          localPort: number;
+          dataReadableStream: ReadableStream<UdpDatagram>;
+          connect: (options: {
+            remoteAddress: string;
+            remotePort: number;
+          }) => Promise<{
+            local: boolean;
+            address: string;
+            family: IpFamily;
+            port: number;
+          }>;
+          disconnect: () => Promise<void>;
+          send: (options: {
+            message: ArrayBuffer;
+            address?: string;
+            port?: number;
+          }) => Promise<void>;
+          close: () => Promise<void>;
+          setOption: (option: UdpSocketOption) => Promise<void>;
+        }>;
+      };
+    };
+    overlay: {
+      setHost: (push: (state: OverlayState) => unknown, options?: {
+        exactClips?: boolean;
+      } | undefined) => Promise<void>;
+    };
+    installPrompt: {
+      show: (reason?: string | undefined) => Promise<void>;
+      hide: () => Promise<void>;
+    };
+    frameConsent: {
+      ensure: (request: FrameConsentRequest) => Promise<boolean>;
+    };
+    connect: {
+      prompt: (consumerOrigin: string) => Promise<boolean>;
+    };
+    relay: {
+      prompt: () => Promise<string>;
+    };
+    packages: {
+      search: (query: PackageQuery) => Promise<{
+        error: PackagesErrorCode;
+        message: string;
+      } | {
+        results: {
+          uri: string;
+          origin: 'npm';
+          name: string;
+          version: string;
+          description: string;
+          keywords: string[];
+          publisher: string | null;
+          downloadsMonthly: number | null;
+          links: {
+            npm?: string;
+            homepage?: string;
+            repository?: string;
+          };
+          installed: boolean;
+        }[];
+      }>;
+      pick: (query: PackageQuery, options?: PickOptions | undefined) => Promise<{
+        error: PackagesErrorCode;
+        message: string;
+      } | {
+        results: {
+          uri: string;
+          origin: 'npm';
+          name: string;
+          version: string;
+          description: string;
+          keywords: string[];
+          publisher: string | null;
+          downloadsMonthly: number | null;
+          links: {
+            npm?: string;
+            homepage?: string;
+            repository?: string;
+          };
+          installed: boolean;
+        }[];
+        failed: string[];
+      } | {
+        declined: true;
+      }>;
+      install: (uri: string, options?: InstallOptions | undefined) => Promise<{
+        error: PackagesErrorCode;
+        message: string;
+      } | {
+        installed: {
+          uri: string;
+          name: string;
+          version: string | null;
+          installedAt: number;
+        };
+      } | {
+        declined: true;
+      }>;
+      frame: (uri: string) => Promise<{
+        error: PackagesErrorCode;
+        message: string;
+      } | {
+        url: string;
+        origin: string;
+        uri: string;
+        name: string;
+        version: string | null;
+        from: string;
+      }>;
+      list: () => Promise<{
+        results: {
+          uri: string;
+          name: string;
+          version: string | null;
+          installedAt: number;
+        }[];
+      }>;
+      uninstall: (uri: string) => Promise<{
+        error: PackagesErrorCode;
+        message: string;
+      } | {
+        ok: true;
+      }>;
+      connect: (uri: string, options?: ConnectOptions | undefined) => Promise<{
+        error: PackagesErrorCode;
+        message: string;
+      } | {
+        port: MessagePort;
+        closed: Promise<void>;
+      }>;
+      show: (uri: string, placement: Placement) => Promise<{
+        error: PackagesErrorCode;
+        message: string;
+      } | {
+        ok: true;
+      }>;
+      hide: (uri: string) => Promise<{
+        error: PackagesErrorCode;
+        message: string;
+      } | {
+        ok: true;
+      }>;
+    };
+    account: {
+      info: () => Promise<{
+        name: string;
+        image: string | null;
+        premium: boolean;
+        premiumUntil: string | null;
+      } | null>;
+      login: (consumerOrigin: string) => Promise<boolean>;
+      logout: () => Promise<void>;
+      onChange: (listener: () => void) => Promise<() => Promise<void>>;
+    };
+    shell: {
+      updateReady: () => Promise<boolean>;
+      onUpdate: (callback: () => void) => Promise<() => Promise<void>>;
+      onUpdateTaken: (callback: () => void) => Promise<() => Promise<void>>;
+      applyUpdate: () => Promise<boolean>;
+    };
+    proxyFetch: (input: ProxyFetchInput, init: ProxyFetchInit) => Promise<Response>;
+    webVpnTcpSocket: (options: TcpSocketOptions) => Promise<{
+      localAddress: string;
+      localFamily: IpFamily;
+      localPort: number;
+      remoteAddress: string;
+      remoteFamily: IpFamily;
+      remotePort: number;
+      dataReadableStream: ReadableStream<Uint8Array>;
+      dataWritableStream: WritableStream<Uint8Array>;
+      end: () => Promise<void>;
+      destroy: () => Promise<void>;
+      destroySoon: () => Promise<void>;
+      resetAndDestroy: () => Promise<void>;
+      setOption: (option: TcpSocketOption) => Promise<void>;
+    }>;
+    webVpnTcpSocketListener: (options: TcpSocketListenerOptions) => Promise<{
+      localAddress: string;
+      localFamily: IpFamily;
+      localPort: number;
+      close: () => Promise<void>;
+    }>;
+    webVpnUdpSocket: (options: UdpSocketOptions) => Promise<{
+      socketId: number;
+      dataPort: MessagePort | undefined;
+      dataPortAcks: true | undefined;
+      closed: Promise<{
+        reason: string;
+      }>;
+      localAddress: string;
+      localFamily: IpFamily;
+      localPort: number;
+      dataReadableStream: ReadableStream<UdpDatagram>;
+      connect: (options: {
+        remoteAddress: string;
+        remotePort: number;
+      }) => Promise<{
+        local: boolean;
+        address: string;
+        family: IpFamily;
+        port: number;
+      }>;
+      disconnect: () => Promise<void>;
+      send: (options: {
+        message: ArrayBuffer;
+        address?: string;
+        port?: number;
+      }) => Promise<void>;
+      close: () => Promise<void>;
+      setOption: (option: UdpSocketOption) => Promise<void>;
+    }>;
+    dnsLookup: (hostname: string, options?: {
+      all?: boolean | undefined;
+      family?: 0 | 4 | 6;
+    } | undefined) => Promise<{
+      address: string;
+      family: 0 | 4 | 6;
+    }[] | {
+      address: string;
+      family: 0 | 4 | 6;
+    } | undefined>;
+    setOverlayHost: (push: (state: OverlayState) => unknown, options?: {
+      exactClips?: boolean;
+    } | undefined) => Promise<void>;
+    showInstallPrompt: (reason?: string | undefined) => Promise<void>;
+    hideInstallPrompt: () => Promise<void>;
+  };
+  epoch: number;
+} | undefined;
+/** Activity on the broker connection: every call flows through the facade, so these see all of it. */
+declare const apiLastCall: () => number;
+declare const apiInFlight: () => number;
+//#endregion
+export { apiPromise as a, hasTransport as c, apiLastCall as i, onApiEpoch as l, BrokerUnreachableError as n, apiWithin as o, apiInFlight as r, currentApiEpoch as s, API_DEADLINE_MS as t };