@cross-deck/web 1.7.0 → 1.9.0

package/dist/index.d.mts

@@ -247,9 +247,9 @@ declare const CrossdeckContracts: {
     /** Filter by lifecycle status. */
     readonly withStatus: (status: ContractStatus) => readonly Contract[];
     /** Semver of the SDK release these contracts were bundled with. */
-    readonly sdkVersion: "1.7.0";
+    readonly sdkVersion: "1.8.0";
     /** Fully-qualified bundle identifier — e.g. `@cross-deck/web@1.4.2`. */
-    readonly bundledIn: "@cross-deck/web@1.7.0";
+    readonly bundledIn: "@cross-deck/web@1.8.0";
     /**
      * Resolve a failing test back to the contract it exercises.
      * Used by test-framework hooks (Vitest `afterEach`, XCTest
@@ -798,6 +798,21 @@ declare class CrossdeckClient {
      * and not a per-device anon id.
      */
     getCheckoutReference(): string;
+    /**
+     * 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(): string | null;
     private requireStarted;
     /**
      * Build the identity query for /v1/entitlements. Priority:
@@ -843,7 +858,7 @@ declare const Crossdeck: CrossdeckClient;
  *     }
  *   }
  */
-type CrossdeckErrorType = "authentication_error" | "permission_error" | "invalid_request_error" | "rate_limit_error" | "internal_error" | "network_error" | "configuration_error";
+type CrossdeckErrorType = "authentication_error" | "permission_error" | "invalid_request_error" | "rate_limit_error" | "version_error" | "internal_error" | "network_error" | "configuration_error";
 interface CrossdeckErrorPayload {
     type: CrossdeckErrorType;
     code: string;
@@ -860,6 +875,14 @@ interface CrossdeckErrorPayload {
      * server is telling you the safe rate.
      */
     retryAfterMs?: number;
+    /**
+     * Required SDK version floor — populated only on a `426 Upgrade Required`
+     * / `sdk_version_unsupported` response. The queue surfaces it in the
+     * "update to >= X" PARK message so the cure is exact.
+     */
+    minVersion?: string;
+    /** SDK surface the rejection applies to (web/node/swift/…), on a 426. */
+    surface?: string;
 }
 declare class CrossdeckError extends Error {
     readonly type: CrossdeckErrorType;
@@ -867,6 +890,8 @@ declare class CrossdeckError extends Error {
     readonly requestId?: string;
     readonly status?: number;
     readonly retryAfterMs?: number;
+    readonly minVersion?: string;
+    readonly surface?: string;
     constructor(payload: CrossdeckErrorPayload);
 }
 
@@ -936,7 +961,7 @@ declare class MemoryStorage implements KeyValueStorage {
  *
  * Do NOT edit by hand — `node scripts/sync-sdk-versions.mjs`.
  */
-declare const SDK_VERSION = "1.7.0";
+declare const SDK_VERSION = "1.9.0";
 declare const SDK_NAME = "@cross-deck/web";
 
 /**
@@ -974,7 +999,7 @@ interface ErrorCodeEntry {
     /** The string thrown as CrossdeckError.code. */
     code: string;
     /** CrossdeckError.type — broad category. */
-    type: "authentication_error" | "permission_error" | "invalid_request_error" | "rate_limit_error" | "internal_error" | "network_error" | "configuration_error";
+    type: "authentication_error" | "permission_error" | "invalid_request_error" | "rate_limit_error" | "version_error" | "internal_error" | "network_error" | "configuration_error";
     /** One-sentence description. Surfaced verbatim in dashboards. */
     description: string;
     /** What the developer should do. Imperative phrasing. */

package/dist/index.d.ts

@@ -247,9 +247,9 @@ declare const CrossdeckContracts: {
     /** Filter by lifecycle status. */
     readonly withStatus: (status: ContractStatus) => readonly Contract[];
     /** Semver of the SDK release these contracts were bundled with. */
-    readonly sdkVersion: "1.7.0";
+    readonly sdkVersion: "1.8.0";
     /** Fully-qualified bundle identifier — e.g. `@cross-deck/web@1.4.2`. */
-    readonly bundledIn: "@cross-deck/web@1.7.0";
+    readonly bundledIn: "@cross-deck/web@1.8.0";
     /**
      * Resolve a failing test back to the contract it exercises.
      * Used by test-framework hooks (Vitest `afterEach`, XCTest
@@ -798,6 +798,21 @@ declare class CrossdeckClient {
      * and not a per-device anon id.
      */
     getCheckoutReference(): string;
+    /**
+     * 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(): string | null;
     private requireStarted;
     /**
      * Build the identity query for /v1/entitlements. Priority:
@@ -843,7 +858,7 @@ declare const Crossdeck: CrossdeckClient;
  *     }
  *   }
  */
-type CrossdeckErrorType = "authentication_error" | "permission_error" | "invalid_request_error" | "rate_limit_error" | "internal_error" | "network_error" | "configuration_error";
+type CrossdeckErrorType = "authentication_error" | "permission_error" | "invalid_request_error" | "rate_limit_error" | "version_error" | "internal_error" | "network_error" | "configuration_error";
 interface CrossdeckErrorPayload {
     type: CrossdeckErrorType;
     code: string;
@@ -860,6 +875,14 @@ interface CrossdeckErrorPayload {
      * server is telling you the safe rate.
      */
     retryAfterMs?: number;
+    /**
+     * Required SDK version floor — populated only on a `426 Upgrade Required`
+     * / `sdk_version_unsupported` response. The queue surfaces it in the
+     * "update to >= X" PARK message so the cure is exact.
+     */
+    minVersion?: string;
+    /** SDK surface the rejection applies to (web/node/swift/…), on a 426. */
+    surface?: string;
 }
 declare class CrossdeckError extends Error {
     readonly type: CrossdeckErrorType;
@@ -867,6 +890,8 @@ declare class CrossdeckError extends Error {
     readonly requestId?: string;
     readonly status?: number;
     readonly retryAfterMs?: number;
+    readonly minVersion?: string;
+    readonly surface?: string;
     constructor(payload: CrossdeckErrorPayload);
 }
 
@@ -936,7 +961,7 @@ declare class MemoryStorage implements KeyValueStorage {
  *
  * Do NOT edit by hand — `node scripts/sync-sdk-versions.mjs`.
  */
-declare const SDK_VERSION = "1.7.0";
+declare const SDK_VERSION = "1.9.0";
 declare const SDK_NAME = "@cross-deck/web";
 
 /**
@@ -974,7 +999,7 @@ interface ErrorCodeEntry {
     /** The string thrown as CrossdeckError.code. */
     code: string;
     /** CrossdeckError.type — broad category. */
-    type: "authentication_error" | "permission_error" | "invalid_request_error" | "rate_limit_error" | "internal_error" | "network_error" | "configuration_error";
+    type: "authentication_error" | "permission_error" | "invalid_request_error" | "rate_limit_error" | "version_error" | "internal_error" | "network_error" | "configuration_error";
     /** One-sentence description. Surfaced verbatim in dashboards. */
     description: string;
     /** What the developer should do. Imperative phrasing. */

package/dist/index.mjs

@@ -8,6 +8,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);
   }
 };
@@ -28,7 +30,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({
@@ -64,7 +69,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
@@ -904,6 +909,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) {
@@ -959,6 +976,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) {
@@ -1010,6 +1028,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;
@@ -1128,8 +1169,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") {
@@ -1315,6 +1370,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";
@@ -2870,6 +2935,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) {
@@ -3415,7 +3487,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",
@@ -4572,6 +4645,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 } : {};
@@ -4789,6 +4869,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",
@@ -5441,6 +5522,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();
@@ -5531,6 +5613,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) {
@@ -5648,8 +5747,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",
@@ -5771,7 +5870,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
   },
   {
@@ -5811,7 +5910,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
   },
   {
@@ -5857,7 +5956,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
   },
   {
@@ -5963,7 +6062,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
   },
   {
@@ -5991,7 +6090,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
   },
   {
@@ -6071,7 +6170,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
   },
   {
@@ -6117,7 +6216,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
   },
   {
@@ -6159,7 +6258,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
   },
   {
@@ -6193,7 +6292,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
   }
 ]);