@cross-deck/web 1.4.2 → 1.5.0

package/dist/index.d.mts

@@ -128,6 +128,167 @@ 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.
+ */
+/**
+ * Which bank-grade pillar a contract belongs to. The taxonomy is
+ * deliberately small — every contract maps to exactly one. New
+ * pillars require a Crossdeck major-version bump.
+ */
+type ContractPillar = "revenue" | "entitlements" | "analytics" | "webhooks" | "errors" | "lifecycle" | "identity";
+/**
+ * Lifecycle stage of a contract.
+ * - `enforced`: live in this SDK and exercised by `testRef`.
+ * - `proposed`: registered for an upcoming release; `testRef`
+ *    may point to a not-yet-existing file.
+ * - `retired`: kept for history only; the behaviour no longer
+ *    ships. Filtered out of `CrossdeckContracts.all()` by default.
+ */
+type ContractStatus = "enforced" | "proposed" | "retired";
+/** Which SDKs (and/or `backend`) a contract is binding on. */
+type ContractAppliesTo = "web" | "node" | "react-native" | "swift" | "android" | "backend";
+/**
+ * Pointer to the test that exercises a contract clause. The
+ * `name` is matched verbatim against the file's text by
+ * `scripts/contract-audit.mjs`, so a rename without updating
+ * the contract aborts CI.
+ */
+interface ContractTestRef {
+    readonly file: string;
+    readonly name: string;
+}
+/** One bank-grade behavioural guarantee — see `contracts/README.md`. */
+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[];
+    /** ISO-8601 date the contract was first registered. */
+    readonly registeredAt: string;
+    /** The release note / phase the contract first appeared in. Immutable. */
+    readonly firstRegisteredIn: string;
+    /** The SDK release this snapshot was bundled with, stamped at build time. */
+    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/web";
+ *
+ * for (const c of CrossdeckContracts.all()) {
+ *   console.log(`[crossdeck] ${c.id} (${c.pillar})`);
+ * }
+ * ```
+ *
+ * @example Assert a specific clause is in force
+ * ```ts
+ * const isolation = CrossdeckContracts.byId("per-user-cache-isolation");
+ * if (!isolation || isolation.status !== "enforced") {
+ *   throw new Error("entitlement isolation contract is not enforced — refusing to start");
+ * }
+ * ```
+ */
+declare const CrossdeckContracts: {
+    /** Every contract that applies to this SDK and is currently enforced. */
+    readonly all: () => readonly Contract[];
+    /**
+     * Every contract bundled with this SDK release, including
+     * `proposed` and `retired` entries. Use `all()` for the
+     * enforced-only view.
+     */
+    readonly allIncludingHistorical: () => readonly Contract[];
+    /** Look up a contract by its stable `id`. */
+    readonly byId: (id: string) => Contract | undefined;
+    /** Every enforced contract within a pillar. */
+    readonly byPillar: (pillar: ContractPillar) => readonly Contract[];
+    /** Filter by lifecycle status. */
+    readonly withStatus: (status: ContractStatus) => readonly Contract[];
+    /** Semver of the SDK release these contracts were bundled with. */
+    readonly sdkVersion: "1.5.0";
+    /** Fully-qualified bundle identifier — e.g. `@cross-deck/web@1.4.2`. */
+    readonly bundledIn: "@cross-deck/web@1.5.0";
+    /**
+     * 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.
+     */
+    readonly findByTestName: (name: string) => Contract | undefined;
+};
+/**
+ * Input to {@link Crossdeck.reportContractFailure}. Lets a test
+ * harness / dogfood app / customer integration report a contract
+ * violation back to Crossdeck through the standard `track()` API
+ * with a typed property bag — no new ingest endpoint, no bespoke
+ * code, just a `crossdeck.contract_failed` custom event.
+ *
+ * `sdk_version` and `sdk_platform` are auto-stamped by the SDK so
+ * every emitted event carries them correctly without the caller
+ * needing to read them out of `CrossdeckContracts.sdkVersion`.
+ */
+interface ContractFailureInput {
+    /** Stable contract id (`per-user-cache-isolation` etc.). */
+    contractId: string;
+    /** Human-readable failure reason — the assertion message. */
+    failureReason: string;
+    /**
+     * Where the failure was observed:
+     *   - `ci`            — the SDK's own test suite on CI
+     *   - `dogfood`       — Crossdeck's internal dogfood project
+     *   - `customer-app`  — a customer's app verifying contracts
+     */
+    runContext: "ci" | "dogfood" | "customer-app";
+    /**
+     * Stable identifier for this verification run. CI: `GITHUB_RUN_ID`
+     * or equivalent. Dogfood: per-launch UUID. Customer app: any
+     * stable handle the customer chooses to group fires by run.
+     */
+    runId: string;
+    /**
+     * Optional pointer back to the failing test, for triage. The SDK
+     * sends both `test_file` and `test_name` on the wire when set.
+     */
+    testRef?: {
+        file: string;
+        name: string;
+    };
+    /** Optional extra properties merged into the event payload. */
+    extra?: Record<string, unknown>;
+}
+
 /**
  * Stack-trace parser — normalises Chrome / Firefox / Safari / Edge
  * stack strings into a common frame shape.
@@ -478,6 +639,18 @@ declare class CrossdeckClient {
      * 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: ContractFailureInput): void;
     track(name: string, properties?: EventProperties): void;
     /**
      * Force-flush queued events. Useful to call from page-unload handlers.
@@ -762,4 +935,4 @@ interface DeviceInfo {
     appVersion?: string;
 }
 
-export { AliasResult, type Breadcrumb, type BreadcrumbCategory, type BreadcrumbLevel, CROSSDECK_ERROR_CODES, type CapturedError, type ConsentState, Crossdeck, CrossdeckClient, CrossdeckError, type CrossdeckErrorPayload, type CrossdeckErrorType, CrossdeckOptions, DEFAULT_BASE_URL, type DeviceInfo, Diagnostics, type ErrorCodeEntry, type ErrorLevel, EventProperties, GroupTraits, HeartbeatResponse, IdentifyOptions, KeyValueStorage, MemoryStorage, PublicEntitlement, PurchaseResult, SDK_NAME, SDK_VERSION, type StackFrame, getErrorCode };
+export { AliasResult, type Breadcrumb, type BreadcrumbCategory, type BreadcrumbLevel, CROSSDECK_ERROR_CODES, type CapturedError, type ConsentState, type Contract, type ContractAppliesTo, type ContractFailureInput, type ContractPillar, type ContractStatus, type ContractTestRef, Crossdeck, CrossdeckClient, CrossdeckContracts, CrossdeckError, type CrossdeckErrorPayload, type CrossdeckErrorType, CrossdeckOptions, DEFAULT_BASE_URL, type DeviceInfo, Diagnostics, type ErrorCodeEntry, type ErrorLevel, EventProperties, GroupTraits, HeartbeatResponse, IdentifyOptions, KeyValueStorage, MemoryStorage, PublicEntitlement, PurchaseResult, SDK_NAME, SDK_VERSION, type StackFrame, getErrorCode };

package/dist/index.d.ts

@@ -128,6 +128,167 @@ 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.
+ */
+/**
+ * Which bank-grade pillar a contract belongs to. The taxonomy is
+ * deliberately small — every contract maps to exactly one. New
+ * pillars require a Crossdeck major-version bump.
+ */
+type ContractPillar = "revenue" | "entitlements" | "analytics" | "webhooks" | "errors" | "lifecycle" | "identity";
+/**
+ * Lifecycle stage of a contract.
+ * - `enforced`: live in this SDK and exercised by `testRef`.
+ * - `proposed`: registered for an upcoming release; `testRef`
+ *    may point to a not-yet-existing file.
+ * - `retired`: kept for history only; the behaviour no longer
+ *    ships. Filtered out of `CrossdeckContracts.all()` by default.
+ */
+type ContractStatus = "enforced" | "proposed" | "retired";
+/** Which SDKs (and/or `backend`) a contract is binding on. */
+type ContractAppliesTo = "web" | "node" | "react-native" | "swift" | "android" | "backend";
+/**
+ * Pointer to the test that exercises a contract clause. The
+ * `name` is matched verbatim against the file's text by
+ * `scripts/contract-audit.mjs`, so a rename without updating
+ * the contract aborts CI.
+ */
+interface ContractTestRef {
+    readonly file: string;
+    readonly name: string;
+}
+/** One bank-grade behavioural guarantee — see `contracts/README.md`. */
+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[];
+    /** ISO-8601 date the contract was first registered. */
+    readonly registeredAt: string;
+    /** The release note / phase the contract first appeared in. Immutable. */
+    readonly firstRegisteredIn: string;
+    /** The SDK release this snapshot was bundled with, stamped at build time. */
+    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/web";
+ *
+ * for (const c of CrossdeckContracts.all()) {
+ *   console.log(`[crossdeck] ${c.id} (${c.pillar})`);
+ * }
+ * ```
+ *
+ * @example Assert a specific clause is in force
+ * ```ts
+ * const isolation = CrossdeckContracts.byId("per-user-cache-isolation");
+ * if (!isolation || isolation.status !== "enforced") {
+ *   throw new Error("entitlement isolation contract is not enforced — refusing to start");
+ * }
+ * ```
+ */
+declare const CrossdeckContracts: {
+    /** Every contract that applies to this SDK and is currently enforced. */
+    readonly all: () => readonly Contract[];
+    /**
+     * Every contract bundled with this SDK release, including
+     * `proposed` and `retired` entries. Use `all()` for the
+     * enforced-only view.
+     */
+    readonly allIncludingHistorical: () => readonly Contract[];
+    /** Look up a contract by its stable `id`. */
+    readonly byId: (id: string) => Contract | undefined;
+    /** Every enforced contract within a pillar. */
+    readonly byPillar: (pillar: ContractPillar) => readonly Contract[];
+    /** Filter by lifecycle status. */
+    readonly withStatus: (status: ContractStatus) => readonly Contract[];
+    /** Semver of the SDK release these contracts were bundled with. */
+    readonly sdkVersion: "1.5.0";
+    /** Fully-qualified bundle identifier — e.g. `@cross-deck/web@1.4.2`. */
+    readonly bundledIn: "@cross-deck/web@1.5.0";
+    /**
+     * 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.
+     */
+    readonly findByTestName: (name: string) => Contract | undefined;
+};
+/**
+ * Input to {@link Crossdeck.reportContractFailure}. Lets a test
+ * harness / dogfood app / customer integration report a contract
+ * violation back to Crossdeck through the standard `track()` API
+ * with a typed property bag — no new ingest endpoint, no bespoke
+ * code, just a `crossdeck.contract_failed` custom event.
+ *
+ * `sdk_version` and `sdk_platform` are auto-stamped by the SDK so
+ * every emitted event carries them correctly without the caller
+ * needing to read them out of `CrossdeckContracts.sdkVersion`.
+ */
+interface ContractFailureInput {
+    /** Stable contract id (`per-user-cache-isolation` etc.). */
+    contractId: string;
+    /** Human-readable failure reason — the assertion message. */
+    failureReason: string;
+    /**
+     * Where the failure was observed:
+     *   - `ci`            — the SDK's own test suite on CI
+     *   - `dogfood`       — Crossdeck's internal dogfood project
+     *   - `customer-app`  — a customer's app verifying contracts
+     */
+    runContext: "ci" | "dogfood" | "customer-app";
+    /**
+     * Stable identifier for this verification run. CI: `GITHUB_RUN_ID`
+     * or equivalent. Dogfood: per-launch UUID. Customer app: any
+     * stable handle the customer chooses to group fires by run.
+     */
+    runId: string;
+    /**
+     * Optional pointer back to the failing test, for triage. The SDK
+     * sends both `test_file` and `test_name` on the wire when set.
+     */
+    testRef?: {
+        file: string;
+        name: string;
+    };
+    /** Optional extra properties merged into the event payload. */
+    extra?: Record<string, unknown>;
+}
+
 /**
  * Stack-trace parser — normalises Chrome / Firefox / Safari / Edge
  * stack strings into a common frame shape.
@@ -478,6 +639,18 @@ declare class CrossdeckClient {
      * 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: ContractFailureInput): void;
     track(name: string, properties?: EventProperties): void;
     /**
      * Force-flush queued events. Useful to call from page-unload handlers.
@@ -762,4 +935,4 @@ interface DeviceInfo {
     appVersion?: string;
 }
 
-export { AliasResult, type Breadcrumb, type BreadcrumbCategory, type BreadcrumbLevel, CROSSDECK_ERROR_CODES, type CapturedError, type ConsentState, Crossdeck, CrossdeckClient, CrossdeckError, type CrossdeckErrorPayload, type CrossdeckErrorType, CrossdeckOptions, DEFAULT_BASE_URL, type DeviceInfo, Diagnostics, type ErrorCodeEntry, type ErrorLevel, EventProperties, GroupTraits, HeartbeatResponse, IdentifyOptions, KeyValueStorage, MemoryStorage, PublicEntitlement, PurchaseResult, SDK_NAME, SDK_VERSION, type StackFrame, getErrorCode };
+export { AliasResult, type Breadcrumb, type BreadcrumbCategory, type BreadcrumbLevel, CROSSDECK_ERROR_CODES, type CapturedError, type ConsentState, type Contract, type ContractAppliesTo, type ContractFailureInput, type ContractPillar, type ContractStatus, type ContractTestRef, Crossdeck, CrossdeckClient, CrossdeckContracts, CrossdeckError, type CrossdeckErrorPayload, type CrossdeckErrorType, CrossdeckOptions, DEFAULT_BASE_URL, type DeviceInfo, Diagnostics, type ErrorCodeEntry, type ErrorLevel, EventProperties, GroupTraits, HeartbeatResponse, IdentifyOptions, KeyValueStorage, MemoryStorage, PublicEntitlement, PurchaseResult, SDK_NAME, SDK_VERSION, type StackFrame, getErrorCode };