@cross-deck/web 0.6.0 → 0.10.0

package/dist/index.d.mts

@@ -139,6 +139,23 @@ interface CrossdeckOptions {
      * `Crossdeck.setDebugMode(true)` after init.
      */
     debug?: boolean;
+    /**
+     * Respect the browser's Do Not Track signal at init (v0.10.0+).
+     * Default `false`. When `true` AND the user has `navigator.doNotTrack === "1"`,
+     * the SDK boots with analytics / marketing / errors all denied —
+     * locked off even if the developer later calls `Crossdeck.consent({...})`.
+     * Industry has effectively deprecated DNT, but opt-in support is the
+     * polite default for privacy-first apps.
+     */
+    respectDnt?: boolean;
+    /**
+     * Scrub PII-shaped strings (email addresses, card numbers) from
+     * URL paths, event properties, and acquisition referrer before they
+     * leave the SDK. Default `true` — Stripe-grade. Disable only if your
+     * pipeline does its own PII redaction downstream and you need the
+     * raw strings.
+     */
+    scrubPii?: boolean;
 }
 /** Auto-tracking flags. See CrossdeckOptions.autoTrack. */
 interface AutoTrackOptions {
@@ -148,6 +165,23 @@ interface AutoTrackOptions {
     pageViews: boolean;
     /** Auto-attach os/browser/locale/screen/etc to every event's `properties`. Default true (browser only). */
     deviceInfo: boolean;
+    /**
+     * Click autocapture — fire `element.clicked` for every interactive
+     * click on the page. Default true. Mixpanel/Amplitude pattern. Powers
+     * Crossdeck's funnel-attribution USP ("clicked X then converted").
+     * Privacy: skips form inputs / password fields / [class~="cd-noTrack"]
+     * subtrees. Override on individual elements with data-cd-event="custom"
+     * or data-cd-prop-* for custom property tagging.
+     */
+    clicks: boolean;
+    /**
+     * Web Vitals capture (v0.9.0+) — emits `webvitals.lcp`, `webvitals.inp`,
+     * `webvitals.cls`, `webvitals.fcp`, `webvitals.ttfb` events using the
+     * browser's `PerformanceObserver`. Defaults to true in browsers,
+     * no-op everywhere else. Disable if you have a separate RUM provider
+     * (DataDog, Sentry Performance) and don't want duplicates.
+     */
+    webVitals: boolean;
 }
 /** Minimal interface for any pluggable key-value persistence. */
 interface KeyValueStorage {
@@ -155,10 +189,44 @@ interface KeyValueStorage {
     setItem(key: string, value: string): void;
     removeItem(key: string): void;
 }
-/** Identity hint object passed to identify() — at least one field required. */
+/**
+ * Identity hint + profile traits passed to identify().
+ *
+ * `traits` is a free-form bag of profile data (name, plan, signupDate,
+ * teamRole, etc.) that gets persisted on the Crossdeck customer record
+ * and attached to every subsequent event of the identified user as
+ * `$user.<key>` properties for dashboard filtering.
+ *
+ * Like event properties, traits are validated at the SDK boundary —
+ * functions/symbols/undefined dropped, Date / BigInt / Error coerced,
+ * strings > 1024 chars truncated. Caller's object is never mutated.
+ */
 interface IdentifyOptions {
     /** Optional email to attach to the customer record. */
     email?: string;
+    /**
+     * Optional profile traits. Examples:
+     *   `{ name: "Wes", plan: "pro", signedUpAt: "2026-05-11" }`
+     *
+     * Treated like event properties — values are sanitised at the SDK
+     * boundary so a `{ avatar: <File>, callback: () => {} }` payload
+     * doesn't crash the alias request. Server-side, traits land on
+     * `customers/{cdcust}.traits` (additively — existing fields are
+     * preserved unless the new identify call overrides them).
+     */
+    traits?: Record<string, unknown>;
+}
+/**
+ * Group context — Mixpanel-style. Identifies a customer's membership
+ * in an organisational entity (org, account, team, workspace) so B2B
+ * dashboards can answer "how is account X using my product".
+ *
+ * Attached to every event as `$groups.<type>` until cleared via
+ * `Crossdeck.group(type, null)`. Multiple types can coexist (e.g.
+ * `org` + `team`) — the SDK keeps a map keyed by type.
+ */
+interface GroupTraits {
+    [key: string]: unknown;
 }
 /** Properties payload for track(). Arbitrary key/value, JSON-serialisable, ≤ 8 KB. */
 type EventProperties = Record<string, unknown>;
@@ -175,9 +243,34 @@ interface Diagnostics {
     developerUserId: string | null;
     sdkVersion: string | null;
     baseUrl: string | null;
+    /**
+     * Last `serverTime` value the SDK saw on a /sdk/heartbeat response,
+     * along with the local clock value AT that moment. Lets dashboards
+     * (and the developer, in debug mode) detect a wrong-system-clock
+     * problem before it corrupts a day of analytics. Null until the
+     * first heartbeat completes.
+     */
+    clock: {
+        /** Server's view of "now" from the last heartbeat (epoch ms). */
+        lastServerTime: number | null;
+        /** Client's `Date.now()` taken at the same moment as `lastServerTime`. */
+        lastClientTime: number | null;
+        /**
+         * `lastClientTime - lastServerTime` — positive means the client
+         * clock is AHEAD of the server. Outside ±5 minutes is suspicious
+         * and worth surfacing to the developer.
+         */
+        skewMs: number | null;
+    };
     entitlements: {
         count: number;
         lastUpdated: number;
+        /**
+         * Cumulative count of listener invocations that threw. Swallowed
+         * inside the cache (a buggy consumer must not crash the SDK) but
+         * surfaced here so developers can spot broken subscribers.
+         */
+        listenerErrors: number;
     };
     events: {
         buffered: number;
@@ -185,6 +278,13 @@ interface Diagnostics {
         inFlight: number;
         lastFlushAt: number;
         lastError: string | null;
+        /** Consecutive flush failures since the last success. */
+        consecutiveFailures: number;
+        /**
+         * When the next retry is scheduled (epoch ms), or null if the queue
+         * is idle / healthy.
+         */
+        nextRetryAt: number | null;
     };
 }
 
@@ -230,6 +330,44 @@ interface Diagnostics {
 
 type EntitlementsListener = (entitlements: PublicEntitlement[]) => void;
 
+/**
+ * Consent gating — GDPR / CCPA-grade kill switches.
+ *
+ * Three independent dimensions, each defaulting to "granted" but
+ * runtime-overridable:
+ *
+ *   analytics  — track(), identify(), heartbeat(), session/page auto-
+ *                emissions. Off → events drop silently, no network
+ *                calls fire.
+ *   marketing  — paid-traffic click IDs (gclid/fbclid/etc) and
+ *                acquisition referrer URL. Off → these get scrubbed
+ *                before they ever land in the event bag.
+ *   errors     — error / breadcrumb / Web Vitals capture. Off → no
+ *                webvitals.* events emitted, no error reporting (when
+ *                Phase 3 errors land).
+ *
+ * Why this granularity: real consent banners offer "Analytics",
+ * "Marketing", "Functional" as separate boxes. The SDK has to match.
+ *
+ * Default state: every dimension is granted. The developer must
+ * explicitly call `Crossdeck.consent({ analytics: false })` before
+ * the first event to opt OUT — same convention as Google Tag Manager
+ * Consent Mode. To start in deny mode, call `init(...)` then
+ * immediately `consent({ analytics: false, marketing: false, errors:
+ * false })` before any user activity.
+ *
+ * DNT (Do Not Track) browser header is checked once at init and
+ * applied as an automatic deny across all dimensions when
+ * `respectDnt: true` is set in CrossdeckOptions (default false because
+ * the industry has effectively deprecated DNT — but opt-in support
+ * is the polite default for privacy-first apps).
+ */
+interface ConsentState {
+    analytics: boolean;
+    marketing: boolean;
+    errors: boolean;
+}
+
 /**
  * Public API surface for @cross-deck/web.
  *
@@ -285,8 +423,88 @@ declare class CrossdeckClient {
     /**
      * Link the anonymous device to a developer-supplied user ID. Cache
      * the resolved Crossdeck customer for follow-up calls.
+     *
+     * v0.9.0+ accepts an optional `traits` bag — profile data (name,
+     * plan, signupDate, role) persisted on the Crossdeck customer record
+     * and queryable from dashboards. Traits are sanitised through the
+     * same validator that gates `track()` properties, so a `{ avatar:
+     * <File>, onSave: () => {} }` payload can't corrupt the alias call.
+     *
+     *   Crossdeck.identify("user_847", {
+     *     email: "wes@pinet.co.za",
+     *     traits: { name: "Wes", plan: "pro", signedUpAt: "2026-05-11" },
+     *   });
      */
-    identify(userId: string, _options?: IdentifyOptions): Promise<AliasResult>;
+    identify(userId: string, options?: IdentifyOptions): Promise<AliasResult>;
+    /**
+     * Register super-properties — Mixpanel pattern. Once set, every
+     * subsequent event of THIS SDK instance carries these keys on its
+     * properties bag automatically.
+     *
+     *   Crossdeck.register({ plan: "pro", releaseChannel: "beta" });
+     *   Crossdeck.track("paywall_shown");  // includes plan + releaseChannel
+     *
+     * Values that are `null` are deleted (the explicit "stop tracking
+     * this key" idiom). Returns the resulting bag.
+     *
+     * Sanitised through `validateEventProperties` so a `{ avatar: File }`
+     * payload can't poison the queue at flush time.
+     */
+    register(properties: Record<string, unknown>): Record<string, unknown>;
+    /** Remove a single super-property key. Idempotent. */
+    unregister(key: string): void;
+    /** Snapshot of the current super-property bag. */
+    getSuperProperties(): Record<string, unknown>;
+    /**
+     * Associate the current user with a group (org, team, account, etc.).
+     * Mixpanel / Segment "Group Analytics" pattern.
+     *
+     *   Crossdeck.group("org", "acme_inc");
+     *   Crossdeck.group("team", "design", { headcount: 12 });
+     *
+     * Once set, every subsequent event carries `$groups.<type>: id` on
+     * its properties bag, enabling B2B dashboards ("how is Acme using
+     * the product"). Pass `id: null` to clear a group membership.
+     */
+    group(type: string, id: string | null, traits?: GroupTraits): void;
+    /** Snapshot of the current groups map keyed by type. */
+    getGroups(): Record<string, {
+        id: string;
+        traits?: Record<string, unknown>;
+    }>;
+    /**
+     * Update consent state. Three independent dimensions:
+     *
+     *   analytics  — track() + identify() + auto-emissions
+     *   marketing  — paid-traffic click IDs + referrer URL on events
+     *   errors     — Web Vitals + (future) error reporting
+     *
+     * Each defaults to `true` (granted). Pass partial state — only the
+     * keys you provide are changed.
+     *
+     *   Crossdeck.consent({ analytics: false });
+     *   Crossdeck.consent({ marketing: true, errors: true });
+     *
+     * DNT-derived denies cannot be flipped back on; if the browser said
+     * "don't track" we don't track even if the developer code disagrees.
+     */
+    consent(state: Partial<ConsentState>): ConsentState;
+    /** Snapshot of the current consent state. */
+    consentStatus(): ConsentState;
+    /**
+     * GDPR/CCPA "right to be forgotten" — calls the backend's
+     * /v1/identity/forget endpoint to schedule a server-side deletion of
+     * the customer's events and profile, then wipes all local state
+     * (identity, entitlements, queue, super-props, persistent stores).
+     *
+     * Idempotent. Safe to call when no identity has been established
+     * (it just wipes the empty local state).
+     *
+     * After forget() resolves, the SDK is in the same shape as if the
+     * developer had called `Crossdeck.reset()` — a fresh anonymousId is
+     * minted and the next session is a brand new identity-graph entry.
+     */
+    forget(): Promise<void>;
     /**
      * Read the current customer's active entitlements from the server.
      * Updates the local cache so subsequent isEntitled() calls answer
@@ -402,7 +620,20 @@ declare class CrossdeckClient {
      * — matches the resolveCrossdeckCustomerId precedence on the server.
      */
     private identityQueryParams;
-    /** Pick the right identity hint to embed on a queued event. */
+    /**
+     * Embed every known identity axis on the event. Earlier this returned
+     * just the highest-priority hint (cdcust → developerUserId → anonymousId)
+     * to keep payloads small, but that leaked into analytics: once a user
+     * was logged in, every subsequent page.viewed shipped without
+     * anonymousId, and `uniqExact(anonymous_id)` on the warehouse side
+     * counted 0 visitors for the entire authenticated app.
+     *
+     * Bank-grade rule: the server is the single source of truth on
+     * dedup. Send everything we know; let CH count by whichever axis
+     * matches the question. Each field is at most 32 bytes — sending
+     * three on every event costs ~80 bytes per request, which is
+     * trivial compared to the analytics correctness it buys.
+     */
     private identityHintForEvent;
     private mintEventId;
 }
@@ -436,12 +667,21 @@ interface CrossdeckErrorPayload {
     requestId?: string;
     /** HTTP status code if the error came from an API response. */
     status?: number;
+    /**
+     * Server-suggested wait (in milliseconds) before retrying. Populated
+     * from the `Retry-After` response header on 429 / 503. The header
+     * spec allows either delta-seconds or an HTTP-date; the parser below
+     * normalises both to milliseconds. Consumers MUST honour this — the
+     * server is telling you the safe rate.
+     */
+    retryAfterMs?: number;
 }
 declare class CrossdeckError extends Error {
     readonly type: CrossdeckErrorType;
     readonly code: string;
     readonly requestId?: string;
     readonly status?: number;
+    readonly retryAfterMs?: number;
     constructor(payload: CrossdeckErrorPayload);
 }
 
@@ -504,9 +744,45 @@ declare class MemoryStorage implements KeyValueStorage {
  * fetch shim, no transitive deps.
  */
 declare const SDK_NAME = "@cross-deck/web";
-declare const SDK_VERSION = "0.6.0";
+declare const SDK_VERSION = "0.10.0";
 declare const DEFAULT_BASE_URL = "https://api.cross-deck.com/v1";
 
+/**
+ * Machine-readable index of every error code the SDK can throw, with
+ * a short description and a hint on what action to take. Published
+ * verbatim as `crossdeck-error-codes.json` in the npm tarball so AI
+ * integration assistants, error-aggregator dashboards (Sentry,
+ * DataDog), and the Crossdeck dashboard can render human-friendly
+ * messages without parsing freeform `message` strings.
+ *
+ * Stripe publishes the same surface at stripe.com/docs/error-codes;
+ * developers love it because every code has a canonical "what does
+ * this mean / what should I do" answer.
+ *
+ * Adding a new error code:
+ *   1. Add the code string to the union in `errors.ts` (where used).
+ *   2. Add an entry here.
+ *   3. The next `npm run build` regenerates the JSON sidecar.
+ *
+ * Keep entries terse — the consumer surfaces this in tooltips and
+ * automated tickets, not in long-form docs.
+ */
+interface ErrorCodeEntry {
+    /** The string thrown as CrossdeckError.code. */
+    code: string;
+    /** CrossdeckError.type — broad category. */
+    type: "authentication_error" | "permission_error" | "invalid_request_error" | "rate_limit_error" | "internal_error" | "network_error" | "configuration_error";
+    /** One-sentence description. Surfaced verbatim in dashboards. */
+    description: string;
+    /** What the developer should do. Imperative phrasing. */
+    resolution: string;
+    /** True for codes the SDK can auto-recover from (no developer action). */
+    retryable: boolean;
+}
+declare const CROSSDECK_ERROR_CODES: readonly ErrorCodeEntry[];
+/** Lookup helper — returns the entry matching a CrossdeckError.code, or undefined. */
+declare function getErrorCode(code: string): ErrorCodeEntry | undefined;
+
 /**
  * Device + environment enrichment.
  *
@@ -541,4 +817,4 @@ interface DeviceInfo {
     appVersion?: string;
 }
 
-export { type AliasResult, type AuditRail, type AutoTrackOptions, Crossdeck, CrossdeckClient, CrossdeckError, type CrossdeckErrorPayload, type CrossdeckErrorType, type CrossdeckOptions, DEFAULT_BASE_URL, type DeviceInfo, type Diagnostics, type EntitlementsListResponse, type Environment, type EventProperties, type HeartbeatResponse, type IdentifyOptions, type KeyValueStorage, MemoryStorage, type Platform, type PublicEntitlement, type PurchaseResult, SDK_NAME, SDK_VERSION };
+export { type AliasResult, type AuditRail, type AutoTrackOptions, CROSSDECK_ERROR_CODES, type ConsentState, Crossdeck, CrossdeckClient, CrossdeckError, type CrossdeckErrorPayload, type CrossdeckErrorType, type CrossdeckOptions, DEFAULT_BASE_URL, type DeviceInfo, type Diagnostics, type EntitlementsListResponse, type Environment, type ErrorCodeEntry, type EventProperties, type GroupTraits, type HeartbeatResponse, type IdentifyOptions, type KeyValueStorage, MemoryStorage, type Platform, type PublicEntitlement, type PurchaseResult, SDK_NAME, SDK_VERSION, getErrorCode };