@cross-deck/web 1.7.0 → 1.9.0

package/dist/error-codes.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "generatedAt": "2026-06-10T12:59:26.148Z",
+  "generatedAt": "2026-06-24T10:42:10.345Z",
   "sdk": "@cross-deck/web",
   "codes": [
     {
@@ -191,6 +191,13 @@
       "description": "A field is present but the value failed validation (wrong shape, wrong length, wrong enum value).",
       "resolution": "Read error.message for the specific field + reason. SDK-managed call sites should never emit this — file a bug if you do.",
       "retryable": false
+    },
+    {
+      "code": "sdk_version_unsupported",
+      "type": "version_error",
+      "description": "HTTP 426 — your installed SDK sends an event format the server no longer accepts. The data is good; only the wire dialect is too old. The SDK PARKS automatically: events are held on-device (paused, not lost) and deliver on the next launch after you upgrade.",
+      "resolution": "Update @cross-deck/web to at least the version in error.minVersion and redeploy — the parked queue backfills automatically. See https://cross-deck.com/docs/sdk-event-durability/.",
+      "retryable": false
     }
   ]
 }

package/dist/index.cjs

@@ -43,6 +43,8 @@ var CrossdeckError = class _CrossdeckError extends Error {
     this.requestId = payload.requestId;
     this.status = payload.status;
     this.retryAfterMs = payload.retryAfterMs;
+    this.minVersion = payload.minVersion;
+    this.surface = payload.surface;
     Object.setPrototypeOf(this, _CrossdeckError.prototype);
   }
 };
