@porulle/sdk 0.7.0 → 0.8.0

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export { createSDK, createClient, type SDKOptions } from "./client.js";
+export { OfflineQueue, memoryStorage, webStorage, type OfflineQueueOptions, type QueuedOperation, type QueueState, type QueueStorage, } from "./offline-queue.js";
 export { authMiddleware, type AuthCredential, type ApiKeyAuth, type BearerAuth } from "./middleware.js";
 export { isApiError, mapApiErrorToFields, type ApiErrorBody, type ValidationIssue, } from "./errors.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AACvE,OAAO,EAAE,cAAc,EAAE,KAAK,cAAc,EAAE,KAAK,UAAU,EAAE,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AACxG,OAAO,EACL,UAAU,EACV,mBAAmB,EACnB,KAAK,YAAY,EACjB,KAAK,eAAe,GACrB,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AACvE,OAAO,EACL,YAAY,EACZ,aAAa,EACb,UAAU,EACV,KAAK,mBAAmB,EACxB,KAAK,eAAe,EACpB,KAAK,UAAU,EACf,KAAK,YAAY,GAClB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,cAAc,EAAE,KAAK,cAAc,EAAE,KAAK,UAAU,EAAE,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AACxG,OAAO,EACL,UAAU,EACV,mBAAmB,EACnB,KAAK,YAAY,EACjB,KAAK,eAAe,GACrB,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -1,4 +1,5 @@
 export { createSDK, createClient } from "./client.js";
+export { OfflineQueue, memoryStorage, webStorage, } from "./offline-queue.js";
 export { authMiddleware } from "./middleware.js";
 export { isApiError, mapApiErrorToFields, } from "./errors.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,YAAY,EAAmB,MAAM,aAAa,CAAC;AACvE,OAAO,EAAE,cAAc,EAAyD,MAAM,iBAAiB,CAAC;AACxG,OAAO,EACL,UAAU,EACV,mBAAmB,GAGpB,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,YAAY,EAAmB,MAAM,aAAa,CAAC;AACvE,OAAO,EACL,YAAY,EACZ,aAAa,EACb,UAAU,GAKX,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,cAAc,EAAyD,MAAM,iBAAiB,CAAC;AACxG,OAAO,EACL,UAAU,EACV,mBAAmB,GAGpB,MAAM,aAAa,CAAC"}

