@guidelytech/sdk-core 0.9.0 → 0.10.0

package/dist/chunk-GDJB466J.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/queue.ts","../src/outbox.ts","../src/emitter.ts","../src/frequency.ts"],"sourcesContent":["import type { SdkEvent } from \"@guidelytech/shared\";\nimport type { ServerHealth } from \"./health\";\nimport { backoffMs } from \"./http\";\nimport { readJson, writeJson, type KeyValueStore } from \"./storage\";\n\nexport interface EventQueueOptions {\n  store: KeyValueStore;\n  storageKey: string;\n  /** Sends one batch. Resolve `{ ok: true }` on success, `{ ok: false, retry }` otherwise. */\n  send: (events: SdkEvent[]) => Promise<{ ok: boolean; retry?: boolean }>;\n  /** Synchronous best-effort send used on page hide. */\n  beacon?: (events: SdkEvent[]) => boolean;\n  /** Should events be flushed right now? (analytics enabled + consent granted). */\n  enabled: () => boolean;\n  /** API reachability: sends wait while its circuit is open, and beaconed events are only forgotten while it is reachable. */\n  health?: ServerHealth;\n  flushIntervalMs?: number;\n  maxQueue?: number;\n  batchSize?: number;\n  maxAttempts?: number;\n  onError?: (err: unknown) => void;\n}\n\n/**\n * Bounded, persisted event queue. Batches ≤50 events every 2s (or on demand), dedupes by\n * `eventId`, and keeps failed events (also across page loads) until the server takes them:\n * retries back off 1s→60s, wait while the API's circuit is open, and start again as soon as it\n * recovers. Drops the oldest events once the queue exceeds 500.\n */\nexport class EventQueue {\n  private events: SdkEvent[] = [];\n  private timer: ReturnType<typeof setTimeout> | null = null;\n  private retryTimer: ReturnType<typeof setTimeout> | null = null;\n  private inflight = false;\n  private inflightIds = new Set<string>();\n  private attempt = 0;\n  private destroyed = false;\n  private offRecover: (() => void) | null = null;\n  private readonly flushIntervalMs: number;\n  private readonly maxQueue: number;\n  private readonly batchSize: number;\n  private readonly maxAttempts: number;\n\n  constructor(private readonly opts: EventQueueOptions) {\n    this.flushIntervalMs = opts.flushIntervalMs ?? 2000;\n    this.maxQueue = opts.maxQueue ?? 500;\n    this.batchSize = opts.batchSize ?? 50;\n    this.maxAttempts = opts.maxAttempts ?? 5;\n    const persisted = readJson<SdkEvent[]>(opts.store, opts.storageKey, []);\n    if (Array.isArray(persisted)) this.events = persisted.filter((e) => e && typeof e.eventId === \"string\").slice(-this.maxQueue);\n    // Events left over from a previous page load are flushed on the next tick.\n    if (this.events.length) this.schedule();\n    this.offRecover = opts.health?.onRecover(() => this.retryNow()) ?? null;\n  }\n\n  /** The API is back: drop any pending backoff and send what is queued. */\n  private retryNow(): void {\n    if (this.destroyed) return;\n    if (this.retryTimer) clearTimeout(this.retryTimer);\n    this.retryTimer = null;\n    this.attempt = 0;\n    void this.flush();\n  }\n\n  private retryIn(ms: number): void {\n    if (this.retryTimer || this.destroyed) return;\n    this.retryTimer = setTimeout(() => {\n      this.retryTimer = null;\n      void this.flush();\n    }, ms);\n  }\n\n  get size(): number {\n    return this.events.length;\n  }\n\n  /** Pending events (read-only copy, for debugging). */\n  peek(): SdkEvent[] {\n    return this.events.slice();\n  }\n\n  enqueue(event: SdkEvent): void {\n    if (this.destroyed) return;\n    if (this.events.some((e) => e.eventId === event.eventId)) return;\n    this.events.push(event);\n    if (this.events.length > this.maxQueue) this.events.splice(0, this.events.length - this.maxQueue);\n    this.persist();\n    this.schedule();\n  }\n\n  private persist(): void {\n    writeJson(this.opts.store, this.opts.storageKey, this.events);\n  }\n\n  private schedule(): void {\n    if (this.timer || this.retryTimer || this.destroyed) return;\n    this.timer = setTimeout(() => {\n      this.timer = null;\n      void this.flush();\n    }, this.flushIntervalMs);\n  }\n\n  /** Sends queued events now (one batch at a time). Safe to call at any time. */\n  async flush(): Promise<void> {\n    if (this.destroyed || this.inflight || !this.events.length || !this.opts.enabled()) return;\n    if (this.timer) {\n      clearTimeout(this.timer);\n      this.timer = null;\n    }\n    const wait = this.opts.health?.waitMs() ?? 0;\n    if (wait > 0) return this.retryIn(wait);\n    this.inflight = true;\n    const batch = this.events.slice(0, this.batchSize);\n    this.inflightIds = new Set(batch.map((e) => e.eventId));\n    let ok = false;\n    let retry = true;\n    try {\n      const res = await this.opts.send(batch);\n      ok = res.ok;\n      retry = res.retry ?? !res.ok;\n    } catch (err) {\n      this.opts.onError?.(err);\n    }\n    this.inflight = false;\n    this.inflightIds.clear();\n    if (this.destroyed) return;\n    if (ok || !retry) {\n      const ids = new Set(batch.map((e) => e.eventId));\n      this.events = this.events.filter((e) => !ids.has(e.eventId));\n      this.attempt = 0;\n      this.persist();\n      if (this.events.length) this.schedule();\n      return;\n    }\n    // Fast retries first, then about once a minute until the server takes the events (or the\n    // API's circuit says to wait longer); a recovery or the next page load sends them sooner.\n    this.attempt = Math.min(this.attempt + 1, this.maxAttempts);\n    const delay = this.attempt >= this.maxAttempts ? 60_000 : backoffMs(this.attempt - 1);\n    this.retryIn(Math.max(delay, this.opts.health?.waitMs() ?? 0));\n  }\n\n  /** Best-effort synchronous flush on unload using `sendBeacon`. */\n  flushSync(): void {\n    if (this.destroyed || !this.opts.enabled() || !this.opts.beacon) return;\n    // Events already in flight (fetch with keepalive) survive unload; only beacon the rest to avoid duplicate batches.\n    const batch = this.events.filter((e) => !this.inflightIds.has(e.eventId)).slice(0, this.batchSize);\n    if (!batch.length) return;\n    // A beacon that was queued may still never arrive (the server is down), and nothing reports\n    // back. Only forget its events while the API is answering; otherwise they stay persisted and the\n    // next page load sends them again (the server drops events it already has, by eventId).\n    if (this.opts.beacon(batch) && (this.opts.health?.reachable ?? true)) {\n      const ids = new Set(batch.map((e) => e.eventId));\n      this.events = this.events.filter((e) => !ids.has(e.eventId));\n    }\n    this.persist();\n  }\n\n  clear(): void {\n    this.events = [];\n    this.persist();\n  }\n\n  destroy(): void {\n    this.destroyed = true;\n    this.offRecover?.();\n    if (this.timer) clearTimeout(this.timer);\n    if (this.retryTimer) clearTimeout(this.retryTimer);\n    this.timer = null;\n    this.retryTimer = null;\n    this.persist();\n  }\n}\n","import type { ServerHealth } from \"./health\";\nimport { backoffMs, type Api } from \"./http\";\nimport { readJson, writeJson, type KeyValueStore } from \"./storage\";\n\n/** One request waiting to reach the server. */\ninterface OutboxItem {\n  /** Same key → the newer request replaces the older one (e.g. a checklist's latest progress). */\n  key: string;\n  path: string;\n  body: unknown;\n  createdAt: number;\n}\n\nexport interface OutboxOptions {\n  api: Api;\n  store: KeyValueStore;\n  storageKey: string;\n  health?: ServerHealth;\n  maxItems?: number;\n  maxAgeMs?: number;\n  onError?: (err: unknown) => void;\n}\n\n/**\n * Persisted queue for writes that must not be lost when the API is down: survey answers, guide\n * completions and checklist progress. Each request is kept (also across page loads) until the\n * server answers it; 5xx, 429 and network errors are retried with backoff, waiting while the API's\n * circuit is open. Every request is idempotent on the server (survey answers dedupe by\n * `responseId`, progress merges), so sending one twice is harmless. Bounded to 50 requests and 7 days.\n */\nexport class Outbox {\n  private items: OutboxItem[];\n  private sending = false;\n  private attempt = 0;\n  private timer: ReturnType<typeof setTimeout> | null = null;\n  private destroyed = false;\n  private readonly offRecover: (() => void) | null;\n  private readonly maxItems: number;\n  private readonly maxAgeMs: number;\n\n  constructor(private readonly opts: OutboxOptions) {\n    this.maxItems = opts.maxItems ?? 50;\n    this.maxAgeMs = opts.maxAgeMs ?? 7 * 24 * 60 * 60 * 1000;\n    const stored = readJson<OutboxItem[]>(opts.store, opts.storageKey, []);\n    const cutoff = Date.now() - this.maxAgeMs;\n    this.items = Array.isArray(stored) ? stored.filter((i) => i && typeof i.path === \"string\" && typeof i.key === \"string\" && i.createdAt > cutoff).slice(-this.maxItems) : [];\n    this.offRecover = opts.health?.onRecover(() => {\n      this.attempt = 0;\n      this.retryIn(0);\n    }) ?? null;\n    if (this.items.length) this.retryIn(0);\n  }\n\n  get size(): number {\n    return this.items.length;\n  }\n\n  /** Queues `POST path` and sends it now (or as soon as the API is reachable). */\n  add(key: string, path: string, body: unknown): void {\n    if (this.destroyed) return;\n    this.items = this.items.filter((i) => i.key !== key);\n    this.items.push({ key, path, body, createdAt: Date.now() });\n    if (this.items.length > this.maxItems) this.items.splice(0, this.items.length - this.maxItems);\n    this.persist();\n    void this.flush();\n  }\n\n  private persist(): void {\n    writeJson(this.opts.store, this.opts.storageKey, this.items);\n  }\n\n  private retryIn(ms: number): void {\n    if (this.destroyed) return;\n    if (this.timer) clearTimeout(this.timer);\n    this.timer = setTimeout(() => {\n      this.timer = null;\n      void this.flush();\n    }, ms);\n  }\n\n  /** Sends queued requests in order, one at a time. */\n  async flush(): Promise<void> {\n    if (this.destroyed || this.sending || !this.items.length) return;\n    const wait = this.opts.health?.waitMs() ?? 0;\n    if (wait > 0) return this.retryIn(wait);\n    this.sending = true;\n    try {\n      while (this.items.length && !this.destroyed) {\n        const item = this.items[0] as OutboxItem;\n        let retry = false;\n        try {\n          const res = await this.opts.api.post(item.path, item.body);\n          retry = !res.ok && (res.status === 429 || res.status >= 500);\n        } catch (err) {\n          retry = true;\n          this.opts.onError?.(err);\n        }\n        if (retry) {\n          this.attempt += 1;\n          this.retryIn(Math.max(backoffMs(this.attempt - 1, 1000, 60_000), this.opts.health?.waitMs() ?? 0));\n          return;\n        }\n        // Answered (or refused for good, e.g. the survey was deleted): done with it. A newer request\n        // under the same key may have replaced it while this one was in flight; keep that one.\n        this.attempt = 0;\n        this.items = this.items.filter((i) => i !== item);\n        this.persist();\n      }\n    } finally {\n      this.sending = false;\n    }\n  }\n\n  destroy(): void {\n    this.destroyed = true;\n    this.offRecover?.();\n    if (this.timer) clearTimeout(this.timer);\n    this.timer = null;\n  }\n}\n","type AnyFn = (...args: any[]) => void;\n\n/** Tiny typed event emitter. Listener errors are reported, never thrown into the caller. */\nexport class Emitter<Events extends { [K in keyof Events]: AnyFn }> {\n  private listeners = new Map<keyof Events, Set<AnyFn>>();\n  constructor(private readonly onError?: (err: unknown) => void) {}\n\n  on<K extends keyof Events>(event: K, cb: Events[K]): () => void {\n    let set = this.listeners.get(event);\n    if (!set) {\n      set = new Set();\n      this.listeners.set(event, set);\n    }\n    set.add(cb);\n    return () => this.off(event, cb);\n  }\n\n  off<K extends keyof Events>(event: K, cb: Events[K]): void {\n    this.listeners.get(event)?.delete(cb);\n  }\n\n  emit<K extends keyof Events>(event: K, ...args: Parameters<Events[K]>): void {\n    const set = this.listeners.get(event);\n    if (!set) return;\n    for (const cb of Array.from(set)) {\n      try {\n        cb(...args);\n      } catch (err) {\n        this.onError?.(err);\n      }\n    }\n  }\n\n  clear(): void {\n    this.listeners.clear();\n  }\n}\n","import type { FrequencyConfig, PublishedGuide } from \"@guidelytech/shared\";\n\n/** Per-guide state kept locally and merged with the server's `IdentifyResponse.guideState`. */\nexport interface GuideLocalState {\n  impressions: number;\n  completedAt?: string | null;\n  dismissedAt?: string | null;\n  lastShownAt?: string | null;\n  /** Last step reached in a multi-step flow (local only), so the messenger can offer to resume it. */\n  lastStepId?: string | null;\n}\n\nconst HOUR = 3600 * 1000;\n\n/**\n * Pure frequency evaluation. `shownThisSession` comes from session storage.\n * - `once`: a single impression ever (unless `reshowAfterDismiss` and it was only dismissed).\n * - `once_per_session`: at most once per browser session.\n * - `every_time`: on every trigger (still blocked by completion/dismissal rules below).\n * - `interval`: at most once every `intervalHours`.\n * `maxImpressions` caps total impressions; dismissal blocks re-showing unless `reshowAfterDismiss`\n * (then `cooldownHours` must have elapsed); completion blocks unless mode is `every_time`.\n */\nexport function isFrequencyEligible(freq: FrequencyConfig, state: GuideLocalState | undefined, shownThisSession: boolean, now: number = Date.now()): boolean {\n  const s = state ?? { impressions: 0 };\n  if (freq.maxImpressions != null && s.impressions >= freq.maxImpressions) return false;\n  if (s.completedAt && freq.mode !== \"every_time\") return false;\n  if (s.dismissedAt) {\n    if (!freq.reshowAfterDismiss) return false;\n    if (freq.cooldownHours > 0 && now - Date.parse(s.dismissedAt) < freq.cooldownHours * HOUR) return false;\n  }\n  switch (freq.mode) {\n    case \"once\":\n      return s.impressions === 0 || (!!s.dismissedAt && freq.reshowAfterDismiss);\n    case \"once_per_session\":\n      return !shownThisSession;\n    case \"interval\": {\n      if (!s.lastShownAt) return true;\n      const hours = freq.intervalHours ?? 24;\n      return now - Date.parse(s.lastShownAt) >= hours * HOUR;\n    }\n    case \"every_time\":\n    default:\n      return true;\n  }\n}\n\n/**\n * Exclusive guides (flows, modals, tooltips, announcements, surveys) run one at a time.\n * Banners, checklists and hotspot-only tooltips can coexist with an active flow.\n */\nexport function isExclusiveGuide(guide: PublishedGuide): boolean {\n  if (guide.kind === \"banner\" || guide.kind === \"checklist\") return false;\n  const steps = guide.config.steps;\n  if (steps.length > 0 && steps.every((s) => s.type === \"hotspot\" || s.type === \"banner\")) return false;\n  return true;\n}\n\n/** Is `a` mutually exclusive with `b` (by id or key, in either direction)? */\nexport function areMutuallyExclusive(a: PublishedGuide, b: PublishedGuide): boolean {\n  const la = a.config.frequency.mutuallyExclusiveWith;\n  const lb = b.config.frequency.mutuallyExclusiveWith;\n  return la.includes(b.id) || la.includes(b.key) || lb.includes(a.id) || lb.includes(a.key);\n}\n\n/** Survey scheduling window. */\nexport function isWithinSchedule(guide: PublishedGuide, now: number = Date.now()): boolean {\n  const s = guide.config.survey;\n  if (!s) return true;\n  if (s.startAt && now < Date.parse(s.startAt)) return false;\n  if (s.endAt && now > Date.parse(s.endAt)) return false;\n  return true;\n}\n\n/**\n * A checklist's dismissal after merging server state. A local dismissal normally wins (it may not have\n * synced yet), but when the server reports a reset this device hasn't applied, the server's value wins:\n * null, or a dismissal made on another device after the reset. Compared as tokens, not times, so a\n * skewed device clock can't keep a reset dismissal.\n */\nexport function dismissedAfterMerge(local: { dismissedAt?: string | null; dismissResetAt?: string | null } | undefined, server: { dismissedAt?: string | null; dismissResetAt?: string | null }): string | null {\n  if (server.dismissResetAt && server.dismissResetAt !== local?.dismissResetAt) return server.dismissedAt ?? null;\n  return local?.dismissedAt ?? server.dismissedAt ?? null;\n}\n"],"mappings":"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","names":[]}

