@athenaintel/react 0.28.1 → 0.32.0

package/dist/collab/client.d.ts

@@ -8,6 +8,15 @@
  * else → provider backoff), and expose presence from awareness. React apps
  * use `useGenericDoc` from `@athenaintel/react/collab` instead of calling
  * this directly.
+ *
+ * A host that keeps a local copy of the document (`localCopy`) gets it applied
+ * before the first connection, keeps its unacknowledged edits waiting across
+ * sessions, and can hold a connection that would send edits made without one
+ * until it has checked them against the server (`beforeConnect`). Offline, a
+ * mint that fails for want of the network is retried (`retryMintError`)
+ * instead of ending the handle, and past `offlineGateAfterMs` without a socket
+ * the handle reconnects itself, re-minting each time, so every reconnect after
+ * a real outage re-checks access and passes the host's gate.
  */
 import * as Y from '@y/y';
 import { type CollabAuth, type CollabTokenResponse, CollabTokenError } from './mint';
@@ -27,10 +36,30 @@ export interface GenericDocHandle {
      * this (or `waitForSync`).
      */
     readonly synced: boolean;
+    /**
+     * Whether every change made to this document has reached the server: `false` from a local edit
+     * until the server sends it back (`@y/websocket`'s `syncStatus.localUpdatesSynced`; yhub echoes
+     * every update to its sender). Kept across reconnects and re-mints: a replaced provider hands its
+     * unconfirmed edits to the next, and an edit made between providers waits for one. A host that
+     * closes the document while this is `false` loses those edits, unless a local copy keeps them.
+     */
+    readonly localChangesSynced: boolean;
     /** Granted access from the last successful mint. */
     readonly accessType: 'r' | 'rw' | null;
     /** Terminal error, when status is 'error' or 'closed'. */
     readonly error: Error | null;
+    /**
+     * Whether the document holds what the host's local copy stored (always `true` without one).
+     * Mount readers after it: until then the document is still empty.
+     */
+    readonly prepared: boolean;
+    /** Whether this host allows a live connection. Disabled documents remain editable locally. */
+    readonly connectionEnabled: boolean;
+    /**
+     * A connection the host's `beforeConnect` held: the handle waits, sending nothing, until the
+     * host calls `resume()` (or destroys the handle).
+     */
+    readonly held: boolean;
     /** Monotonic change counter — bumps on every status/presence notification. */
     readonly version: number;
     /**
@@ -38,22 +67,118 @@ export interface GenericDocHandle {
      * terminal connection state, or if the handle is destroyed first.
      */
     waitForSync: (timeoutMs?: number) => Promise<void>;
+    /**
+     * Resolve once connected, initially synced, and every local change has been acknowledged,
+     * including any edits the local-copy hook restores after sync. The host must prevent further
+     * editing while saving a checkpoint. Reject on timeout, a disabled connection, or a terminal state.
+     */
+    waitForAcknowledged: (timeoutMs?: number) => Promise<void>;
     getPresence: () => PresenceEntry[];
     /** Broadcast this client's presence state (requires a live connection). */
     setPresence: (state: Record<string, unknown> | null) => void;
     /**
      * Force an early token refresh. Session-preserving: the live connection
      * stays up until the fresh token is minted; a failed mint retries on a
-     * short timer instead of dropping the session.
+     * short timer instead of dropping the session. Without a connection it
+     * reconnects now.
      */
     refreshNow: () => Promise<void>;
+    /**
+     * Disable all connections without losing the document or its pending edits. Enabling mints a
+     * fresh grant and runs the host's beforeConnect gate; it never bypasses a permission or review.
+     */
+    setConnectionEnabled: (enabled: boolean) => void;
+    /** Connect past a hold, without asking `beforeConnect` again. */
+    resume: () => void;
+    /** Local edits the server has not echoed yet (handed between providers too), or `null`. */
+    unconfirmedEdits: () => Y.ContentIds | null;
     onChange: (listener: () => void) => () => void;
     destroy: () => void;
 }