@@ -63,7 +65,10 @@ async function crossdeckErrorFromResponse(res) {
       message: envelope.message ?? `HTTP ${res.status}`,
       requestId: envelope.request_id ?? requestId,
       status: res.status,
-      retryAfterMs
+      retryAfterMs,
+      // PARK metadata, present only on a 426 / sdk_version_unsupported body.
+      minVersion: typeof envelope.minVersion === "string" ? envelope.minVersion : void 0,
+      surface: typeof envelope.surface === "string" ? envelope.surface : void 0
     });
   }
   return new CrossdeckError({
@@ -99,7 +104,7 @@ function typeMapForStatus(status) {
 }
 
 // src/_version.ts
-var SDK_VERSION = "1.7.0";
+var SDK_VERSION = "1.9.0";
 var SDK_NAME = "@cross-deck/web";
 
 // src/http.ts
@@ -939,6 +944,18 @@ var EventQueue = class {
     this.cancelTimer = null;
     this.firstFlushFired = false;
     this.nextRetryAt = null;
+    /**
+     * PARK state (HTTP 426 / `sdk_version_unsupported`). Once parked, the
+     * queue stops flushing — the server has told us our wire dialect is too
+     * old, and retrying the same payload only burns the user's battery and
+     * bandwidth and drips pointless rejects into the server logs until the
+     * app ships an upgraded SDK. The held events stay durable (persisted)
+     * and are delivered by the next boot's rehydrate, post-upgrade. Parked
+     * is per-instance: a fresh boot (the upgraded build) starts unparked.
+     */
+    this.parked = false;
+    /** One developer-facing console warning per instance — never per-event spam. */
+    this.parkWarned = false;
     this.retry = new RetryPolicy(cfg.retry ?? {});
     this.persistent = cfg.persistentStore ?? null;
     if (this.persistent) {
@@ -994,6 +1011,7 @@ var EventQueue = class {
    * flushes (pagehide / visibilitychange→hidden / beforeunload).
    */
   async flush(options = {}) {
+    if (this.parked) return null;
     let batch;
     let batchId;
     if (this.pendingBatch !== null && this.pendingBatchId !== null) {
@@ -1045,6 +1063,29 @@ var EventQueue = class {
     } catch (err) {
       const message = err instanceof Error ? err.message : String(err);
       this.lastError = message;
+      if (isVersionRejected(err)) {
+        this.parked = true;
+        this.buffer = [...batch, ...this.buffer];
+        if (this.buffer.length > HARD_BUFFER_CAP) {
+          const overflow = this.buffer.length - HARD_BUFFER_CAP;
+          this.buffer.splice(0, overflow);
+          this.dropped += overflow;
+        }
+        this.pendingBatch = null;
+        this.pendingBatchId = null;
+        this.inFlight -= batch.length;
+        this.persistAll();
+        this.cfg.onBufferChange?.(this.buffer.length);
+        const minVersion = versionRejectionFloor(err);
+        if (!this.parkWarned) {
+          this.parkWarned = true;
+          console.warn(
+            `[Crossdeck] SDK outdated \u2014 the server is no longer accepting this version's event format. Your events are PARKED on-device (held, not lost) and will deliver automatically once you update @cross-deck/web${minVersion ? ` to >= ${minVersion}` : ""} and redeploy.`
+          );
+        }
+        this.cfg.onParked?.({ minVersion, surface: versionRejectionSurface(err) });
+        return null;
+      }
       if (isPermanent4xx(err)) {
         const droppedCount = batch.length;
         this.pendingBatch = null;
@@ -1163,8 +1204,22 @@ function isPermanent4xx(err) {
   if (typeof status !== "number" || !Number.isFinite(status)) return false;
   if (status < 400 || status >= 500) return false;
   if (status === 408 || status === 429) return false;
+  if (status === 426) return false;
   return true;
 }
+function isVersionRejected(err) {
+  if (!err || typeof err !== "object") return false;
+  if (err.status === 426) return true;
+  return err.code === "sdk_version_unsupported";
+}
+function versionRejectionFloor(err) {
+  const v = err?.minVersion;
+  return typeof v === "string" && v.length > 0 ? v : void 0;
+}
+function versionRejectionSurface(err) {
+  const v = err?.surface;
+  return typeof v === "string" && v.length > 0 ? v : void 0;
+}
 function defaultScheduler(fn, ms) {
   const id = setTimeout(fn, ms);
   if (typeof id.unref === "function") {
@@ -1350,6 +1405,16 @@ function hasDocument() {
   return typeof globalThis.document !== "undefined";
 }
 
+// src/read-cost-bridge.ts
+var BUCKETS_BRIDGE_KEY = "__crossdeckBucketsBridge__";
+function bridgeReadCost(ctx) {
+  try {
+    const setter = globalThis[BUCKETS_BRIDGE_KEY];
+    if (typeof setter === "function") setter(ctx);
+  } catch {
+  }
+}
+
 // src/device-info.ts
 function isBrowser() {
   return typeof globalThis.window !== "undefined" && typeof globalThis.document !== "undefined" && typeof globalThis.navigator !== "undefined";
@@ -2905,6 +2970,13 @@ var CROSSDECK_ERROR_CODES = Object.freeze([
     description: "A field is present but the value failed validation (wrong shape, wrong length, wrong enum value).",
     resolution: "Read error.message for the specific field + reason. SDK-managed call sites should never emit this \u2014 file a bug if you do.",
     retryable: false
+  },
+  {
+    code: "sdk_version_unsupported",
+    type: "version_error",
+    description: "HTTP 426 \u2014 your installed SDK sends an event format the server no longer accepts. The data is good; only the wire dialect is too old. The SDK PARKS automatically: events are held on-device (paused, not lost) and deliver on the next launch after you upgrade.",
+    resolution: "Update @cross-deck/web to at least the version in error.minVersion and redeploy \u2014 the parked queue backfills automatically. See https://cross-deck.com/docs/sdk-event-durability/.",
+    retryable: false
   }
 ]);
 function getErrorCode(code) {
@@ -3450,7 +3522,8 @@ var BACKEND_WIRE_CODES = Object.freeze([
   "google_not_supported",
   "stripe_not_supported",
   "missing_required_param",
-  "invalid_param_value"
+  "invalid_param_value",
+  "sdk_version_unsupported"
 ]);
 var VERIFIER_SDK_ERROR_CODES_CATALOGUE = {
   contractId: "sdk-error-codes-catalogue",
@@ -4607,6 +4680,13 @@ var CrossdeckClient = class {
           headline,
           { ...info }
         );
+      },
+      onParked: (info) => {
+        debug.emit(
+          "sdk.parked",
+          `[crossdeck] SDK parked \u2014 server no longer accepts this version's event format. Events held on-device (paused, not lost); update @cross-deck/web${info.minVersion ? ` to >= ${info.minVersion}` : ""} to resume.`,
+          { ...info }
+        );
       }
     });
     const deviceInfo = autoTrack.deviceInfo ? collectDeviceInfo({ appVersion: opts.appVersion ?? void 0 }) : opts.appVersion ? { appVersion: opts.appVersion } : {};
@@ -4824,6 +4904,7 @@ var CrossdeckClient = class {
         message: "identify(userId) requires a non-empty userId."
       });
     }
+    bridgeReadCost({ actor: userId });
     if (!s.consent.analytics) {
       s.debug.emit(
         "sdk.consent_denied",
@@ -5476,6 +5557,7 @@ var CrossdeckClient = class {
     }
     this.state.autoTracker?.uninstall();
     this.state.identity.reset();
+    bridgeReadCost({ actor: void 0 });
     this.state.entitlements.clearAll();
     this.state.events.reset();
     this.state.superProps.clear();
@@ -5566,6 +5648,23 @@ var CrossdeckClient = class {
     const s = this.requireStarted();
     return s.identity.crossdeckCustomerId ?? s.developerUserId ?? s.identity.anonymousId;
   }
+  /**
+   * The device-scoped anonymous id the SDK minted on first boot and persists
+   * across launches (stable until reset()). Public accessor so a server-to-
+   * server flow or a block/suspension gate can pass the device identity to
+   * POST /v1/resolve without reaching into private storage.
+   *
+   * Returns `null` BEFORE init() — there is no anon id yet, and a gate that
+   * fires during early app boot should get a clean falsy, not a throw. (This is
+   * deliberately softer than getCheckoutReference(), which requires init.)
+   *
+   * Note: /v1/resolve also accepts a VERIFIED identity (userId + idToken)
+   * without an anonymousId, and that path is higher-trust — prefer it where the
+   * user is authenticated.
+   */
+  getAnonymousId() {
+    return this.state ? this.state.identity.anonymousId : null;
+  }
   // ---------- private helpers ----------
   requireStarted() {
     if (!this.state) {
@@ -5683,8 +5782,8 @@ function installUnloadFlush(onUnload) {
 }
 
 // src/_contracts-bundled.ts
-var BUNDLED_IN = "@cross-deck/web@1.7.0";
-var SDK_VERSION2 = "1.7.0";
+var BUNDLED_IN = "@cross-deck/web@1.8.0";
+var SDK_VERSION2 = "1.8.0";
 var BUNDLED_CONTRACTS = Object.freeze([
   {
     "id": "contract-failed-payload-schema-lock",
@@ -5806,7 +5905,7 @@ var BUNDLED_CONTRACTS = Object.freeze([
       "legal/security/index.html#diagnostic",
       "legal/sdk-data/index.html#b-diagnostic"
     ],
-    "bundledIn": "@cross-deck/web@1.7.0",
+    "bundledIn": "@cross-deck/web@1.8.0",
     "runtimeVerified": true
   },
   {
@@ -5846,7 +5945,7 @@ var BUNDLED_CONTRACTS = Object.freeze([
     ],
     "registeredAt": "2026-05-26",
     "firstRegisteredIn": "bank-grade reconciliation v1.4.0 \u2014 phase 8 (codifies existing contract)",
-    "bundledIn": "@cross-deck/web@1.7.0",
+    "bundledIn": "@cross-deck/web@1.8.0",
     "runtimeVerified": true
   },
   {
@@ -5892,7 +5991,7 @@ var BUNDLED_CONTRACTS = Object.freeze([
     ],
     "registeredAt": "2026-05-26",
     "firstRegisteredIn": "bank-grade reconciliation v1.4.0 \u2014 phase 3.3",
-    "bundledIn": "@cross-deck/web@1.7.0",
+    "bundledIn": "@cross-deck/web@1.8.0",
     "runtimeVerified": true
   },
   {
@@ -5998,7 +6097,7 @@ var BUNDLED_CONTRACTS = Object.freeze([
     ],
     "registeredAt": "2026-05-26",
     "firstRegisteredIn": "bank-grade reconciliation v1.4.0 \u2014 phase 2.2.a + 2.2.b + 2.2.c",
-    "bundledIn": "@cross-deck/web@1.7.0",
+    "bundledIn": "@cross-deck/web@1.8.0",
     "runtimeVerified": true
   },
   {
@@ -6026,7 +6125,7 @@ var BUNDLED_CONTRACTS = Object.freeze([
     ],
     "registeredAt": "2026-05-26",
     "firstRegisteredIn": "bank-grade reconciliation v1.4.0 \u2014 phase 5.5",
-    "bundledIn": "@cross-deck/web@1.7.0",
+    "bundledIn": "@cross-deck/web@1.8.0",
     "runtimeVerified": false
   },
   {
@@ -6106,7 +6205,7 @@ var BUNDLED_CONTRACTS = Object.freeze([
     ],
     "registeredAt": "2026-05-26",
     "firstRegisteredIn": "bank-grade reconciliation v1.4.0 \u2014 phase 1.3 (web/RN) + dogfood-gap fix (swift + android)",
-    "bundledIn": "@cross-deck/web@1.7.0",
+    "bundledIn": "@cross-deck/web@1.8.0",
     "runtimeVerified": true
   },
   {
@@ -6152,7 +6251,7 @@ var BUNDLED_CONTRACTS = Object.freeze([
     ],
     "registeredAt": "2026-05-26",
     "firstRegisteredIn": "bank-grade reconciliation v1.4.0 \u2014 phase 6.2",
-    "bundledIn": "@cross-deck/web@1.7.0",
+    "bundledIn": "@cross-deck/web@1.8.0",
     "runtimeVerified": true
   },
   {
@@ -6194,7 +6293,7 @@ var BUNDLED_CONTRACTS = Object.freeze([
     ],
     "registeredAt": "2026-05-26",
     "firstRegisteredIn": "bank-grade reconciliation v1.4.0 \u2014 phase 3.2",
-    "bundledIn": "@cross-deck/web@1.7.0",
+    "bundledIn": "@cross-deck/web@1.8.0",
     "runtimeVerified": true
   },
   {
@@ -6228,7 +6327,7 @@ var BUNDLED_CONTRACTS = Object.freeze([
     ],
     "registeredAt": "2026-05-26",
     "firstRegisteredIn": "bank-grade reconciliation v1.4.0 \u2014 phase 3.5",
-    "bundledIn": "@cross-deck/web@1.7.0",
+    "bundledIn": "@cross-deck/web@1.8.0",
     "runtimeVerified": false
   }
 ]);