package/dist/offline-queue.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Offline-first operation queue (issue #54).
+ *
+ * POS clients must keep selling through network drops. This queue persists
+ * write operations (pluggable storage), stamps each with an idempotency key
+ * (core replays `POST /api/orders` / `POST /api/checkout` with the same key
+ * and returns the original order), and drains on reconnect with backoff.
+ * Queue state — pending/failed plus server error bodies — is observable, and
+ * failed operations support manual retry/drop.
+ */
+export interface QueuedOperation {
+    /** Unique id; also stamped into the body as `idempotencyKey`. */
+    id: string;
+    path: string;
+    method: "POST" | "PUT" | "PATCH" | "DELETE";
+    body: Record<string, unknown>;
+    createdAt: string;
+    attempts: number;
+    status: "pending" | "failed";
+    lastError?: {
+        status?: number | undefined;
+        body?: unknown;
+        message: string;
+    } | undefined;
+}
+export interface QueueStorage {
+    load(): Promise<QueuedOperation[]> | QueuedOperation[];
+    save(operations: QueuedOperation[]): Promise<void> | void;
+}
+/** Volatile storage — tests and environments without persistence. */
+export declare function memoryStorage(): QueueStorage;
+/** Storage backed by any localStorage-compatible object (web, RN shims). */
+export declare function webStorage(storage: {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+}, key?: string): QueueStorage;
+export interface OfflineQueueOptions {
+    /** Base URL of the commerce server (e.g. "https://api.example.com"). */
+    baseUrl: string;
+    /** Headers sent with every replayed request (e.g. Authorization). */
+    headers?: Record<string, string> | undefined;
+    /** Where operations persist. Default: in-memory. */
+    storage?: QueueStorage | undefined;
+    /** Custom fetch (testing, RN). Default: globalThis.fetch. */
+    fetch?: typeof globalThis.fetch | undefined;
+    /** Attempts before a retryable failure is marked `failed`. Default: 5. */
+    maxAttempts?: number | undefined;
+    /** Base backoff delay in ms (doubles per attempt, capped at 60s). Default: 1000. */
+    backoffMs?: number | undefined;
+    /** Listen for the window `online` event and auto-flush. Default: true when available. */
+    autoFlush?: boolean | undefined;
+    /** Field name stamped into the body. Default: "idempotencyKey". */
+    idempotencyField?: string | undefined;
+}
+export interface QueueState {
+    pending: number;
+    failed: number;
+    operations: QueuedOperation[];
+}
+type Listener = (state: QueueState) => void;
+export declare class OfflineQueue {
+    private readonly baseUrl;
+    private readonly headers;
+    private readonly fetchImpl;
+    private readonly maxAttempts;
+    private readonly backoffMs;
+    private readonly idempotencyField;
+    private readonly storage;
+    private operations;
+    private listeners;
+    private loaded;
+    private flushing;
+    private retryTimer;
+    private readonly onlineHandler;
+    constructor(options: OfflineQueueOptions);
+    /** Stops timers and the online listener. */
+    dispose(): void;
+    /**
+     * Enqueues an operation with an idempotency key stamped into the body.
+     * Resolves once the operation is durably queued — call `flush()` (or rely
+     * on the `online` listener / backoff timer) to deliver it.
+     */
+    enqueue(path: string, body: Record<string, unknown>, opts?: {
+        method?: QueuedOperation["method"] | undefined;
+        idempotencyKey?: string | undefined;
+    }): Promise<QueuedOperation>;
+    /** Current queue state (pending/failed counts + operations with errors). */
+    state(): Promise<QueueState>;
+    /** Subscribe to state changes. Returns an unsubscribe function. */
+    onChange(listener: Listener): () => void;
+    /** Re-queues a failed operation for the next flush. */
+    retry(id: string): Promise<void>;
+    /** Drops an operation from the queue entirely. */
+    drop(id: string): Promise<void>;
+    /**
+     * Drains pending operations FIFO. Network-level failures stop the drain
+     * (we're offline) and schedule a backoff retry; HTTP failures mark the
+     * operation failed (non-retryable) or retry it (5xx/408/429).
+     */
+    flush(): Promise<QueueState>;
+    private scheduleRetry;
+    private persist;
+}
+export {};
+//# sourceMappingURL=offline-queue.d.ts.map

package/dist/offline-queue.d.ts.map

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

package/dist/offline-queue.js

@@ -0,0 +1,228 @@
+/**
+ * Offline-first operation queue (issue #54).
+ *
+ * POS clients must keep selling through network drops. This queue persists
+ * write operations (pluggable storage), stamps each with an idempotency key
+ * (core replays `POST /api/orders` / `POST /api/checkout` with the same key
+ * and returns the original order), and drains on reconnect with backoff.
+ * Queue state — pending/failed plus server error bodies — is observable, and
+ * failed operations support manual retry/drop.
+ */
+/** Volatile storage — tests and environments without persistence. */
+export function memoryStorage() {
+    let operations = [];
+    return {
+        load: () => operations,
+        save: (next) => {
+            operations = next;
+        },
+    };
+}
+/** Storage backed by any localStorage-compatible object (web, RN shims). */
+export function webStorage(storage, key = "porulle.offline-queue") {
+    return {
+        load: () => {
+            try {
+                const raw = storage.getItem(key);
+                return raw ? JSON.parse(raw) : [];
+            }
+            catch {
+                return [];
+            }
+        },
+        save: (operations) => {
+            storage.setItem(key, JSON.stringify(operations));
+        },
+    };
+}
+function generateId() {
+    const cryptoObj = globalThis.crypto;
+    if (cryptoObj?.randomUUID)
+        return cryptoObj.randomUUID();
+    return `op_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`;
+}
+// 408 (timeout) and 429 (rate limit) are worth retrying; other 4xx are the
+// server telling us the operation itself is wrong.
+function isRetryableStatus(status) {
+    return status >= 500 || status === 408 || status === 429;
+}
+export class OfflineQueue {
+    baseUrl;
+    headers;
+    fetchImpl;
+    maxAttempts;
+    backoffMs;
+    idempotencyField;
+    storage;
+    operations = [];
+    listeners = new Set();
+    loaded;
+    flushing = false;
+    retryTimer;
+    onlineHandler = () => {
+        void this.flush();
+    };
+    constructor(options) {
+        this.baseUrl = options.baseUrl;
+        this.headers = options.headers;
+        this.fetchImpl = options.fetch;
+        this.maxAttempts = options.maxAttempts ?? 5;
+        this.backoffMs = options.backoffMs ?? 1000;
+        this.idempotencyField = options.idempotencyField ?? "idempotencyKey";
+        this.storage = options.storage ?? memoryStorage();
+        this.loaded = Promise.resolve(this.storage.load()).then((ops) => {
+            this.operations = ops;
+        });
+        const target = globalThis;
+        if ((options.autoFlush ?? true) && typeof target.addEventListener === "function") {
+            target.addEventListener("online", this.onlineHandler);
+        }
+    }
+    /** Stops timers and the online listener. */
+    dispose() {
+        if (this.retryTimer !== undefined)
+            clearTimeout(this.retryTimer);
+        const target = globalThis;
+        if (typeof target.removeEventListener === "function") {
+            target.removeEventListener("online", this.onlineHandler);
+        }
+    }
+    /**
+     * Enqueues an operation with an idempotency key stamped into the body.
+     * Resolves once the operation is durably queued — call `flush()` (or rely
+     * on the `online` listener / backoff timer) to deliver it.
+     */
+    async enqueue(path, body, opts) {
+        await this.loaded;
+        const id = opts?.idempotencyKey ?? generateId();
+        const operation = {
+            id,
+            path,
+            method: opts?.method ?? "POST",
+            body: { ...body, [this.idempotencyField]: id },
+            createdAt: new Date().toISOString(),
+            attempts: 0,
+            status: "pending",
+        };
+        this.operations.push(operation);
+        await this.persist();
+        return operation;
+    }
+    /** Current queue state (pending/failed counts + operations with errors). */
+    async state() {
+        await this.loaded;
+        return {
+            pending: this.operations.filter((op) => op.status === "pending").length,
+            failed: this.operations.filter((op) => op.status === "failed").length,
+            operations: [...this.operations],
+        };
+    }
+    /** Subscribe to state changes. Returns an unsubscribe function. */
+    onChange(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    /** Re-queues a failed operation for the next flush. */
+    async retry(id) {
+        await this.loaded;
+        const operation = this.operations.find((op) => op.id === id);
+        if (operation && operation.status === "failed") {
+            operation.status = "pending";
+            operation.attempts = 0;
+            operation.lastError = undefined;
+            await this.persist();
+            void this.flush();
+        }
+    }
+    /** Drops an operation from the queue entirely. */
+    async drop(id) {
+        await this.loaded;
+        this.operations = this.operations.filter((op) => op.id !== id);
+        await this.persist();
+    }
+    /**
+     * Drains pending operations FIFO. Network-level failures stop the drain
+     * (we're offline) and schedule a backoff retry; HTTP failures mark the
+     * operation failed (non-retryable) or retry it (5xx/408/429).
+     */
+    async flush() {
+        await this.loaded;
+        if (this.flushing)
+            return this.state();
+        this.flushing = true;
+        try {
+            const fetchImpl = this.fetchImpl ?? globalThis.fetch;
+            for (const operation of [...this.operations]) {
+                if (operation.status !== "pending")
+                    continue;
+                let response;
+                try {
+                    response = await fetchImpl(`${this.baseUrl}${operation.path}`, {
+                        method: operation.method,
+                        headers: { "content-type": "application/json", ...this.headers },
+                        body: JSON.stringify(operation.body),
+                    });
+                }
+                catch (error) {
+                    // Network down — keep everything pending and back off.
+                    operation.attempts += 1;
+                    operation.lastError = { message: error instanceof Error ? error.message : String(error) };
+                    await this.persist();
+                    this.scheduleRetry(operation.attempts);
+                    return this.state();
+                }
+                if (response.ok) {
+                    this.operations = this.operations.filter((op) => op.id !== operation.id);
+                    await this.persist();
+                    continue;
+                }
+                operation.attempts += 1;
+                let errorBody;
+                try {
+                    errorBody = await response.clone().json();
+                }
+                catch {
+                    errorBody = undefined;
+                }
+                operation.lastError = {
+                    status: response.status,
+                    body: errorBody,
+                    message: `HTTP ${response.status}`,
+                };
+                if (!isRetryableStatus(response.status) || operation.attempts >= this.maxAttempts) {
+                    operation.status = "failed";
+                }
+                else {
+                    this.scheduleRetry(operation.attempts);
+                }
+                await this.persist();
+            }
+            return this.state();
+        }
+        finally {
+            this.flushing = false;
+        }
+    }
+    scheduleRetry(attempts) {
+        if (this.retryTimer !== undefined)
+            clearTimeout(this.retryTimer);
+        const delay = Math.min(this.backoffMs * 2 ** (attempts - 1), 60_000);
+        this.retryTimer = setTimeout(() => {
+            this.retryTimer = undefined;
+            void this.flush();
+        }, delay);
+        // Never keep a Node.js process alive just for a queue retry.
+        this.retryTimer.unref?.();
+    }
+    async persist() {
+        await this.storage.save([...this.operations]);
+        const state = {
+            pending: this.operations.filter((op) => op.status === "pending").length,
+            failed: this.operations.filter((op) => op.status === "failed").length,
+            operations: [...this.operations],
+        };
+        for (const listener of this.listeners)
+            listener(state);
+    }
+}
+//# sourceMappingURL=offline-queue.js.map

package/dist/offline-queue.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@porulle/sdk",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "license": "MIT",
   "type": "module",
   "exports": {

package/src/index.ts

@@ -1,4 +1,13 @@
 export { createSDK, createClient, type SDKOptions } from "./client.js";
+export {
+  OfflineQueue,
+  memoryStorage,
+  webStorage,
+  type OfflineQueueOptions,
+  type QueuedOperation,
+  type QueueState,
+  type QueueStorage,
+} from "./offline-queue.js";
 export { authMiddleware, type AuthCredential, type ApiKeyAuth, type BearerAuth } from "./middleware.js";
 export {
   isApiError,

package/src/offline-queue.ts

@@ -0,0 +1,286 @@
+/**
+ * Offline-first operation queue (issue #54).
+ *
+ * POS clients must keep selling through network drops. This queue persists
+ * write operations (pluggable storage), stamps each with an idempotency key
+ * (core replays `POST /api/orders` / `POST /api/checkout` with the same key
+ * and returns the original order), and drains on reconnect with backoff.
+ * Queue state — pending/failed plus server error bodies — is observable, and
+ * failed operations support manual retry/drop.
+ */
+
+export interface QueuedOperation {
+  /** Unique id; also stamped into the body as `idempotencyKey`. */
+  id: string;
+  path: string;
+  method: "POST" | "PUT" | "PATCH" | "DELETE";
+  body: Record<string, unknown>;
+  createdAt: string;
+  attempts: number;
+  status: "pending" | "failed";
+  lastError?: { status?: number | undefined; body?: unknown; message: string } | undefined;
+}
+
+export interface QueueStorage {
+  load(): Promise<QueuedOperation[]> | QueuedOperation[];
+  save(operations: QueuedOperation[]): Promise<void> | void;
+}
+
+/** Volatile storage — tests and environments without persistence. */
+export function memoryStorage(): QueueStorage {
+  let operations: QueuedOperation[] = [];
+  return {
+    load: () => operations,
+    save: (next) => {
+      operations = next;
+    },
+  };
+}
+
+/** Storage backed by any localStorage-compatible object (web, RN shims). */
+export function webStorage(
+  storage: { getItem(key: string): string | null; setItem(key: string, value: string): void },
+  key = "porulle.offline-queue",
+): QueueStorage {
+  return {
+    load: () => {
+      try {
+        const raw = storage.getItem(key);
+        return raw ? (JSON.parse(raw) as QueuedOperation[]) : [];
+      } catch {
+        return [];
+      }
+    },
+    save: (operations) => {
+      storage.setItem(key, JSON.stringify(operations));
+    },
+  };
+}
+
+export interface OfflineQueueOptions {
+  /** Base URL of the commerce server (e.g. "https://api.example.com"). */
+  baseUrl: string;
+  /** Headers sent with every replayed request (e.g. Authorization). */
+  headers?: Record<string, string> | undefined;
+  /** Where operations persist. Default: in-memory. */
+  storage?: QueueStorage | undefined;
+  /** Custom fetch (testing, RN). Default: globalThis.fetch. */
+  fetch?: typeof globalThis.fetch | undefined;
+  /** Attempts before a retryable failure is marked `failed`. Default: 5. */
+  maxAttempts?: number | undefined;
+  /** Base backoff delay in ms (doubles per attempt, capped at 60s). Default: 1000. */
+  backoffMs?: number | undefined;
+  /** Listen for the window `online` event and auto-flush. Default: true when available. */
+  autoFlush?: boolean | undefined;
+  /** Field name stamped into the body. Default: "idempotencyKey". */
+  idempotencyField?: string | undefined;
+}
+
+export interface QueueState {
+  pending: number;
+  failed: number;
+  operations: QueuedOperation[];
+}
+
+type Listener = (state: QueueState) => void;
+
+function generateId(): string {
+  const cryptoObj = (globalThis as { crypto?: { randomUUID?: () => string } }).crypto;
+  if (cryptoObj?.randomUUID) return cryptoObj.randomUUID();
+  return `op_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`;
+}
+
+// 408 (timeout) and 429 (rate limit) are worth retrying; other 4xx are the
+// server telling us the operation itself is wrong.
+function isRetryableStatus(status: number): boolean {
+  return status >= 500 || status === 408 || status === 429;
+}
+
+export class OfflineQueue {
+  private readonly baseUrl: string;
+  private readonly headers: Record<string, string> | undefined;
+  private readonly fetchImpl: typeof globalThis.fetch | undefined;
+  private readonly maxAttempts: number;
+  private readonly backoffMs: number;
+  private readonly idempotencyField: string;
+  private readonly storage: QueueStorage;
+  private operations: QueuedOperation[] = [];
+  private listeners = new Set<Listener>();
+  private loaded: Promise<void>;
+  private flushing = false;
+  private retryTimer: ReturnType<typeof setTimeout> | undefined;
+  private readonly onlineHandler = () => {
+    void this.flush();
+  };
+
+  constructor(options: OfflineQueueOptions) {
+    this.baseUrl = options.baseUrl;
+    this.headers = options.headers;
+    this.fetchImpl = options.fetch;
+    this.maxAttempts = options.maxAttempts ?? 5;
+    this.backoffMs = options.backoffMs ?? 1000;
+    this.idempotencyField = options.idempotencyField ?? "idempotencyKey";
+    this.storage = options.storage ?? memoryStorage();
+    this.loaded = Promise.resolve(this.storage.load()).then((ops) => {
+      this.operations = ops;
+    });
+
+    const target = (globalThis as { addEventListener?: (t: string, h: () => void) => void });
+    if ((options.autoFlush ?? true) && typeof target.addEventListener === "function") {
+      target.addEventListener("online", this.onlineHandler);
+    }
+  }
+
+  /** Stops timers and the online listener. */
+  dispose(): void {
+    if (this.retryTimer !== undefined) clearTimeout(this.retryTimer);
+    const target = (globalThis as { removeEventListener?: (t: string, h: () => void) => void });
+    if (typeof target.removeEventListener === "function") {
+      target.removeEventListener("online", this.onlineHandler);
+    }
+  }
+
+  /**
+   * Enqueues an operation with an idempotency key stamped into the body.
+   * Resolves once the operation is durably queued — call `flush()` (or rely
+   * on the `online` listener / backoff timer) to deliver it.
+   */
+  async enqueue(
+    path: string,
+    body: Record<string, unknown>,
+    opts?: { method?: QueuedOperation["method"] | undefined; idempotencyKey?: string | undefined },
+  ): Promise<QueuedOperation> {
+    await this.loaded;
+    const id = opts?.idempotencyKey ?? generateId();
+    const operation: QueuedOperation = {
+      id,
+      path,
+      method: opts?.method ?? "POST",
+      body: { ...body, [this.idempotencyField]: id },
+      createdAt: new Date().toISOString(),
+      attempts: 0,
+      status: "pending",
+    };
+    this.operations.push(operation);
+    await this.persist();
+    return operation;
+  }
+
+  /** Current queue state (pending/failed counts + operations with errors). */
+  async state(): Promise<QueueState> {
+    await this.loaded;
+    return {
+      pending: this.operations.filter((op) => op.status === "pending").length,
+      failed: this.operations.filter((op) => op.status === "failed").length,
+      operations: [...this.operations],
+    };
+  }
+
+  /** Subscribe to state changes. Returns an unsubscribe function. */
+  onChange(listener: Listener): () => void {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+
+  /** Re-queues a failed operation for the next flush. */
+  async retry(id: string): Promise<void> {
+    await this.loaded;
+    const operation = this.operations.find((op) => op.id === id);
+    if (operation && operation.status === "failed") {
+      operation.status = "pending";
+      operation.attempts = 0;
+      operation.lastError = undefined;
+      await this.persist();
+      void this.flush();
+    }
+  }
+
+  /** Drops an operation from the queue entirely. */
+  async drop(id: string): Promise<void> {
+    await this.loaded;
+    this.operations = this.operations.filter((op) => op.id !== id);
+    await this.persist();
+  }
+
+  /**
+   * Drains pending operations FIFO. Network-level failures stop the drain
+   * (we're offline) and schedule a backoff retry; HTTP failures mark the
+   * operation failed (non-retryable) or retry it (5xx/408/429).
+   */
+  async flush(): Promise<QueueState> {
+    await this.loaded;
+    if (this.flushing) return this.state();
+    this.flushing = true;
+    try {
+      const fetchImpl = this.fetchImpl ?? globalThis.fetch;
+      for (const operation of [...this.operations]) {
+        if (operation.status !== "pending") continue;
+
+        let response: Response;
+        try {
+          response = await fetchImpl(`${this.baseUrl}${operation.path}`, {
+            method: operation.method,
+            headers: { "content-type": "application/json", ...this.headers },
+            body: JSON.stringify(operation.body),
+          });
+        } catch (error) {
+          // Network down — keep everything pending and back off.
+          operation.attempts += 1;
+          operation.lastError = { message: error instanceof Error ? error.message : String(error) };
+          await this.persist();
+          this.scheduleRetry(operation.attempts);
+          return this.state();
+        }
+
+        if (response.ok) {
+          this.operations = this.operations.filter((op) => op.id !== operation.id);
+          await this.persist();
+          continue;
+        }
+
+        operation.attempts += 1;
+        let errorBody: unknown;
+        try {
+          errorBody = await response.clone().json();
+        } catch {
+          errorBody = undefined;
+        }
+        operation.lastError = {
+          status: response.status,
+          body: errorBody,
+          message: `HTTP ${response.status}`,
+        };
+        if (!isRetryableStatus(response.status) || operation.attempts >= this.maxAttempts) {
+          operation.status = "failed";
+        } else {
+          this.scheduleRetry(operation.attempts);
+        }
+        await this.persist();
+      }
+      return this.state();
+    } finally {
+      this.flushing = false;
+    }
+  }
+
+  private scheduleRetry(attempts: number): void {
+    if (this.retryTimer !== undefined) clearTimeout(this.retryTimer);
+    const delay = Math.min(this.backoffMs * 2 ** (attempts - 1), 60_000);
+    this.retryTimer = setTimeout(() => {
+      this.retryTimer = undefined;
+      void this.flush();
+    }, delay);
+    // Never keep a Node.js process alive just for a queue retry.
+    (this.retryTimer as { unref?: () => void }).unref?.();
+  }
+
+  private async persist(): Promise<void> {
+    await this.storage.save([...this.operations]);
+    const state: QueueState = {
+      pending: this.operations.filter((op) => op.status === "pending").length,
+      failed: this.operations.filter((op) => op.status === "failed").length,
+      operations: [...this.operations],
+    };
+    for (const listener of this.listeners) listener(state);
+  }
+}