@cross-deck/web 1.5.1 → 1.5.2
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/crossdeck.umd.min.js +2 -2
- package/dist/crossdeck.umd.min.js.map +1 -1
- package/dist/error-codes.json +1 -106
- package/dist/index.cjs +22 -940
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.mts +4 -177
- package/dist/index.d.ts +4 -177
- package/dist/index.mjs +22 -939
- package/dist/index.mjs.map +1 -1
- package/dist/react.cjs +22 -404
- 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 +22 -404
- package/dist/react.mjs.map +1 -1
- package/dist/{types-Bu3jbmdq.d.mts → types-BzoKor4z.d.mts} +0 -4
- package/dist/{types-Bu3jbmdq.d.ts → types-BzoKor4z.d.ts} +0 -4
- package/dist/vue.cjs +22 -404
- package/dist/vue.cjs.map +1 -1
- package/dist/vue.mjs +22 -404
- package/dist/vue.mjs.map +1 -1
- package/package.json +1 -1
- package/dist/contracts 2.json +0 -378
- package/dist/contracts.json +0 -378
- package/dist/crossdeck.umd.min 2.js +0 -3
- package/dist/crossdeck.umd.min.js 2.map +0 -1
- package/dist/error-codes 2.json +0 -196
- package/dist/index 2.cjs +0 -4778
- package/dist/index 2.mjs +0 -4742
- package/dist/index.cjs 2.map +0 -1
- package/dist/index.d 2.mts +0 -938
- package/dist/index.d 2.ts +0 -938
- package/dist/index.mjs 2.map +0 -1
- package/dist/react 2.cjs +0 -4220
- package/dist/react 2.mjs +0 -4193
- package/dist/react.cjs 2.map +0 -1
- package/dist/react.d 2.mts +0 -91
- package/dist/react.d 2.ts +0 -91
- package/dist/react.mjs 2.map +0 -1
- package/dist/types-Bu3jbmdq.d 2.mts +0 -314
- package/dist/types-Bu3jbmdq.d 2.ts +0 -314
- package/dist/vue 2.cjs +0 -4185
- package/dist/vue 2.mjs +0 -4159
- package/dist/vue.cjs 2.map +0 -1
- package/dist/vue.d 2.mts +0 -37
- package/dist/vue.d 2.ts +0 -37
- package/dist/vue.mjs 2.map +0 -1
|
@@ -1,314 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* Public types for @cross-deck/web. These mirror the wire format
|
|
3
|
-
* exposed by the v1 backend API. Keep them in lockstep with
|
|
4
|
-
* backend/src/api/v1-types.ts — same field names, same nullability.
|
|
5
|
-
*/
|
|
6
|
-
type Environment = "production" | "sandbox";
|
|
7
|
-
type Platform = "ios" | "android" | "web";
|
|
8
|
-
type AuditRail = "apple" | "stripe" | "google" | "manual";
|
|
9
|
-
interface PublicEntitlement {
|
|
10
|
-
object: "entitlement";
|
|
11
|
-
key: string;
|
|
12
|
-
isActive: boolean;
|
|
13
|
-
validUntil?: number | null;
|
|
14
|
-
source: {
|
|
15
|
-
rail: AuditRail;
|
|
16
|
-
productId: string;
|
|
17
|
-
subscriptionId: string;
|
|
18
|
-
};
|
|
19
|
-
updatedAt: number;
|
|
20
|
-
}
|
|
21
|
-
interface EntitlementsListResponse {
|
|
22
|
-
object: "list";
|
|
23
|
-
data: PublicEntitlement[];
|
|
24
|
-
crossdeckCustomerId: string;
|
|
25
|
-
env: Environment;
|
|
26
|
-
}
|
|
27
|
-
interface AliasResult {
|
|
28
|
-
object: "alias_result";
|
|
29
|
-
crossdeckCustomerId: string;
|
|
30
|
-
linked: Array<{
|
|
31
|
-
type: "developer";
|
|
32
|
-
id: string;
|
|
33
|
-
} | {
|
|
34
|
-
type: "anonymous";
|
|
35
|
-
id: string;
|
|
36
|
-
}>;
|
|
37
|
-
mergePending: boolean;
|
|
38
|
-
env: Environment;
|
|
39
|
-
}
|
|
40
|
-
interface PurchaseResult {
|
|
41
|
-
object: "purchase_result";
|
|
42
|
-
crossdeckCustomerId: string;
|
|
43
|
-
env: Environment;
|
|
44
|
-
entitlements: PublicEntitlement[];
|
|
45
|
-
/** True when the response came from the backend's idempotency
|
|
46
|
-
* cache instead of fresh processing. Backend also returns
|
|
47
|
-
* `Idempotent-Replayed: true` as a response header (v1.4.0). */
|
|
48
|
-
idempotent_replay?: boolean;
|
|
49
|
-
}
|
|
50
|
-
interface HeartbeatResponse {
|
|
51
|
-
object: "heartbeat";
|
|
52
|
-
ok: true;
|
|
53
|
-
projectId: string;
|
|
54
|
-
appId: string;
|
|
55
|
-
platform: Platform;
|
|
56
|
-
env: Environment;
|
|
57
|
-
serverTime: number;
|
|
58
|
-
}
|
|
59
|
-
/**
|
|
60
|
-
* Configuration for Crossdeck.init. Three fields are mandatory —
|
|
61
|
-
* `appId`, `publicKey`, and `environment` — per NorthStar §11.1.
|
|
62
|
-
*
|
|
63
|
-
* The pair of (appId, environment) is what we put on the wire envelope
|
|
64
|
-
* (NorthStar §13.1) so the backend can correlate events against the
|
|
65
|
-
* specific app surface and refuse mismatched env declarations loudly.
|
|
66
|
-
*/
|
|
67
|
-
interface CrossdeckOptions {
|
|
68
|
-
/**
|
|
69
|
-
* Your Crossdeck App ID (e.g. "app_web_xxx"). Required.
|
|
70
|
-
*
|
|
71
|
-
* Issued in the dashboard when you create an app. Goes on the wire
|
|
72
|
-
* envelope so the backend correlates events with the specific app
|
|
73
|
-
* surface — useful when one project has multiple apps (web + iOS +
|
|
74
|
-
* Android) sharing the same publishable key family.
|
|
75
|
-
*/
|
|
76
|
-
appId: string;
|
|
77
|
-
/** Your Crossdeck publishable key (cd_pub_…). Required. */
|
|
78
|
-
publicKey: string;
|
|
79
|
-
/**
|
|
80
|
-
* Explicit environment declaration. Required.
|
|
81
|
-
*
|
|
82
|
-
* Must match the publishable key's prefix:
|
|
83
|
-
* cd_pub_test_… → "sandbox"
|
|
84
|
-
* cd_pub_live_… → "production"
|
|
85
|
-
*
|
|
86
|
-
* Mismatch is rejected at init time so a typo'd key can't silently
|
|
87
|
-
* route prod telemetry into sandbox dashboards.
|
|
88
|
-
*/
|
|
89
|
-
environment: Environment;
|
|
90
|
-
/**
|
|
91
|
-
* Override the API base URL. Default is https://api.cross-deck.com/v1.
|
|
92
|
-
* Useful for self-hosted setups or pointing at the local emulator
|
|
93
|
-
* (e.g. http://localhost:5001/crossdeck-47d8f/us-east4/v1).
|
|
94
|
-
*/
|
|
95
|
-
baseUrl?: string;
|
|
96
|
-
/**
|
|
97
|
-
* Persist anonymousId + crossdeckCustomerId across sessions.
|
|
98
|
-
* Default: true in the browser (localStorage), false in Node (in-memory only).
|
|
99
|
-
*/
|
|
100
|
-
persistIdentity?: boolean;
|
|
101
|
-
/**
|
|
102
|
-
* Storage adapter. The SDK calls .getItem / .setItem / .removeItem.
|
|
103
|
-
* Defaults to globalThis.localStorage when present. Pass an in-memory
|
|
104
|
-
* adapter for Node runtimes where you want session-only persistence.
|
|
105
|
-
*/
|
|
106
|
-
storage?: KeyValueStorage;
|
|
107
|
-
/** Storage key prefix for the SDK's persisted state. Default "crossdeck:". */
|
|
108
|
-
storagePrefix?: string;
|
|
109
|
-
/**
|
|
110
|
-
* Send a heartbeat to /v1/sdk/heartbeat on start(). Default true.
|
|
111
|
-
* Disable for high-frequency boot scenarios where the heartbeat is
|
|
112
|
-
* pure overhead.
|
|
113
|
-
*/
|
|
114
|
-
autoHeartbeat?: boolean;
|
|
115
|
-
/** Maximum events buffered before forced flush. Default 20. */
|
|
116
|
-
eventFlushBatchSize?: number;
|
|
117
|
-
/** Idle ms after the last track() before flushing. Default 5000. */
|
|
118
|
-
eventFlushIntervalMs?: number;
|
|
119
|
-
/** Override the SDK version reported on heartbeats. Default: package version. */
|
|
120
|
-
sdkVersion?: string;
|
|
121
|
-
/**
|
|
122
|
-
* Auto-tracking. Default: every flag is `true` in browsers, all
|
|
123
|
-
* silently no-op in Node.
|
|
124
|
-
*
|
|
125
|
-
* Pass `false` to disable everything, or a partial object to override
|
|
126
|
-
* individual flags:
|
|
127
|
-
*
|
|
128
|
-
* Crossdeck.start({
|
|
129
|
-
* publicKey: "...",
|
|
130
|
-
* autoTrack: { pageViews: false }, // sessions + deviceInfo still on
|
|
131
|
-
* });
|
|
132
|
-
*/
|
|
133
|
-
autoTrack?: boolean | Partial<AutoTrackOptions>;
|
|
134
|
-
/**
|
|
135
|
-
* Your app's version (e.g. "1.2.3"). Auto-attached to every event as
|
|
136
|
-
* `properties.appVersion` when `autoTrack.deviceInfo` is enabled.
|
|
137
|
-
* Useful for slicing dashboards by build.
|
|
138
|
-
*/
|
|
139
|
-
appVersion?: string;
|
|
140
|
-
/**
|
|
141
|
-
* Enable verbose diagnostic logging via the NorthStar §16 debug-signal
|
|
142
|
-
* vocabulary. Default: false. Equivalent to calling
|
|
143
|
-
* `Crossdeck.setDebugMode(true)` after init.
|
|
144
|
-
*/
|
|
145
|
-
debug?: boolean;
|
|
146
|
-
/**
|
|
147
|
-
* Respect the browser's Do Not Track signal at init (v0.10.0+).
|
|
148
|
-
* Default `false`. When `true` AND the user has `navigator.doNotTrack === "1"`,
|
|
149
|
-
* the SDK boots with analytics / marketing / errors all denied —
|
|
150
|
-
* locked off even if the developer later calls `Crossdeck.consent({...})`.
|
|
151
|
-
* Industry has effectively deprecated DNT, but opt-in support is the
|
|
152
|
-
* polite default for privacy-first apps.
|
|
153
|
-
*/
|
|
154
|
-
respectDnt?: boolean;
|
|
155
|
-
/**
|
|
156
|
-
* Scrub PII-shaped strings (email addresses, card numbers) from
|
|
157
|
-
* URL paths, event properties, and acquisition referrer before they
|
|
158
|
-
* leave the SDK. Default `true` — Stripe-grade. Disable only if your
|
|
159
|
-
* pipeline does its own PII redaction downstream and you need the
|
|
160
|
-
* raw strings.
|
|
161
|
-
*/
|
|
162
|
-
scrubPii?: boolean;
|
|
163
|
-
}
|
|
164
|
-
/** Auto-tracking flags. See CrossdeckOptions.autoTrack. */
|
|
165
|
-
interface AutoTrackOptions {
|
|
166
|
-
/** Emit `session.started` / `session.ended` automatically. Default true (browser only). */
|
|
167
|
-
sessions: boolean;
|
|
168
|
-
/** Emit `page.viewed` on initial load + SPA navigation. Default true (browser only). */
|
|
169
|
-
pageViews: boolean;
|
|
170
|
-
/** Auto-attach os/browser/locale/screen/etc to every event's `properties`. Default true (browser only). */
|
|
171
|
-
deviceInfo: boolean;
|
|
172
|
-
/**
|
|
173
|
-
* Click autocapture — fire `element.clicked` for every interactive
|
|
174
|
-
* click on the page. Default true. Mixpanel/Amplitude pattern. Powers
|
|
175
|
-
* Crossdeck's funnel-attribution USP ("clicked X then converted").
|
|
176
|
-
* Privacy: skips form inputs / password fields / [class~="cd-noTrack"]
|
|
177
|
-
* subtrees. Override on individual elements with data-cd-event="custom"
|
|
178
|
-
* or data-cd-prop-* for custom property tagging.
|
|
179
|
-
*/
|
|
180
|
-
clicks: boolean;
|
|
181
|
-
/**
|
|
182
|
-
* Web Vitals capture (v0.9.0+) — emits `webvitals.lcp`, `webvitals.inp`,
|
|
183
|
-
* `webvitals.cls`, `webvitals.fcp`, `webvitals.ttfb` events using the
|
|
184
|
-
* browser's `PerformanceObserver`. Defaults to true in browsers,
|
|
185
|
-
* no-op everywhere else. Disable if you have a separate RUM provider
|
|
186
|
-
* (DataDog, Sentry Performance) and don't want duplicates.
|
|
187
|
-
*/
|
|
188
|
-
webVitals: boolean;
|
|
189
|
-
/**
|
|
190
|
-
* Error capture (v1.0.0+) — installs window.onerror +
|
|
191
|
-
* window.onunhandledrejection listeners, wraps fetch + XHR to catch
|
|
192
|
-
* 5xx + network failures, ships each captured error as a Crossdeck
|
|
193
|
-
* event (kind: error.unhandled / error.unhandledrejection /
|
|
194
|
-
* error.handled / error.http / error.message). Errors gate on
|
|
195
|
-
* `consent.errors`. Rate-limited per-fingerprint so a runaway loop
|
|
196
|
-
* can't flood the queue; browser-extension noise filtered by
|
|
197
|
-
* default. Default true in browsers, no-op everywhere else.
|
|
198
|
-
*/
|
|
199
|
-
errors: boolean;
|
|
200
|
-
}
|
|
201
|
-
/** Minimal interface for any pluggable key-value persistence. */
|
|
202
|
-
interface KeyValueStorage {
|
|
203
|
-
getItem(key: string): string | null;
|
|
204
|
-
setItem(key: string, value: string): void;
|
|
205
|
-
removeItem(key: string): void;
|
|
206
|
-
}
|
|
207
|
-
/**
|
|
208
|
-
* Identity hint + profile traits passed to identify().
|
|
209
|
-
*
|
|
210
|
-
* `traits` is a free-form bag of profile data (name, plan, signupDate,
|
|
211
|
-
* teamRole, etc.) that gets persisted on the Crossdeck customer record
|
|
212
|
-
* and attached to every subsequent event of the identified user as
|
|
213
|
-
* `$user.<key>` properties for dashboard filtering.
|
|
214
|
-
*
|
|
215
|
-
* Like event properties, traits are validated at the SDK boundary —
|
|
216
|
-
* functions/symbols/undefined dropped, Date / BigInt / Error coerced,
|
|
217
|
-
* strings > 1024 chars truncated. Caller's object is never mutated.
|
|
218
|
-
*/
|
|
219
|
-
interface IdentifyOptions {
|
|
220
|
-
/** Optional email to attach to the customer record. */
|
|
221
|
-
email?: string;
|
|
222
|
-
/**
|
|
223
|
-
* Optional profile traits. Examples:
|
|
224
|
-
* `{ name: "Wes", plan: "pro", signedUpAt: "2026-05-11" }`
|
|
225
|
-
*
|
|
226
|
-
* Treated like event properties — values are sanitised at the SDK
|
|
227
|
-
* boundary so a `{ avatar: <File>, callback: () => {} }` payload
|
|
228
|
-
* doesn't crash the alias request. Server-side, traits land on
|
|
229
|
-
* `customers/{cdcust}.traits` (additively — existing fields are
|
|
230
|
-
* preserved unless the new identify call overrides them).
|
|
231
|
-
*/
|
|
232
|
-
traits?: Record<string, unknown>;
|
|
233
|
-
}
|
|
234
|
-
/**
|
|
235
|
-
* Group context — Mixpanel-style. Identifies a customer's membership
|
|
236
|
-
* in an organisational entity (org, account, team, workspace) so B2B
|
|
237
|
-
* dashboards can answer "how is account X using my product".
|
|
238
|
-
*
|
|
239
|
-
* Attached to every event as `$groups.<type>` until cleared via
|
|
240
|
-
* `Crossdeck.group(type, null)`. Multiple types can coexist (e.g.
|
|
241
|
-
* `org` + `team`) — the SDK keeps a map keyed by type.
|
|
242
|
-
*/
|
|
243
|
-
interface GroupTraits {
|
|
244
|
-
[key: string]: unknown;
|
|
245
|
-
}
|
|
246
|
-
/** Properties payload for track(). Arbitrary key/value, JSON-serialisable, ≤ 8 KB. */
|
|
247
|
-
type EventProperties = Record<string, unknown>;
|
|
248
|
-
/**
|
|
249
|
-
* Diagnostic snapshot returned by Crossdeck.diagnostics(). Stable shape
|
|
250
|
-
* whether or not start() has been called — callers don't need to narrow
|
|
251
|
-
* on `started` to read `events` or `entitlements`. Pre-start values are
|
|
252
|
-
* sensible empties (zeros, nulls).
|
|
253
|
-
*/
|
|
254
|
-
interface Diagnostics {
|
|
255
|
-
started: boolean;
|
|
256
|
-
anonymousId: string | null;
|
|
257
|
-
crossdeckCustomerId: string | null;
|
|
258
|
-
developerUserId: string | null;
|
|
259
|
-
sdkVersion: string | null;
|
|
260
|
-
baseUrl: string | null;
|
|
261
|
-
/**
|
|
262
|
-
* Last `serverTime` value the SDK saw on a /sdk/heartbeat response,
|
|
263
|
-
* along with the local clock value AT that moment. Lets dashboards
|
|
264
|
-
* (and the developer, in debug mode) detect a wrong-system-clock
|
|
265
|
-
* problem before it corrupts a day of analytics. Null until the
|
|
266
|
-
* first heartbeat completes.
|
|
267
|
-
*/
|
|
268
|
-
clock: {
|
|
269
|
-
/** Server's view of "now" from the last heartbeat (epoch ms). */
|
|
270
|
-
lastServerTime: number | null;
|
|
271
|
-
/** Client's `Date.now()` taken at the same moment as `lastServerTime`. */
|
|
272
|
-
lastClientTime: number | null;
|
|
273
|
-
/**
|
|
274
|
-
* `lastClientTime - lastServerTime` — positive means the client
|
|
275
|
-
* clock is AHEAD of the server. Outside ±5 minutes is suspicious
|
|
276
|
-
* and worth surfacing to the developer.
|
|
277
|
-
*/
|
|
278
|
-
skewMs: number | null;
|
|
279
|
-
};
|
|
280
|
-
entitlements: {
|
|
281
|
-
count: number;
|
|
282
|
-
lastUpdated: number;
|
|
283
|
-
/**
|
|
284
|
-
* True when the durable cache is knowingly serving older-than-
|
|
285
|
-
* trustworthy data — the last refresh attempt failed (Crossdeck
|
|
286
|
-
* unreachable) or last-known-good has aged past the staleness
|
|
287
|
-
* window. The cache still serves last-known-good; this makes the
|
|
288
|
-
* staleness observable instead of a silent unbounded window.
|
|
289
|
-
*/
|
|
290
|
-
stale: boolean;
|
|
291
|
-
/**
|
|
292
|
-
* Cumulative count of listener invocations that threw. Swallowed
|
|
293
|
-
* inside the cache (a buggy consumer must not crash the SDK) but
|
|
294
|
-
* surfaced here so developers can spot broken subscribers.
|
|
295
|
-
*/
|
|
296
|
-
listenerErrors: number;
|
|
297
|
-
};
|
|
298
|
-
events: {
|
|
299
|
-
buffered: number;
|
|
300
|
-
dropped: number;
|
|
301
|
-
inFlight: number;
|
|
302
|
-
lastFlushAt: number;
|
|
303
|
-
lastError: string | null;
|
|
304
|
-
/** Consecutive flush failures since the last success. */
|
|
305
|
-
consecutiveFailures: number;
|
|
306
|
-
/**
|
|
307
|
-
* When the next retry is scheduled (epoch ms), or null if the queue
|
|
308
|
-
* is idle / healthy.
|
|
309
|
-
*/
|
|
310
|
-
nextRetryAt: number | null;
|
|
311
|
-
};
|
|
312
|
-
}
|
|
313
|
-
|
|
314
|
-
export type { AliasResult as A, CrossdeckOptions as C, Diagnostics as D, EventProperties as E, GroupTraits as G, HeartbeatResponse as H, IdentifyOptions as I, KeyValueStorage as K, PublicEntitlement as P, PurchaseResult as a, AuditRail as b, AutoTrackOptions as c, EntitlementsListResponse as d, Environment as e, Platform as f };
|
|
@@ -1,314 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* Public types for @cross-deck/web. These mirror the wire format
|
|
3
|
-
* exposed by the v1 backend API. Keep them in lockstep with
|
|
4
|
-
* backend/src/api/v1-types.ts — same field names, same nullability.
|
|
5
|
-
*/
|
|
6
|
-
type Environment = "production" | "sandbox";
|
|
7
|
-
type Platform = "ios" | "android" | "web";
|
|
8
|
-
type AuditRail = "apple" | "stripe" | "google" | "manual";
|
|
9
|
-
interface PublicEntitlement {
|
|
10
|
-
object: "entitlement";
|
|
11
|
-
key: string;
|
|
12
|
-
isActive: boolean;
|
|
13
|
-
validUntil?: number | null;
|
|
14
|
-
source: {
|
|
15
|
-
rail: AuditRail;
|
|
16
|
-
productId: string;
|
|
17
|
-
subscriptionId: string;
|
|
18
|
-
};
|
|
19
|
-
updatedAt: number;
|
|
20
|
-
}
|
|
21
|
-
interface EntitlementsListResponse {
|
|
22
|
-
object: "list";
|
|
23
|
-
data: PublicEntitlement[];
|
|
24
|
-
crossdeckCustomerId: string;
|
|
25
|
-
env: Environment;
|
|
26
|
-
}
|
|
27
|
-
interface AliasResult {
|
|
28
|
-
object: "alias_result";
|
|
29
|
-
crossdeckCustomerId: string;
|
|
30
|
-
linked: Array<{
|
|
31
|
-
type: "developer";
|
|
32
|
-
id: string;
|
|
33
|
-
} | {
|
|
34
|
-
type: "anonymous";
|
|
35
|
-
id: string;
|
|
36
|
-
}>;
|
|
37
|
-
mergePending: boolean;
|
|
38
|
-
env: Environment;
|
|
39
|
-
}
|
|
40
|
-
interface PurchaseResult {
|
|
41
|
-
object: "purchase_result";
|
|
42
|
-
crossdeckCustomerId: string;
|
|
43
|
-
env: Environment;
|
|
44
|
-
entitlements: PublicEntitlement[];
|
|
45
|
-
/** True when the response came from the backend's idempotency
|
|
46
|
-
* cache instead of fresh processing. Backend also returns
|
|
47
|
-
* `Idempotent-Replayed: true` as a response header (v1.4.0). */
|
|
48
|
-
idempotent_replay?: boolean;
|
|
49
|
-
}
|
|
50
|
-
interface HeartbeatResponse {
|
|
51
|
-
object: "heartbeat";
|
|
52
|
-
ok: true;
|
|
53
|
-
projectId: string;
|
|
54
|
-
appId: string;
|
|
55
|
-
platform: Platform;
|
|
56
|
-
env: Environment;
|
|
57
|
-
serverTime: number;
|
|
58
|
-
}
|
|
59
|
-
/**
|
|
60
|
-
* Configuration for Crossdeck.init. Three fields are mandatory —
|
|
61
|
-
* `appId`, `publicKey`, and `environment` — per NorthStar §11.1.
|
|
62
|
-
*
|
|
63
|
-
* The pair of (appId, environment) is what we put on the wire envelope
|
|
64
|
-
* (NorthStar §13.1) so the backend can correlate events against the
|
|
65
|
-
* specific app surface and refuse mismatched env declarations loudly.
|
|
66
|
-
*/
|
|
67
|
-
interface CrossdeckOptions {
|
|
68
|
-
/**
|
|
69
|
-
* Your Crossdeck App ID (e.g. "app_web_xxx"). Required.
|
|
70
|
-
*
|
|
71
|
-
* Issued in the dashboard when you create an app. Goes on the wire
|
|
72
|
-
* envelope so the backend correlates events with the specific app
|
|
73
|
-
* surface — useful when one project has multiple apps (web + iOS +
|
|
74
|
-
* Android) sharing the same publishable key family.
|
|
75
|
-
*/
|
|
76
|
-
appId: string;
|
|
77
|
-
/** Your Crossdeck publishable key (cd_pub_…). Required. */
|
|
78
|
-
publicKey: string;
|
|
79
|
-
/**
|
|
80
|
-
* Explicit environment declaration. Required.
|
|
81
|
-
*
|
|
82
|
-
* Must match the publishable key's prefix:
|
|
83
|
-
* cd_pub_test_… → "sandbox"
|
|
84
|
-
* cd_pub_live_… → "production"
|
|
85
|
-
*
|
|
86
|
-
* Mismatch is rejected at init time so a typo'd key can't silently
|
|
87
|
-
* route prod telemetry into sandbox dashboards.
|
|
88
|
-
*/
|
|
89
|
-
environment: Environment;
|
|
90
|
-
/**
|
|
91
|
-
* Override the API base URL. Default is https://api.cross-deck.com/v1.
|
|
92
|
-
* Useful for self-hosted setups or pointing at the local emulator
|
|
93
|
-
* (e.g. http://localhost:5001/crossdeck-47d8f/us-east4/v1).
|
|
94
|
-
*/
|
|
95
|
-
baseUrl?: string;
|
|
96
|
-
/**
|
|
97
|
-
* Persist anonymousId + crossdeckCustomerId across sessions.
|
|
98
|
-
* Default: true in the browser (localStorage), false in Node (in-memory only).
|
|
99
|
-
*/
|
|
100
|
-
persistIdentity?: boolean;
|
|
101
|
-
/**
|
|
102
|
-
* Storage adapter. The SDK calls .getItem / .setItem / .removeItem.
|
|
103
|
-
* Defaults to globalThis.localStorage when present. Pass an in-memory
|
|
104
|
-
* adapter for Node runtimes where you want session-only persistence.
|
|
105
|
-
*/
|
|
106
|
-
storage?: KeyValueStorage;
|
|
107
|
-
/** Storage key prefix for the SDK's persisted state. Default "crossdeck:". */
|
|
108
|
-
storagePrefix?: string;
|
|
109
|
-
/**
|
|
110
|
-
* Send a heartbeat to /v1/sdk/heartbeat on start(). Default true.
|
|
111
|
-
* Disable for high-frequency boot scenarios where the heartbeat is
|
|
112
|
-
* pure overhead.
|
|
113
|
-
*/
|
|
114
|
-
autoHeartbeat?: boolean;
|
|
115
|
-
/** Maximum events buffered before forced flush. Default 20. */
|
|
116
|
-
eventFlushBatchSize?: number;
|
|
117
|
-
/** Idle ms after the last track() before flushing. Default 5000. */
|
|
118
|
-
eventFlushIntervalMs?: number;
|
|
119
|
-
/** Override the SDK version reported on heartbeats. Default: package version. */
|
|
120
|
-
sdkVersion?: string;
|
|
121
|
-
/**
|
|
122
|
-
* Auto-tracking. Default: every flag is `true` in browsers, all
|
|
123
|
-
* silently no-op in Node.
|
|
124
|
-
*
|
|
125
|
-
* Pass `false` to disable everything, or a partial object to override
|
|
126
|
-
* individual flags:
|
|
127
|
-
*
|
|
128
|
-
* Crossdeck.start({
|
|
129
|
-
* publicKey: "...",
|
|
130
|
-
* autoTrack: { pageViews: false }, // sessions + deviceInfo still on
|
|
131
|
-
* });
|
|
132
|
-
*/
|
|
133
|
-
autoTrack?: boolean | Partial<AutoTrackOptions>;
|
|
134
|
-
/**
|
|
135
|
-
* Your app's version (e.g. "1.2.3"). Auto-attached to every event as
|
|
136
|
-
* `properties.appVersion` when `autoTrack.deviceInfo` is enabled.
|
|
137
|
-
* Useful for slicing dashboards by build.
|
|
138
|
-
*/
|
|
139
|
-
appVersion?: string;
|
|
140
|
-
/**
|
|
141
|
-
* Enable verbose diagnostic logging via the NorthStar §16 debug-signal
|
|
142
|
-
* vocabulary. Default: false. Equivalent to calling
|
|
143
|
-
* `Crossdeck.setDebugMode(true)` after init.
|
|
144
|
-
*/
|
|
145
|
-
debug?: boolean;
|
|
146
|
-
/**
|
|
147
|
-
* Respect the browser's Do Not Track signal at init (v0.10.0+).
|
|
148
|
-
* Default `false`. When `true` AND the user has `navigator.doNotTrack === "1"`,
|
|
149
|
-
* the SDK boots with analytics / marketing / errors all denied —
|
|
150
|
-
* locked off even if the developer later calls `Crossdeck.consent({...})`.
|
|
151
|
-
* Industry has effectively deprecated DNT, but opt-in support is the
|
|
152
|
-
* polite default for privacy-first apps.
|
|
153
|
-
*/
|
|
154
|
-
respectDnt?: boolean;
|
|
155
|
-
/**
|
|
156
|
-
* Scrub PII-shaped strings (email addresses, card numbers) from
|
|
157
|
-
* URL paths, event properties, and acquisition referrer before they
|
|
158
|
-
* leave the SDK. Default `true` — Stripe-grade. Disable only if your
|
|
159
|
-
* pipeline does its own PII redaction downstream and you need the
|
|
160
|
-
* raw strings.
|
|
161
|
-
*/
|
|
162
|
-
scrubPii?: boolean;
|
|
163
|
-
}
|
|
164
|
-
/** Auto-tracking flags. See CrossdeckOptions.autoTrack. */
|
|
165
|
-
interface AutoTrackOptions {
|
|
166
|
-
/** Emit `session.started` / `session.ended` automatically. Default true (browser only). */
|
|
167
|
-
sessions: boolean;
|
|
168
|
-
/** Emit `page.viewed` on initial load + SPA navigation. Default true (browser only). */
|
|
169
|
-
pageViews: boolean;
|
|
170
|
-
/** Auto-attach os/browser/locale/screen/etc to every event's `properties`. Default true (browser only). */
|
|
171
|
-
deviceInfo: boolean;
|
|
172
|
-
/**
|
|
173
|
-
* Click autocapture — fire `element.clicked` for every interactive
|
|
174
|
-
* click on the page. Default true. Mixpanel/Amplitude pattern. Powers
|
|
175
|
-
* Crossdeck's funnel-attribution USP ("clicked X then converted").
|
|
176
|
-
* Privacy: skips form inputs / password fields / [class~="cd-noTrack"]
|
|
177
|
-
* subtrees. Override on individual elements with data-cd-event="custom"
|
|
178
|
-
* or data-cd-prop-* for custom property tagging.
|
|
179
|
-
*/
|
|
180
|
-
clicks: boolean;
|
|
181
|
-
/**
|
|
182
|
-
* Web Vitals capture (v0.9.0+) — emits `webvitals.lcp`, `webvitals.inp`,
|
|
183
|
-
* `webvitals.cls`, `webvitals.fcp`, `webvitals.ttfb` events using the
|
|
184
|
-
* browser's `PerformanceObserver`. Defaults to true in browsers,
|
|
185
|
-
* no-op everywhere else. Disable if you have a separate RUM provider
|
|
186
|
-
* (DataDog, Sentry Performance) and don't want duplicates.
|
|
187
|
-
*/
|
|
188
|
-
webVitals: boolean;
|
|
189
|
-
/**
|
|
190
|
-
* Error capture (v1.0.0+) — installs window.onerror +
|
|
191
|
-
* window.onunhandledrejection listeners, wraps fetch + XHR to catch
|
|
192
|
-
* 5xx + network failures, ships each captured error as a Crossdeck
|
|
193
|
-
* event (kind: error.unhandled / error.unhandledrejection /
|
|
194
|
-
* error.handled / error.http / error.message). Errors gate on
|
|
195
|
-
* `consent.errors`. Rate-limited per-fingerprint so a runaway loop
|
|
196
|
-
* can't flood the queue; browser-extension noise filtered by
|
|
197
|
-
* default. Default true in browsers, no-op everywhere else.
|
|
198
|
-
*/
|
|
199
|
-
errors: boolean;
|
|
200
|
-
}
|
|
201
|
-
/** Minimal interface for any pluggable key-value persistence. */
|
|
202
|
-
interface KeyValueStorage {
|
|
203
|
-
getItem(key: string): string | null;
|
|
204
|
-
setItem(key: string, value: string): void;
|
|
205
|
-
removeItem(key: string): void;
|
|
206
|
-
}
|
|
207
|
-
/**
|
|
208
|
-
* Identity hint + profile traits passed to identify().
|
|
209
|
-
*
|
|
210
|
-
* `traits` is a free-form bag of profile data (name, plan, signupDate,
|
|
211
|
-
* teamRole, etc.) that gets persisted on the Crossdeck customer record
|
|
212
|
-
* and attached to every subsequent event of the identified user as
|
|
213
|
-
* `$user.<key>` properties for dashboard filtering.
|
|
214
|
-
*
|
|
215
|
-
* Like event properties, traits are validated at the SDK boundary —
|
|
216
|
-
* functions/symbols/undefined dropped, Date / BigInt / Error coerced,
|
|
217
|
-
* strings > 1024 chars truncated. Caller's object is never mutated.
|
|
218
|
-
*/
|
|
219
|
-
interface IdentifyOptions {
|
|
220
|
-
/** Optional email to attach to the customer record. */
|
|
221
|
-
email?: string;
|
|
222
|
-
/**
|
|
223
|
-
* Optional profile traits. Examples:
|
|
224
|
-
* `{ name: "Wes", plan: "pro", signedUpAt: "2026-05-11" }`
|
|
225
|
-
*
|
|
226
|
-
* Treated like event properties — values are sanitised at the SDK
|
|
227
|
-
* boundary so a `{ avatar: <File>, callback: () => {} }` payload
|
|
228
|
-
* doesn't crash the alias request. Server-side, traits land on
|
|
229
|
-
* `customers/{cdcust}.traits` (additively — existing fields are
|
|
230
|
-
* preserved unless the new identify call overrides them).
|
|
231
|
-
*/
|
|
232
|
-
traits?: Record<string, unknown>;
|
|
233
|
-
}
|
|
234
|
-
/**
|
|
235
|
-
* Group context — Mixpanel-style. Identifies a customer's membership
|
|
236
|
-
* in an organisational entity (org, account, team, workspace) so B2B
|
|
237
|
-
* dashboards can answer "how is account X using my product".
|
|
238
|
-
*
|
|
239
|
-
* Attached to every event as `$groups.<type>` until cleared via
|
|
240
|
-
* `Crossdeck.group(type, null)`. Multiple types can coexist (e.g.
|
|
241
|
-
* `org` + `team`) — the SDK keeps a map keyed by type.
|
|
242
|
-
*/
|
|
243
|
-
interface GroupTraits {
|
|
244
|
-
[key: string]: unknown;
|
|
245
|
-
}
|
|
246
|
-
/** Properties payload for track(). Arbitrary key/value, JSON-serialisable, ≤ 8 KB. */
|
|
247
|
-
type EventProperties = Record<string, unknown>;
|
|
248
|
-
/**
|
|
249
|
-
* Diagnostic snapshot returned by Crossdeck.diagnostics(). Stable shape
|
|
250
|
-
* whether or not start() has been called — callers don't need to narrow
|
|
251
|
-
* on `started` to read `events` or `entitlements`. Pre-start values are
|
|
252
|
-
* sensible empties (zeros, nulls).
|
|
253
|
-
*/
|
|
254
|
-
interface Diagnostics {
|
|
255
|
-
started: boolean;
|
|
256
|
-
anonymousId: string | null;
|
|
257
|
-
crossdeckCustomerId: string | null;
|
|
258
|
-
developerUserId: string | null;
|
|
259
|
-
sdkVersion: string | null;
|
|
260
|
-
baseUrl: string | null;
|
|
261
|
-
/**
|
|
262
|
-
* Last `serverTime` value the SDK saw on a /sdk/heartbeat response,
|
|
263
|
-
* along with the local clock value AT that moment. Lets dashboards
|
|
264
|
-
* (and the developer, in debug mode) detect a wrong-system-clock
|
|
265
|
-
* problem before it corrupts a day of analytics. Null until the
|
|
266
|
-
* first heartbeat completes.
|
|
267
|
-
*/
|
|
268
|
-
clock: {
|
|
269
|
-
/** Server's view of "now" from the last heartbeat (epoch ms). */
|
|
270
|
-
lastServerTime: number | null;
|
|
271
|
-
/** Client's `Date.now()` taken at the same moment as `lastServerTime`. */
|
|
272
|
-
lastClientTime: number | null;
|
|
273
|
-
/**
|
|
274
|
-
* `lastClientTime - lastServerTime` — positive means the client
|
|
275
|
-
* clock is AHEAD of the server. Outside ±5 minutes is suspicious
|
|
276
|
-
* and worth surfacing to the developer.
|
|
277
|
-
*/
|
|
278
|
-
skewMs: number | null;
|
|
279
|
-
};
|
|
280
|
-
entitlements: {
|
|
281
|
-
count: number;
|
|
282
|
-
lastUpdated: number;
|
|
283
|
-
/**
|
|
284
|
-
* True when the durable cache is knowingly serving older-than-
|
|
285
|
-
* trustworthy data — the last refresh attempt failed (Crossdeck
|
|
286
|
-
* unreachable) or last-known-good has aged past the staleness
|
|
287
|
-
* window. The cache still serves last-known-good; this makes the
|
|
288
|
-
* staleness observable instead of a silent unbounded window.
|
|
289
|
-
*/
|
|
290
|
-
stale: boolean;
|
|
291
|
-
/**
|
|
292
|
-
* Cumulative count of listener invocations that threw. Swallowed
|
|
293
|
-
* inside the cache (a buggy consumer must not crash the SDK) but
|
|
294
|
-
* surfaced here so developers can spot broken subscribers.
|
|
295
|
-
*/
|
|
296
|
-
listenerErrors: number;
|
|
297
|
-
};
|
|
298
|
-
events: {
|
|
299
|
-
buffered: number;
|
|
300
|
-
dropped: number;
|
|
301
|
-
inFlight: number;
|
|
302
|
-
lastFlushAt: number;
|
|
303
|
-
lastError: string | null;
|
|
304
|
-
/** Consecutive flush failures since the last success. */
|
|
305
|
-
consecutiveFailures: number;
|
|
306
|
-
/**
|
|
307
|
-
* When the next retry is scheduled (epoch ms), or null if the queue
|
|
308
|
-
* is idle / healthy.
|
|
309
|
-
*/
|
|
310
|
-
nextRetryAt: number | null;
|
|
311
|
-
};
|
|
312
|
-
}
|
|
313
|
-
|
|
314
|
-
export type { AliasResult as A, CrossdeckOptions as C, Diagnostics as D, EventProperties as E, GroupTraits as G, HeartbeatResponse as H, IdentifyOptions as I, KeyValueStorage as K, PublicEntitlement as P, PurchaseResult as a, AuditRail as b, AutoTrackOptions as c, EntitlementsListResponse as d, Environment as e, Platform as f };
|