+/**
+ * Issues a room-bound Keryx token for one asset. The default calls the public
+ * `/collab-token` route with the handle's `auth`; a host with its own trusted
+ * mint (a desktop app's main process holding the user's key) passes one
+ * instead, and the handle uses it for the first mint and every re-mint.
+ */
+export type CollabMint = (params: {
+    assetId: string;
+    access: 'view' | 'edit';
+}) => Promise<CollabTokenResponse>;
+/** What a host's local copy reads of the handle's transport. */
+export interface GenericDocTransportView {
+    /** True for a transaction the transport applied (the server's state, a peer's edit). */
+    isRemoteOrigin: (origin: unknown) => boolean;
+    /** Local edits the server has not echoed yet, or `null`. */
+    getUnconfirmed: () => Y.ContentIds | null;
+    /** Connected, past the initial sync, and nothing unconfirmed. */
+    isFullySynced: () => boolean;
+}
+/** What `beforeConnect` is asked about. */
+export interface GenericDocConnectGate {
+    /** The grant the connection would use (its access is the server's current verdict). */
+    grant: CollabTokenResponse;
+    /** The handle has not connected yet. */
+    firstConnection: boolean;
+    /** How long the handle had been without a connection, when it had one before. */
+    offlineForMs: number | null;
+    /** Local edits made without a connection (or inherited from an earlier session) wait to be sent. */
+    hasUnsyncedEdits: boolean;
+}
+/** A host's local copy of the document (`@athenaintel/local-copy` behind a host's glue). */
+export interface GenericDocLocalCopy {
+    /**
+     * Called once, before the first mint: apply the stored copy to `doc` and return the local edits
+     * it holds that the server never acknowledged. The handle sends them and waits for their echo
+     * like its own. A failure here must resolve `{ unsyncedEdits: null }`: the handle then runs
+     * without a copy.
+     */
+    prepare: (params: {
+        doc: Y.Doc;
+        transport: GenericDocTransportView;
+    }) => Promise<{
+        unsyncedEdits: Y.ContentIds | null;
+    }>;
+    /** The handle's unconfirmed edits or sync state changed. */
+    transportChanged: () => void;
+    /**
+     * An explicit host pause/resume policy changed. Invalidate decisions that must be checked afresh
+     * before a later manual save. A pause runs after its provider is destroyed and its status is
+     * disconnected, so edits restored by the hook stay local. A resume runs before minting.
+     * Network retries and an immediate conflict `resume()` do not call it.
+     */
+    connectionPolicyChanged?: (enabled: boolean) => void;
+    /**
+     * Asked after each mint and before the connection it would open: the first connection, a
+     * reconnect after an outage longer than `offlineGateAfterMs`, and a re-mint after a revocation
+     * (never a scheduled token refresh of a live connection, never past `resume()`). The host
+     * checks what it must before anything is sent (the document still opens here; access; edits
+     * made without a connection against the server's). `'hold'` keeps the handle from connecting
+     * until `resume()`; a throw counts as "not yet" and is asked again on the next attempt.
+     */
+    beforeConnect?: (gate: GenericDocConnectGate) => Promise<'connect' | 'hold'>;
+}
+/** After this long without a socket, the handle reconnects itself (re-mint, gate) instead of the provider. */
+export declare const DEFAULT_OFFLINE_GATE_AFTER_MS = 15000;
+/**
+ * The default `retryMintError`: a network failure, a timeout, a rate limit or a server error is
+ * worth retrying; a refusal (401/403/404) is the server's verdict and ends the handle.
+ */
+export declare function isRetryableMintError(error: unknown): boolean;
 export declare function connectGenericDoc(args: {
     assetId: string;
-    auth: CollabAuth;
+    /** Credentials for the default mint; not used when `mint` is given. */
+    auth?: CollabAuth;
     access?: 'view' | 'edit';
+    mint?: CollabMint;
+    /** A local copy of the document the host keeps (see {@link GenericDocLocalCopy}). */
+    localCopy?: GenericDocLocalCopy;
+    /** Whether a failed mint is worth retrying; defaults to {@link isRetryableMintError}. */
+    retryMintError?: (error: unknown) => boolean;
+    /** See {@link DEFAULT_OFFLINE_GATE_AFTER_MS}. */
+    offlineGateAfterMs?: number;
+    /** Start without connecting or minting (for a host's manual-save mode). Defaults to true. */
+    connectionEnabled?: boolean;
 }): GenericDocHandle;
 export { CollabTokenError };
 export type { CollabAuth, CollabTokenResponse };

package/dist/collab/client.js