package/dist/headless.cjs

@@ -26,13 +26,17 @@ __export(headless_exports, {
   Emitter: () => Emitter,
   EventQueue: () => EventQueue,
   KEYS: () => KEYS,
+  Outbox: () => Outbox,
+  ServerHealth: () => ServerHealth,
   areMutuallyExclusive: () => areMutuallyExclusive,
   backoffMs: () => backoffMs,
   dismissedAfterMerge: () => dismissedAfterMerge,
   isExclusiveGuide: () => isExclusiveGuide,
   isFrequencyEligible: () => isFrequencyEligible,
+  isServerFailure: () => isServerFailure,
   isWithinSchedule: () => isWithinSchedule,
   memoryStore: () => memoryStore,
+  parseRetryAfter: () => parseRetryAfter,
   postWithRetry: () => postWithRetry,
   readJson: () => readJson,
   sleep: () => sleep,
@@ -40,12 +44,108 @@ __export(headless_exports, {
 });
 module.exports = __toCommonJS(headless_exports);
 
+// src/health.ts
+var MAX_RETRY_AFTER_MS = 60 * 60 * 1e3;
+var OFFLINE_WAIT_MS = 3e4;
+var ServerHealth = class {
+  constructor(opts = {}) {
+    __publicField(this, "failures", 0);
+    __publicField(this, "openUntil", 0);
+    __publicField(this, "lastOkAt", 0);
+    __publicField(this, "listeners", /* @__PURE__ */ new Set());
+    __publicField(this, "threshold");
+    __publicField(this, "baseMs");
+    __publicField(this, "maxMs");
+    __publicField(this, "now");
+    __publicField(this, "random");
+    this.threshold = opts.threshold ?? 3;
+    this.baseMs = opts.baseMs ?? 5e3;
+    this.maxMs = opts.maxMs ?? 5 * 60 * 1e3;
+    this.now = opts.now ?? Date.now;
+    this.random = opts.random ?? Math.random;
+  }
+  /** The server answered (2xx, 3xx, or a 4xx other than 429): it is up. */
+  success() {
+    const wasDown = this.failures > 0 || this.openUntil > 0;
+    this.failures = 0;
+    this.openUntil = 0;
+    this.lastOkAt = this.now();
+    if (wasDown) this.notify();
+  }
+  /** The request failed or the server is overloaded. `retryAfterMs` comes from a `Retry-After` header. */
+  failure(retryAfterMs) {
+    this.failures += 1;
+    const now = this.now();
+    if (retryAfterMs != null && retryAfterMs > 0) {
+      this.openUntil = Math.max(this.openUntil, now + Math.min(retryAfterMs, MAX_RETRY_AFTER_MS));
+      return;
+    }
+    if (this.failures < this.threshold) return;
+    const cooldown = Math.min(this.maxMs, this.baseMs * 2 ** (this.failures - this.threshold));
+    this.openUntil = Math.max(this.openUntil, now + cooldown * (0.8 + this.random() * 0.4));
+  }
+  /** Milliseconds background traffic should wait before trying again (0: send now). */
+  waitMs() {
+    if (typeof navigator !== "undefined" && navigator.onLine === false) return OFFLINE_WAIT_MS;
+    return Math.max(0, this.openUntil - this.now());
+  }
+  canSend() {
+    return this.waitMs() === 0;
+  }
+  /**
+   * The last request got an answer. Unload beacons can't report back, so what they carry is only
+   * forgotten while this holds; otherwise it stays queued and is sent again (the server drops duplicates).
+   */
+  get reachable() {
+    return this.failures === 0 && this.lastOkAt > 0;
+  }
+  /** The browser came back online: end the cooldown and let queued traffic try straight away. */
+  online() {
+    this.openUntil = 0;
+    this.notify();
+  }
+  /** Called when the server answers again after failures, or the browser comes back online. */
+  onRecover(cb) {
+    this.listeners.add(cb);
+    return () => this.listeners.delete(cb);
+  }
+  notify() {
+    for (const cb of Array.from(this.listeners)) {
+      try {
+        cb();
+      } catch {
+      }
+    }
+  }
+};
+function parseRetryAfter(value, now = Date.now()) {
+  if (!value) return null;
+  const trimmed = value.trim();
+  if (/^\d+$/.test(trimmed)) return Number(trimmed) * 1e3;
+  const at = Date.parse(trimmed);
+  return Number.isNaN(at) ? null : Math.max(0, at - now);
+}
+function isServerFailure(status) {
+  return status === 429 || status >= 500;
+}
+
 // src/http.ts
+var STREAM_RESPONSE_TIMEOUT_MS = 3e4;
+var STREAM_IDLE_TIMEOUT_MS = 6e4;
 var Api = class {
-  constructor(baseUrl, key, fetchImpl) {
+  constructor(baseUrl, key, fetchImpl, health) {
     __publicField(this, "baseUrl", baseUrl);
     __publicField(this, "key", key);
     __publicField(this, "fetchImpl", fetchImpl);
+    /** Reachability of the API, fed by every answer (see {@link ServerHealth}). */
+    __publicField(this, "health");
+    this.health = health ?? new ServerHealth();
+  }
+  /** Feeds an answer (or a failed request, `null`) into {@link health}. */
+  observe(res) {
+    if (!res) this.health.failure();
+    else if (isServerFailure(res.status)) this.health.failure(parseRetryAfter(res.headers?.get?.("retry-after")));
+    else this.health.success();
   }
   url(path, params = {}) {
     const query = Object.entries({ key: this.key, ...params }).filter((e) => e[1] != null).map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`).join("&");
@@ -65,15 +165,22 @@ var Api = class {
     const ac = typeof AbortController !== "undefined" ? new AbortController() : null;
     const timer = ac ? setTimeout(() => ac.abort(), options.timeoutMs ?? 1e4) : null;
     try {
-      const res = await f(this.url(path, options.params), {
-        method,
-        headers,
-        body: options.body === void 0 ? void 0 : form ? options.body : JSON.stringify(options.body),
-        keepalive: options.keepalive,
-        signal: ac?.signal,
-        credentials: "omit",
-        mode: "cors"
-      });
+      let res;
+      try {
+        res = await f(this.url(path, options.params), {
+          method,
+          headers,
+          body: options.body === void 0 ? void 0 : form ? options.body : JSON.stringify(options.body),
+          keepalive: options.keepalive,
+          signal: ac?.signal,
+          credentials: "omit",
+          mode: "cors"
+        });
+      } catch (err) {
+        this.observe(null);
+        throw err;
+      }
+      this.observe(res);
       let data = null;
       if (res.status !== 304 && res.status !== 204) {
         try {
@@ -99,30 +206,53 @@ var Api = class {
   }
   /**
    * POST that may answer with server-sent events. Each event is passed to `onEvent`; a JSON answer is
-   * returned instead. No timeout: Scout replies can take a while and the server keeps the stream alive.
+   * returned instead. Scout replies can take a while, so there is no overall timeout: the response
+   * must start within 30 s and then never go quiet for more than 60 s (the server sends keepalives),
+   * otherwise the request is aborted and rejects.
    */
   async stream(path, body, onEvent, headers = {}) {
     const f = this.fetcher;
     if (!f) throw new Error("fetch is not available");
-    const res = await f(this.url(path), {
-      method: "POST",
-      headers: { ...headers, "X-Guidely-Key": this.key, Accept: "text/event-stream, application/json", "Content-Type": "application/json" },
-      body: JSON.stringify(body),
-      credentials: "omit",
-      mode: "cors"
-    });
-    const type = res.headers?.get?.("content-type") ?? "";
-    if (!type.includes("text/event-stream") || !res.body) {
-      let data = null;
+    const ac = typeof AbortController !== "undefined" ? new AbortController() : null;
+    let timer = null;
+    const arm = (ms) => {
+      if (!ac) return;
+      if (timer) clearTimeout(timer);
+      timer = setTimeout(() => ac.abort(), ms);
+    };
+    arm(STREAM_RESPONSE_TIMEOUT_MS);
+    try {
+      let res;
       try {
-        data = await res.json();
-      } catch {
-        data = null;
+        res = await f(this.url(path), {
+          method: "POST",
+          headers: { ...headers, "X-Guidely-Key": this.key, Accept: "text/event-stream, application/json", "Content-Type": "application/json" },
+          body: JSON.stringify(body),
+          signal: ac?.signal,
+          credentials: "omit",
+          mode: "cors"
+        });
+      } catch (err) {
+        this.observe(null);
+        throw err;
       }
-      return { status: res.status, ok: res.ok, data, etag: null };
+      this.observe(res);
+      const type = res.headers?.get?.("content-type") ?? "";
+      if (!type.includes("text/event-stream") || !res.body) {
+        let data = null;
+        try {
+          data = await res.json();
+        } catch {
+          data = null;
+        }
+        return { status: res.status, ok: res.ok, data, etag: null };
+      }
+      arm(STREAM_IDLE_TIMEOUT_MS);
+      await readEventStream(res.body, onEvent, () => arm(STREAM_IDLE_TIMEOUT_MS));
+      return { status: res.status, ok: res.ok, data: null, etag: null };
+    } finally {
+      if (timer) clearTimeout(timer);
     }
-    await readEventStream(res.body, onEvent);
-    return { status: res.status, ok: res.ok, data: null, etag: null };
   }
   /** `navigator.sendBeacon` when available (page unload); returns false when it could not be queued. */
   beacon(path, body) {
@@ -153,7 +283,7 @@ async function withRetry(send, attempts = 3, baseMs = 500) {
 function postWithRetry(api, path, body, attempts = 3, baseMs = 500) {
   return withRetry(() => api.post(path, body), attempts, baseMs);
 }
-async function readEventStream(body, onEvent) {
+async function readEventStream(body, onEvent, onChunk) {
   const reader = body.getReader();
   const decoder = new TextDecoder();
   let buffer = "";
@@ -176,6 +306,7 @@ async function readEventStream(body, onEvent) {
   };
   for (; ; ) {
     const { done, value } = await reader.read();
+    if (value) onChunk?.();
     if (value) buffer += decoder.decode(value, { stream: true }).replace(/\r\n?/g, "\n");
     let sep;
     while ((sep = buffer.indexOf("\n\n")) >= 0) {
@@ -215,6 +346,8 @@ var KEYS = {
   state: (key) => `guidely:state:${key}`,
   user: (key) => `guidely:user:${key}`,
   queue: (key) => `guidely:queue:${key}`,
+  /** Survey answers and guide/checklist progress not yet accepted by the server. */
+  outbox: (key) => `guidely:outbox:${key}`,
   session: "guidely:session",
   active: "guidely:active",
   authoring: "guidely:authoring",
@@ -238,17 +371,34 @@ var EventQueue = class {
     __publicField(this, "inflightIds", /* @__PURE__ */ new Set());
     __publicField(this, "attempt", 0);
     __publicField(this, "destroyed", false);
+    __publicField(this, "offRecover", null);
     __publicField(this, "flushIntervalMs");
     __publicField(this, "maxQueue");
     __publicField(this, "batchSize");
     __publicField(this, "maxAttempts");
     this.flushIntervalMs = opts.flushIntervalMs ?? 2e3;
-    this.maxQueue = opts.maxQueue ?? 200;
+    this.maxQueue = opts.maxQueue ?? 500;
     this.batchSize = opts.batchSize ?? 50;
     this.maxAttempts = opts.maxAttempts ?? 5;
     const persisted = readJson(opts.store, opts.storageKey, []);
     if (Array.isArray(persisted)) this.events = persisted.filter((e) => e && typeof e.eventId === "string").slice(-this.maxQueue);
     if (this.events.length) this.schedule();
+    this.offRecover = opts.health?.onRecover(() => this.retryNow()) ?? null;
+  }
+  /** The API is back: drop any pending backoff and send what is queued. */
+  retryNow() {
+    if (this.destroyed) return;
+    if (this.retryTimer) clearTimeout(this.retryTimer);
+    this.retryTimer = null;
+    this.attempt = 0;
+    void this.flush();
+  }
+  retryIn(ms) {
+    if (this.retryTimer || this.destroyed) return;
+    this.retryTimer = setTimeout(() => {
+      this.retryTimer = null;
+      void this.flush();
+    }, ms);
   }
   get size() {
     return this.events.length;
@@ -282,6 +432,8 @@ var EventQueue = class {
       clearTimeout(this.timer);
       this.timer = null;
     }
+    const wait = this.opts.health?.waitMs() ?? 0;
+    if (wait > 0) return this.retryIn(wait);
     this.inflight = true;
     const batch = this.events.slice(0, this.batchSize);
     this.inflightIds = new Set(batch.map((e) => e.eventId));
@@ -305,26 +457,20 @@ var EventQueue = class {
       if (this.events.length) this.schedule();
       return;
     }
-    this.attempt += 1;
-    if (this.attempt >= this.maxAttempts) {
-      this.attempt = 0;
-      return;
-    }
-    this.retryTimer = setTimeout(() => {
-      this.retryTimer = null;
-      void this.flush();
-    }, backoffMs(this.attempt - 1));
+    this.attempt = Math.min(this.attempt + 1, this.maxAttempts);
+    const delay = this.attempt >= this.maxAttempts ? 6e4 : backoffMs(this.attempt - 1);
+    this.retryIn(Math.max(delay, this.opts.health?.waitMs() ?? 0));
   }
   /** Best-effort synchronous flush on unload using `sendBeacon`. */
   flushSync() {
     if (this.destroyed || !this.opts.enabled() || !this.opts.beacon) return;
     const batch = this.events.filter((e) => !this.inflightIds.has(e.eventId)).slice(0, this.batchSize);
     if (!batch.length) return;
-    if (this.opts.beacon(batch)) {
+    if (this.opts.beacon(batch) && (this.opts.health?.reachable ?? true)) {
       const ids = new Set(batch.map((e) => e.eventId));
       this.events = this.events.filter((e) => !ids.has(e.eventId));
-      this.persist();
     }
+    this.persist();
   }
   clear() {
     this.events = [];
@@ -332,6 +478,7 @@ var EventQueue = class {
   }
   destroy() {
     this.destroyed = true;
+    this.offRecover?.();
     if (this.timer) clearTimeout(this.timer);
     if (this.retryTimer) clearTimeout(this.retryTimer);
     this.timer = null;
@@ -340,6 +487,90 @@ var EventQueue = class {
   }
 };
 
+// src/outbox.ts
+var Outbox = class {
+  constructor(opts) {
+    __publicField(this, "opts", opts);
+    __publicField(this, "items");
+    __publicField(this, "sending", false);
+    __publicField(this, "attempt", 0);
+    __publicField(this, "timer", null);
+    __publicField(this, "destroyed", false);
+    __publicField(this, "offRecover");
+    __publicField(this, "maxItems");
+    __publicField(this, "maxAgeMs");
+    this.maxItems = opts.maxItems ?? 50;
+    this.maxAgeMs = opts.maxAgeMs ?? 7 * 24 * 60 * 60 * 1e3;
+    const stored = readJson(opts.store, opts.storageKey, []);
+    const cutoff = Date.now() - this.maxAgeMs;
+    this.items = Array.isArray(stored) ? stored.filter((i) => i && typeof i.path === "string" && typeof i.key === "string" && i.createdAt > cutoff).slice(-this.maxItems) : [];
+    this.offRecover = opts.health?.onRecover(() => {
+      this.attempt = 0;
+      this.retryIn(0);
+    }) ?? null;
+    if (this.items.length) this.retryIn(0);
+  }
+  get size() {
+    return this.items.length;
+  }
+  /** Queues `POST path` and sends it now (or as soon as the API is reachable). */
+  add(key, path, body) {
+    if (this.destroyed) return;
+    this.items = this.items.filter((i) => i.key !== key);
+    this.items.push({ key, path, body, createdAt: Date.now() });
+    if (this.items.length > this.maxItems) this.items.splice(0, this.items.length - this.maxItems);
+    this.persist();
+    void this.flush();
+  }
+  persist() {
+    writeJson(this.opts.store, this.opts.storageKey, this.items);
+  }
+  retryIn(ms) {
+    if (this.destroyed) return;
+    if (this.timer) clearTimeout(this.timer);
+    this.timer = setTimeout(() => {
+      this.timer = null;
+      void this.flush();
+    }, ms);
+  }
+  /** Sends queued requests in order, one at a time. */
+  async flush() {
+    if (this.destroyed || this.sending || !this.items.length) return;
+    const wait = this.opts.health?.waitMs() ?? 0;
+    if (wait > 0) return this.retryIn(wait);
+    this.sending = true;
+    try {
+      while (this.items.length && !this.destroyed) {
+        const item = this.items[0];
+        let retry = false;
+        try {
+          const res = await this.opts.api.post(item.path, item.body);
+          retry = !res.ok && (res.status === 429 || res.status >= 500);
+        } catch (err) {
+          retry = true;
+          this.opts.onError?.(err);
+        }
+        if (retry) {
+          this.attempt += 1;
+          this.retryIn(Math.max(backoffMs(this.attempt - 1, 1e3, 6e4), this.opts.health?.waitMs() ?? 0));
+          return;
+        }
+        this.attempt = 0;
+        this.items = this.items.filter((i) => i !== item);
+        this.persist();
+      }
+    } finally {
+      this.sending = false;
+    }
+  }
+  destroy() {
+    this.destroyed = true;
+    this.offRecover?.();
+    if (this.timer) clearTimeout(this.timer);
+    this.timer = null;
+  }
+};
+
 // src/emitter.ts
 var Emitter = class {
   constructor(onError) {
@@ -427,13 +658,17 @@ function dismissedAfterMerge(local, server) {
   Emitter,
   EventQueue,
   KEYS,
+  Outbox,
+  ServerHealth,
   areMutuallyExclusive,
   backoffMs,
   dismissedAfterMerge,
   isExclusiveGuide,
   isFrequencyEligible,
+  isServerFailure,
   isWithinSchedule,
   memoryStore,
+  parseRetryAfter,
   postWithRetry,
   readJson,
   sleep,