@ironflow/browser 0.26.0 → 0.28.0

package/dist/offline.js

@@ -0,0 +1,306 @@
+/**
+ * The offline-capable client (ADR 0052).
+ *
+ * Why this is a separate factory rather than a flag on the singleton:
+ * `configure()` returns `void`, so TypeScript cannot refine `emit()`'s static
+ * return type from a runtime option. Putting the queued-result type on the
+ * shared `ironflow` singleton would force every existing caller to handle a
+ * case that can only occur for apps that opted in — a package-wide breaking
+ * change dressed up as an opt-in. A factory confines the new type to clients
+ * that asked for it and leaves `ironflow` exactly as it was.
+ *
+ *   createClient({ offlineQueue: { identity } })
+ *        │
+ *        ├─ no IndexedDB (SSR, Node)  ──> queue disabled, writes go direct
+ *        └─ IndexedDB available       ──> OfflineQueue over emit + append
+ *
+ * The underlying full client stays reachable as `.client`, so everything this
+ * surface does not wrap (runs, projections, subscriptions, admin) is one
+ * property away rather than re-declared here.
+ */
+import { IronflowError } from "@ironflow/core";
+import { IronflowClient, REPLAY_QUEUED_WRITE } from "./client.js";
+import { newUuid } from "./queue/ids.js";
+import { OfflineQueue } from "./queue/queue.js";
+/**
+ * Endpoint per write kind.
+ *
+ * The drainer resolves the path through this at send time and never reads one
+ * out of storage, so a record injected into IndexedDB cannot aim an
+ * authenticated POST at an arbitrary endpoint.
+ */
+const PATHS = {
+    emit: "/ironflow.v1.PubSubService/Emit",
+    "stream-append": "/ironflow.v1.EntityStreamService/AppendEvent",
+};
+/**
+ * A client whose `emit` and `streams.append` persist before they send.
+ *
+ * Note that neither returns `runIds`. A run id cannot exist before the server
+ * creates the run, and the whole point here is to answer before contacting the
+ * server. Subscribe for the outcome instead.
+ */
+export class OfflineClient {
+    /** The full client. Everything not wrapped here lives on it. */
+    client;
+    offlineQueue;
+    /** @internal Use {@link createClient}. */
+    constructor(client, queue) {
+        this.client = client;
+        this.offlineQueue = queue;
+    }
+    /**
+     * Emit an event, persisting it first.
+     *
+     * Always write-through, even when the network is fine. Sending directly
+     * whenever the queue happens to be empty would let a new write overtake
+     * queued ones the moment it is not, which is the FIFO violation the design
+     * exists to prevent.
+     */
+    async emit(eventName, data, options) {
+        // Fix the key HERE, before serialising, so the stored bytes already carry
+        // it. If the body went out without one, every retry would create a fresh
+        // event server-side and the queue's whole exactly-once story would be
+        // fiction — the engine dedups on this field and nothing else.
+        //
+        // `||`, not `??`: an empty string is a key the engine will ignore, so
+        // honouring it verbatim would report a dedup key that does not dedup.
+        if (!this.offlineQueue) {
+            const direct = directIdempotencyKey(options?.idempotencyKey);
+            const result = await this.client.emit(eventName, data, {
+                ...options,
+                idempotencyKey: direct,
+            });
+            return {
+                queued: false,
+                localId: result.eventId ?? "",
+                idempotencyKey: direct ?? "",
+                pending: false,
+            };
+        }
+        const key = options?.idempotencyKey || newUuid();
+        const { localId, idempotencyKey } = await this.offlineQueue.enqueue({
+            kind: "emit",
+            body: {
+                event: eventName,
+                data,
+                ...(options?.version ? { version: options.version } : {}),
+                idempotency_key: key,
+                metadata: options?.metadata,
+                namespace: options?.namespace,
+            },
+            idempotencyKey: key,
+        });
+        return { queued: true, localId, idempotencyKey, pending: true };
+    }
+    streams = {
+        /**
+         * Append to an entity stream, persisting first.
+         *
+         * `expectedVersion` is refused outright. A version read before the write
+         * was queued is stale by definition, so the append is guaranteed to lose
+         * its optimistic-concurrency check — the server answers `CodeAborted`/409,
+         * which this queue treats as permanent and dead-letters. Failing loudly at
+         * call time beats discovering it in the dead-letter store later.
+         * Merge-on-conflict is a separate feature.
+         */
+        append: async (entityId, input, options) => {
+            if (options?.expectedVersion !== undefined &&
+                options.expectedVersion !== -1) {
+                throw new IronflowError("streams.append cannot be queued with expectedVersion set: the version " +
+                    "is stale by the time the write is sent, so the append would always " +
+                    "conflict. Use expectedVersion: -1, or write through client.streams.append.", { code: "QUEUE_EXPECTED_VERSION_UNSUPPORTED", retryable: false });
+            }
+            // Same reasoning as emit(): the key has to be in the stored bytes, not
+            // just alongside them, or a retry duplicates the event — and the direct
+            // path gets one too, so the reported key is always the one the engine saw.
+            if (!this.offlineQueue) {
+                const direct = directIdempotencyKey(options?.idempotencyKey);
+                const result = await this.client.streams.append(entityId, input, {
+                    ...options,
+                    idempotencyKey: direct,
+                });
+                return {
+                    queued: false,
+                    localId: result.eventId,
+                    idempotencyKey: direct ?? "",
+                    pending: false,
+                };
+            }
+            const key = options?.idempotencyKey || newUuid();
+            const body = {
+                entity_id: entityId,
+                entity_type: input.entityType,
+                event_name: input.name,
+                data: input.data,
+                expected_version: -1,
+                idempotency_key: key,
+                version: options?.version ?? 1,
+            };
+            if (options?.metadata !== undefined) {
+                body.metadata = options.metadata;
+            }
+            const { localId, idempotencyKey } = await this.offlineQueue.enqueue({
+                kind: "stream-append",
+                body,
+                idempotencyKey: key,
+            });
+            return { queued: true, localId, idempotencyKey, pending: true };
+        },
+    };
+    /** Stable across reads, so `useEffect(..., [app.queue])` does not thrash. */
+    queueApi = null;
+    get queue() {
+        if (this.queueApi)
+            return this.queueApi;
+        const q = this.offlineQueue;
+        if (!q) {
+            // No IndexedDB: the surface still exists so callers need no branching,
+            // it just reports an empty, disabled queue.
+            const empty = {
+                pending: 0,
+                inFlight: 0,
+                total: 0,
+                deadLettered: 0,
+                state: "idle",
+            };
+            return (this.queueApi = {
+                enabled: false,
+                stats: () => empty,
+                subscribe: (cb) => {
+                    cb(empty);
+                    return () => { };
+                },
+                watch: (_id, cb) => {
+                    cb({ status: "sent" });
+                    return () => { };
+                },
+                flush: async () => { },
+                deadLetter: async () => [],
+                discard: async () => false,
+                retry: async () => false,
+            });
+        }
+        return (this.queueApi = {
+            enabled: true,
+            stats: () => q.stats(),
+            subscribe: (cb) => q.subscribe(cb),
+            watch: (id, cb) => q.watch(id, cb),
+            flush: () => q.flush(),
+            deadLetter: () => q.deadLetter(),
+            discard: (id) => q.discard(id),
+            retry: (id) => q.retry(id),
+        });
+    }
+    /**
+     * Stop draining and release the database.
+     *
+     * Drain-then-swap: an in-flight write is allowed to finish rather than being
+     * abandoned with its fate unknown.
+     */
+    async close() {
+        await this.offlineQueue?.stop();
+        this.client.disconnect();
+    }
+}
+/**
+ * The dedup key to report and send on the direct (queue-disabled) path.
+ *
+ * An empty string counts as absent. The engine skips dedup entirely for an
+ * empty key, so passing one straight through would make
+ * `QueuedWriteResult.idempotencyKey` — documented as "the dedup key the engine
+ * will see" — false exactly where a caller might trust it to retry safely.
+ *
+ * Generation is allowed to FAIL rather than throw. This path exists for
+ * environments missing browser APIs (SSR, Node, a locked-down WebView), and
+ * `newUuid()` throws without Web Crypto — so generating unconditionally would
+ * turn the documented degradation path into a crash on the very environments it
+ * exists to tolerate. Reporting no key there is honest: the engine saw none.
+ */
+function directIdempotencyKey(supplied) {
+    if (supplied)
+        return supplied;
+    try {
+        return newUuid();
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Default database name; scoped so staging writes can never flush into prod. */
+export function queueDbName(serverUrl, environment) {
+    return `ironflow-queue:${serverUrl}:${environment}`;
+}
+/**
+ * Create a client that persists writes before sending them.
+ *
+ * Async because the outbox has to be opened and its counters hydrated before
+ * the first `emit` can be honestly answered.
+ *
+ * Degrades rather than throwing when the environment has no IndexedDB (SSR, a
+ * Node import, a locked-down browser): the queue disables itself, writes go
+ * straight out, and the app keeps working. Throwing here would crash a server
+ * render for anyone who put the option in shared config.
+ */
+export async function createClient(options) {
+    const { offlineQueue: queueConfig, ...clientOptions } = options;
+    const client = new IronflowClient();
+    client.configure(clientOptions);
+    const config = client.getConfig();
+    if (typeof indexedDB === "undefined") {
+        // Through the client's logger, so an app that quieted SDK logging is not
+        // shouted at on every SSR render — the case this branch exists to tolerate.
+        client.getLogger().warn("IndexedDB is unavailable; the offline write queue is disabled and writes will be sent directly.");
+        return new OfflineClient(client, null);
+    }
+    const queue = new OfflineQueue({
+        dbName: queueConfig.dbName ?? queueDbName(config.serverUrl, config.environment),
+        identity: queueConfig.identity,
+        maxItems: queueConfig.maxItems,
+        maxBytes: queueConfig.maxBytes,
+        maxRetentionMs: queueConfig.maxRetentionMs,
+        maxDeadLettered: queueConfig.maxDeadLettered,
+        onWriteLost: queueConfig.onWriteLost
+            ? (write, reason, message) => queueConfig.onWriteLost({ localId: write.localId, kind: write.kind, body: write.body }, reason, message)
+            : undefined,
+        onAuthRequired: queueConfig.onAuthRequired
+            ? async () => {
+                // Applied through setAuth(), never configure(): configure() is a full
+                // teardown and would destroy the transport, the subscriptions and the
+                // drainer that is mid-recovery.
+                const { identity, ...auth } = await queueConfig.onAuthRequired();
+                // Only when a credential actually came back. Both `AuthConfig` fields
+                // are optional, so returning `{ identity }` alone typechecks — and
+                // `setAuth({})` would then clear the credential on the SHARED client,
+                // taking subscriptions and every non-queue call down with it, and
+                // guaranteeing the next attempt 401s again.
+                if (auth.apiKey || auth.token) {
+                    client.setAuth(auth);
+                }
+                // Returning the identity lets the queue rebind. If a DIFFERENT user
+                // signed in at the prompt, the pending writes then fail the identity
+                // check and are quarantined instead of being sent as that new user.
+                return { identity };
+            }
+            : undefined,
+        resolvePath: (kind) => PATHS[kind] ?? null,
+        // Read live, not captured: the guard exists to catch a client that was
+        // reconfigured to another server or environment while writes were queued.
+        currentDestination: () => {
+            const live = client.getConfig();
+            return { serverUrl: live.serverUrl, environment: live.environment };
+        },
+        send: (path, write) => client[REPLAY_QUEUED_WRITE](path, write.body),
+    });
+    try {
+        await queue.start();
+    }
+    catch (error) {
+        // A database written by a newer SDK, or storage that refuses to open. The
+        // app is more useful with direct writes than with a hard failure at import.
+        client.getLogger().warn(`offline write queue could not start; writes will be sent directly. ${error instanceof Error ? error.message : String(error)}`);
+        return new OfflineClient(client, null);
+    }
+    return new OfflineClient(client, queue);
+}
+//# sourceMappingURL=offline.js.map

package/dist/offline.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"offline.js","sourceRoot":"","sources":["../src/offline.ts"],"names":[],"mappings":"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"}

package/dist/queue/db.d.ts

@@ -0,0 +1,123 @@
+/**
+ * IndexedDB persistence for the offline write queue (ADR 0052).
+ *
+ * Two object stores:
+ *
+ *   outbox      keyPath "seq", autoIncrement   index: localId
+ *               Insertion order IS send order — autoIncrement gives a
+ *               monotonic FIFO key for free, so "next to send" is just the
+ *               first record by key.
+ *
+ *   deadletter  keyPath "write.localId"
+ *               Writes that will never be sent, kept so an app can list,
+ *               discard, or replay them. Without a surface they would be
+ *               inaccessible data growing until quota pressure.
+ *
+ * Raw IndexedDB, no wrapper dependency: two stores and one upgrade handler do
+ * not justify adding to a package with four runtime deps.
+ */
+import { type DeadLetteredWrite, type QueuedWrite } from "./types.js";
+/** A write with its FIFO key not yet assigned by IndexedDB. */
+export type NewQueuedWrite = Omit<QueuedWrite, "seq">;
+/**
+ * Thrown when the stored database was created by a NEWER SDK.
+ *
+ * IndexedDB refuses to open a database at a lower version than the one on disk,
+ * which is exactly the signal we want: a rollback, or another tab on a newer
+ * build. The queue disables delivery rather than touching data it cannot read.
+ */
+export declare class QueueVersionError extends Error {
+    constructor(message: string);
+}
+/** Thrown when a write cannot be stored because the origin is out of quota. */
+export declare class QueueQuotaError extends Error {
+    constructor(message: string);
+}
+export declare class QueueDb {
+    private readonly db;
+    readonly name: string;
+    private constructor();
+    /**
+     * Open (creating if needed) the queue database.
+     *
+     * @throws {QueueVersionError} when the stored database is newer than this SDK.
+     */
+    static open(name: string): Promise<QueueDb>;
+    close(): void;
+    /**
+     * Append a write and return the FIFO key IndexedDB assigned it.
+     *
+     * @throws {QueueQuotaError} when the origin is out of storage.
+     */
+    append(write: NewQueuedWrite): Promise<number>;
+    /**
+     * The next write to send, or `undefined` when the outbox is empty.
+     *
+     * Strict FIFO: always the lowest key. A write that fails stays here, which is
+     * what makes the queue blocking — item N+1 cannot pass item N.
+     */
+    head(): Promise<QueuedWrite | undefined>;
+    remove(seq: number): Promise<void>;
+    findByLocalId(localId: string): Promise<QueuedWrite | undefined>;
+    /**
+     * Item count and total bytes, for the caps and the pending badge.
+     *
+     * Read once at open; the queue keeps counters in memory afterwards rather
+     * than paying a store scan per write.
+     */
+    usage(): Promise<{
+        count: number;
+        bytes: number;
+    }>;
+    /**
+     * Whether the outbox holds records this SDK does not understand.
+     *
+     * Such records are left untouched and stop delivery entirely: skipping past
+     * them would break FIFO, and dead-lettering them would destroy valid data
+     * written by a newer build.
+     */
+    hasFutureRecords(): Promise<boolean>;
+    /** Move a write out of the outbox and into the dead-letter store atomically. */
+    deadLetter(entry: DeadLetteredWrite): Promise<void>;
+    listDeadLettered(): Promise<DeadLetteredWrite[]>;
+    countDeadLettered(): Promise<number>;
+    discardDeadLettered(localId: string): Promise<boolean>;
+    /**
+     * Move a dead-lettered write back onto the outbox in ONE transaction.
+     *
+     * Two transactions would leave both copies alive if the second failed, and the
+     * surviving dead letter could then be retried again — a duplicate that the
+     * engine only dedupes because the idempotency key is preserved.
+     */
+    requeueDeadLettered(localId: string, enqueuedAt: number): Promise<QueuedWrite | undefined>;
+    /**
+     * Where one write currently lives, read from BOTH stores in ONE transaction.
+     *
+     * Two separate reads can interleave with `deadLetter()`, which moves a record
+     * between the stores atomically: read the dead-letter store (miss), the move
+     * commits, read the outbox (miss) — and the write reports as delivered when
+     * it was actually lost. A single readonly transaction spanning both stores
+     * cannot observe that intermediate state.
+     *
+     * Both requests are issued before the first await on purpose. Awaiting one
+     * before opening the other would let the transaction auto-close, putting the
+     * second read back in a transaction of its own and reinstating the race.
+     */
+    statusOf(localId: string): Promise<{
+        kind: "queued";
+    } | {
+        kind: "dead";
+        entry: DeadLetteredWrite;
+    } | {
+        kind: "absent";
+    }>;
+    getDeadLettered(localId: string): Promise<DeadLetteredWrite | undefined>;
+    /**
+     * Trim the dead-letter store to its cap, oldest first.
+     *
+     * Drop-oldest is fine here, unlike the outbox: ordering does not matter for
+     * writes that are already never going to be sent.
+     */
+    trimDeadLettered(max: number): Promise<void>;
+}
+//# sourceMappingURL=db.d.ts.map

package/dist/queue/db.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"db.d.ts","sourceRoot":"","sources":["../../src/queue/db.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,EAEL,KAAK,iBAAiB,EACtB,KAAK,WAAW,EACjB,MAAM,YAAY,CAAC;AASpB,+DAA+D;AAC/D,MAAM,MAAM,cAAc,GAAG,IAAI,CAAC,WAAW,EAAE,KAAK,CAAC,CAAC;AAEtD;;;;;;GAMG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;gBAC9B,OAAO,EAAE,MAAM;CAI5B;AAED,+EAA+E;AAC/E,qBAAa,eAAgB,SAAQ,KAAK;gBAC5B,OAAO,EAAE,MAAM;CAI5B;AA4BD,qBAAa,OAAO;IAEhB,OAAO,CAAC,QAAQ,CAAC,EAAE;IACnB,QAAQ,CAAC,IAAI,EAAE,MAAM;IAFvB,OAAO;IAKP;;;;OAIG;WACU,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAmDjD,KAAK,IAAI,IAAI;IAQb;;;;OAIG;IACG,MAAM,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC;IAgBpD;;;;;OAKG;IACG,IAAI,IAAI,OAAO,CAAC,WAAW,GAAG,SAAS,CAAC;IAMxC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAMlC,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,SAAS,CAAC;IAQtE;;;;;OAKG;IACG,KAAK,IAAI,OAAO,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAWxD;;;;;;OAMG;IACG,gBAAgB,IAAI,OAAO,CAAC,OAAO,CAAC;IAY1C,gFAAgF;IAC1E,UAAU,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;IAOnD,gBAAgB,IAAI,OAAO,CAAC,iBAAiB,EAAE,CAAC;IAQhD,iBAAiB,IAAI,OAAO,CAAC,MAAM,CAAC;IAKpC,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAa5D;;;;;;OAMG;IACG,mBAAmB,CACvB,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,WAAW,GAAG,SAAS,CAAC;IAoBnC;;;;;;;;;;;;OAYG;IACG,QAAQ,CACZ,OAAO,EAAE,MAAM,GACd,OAAO,CACN;QAAE,IAAI,EAAE,QAAQ,CAAA;KAAE,GAClB;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,iBAAiB,CAAA;KAAE,GAC1C;QAAE,IAAI,EAAE,QAAQ,CAAA;KAAE,CACrB;IAaK,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,GAAG,SAAS,CAAC;IAO9E;;;;;OAKG;IACG,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CA4BnD"}