@@ -1,31 +1,99 @@
 import { WebsocketProvider } from "@y/websocket";
 import * as Y from "@y/y";
 import { classifyClose } from "./close-policy.js";
-import { mintCollabToken } from "./mint.js";
-import { CollabTokenError } from "./mint.js";
-import { MIN_REFRESH_DELAY_MS, MAX_CONSECUTIVE_REMINTS, refreshDelayMs } from "./token-refresh.js";
+import { CollabTokenError, mintCollabToken } from "./mint.js";
+import { MAX_CONSECUTIVE_REMINTS, refreshDelayMs, MIN_REFRESH_DELAY_MS } from "./token-refresh.js";
+const DEFAULT_OFFLINE_GATE_AFTER_MS = 15e3;
+const MINT_RETRY_DELAYS_MS = [1e3, 2e3, 4e3, 8e3, 15e3, 3e4, 6e4];
+function isRetryableMintError(error) {
+  if (error instanceof CollabTokenError) {
+    return error.status >= 500 || error.status === 408 || error.status === 429;
+  }
+  return error instanceof TypeError || error instanceof DOMException && error.name === "TimeoutError";
+}
+function resolveMint({ auth, mint }) {
+  if (mint) return mint;
+  if (!auth) throw new Error("connectGenericDoc needs `auth` or `mint`");
+  return ({ assetId, access }) => mintCollabToken({ auth, assetId, access });
+}
 function connectGenericDoc(args) {
   const access = args.access ?? "view";
+  const mint = resolveMint({ auth: args.auth, mint: args.mint });
+  const localCopy = args.localCopy;
+  const retryMintError = args.retryMintError ?? isRetryableMintError;
+  const offlineGateAfterMs = args.offlineGateAfterMs ?? DEFAULT_OFFLINE_GATE_AFTER_MS;
   const doc = new Y.Doc();
   const listeners = /* @__PURE__ */ new Set();
   let provider = null;
   let refreshTimer = null;
+  let retryTimer = null;
+  let offlineTimer = null;
+  let openingPastThreshold = null;
+  let mintRetries = 0;
   let destroyed = false;
-  let status = "connecting";
+  let connectionEnabled = args.connectionEnabled ?? true;
+  let status = connectionEnabled ? "connecting" : "disconnected";
   let synced = false;
   let accessType = null;
   let error = null;
   let lastPresence = null;
   let version = 0;
   let consecutiveRemints = 0;
+  let prepared = localCopy === void 0;
+  let held = false;
+  let heldGrant = null;
+  let everConnected = false;
+  let disconnectedSince = null;
+  let connectSeq = 0;
+  let carriedUpdates = [];
+  let localChangesSynced = true;
   const notify = () => {
     version += 1;
     for (const listener of listeners) listener();
   };
+  const unconfirmedEdits = () => {
+    const all = [...carriedUpdates, ...(provider == null ? void 0 : provider.unconfirmedUpdates) ?? []].map(
+      (entry) => entry.ids
+    );
+    if (all.length === 0) return null;
+    return all.length === 1 ? all[0] : Y.mergeContentIds(all);
+  };
+  const transport = {
+    isRemoteOrigin: (origin) => origin instanceof WebsocketProvider,
+    getUnconfirmed: unconfirmedEdits,
+    isFullySynced: () => status === "connected" && synced && localChangesSynced
+  };
+  const transportChanged = () => {
+    localCopy == null ? void 0 : localCopy.transportChanged();
+  };
+  const refreshLocalChangesSynced = () => {
+    const next = carriedUpdates.length === 0 && ((provider == null ? void 0 : provider.unconfirmedUpdates.length) ?? 0) === 0;
+    const changed = next !== localChangesSynced;
+    localChangesSynced = next;
+    transportChanged();
+    if (changed) notify();
+  };
+  doc.on("update", (update, origin) => {
+    if (!prepared || provider !== null || destroyed || origin instanceof WebsocketProvider) return;
+    carriedUpdates = [
+      ...carriedUpdates,
+      { created: Date.now(), ids: Y.createContentIdsFromUpdate(update) }
+    ];
+    refreshLocalChangesSynced();
+  });
   const setStatus = (next, err = null) => {
     if (destroyed && next !== "closed") return;
+    const wasConnected = status === "connected";
     status = next;
     error = err;
+    if (next === "connected") {
+      everConnected = true;
+      disconnectedSince = null;
+      clearOfflineTimer();
+    } else if (wasConnected || everConnected && disconnectedSince === null) {
+      disconnectedSince = Date.now();
+    }
+    transportChanged();
     notify();
   };
   const clearRefreshTimer = () => {
@@ -34,6 +102,18 @@ function connectGenericDoc(args) {
       refreshTimer = null;
     }
   };
+  const clearRetryTimer = () => {
+    if (retryTimer !== null) {
+      clearTimeout(retryTimer);
+      retryTimer = null;
+    }
+  };
+  function clearOfflineTimer() {
+    if (offlineTimer !== null) {
+      clearTimeout(offlineTimer);
+      offlineTimer = null;
+    }
+  }
   const teardownProvider = () => {
     clearRefreshTimer();
     if (synced) {
@@ -41,8 +121,10 @@ function connectGenericDoc(args) {
       notify();
     }
     if (provider) {
-      provider.destroy();
+      const previous = provider;
       provider = null;
+      carriedUpdates = [...carriedUpdates, ...previous.unconfirmedUpdates];
+      previous.destroy();
     }
   };
   const scheduleRefresh = (grant) => {
@@ -52,32 +134,107 @@ function connectGenericDoc(args) {
       void connect({ scheduledRefresh: true });
     }, delay);
   };
+  const scheduleRetry = () => {
+    clearRetryTimer();
+    const delay = MINT_RETRY_DELAYS_MS[Math.min(mintRetries, MINT_RETRY_DELAYS_MS.length - 1)];
+    mintRetries += 1;
+    retryTimer = setTimeout(() => {
+      retryTimer = null;
+      void connect();
+    }, delay);
+  };
+  const onBrowserOnline = () => {
+    if (destroyed || !connectionEnabled || status === "closed" || status === "error" || provider !== null || held) return;
+    mintRetries = 0;
+    clearRetryTimer();
+    void connect();
+  };
+  if (typeof window !== "undefined") window.addEventListener("online", onBrowserOnline);
+  const armOfflineTakeover = () => {
+    if (!connectionEnabled || offlineTimer !== null || !(localCopy == null ? void 0 : localCopy.beforeConnect)) return;
+    offlineTimer = setTimeout(() => {
+      offlineTimer = null;
+      if (destroyed || !connectionEnabled || status === "connected" || provider === null) return;
+      if (provider.wsconnecting && !hasUnsyncedLocalEdits()) {
+        openingPastThreshold = provider;
+        armOfflineTakeover();
+        return;
+      }
+      teardownProvider();
+      void connect();
+    }, offlineGateAfterMs);
+  };
+  const hasUnsyncedLocalEdits = () => carriedUpdates.length > 0 || ((provider == null ? void 0 : provider.unconfirmedUpdates.length) ?? 0) > 0;
   const connect = async (opts) => {
-    if (destroyed) return;
-    const scheduledRefresh = (opts == null ? void 0 : opts.scheduledRefresh) === true;
+    if (destroyed || !connectionEnabled) return;
+    const seq = ++connectSeq;
+    await preparing;
+    if (destroyed || !connectionEnabled || seq !== connectSeq) return;
+    const scheduledRefresh = (opts == null ? void 0 : opts.scheduledRefresh) === true && status === "connected";
     if (!scheduledRefresh) {
       teardownProvider();
     } else {
       clearRefreshTimer();
     }
+    clearRetryTimer();
+    if (destroyed || !connectionEnabled || seq !== connectSeq) return;
     let grant;
-    try {
-      grant = await mintCollabToken({ auth: args.auth, assetId: args.assetId, access });
-    } catch (err) {
-      if (scheduledRefresh && !destroyed) {
-        refreshTimer = setTimeout(() => {
-          void connect({ scheduledRefresh: true });
-        }, MIN_REFRESH_DELAY_MS);
+    if ((opts == null ? void 0 : opts.grant) && opts.grant.expires_at_ms - Date.now() > MIN_REFRESH_DELAY_MS) {
+      grant = opts.grant;
+    } else {
+      try {
+        grant = await mint({ assetId: args.assetId, access });
+      } catch (err) {
+        if (destroyed || !connectionEnabled || seq !== connectSeq) return;
+        if (scheduledRefresh) {
+          refreshTimer = setTimeout(() => {
+            void connect({ scheduledRefresh: true });
+          }, MIN_REFRESH_DELAY_MS);
+          return;
+        }
+        if (retryMintError(err)) {
+          if (status !== "disconnected") setStatus("disconnected");
+          scheduleRetry();
+          return;
+        }
+        setStatus("error", err instanceof Error ? err : new Error(String(err)));
+        return;
+      }
+    }
+    if (destroyed || !connectionEnabled || seq !== connectSeq) return;
+    mintRetries = 0;
+    accessType = grant.access_type;
+    const beforeConnect = localCopy == null ? void 0 : localCopy.beforeConnect;
+    if (beforeConnect && !scheduledRefresh && !(opts == null ? void 0 : opts.skipGate)) {
+      const firstConnection = !everConnected;
+      const offlineForMs = disconnectedSince === null ? null : Date.now() - disconnectedSince;
+      let decision;
+      try {
+        decision = await beforeConnect({
+          grant,
+          firstConnection,
+          offlineForMs,
+          hasUnsyncedEdits: hasUnsyncedLocalEdits()
+        });
+      } catch {
+        if (destroyed || !connectionEnabled || seq !== connectSeq) return;
+        if (status !== "disconnected") setStatus("disconnected");
+        scheduleRetry();
+        return;
+      }
+      if (destroyed || !connectionEnabled || seq !== connectSeq) return;
+      if (decision === "hold") {
+        held = true;
+        heldGrant = grant;
+        if (status !== "disconnected") setStatus("disconnected");
+        else notify();
         return;
       }
-      setStatus("error", err instanceof Error ? err : new Error(String(err)));
-      return;
     }
-    if (destroyed) return;
     if (scheduledRefresh) {
       teardownProvider();
     }
-    accessType = grant.access_type;
+    if (destroyed || !connectionEnabled || seq !== connectSeq) return;
     const nextProvider = new WebsocketProvider(grant.ws_url, `${grant.org}/${grant.doc_id}`, doc, {
       params: {
         yauth: grant.token,
@@ -90,8 +247,20 @@ function connectGenericDoc(args) {
       disableBc: true
     });
     provider = nextProvider;
+    nextProvider.unconfirmedUpdates = [...carriedUpdates, ...nextProvider.unconfirmedUpdates];
+    carriedUpdates = [];
+    refreshLocalChangesSynced();
+    nextProvider.on("sync-status", () => {
+      if (provider !== nextProvider) return;
+      refreshLocalChangesSynced();
+    });
     nextProvider.on("status", (event) => {
       if (provider !== nextProvider) return;
+      if (event.status === "connected" && openingPastThreshold === nextProvider && hasUnsyncedLocalEdits()) {
+        teardownProvider();
+        void connect();
+        return;
+      }
       if (event.status === "connected") {
         consecutiveRemints = 0;
       }
@@ -99,11 +268,14 @@ function connectGenericDoc(args) {
       if (event.status === "connected" && lastPresence !== null) {
         nextProvider.awareness.setLocalState(lastPresence);
       }
+      if (event.status !== "connected") armOfflineTakeover();
     });
+    if (!nextProvider.wsconnected) armOfflineTakeover();
     nextProvider.on("sync", (state) => {
       if (provider !== nextProvider) return;
       if (synced !== state) {
         synced = state;
+        transportChanged();
         notify();
       }
     });
@@ -135,6 +307,15 @@ function connectGenericDoc(args) {
     });
     scheduleRefresh(grant);
   };
+  const preparing = localCopy ? localCopy.prepare({ doc, transport }).catch(() => ({ unsyncedEdits: null })).then(({ unsyncedEdits }) => {
+    if (destroyed) return;
+    if (unsyncedEdits && !(unsyncedEdits.inserts.isEmpty() && unsyncedEdits.deletes.isEmpty())) {
+      carriedUpdates = [...carriedUpdates, { created: Date.now(), ids: unsyncedEdits }];
+    }
+    prepared = true;
+    refreshLocalChangesSynced();
+    notify();
+  }) : Promise.resolve();
   void connect();
   const waitForSync = (timeoutMs = 15e3) => new Promise((resolve, reject) => {
     const terminal = () => {
@@ -175,6 +356,41 @@ function connectGenericDoc(args) {
     };
     listeners.add(listener);
   });
+  const waitForAcknowledged = (timeoutMs = 15e3) => new Promise((resolve, reject) => {
+    let finished = false;
+    let checkQueued = false;
+    let timer = null;
+    const finish = (failure) => {
+      if (finished) return;
+      finished = true;
+      if (timer !== null) clearTimeout(timer);
+      listeners.delete(check);
+      if (failure) reject(failure);
+      else resolve();
+    };
+    const check = () => {
+      if (finished || checkQueued) return;
+      checkQueued = true;
+      queueMicrotask(() => {
+        checkQueued = false;
+        if (finished) return;
+        if (destroyed) {
+          finish(new Error("Handle destroyed before local changes were acknowledged"));
+        } else if (!connectionEnabled) {
+          finish(new Error("Connection disabled before local changes were acknowledged"));
+        } else if (status === "closed" || status === "error") {
+          finish(error ?? new Error(`Connection ${status} before local changes were acknowledged`));
+        } else if (prepared && status === "connected" && synced && localChangesSynced) {
+          finish();
+        }
+      });
+    };
+    timer = setTimeout(() => {
+      finish(new Error(`Timed out after ${timeoutMs}ms waiting for local changes to be acknowledged`));
+    }, timeoutMs);
+    listeners.add(check);
+    check();
+  });
   return {
     doc,
     get status() {
@@ -183,16 +399,29 @@ function connectGenericDoc(args) {
     get synced() {
       return synced;
     },
+    get localChangesSynced() {
+      return localChangesSynced;
+    },
     get accessType() {
       return accessType;
     },
     get error() {
       return error;
     },
+    get prepared() {
+      return prepared;
+    },
+    get connectionEnabled() {
+      return connectionEnabled;
+    },
+    get held() {
+      return held;
+    },
     get version() {
       return version;
     },
     waitForSync,
+    waitForAcknowledged,
     getPresence: () => {
       if (!provider) return [];
       const entries = [];
@@ -205,7 +434,38 @@ function connectGenericDoc(args) {
       lastPresence = state;
       provider == null ? void 0 : provider.awareness.setLocalState(state);
     },
-    refreshNow: () => connect({ scheduledRefresh: true }),
+    refreshNow: () => {
+      if (!connectionEnabled || held) return Promise.resolve();
+      return provider ? connect({ scheduledRefresh: true }) : connect();
+    },
+    setConnectionEnabled: (enabled) => {
+      var _a, _b;
+      if (destroyed || enabled === connectionEnabled) return;
+      connectionEnabled = enabled;
+      if (!enabled) {
+        connectSeq += 1;
+        clearRetryTimer();
+        clearOfflineTimer();
+        teardownProvider();
+        setStatus("disconnected");
+        (_a = localCopy == null ? void 0 : localCopy.connectionPolicyChanged) == null ? void 0 : _a.call(localCopy, false);
+        return;
+      }
+      (_b = localCopy == null ? void 0 : localCopy.connectionPolicyChanged) == null ? void 0 : _b.call(localCopy, true);
+      held = false;
+      heldGrant = null;
+      setStatus("connecting");
+      void connect();
+    },
+    resume: () => {
+      if (!held || destroyed || !connectionEnabled) return;
+      held = false;
+      const grant = heldGrant;
+      heldGrant = null;
+      notify();
+      void connect({ skipGate: true, grant: grant ?? void 0 });
+    },
+    unconfirmedEdits,
     onChange: (listener) => {
       listeners.add(listener);
       return () => {
@@ -216,6 +476,9 @@ function connectGenericDoc(args) {
       if (destroyed) return;
       destroyed = true;
       teardownProvider();
+      clearRetryTimer();
+      clearOfflineTimer();
+      if (typeof window !== "undefined") window.removeEventListener("online", onBrowserOnline);
       status = "closed";
       for (const listener of [...listeners]) listener();
       listeners.clear();
@@ -225,6 +488,8 @@ function connectGenericDoc(args) {
 }
 export {
   CollabTokenError,
-  connectGenericDoc
+  DEFAULT_OFFLINE_GATE_AFTER_MS,
+  connectGenericDoc,
+  isRetryableMintError
 };
 //# sourceMappingURL=client.js.map