@lenne.tech/nuxt-extensions 1.20.1 → 1.21.0

package/dist/runtime/composables/use-lt-offline-sync.js

@@ -0,0 +1,250 @@
+import { getCurrentScope, onScopeDispose, readonly, ref, shallowRef, watch } from "#imports";
+import { createLtSyncEngine } from "../lib/sync.js";
+import { subscribeLtSyncHints } from "../lib/sync-hints.js";
+import { claimLtSyncOwner, LT_SYNC_CHANNEL_NAME } from "../lib/sync-store.js";
+import { useLtAuth } from "./auth/use-lt-auth.js";
+const BACKOFF_START_MS = 1e3;
+const BACKOFF_MAX_MS = 6e4;
+const LOCAL_CHANGE_DELAY_MS = 300;
+const emptyResult = (overrides = {}) => ({
+  applied: 0,
+  conflicts: [],
+  forbidden: false,
+  needsLogin: false,
+  offline: false,
+  rejected: [],
+  resynced: false,
+  retried: 0,
+  ...overrides
+});
+export function useLtOfflineSync(model, options = {}) {
+  const records = shallowRef([]);
+  const pendingCount = ref(0);
+  const offline = ref(false);
+  const syncing = ref(false);
+  const needsLogin = ref(false);
+  const forbidden = ref(false);
+  const conflicts = shallowRef([]);
+  const rejected = shallowRef([]);
+  const error = ref(null);
+  const lastSyncedAt = ref(null);
+  const state = {
+    conflicts: readonly(conflicts),
+    error: readonly(error),
+    forbidden: readonly(forbidden),
+    lastSyncedAt: readonly(lastSyncedAt),
+    needsLogin: readonly(needsLogin),
+    offline: readonly(offline),
+    pendingCount: readonly(pendingCount),
+    // A shallow ref typed read-only: consumers cannot reassign it but can bind single records
+    records,
+    rejected: readonly(rejected),
+    syncing: readonly(syncing)
+  };
+  if (import.meta.server || typeof indexedDB === "undefined") {
+    const browserOnly = () => Promise.reject(new Error("useLtOfflineSync: offline sync runs in the browser only"));
+    return { ...state, create: browserOnly, get: async () => void 0, remove: browserOnly, sync: async () => emptyResult(), update: browserOnly };
+  }
+  const auto = options.auto !== false;
+  const { user } = useLtAuth();
+  const engine = createLtSyncEngine({ idFormat: options.idFormat, model, onConflict: options.onConflict, pageLimit: options.pageLimit, tenantId: options.tenantId });
+  const channel = typeof BroadcastChannel === "undefined" ? void 0 : new BroadcastChannel(LT_SYNC_CHANNEL_NAME);
+  let ownerId = null;
+  let claiming = null;
+  const currentUserId = () => user.value?.id ? String(user.value.id) : null;
+  async function ensureOwner() {
+    const id = currentUserId();
+    if (!id) {
+      ownerId = null;
+      return false;
+    }
+    if (id === ownerId) return true;
+    if (claiming?.id !== id) {
+      const pending = { done: claimLtSyncOwner(id), id };
+      claiming = pending;
+      void pending.done.finally(() => {
+        if (claiming === pending) claiming = null;
+      });
+    }
+    await claiming.done;
+    if (currentUserId() !== id) return ensureOwner();
+    ownerId = id;
+    return true;
+  }
+  async function refresh() {
+    if (!await ensureOwner()) {
+      records.value = [];
+      pendingCount.value = 0;
+      return;
+    }
+    const [list, pending] = await Promise.all([engine.list(), engine.pendingCount()]);
+    records.value = list;
+    pendingCount.value = pending;
+  }
+  async function owned(fn) {
+    if (!await ensureOwner()) throw new Error("useLtOfflineSync: no signed-in user owns the local data");
+    return fn();
+  }
+  let timer;
+  let backoffMs = 0;
+  let disposed = false;
+  let closeHints;
+  let hintsStopped = null;
+  function schedule(ms) {
+    if (disposed) return;
+    clearTimeout(timer);
+    timer = setTimeout(() => void sync().catch(() => void 0), ms);
+  }
+  function backOff(retryAfterMs = 0) {
+    backoffMs = Math.min(backoffMs ? backoffMs * 2 : BACKOFF_START_MS, BACKOFF_MAX_MS);
+    if (auto && !(typeof navigator !== "undefined" && navigator.onLine === false)) schedule(Math.max(retryAfterMs, backoffMs));
+  }
+  async function sync() {
+    if (!await ensureOwner()) {
+      needsLogin.value = true;
+      return emptyResult({ needsLogin: true });
+    }
+    syncing.value = true;
+    try {
+      const result = await engine.sync();
+      error.value = null;
+      offline.value = result.offline;
+      needsLogin.value = result.needsLogin;
+      forbidden.value = result.forbidden;
+      conflicts.value = result.conflicts;
+      rejected.value = result.rejected;
+      if (result.offline || result.retryAfterMs !== void 0 || result.retried) {
+        backOff(result.retryAfterMs);
+      } else if (!result.needsLogin) {
+        backoffMs = 0;
+        lastSyncedAt.value = /* @__PURE__ */ new Date();
+        if (hintsStopped === "unauthorized") {
+          hintsStopped = null;
+          startHints();
+        }
+      }
+      return result;
+    } catch (caught) {
+      error.value = caught instanceof Error ? caught : new Error(String(caught));
+      throw caught;
+    } finally {
+      syncing.value = false;
+      await refresh();
+      channel?.postMessage({ scope: engine.scope, type: "changed" });
+    }
+  }
+  const autoSync = () => {
+    if (auto) void sync().catch(() => void 0);
+  };
+  async function afterLocalChange() {
+    channel?.postMessage({ scope: engine.scope, type: "changed" });
+    await refresh();
+    if (auto) schedule(LOCAL_CHANGE_DELAY_MS);
+  }
+  function startHints() {
+    if (!auto || options.hints === false || closeHints || hintsStopped || disposed) return;
+    if (typeof document !== "undefined" && document.visibilityState === "hidden") return;
+    if (!user.value?.id) return;
+    closeHints = subscribeLtSyncHints({
+      model,
+      // Hints sent while the stream was down are not replayed: every (re)connect pulls once
+      onConnect: autoSync,
+      onHint: autoSync,
+      onStop: (reason) => {
+        stopHints();
+        hintsStopped = reason;
+      },
+      tenantId: options.tenantId
+    });
+  }
+  function stopHints() {
+    closeHints?.();
+    closeHints = void 0;
+  }
+  const onOnline = () => {
+    offline.value = false;
+    backoffMs = 0;
+    autoSync();
+  };
+  const onOffline = () => {
+    offline.value = true;
+  };
+  const onVisibility = () => {
+    if (document.visibilityState === "hidden") {
+      stopHints();
+      return;
+    }
+    startHints();
+    autoSync();
+  };
+  const onMessage = (event) => {
+    if (event.data?.type === "cleared") {
+      ownerId = null;
+      void refresh();
+    } else if (event.data?.type === "changed" && event.data.scope === engine.scope) {
+      void refresh();
+    }
+  };
+  if (typeof window !== "undefined") {
+    window.addEventListener("online", onOnline);
+    window.addEventListener("offline", onOffline);
+    window.addEventListener("focus", autoSync);
+    document.addEventListener("visibilitychange", onVisibility);
+    if (navigator.onLine === false) offline.value = true;
+  }
+  channel?.addEventListener("message", onMessage);
+  const stopUserWatch = watch(
+    () => user.value?.id ?? null,
+    (id, previous) => {
+      if (id === previous) return;
+      stopHints();
+      hintsStopped = hintsStopped === "disabled" ? "disabled" : null;
+      void refresh().then(() => {
+        if (!id) return;
+        startHints();
+        autoSync();
+      });
+    }
+  );
+  if (getCurrentScope()) {
+    onScopeDispose(() => {
+      disposed = true;
+      clearTimeout(timer);
+      stopHints();
+      stopUserWatch();
+      channel?.removeEventListener("message", onMessage);
+      channel?.close();
+      if (typeof window !== "undefined") {
+        window.removeEventListener("online", onOnline);
+        window.removeEventListener("offline", onOffline);
+        window.removeEventListener("focus", autoSync);
+        document.removeEventListener("visibilitychange", onVisibility);
+      }
+    });
+  }
+  void refresh().then(() => {
+    startHints();
+    autoSync();
+  });
+  return {
+    ...state,
+    async create(data) {
+      const record = await owned(() => engine.create(data));
+      await afterLocalChange();
+      return record;
+    },
+    async get(id) {
+      return await ensureOwner() ? engine.get(id) : void 0;
+    },
+    async remove(id) {
+      await owned(() => engine.remove(id));
+      await afterLocalChange();
+    },
+    sync,
+    async update(id, data) {
+      const record = await owned(() => engine.update(id, data));
+      await afterLocalChange();
+      return record;
+    }
+  };
+}

