@cross-deck/web 1.5.2 → 1.5.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/contracts.json +500 -0
- package/dist/crossdeck.umd.min.js +2 -2
- package/dist/crossdeck.umd.min.js.map +1 -1
- package/dist/error-codes.json +106 -1
- package/dist/index.cjs +1998 -24
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.mts +212 -4
- package/dist/index.d.ts +212 -4
- package/dist/index.mjs +1997 -24
- package/dist/index.mjs.map +1 -1
- package/dist/react.cjs +1340 -24
- package/dist/react.cjs.map +1 -1
- package/dist/react.d.mts +1 -1
- package/dist/react.d.ts +1 -1
- package/dist/react.mjs +1340 -24
- package/dist/react.mjs.map +1 -1
- package/dist/{types-BzoKor4z.d.mts → types-B9sxUuKh.d.mts} +75 -0
- package/dist/{types-BzoKor4z.d.ts → types-B9sxUuKh.d.ts} +75 -0
- package/dist/vue.cjs +1340 -24
- package/dist/vue.cjs.map +1 -1
- package/dist/vue.mjs +1340 -24
- package/dist/vue.mjs.map +1 -1
- package/package.json +1 -1
package/dist/index.d.mts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
|
-
import { P as PublicEntitlement, C as CrossdeckOptions, I as IdentifyOptions, A as AliasResult, G as GroupTraits, E as EventProperties, a as PurchaseResult, H as HeartbeatResponse, D as Diagnostics, K as KeyValueStorage } from './types-
|
|
2
|
-
export { b as AuditRail, c as AutoTrackOptions, d as EntitlementsListResponse, e as Environment, f as Platform } from './types-
|
|
1
|
+
import { P as PublicEntitlement, C as CrossdeckOptions, I as IdentifyOptions, A as AliasResult, G as GroupTraits, E as EventProperties, a as PurchaseResult, H as HeartbeatResponse, D as Diagnostics, K as KeyValueStorage } from './types-B9sxUuKh.mjs';
|
|
2
|
+
export { b as AuditRail, c as AutoTrackOptions, d as EntitlementsListResponse, e as Environment, f as Platform } from './types-B9sxUuKh.mjs';
|
|
3
3
|
|
|
4
4
|
/**
|
|
5
5
|
* Durable last-known-good cache of the customer's entitlements.
|
|
@@ -128,6 +128,180 @@ interface Breadcrumb {
|
|
|
128
128
|
data?: Record<string, unknown>;
|
|
129
129
|
}
|
|
130
130
|
|
|
131
|
+
/**
|
|
132
|
+
* Public, typed accessor for the bank-grade behavioural contracts
|
|
133
|
+
* this SDK ships. The full architecture — schema, distribution,
|
|
134
|
+
* audit loop, pillar taxonomy — lives in `contracts/README.md`
|
|
135
|
+
* at the monorepo root.
|
|
136
|
+
*
|
|
137
|
+
* Why a typed surface (vs. plain JSON access): contract IDs and
|
|
138
|
+
* pillar names are part of Crossdeck's public commitment to
|
|
139
|
+
* customers. Reading them through `CrossdeckContracts` means the
|
|
140
|
+
* compiler catches drift the moment a contract is renamed or
|
|
141
|
+
* retired. Tools that consume contracts at runtime (dashboards,
|
|
142
|
+
* AI assistants, customer integration tests) get the exact same
|
|
143
|
+
* shape every SDK ships, with no parsing layer to drift.
|
|
144
|
+
*
|
|
145
|
+
* --- BINARY STABILITY ---
|
|
146
|
+
* `Contract` is treated as an evolving — but back-compat — wire
|
|
147
|
+
* shape. Fields may be added in any minor release. Existing
|
|
148
|
+
* fields will not be removed or repurposed except in a major
|
|
149
|
+
* version bump, even if all known contracts stop using them.
|
|
150
|
+
* Customers can rely on `id`, `pillar`, `status`, `appliesTo`,
|
|
151
|
+
* `codeRef`, `testRef`, `registeredAt`, `firstRegisteredIn`,
|
|
152
|
+
* and `bundledIn` being present on every contract in every
|
|
153
|
+
* future minor/patch release of this SDK.
|
|
154
|
+
*/
|
|
155
|
+
/**
|
|
156
|
+
* Which bank-grade pillar a contract belongs to. The taxonomy is
|
|
157
|
+
* deliberately small — every contract maps to exactly one. New
|
|
158
|
+
* pillars require a Crossdeck major-version bump.
|
|
159
|
+
*/
|
|
160
|
+
type ContractPillar = "revenue" | "entitlements" | "analytics" | "webhooks" | "errors" | "lifecycle" | "identity";
|
|
161
|
+
/**
|
|
162
|
+
* Lifecycle stage of a contract.
|
|
163
|
+
* - `enforced`: live in this SDK and exercised by `testRef`.
|
|
164
|
+
* - `proposed`: registered for an upcoming release; `testRef`
|
|
165
|
+
* may point to a not-yet-existing file.
|
|
166
|
+
* - `retired`: kept for history only; the behaviour no longer
|
|
167
|
+
* ships. Filtered out of `CrossdeckContracts.all()` by default.
|
|
168
|
+
*/
|
|
169
|
+
type ContractStatus = "enforced" | "proposed" | "retired";
|
|
170
|
+
/** Which SDKs (and/or `backend`) a contract is binding on. */
|
|
171
|
+
type ContractAppliesTo = "web" | "node" | "react-native" | "swift" | "android" | "backend";
|
|
172
|
+
/**
|
|
173
|
+
* Pointer to the test that exercises a contract clause. The
|
|
174
|
+
* `name` is matched verbatim against the file's text by
|
|
175
|
+
* `scripts/contract-audit.mjs`, so a rename without updating
|
|
176
|
+
* the contract aborts CI.
|
|
177
|
+
*/
|
|
178
|
+
interface ContractTestRef {
|
|
179
|
+
readonly file: string;
|
|
180
|
+
readonly name: string;
|
|
181
|
+
}
|
|
182
|
+
/** One bank-grade behavioural guarantee — see `contracts/README.md`. */
|
|
183
|
+
interface Contract {
|
|
184
|
+
readonly id: string;
|
|
185
|
+
readonly pillar: ContractPillar;
|
|
186
|
+
readonly status: ContractStatus;
|
|
187
|
+
readonly claim: string;
|
|
188
|
+
readonly appliesTo: readonly ContractAppliesTo[];
|
|
189
|
+
readonly codeRef: readonly string[];
|
|
190
|
+
readonly testRef: readonly ContractTestRef[];
|
|
191
|
+
/** ISO-8601 date the contract was first registered. */
|
|
192
|
+
readonly registeredAt: string;
|
|
193
|
+
/** The release note / phase the contract first appeared in. Immutable. */
|
|
194
|
+
readonly firstRegisteredIn: string;
|
|
195
|
+
/** The SDK release this snapshot was bundled with, stamped at build time. */
|
|
196
|
+
readonly bundledIn: string;
|
|
197
|
+
}
|
|
198
|
+
/**
|
|
199
|
+
* Typed entry point to the bank-grade contracts bundled with this
|
|
200
|
+
* SDK release. Stable, side-effect-free, tree-shakeable.
|
|
201
|
+
*
|
|
202
|
+
* @example Audit at app boot
|
|
203
|
+
* ```ts
|
|
204
|
+
* import { CrossdeckContracts } from "@cross-deck/web";
|
|
205
|
+
*
|
|
206
|
+
* for (const c of CrossdeckContracts.all()) {
|
|
207
|
+
* console.log(`[crossdeck] ${c.id} (${c.pillar})`);
|
|
208
|
+
* }
|
|
209
|
+
* ```
|
|
210
|
+
*
|
|
211
|
+
* @example Assert a specific clause is in force
|
|
212
|
+
* ```ts
|
|
213
|
+
* const isolation = CrossdeckContracts.byId("per-user-cache-isolation");
|
|
214
|
+
* if (!isolation || isolation.status !== "enforced") {
|
|
215
|
+
* throw new Error("entitlement isolation contract is not enforced — refusing to start");
|
|
216
|
+
* }
|
|
217
|
+
* ```
|
|
218
|
+
*/
|
|
219
|
+
declare const CrossdeckContracts: {
|
|
220
|
+
/** Every contract that applies to this SDK and is currently enforced. */
|
|
221
|
+
readonly all: () => readonly Contract[];
|
|
222
|
+
/**
|
|
223
|
+
* Every contract bundled with this SDK release, including
|
|
224
|
+
* `proposed` and `retired` entries. Use `all()` for the
|
|
225
|
+
* enforced-only view.
|
|
226
|
+
*/
|
|
227
|
+
readonly allIncludingHistorical: () => readonly Contract[];
|
|
228
|
+
/** Look up a contract by its stable `id`. */
|
|
229
|
+
readonly byId: (id: string) => Contract | undefined;
|
|
230
|
+
/** Every enforced contract within a pillar. */
|
|
231
|
+
readonly byPillar: (pillar: ContractPillar) => readonly Contract[];
|
|
232
|
+
/** Filter by lifecycle status. */
|
|
233
|
+
readonly withStatus: (status: ContractStatus) => readonly Contract[];
|
|
234
|
+
/** Semver of the SDK release these contracts were bundled with. */
|
|
235
|
+
readonly sdkVersion: "1.5.3";
|
|
236
|
+
/** Fully-qualified bundle identifier — e.g. `@cross-deck/web@1.4.2`. */
|
|
237
|
+
readonly bundledIn: "@cross-deck/web@1.5.3";
|
|
238
|
+
/**
|
|
239
|
+
* Resolve a failing test back to the contract it exercises.
|
|
240
|
+
* Used by test-framework hooks (Vitest `afterEach`, XCTest
|
|
241
|
+
* observation, JUnit `TestWatcher`) to find the contract id of
|
|
242
|
+
* a failed contract test so `reportContractFailure(...)` can
|
|
243
|
+
* stamp the right `contract_id` on the emitted event.
|
|
244
|
+
*
|
|
245
|
+
* Match is on `testRef.name` (case-sensitive, exact). Returns
|
|
246
|
+
* the first contract whose `testRef` list contains a matching
|
|
247
|
+
* entry, regardless of pillar or status.
|
|
248
|
+
*/
|
|
249
|
+
readonly findByTestName: (name: string) => Contract | undefined;
|
|
250
|
+
};
|
|
251
|
+
/**
|
|
252
|
+
* Input to {@link Crossdeck.reportContractFailure}. Lets a test
|
|
253
|
+
* harness / dogfood app / customer integration report a contract
|
|
254
|
+
* violation back to Crossdeck on the dedicated reliability channel —
|
|
255
|
+
* single-fire, never visible in the customer's dashboard.
|
|
256
|
+
*
|
|
257
|
+
* SCHEMA-LOCK: this interface's field set is exhaustively named. No
|
|
258
|
+
* free-form `extra: Record<string, unknown>` — the schema-lock
|
|
259
|
+
* contract at
|
|
260
|
+
* `contracts/diagnostics/contract-failed-payload-schema-lock.json`
|
|
261
|
+
* forbids unbounded fields. Adding a field requires a PR that
|
|
262
|
+
* amends the contract first, then the public interface.
|
|
263
|
+
*
|
|
264
|
+
* `sdk_version` and `sdk_platform` are auto-stamped by the SDK so
|
|
265
|
+
* every emitted event carries them correctly without the caller
|
|
266
|
+
* needing to read them out of `CrossdeckContracts.sdkVersion`.
|
|
267
|
+
*/
|
|
268
|
+
interface ContractFailureInput {
|
|
269
|
+
/** Stable contract id (`per-user-cache-isolation` etc.). */
|
|
270
|
+
contractId: string;
|
|
271
|
+
/**
|
|
272
|
+
* Short categorical-ish label — the SDK convention is to keep this
|
|
273
|
+
* under 128 chars and stable across runs (so dashboards can group).
|
|
274
|
+
* Never an end-user-supplied string.
|
|
275
|
+
*/
|
|
276
|
+
failureReason: string;
|
|
277
|
+
/**
|
|
278
|
+
* Where the failure was observed:
|
|
279
|
+
* - `ci` — the SDK's own test suite on CI
|
|
280
|
+
* - `dogfood` — Crossdeck's internal dogfood project
|
|
281
|
+
* - `customer-app` — a customer's app verifying contracts
|
|
282
|
+
*/
|
|
283
|
+
runContext: "ci" | "dogfood" | "customer-app";
|
|
284
|
+
/**
|
|
285
|
+
* Stable identifier for this verification run. CI: `GITHUB_RUN_ID`
|
|
286
|
+
* or equivalent. Dogfood: per-launch UUID. Customer app: any
|
|
287
|
+
* stable handle the customer chooses to group fires by run.
|
|
288
|
+
*/
|
|
289
|
+
runId: string;
|
|
290
|
+
/**
|
|
291
|
+
* Optional pointer back to the failing test, for triage. The SDK
|
|
292
|
+
* sends both `test_file` and `test_name` on the wire when set.
|
|
293
|
+
*/
|
|
294
|
+
testRef?: {
|
|
295
|
+
file: string;
|
|
296
|
+
name: string;
|
|
297
|
+
};
|
|
298
|
+
/**
|
|
299
|
+
* Optional coarse device class, e.g. "desktop", "mobile-web",
|
|
300
|
+
* "ssr". A categorical bucket, not a device identifier.
|
|
301
|
+
*/
|
|
302
|
+
deviceClass?: string;
|
|
303
|
+
}
|
|
304
|
+
|
|
131
305
|
/**
|
|
132
306
|
* Stack-trace parser — normalises Chrome / Firefox / Safari / Edge
|
|
133
307
|
* stack strings into a common frame shape.
|
|
@@ -270,6 +444,9 @@ interface CapturedError {
|
|
|
270
444
|
|
|
271
445
|
declare class CrossdeckClient {
|
|
272
446
|
private state;
|
|
447
|
+
private verifiers;
|
|
448
|
+
private verifierReporter;
|
|
449
|
+
private verifierCtx;
|
|
273
450
|
/**
|
|
274
451
|
* Boot the SDK. Idempotent — calling init twice with the same options
|
|
275
452
|
* is a no-op; calling with different options replaces the previous
|
|
@@ -280,6 +457,22 @@ declare class CrossdeckClient {
|
|
|
280
457
|
* mismatched env fails fast at boot rather than at first event-flush.
|
|
281
458
|
*/
|
|
282
459
|
init(options: CrossdeckOptions): void;
|
|
460
|
+
/**
|
|
461
|
+
* Fetch /v1/config from the backend and apply any per-app verifier
|
|
462
|
+
* overrides set in the dashboard, then fire the boot self-test
|
|
463
|
+
* once with the FINAL resolved flags.
|
|
464
|
+
*
|
|
465
|
+
* Precedence (also documented at the call site in init()):
|
|
466
|
+
* code option > dashboard remote config > DEBUG/RELEASE default
|
|
467
|
+
*
|
|
468
|
+
* Code wins so engineers retain ultimate control; dashboard is the
|
|
469
|
+
* no-deploy operational lever for QA / staging soaks.
|
|
470
|
+
*
|
|
471
|
+
* Never throws — a /v1/config failure surfaces as "stick with the
|
|
472
|
+
* synchronous defaults that init() already applied" and the boot
|
|
473
|
+
* self-test runs only if code > default resolves true.
|
|
474
|
+
*/
|
|
475
|
+
private bootstrapVerifierLayerRemote;
|
|
283
476
|
/**
|
|
284
477
|
* @deprecated Use `init()` instead. NorthStar §4 standardised the
|
|
285
478
|
* lifecycle method name across SDKs as `init` (formerly `start` /
|
|
@@ -478,6 +671,21 @@ declare class CrossdeckClient {
|
|
|
478
671
|
* trip happens in the background. To flush before the page unloads,
|
|
479
672
|
* call flush().
|
|
480
673
|
*/
|
|
674
|
+
/**
|
|
675
|
+
* Emit `crossdeck.contract_failed` to the Crossdeck reliability
|
|
676
|
+
* endpoint — single-fire, one-way, never visible in the customer's
|
|
677
|
+
* dashboard. Goes over a dedicated HTTP path with the reliability
|
|
678
|
+
* publishable key embedded at build time; the customer's track()
|
|
679
|
+
* pipeline never carries `crossdeck.*` events. This is the
|
|
680
|
+
* independent-controller flow described in Privacy Policy §6
|
|
681
|
+
* ("Flow B"). The wire shape is fixed by the schema-lock contract
|
|
682
|
+
* at `contracts/diagnostics/contract-failed-payload-schema-lock.json`.
|
|
683
|
+
*
|
|
684
|
+
* Wire the call from a test hook, dogfood failure path, or
|
|
685
|
+
* customer contract-verification harness; see
|
|
686
|
+
* `contracts/README.md` for the per-test-framework hook recipes.
|
|
687
|
+
*/
|
|
688
|
+
reportContractFailure(input: ContractFailureInput): void;
|
|
481
689
|
track(name: string, properties?: EventProperties): void;
|
|
482
690
|
/**
|
|
483
691
|
* Force-flush queued events. Useful to call from page-unload handlers.
|
|
@@ -678,7 +886,7 @@ declare class MemoryStorage implements KeyValueStorage {
|
|
|
678
886
|
*
|
|
679
887
|
* Do NOT edit by hand — `node scripts/sync-sdk-versions.mjs`.
|
|
680
888
|
*/
|
|
681
|
-
declare const SDK_VERSION = "1.3
|
|
889
|
+
declare const SDK_VERSION = "1.5.3";
|
|
682
890
|
declare const SDK_NAME = "@cross-deck/web";
|
|
683
891
|
|
|
684
892
|
/**
|
|
@@ -762,4 +970,4 @@ interface DeviceInfo {
|
|
|
762
970
|
appVersion?: string;
|
|
763
971
|
}
|
|
764
972
|
|
|
765
|
-
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 };
|
|
973
|
+
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
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
|
-
import { P as PublicEntitlement, C as CrossdeckOptions, I as IdentifyOptions, A as AliasResult, G as GroupTraits, E as EventProperties, a as PurchaseResult, H as HeartbeatResponse, D as Diagnostics, K as KeyValueStorage } from './types-
|
|
2
|
-
export { b as AuditRail, c as AutoTrackOptions, d as EntitlementsListResponse, e as Environment, f as Platform } from './types-
|
|
1
|
+
import { P as PublicEntitlement, C as CrossdeckOptions, I as IdentifyOptions, A as AliasResult, G as GroupTraits, E as EventProperties, a as PurchaseResult, H as HeartbeatResponse, D as Diagnostics, K as KeyValueStorage } from './types-B9sxUuKh.js';
|
|
2
|
+
export { b as AuditRail, c as AutoTrackOptions, d as EntitlementsListResponse, e as Environment, f as Platform } from './types-B9sxUuKh.js';
|
|
3
3
|
|
|
4
4
|
/**
|
|
5
5
|
* Durable last-known-good cache of the customer's entitlements.
|
|
@@ -128,6 +128,180 @@ interface Breadcrumb {
|
|
|
128
128
|
data?: Record<string, unknown>;
|
|
129
129
|
}
|
|
130
130
|
|
|
131
|
+
/**
|
|
132
|
+
* Public, typed accessor for the bank-grade behavioural contracts
|
|
133
|
+
* this SDK ships. The full architecture — schema, distribution,
|
|
134
|
+
* audit loop, pillar taxonomy — lives in `contracts/README.md`
|
|
135
|
+
* at the monorepo root.
|
|
136
|
+
*
|
|
137
|
+
* Why a typed surface (vs. plain JSON access): contract IDs and
|
|
138
|
+
* pillar names are part of Crossdeck's public commitment to
|
|
139
|
+
* customers. Reading them through `CrossdeckContracts` means the
|
|
140
|
+
* compiler catches drift the moment a contract is renamed or
|
|
141
|
+
* retired. Tools that consume contracts at runtime (dashboards,
|
|
142
|
+
* AI assistants, customer integration tests) get the exact same
|
|
143
|
+
* shape every SDK ships, with no parsing layer to drift.
|
|
144
|
+
*
|
|
145
|
+
* --- BINARY STABILITY ---
|
|
146
|
+
* `Contract` is treated as an evolving — but back-compat — wire
|
|
147
|
+
* shape. Fields may be added in any minor release. Existing
|
|
148
|
+
* fields will not be removed or repurposed except in a major
|
|
149
|
+
* version bump, even if all known contracts stop using them.
|
|
150
|
+
* Customers can rely on `id`, `pillar`, `status`, `appliesTo`,
|
|
151
|
+
* `codeRef`, `testRef`, `registeredAt`, `firstRegisteredIn`,
|
|
152
|
+
* and `bundledIn` being present on every contract in every
|
|
153
|
+
* future minor/patch release of this SDK.
|
|
154
|
+
*/
|
|
155
|
+
/**
|
|
156
|
+
* Which bank-grade pillar a contract belongs to. The taxonomy is
|
|
157
|
+
* deliberately small — every contract maps to exactly one. New
|
|
158
|
+
* pillars require a Crossdeck major-version bump.
|
|
159
|
+
*/
|
|
160
|
+
type ContractPillar = "revenue" | "entitlements" | "analytics" | "webhooks" | "errors" | "lifecycle" | "identity";
|
|
161
|
+
/**
|
|
162
|
+
* Lifecycle stage of a contract.
|
|
163
|
+
* - `enforced`: live in this SDK and exercised by `testRef`.
|
|
164
|
+
* - `proposed`: registered for an upcoming release; `testRef`
|
|
165
|
+
* may point to a not-yet-existing file.
|
|
166
|
+
* - `retired`: kept for history only; the behaviour no longer
|
|
167
|
+
* ships. Filtered out of `CrossdeckContracts.all()` by default.
|
|
168
|
+
*/
|
|
169
|
+
type ContractStatus = "enforced" | "proposed" | "retired";
|
|
170
|
+
/** Which SDKs (and/or `backend`) a contract is binding on. */
|
|
171
|
+
type ContractAppliesTo = "web" | "node" | "react-native" | "swift" | "android" | "backend";
|
|
172
|
+
/**
|
|
173
|
+
* Pointer to the test that exercises a contract clause. The
|
|
174
|
+
* `name` is matched verbatim against the file's text by
|
|
175
|
+
* `scripts/contract-audit.mjs`, so a rename without updating
|
|
176
|
+
* the contract aborts CI.
|
|
177
|
+
*/
|
|
178
|
+
interface ContractTestRef {
|
|
179
|
+
readonly file: string;
|
|
180
|
+
readonly name: string;
|
|
181
|
+
}
|
|
182
|
+
/** One bank-grade behavioural guarantee — see `contracts/README.md`. */
|
|
183
|
+
interface Contract {
|
|
184
|
+
readonly id: string;
|
|
185
|
+
readonly pillar: ContractPillar;
|
|
186
|
+
readonly status: ContractStatus;
|
|
187
|
+
readonly claim: string;
|
|
188
|
+
readonly appliesTo: readonly ContractAppliesTo[];
|
|
189
|
+
readonly codeRef: readonly string[];
|
|
190
|
+
readonly testRef: readonly ContractTestRef[];
|
|
191
|
+
/** ISO-8601 date the contract was first registered. */
|
|
192
|
+
readonly registeredAt: string;
|
|
193
|
+
/** The release note / phase the contract first appeared in. Immutable. */
|
|
194
|
+
readonly firstRegisteredIn: string;
|
|
195
|
+
/** The SDK release this snapshot was bundled with, stamped at build time. */
|
|
196
|
+
readonly bundledIn: string;
|
|
197
|
+
}
|
|
198
|
+
/**
|
|
199
|
+
* Typed entry point to the bank-grade contracts bundled with this
|
|
200
|
+
* SDK release. Stable, side-effect-free, tree-shakeable.
|
|
201
|
+
*
|
|
202
|
+
* @example Audit at app boot
|
|
203
|
+
* ```ts
|
|
204
|
+
* import { CrossdeckContracts } from "@cross-deck/web";
|
|
205
|
+
*
|
|
206
|
+
* for (const c of CrossdeckContracts.all()) {
|
|
207
|
+
* console.log(`[crossdeck] ${c.id} (${c.pillar})`);
|
|
208
|
+
* }
|
|
209
|
+
* ```
|
|
210
|
+
*
|
|
211
|
+
* @example Assert a specific clause is in force
|
|
212
|
+
* ```ts
|
|
213
|
+
* const isolation = CrossdeckContracts.byId("per-user-cache-isolation");
|
|
214
|
+
* if (!isolation || isolation.status !== "enforced") {
|
|
215
|
+
* throw new Error("entitlement isolation contract is not enforced — refusing to start");
|
|
216
|
+
* }
|
|
217
|
+
* ```
|
|
218
|
+
*/
|
|
219
|
+
declare const CrossdeckContracts: {
|
|
220
|
+
/** Every contract that applies to this SDK and is currently enforced. */
|
|
221
|
+
readonly all: () => readonly Contract[];
|
|
222
|
+
/**
|
|
223
|
+
* Every contract bundled with this SDK release, including
|
|
224
|
+
* `proposed` and `retired` entries. Use `all()` for the
|
|
225
|
+
* enforced-only view.
|
|
226
|
+
*/
|
|
227
|
+
readonly allIncludingHistorical: () => readonly Contract[];
|
|
228
|
+
/** Look up a contract by its stable `id`. */
|
|
229
|
+
readonly byId: (id: string) => Contract | undefined;
|
|
230
|
+
/** Every enforced contract within a pillar. */
|
|
231
|
+
readonly byPillar: (pillar: ContractPillar) => readonly Contract[];
|
|
232
|
+
/** Filter by lifecycle status. */
|
|
233
|
+
readonly withStatus: (status: ContractStatus) => readonly Contract[];
|
|
234
|
+
/** Semver of the SDK release these contracts were bundled with. */
|
|
235
|
+
readonly sdkVersion: "1.5.3";
|
|
236
|
+
/** Fully-qualified bundle identifier — e.g. `@cross-deck/web@1.4.2`. */
|
|
237
|
+
readonly bundledIn: "@cross-deck/web@1.5.3";
|
|
238
|
+
/**
|
|
239
|
+
* Resolve a failing test back to the contract it exercises.
|
|
240
|
+
* Used by test-framework hooks (Vitest `afterEach`, XCTest
|
|
241
|
+
* observation, JUnit `TestWatcher`) to find the contract id of
|
|
242
|
+
* a failed contract test so `reportContractFailure(...)` can
|
|
243
|
+
* stamp the right `contract_id` on the emitted event.
|
|
244
|
+
*
|
|
245
|
+
* Match is on `testRef.name` (case-sensitive, exact). Returns
|
|
246
|
+
* the first contract whose `testRef` list contains a matching
|
|
247
|
+
* entry, regardless of pillar or status.
|
|
248
|
+
*/
|
|
249
|
+
readonly findByTestName: (name: string) => Contract | undefined;
|
|
250
|
+
};
|
|
251
|
+
/**
|
|
252
|
+
* Input to {@link Crossdeck.reportContractFailure}. Lets a test
|
|
253
|
+
* harness / dogfood app / customer integration report a contract
|
|
254
|
+
* violation back to Crossdeck on the dedicated reliability channel —
|
|
255
|
+
* single-fire, never visible in the customer's dashboard.
|
|
256
|
+
*
|
|
257
|
+
* SCHEMA-LOCK: this interface's field set is exhaustively named. No
|
|
258
|
+
* free-form `extra: Record<string, unknown>` — the schema-lock
|
|
259
|
+
* contract at
|
|
260
|
+
* `contracts/diagnostics/contract-failed-payload-schema-lock.json`
|
|
261
|
+
* forbids unbounded fields. Adding a field requires a PR that
|
|
262
|
+
* amends the contract first, then the public interface.
|
|
263
|
+
*
|
|
264
|
+
* `sdk_version` and `sdk_platform` are auto-stamped by the SDK so
|
|
265
|
+
* every emitted event carries them correctly without the caller
|
|
266
|
+
* needing to read them out of `CrossdeckContracts.sdkVersion`.
|
|
267
|
+
*/
|
|
268
|
+
interface ContractFailureInput {
|
|
269
|
+
/** Stable contract id (`per-user-cache-isolation` etc.). */
|
|
270
|
+
contractId: string;
|
|
271
|
+
/**
|
|
272
|
+
* Short categorical-ish label — the SDK convention is to keep this
|
|
273
|
+
* under 128 chars and stable across runs (so dashboards can group).
|
|
274
|
+
* Never an end-user-supplied string.
|
|
275
|
+
*/
|
|
276
|
+
failureReason: string;
|
|
277
|
+
/**
|
|
278
|
+
* Where the failure was observed:
|
|
279
|
+
* - `ci` — the SDK's own test suite on CI
|
|
280
|
+
* - `dogfood` — Crossdeck's internal dogfood project
|
|
281
|
+
* - `customer-app` — a customer's app verifying contracts
|
|
282
|
+
*/
|
|
283
|
+
runContext: "ci" | "dogfood" | "customer-app";
|
|
284
|
+
/**
|
|
285
|
+
* Stable identifier for this verification run. CI: `GITHUB_RUN_ID`
|
|
286
|
+
* or equivalent. Dogfood: per-launch UUID. Customer app: any
|
|
287
|
+
* stable handle the customer chooses to group fires by run.
|
|
288
|
+
*/
|
|
289
|
+
runId: string;
|
|
290
|
+
/**
|
|
291
|
+
* Optional pointer back to the failing test, for triage. The SDK
|
|
292
|
+
* sends both `test_file` and `test_name` on the wire when set.
|
|
293
|
+
*/
|
|
294
|
+
testRef?: {
|
|
295
|
+
file: string;
|
|
296
|
+
name: string;
|
|
297
|
+
};
|
|
298
|
+
/**
|
|
299
|
+
* Optional coarse device class, e.g. "desktop", "mobile-web",
|
|
300
|
+
* "ssr". A categorical bucket, not a device identifier.
|
|
301
|
+
*/
|
|
302
|
+
deviceClass?: string;
|
|
303
|
+
}
|
|
304
|
+
|
|
131
305
|
/**
|
|
132
306
|
* Stack-trace parser — normalises Chrome / Firefox / Safari / Edge
|
|
133
307
|
* stack strings into a common frame shape.
|
|
@@ -270,6 +444,9 @@ interface CapturedError {
|
|
|
270
444
|
|
|
271
445
|
declare class CrossdeckClient {
|
|
272
446
|
private state;
|
|
447
|
+
private verifiers;
|
|
448
|
+
private verifierReporter;
|
|
449
|
+
private verifierCtx;
|
|
273
450
|
/**
|
|
274
451
|
* Boot the SDK. Idempotent — calling init twice with the same options
|
|
275
452
|
* is a no-op; calling with different options replaces the previous
|
|
@@ -280,6 +457,22 @@ declare class CrossdeckClient {
|
|
|
280
457
|
* mismatched env fails fast at boot rather than at first event-flush.
|
|
281
458
|
*/
|
|
282
459
|
init(options: CrossdeckOptions): void;
|
|
460
|
+
/**
|
|
461
|
+
* Fetch /v1/config from the backend and apply any per-app verifier
|
|
462
|
+
* overrides set in the dashboard, then fire the boot self-test
|
|
463
|
+
* once with the FINAL resolved flags.
|
|
464
|
+
*
|
|
465
|
+
* Precedence (also documented at the call site in init()):
|
|
466
|
+
* code option > dashboard remote config > DEBUG/RELEASE default
|
|
467
|
+
*
|
|
468
|
+
* Code wins so engineers retain ultimate control; dashboard is the
|
|
469
|
+
* no-deploy operational lever for QA / staging soaks.
|
|
470
|
+
*
|
|
471
|
+
* Never throws — a /v1/config failure surfaces as "stick with the
|
|
472
|
+
* synchronous defaults that init() already applied" and the boot
|
|
473
|
+
* self-test runs only if code > default resolves true.
|
|
474
|
+
*/
|
|
475
|
+
private bootstrapVerifierLayerRemote;
|
|
283
476
|
/**
|
|
284
477
|
* @deprecated Use `init()` instead. NorthStar §4 standardised the
|
|
285
478
|
* lifecycle method name across SDKs as `init` (formerly `start` /
|
|
@@ -478,6 +671,21 @@ declare class CrossdeckClient {
|
|
|
478
671
|
* trip happens in the background. To flush before the page unloads,
|
|
479
672
|
* call flush().
|
|
480
673
|
*/
|
|
674
|
+
/**
|
|
675
|
+
* Emit `crossdeck.contract_failed` to the Crossdeck reliability
|
|
676
|
+
* endpoint — single-fire, one-way, never visible in the customer's
|
|
677
|
+
* dashboard. Goes over a dedicated HTTP path with the reliability
|
|
678
|
+
* publishable key embedded at build time; the customer's track()
|
|
679
|
+
* pipeline never carries `crossdeck.*` events. This is the
|
|
680
|
+
* independent-controller flow described in Privacy Policy §6
|
|
681
|
+
* ("Flow B"). The wire shape is fixed by the schema-lock contract
|
|
682
|
+
* at `contracts/diagnostics/contract-failed-payload-schema-lock.json`.
|
|
683
|
+
*
|
|
684
|
+
* Wire the call from a test hook, dogfood failure path, or
|
|
685
|
+
* customer contract-verification harness; see
|
|
686
|
+
* `contracts/README.md` for the per-test-framework hook recipes.
|
|
687
|
+
*/
|
|
688
|
+
reportContractFailure(input: ContractFailureInput): void;
|
|
481
689
|
track(name: string, properties?: EventProperties): void;
|
|
482
690
|
/**
|
|
483
691
|
* Force-flush queued events. Useful to call from page-unload handlers.
|
|
@@ -678,7 +886,7 @@ declare class MemoryStorage implements KeyValueStorage {
|
|
|
678
886
|
*
|
|
679
887
|
* Do NOT edit by hand — `node scripts/sync-sdk-versions.mjs`.
|
|
680
888
|
*/
|
|
681
|
-
declare const SDK_VERSION = "1.3
|
|
889
|
+
declare const SDK_VERSION = "1.5.3";
|
|
682
890
|
declare const SDK_NAME = "@cross-deck/web";
|
|
683
891
|
|
|
684
892
|
/**
|
|
@@ -762,4 +970,4 @@ interface DeviceInfo {
|
|
|
762
970
|
appVersion?: string;
|
|
763
971
|
}
|
|
764
972
|
|
|
765
|
-
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 };
|
|
973
|
+
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 };
|