@cross-deck/react-native 1.0.0 → 1.5.1

package/dist/index.d.mts

@@ -58,6 +58,10 @@ interface PurchaseResult {
     crossdeckCustomerId: string;
     env: Environment;
     entitlements: PublicEntitlement[];
+    /** True when the response came from the backend's idempotency
+     * cache instead of fresh processing. Backend also returns
+     * `Idempotent-Replayed: true` as a response header (v1.4.0). */
+    idempotent_replay?: boolean;
 }
 interface HeartbeatResponse {
     object: "heartbeat";
@@ -140,6 +144,37 @@ interface CrossdeckOptions {
      * validators don't reject.
      */
     platform?: Platform;
+    /**
+     * iOS Bundle ID (e.g. `com.acme.app`). REQUIRED for iOS builds.
+     * Sent as `X-Crossdeck-Bundle-Id` on every request so the backend
+     * can enforce the bank-grade identity lock against the bundleId
+     * stored on the iOS app key. Without it, every iOS request is
+     * rejected with 403 / bundle_id_not_allowed.
+     *
+     * Source the value from your native shell:
+     *   * Expo: `import { applicationId } from "expo-application"`
+     *   * Bare RN: `react-native-device-info.getBundleId()` or
+     *     `NativeModules.PlatformConstants.bundleId`.
+     *
+     * Safe to set on Android too — the backend ignores it for non-iOS
+     * platforms, so a single config object works for both runtimes.
+     */
+    bundleId?: string;
+    /**
+     * Android applicationId / package name (e.g. `com.acme.app`).
+     * REQUIRED for Android builds. Sent as `X-Crossdeck-Package-Name`
+     * on every request so the backend can enforce the bank-grade
+     * identity lock against the packageName stored on the Android
+     * app key. Without it, every Android request is rejected with
+     * 403 / package_name_not_allowed.
+     *
+     * Source from:
+     *   * Expo: `import { applicationId } from "expo-application"`
+     *     (same field on Android)
+     *   * Bare RN: `NativeModules.PlatformConstants.packageName` /
+     *     `react-native-device-info.getBundleId()`.
+     */
+    packageName?: string;
     /**
      * Per-request timeout in ms. Default 15000. A captive portal or
      * hung connection would otherwise inherit the runtime's default
@@ -392,6 +427,108 @@ interface Breadcrumb {
     data?: Record<string, unknown>;
 }
 
+/**
+ * Public, typed accessor for the bank-grade behavioural contracts
+ * this SDK ships. The full architecture — schema, distribution,
+ * audit loop, pillar taxonomy — lives in `contracts/README.md`
+ * at the monorepo root.
+ *
+ * Why a typed surface (vs. plain JSON access): contract IDs and
+ * pillar names are part of Crossdeck's public commitment to
+ * customers. Reading them through `CrossdeckContracts` means the
+ * compiler catches drift the moment a contract is renamed or
+ * retired. Tools that consume contracts at runtime (dashboards,
+ * AI assistants, customer integration tests) get the exact same
+ * shape every SDK ships, with no parsing layer to drift.
+ *
+ * --- BINARY STABILITY ---
+ * `Contract` is treated as an evolving — but back-compat — wire
+ * shape. Fields may be added in any minor release. Existing
+ * fields will not be removed or repurposed except in a major
+ * version bump, even if all known contracts stop using them.
+ * Customers can rely on `id`, `pillar`, `status`, `appliesTo`,
+ * `codeRef`, `testRef`, `registeredAt`, `firstRegisteredIn`,
+ * and `bundledIn` being present on every contract in every
+ * future minor/patch release of this SDK.
+ */
+type ContractPillar = "revenue" | "entitlements" | "analytics" | "webhooks" | "errors" | "lifecycle" | "identity";
+type ContractStatus = "enforced" | "proposed" | "retired";
+type ContractAppliesTo = "web" | "node" | "react-native" | "swift" | "android" | "backend";
+interface ContractTestRef {
+    readonly file: string;
+    readonly name: string;
+}
+interface Contract {
+    readonly id: string;
+    readonly pillar: ContractPillar;
+    readonly status: ContractStatus;
+    readonly claim: string;
+    readonly appliesTo: readonly ContractAppliesTo[];
+    readonly codeRef: readonly string[];
+    readonly testRef: readonly ContractTestRef[];
+    readonly registeredAt: string;
+    readonly firstRegisteredIn: string;
+    readonly bundledIn: string;
+}
+/**
+ * Typed entry point to the bank-grade contracts bundled with this
+ * SDK release. Stable, side-effect-free, tree-shakeable.
+ *
+ * @example Audit at app boot
+ * ```ts
+ * import { CrossdeckContracts } from "@cross-deck/react-native";
+ *
+ * for (const c of CrossdeckContracts.all()) {
+ *   console.log(`[crossdeck] ${c.id} (${c.pillar})`);
+ * }
+ * ```
+ */
+declare const CrossdeckContracts: {
+    readonly all: () => readonly Contract[];
+    readonly allIncludingHistorical: () => readonly Contract[];
+    readonly byId: (id: string) => Contract | undefined;
+    readonly byPillar: (pillar: ContractPillar) => readonly Contract[];
+    readonly withStatus: (status: ContractStatus) => readonly Contract[];
+    readonly sdkVersion: "1.5.1";
+    readonly bundledIn: "@cross-deck/react-native@1.5.1";
+    /**
+     * Resolve a failing test back to the contract it exercises.
+     * Used by test-framework hooks to find the contract id of a
+     * failed contract test so `reportContractFailure(...)` can stamp
+     * the right `contract_id` on the emitted event.
+     */
+    readonly findByTestName: (name: string) => Contract | undefined;
+};
+/**
+ * Input to {@link Crossdeck.reportContractFailure}.
+ *
+ * SCHEMA-LOCK: this interface's field set is exhaustively named. No
+ * free-form `extra: Record<string, unknown>` — the schema-lock
+ * contract at
+ * `contracts/diagnostics/contract-failed-payload-schema-lock.json`
+ * forbids unbounded fields.
+ */
+interface ContractFailureInput {
+    contractId: string;
+    /**
+     * Short categorical-ish label — the SDK convention is to keep
+     * this under 128 chars and stable across runs. Never an
+     * end-user-supplied string.
+     */
+    failureReason: string;
+    runContext: "ci" | "dogfood" | "customer-app";
+    runId: string;
+    testRef?: {
+        file: string;
+        name: string;
+    };
+    /**
+     * Optional coarse device class, e.g. "ios-phone", "android-tablet".
+     * A categorical bucket, not a device identifier.
+     */
+    deviceClass?: string;
+}
+
 /**
  * Stack-trace parser — normalises Hermes / JSC / V8 stack strings
  * into a common frame shape.
@@ -642,6 +779,17 @@ declare class CrossdeckClient {
      * stamped. Common-case `track()` after hydration runs entirely
      * synchronously.
      */
+    /**
+     * Emit `crossdeck.contract_failed` to the Crossdeck reliability
+     * endpoint — single-fire, one-way, never visible in the customer's
+     * dashboard. Goes over a dedicated HTTP path with the reliability
+     * publishable key embedded at build time; the customer's track()
+     * pipeline never carries `crossdeck.*` events. This is the
+     * independent-controller flow described in Privacy Policy §6
+     * ("Flow B"). The wire shape is fixed by the schema-lock contract
+     * at `contracts/diagnostics/contract-failed-payload-schema-lock.json`.
+     */
+    reportContractFailure(input: ContractFailureInput): void;
     track(name: string, properties?: EventProperties): void;
     /**
      * The body of `track()` — everything after the synchronous
@@ -665,6 +813,33 @@ declare class CrossdeckClient {
         purchaseToken?: string;
         appAccountToken?: string;
     }): Promise<PurchaseResult>;
+    /**
+     * v1.4.0 Phase 3.4 — set the active session id. RN doesn't own
+     * session lifecycle (that's the host's AppState + nav library);
+     * the host calls `setSessionId()` from its AppState change
+     * listener so every subsequent `track()` event carries the
+     * `sessionId` property — matches the web SDK's session-anchored
+     * funnel queries.
+     *
+     * ```ts
+     * import { AppState } from "react-native";
+     *
+     * let sessionId = uuid();
+     * AppState.addEventListener("change", (next) => {
+     *   if (next === "active") {
+     *     // New session if backgrounded > 30 min.
+     *     sessionId = uuid();
+     *     Crossdeck.setSessionId(sessionId);
+     *   } else if (next === "background") {
+     *     void Crossdeck.flush();
+     *   }
+     * });
+     * Crossdeck.setSessionId(sessionId);
+     * ```
+     *
+     * Pass `null` to clear (between sessions, on logout, etc).
+     */
+    setSessionId(sessionId: string | null): void;
     /** Toggle verbose diagnostic logging. */
     setDebugMode(enabled: boolean): void;
     /**
@@ -837,7 +1012,7 @@ declare class AsyncStorageAdapter implements KeyValueStorage {
  *
  * Do NOT edit by hand — `node scripts/sync-sdk-versions.mjs`.
  */
-declare const SDK_VERSION = "1.0.0";
+declare const SDK_VERSION = "1.5.1";
 declare const SDK_NAME = "@cross-deck/react-native";
 
 /**
@@ -900,4 +1075,4 @@ interface DeviceInfo {
     appVersion?: string;
 }
 
-export { type AliasResult, AsyncStorageAdapter, type AuditRail, type Breadcrumb, type BreadcrumbCategory, type BreadcrumbLevel, type CapturedError, type ConsentState, Crossdeck, CrossdeckClient, CrossdeckError, type CrossdeckErrorPayload, type CrossdeckErrorType, type CrossdeckOptions, DEFAULT_BASE_URL, type DeviceInfo, type Diagnostics, type EntitlementsListResponse, type EntitlementsListener, type Environment, type ErrorLevel, type EventProperties, type GroupTraits, type HeartbeatResponse, type IdentifyOptions, type KeyValueStorage, MemoryStorage, type Platform, type PublicEntitlement, type PurchaseResult, SDK_NAME, SDK_VERSION, type StackFrame, parseRetryAfterHeader, scrubPii, scrubPiiFromProperties };
+export { type AliasResult, AsyncStorageAdapter, type AuditRail, type Breadcrumb, type BreadcrumbCategory, type BreadcrumbLevel, type CapturedError, type ConsentState, type Contract, type ContractAppliesTo, type ContractFailureInput, type ContractPillar, type ContractStatus, type ContractTestRef, Crossdeck, CrossdeckClient, CrossdeckContracts, CrossdeckError, type CrossdeckErrorPayload, type CrossdeckErrorType, type CrossdeckOptions, DEFAULT_BASE_URL, type DeviceInfo, type Diagnostics, type EntitlementsListResponse, type EntitlementsListener, type Environment, type ErrorLevel, type EventProperties, type GroupTraits, type HeartbeatResponse, type IdentifyOptions, type KeyValueStorage, MemoryStorage, type Platform, type PublicEntitlement, type PurchaseResult, SDK_NAME, SDK_VERSION, type StackFrame, parseRetryAfterHeader, scrubPii, scrubPiiFromProperties };

package/dist/index.d.ts

@@ -58,6 +58,10 @@ interface PurchaseResult {
     crossdeckCustomerId: string;
     env: Environment;
     entitlements: PublicEntitlement[];
+    /** True when the response came from the backend's idempotency
+     * cache instead of fresh processing. Backend also returns
+     * `Idempotent-Replayed: true` as a response header (v1.4.0). */
+    idempotent_replay?: boolean;
 }
 interface HeartbeatResponse {
     object: "heartbeat";
@@ -140,6 +144,37 @@ interface CrossdeckOptions {
      * validators don't reject.
      */
     platform?: Platform;
+    /**
+     * iOS Bundle ID (e.g. `com.acme.app`). REQUIRED for iOS builds.
+     * Sent as `X-Crossdeck-Bundle-Id` on every request so the backend
+     * can enforce the bank-grade identity lock against the bundleId
+     * stored on the iOS app key. Without it, every iOS request is
+     * rejected with 403 / bundle_id_not_allowed.
+     *
+     * Source the value from your native shell:
+     *   * Expo: `import { applicationId } from "expo-application"`
+     *   * Bare RN: `react-native-device-info.getBundleId()` or
+     *     `NativeModules.PlatformConstants.bundleId`.
+     *
+     * Safe to set on Android too — the backend ignores it for non-iOS
+     * platforms, so a single config object works for both runtimes.
+     */
+    bundleId?: string;
+    /**
+     * Android applicationId / package name (e.g. `com.acme.app`).
+     * REQUIRED for Android builds. Sent as `X-Crossdeck-Package-Name`
+     * on every request so the backend can enforce the bank-grade
+     * identity lock against the packageName stored on the Android
+     * app key. Without it, every Android request is rejected with
+     * 403 / package_name_not_allowed.
+     *
+     * Source from:
+     *   * Expo: `import { applicationId } from "expo-application"`
+     *     (same field on Android)
+     *   * Bare RN: `NativeModules.PlatformConstants.packageName` /
+     *     `react-native-device-info.getBundleId()`.
+     */
+    packageName?: string;
     /**
      * Per-request timeout in ms. Default 15000. A captive portal or
      * hung connection would otherwise inherit the runtime's default
@@ -392,6 +427,108 @@ interface Breadcrumb {
     data?: Record<string, unknown>;
 }
 
+/**
+ * Public, typed accessor for the bank-grade behavioural contracts
+ * this SDK ships. The full architecture — schema, distribution,
+ * audit loop, pillar taxonomy — lives in `contracts/README.md`
+ * at the monorepo root.
+ *
+ * Why a typed surface (vs. plain JSON access): contract IDs and
+ * pillar names are part of Crossdeck's public commitment to
+ * customers. Reading them through `CrossdeckContracts` means the
+ * compiler catches drift the moment a contract is renamed or
+ * retired. Tools that consume contracts at runtime (dashboards,
+ * AI assistants, customer integration tests) get the exact same
+ * shape every SDK ships, with no parsing layer to drift.
+ *
+ * --- BINARY STABILITY ---
+ * `Contract` is treated as an evolving — but back-compat — wire
+ * shape. Fields may be added in any minor release. Existing
+ * fields will not be removed or repurposed except in a major
+ * version bump, even if all known contracts stop using them.
+ * Customers can rely on `id`, `pillar`, `status`, `appliesTo`,
+ * `codeRef`, `testRef`, `registeredAt`, `firstRegisteredIn`,
+ * and `bundledIn` being present on every contract in every
+ * future minor/patch release of this SDK.
+ */
+type ContractPillar = "revenue" | "entitlements" | "analytics" | "webhooks" | "errors" | "lifecycle" | "identity";
+type ContractStatus = "enforced" | "proposed" | "retired";
+type ContractAppliesTo = "web" | "node" | "react-native" | "swift" | "android" | "backend";
+interface ContractTestRef {
+    readonly file: string;
+    readonly name: string;
+}
+interface Contract {
+    readonly id: string;
+    readonly pillar: ContractPillar;
+    readonly status: ContractStatus;
+    readonly claim: string;
+    readonly appliesTo: readonly ContractAppliesTo[];
+    readonly codeRef: readonly string[];
+    readonly testRef: readonly ContractTestRef[];
+    readonly registeredAt: string;
+    readonly firstRegisteredIn: string;
+    readonly bundledIn: string;
+}
+/**
+ * Typed entry point to the bank-grade contracts bundled with this
+ * SDK release. Stable, side-effect-free, tree-shakeable.
+ *
+ * @example Audit at app boot
+ * ```ts
+ * import { CrossdeckContracts } from "@cross-deck/react-native";
+ *
+ * for (const c of CrossdeckContracts.all()) {
+ *   console.log(`[crossdeck] ${c.id} (${c.pillar})`);
+ * }
+ * ```
+ */
+declare const CrossdeckContracts: {
+    readonly all: () => readonly Contract[];
+    readonly allIncludingHistorical: () => readonly Contract[];
+    readonly byId: (id: string) => Contract | undefined;
+    readonly byPillar: (pillar: ContractPillar) => readonly Contract[];
+    readonly withStatus: (status: ContractStatus) => readonly Contract[];
+    readonly sdkVersion: "1.5.1";
+    readonly bundledIn: "@cross-deck/react-native@1.5.1";
+    /**
+     * Resolve a failing test back to the contract it exercises.
+     * Used by test-framework hooks to find the contract id of a
+     * failed contract test so `reportContractFailure(...)` can stamp
+     * the right `contract_id` on the emitted event.
+     */
+    readonly findByTestName: (name: string) => Contract | undefined;
+};
+/**
+ * Input to {@link Crossdeck.reportContractFailure}.
+ *
+ * SCHEMA-LOCK: this interface's field set is exhaustively named. No
+ * free-form `extra: Record<string, unknown>` — the schema-lock
+ * contract at
+ * `contracts/diagnostics/contract-failed-payload-schema-lock.json`
+ * forbids unbounded fields.
+ */
+interface ContractFailureInput {
+    contractId: string;
+    /**
+     * Short categorical-ish label — the SDK convention is to keep
+     * this under 128 chars and stable across runs. Never an
+     * end-user-supplied string.
+     */
+    failureReason: string;
+    runContext: "ci" | "dogfood" | "customer-app";
+    runId: string;
+    testRef?: {
+        file: string;
+        name: string;
+    };
+    /**
+     * Optional coarse device class, e.g. "ios-phone", "android-tablet".
+     * A categorical bucket, not a device identifier.
+     */
+    deviceClass?: string;
+}
+
 /**
  * Stack-trace parser — normalises Hermes / JSC / V8 stack strings
  * into a common frame shape.
@@ -642,6 +779,17 @@ declare class CrossdeckClient {
      * stamped. Common-case `track()` after hydration runs entirely
      * synchronously.
      */
+    /**
+     * Emit `crossdeck.contract_failed` to the Crossdeck reliability
+     * endpoint — single-fire, one-way, never visible in the customer's
+     * dashboard. Goes over a dedicated HTTP path with the reliability
+     * publishable key embedded at build time; the customer's track()
+     * pipeline never carries `crossdeck.*` events. This is the
+     * independent-controller flow described in Privacy Policy §6
+     * ("Flow B"). The wire shape is fixed by the schema-lock contract
+     * at `contracts/diagnostics/contract-failed-payload-schema-lock.json`.
+     */
+    reportContractFailure(input: ContractFailureInput): void;
     track(name: string, properties?: EventProperties): void;
     /**
      * The body of `track()` — everything after the synchronous
@@ -665,6 +813,33 @@ declare class CrossdeckClient {
         purchaseToken?: string;
         appAccountToken?: string;
     }): Promise<PurchaseResult>;
+    /**
+     * v1.4.0 Phase 3.4 — set the active session id. RN doesn't own
+     * session lifecycle (that's the host's AppState + nav library);
+     * the host calls `setSessionId()` from its AppState change
+     * listener so every subsequent `track()` event carries the
+     * `sessionId` property — matches the web SDK's session-anchored
+     * funnel queries.
+     *
+     * ```ts
+     * import { AppState } from "react-native";
+     *
+     * let sessionId = uuid();
+     * AppState.addEventListener("change", (next) => {
+     *   if (next === "active") {
+     *     // New session if backgrounded > 30 min.
+     *     sessionId = uuid();
+     *     Crossdeck.setSessionId(sessionId);
+     *   } else if (next === "background") {
+     *     void Crossdeck.flush();
+     *   }
+     * });
+     * Crossdeck.setSessionId(sessionId);
+     * ```
+     *
+     * Pass `null` to clear (between sessions, on logout, etc).
+     */
+    setSessionId(sessionId: string | null): void;
     /** Toggle verbose diagnostic logging. */
     setDebugMode(enabled: boolean): void;
     /**
@@ -837,7 +1012,7 @@ declare class AsyncStorageAdapter implements KeyValueStorage {
  *
  * Do NOT edit by hand — `node scripts/sync-sdk-versions.mjs`.
  */
-declare const SDK_VERSION = "1.0.0";
+declare const SDK_VERSION = "1.5.1";
 declare const SDK_NAME = "@cross-deck/react-native";
 
 /**
@@ -900,4 +1075,4 @@ interface DeviceInfo {
     appVersion?: string;
 }
 
-export { type AliasResult, AsyncStorageAdapter, type AuditRail, type Breadcrumb, type BreadcrumbCategory, type BreadcrumbLevel, type CapturedError, type ConsentState, Crossdeck, CrossdeckClient, CrossdeckError, type CrossdeckErrorPayload, type CrossdeckErrorType, type CrossdeckOptions, DEFAULT_BASE_URL, type DeviceInfo, type Diagnostics, type EntitlementsListResponse, type EntitlementsListener, type Environment, type ErrorLevel, type EventProperties, type GroupTraits, type HeartbeatResponse, type IdentifyOptions, type KeyValueStorage, MemoryStorage, type Platform, type PublicEntitlement, type PurchaseResult, SDK_NAME, SDK_VERSION, type StackFrame, parseRetryAfterHeader, scrubPii, scrubPiiFromProperties };
+export { type AliasResult, AsyncStorageAdapter, type AuditRail, type Breadcrumb, type BreadcrumbCategory, type BreadcrumbLevel, type CapturedError, type ConsentState, type Contract, type ContractAppliesTo, type ContractFailureInput, type ContractPillar, type ContractStatus, type ContractTestRef, Crossdeck, CrossdeckClient, CrossdeckContracts, CrossdeckError, type CrossdeckErrorPayload, type CrossdeckErrorType, type CrossdeckOptions, DEFAULT_BASE_URL, type DeviceInfo, type Diagnostics, type EntitlementsListResponse, type EntitlementsListener, type Environment, type ErrorLevel, type EventProperties, type GroupTraits, type HeartbeatResponse, type IdentifyOptions, type KeyValueStorage, MemoryStorage, type Platform, type PublicEntitlement, type PurchaseResult, SDK_NAME, SDK_VERSION, type StackFrame, parseRetryAfterHeader, scrubPii, scrubPiiFromProperties };