@cross-deck/web 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,306 @@
+/**
+ * Public types for @cross-deck/web. These mirror the wire format
+ * exposed by the v1 backend API. Keep them in lockstep with
+ * backend/src/api/v1-types.ts — same field names, same nullability.
+ */
+type Environment = "production" | "sandbox";
+type Platform = "ios" | "android" | "web";
+type AuditRail = "apple" | "stripe" | "google" | "manual";
+interface PublicEntitlement {
+    object: "entitlement";
+    key: string;
+    isActive: boolean;
+    validUntil?: number | null;
+    source: {
+        rail: AuditRail;
+        productId: string;
+        subscriptionId: string;
+    };
+    updatedAt: number;
+}
+interface EntitlementsListResponse {
+    object: "list";
+    data: PublicEntitlement[];
+    crossdeckCustomerId: string;
+    env: Environment;
+}
+interface AliasResult {
+    object: "alias_result";
+    crossdeckCustomerId: string;
+    linked: Array<{
+        type: "developer";
+        id: string;
+    } | {
+        type: "anonymous";
+        id: string;
+    }>;
+    mergePending: boolean;
+    env: Environment;
+}
+interface PurchaseResult {
+    object: "purchase_result";
+    crossdeckCustomerId: string;
+    env: Environment;
+    entitlements: PublicEntitlement[];
+}
+interface HeartbeatResponse {
+    object: "heartbeat";
+    ok: true;
+    projectId: string;
+    appId: string;
+    platform: Platform;
+    env: Environment;
+    serverTime: number;
+}
+/**
+ * Configuration for Crossdeck.start. Most fields have sensible defaults
+ * — only `publicKey` is mandatory.
+ */
+interface CrossdeckOptions {
+    /** Your Crossdeck publishable key (cd_pub_…). Required. */
+    publicKey: string;
+    /**
+     * Override the API base URL. Default is https://api.cross-deck.com/v1.
+     * Useful for self-hosted setups or pointing at the local emulator
+     * (e.g. http://localhost:5001/crossdeck-47d8f/us-east4/v1).
+     */
+    baseUrl?: string;
+    /**
+     * Persist anonymousId + crossdeckCustomerId across sessions.
+     * Default: true in the browser (localStorage), false in Node (in-memory only).
+     */
+    persistIdentity?: boolean;
+    /**
+     * Storage adapter. The SDK calls .getItem / .setItem / .removeItem.
+     * Defaults to globalThis.localStorage when present. Pass an in-memory
+     * adapter for Node runtimes where you want session-only persistence.
+     */
+    storage?: KeyValueStorage;
+    /** Storage key prefix for the SDK's persisted state. Default "crossdeck:". */
+    storagePrefix?: string;
+    /**
+     * Send a heartbeat to /v1/sdk/heartbeat on start(). Default true.
+     * Disable for high-frequency boot scenarios where the heartbeat is
+     * pure overhead.
+     */
+    autoHeartbeat?: boolean;
+    /** Maximum events buffered before forced flush. Default 20. */
+    eventFlushBatchSize?: number;
+    /** Idle ms after the last track() before flushing. Default 5000. */
+    eventFlushIntervalMs?: number;
+    /** Override the SDK version reported on heartbeats. Default: package version. */
+    sdkVersion?: string;
+}
+/** Minimal interface for any pluggable key-value persistence. */
+interface KeyValueStorage {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+/** Identity hint object passed to identify() — at least one field required. */
+interface IdentifyOptions {
+    /** Optional email to attach to the customer record. */
+    email?: string;
+}
+/** Properties payload for track(). Arbitrary key/value, JSON-serialisable, ≤ 8 KB. */
+type EventProperties = Record<string, unknown>;
+/**
+ * Diagnostic snapshot returned by Crossdeck.diagnostics(). Stable shape
+ * whether or not start() has been called — callers don't need to narrow
+ * on `started` to read `events` or `entitlements`. Pre-start values are
+ * sensible empties (zeros, nulls).
+ */
+interface Diagnostics {
+    started: boolean;
+    anonymousId: string | null;
+    crossdeckCustomerId: string | null;
+    developerUserId: string | null;
+    sdkVersion: string | null;
+    baseUrl: string | null;
+    entitlements: {
+        count: number;
+        lastUpdated: number;
+    };
+    events: {
+        buffered: number;
+        dropped: number;
+        inFlight: number;
+        lastFlushAt: number;
+        lastError: string | null;
+    };
+}
+
+/**
+ * Public API surface for @cross-deck/web.
+ *
+ * Usage (browser):
+ *
+ *   import { Crossdeck } from "@cross-deck/web";
+ *
+ *   Crossdeck.start({ publicKey: "cd_pub_live_…" });
+ *
+ *   await Crossdeck.identify("user_847");
+ *   const ents = await Crossdeck.getEntitlements();
+ *   if (Crossdeck.isEntitled("pro")) {
+ *     showPro();
+ *   }
+ *   Crossdeck.track("paywall_shown", { variant: "v3" });
+ *
+ *
+ * Usage (Node):
+ *
+ *   import { Crossdeck } from "@cross-deck/web";
+ *   import { MemoryStorage } from "@cross-deck/web";
+ *
+ *   Crossdeck.start({
+ *     publicKey: "cd_pub_test_…",
+ *     storage: new MemoryStorage(),  // session-only persistence
+ *     autoHeartbeat: false,           // skip the boot ping in scripts
+ *   });
+ */
+
+declare class CrossdeckClient {
+    private state;
+    /**
+     * Boot the SDK. Idempotent — calling start twice with the same options
+     * is a no-op; calling with different options replaces the previous
+     * configuration.
+     */
+    start(options: CrossdeckOptions): void;
+    /**
+     * Link the anonymous device to a developer-supplied user ID. Cache
+     * the resolved Crossdeck customer for follow-up calls.
+     */
+    identify(userId: string, _options?: IdentifyOptions): Promise<AliasResult>;
+    /**
+     * Read the current customer's active entitlements from the server.
+     * Updates the local cache so subsequent isEntitled() calls answer
+     * synchronously.
+     */
+    getEntitlements(): Promise<PublicEntitlement[]>;
+    /**
+     * Synchronous read from the local cache. Returns false if the cache
+     * has never been populated (call getEntitlements first to warm it).
+     */
+    isEntitled(key: string): boolean;
+    /** Snapshot of the local entitlement cache. */
+    listEntitlements(): PublicEntitlement[];
+    /**
+     * Queue a telemetry event. Returns immediately — the network round-
+     * trip happens in the background. To flush before the page unloads,
+     * call flushEvents().
+     */
+    track(name: string, properties?: EventProperties): void;
+    /** Force-flush queued events. Useful to call from page-unload handlers. */
+    flushEvents(): Promise<void>;
+    /** Forward an Apple StoreKit 2 transaction for verification + projection. */
+    purchaseApple(input: {
+        signedTransactionInfo: string;
+        signedRenewalInfo?: string;
+        appAccountToken?: string;
+    }): Promise<PurchaseResult>;
+    /**
+     * Send the boot heartbeat. Called automatically by start() unless
+     * autoHeartbeat:false. Safe to call manually as a "we're still here" ping.
+     */
+    heartbeat(): Promise<HeartbeatResponse>;
+    /**
+     * Wipe persisted identity + entitlement cache. Use on logout. The
+     * next pre-login session generates a fresh anonymousId and starts a
+     * new identity-graph entry.
+     */
+    reset(): void;
+    /**
+     * Diagnostic: current state + queue stats. Useful for the dashboard's
+     * heartbeat row and debugging in dev.
+     *
+     * Returns a stable shape regardless of whether start() has been called —
+     * callers don't need to narrow on `started` to access `events` or
+     * `entitlements`. Pre-start values are sensible empties.
+     */
+    diagnostics(): Diagnostics;
+    private requireStarted;
+    /**
+     * Build the identity query for /v1/entitlements. Priority:
+     *   crossdeckCustomerId > developerUserId > anonymousId
+     * — matches the resolveCrossdeckCustomerId precedence on the server.
+     */
+    private identityQueryParams;
+    /** Pick the right identity hint to embed on a queued event. */
+    private identityHintForEvent;
+    private mintEventId;
+}
+/**
+ * Default singleton — most consumers want one SDK instance per app.
+ * Creating extra instances is fine; just `new CrossdeckClient()`.
+ */
+declare const Crossdeck: CrossdeckClient;
+
+/**
+ * Stripe-style error wrapper for @cross-deck/web.
+ *
+ * Mirrors the wire shape returned by the v1 backend (see
+ * backend/src/api/v1-errors.ts) so SDK consumers can `catch`
+ * with consistent fields:
+ *
+ *   try {
+ *     await crossdeck.identify("user_847");
+ *   } catch (err) {
+ *     if (err instanceof CrossdeckError && err.code === "invalid_api_key") {
+ *       // ...
+ *     }
+ *   }
+ */
+type CrossdeckErrorType = "authentication_error" | "permission_error" | "invalid_request_error" | "rate_limit_error" | "internal_error" | "network_error" | "configuration_error";
+interface CrossdeckErrorPayload {
+    type: CrossdeckErrorType;
+    code: string;
+    message: string;
+    /** Server-issued request ID. Echoed in support tickets. */
+    requestId?: string;
+    /** HTTP status code if the error came from an API response. */
+    status?: number;
+}
+declare class CrossdeckError extends Error {
+    readonly type: CrossdeckErrorType;
+    readonly code: string;
+    readonly requestId?: string;
+    readonly status?: number;
+    constructor(payload: CrossdeckErrorPayload);
+}
+
+/**
+ * Storage adapters for SDK-persisted state.
+ *
+ * Two flavours:
+ *   - browser localStorage (default in browsers)
+ *   - in-memory (default in Node, or as an explicit fallback)
+ *
+ * Detection is at construction time, not at every call — picking the
+ * adapter once means we don't hit `typeof window` checks on hot paths.
+ */
+
+/**
+ * In-memory storage. Cleared on process exit. Useful for Node runtimes
+ * where you want session-scoped identity that doesn't persist to disk.
+ */
+declare class MemoryStorage implements KeyValueStorage {
+    private store;
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+
+/**
+ * HTTP transport for the SDK. Single fetch wrapper used by every endpoint
+ * call. Adds the Bearer token and SDK version header, parses responses,
+ * normalises errors to CrossdeckError.
+ *
+ * Uses platform-native fetch (browser + Node 18+). No axios, no isomorphic-
+ * fetch shim, no transitive deps.
+ */
+declare const SDK_NAME = "@cross-deck/web";
+declare const SDK_VERSION = "0.1.0";
+declare const DEFAULT_BASE_URL = "https://api.cross-deck.com/v1";
+
+export { type AliasResult, type AuditRail, Crossdeck, CrossdeckClient, CrossdeckError, type CrossdeckErrorPayload, type CrossdeckErrorType, type CrossdeckOptions, DEFAULT_BASE_URL, 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 };