@helipod/client 0.1.0

package/dist/index.js

@@ -0,0 +1,642 @@
+import {
+  AUTH_REFRESH_UDF_PATH,
+  DEFAULT_DRAIN_CHUNK_SIZE,
+  DEFAULT_DRAIN_INTERVAL_MS,
+  HelipodClient,
+  MutationUndeliveredError,
+  NON_REPLAYABLE_MUTATION_DROPPED,
+  OFFLINE_IDENTITY_CHANGED,
+  OutboxDrain,
+  anyApi,
+  buildConnectMessage,
+  computeDrainBackoff,
+  createOptimisticLocalStore,
+  dropIfNonReplayable,
+  getFunctionPath,
+  outboxAckedThrough,
+  outboxHeldFromLog,
+  outboxHeldFromStore,
+  sessionFingerprintKey,
+  sha256Hex
+} from "./chunk-I7ZJFW4E.js";
+import {
+  DEFAULT_OUTBOX_MAX_QUEUE_SIZE,
+  OUTBOX_VERSION,
+  OfflineClientResetError,
+  OutboxOverflowError,
+  defaultMintClientId,
+  indexedDBOutbox,
+  memoryOutbox,
+  mintIdentity
+} from "./chunk-DW55SNHW.js";
+
+// src/transport.ts
+function loopbackTransport(connection) {
+  const closeListeners = /* @__PURE__ */ new Set();
+  let closed = false;
+  return {
+    send(message) {
+      if (!closed) void Promise.resolve(connection.send(message));
+    },
+    onMessage(listener) {
+      return connection.onMessage(listener);
+    },
+    onClose(listener) {
+      closeListeners.add(listener);
+      return () => closeListeners.delete(listener);
+    },
+    close() {
+      if (closed) return;
+      closed = true;
+      connection.close();
+      for (const l of closeListeners) l();
+    }
+  };
+}
+function reconnectDelayMs(attempt, initialBackoffMs, maxBackoffMs, rand = Math.random) {
+  const exp = Math.min(maxBackoffMs, initialBackoffMs * 2 ** attempt);
+  const half = exp / 2;
+  return half + rand() * half;
+}
+function webSocketTransport(url, opts = {}) {
+  const reconnect = opts.reconnect ?? true;
+  const initialBackoffMs = opts.initialBackoffMs ?? 300;
+  const maxBackoffMs = opts.maxBackoffMs ?? 3e4;
+  const createWebSocket = opts.createWebSocket ?? ((u) => new WebSocket(u));
+  const listeners = /* @__PURE__ */ new Set();
+  const closeListeners = /* @__PURE__ */ new Set();
+  const reopenListeners = /* @__PURE__ */ new Set();
+  const queue = [];
+  let ws;
+  let open = false;
+  let everOpened = false;
+  let hadFailedConnect = false;
+  let announced = false;
+  let terminated = false;
+  let attempt = 0;
+  let reconnectTimer;
+  const clearReconnectTimer = () => {
+    if (reconnectTimer !== void 0) {
+      clearTimeout(reconnectTimer);
+      reconnectTimer = void 0;
+    }
+  };
+  const announceClose = () => {
+    if (announced) return;
+    announced = true;
+    queue.length = 0;
+    for (const l of closeListeners) l();
+  };
+  const handleDisconnect = () => {
+    open = false;
+    if (!everOpened) hadFailedConnect = true;
+    announceClose();
+    if (terminated || !reconnect) {
+      terminated = true;
+      return;
+    }
+    const delay = reconnectDelayMs(attempt, initialBackoffMs, maxBackoffMs);
+    attempt++;
+    clearReconnectTimer();
+    reconnectTimer = setTimeout(() => {
+      reconnectTimer = void 0;
+      if (terminated) return;
+      ws = createWebSocket(url);
+      wire(ws);
+    }, delay);
+    reconnectTimer.unref?.();
+  };
+  function wire(socket) {
+    socket.addEventListener("open", () => {
+      if (terminated) return;
+      open = true;
+      announced = false;
+      attempt = 0;
+      for (const m of queue) socket.send(JSON.stringify(m));
+      queue.length = 0;
+      if (everOpened || hadFailedConnect) {
+        for (const l of reopenListeners) l();
+      }
+      hadFailedConnect = false;
+      everOpened = true;
+    });
+    socket.addEventListener("message", (ev) => {
+      if (typeof ev.data !== "string") return;
+      const msg = JSON.parse(ev.data);
+      for (const l of listeners) l(msg);
+    });
+    socket.addEventListener("close", handleDisconnect);
+    socket.addEventListener("error", handleDisconnect);
+  }
+  ws = createWebSocket(url);
+  wire(ws);
+  return {
+    send(message) {
+      if (terminated) return;
+      if (open) {
+        ws.send(JSON.stringify(message));
+        return;
+      }
+      if (everOpened && reconnect) return;
+      queue.push(message);
+    },
+    onMessage(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    onClose(listener) {
+      closeListeners.add(listener);
+      return () => closeListeners.delete(listener);
+    },
+    onReopen(listener) {
+      reopenListeners.add(listener);
+      return () => reopenListeners.delete(listener);
+    },
+    close() {
+      terminated = true;
+      clearReconnectTimer();
+      announceClose();
+      try {
+        ws.close();
+      } catch {
+      }
+    }
+  };
+}
+
+// src/headless-drain.ts
+function originTag() {
+  const loc = globalThis.location;
+  return loc?.origin ?? "app";
+}
+function probeLockManager() {
+  const nav = globalThis.navigator;
+  const locks = nav?.locks;
+  if (locks && typeof locks.request === "function") {
+    return {
+      request: (name, options, callback) => locks.request(name, options, callback)
+    };
+  }
+  return void 0;
+}
+async function isLockAvailable(locks, name) {
+  let available = false;
+  await locks.request(name, { ifAvailable: true }, async (lock) => {
+    available = lock !== null;
+  });
+  return available;
+}
+function countActive(entries) {
+  return entries.filter((e) => e.status === "unsent" || e.status === "inflight" || e.status === "parked").length;
+}
+function toOutboxEntry(entry) {
+  return {
+    clientId: entry.clientId,
+    seq: entry.seq,
+    requestId: entry.requestId,
+    udfPath: entry.udfPath,
+    args: entry.args,
+    seed: entry.seed,
+    order: entry.order,
+    status: "unsent",
+    identityFingerprint: entry.identityFingerprint,
+    outboxVersion: OUTBOX_VERSION,
+    enqueuedAt: entry.enqueuedAt ?? Date.now()
+  };
+}
+async function drainOutboxOnce(opts) {
+  const outbox = opts.outbox ?? indexedDBOutbox();
+  const deployment = opts.deployment ?? "default";
+  const lockName = `helipod:outbox:${originTag()}:${deployment}`;
+  const timeoutMs = opts.timeoutMs ?? 3e4;
+  const initial = await outbox.loadAll();
+  if (countActive(initial.entries) === 0) {
+    return { drained: 0, failed: 0, remaining: 0 };
+  }
+  const locks = opts.locks === void 0 ? probeLockManager() : opts.locks ?? void 0;
+  if (locks) {
+    const available = await isLockAvailable(locks, lockName);
+    if (!available) {
+      return { drained: 0, failed: 0, remaining: countActive(initial.entries) };
+    }
+  }
+  let transport = opts._transport;
+  try {
+    let fingerprint = "anon";
+    let authToken = null;
+    if (opts.getAuthToken) {
+      authToken = await opts.getAuthToken();
+      if (authToken) fingerprint = await sha256Hex(authToken);
+    }
+    if (opts.getSessionId) {
+      const sessionId = await opts.getSessionId();
+      if (sessionId) fingerprint = await sha256Hex(sessionFingerprintKey(sessionId));
+    }
+    transport = transport ?? webSocketTransport(opts.url, { reconnect: false });
+    if (authToken) transport.send({ type: "SetAuth", token: authToken });
+    return await runDrain(transport, opts, outbox, initial.entries, deployment, lockName, timeoutMs, fingerprint);
+  } finally {
+    transport?.close();
+  }
+}
+async function runDrain(transport, opts, outbox, initialEntries, deployment, lockName, timeoutMs, fingerprint) {
+  let drained = 0;
+  let failed = 0;
+  let armed = false;
+  let closed = false;
+  let connectSent = false;
+  let orderCounter = Date.now();
+  const log = /* @__PURE__ */ new Map();
+  let nextRequestId = 1;
+  const heldAtConnect = outboxHeldFromStore(initialEntries);
+  function addHydrated(e) {
+    if (dropIfNonReplayable(outbox, e)) return;
+    for (const existing of log.values()) {
+      if (existing.clientId === e.clientId && existing.seq === e.seq) return;
+    }
+    const status = e.status === "parked" ? { type: "parked" } : { type: "unsent" };
+    const entry = {
+      requestId: String(nextRequestId++),
+      udfPath: e.udfPath,
+      args: e.args,
+      seed: e.seed,
+      touched: /* @__PURE__ */ new Set(),
+      status,
+      clientId: e.clientId,
+      seq: e.seq,
+      order: e.order,
+      identityFingerprint: e.identityFingerprint,
+      enqueuedAt: e.enqueuedAt,
+      durable: true
+    };
+    log.set(entry.requestId, entry);
+  }
+  function drainable() {
+    return [...log.values()].filter((e) => e.clientId !== void 0 && e.seq !== void 0 && e.durable === true && (e.status.type === "unsent" || e.status.type === "parked")).sort((a, b) => (a.order ?? 0) - (b.order ?? 0));
+  }
+  let doneResolve;
+  function checkDone() {
+    if (log.size === 0 || drain.isPaused || closed) doneResolve?.();
+  }
+  const host = {
+    outbox,
+    // No live identity is ever minted for NEW mutations here (this function never calls
+    // `mutation()`) — nothing of this session's own needs protecting from `pruneDeadMeta`.
+    currentClientId: () => void 0,
+    currentFingerprint: () => fingerprint,
+    transportOpen: () => !closed,
+    isArmed: () => armed,
+    drainable,
+    addHydrated,
+    ensureInitialHandshake: () => {
+      if (connectSent) return;
+      connectSent = true;
+      transport.send(buildConnectMessage(`${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`, void 0, heldAtConnect));
+    },
+    setStatus: (entry, status) => {
+      entry.status = { type: status };
+      if (entry.clientId !== void 0 && entry.seq !== void 0) {
+        void outbox.updateStatus(entry.clientId, entry.seq, status).catch(() => {
+        });
+      }
+    },
+    batchEntry: (entry) => ({ requestId: entry.requestId, udfPath: entry.udfPath, args: entry.args, clientId: entry.clientId, seq: entry.seq }),
+    sendBatch: (entries) => transport.send({ type: "MutationBatch", entries }),
+    settleApplied: (requestId) => {
+      const entry = log.get(requestId);
+      log.delete(requestId);
+      if (entry?.clientId !== void 0 && entry.seq !== void 0) void outbox.dequeue(entry.clientId, entry.seq).catch(() => {
+      });
+      drained++;
+      checkDone();
+    },
+    settleTerminal: (requestId, code, message) => {
+      const entry = log.get(requestId);
+      log.delete(requestId);
+      if (entry?.clientId !== void 0 && entry.seq !== void 0) {
+        void outbox.updateStatus(entry.clientId, entry.seq, "failed", { message, code }).catch(() => {
+        });
+      }
+      failed++;
+      checkDone();
+    },
+    // No live queries — nothing to re-baseline (matches `client.ts#beginBaselineAwait`'s
+    // `expectTransition: false` branch, which adopts immediately with nothing to wait for).
+    whenBaselineAdopted: () => Promise.resolve()
+  };
+  const drain = new OutboxDrain(host, {
+    lockName,
+    locks: opts.locks,
+    poisonPolicy: opts.poisonPolicy ?? "skip",
+    intervalMs: 0,
+    // one-shot: progress is driven by responses/backoff timers, not a periodic nudge
+    onPause: () => checkDone()
+  });
+  async function handleClientReset() {
+    const fresh = defaultMintClientId();
+    let freshSeq = 0;
+    for (const entry of [...log.values()]) {
+      if (entry.status.type === "parked") {
+        log.delete(entry.requestId);
+        failed++;
+        if (entry.clientId !== void 0 && entry.seq !== void 0) {
+          void outbox.updateStatus(entry.clientId, entry.seq, "failed", {
+            message: "the server disowned this client's mutation history (swept/foreign timeline)",
+            code: "OFFLINE_CLIENT_RESET"
+          }).catch(() => {
+          });
+        }
+      } else if (entry.status.type === "unsent") {
+        const oldClientId = entry.clientId;
+        const oldSeq = entry.seq;
+        entry.clientId = fresh;
+        entry.seq = freshSeq++;
+        entry.order = ++orderCounter;
+        if (oldClientId !== void 0 && oldSeq !== void 0) void outbox.dequeue(oldClientId, oldSeq).catch(() => {
+        });
+        void outbox.append(toOutboxEntry(entry)).catch(() => {
+        });
+      }
+    }
+    await outbox.setMeta(fresh, { nextSeq: freshSeq, deployment });
+  }
+  const disposeMessage = transport.onMessage((msg) => {
+    if (msg.type === "MutationResponse") {
+      if (drain.handles(msg.requestId)) drain.onResponse(msg);
+      return;
+    }
+    if (msg.type === "ConnectAck") {
+      armed = true;
+      if (msg.known) {
+        drain.nudge();
+      } else {
+        void handleClientReset().then(() => {
+          drain.nudge();
+          checkDone();
+        }).catch((err) => {
+          console.error("[helipod] outbox: handleClientReset failed", err);
+          checkDone();
+        });
+      }
+    }
+  });
+  const disposeClose = transport.onClose(() => {
+    closed = true;
+    drain.onTransportClosed();
+    checkDone();
+  });
+  const donePromise = new Promise((resolve) => {
+    doneResolve = resolve;
+  });
+  drain.start();
+  let timeoutTimer;
+  const timeoutPromise = new Promise((resolve) => {
+    timeoutTimer = setTimeout(resolve, timeoutMs);
+    timeoutTimer.unref?.();
+  });
+  await Promise.race([donePromise, timeoutPromise]);
+  if (timeoutTimer !== void 0) clearTimeout(timeoutTimer);
+  drain.stop();
+  disposeMessage();
+  disposeClose();
+  return { drained, failed, remaining: log.size };
+}
+
+// src/auth-client.ts
+var KEY = "helipod.session";
+var SESSION_STORAGE_KEY = KEY;
+function localStorageSession(key = KEY) {
+  let ls;
+  try {
+    ls = typeof localStorage !== "undefined" ? localStorage : void 0;
+    if (ls) {
+      ls.setItem(`${key}.probe`, "1");
+      ls.removeItem(`${key}.probe`);
+    }
+  } catch {
+    ls = void 0;
+  }
+  if (!ls) return memorySession();
+  return {
+    load() {
+      try {
+        const raw = ls.getItem(key);
+        return raw ? JSON.parse(raw) : null;
+      } catch {
+        return null;
+      }
+    },
+    save(info) {
+      try {
+        ls.setItem(key, JSON.stringify(info));
+      } catch {
+      }
+    },
+    clear() {
+      try {
+        ls.removeItem(key);
+      } catch {
+      }
+    }
+  };
+}
+function memorySession() {
+  let cur = null;
+  return { load: () => cur, save: (i) => {
+    cur = i;
+  }, clear: () => {
+    cur = null;
+  } };
+}
+function defaultLock() {
+  const locks = typeof navigator !== "undefined" ? navigator.locks : void 0;
+  if (locks) {
+    return { run: (fn) => locks.request("helipod:auth:refresh", fn) };
+  }
+  let tail = Promise.resolve();
+  return {
+    run(fn) {
+      const next = tail.then(fn, fn);
+      tail = next.catch(() => {
+      });
+      return next;
+    }
+  };
+}
+function defaultBroadcast() {
+  const BC = typeof BroadcastChannel !== "undefined" ? BroadcastChannel : void 0;
+  if (!BC) return { post: () => {
+  }, onMessage: () => {
+  }, close: () => {
+  } };
+  const ch = new BC("helipod:auth:pair");
+  return {
+    post: (info) => ch.postMessage(info),
+    onMessage: (cb) => {
+      ch.onmessage = (e) => cb(e.data);
+    },
+    close: () => ch.close()
+  };
+}
+function codeOf(err) {
+  if (err && typeof err === "object") {
+    const c = err.code;
+    if (typeof c === "string") return c;
+    const m = err.message;
+    if (typeof m === "string") return m;
+  }
+  return String(err);
+}
+function createAuthClient(client, opts = {}) {
+  const storage = opts.storage ?? localStorageSession();
+  const lock = opts.lock ?? defaultLock();
+  const broadcast = opts.broadcast ?? defaultBroadcast();
+  const now = opts.now ?? (() => Date.now());
+  const fraction = opts.refreshAtFraction ?? 0.8;
+  const refreshPath = opts.refreshPath ?? "auth:refresh";
+  let info = storage.load();
+  let timer;
+  let closed = false;
+  let refreshFailureCount = 0;
+  function apply(next) {
+    refreshFailureCount = 0;
+    info = next;
+    if (next) {
+      storage.save(next);
+      client.setSessionFingerprint(next.sessionId);
+      client.setAuth(next.token);
+      schedule();
+    } else {
+      storage.clear();
+      client.setSessionFingerprint(null);
+      client.setAuth(null);
+      if (timer) clearTimeout(timer);
+    }
+  }
+  function schedule() {
+    if (timer) clearTimeout(timer);
+    if (!info || closed) return;
+    const remaining = info.expiresAt - now();
+    const delay = Math.max(0, remaining * fraction);
+    timer = setTimeout(() => {
+      void doRefresh();
+    }, delay);
+  }
+  const backoffBaseMs = 1e3;
+  const backoffCapMs = 6e4;
+  function scheduleBackoff() {
+    if (timer) clearTimeout(timer);
+    if (!info || closed) return;
+    refreshFailureCount++;
+    const delay = Math.min(backoffCapMs, backoffBaseMs * 2 ** (refreshFailureCount - 1));
+    timer = setTimeout(() => {
+      void doRefresh();
+    }, delay);
+  }
+  function isNewer(candidate, currentInfo) {
+    return candidate.refreshToken !== currentInfo.refreshToken && candidate.expiresAt > currentInfo.expiresAt;
+  }
+  async function doRefresh() {
+    if (!info || closed) return;
+    const before = info;
+    try {
+      const result = await lock.run(async () => {
+        const latest = storage.load();
+        if (latest && isNewer(latest, before)) return { adopted: latest };
+        const next = await client.mutation(refreshPath, { refreshToken: before.refreshToken }, { transient: true });
+        return { minted: next };
+      });
+      if (closed) return;
+      if ("adopted" in result && result.adopted) {
+        apply(result.adopted);
+        return;
+      }
+      if ("minted" in result && result.minted) {
+        apply(result.minted);
+        broadcast.post(result.minted);
+      }
+    } catch (err) {
+      if (closed) return;
+      const code = codeOf(err);
+      if (code === "REFRESH_STALE") {
+        setTimeout(() => {
+          if (closed) return;
+          const latest = storage.load();
+          if (latest && isNewer(latest, before)) apply(latest);
+          else schedule();
+        }, 250);
+        return;
+      }
+      if (code === "REFRESH_EXPIRED" || code === "REFRESH_REUSED") {
+        apply(null);
+        opts.onSignedOut?.();
+        return;
+      }
+      scheduleBackoff();
+    }
+  }
+  broadcast.onMessage((incoming) => {
+    if (closed || !info) return;
+    if (isNewer(incoming, info)) apply(incoming);
+  });
+  if (info) apply(info);
+  return {
+    setSession(next) {
+      apply(next);
+    },
+    clearSession() {
+      apply(null);
+      opts.onSignedOut?.();
+    },
+    getSessionInfo() {
+      return info ? { ...info } : null;
+    },
+    // shallow copy — never hand out the live internal object
+    close() {
+      closed = true;
+      if (timer) clearTimeout(timer);
+      broadcast.close();
+    }
+  };
+}
+
+// src/index.ts
+import { mintEncodedDocumentId } from "@helipod/id-codec";
+export {
+  AUTH_REFRESH_UDF_PATH,
+  DEFAULT_DRAIN_CHUNK_SIZE,
+  DEFAULT_DRAIN_INTERVAL_MS,
+  DEFAULT_OUTBOX_MAX_QUEUE_SIZE,
+  HelipodClient,
+  MutationUndeliveredError,
+  NON_REPLAYABLE_MUTATION_DROPPED,
+  OFFLINE_IDENTITY_CHANGED,
+  OUTBOX_VERSION,
+  OfflineClientResetError,
+  OutboxDrain,
+  OutboxOverflowError,
+  SESSION_STORAGE_KEY,
+  anyApi,
+  buildConnectMessage,
+  computeDrainBackoff,
+  createAuthClient,
+  createOptimisticLocalStore,
+  defaultMintClientId,
+  drainOutboxOnce,
+  getFunctionPath,
+  indexedDBOutbox,
+  localStorageSession,
+  loopbackTransport,
+  memoryOutbox,
+  memorySession,
+  mintEncodedDocumentId as mintDocumentId,
+  mintIdentity,
+  outboxAckedThrough,
+  outboxHeldFromLog,
+  outboxHeldFromStore,
+  reconnectDelayMs,
+  sessionFingerprintKey,
+  sha256Hex,
+  webSocketTransport
+};
+//# sourceMappingURL=index.js.map