package/dist/runtime/lib/index.d.ts

@@ -1,3 +1,5 @@
 export { attemptLtJwtSwitch, clearLtAuthCookies, createLtAuthFetch, getLtApiBase, getLtAuthCookieNames, getLtAuthMode, getLtJwtToken, isLtAuthenticated, LT_AUTH_STATE_COOKIE_DEFAULT, LT_JWT_TOKEN_COOKIE_DEFAULT, ltAuthFetch, setLtAuthMode, setLtJwtToken, } from './auth-state.js';
 export { clearLtAuthPluginRegistry, createLtAuthClient, getOrCreateLtAuthClient, getLtAuthPluginRegistry, registerLtAuthPlugins, resetLtAuthClientSingleton, type LtAuthClient, } from './auth-client.js';
 export { buildLtAiUrl, getLtAiBasePath, ltAiRequest, ltAiResponseError, parseLtAiSseStream } from './ai.js';
+export { buildLtSyncUrl, flushLtSyncBeforeSignOut, getLtSyncBasePath, ltSyncObjectId, ltSyncUuidV7 } from './sync.js';
+export { deleteLtSyncDatabase } from './sync-store.js';

package/dist/runtime/lib/index.js

@@ -22,3 +22,5 @@ export {
   resetLtAuthClientSingleton
 } from "./auth-client.js";
 export { buildLtAiUrl, getLtAiBasePath, ltAiRequest, ltAiResponseError, parseLtAiSseStream } from "./ai.js";
