@cross-deck/web 1.4.2 → 1.5.1

package/dist/index.mjs

@@ -3673,6 +3673,37 @@ var CrossdeckClient = class {
    * trip happens in the background. To flush before the page unloads,
    * call flush().
    */
+  /**
+   * Emit `crossdeck.contract_failed` with the canonical property
+   * shape (`contract_id`, `sdk_version`, `sdk_platform`,
+   * `failure_reason`, `run_context`, `run_id`). Goes through the
+   * standard track() pipeline — same consent gate, same queue,
+   * same ingest, no new endpoint.
+   *
+   * Wire the call from a test hook, dogfood failure path, or
+   * customer contract-verification harness; see
+   * `contracts/README.md` for the per-test-framework hook recipes.
+   */
+  reportContractFailure(input) {
+    const props = {
+      contract_id: input.contractId,
+      sdk_version: SDK_VERSION,
+      sdk_platform: "web",
+      failure_reason: input.failureReason,
+      run_context: input.runContext,
+      run_id: input.runId
+    };
+    if (input.testRef) {
+      props.test_file = input.testRef.file;
+      props.test_name = input.testRef.name;
+    }
+    if (input.extra) {
+      for (const [k, v] of Object.entries(input.extra)) {
+        if (props[k] === void 0) props[k] = v;
+      }
+    }
+    this.track("crossdeck.contract_failed", props);
+  }
   track(name, properties) {
     const s = this.requireStarted();
     if (!name) {
@@ -4272,10 +4303,435 @@ var CROSSDECK_ERROR_CODES = Object.freeze([
 function getErrorCode(code) {
   return CROSSDECK_ERROR_CODES.find((e) => e.code === code);
 }
+
+// src/_contracts-bundled.ts
+var BUNDLED_IN = "@cross-deck/web@1.5.0";
+var SDK_VERSION2 = "1.5.0";
+var BUNDLED_CONTRACTS = Object.freeze([
+  {
+    "id": "error-envelope-shape",
+    "pillar": "errors",
+    "status": "enforced",
+    "claim": "Every v1 REST endpoint returns errors in a Stripe-shape envelope: `{ error: { type, code, message, request_id } }` where `type` is one of authentication_error / permission_error / invalid_request_error / rate_limit_error / internal_error (the wire vocabulary in backend/src/api/v1-errors.ts ApiErrorType). HTTP status parity: invalid_request_error \u2192 400, authentication_error \u2192 401, permission_error \u2192 403, rate_limit_error \u2192 429, internal_error \u2192 500. SDK-side clients parse this shape via `crossdeckErrorFromResponse` (Web/Node/RN) / `crossdeckErrorFrom(response:)` (Swift) / `crossdeckErrorFromResponse` (Android) and surface the request_id verbatim so support traces are end-to-end joinable. Firebase callable endpoints (managed-keys / dashboard auth) use the Firebase HttpsError envelope instead \u2014 this contract applies to REST /v1/* only.",
+    "appliesTo": [
+      "web",
+      "node",
+      "react-native",
+      "swift",
+      "android",
+      "backend"
+    ],
+    "codeRef": [
+      "backend/src/api/v1-errors.ts",
+      "sdks/web/src/errors.ts",
+      "sdks/node/src/errors.ts",
+      "sdks/react-native/src/errors.ts",
+      "sdks/swift/Sources/Crossdeck/Errors.swift",
+      "sdks/android/crossdeck/src/main/kotlin/com/crossdeck/Errors.kt"
+    ],
+    "testRef": [
+      {
+        "file": "sdks/swift/Tests/CrossdeckTests/ErrorsTests.swift",
+        "name": "test_errorEnvelope_fallsBackOnGarbageBody"
+      },
+      {
+        "file": "sdks/swift/Tests/CrossdeckTests/ErrorsTests.swift",
+        "name": "test_errorEnvelope_reads_XRequestId_fallback"
+      },
+      {
+        "file": "sdks/android/crossdeck/src/test/kotlin/com/crossdeck/ErrorTypeWireVocabTest.kt",
+        "name": "backend 500 response parses to INTERNAL_ERROR"
+      }
+    ],
+    "registeredAt": "2026-05-26",
+    "firstRegisteredIn": "bank-grade reconciliation v1.4.0 \u2014 phase 8 (codifies existing contract)",
+    "bundledIn": "@cross-deck/web@1.5.0"
+  },
+  {
+    "id": "flush-interval-parity",
+    "pillar": "analytics",
+    "status": "enforced",
+    "claim": "Every Crossdeck SDK defaults its event-queue flush interval to 2000ms \u2014 the Stripe-adjacent industry norm. Pre-v1.4.0 the defaults disagreed (Web/Node 1500ms; RN/Swift/Android 5000ms), so cross-platform funnels saw events landing at different cadences. Per-instance override stays \u2014 call sites can still tune it freely.",
+    "appliesTo": [
+      "web",
+      "node",
+      "react-native",
+      "swift",
+      "android"
+    ],
+    "codeRef": [
+      "sdks/web/src/crossdeck.ts",
+      "sdks/node/src/crossdeck-server.ts",
+      "sdks/react-native/src/crossdeck.ts",
+      "sdks/swift/Sources/Crossdeck/EventQueue.swift",
+      "sdks/android/crossdeck/src/main/kotlin/com/crossdeck/EventQueue.kt"
+    ],
+    "testRef": [
+      {
+        "file": "sdks/swift/Sources/Crossdeck/EventQueue.swift",
+        "name": "flushIntervalMs: Int = 2_000"
+      },
+      {
+        "file": "sdks/android/crossdeck/src/main/kotlin/com/crossdeck/EventQueue.kt",
+        "name": "flushIntervalMs: Long = 2_000L"
+      },
+      {
+        "file": "sdks/web/src/crossdeck.ts",
+        "name": "options.eventFlushIntervalMs ?? 2000"
+      },
+      {
+        "file": "sdks/node/src/crossdeck-server.ts",
+        "name": "options.eventFlushIntervalMs ?? 2000"
+      },
+      {
+        "file": "sdks/react-native/src/crossdeck.ts",
+        "name": "options.eventFlushIntervalMs ?? 2000"
+      }
+    ],
+    "registeredAt": "2026-05-26",
+    "firstRegisteredIn": "bank-grade reconciliation v1.4.0 \u2014 phase 3.3",
+    "bundledIn": "@cross-deck/web@1.5.0"
+  },
+  {
+    "id": "idempotency-key-deterministic",
+    "pillar": "revenue",
+    "status": "enforced",
+    "claim": "syncPurchases() on every SDK derives a deterministic Idempotency-Key from the request body (UUID-shaped SHA-256 of `crossdeck:purchases/sync:<rail>:<jws|token>`). Same input -> same key. Backend short-circuits same-key-same-body retries by returning the cached response (status + body) with `idempotent_replay: true` flag in the body AND `Idempotent-Replayed: true` response header. Same-key-different-body returns 400 `idempotency_key_in_use`. 24-hour TTL matches Stripe. Cache only stores 2xx responses \u2014 4xx/5xx pass through so callers can fix bugs and retry. Helper returns nil/throws on missing identifier (no silent random fallback). Cross-SDK parity is CI-pinned: deriveForPurchase('apple', 'eyJ.jws.sig') MUST equal 'a66b1640-efaf-bb4d-1261-6650033bf111' on every SDK.",
+    "appliesTo": [
+      "web",
+      "node",
+      "react-native",
+      "swift",
+      "android",
+      "backend"
+    ],
+    "codeRef": [
+      "sdks/web/src/idempotency-key.ts",
+      "sdks/web/src/crossdeck.ts",
+      "sdks/react-native/src/idempotency-key.ts",
+      "sdks/react-native/src/crossdeck.ts",
+      "sdks/node/src/idempotency-key.ts",
+      "sdks/node/src/crossdeck-server.ts",
+      "sdks/swift/Sources/Crossdeck/IdempotencyKey.swift",
+      "sdks/swift/Sources/Crossdeck/Crossdeck.swift",
+      "sdks/android/crossdeck/src/main/kotlin/com/crossdeck/IdempotencyKey.kt",
+      "sdks/android/crossdeck/src/main/kotlin/com/crossdeck/Crossdeck.kt",
+      "backend/src/lib/idempotency-response-cache.ts",
+      "backend/src/api/v1-purchases.ts"
+    ],
+    "testRef": [
+      {
+        "file": "sdks/web/tests/idempotency-key.test.ts",
+        "name": "cross-SDK oracle \u2014 apple JWS pins canonical vector"
+      },
+      {
+        "file": "sdks/web/tests/idempotency-key.test.ts",
+        "name": "is deterministic: same body twice -> identical key"
+      },
+      {
+        "file": "sdks/web/tests/idempotency-key.test.ts",
+        "name": "same identifier under different rails -> different keys"
+      },
+      {
+        "file": "sdks/web/tests/idempotency-key.test.ts",
+        "name": "never silently falls back to a random key on missing identifier"
+      },
+      {
+        "file": "sdks/react-native/tests/idempotency-key.test.ts",
+        "name": "is deterministic"
+      },
+      {
+        "file": "sdks/react-native/tests/idempotency-key.test.ts",
+        "name": "cross-SDK oracle \u2014 apple JWS pins canonical vector"
+      },
+      {
+        "file": "sdks/node/tests/idempotency-key.test.ts",
+        "name": "is deterministic"
+      },
+      {
+        "file": "sdks/node/tests/idempotency-key.test.ts",
+        "name": "rail namespacing prevents cross-rail collisions"
+      },
+      {
+        "file": "sdks/node/tests/idempotency-key.test.ts",
+        "name": "apple JWS produces the canonical pinned UUID across all 5 SDKs"
+      },
+      {
+        "file": "backend/tests/unit/idempotency-response-cache.test.ts",
+        "name": "is deterministic for the same input"
+      },
+      {
+        "file": "backend/tests/unit/idempotency-response-cache.test.ts",
+        "name": "injects idempotent_replay: true into a JSON object body"
+      },
+      {
+        "file": "backend/tests/unit/idempotency-response-cache.test.ts",
+        "name": "matches Stripe's 24-hour idempotency window"
+      },
+      {
+        "file": "sdks/swift/Tests/CrossdeckTests/IdempotencyKeyTests.swift",
+        "name": "test_crossSdkOracle_appleJWS"
+      },
+      {
+        "file": "sdks/swift/Tests/CrossdeckTests/IdempotencyKeyTests.swift",
+        "name": "test_railNamespacing_preventsCrossRailCollisions"
+      },
+      {
+        "file": "sdks/swift/Tests/CrossdeckTests/IdempotencyKeyTests.swift",
+        "name": "test_missingIdentifier_returnsNil"
+      },
+      {
+        "file": "sdks/android/crossdeck/src/test/kotlin/com/crossdeck/IdempotencyKeyTest.kt",
+        "name": "cross-SDK oracle for apple JWS"
+      },
+      {
+        "file": "sdks/android/crossdeck/src/test/kotlin/com/crossdeck/IdempotencyKeyTest.kt",
+        "name": "rail namespacing prevents cross-rail collisions"
+      },
+      {
+        "file": "sdks/android/crossdeck/src/test/kotlin/com/crossdeck/IdempotencyKeyTest.kt",
+        "name": "missing identifier returns null - never silent random fallback"
+      }
+    ],
+    "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.5.0"
+  },
+  {
+    "id": "init-reentry-drains-prior-queue",
+    "pillar": "lifecycle",
+    "status": "enforced",
+    "claim": "Web + RN init() re-entry drains the prior EventQueue's pending setTimeout BEFORE replacing this.state. Pre-v1.4.0 the teardown handled autoTracker/webVitals/errors/unloadFlush but NOT events, so the prior queue's timer would fire AFTER the state swap \u2014 sending old-init events against new-init http + identity references (cross-identity leak during HMR / config swap / multi-tenant SDK shells). The teardown CANNOT call persistent.clear() \u2014 the durable queue belongs to the SDK lifetime, not the init() lifetime, and a survived crash mid-flush re-hydrates on the next init.",
+    "appliesTo": [
+      "web",
+      "react-native"
+    ],
+    "codeRef": [
+      "sdks/web/src/crossdeck.ts",
+      "sdks/react-native/src/crossdeck.ts"
+    ],
+    "testRef": [
+      {
+        "file": "sdks/web/tests/init-reentry.test.ts",
+        "name": "re-init drains the prior queue's pending timer before swapping state"
+      },
+      {
+        "file": "sdks/web/tests/init-reentry.test.ts",
+        "name": "re-init does NOT wipe the durable event store"
+      }
+    ],
+    "registeredAt": "2026-05-26",
+    "firstRegisteredIn": "bank-grade reconciliation v1.4.0 \u2014 phase 5.5",
+    "bundledIn": "@cross-deck/web@1.5.0"
+  },
+  {
+    "id": "per-user-cache-isolation",
+    "pillar": "entitlements",
+    "status": "enforced",
+    "claim": "Every identify(userId) switches the entitlement cache to a physically separate per-user storage slot \u2014 `crossdeck:entitlements:<sha256(userId)>` \u2014 and unconditionally wipes the in-memory snapshot. A user-switch on a shared device CANNOT cross-read a prior user's cached entitlements, even if the in-memory clear is somehow skipped, because the storage keys are physically separate. reset() wipes every per-user slot via the persisted index.",
+    "appliesTo": [
+      "web",
+      "react-native",
+      "swift",
+      "android"
+    ],
+    "codeRef": [
+      "sdks/web/src/entitlement-cache.ts",
+      "sdks/web/src/hash.ts",
+      "sdks/web/src/crossdeck.ts",
+      "sdks/react-native/src/entitlement-cache.ts",
+      "sdks/react-native/src/hash.ts",
+      "sdks/react-native/src/crossdeck.ts",
+      "sdks/swift/Sources/Crossdeck/EntitlementCache.swift",
+      "sdks/swift/Sources/Crossdeck/IdempotencyKey.swift",
+      "sdks/swift/Sources/Crossdeck/Crossdeck.swift",
+      "sdks/android/crossdeck/src/main/kotlin/com/crossdeck/EntitlementCache.kt",
+      "sdks/android/crossdeck/src/main/kotlin/com/crossdeck/IdempotencyKey.kt",
+      "sdks/android/crossdeck/src/main/kotlin/com/crossdeck/Crossdeck.kt"
+    ],
+    "testRef": [
+      {
+        "file": "sdks/web/tests/entitlement-cache-isolation.test.ts",
+        "name": "identify(B) makes A's entitlements unreachable from in-memory"
+      },
+      {
+        "file": "sdks/web/tests/entitlement-cache-isolation.test.ts",
+        "name": "clearAll() removes every per-user storage key plus the index"
+      },
+      {
+        "file": "sdks/web/tests/entitlement-cache-isolation.test.ts",
+        "name": "a second cache instance reading A's storage suffix CANNOT see B's data"
+      },
+      {
+        "file": "sdks/react-native/tests/entitlement-cache-isolation.test.ts",
+        "name": "identify(B) makes A's entitlements unreachable from in-memory"
+      },
+      {
+        "file": "sdks/react-native/tests/entitlement-cache-isolation.test.ts",
+        "name": "removes every per-user storage key plus the index"
+      },
+      {
+        "file": "sdks/swift/Tests/CrossdeckTests/EntitlementCacheIsolationTests.swift",
+        "name": "test_identifyB_makesAEntitlementsUnreachable"
+      },
+      {
+        "file": "sdks/swift/Tests/CrossdeckTests/EntitlementCacheIsolationTests.swift",
+        "name": "test_identifiedWritesLandUnderPerUserSha256Key"
+      },
+      {
+        "file": "sdks/swift/Tests/CrossdeckTests/EntitlementCacheIsolationTests.swift",
+        "name": "test_clearAll_removesEveryPerUserStorageKeyPlusIndex"
+      },
+      {
+        "file": "sdks/android/crossdeck/src/test/kotlin/com/crossdeck/EntitlementCacheIsolationTest.kt",
+        "name": "identified writes land under per-user sha256 key"
+      },
+      {
+        "file": "sdks/android/crossdeck/src/test/kotlin/com/crossdeck/EntitlementCacheIsolationTest.kt",
+        "name": "identify B makes A entitlements unreachable from in-memory"
+      },
+      {
+        "file": "sdks/android/crossdeck/src/test/kotlin/com/crossdeck/EntitlementCacheIsolationTest.kt",
+        "name": "clearAll removes every per-user storage key plus the index"
+      },
+      {
+        "file": "sdks/android/crossdeck/src/test/kotlin/com/crossdeck/EntitlementCacheIsolationTest.kt",
+        "name": "a fresh cache bound to A's key CANNOT read B's blob"
+      }
+    ],
+    "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.5.0"
+  },
+  {
+    "id": "sdk-error-codes-catalogue",
+    "pillar": "errors",
+    "status": "enforced",
+    "claim": "Web + Node SDK error-codes catalogues include EVERY backend-emitted ApiErrorCode with a description + resolution. Pre-v1.4.0 the catalogues documented codes the SDK threw ITSELF but ZERO backend codes \u2014 a developer hitting `invalid_api_key` / `origin_not_allowed` / `bundle_id_not_allowed` / `env_mismatch` / `idempotency_key_in_use` etc. got `undefined` from getErrorCode() and had to hunt for guidance. v1.4.0 backfills the catalogue from backend/src/api/v1-errors.ts so every wire code has a canonical 'what does this mean / what should I do' answer Stripe-style.",
+    "appliesTo": [
+      "web",
+      "node"
+    ],
+    "codeRef": [
+      "sdks/web/src/error-codes.ts",
+      "sdks/node/src/error-codes.ts",
+      "backend/src/api/v1-errors.ts"
+    ],
+    "testRef": [
+      {
+        "file": "sdks/web/tests/error-codes-backfill.test.ts",
+        "name": "includes backend code"
+      },
+      {
+        "file": "sdks/web/tests/error-codes-backfill.test.ts",
+        "name": "invalid_api_key resolution points at the dashboard"
+      },
+      {
+        "file": "sdks/web/tests/error-codes-backfill.test.ts",
+        "name": "idempotency_key_in_use resolution mentions Stripe-grade contract"
+      },
+      {
+        "file": "sdks/web/tests/error-codes-backfill.test.ts",
+        "name": "identity-lock codes carry permission_error type"
+      },
+      {
+        "file": "sdks/web/tests/error-codes-backfill.test.ts",
+        "name": "no entry has an empty description or resolution"
+      }
+    ],
+    "registeredAt": "2026-05-26",
+    "firstRegisteredIn": "bank-grade reconciliation v1.4.0 \u2014 phase 6.2",
+    "bundledIn": "@cross-deck/web@1.5.0"
+  },
+  {
+    "id": "sync-purchases-funnel-parity",
+    "pillar": "analytics",
+    "status": "enforced",
+    "claim": "Manual syncPurchases() emits a `purchase.completed` analytics event on success across ALL SDKs (Web / Node / RN / Swift / Android). Pre-v1.4.0 only Swift/Android auto-track emitted it \u2014 Web/Node/RN manual calls + Swift/Android manual calls fired ZERO analytics. Schema mirrors the auto-track event name + rail/productId/subscriptionId so cross-platform funnels reconcile on every payment path. When the backend short-circuits via the v1.4.0 idempotency cache, the event also carries `idempotent_replay: true`.",
+    "appliesTo": [
+      "web",
+      "node",
+      "react-native",
+      "swift",
+      "android"
+    ],
+    "codeRef": [
+      "sdks/web/src/crossdeck.ts",
+      "sdks/node/src/crossdeck-server.ts",
+      "sdks/react-native/src/crossdeck.ts",
+      "sdks/swift/Sources/Crossdeck/Crossdeck.swift",
+      "sdks/android/crossdeck/src/main/kotlin/com/crossdeck/Crossdeck.kt"
+    ],
+    "testRef": [
+      {
+        "file": "sdks/web/tests/sync-purchases-funnel.test.ts",
+        "name": "emits purchase.completed after a successful sync"
+      },
+      {
+        "file": "sdks/web/tests/sync-purchases-funnel.test.ts",
+        "name": "carries idempotent_replay=true when backend replied from cache"
+      }
+    ],
+    "registeredAt": "2026-05-26",
+    "firstRegisteredIn": "bank-grade reconciliation v1.4.0 \u2014 phase 3.5",
+    "bundledIn": "@cross-deck/web@1.5.0"
+  }
+]);
+
+// src/contracts.ts
+var CrossdeckContracts = {
+  /** Every contract that applies to this SDK and is currently enforced. */
+  all() {
+    return BUNDLED_CONTRACTS.filter((c) => c.status === "enforced");
+  },
+  /**
+   * Every contract bundled with this SDK release, including
+   * `proposed` and `retired` entries. Use `all()` for the
+   * enforced-only view.
+   */
+  allIncludingHistorical() {
+    return BUNDLED_CONTRACTS;
+  },
+  /** Look up a contract by its stable `id`. */
+  byId(id) {
+    return BUNDLED_CONTRACTS.find((c) => c.id === id);
+  },
+  /** Every enforced contract within a pillar. */
+  byPillar(pillar) {
+    return BUNDLED_CONTRACTS.filter(
+      (c) => c.pillar === pillar && c.status === "enforced"
+    );
+  },
+  /** Filter by lifecycle status. */
+  withStatus(status) {
+    return BUNDLED_CONTRACTS.filter((c) => c.status === status);
+  },
+  /** Semver of the SDK release these contracts were bundled with. */
+  sdkVersion: SDK_VERSION2,
+  /** Fully-qualified bundle identifier — e.g. `@cross-deck/web@1.4.2`. */
+  bundledIn: BUNDLED_IN,
+  /**
+   * Resolve a failing test back to the contract it exercises.
+   * Used by test-framework hooks (Vitest `afterEach`, XCTest
+   * observation, JUnit `TestWatcher`) to find the contract id of
+   * a failed contract test so `reportContractFailure(...)` can
+   * stamp the right `contract_id` on the emitted event.
+   *
+   * Match is on `testRef.name` (case-sensitive, exact). Returns
+   * the first contract whose `testRef` list contains a matching
+   * entry, regardless of pillar or status.
+   */
+  findByTestName(name) {
+    return BUNDLED_CONTRACTS.find(
+      (c) => c.testRef.some((ref) => ref.name === name)
+    );
+  }
+};
 export {
   CROSSDECK_ERROR_CODES,
   Crossdeck,
   CrossdeckClient,
+  CrossdeckContracts,
   CrossdeckError,
   DEFAULT_BASE_URL,
   MemoryStorage,