+export { buildLtSyncUrl, flushLtSyncBeforeSignOut, getLtSyncBasePath, ltSyncObjectId, ltSyncUuidV7 } from "./sync.js";
+export { deleteLtSyncDatabase } from "./sync-store.js";

package/dist/runtime/lib/sync-hints.d.ts

@@ -0,0 +1,46 @@
+/**
+ * The hint stream of the offline sync: `GET <basePath>/hints` as server-sent events (protocol §9).
+ *
+ * Read with `fetch` and a `ReadableStream`, not `EventSource`: an EventSource cannot send an
+ * `Authorization` header, so in JWT mode (the fallback `ltAuthFetch` switches to when the cookie
+ * is refused) it would never be signed in (decision E2 of DEV-3917).
+ *
+ * The server ends a stream on purpose before its first hint after the re-check interval (30 s by
+ * default) and does not replay that hint. So every (re)connect calls `onConnect`, and the caller
+ * pulls once — without it a change would wait for the next focus or start whenever hints are
+ * further apart than the interval.
+ */
+export interface LtSyncHintsOptions {
+    /** `fetch` for the stream (default: `ltAuthFetch`) */
+    fetch?: (input: string, init: RequestInit) => Promise<Response>;
+    /** The models to hear about; a model the caller may not pull simply never sends a hint */
+    models: string[];
+    /** Every (re)connect. Hints sent while disconnected are not replayed: pull once (§9) */
+    onConnect: () => void;
+    /** A change of `model` was committed: pulling is worthwhile */
+    onHint: (model: string) => void;
+    /** The stream stopped for good: the server switched SSE off (`404`) or the session ended (`401`) */
+    onStop?: (reason: 'disabled' | 'unauthorized') => void;
+    /** Restrict to one tenant (`X-Tenant-Id`) */
+    tenantId?: string;
+}
+/** One instance listening for the hints of its model */
+export interface LtSyncHintSubscriber {
+    model: string;
+    onConnect: () => void;
+    onHint: () => void;
+    onStop?: (reason: 'disabled' | 'unauthorized') => void;
+    tenantId?: string;
+}
+/**
+ * Listen for the hints of a model on the ONE stream this tab keeps per tenant, for every model in
+ * use (`?models=` takes a list, §9). A stream per `useLtOfflineSync()` call would hold a connection
+ * each; over HTTP/1.1 a browser allows six per host, so six instances on one page would stall every
+ * other request to the API, sign-in and sign-out included. Answers the unsubscribe.
+ */
+export declare function subscribeLtSyncHints(subscriber: LtSyncHintSubscriber): () => void;
+/**
+ * Open the hint stream and keep it open — reconnecting after the server ends it, backing off after
+ * failures — until the returned `close()` is called or the stream stops for good (`onStop`).
+ */
+export declare function openLtSyncHints(options: LtSyncHintsOptions): () => void;

package/dist/runtime/lib/sync-hints.js

@@ -0,0 +1,147 @@
+import { ltAuthFetch } from "./auth-state.js";
+import { buildLtSyncUrl } from "./sync.js";
+const LINE_LIMIT = 1024 * 1024;
+const DEFAULT_RETRY_MS = 3e3;
+const MAX_BACKOFF_MS = 6e4;
+async function readEvents(body, onEvent, signal) {
+  const reader = body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  let event = { data: "", event: "message" };
+  const dispatchLine = (line) => {
+    if (line === "") {
+      if (event.data || event.retry !== void 0) onEvent(event);
+      event = { data: "", event: "message" };
+      return;
+    }
+    if (line.startsWith(":")) return;
+    const colon = line.indexOf(":");
+    const field = colon === -1 ? line : line.slice(0, colon);
+    const value = colon === -1 ? "" : line.slice(colon + 1).replace(/^ /, "");
+    if (field === "event") event.event = value;
+    else if (field === "data") event.data = event.data ? `${event.data}
+${value}` : value;
+    else if (field === "retry" && /^\d+$/.test(value)) event.retry = Number(value);
+  };
+  const onAbort = () => void reader.cancel().catch(() => void 0);
+  signal.addEventListener("abort", onAbort);
+  try {
+    for (; ; ) {
+      const { done, value } = await reader.read();
+      if (done) return;
+      buffer += decoder.decode(value, { stream: true });
+      let newline = buffer.search(/\r?\n|\r/);
+      while (newline !== -1) {
+        const line = buffer.slice(0, newline);
+        const skip = buffer[newline] === "\r" && buffer[newline + 1] === "\n" ? 2 : 1;
+        buffer = buffer.slice(newline + skip);
+        dispatchLine(line);
+        newline = buffer.search(/\r?\n|\r/);
+      }
+      if (buffer.length > LINE_LIMIT) throw new Error("sync hint stream: line exceeds 1 MiB");
+    }
+  } finally {
+    signal.removeEventListener("abort", onAbort);
+    reader.releaseLock();
+  }
+}
+const hubs = /* @__PURE__ */ new Map();
+export function subscribeLtSyncHints(subscriber) {
+  const key = subscriber.tenantId ?? "";
+  let hub = hubs.get(key);
+  if (!hub) {
+    hub = { models: "", subscribers: /* @__PURE__ */ new Set() };
+    hubs.set(key, hub);
+  }
+  const joined = hub;
+  joined.subscribers.add(subscriber);
+  connectHub(key, joined);
+  return () => {
+    if (!joined.subscribers.delete(subscriber)) return;
+    if (joined.subscribers.size === 0) {
+      joined.close?.();
+      if (hubs.get(key) === joined) hubs.delete(key);
+      return;
+    }
+    connectHub(key, joined);
+  };
+}
+function connectHub(key, hub) {
+  const models = [...new Set([...hub.subscribers].map((subscriber) => subscriber.model))].sort().join(",");
+  if (hub.close && hub.models === models) return;
+  hub.close?.();
+  hub.models = models;
+  hub.close = openLtSyncHints({
+    models: models.split(","),
+    onConnect: () => {
+      for (const subscriber of [...hub.subscribers]) subscriber.onConnect();
+    },
+    onHint: (model) => {
+      for (const subscriber of [...hub.subscribers]) if (subscriber.model === model) subscriber.onHint();
+    },
+    onStop: (reason) => {
+      hub.close = void 0;
+      hub.models = "";
+      for (const subscriber of [...hub.subscribers]) subscriber.onStop?.(reason);
+    },
+    tenantId: key || void 0
+  });
+}
+export function openLtSyncHints(options) {
+  const { models, onConnect, onHint, onStop, tenantId } = options;
+  const fetchImpl = options.fetch ?? ((input, init) => ltAuthFetch(input, init));
+  let closed = false;
+  let controller;
+  let timer;
+  let wake;
+  let retryMs = DEFAULT_RETRY_MS;
+  let failures = 0;
+  const wait = (ms) => new Promise((resolve) => {
+    wake = resolve;
+    timer = setTimeout(resolve, ms);
+  });
+  const loop = async () => {
+    while (!closed) {
+      controller = new AbortController();
+      try {
+        const query = new URLSearchParams({ models: models.join(",") });
+        const headers = { accept: "text/event-stream" };
+        if (tenantId) headers["x-tenant-id"] = tenantId;
+        const response = await fetchImpl(buildLtSyncUrl(`/hints?${query}`), { headers, method: "GET", signal: controller.signal });
+        if (response.status === 404 || response.status === 401) {
+          await response.body?.cancel().catch(() => void 0);
+          if (!closed) onStop?.(response.status === 404 ? "disabled" : "unauthorized");
+          return;
+        }
+        if (!response.ok || !response.body) throw new Error(`sync hint stream answered ${response.status}`);
+        failures = 0;
+        onConnect();
+        await readEvents(
+          response.body,
+          (event) => {
+            if (event.retry !== void 0) retryMs = event.retry;
+            if (event.event !== "change") return;
+            try {
+              const model = JSON.parse(event.data).model;
+              if (typeof model === "string") onHint(model);
+            } catch {
+            }
+          },
+          controller.signal
+        );
+        if (!closed) await wait(retryMs);
+      } catch {
+        if (closed) return;
+        failures++;
+        await wait(Math.min(retryMs * 2 ** Math.min(failures - 1, 5), MAX_BACKOFF_MS));
+      }
+    }
+  };
+  void loop();
+  return () => {
+    closed = true;
+    controller?.abort();
+    clearTimeout(timer);
+    wake?.();
+  };
+}

package/dist/runtime/lib/sync-store.d.ts

@@ -0,0 +1,89 @@
+/**
+ * IndexedDB storage of the offline sync (`useLtOfflineSync`).
+ *
+ * ONE database per origin holds every synchronized model: records, the outbox of unsent changes,
+ * and meta values (cursors, the owning user). One database is what makes sign-out safe — the
+ * nest-server's `SECURITY.md` asks a client to delete every record, cursor and unsent change, and
+ * deleting the whole database is the one operation that cannot miss a model.
+ *
+ * Every tab of the origin shares the database; IndexedDB serializes their read-write transactions.
+ * A transaction stays open only while `fn` awaits requests of that same transaction, so nothing
+ * inside `run()` may await anything else (a fetch, a timer, an app hook).
+ */
+import type { LtSyncRecord } from '../types/sync.js';
+/** Name of the database every model shares */
+export declare const LT_SYNC_DB_NAME = "lt-offline-sync";
+/** BroadcastChannel the tabs of an origin use to tell each other about changes */
+export declare const LT_SYNC_CHANNEL_NAME = "lt-offline-sync";
+/** An outbox entry: a protocol push item (§6.2) plus local bookkeeping */
+export interface LtSyncOutboxItem {
+    /** Set once a push carried the item; it is never changed again, a repeat must carry the same change (§6.5) */
+    attempted?: boolean;
+    baseVersion?: number;
+    data?: Record<string, unknown>;
+    id: string;
+    mutationId: string;
+    op: 'delete' | 'upsert';
+    seq?: number;
+}
+/** What `run()` hands its callback: the transaction's operations, scoped to one model */
+export interface LtSyncStoreTx {
+    addOutbox: (item: LtSyncOutboxItem) => Promise<unknown>;
+    /** Delete every local record of the model except `keepIds` */
+    clearRecords: (keepIds: Set<string>) => Promise<void>;
+    deleteMeta: (key: string) => Promise<unknown>;
+    deleteRecord: (id: string) => Promise<unknown>;
+    getMeta: <V = unknown>(key: string) => Promise<undefined | V>;
+    getRecord: (id: string) => Promise<LtSyncRecord | undefined>;
+    /** The model's unsent changes in the order they were made */
+    listOutbox: () => Promise<LtSyncOutboxItem[]>;
+    listRecords: () => Promise<LtSyncRecord[]>;
+    putOutbox: (item: LtSyncOutboxItem) => Promise<unknown>;
+    putRecord: (record: LtSyncRecord) => Promise<unknown>;
+    removeOutbox: (mutationId: string) => Promise<void>;
+    setMeta: (key: string, value: unknown) => Promise<unknown>;
+}
+/**
+ * The data no longer belongs to the user a sync run started for: signed out (database deleted) or
+ * another account claimed it. The run's write was refused, nothing of it was stored.
+ */
+export declare class LtSyncOwnerChangedError extends Error {
+    constructor();
+}
+/**
+ * Run `fn` in one read-write transaction over the scope's records, outbox and meta values. `scope`
+ * is a model, or a model and tenant (`note#<tenantId>`).
+ *
+ * With `owner`, the transaction first checks that the data still belongs to that user and refuses
+ * otherwise (`LtSyncOwnerChangedError`). A sync answer can arrive after sign-out deleted the
+ * database, or after another account claimed it — in this tab or another one. Unfenced, it would
+ * reopen the database and write the previous user's records for the next user to see.
+ */
+export declare function runLtSyncTx<R>(model: string, fn: (tx: LtSyncStoreTx) => Promise<R>, options?: {
+    owner?: string;
+}): Promise<R>;
+/** The scopes (model, or model and tenant) that hold unsent changes, in no particular order */
+export declare function listLtSyncPendingModels(): Promise<string[]>;
+/** The user the local data belongs to, if any */
+export declare function getLtSyncOwner(): Promise<string | undefined>;
+/**
+ * Bind the local data to the signed-in user, in ONE transaction. The same user keeps it. Anybody
+ * else — another user, or nobody at all while data is present — means it is not this user's: every
+ * model is wiped before anything is shown or pulled (nest-server `SECURITY.md`). Data without an
+ * owner can only be a write that outlived a sign-out, which is exactly what must not be inherited.
+ * Answers whether it wiped.
+ */
+export declare function claimLtSyncOwner(userId: string): Promise<boolean>;
+/**
+ * Delete every record, cursor and unsent change of every model — on sign-out. Other tabs close
+ * their connection on `versionchange` and are told via the channel. A sync answer arriving later
+ * finds no owner and is refused (`runLtSyncTx` with `owner`).
+ */
+export declare function deleteLtSyncDatabase(): Promise<void>;
+/** Messages the tabs exchange */
+export type LtSyncMessage = {
+    scope: string;
+    type: 'changed';
+} | {
+    type: 'cleared';
+};