@cross-deck/node 0.1.0 → 1.1.0

package/dist/index.mjs

@@ -1,5 +1,5 @@
 // src/crossdeck-server.ts
-import { randomUUID } from "crypto";
+import { EventEmitter } from "events";
 
 // src/errors.ts
 var CrossdeckError = class _CrossdeckError extends Error {
@@ -18,7 +18,98 @@ var CrossdeckError = class _CrossdeckError extends Error {
     this.retryAfterMs = payload.retryAfterMs;
     Object.setPrototypeOf(this, _CrossdeckError.prototype);
   }
+  /**
+   * JSON representation suitable for structured loggers. Without this,
+   * `console.log(err)` and most log frameworks (Pino, Winston) emit
+   * only `name` + `message` + `stack` — losing `type`, `code`,
+   * `requestId`, `status`, `retryAfterMs`. With `toJSON`, calling
+   * `JSON.stringify(err)` or passing the error to a logger that
+   * serialises via JSON includes the full diagnostic surface.
+   *
+   * Stripe pattern. Critical for production observability.
+   */
+  toJSON() {
+    return {
+      name: this.name,
+      message: this.message,
+      type: this.type,
+      code: this.code,
+      requestId: this.requestId,
+      status: this.status,
+      retryAfterMs: this.retryAfterMs,
+      stack: this.stack
+    };
+  }
+};
+var CrossdeckAuthenticationError = class _CrossdeckAuthenticationError extends CrossdeckError {
+  constructor(payload) {
+    super(payload);
+    this.name = "CrossdeckAuthenticationError";
+    Object.setPrototypeOf(this, _CrossdeckAuthenticationError.prototype);
+  }
+};
+var CrossdeckPermissionError = class _CrossdeckPermissionError extends CrossdeckError {
+  constructor(payload) {
+    super(payload);
+    this.name = "CrossdeckPermissionError";
+    Object.setPrototypeOf(this, _CrossdeckPermissionError.prototype);
+  }
+};
+var CrossdeckValidationError = class _CrossdeckValidationError extends CrossdeckError {
+  constructor(payload) {
+    super(payload);
+    this.name = "CrossdeckValidationError";
+    Object.setPrototypeOf(this, _CrossdeckValidationError.prototype);
+  }
+};
+var CrossdeckRateLimitError = class _CrossdeckRateLimitError extends CrossdeckError {
+  constructor(payload) {
+    super(payload);
+    this.name = "CrossdeckRateLimitError";
+    Object.setPrototypeOf(this, _CrossdeckRateLimitError.prototype);
+  }
+};
+var CrossdeckNetworkError = class _CrossdeckNetworkError extends CrossdeckError {
+  constructor(payload) {
+    super(payload);
+    this.name = "CrossdeckNetworkError";
+    Object.setPrototypeOf(this, _CrossdeckNetworkError.prototype);
+  }
+};
+var CrossdeckInternalError = class _CrossdeckInternalError extends CrossdeckError {
+  constructor(payload) {
+    super(payload);
+    this.name = "CrossdeckInternalError";
+    Object.setPrototypeOf(this, _CrossdeckInternalError.prototype);
+  }
+};
+var CrossdeckConfigurationError = class _CrossdeckConfigurationError extends CrossdeckError {
+  constructor(payload) {
+    super(payload);
+    this.name = "CrossdeckConfigurationError";
+    Object.setPrototypeOf(this, _CrossdeckConfigurationError.prototype);
+  }
 };
+function makeCrossdeckError(payload) {
+  switch (payload.type) {
+    case "authentication_error":
+      return new CrossdeckAuthenticationError(payload);
+    case "permission_error":
+      return new CrossdeckPermissionError(payload);
+    case "invalid_request_error":
+      return new CrossdeckValidationError(payload);
+    case "rate_limit_error":
+      return new CrossdeckRateLimitError(payload);
+    case "network_error":
+      return new CrossdeckNetworkError(payload);
+    case "internal_error":
+      return new CrossdeckInternalError(payload);
+    case "configuration_error":
+      return new CrossdeckConfigurationError(payload);
+    default:
+      return new CrossdeckError(payload);
+  }
+}
 async function crossdeckErrorFromResponse(res) {
   const requestId = res.headers.get("x-request-id") ?? void 0;
   const retryAfterMs = parseRetryAfterHeader(res.headers.get("retry-after"));
@@ -30,7 +121,7 @@ async function crossdeckErrorFromResponse(res) {
   }
   const envelope = body?.error;
   if (envelope && typeof envelope.type === "string" && typeof envelope.code === "string") {
-    return new CrossdeckError({
+    return makeCrossdeckError({
       type: envelope.type,
       code: envelope.code,
       message: envelope.message ?? `HTTP ${res.status}`,
@@ -39,7 +130,7 @@ async function crossdeckErrorFromResponse(res) {
       retryAfterMs
     });
   }
-  return new CrossdeckError({
+  return makeCrossdeckError({
     type: typeMapForStatus(res.status),
     code: `http_${res.status}`,
     message: `HTTP ${res.status} ${res.statusText || ""}`.trim(),
@@ -227,66 +318,193 @@ function byteLength(s) {
 
 // src/http.ts
 var SDK_NAME = "@cross-deck/node";
-var SDK_VERSION = "0.1.0";
+var SDK_VERSION = "1.1.0";
 var DEFAULT_BASE_URL = "https://api.cross-deck.com/v1";
 var DEFAULT_TIMEOUT_MS = 15e3;
+var CROSSDECK_API_VERSION = "2025-01-01";
+var DEFAULT_GET_RETRY_ATTEMPTS = 3;
+var DEFAULT_RETRYABLE_STATUSES = /* @__PURE__ */ new Set([408, 500, 502, 503, 504]);
 var HttpClient = class {
   constructor(config) {
     this.config = config;
+    this.userAgent = buildUserAgent(config.sdkVersion, config.runtimeToken);
   }
   config;
+  userAgent;
   async request(method, path, options = {}) {
     const url = this.buildUrl(path, options.query);
-    const headers = {
-      Authorization: `Bearer ${this.config.secretKey}`,
-      "Crossdeck-Sdk-Version": `${SDK_NAME}@${this.config.sdkVersion}`,
-      Accept: "application/json"
-    };
-    if (options.idempotencyKey) headers["Idempotency-Key"] = options.idempotencyKey;
-    let bodyInit;
-    if (options.body !== void 0) {
-      headers["Content-Type"] = "application/json";
-      bodyInit = serializeRequestBody(options.body);
+    if (this.config.testMode === true) {
+      return this.synthesizeTestModeResponse(method, path, url, options);
+    }
+    const headers = this.buildHeaders(options);
+    const bodyInit = this.buildBody(headers, options.body);
+    const retryCfg = options.retries ?? this.config.httpRetries ?? {};
+    const maxAttempts = method === "GET" ? retryCfg.maxAttempts ?? DEFAULT_GET_RETRY_ATTEMPTS : 1;
+    const retryableStatuses = retryCfg.retryableStatuses ? new Set(retryCfg.retryableStatuses) : DEFAULT_RETRYABLE_STATUSES;
+    let lastError = null;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+      const reqInfo = {
+        method,
+        url,
+        headers,
+        bodyPreview: typeof bodyInit === "string" ? bodyInit : void 0,
+        attempt
+      };
+      try {
+        this.config.onRequest?.(reqInfo);
+      } catch {
+      }
+      const start = Date.now();
+      let response = null;
+      let networkError = null;
+      try {
+        response = await this.dispatch(url, method, headers, bodyInit, options);
+      } catch (err) {
+        networkError = err;
+      }
+      const durationMs = Date.now() - start;
+      if (response) {
+        try {
+          this.config.onResponse?.({
+            method,
+            url,
+            status: response.status,
+            durationMs,
+            attempt,
+            testMode: false
+          });
+        } catch {
+        }
+      }
+      if (networkError !== null) {
+        lastError = this.translateNetworkError(networkError, path, options);
+        if (method === "GET" && attempt < maxAttempts) {
+          await sleepWithJitter(attempt);
+          continue;
+        }
+        throw lastError;
+      }
+      if (response && !response.ok) {
+        const err = await crossdeckErrorFromResponse(response);
+        if (method === "GET" && retryableStatuses.has(response.status) && attempt < maxAttempts) {
+          lastError = err;
+          await sleepForRetry(err, attempt);
+          continue;
+        }
+        throw err;
+      }
+      if (response.status === 204) return void 0;
+      try {
+        return await response.json();
+      } catch {
+        throw makeCrossdeckError({
+          type: "internal_error",
+          code: "invalid_json_response",
+          message: "Server returned a 2xx with an unparseable body.",
+          requestId: response.headers.get("x-request-id") ?? void 0,
+          status: response.status
+        });
+      }
     }
+    throw lastError ?? makeCrossdeckError({
+      type: "internal_error",
+      code: "retry_exhausted",
+      message: `GET ${path} exhausted ${maxAttempts} attempts.`
+    });
+  }
+  /**
+   * Issue a single fetch invocation. Composes the per-request timeout
+   * with the caller-supplied AbortSignal — whichever fires first wins.
+   */
+  async dispatch(url, method, headers, bodyInit, options) {
     const effectiveTimeout = options.timeoutMs ?? this.config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
-    const controller = typeof AbortController !== "undefined" && effectiveTimeout > 0 ? new AbortController() : null;
+    const supportsAbort = typeof AbortController !== "undefined";
+    const controller = supportsAbort && effectiveTimeout > 0 ? new AbortController() : null;
+    let externalAbortHandler = null;
+    if (controller && options.signal) {
+      if (options.signal.aborted) {
+        controller.abort();
+      } else {
+        externalAbortHandler = () => controller.abort();
+        options.signal.addEventListener("abort", externalAbortHandler, { once: true });
+      }
+    }
     let timeoutHandle = null;
     if (controller && effectiveTimeout > 0) {
       timeoutHandle = setTimeout(() => controller.abort(), effectiveTimeout);
     }
-    let response;
     try {
-      response = await fetch(url, {
+      return await fetch(url, {
         method,
         headers,
         body: bodyInit,
-        signal: controller?.signal
-      });
-    } catch (err) {
-      const aborted = controller?.signal?.aborted === true;
-      throw new CrossdeckError({
-        type: "network_error",
-        code: aborted ? "request_timeout" : "fetch_failed",
-        message: aborted ? `Request to ${path} aborted after ${effectiveTimeout}ms` : err instanceof Error ? err.message : "fetch failed"
+        signal: controller?.signal ?? options.signal
       });
     } finally {
       if (timeoutHandle !== null) clearTimeout(timeoutHandle);
+      if (externalAbortHandler && options.signal) {
+        try {
+          options.signal.removeEventListener("abort", externalAbortHandler);
+        } catch {
+        }
+      }
     }
-    if (!response.ok) {
-      throw await crossdeckErrorFromResponse(response);
+  }
+  /** Build the request headers. Same across attempts so caches can dedupe. */
+  buildHeaders(options) {
+    const headers = {
+      Authorization: `Bearer ${this.config.secretKey}`,
+      "Crossdeck-Sdk-Version": `${SDK_NAME}@${this.config.sdkVersion}`,
+      "Crossdeck-Api-Version": CROSSDECK_API_VERSION,
+      "User-Agent": this.userAgent,
+      Accept: "application/json"
+    };
+    if (options.idempotencyKey) headers["Idempotency-Key"] = options.idempotencyKey;
+    if (options.body !== void 0) {
+      headers["Content-Type"] = "application/json";
     }
-    if (response.status === 204) return void 0;
+    return headers;
+  }
+  buildBody(headers, body) {
+    if (body === void 0) return void 0;
+    void headers;
+    return serializeRequestBody(body);
+  }
+  /** Translate a thrown fetch error or abort into a typed `CrossdeckError`. */
+  translateNetworkError(err, path, options) {
+    const callerAborted = options.signal?.aborted === true || err instanceof Error && (err.name === "AbortError" || /aborted/i.test(err.message));
+    const callerInitiated = options.signal?.aborted === true;
+    return makeCrossdeckError({
+      type: "network_error",
+      code: callerAborted ? callerInitiated ? "request_aborted" : "request_timeout" : "fetch_failed",
+      message: callerAborted ? callerInitiated ? `Request to ${path} aborted by caller AbortSignal.` : `Request to ${path} aborted after ${options.timeoutMs ?? this.config.timeoutMs ?? DEFAULT_TIMEOUT_MS}ms` : err instanceof Error ? err.message : "fetch failed"
+    });
+  }
+  /** Synthesise a benign success-shaped response for `testMode: true`. */
+  synthesizeTestModeResponse(method, path, url, options) {
     try {
-      return await response.json();
+      this.config.onRequest?.({
+        method,
+        url,
+        headers: this.buildHeaders(options),
+        bodyPreview: options.body !== void 0 ? safeStringify2(options.body) : void 0,
+        attempt: 1
+      });
     } catch {
-      throw new CrossdeckError({
-        type: "internal_error",
-        code: "invalid_json_response",
-        message: "Server returned a 2xx with an unparseable body.",
-        requestId: response.headers.get("x-request-id") ?? void 0,
-        status: response.status
+    }
+    const synth = synthForPath(path);
+    try {
+      this.config.onResponse?.({
+        method,
+        url,
+        status: 200,
+        durationMs: 0,
+        attempt: 1,
+        testMode: true
       });
+    } catch {
     }
+    return synth;
   }
   buildUrl(path, query) {
     const base = this.config.baseUrl.replace(/\/+$/, "");
@@ -303,6 +521,134 @@ var HttpClient = class {
     return url;
   }
 };
+function buildUserAgent(sdkVersion, override) {
+  if (override) return `${SDK_NAME}/${sdkVersion} ${override}`;
+  const nodeVersion = typeof process !== "undefined" && process.versions ? process.versions.node : "unknown";
+  const osPlatform2 = typeof process !== "undefined" && process.platform ? process.platform : "unknown";
+  return `${SDK_NAME}/${sdkVersion} node/${nodeVersion} ${osPlatform2}`;
+}
+async function sleepWithJitter(attempt) {
+  const ceiling = Math.min(2e3, 50 * Math.pow(2, attempt - 1));
+  const delay = Math.round(ceiling * Math.random());
+  await new Promise((resolve) => {
+    const t = setTimeout(resolve, delay);
+    if (typeof t.unref === "function") {
+      try {
+        t.unref();
+      } catch {
+      }
+    }
+  });
+}
+async function sleepForRetry(err, attempt) {
+  if (err.retryAfterMs !== void 0 && err.retryAfterMs > 0) {
+    await new Promise((resolve) => {
+      const t = setTimeout(resolve, err.retryAfterMs);
+      if (typeof t.unref === "function") {
+        try {
+          t.unref();
+        } catch {
+        }
+      }
+    });
+    return;
+  }
+  await sleepWithJitter(attempt);
+}
+function synthForPath(path) {
+  if (path.startsWith("/sdk/heartbeat")) {
+    return {
+      object: "heartbeat",
+      ok: true,
+      projectId: "proj_test_mode",
+      appId: "app_test_mode",
+      platform: "node",
+      env: "sandbox",
+      serverTime: Date.now()
+    };
+  }
+  if (path.startsWith("/identity/alias")) {
+    return {
+      object: "alias_result",
+      crossdeckCustomerId: "cdcust_test_mode",
+      linked: [],
+      mergePending: false,
+      env: "sandbox"
+    };
+  }
+  if (path.startsWith("/identity/forget")) {
+    return {
+      object: "forgot",
+      crossdeckCustomerId: null,
+      queuedAt: Date.now(),
+      env: "sandbox"
+    };
+  }
+  if (path.includes("/entitlements")) {
+    return {
+      object: "list",
+      data: [],
+      crossdeckCustomerId: "cdcust_test_mode",
+      env: "sandbox"
+    };
+  }
+  if (path.startsWith("/events")) {
+    return {
+      object: "list",
+      received: 0,
+      env: "sandbox"
+    };
+  }
+  if (path.includes("/purchases/sync")) {
+    return {
+      object: "purchase_result",
+      crossdeckCustomerId: "cdcust_test_mode",
+      env: "sandbox",
+      entitlements: []
+    };
+  }
+  if (path.includes("/grant") || path.includes("/revoke")) {
+    return {
+      object: "entitlement_mutation",
+      action: path.includes("/grant") ? "grant" : "revoke",
+      crossdeckCustomerId: "cdcust_test_mode",
+      entitlement: {
+        object: "entitlement",
+        key: "pro",
+        isActive: path.includes("/grant"),
+        validUntil: null,
+        source: { rail: "manual", productId: "manual", subscriptionId: "manual:test_mode" },
+        updatedAt: Date.now()
+      },
+      env: "sandbox"
+    };
+  }
+  if (path.startsWith("/server/audit/")) {
+    return {
+      object: "audit_entry",
+      data: {
+        eventId: "audit_test_mode",
+        rail: "manual",
+        env: "sandbox",
+        eventType: "test_mode",
+        projectId: "proj_test_mode",
+        decision: "applied",
+        signatureVerified: true,
+        reconciledWithProvider: false,
+        rawEventReceivedAt: Date.now(),
+        processedAt: Date.now()
+      }
+    };
+  }
+  return {};
+}
+function safeStringify2(v) {
+  try {
+    return JSON.stringify(v) ?? "";
+  } catch {
+    return "[unserialisable]";
+  }
+}
 function serializeRequestBody(body) {
   try {
     const direct = JSON.stringify(body);
@@ -329,164 +675,2348 @@ function serializeRequestBody(body) {
   });
 }
 
-// src/crossdeck-server.ts
-var CrossdeckServer = class {
-  http;
-  sdkVersion;
-  appId;
-  constructor(options) {
-    if (!options.secretKey || !options.secretKey.startsWith("cd_sk_")) {
-      throw new CrossdeckError({
-        type: "configuration_error",
-        code: "invalid_secret_key",
-        message: "CrossdeckServer requires a secret key starting with cd_sk_."
-      });
-    }
-    this.sdkVersion = options.sdkVersion ?? SDK_VERSION;
-    this.appId = options.appId;
-    this.http = new HttpClient({
-      secretKey: options.secretKey,
-      baseUrl: options.baseUrl ?? DEFAULT_BASE_URL,
-      sdkVersion: this.sdkVersion,
-      timeoutMs: options.timeoutMs ?? DEFAULT_TIMEOUT_MS
-    });
+// src/retry-policy.ts
+var DEFAULT_BASE = 1e3;
+var DEFAULT_MAX = 6e4;
+var DEFAULT_FACTOR = 2;
+var DEFAULT_WARN = 8;
+function computeNextDelay(attempts, retryAfterMs, options = {}, random = Math.random) {
+  const base = options.baseMs ?? DEFAULT_BASE;
+  const max = options.maxMs ?? DEFAULT_MAX;
+  const factor = options.factor ?? DEFAULT_FACTOR;
+  const safeAttempts = Math.min(attempts, 30);
+  const ceiling = Math.min(max, base * Math.pow(factor, safeAttempts));
+  const jittered = ceiling * random();
+  if (retryAfterMs !== void 0 && retryAfterMs > jittered) {
+    return Math.min(max, retryAfterMs);
   }
-  async identify(userId, anonymousId, options) {
-    return this.aliasIdentity({ userId, anonymousId, ...options });
+  return Math.max(0, Math.round(jittered));
+}
+var RetryPolicy = class {
+  constructor(options = {}) {
+    this.options = options;
   }
-  async aliasIdentity(input) {
-    if (!input.userId) {
-      throw new CrossdeckError({
-        type: "invalid_request_error",
-        code: "missing_user_id",
-        message: "aliasIdentity requires a non-empty userId."
-      });
+  options;
+  attempts = 0;
+  /** How many consecutive failures since the last success. */
+  get consecutiveFailures() {
+    return this.attempts;
+  }
+  /** Whether we've crossed the failuresBeforeWarn threshold. */
+  get isWarning() {
+    return this.attempts >= (this.options.failuresBeforeWarn ?? DEFAULT_WARN);
+  }
+  /** Schedule-time delay for the NEXT retry. Increments the counter. */
+  nextDelay(retryAfterMs, random = Math.random) {
+    const delay = computeNextDelay(this.attempts, retryAfterMs, this.options, random);
+    this.attempts += 1;
+    return delay;
+  }
+  /** Mark a successful flush — reset the counter. */
+  recordSuccess() {
+    this.attempts = 0;
+  }
+};
+
+// src/_rand.ts
+var ALPHABET = "0123456789abcdefghijklmnopqrstuvwxyz";
+function randomChars(count) {
+  const out = [];
+  const cryptoApi = globalThis.crypto;
+  if (cryptoApi?.getRandomValues) {
+    const buf = new Uint8Array(count);
+    cryptoApi.getRandomValues(buf);
+    for (let i = 0; i < count; i++) {
+      out.push(ALPHABET[buf[i] % ALPHABET.length] ?? "0");
     }
-    if (!input.anonymousId) {
-      throw new CrossdeckError({
-        type: "invalid_request_error",
-        code: "missing_anonymous_id",
-        message: "aliasIdentity requires a non-empty anonymousId."
-      });
+  } else {
+    for (let i = 0; i < count; i++) {
+      out.push(ALPHABET[Math.floor(Math.random() * ALPHABET.length)] ?? "0");
     }
-    const traits = sanitizePropertyBag(input.traits, "traits");
-    const body = {
-      userId: input.userId,
-      anonymousId: input.anonymousId
-    };
-    if (input.email) body.email = input.email;
-    if (traits && Object.keys(traits).length > 0) body.traits = traits;
-    return this.http.request("POST", "/identity/alias", { body });
   }
-  async forget(hints) {
-    const body = this.identityPayload(hints);
-    return this.http.request("POST", "/identity/forget", { body });
+  return out.join("");
+}
+function mintId(prefix, randLen = 10) {
+  return `${prefix}_${Date.now().toString(36)}${randomChars(randLen)}`;
+}
+
+// src/event-queue.ts
+var HARD_BUFFER_CAP = 1e3;
+var EventQueue = class {
+  constructor(cfg) {
+    this.cfg = cfg;
+    this.retry = new RetryPolicy(cfg.retry ?? {});
   }
-  async getEntitlements(hints) {
-    return this.http.request("GET", "/entitlements", {
-      query: this.identityPayload(hints)
-    });
+  cfg;
+  buffer = [];
+  dropped = 0;
+  inFlight = 0;
+  lastFlushAt = 0;
+  lastError = null;
+  cancelTimer = null;
+  firstFlushFired = false;
+  nextRetryAt = null;
+  retry;
+  /**
+   * Stable Idempotency-Key for the current in-flight batch. Minted
+   * lazily inside `flush()` when no key is pending. Reused across
+   * retries of the same logical batch so the backend's idempotency
+   * layer can short-circuit duplicates (Stripe pattern). Reset to
+   * `null` after a successful flush.
+   */
+  pendingBatchId = null;
+  /**
+   * In-flight events that have been spliced from the buffer for the
+   * current batch but haven't yet been confirmed (success or final
+   * failure). On a retry-driven flush, we re-use this batch alongside
+   * `pendingBatchId` instead of re-splicing. New events that arrive
+   * during in-flight are buffered separately and join the next batch
+   * AFTER this one settles.
+   */
+  pendingBatch = null;
+  enqueue(event) {
+    this.buffer.push(event);
+    if (this.buffer.length > HARD_BUFFER_CAP) {
+      const overflow = this.buffer.length - HARD_BUFFER_CAP;
+      this.buffer.splice(0, overflow);
+      this.dropped += overflow;
+      this.cfg.onDrop?.(overflow);
+    }
+    this.cfg.onBufferChange?.(this.buffer.length);
+    if (this.buffer.length >= this.cfg.batchSize) {
+      void this.flush();
+    } else {
+      this.scheduleIdleFlush();
+    }
   }
-  async getCustomerEntitlements(customerId) {
-    if (!customerId) {
-      throw new CrossdeckError({
-        type: "invalid_request_error",
-        code: "missing_customer_id",
-        message: "getCustomerEntitlements requires a customerId."
+  /**
+   * Flush the buffer to /v1/events. Resolves when the network call
+   * completes (success or failure). On failure, events stay in the
+   * `pendingBatch` slot for the next scheduled retry — the SAME batch
+   * with the SAME `Idempotency-Key` is re-sent (Stripe pattern).
+   *
+   * The `pendingBatch` slot guarantees retry semantics:
+   *   - First call: splices buffer → pendingBatch + mints batchId.
+   *   - On 5xx / network failure: pendingBatch stays; scheduler fires
+   *     `flush()` again later, which re-uses pendingBatch + the same
+   *     batchId.
+   *   - On success: pendingBatch + batchId cleared; subsequent calls
+   *     splice the buffer again with a fresh batchId.
+   *
+   * New events that arrive during an in-flight batch land in `buffer`
+   * (separate from `pendingBatch`) and ship on the next batch after
+   * this one settles. Strict ordering preserved.
+   */
+  async flush() {
+    let batch;
+    let batchId;
+    if (this.pendingBatch !== null && this.pendingBatchId !== null) {
+      batch = this.pendingBatch;
+      batchId = this.pendingBatchId;
+    } else {
+      if (this.buffer.length === 0) return null;
+      batch = this.buffer.splice(0);
+      batchId = mintId("batch");
+      this.pendingBatch = batch;
+      this.pendingBatchId = batchId;
+      this.inFlight += batch.length;
+      this.cfg.onBufferChange?.(this.buffer.length);
+    }
+    this.cancelTimerIfSet();
+    this.nextRetryAt = null;
+    try {
+      const env = this.cfg.envelope();
+      const body = {
+        events: batch,
+        sdk: env.sdk
+      };
+      if (env.appId) body.appId = env.appId;
+      const result = await this.cfg.http.request("POST", "/events", {
+        body,
+        idempotencyKey: batchId
       });
+      this.lastFlushAt = Date.now();
+      this.lastError = null;
+      this.inFlight -= batch.length;
+      this.pendingBatch = null;
+      this.pendingBatchId = null;
+      this.retry.recordSuccess();
+      if (!this.firstFlushFired) {
+        this.firstFlushFired = true;
+        this.cfg.onFirstFlushSuccess?.();
+      }
+      return result;
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      this.lastError = message;
+      const retryAfterMs = extractRetryAfterMs(err);
+      const delay = this.retry.nextDelay(retryAfterMs);
+      this.scheduleRetry(delay);
+      this.cfg.onRetryScheduled?.({
+        delayMs: delay,
+        consecutiveFailures: this.retry.consecutiveFailures,
+        retryAfterMs,
+        lastError: message
+      });
+      return null;
     }
-    return this.http.request(
-      "GET",
-      `/server/customers/${encodeURIComponent(customerId)}/entitlements`
-    );
   }
-  async track(event, options = {}) {
-    return this.ingest([event], options);
+  /** Cancel any pending timer and clear in-memory state. */
+  reset() {
+    this.cancelTimerIfSet();
+    this.nextRetryAt = null;
+    this.buffer = [];
+    this.pendingBatch = null;
+    this.pendingBatchId = null;
+    this.dropped = 0;
+    this.inFlight = 0;
+    this.lastError = null;
+    this.retry.recordSuccess();
+    this.cfg.onBufferChange?.(0);
   }
-  async ingest(events, options = {}) {
-    if (!Array.isArray(events) || events.length === 0) {
-      throw new CrossdeckError({
-        type: "invalid_request_error",
-        code: "missing_events",
-        message: "ingest requires at least one event."
-      });
-    }
-    const normalized = events.map((event) => this.normalizeEvent(event));
-    const body = {
-      events: normalized,
-      sdk: { name: SDK_NAME, version: this.sdkVersion }
+  getStats() {
+    return {
+      // `buffered` counts events waiting for their FIRST flush. The
+      // in-flight pendingBatch (retrying) is tracked separately via
+      // `inFlight` — surfacing both lets diagnostics show "we have
+      // events stuck retrying" distinct from "new events arriving".
+      buffered: this.buffer.length,
+      dropped: this.dropped,
+      inFlight: this.inFlight,
+      lastFlushAt: this.lastFlushAt,
+      lastError: this.lastError,
+      consecutiveFailures: this.retry.consecutiveFailures,
+      nextRetryAt: this.nextRetryAt
     };
-    if (this.appId) body.appId = this.appId;
-    return this.http.request("POST", "/events", {
-      body,
-      idempotencyKey: options.idempotencyKey ?? this.mintBatchId()
-    });
   }
-  async syncPurchases(input) {
-    if (!input.signedTransactionInfo) {
-      throw new CrossdeckError({
-        type: "invalid_request_error",
-        code: "missing_signed_transaction_info",
-        message: "syncPurchases requires a signedTransactionInfo string."
-      });
-    }
-    return this.http.request("POST", "/purchases/sync", {
-      body: { rail: input.rail ?? "apple", ...input }
-    });
+  /**
+   * The Idempotency-Key of the in-flight pending batch (if any).
+   * Exposed for testing the Stripe-style reuse contract. Production
+   * callers don't need this.
+   */
+  get pendingIdempotencyKey() {
+    return this.pendingBatchId;
   }
-  async grantEntitlement(input) {
-    if (!input.customerId) {
-      throw new CrossdeckError({
-        type: "invalid_request_error",
-        code: "missing_customer_id",
-        message: "grantEntitlement requires a customerId."
-      });
+  // ---------- internal scheduling ----------
+  scheduleIdleFlush() {
+    this.cancelTimerIfSet();
+    const sched = this.cfg.scheduler ?? defaultScheduler;
+    this.cancelTimer = sched(() => {
+      void this.flush();
+    }, this.cfg.intervalMs);
+  }
+  scheduleRetry(delayMs) {
+    this.cancelTimerIfSet();
+    this.nextRetryAt = Date.now() + delayMs;
+    const sched = this.cfg.scheduler ?? defaultScheduler;
+    this.cancelTimer = sched(() => {
+      void this.flush();
+    }, delayMs);
+  }
+  cancelTimerIfSet() {
+    if (this.cancelTimer) {
+      this.cancelTimer();
+      this.cancelTimer = null;
     }
-    return this.http.request(
-      "POST",
-      `/server/customers/${encodeURIComponent(input.customerId)}/grant`,
-      {
-        body: {
-          entitlementKey: input.entitlementKey,
-          duration: input.duration,
-          reason: input.reason
-        }
-      }
-    );
   }
-  async revokeEntitlement(input) {
-    if (!input.customerId) {
-      throw new CrossdeckError({
-        type: "invalid_request_error",
-        code: "missing_customer_id",
-        message: "revokeEntitlement requires a customerId."
-      });
+};
+function extractRetryAfterMs(err) {
+  if (err && typeof err === "object" && "retryAfterMs" in err) {
+    const v = err.retryAfterMs;
+    return typeof v === "number" && Number.isFinite(v) && v >= 0 ? v : void 0;
+  }
+  return void 0;
+}
+function defaultScheduler(fn, ms) {
+  const id = setTimeout(fn, ms);
+  if (typeof id.unref === "function") {
+    try {
+      id.unref();
+    } catch {
     }
-    return this.http.request(
-      "POST",
-      `/server/customers/${encodeURIComponent(input.customerId)}/revoke`,
-      {
-        body: {
-          entitlementKey: input.entitlementKey,
-          reason: input.reason
-        }
-      }
-    );
   }
-  async getAuditEntry(eventId) {
-    if (!eventId) {
-      throw new CrossdeckError({
-        type: "invalid_request_error",
-        code: "missing_event_id",
-        message: "getAuditEntry requires an eventId."
-      });
+  return () => clearTimeout(id);
+}
+
+// src/breadcrumbs.ts
+var BreadcrumbBuffer = class {
+  constructor(maxSize = 50) {
+    this.maxSize = maxSize;
+  }
+  maxSize;
+  items = [];
+  add(crumb) {
+    this.items.push(crumb);
+    if (this.items.length > this.maxSize) {
+      this.items.shift();
+    }
+  }
+  /** Defensive copy — caller can read freely without mutating buffer state. */
+  snapshot() {
+    return this.items.slice();
+  }
+  clear() {
+    this.items = [];
+  }
+  get size() {
+    return this.items.length;
+  }
+};
+
+// src/stack-parser.ts
+function parseStack(stack) {
+  if (!stack || typeof stack !== "string") return [];
+  const lines = stack.split("\n");
+  const frames = [];
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    const frame = parseLine(trimmed);
+    if (frame) frames.push(frame);
+  }
+  return frames;
+}
+function parseLine(line) {
+  let m = /^at\s+(.+?)\s+\((.+?):(\d+):(\d+)\)$/.exec(line);
+  if (m) {
+    return buildFrame({
+      function: m[1],
+      filename: m[2],
+      lineno: parseInt(m[3], 10),
+      colno: parseInt(m[4], 10),
+      raw: line
+    });
+  }
+  m = /^at\s+(.+?):(\d+):(\d+)$/.exec(line);
+  if (m) {
+    return buildFrame({
+      function: "?",
+      filename: m[1],
+      lineno: parseInt(m[2], 10),
+      colno: parseInt(m[3], 10),
+      raw: line
+    });
+  }
+  m = /^(.*?)@(.+?):(\d+):(\d+)$/.exec(line);
+  if (m) {
+    return buildFrame({
+      function: m[1] || "?",
+      filename: m[2],
+      lineno: parseInt(m[3], 10),
+      colno: parseInt(m[4], 10),
+      raw: line
+    });
+  }
+  if (/^\w*Error/.test(line) || !line.includes(":")) {
+    return null;
+  }
+  return {
+    function: "?",
+    filename: "",
+    lineno: 0,
+    colno: 0,
+    in_app: true,
+    raw: line
+  };
+}
+function buildFrame(input) {
+  return {
+    function: input.function || "?",
+    filename: input.filename,
+    lineno: Number.isFinite(input.lineno) ? input.lineno : 0,
+    colno: Number.isFinite(input.colno) ? input.colno : 0,
+    in_app: isInAppFrame(input.filename),
+    raw: input.raw
+  };
+}
+function isInAppFrame(filename) {
+  if (!filename) return true;
+  if (/@cross-deck[\\/]node/.test(filename)) return false;
+  if (/[\\/]node_modules[\\/]/.test(filename)) return false;
+  if (/^node:/.test(filename)) return false;
+  if (/^internal[\\/]/.test(filename)) return false;
+  return true;
+}
+function fingerprintError(message, frames) {
+  const inAppFrames = frames.filter((f) => f.in_app).slice(0, 3);
+  const key = [
+    (message || "").slice(0, 200),
+    ...inAppFrames.map((f) => `${f.function}@${f.filename}:${f.lineno}`)
+  ].join("|");
+  return djb2Hex(key);
+}
+function djb2Hex(input) {
+  let h = 5381;
+  for (let i = 0; i < input.length; i++) {
+    h = (h << 5) + h + input.charCodeAt(i) | 0;
+  }
+  return (h >>> 0).toString(16).padStart(8, "0");
+}
+
+// src/error-capture.ts
+var DEFAULT_ERROR_CAPTURE = {
+  enabled: true,
+  onUncaughtException: true,
+  onUnhandledRejection: true,
+  wrapFetch: true,
+  captureConsole: false,
+  ignoreErrors: [],
+  allowPaths: [],
+  denyPaths: [
+    // SDK self-skip — caught by stack-parser's `isInAppFrame` too,
+    // but defensive here in case a future change to the heuristic
+    // misses one of these paths.
+    /[\\/]node_modules[\\/]@cross-deck[\\/]node[\\/]/
+  ],
+  sampleRate: 1,
+  maxPerFingerprintPerMinute: 5,
+  maxPerSession: 100
+};
+var MAX_FINGERPRINTS_TRACKED = 4096;
+var FINGERPRINT_WINDOW_MS = 6e4;
+var ErrorTracker = class {
+  constructor(opts) {
+    this.opts = opts;
+  }
+  opts;
+  installed = false;
+  cleanups = [];
+  _reporting = false;
+  sessionCount = 0;
+  fingerprintWindow = /* @__PURE__ */ new Map();
+  install() {
+    if (this.installed) return;
+    if (!this.opts.config.enabled) return;
+    if (this.opts.config.onUncaughtException) this.installUncaughtExceptionHandler();
+    if (this.opts.config.onUnhandledRejection) this.installUnhandledRejectionHandler();
+    if (this.opts.config.wrapFetch) this.installFetchWrap();
+    if (this.opts.config.captureConsole) this.installConsoleWrap();
+    this.installed = true;
+  }
+  uninstall() {
+    for (const fn of this.cleanups.splice(0)) {
+      try {
+        fn();
+      } catch {
+      }
+    }
+    this.installed = false;
+  }
+  /**
+   * Manual API. Either an Error instance or any unknown value (we
+   * coerce). Returns silently — never throws, even if the SDK isn't
+   * initialised.
+   */
+  captureError(error, options) {
+    if (!this.opts.isConsented()) return;
+    try {
+      const captured = this.buildFromUnknown(error, "error.handled", options?.level ?? "error");
+      if (options?.context) captured.context = { ...captured.context, ...options.context };
+      if (options?.tags) captured.tags = { ...captured.tags, ...options.tags };
+      this.maybeReport(captured);
+    } catch {
+    }
+  }
+  /**
+   * Capture a non-error event as an issue. For "we hit a soft-warning
+   * code path" / "deprecated API used" kinds of signals. Pairs with
+   * Sentry's captureMessage().
+   */
+  captureMessage(message, level = "info") {
+    if (!this.opts.isConsented()) return;
+    try {
+      const captured = {
+        timestamp: Date.now(),
+        kind: "error.message",
+        level,
+        message,
+        errorType: null,
+        frames: [],
+        rawStack: null,
+        fingerprint: fingerprintError(message, []),
+        breadcrumbs: this.opts.breadcrumbs.snapshot(),
+        context: this.opts.getContext(),
+        tags: this.opts.getTags()
+      };
+      this.maybeReport(captured);
+    } catch {
+    }
+  }
+  /** Inspection hook — total reports captured this process lifetime. */
+  get reportedCount() {
+    return this.sessionCount;
+  }
+  /** Inspection hook — number of distinct fingerprints inside the rate-limit window. */
+  get fingerprintsTracked() {
+    return this.fingerprintWindow.size;
+  }
+  /** Inspection hook — whether global handlers are installed. */
+  get handlersInstalled() {
+    return this.installed;
+  }
+  // ============================================================
+  // Listener installation — Node hooks
+  // ============================================================
+  installUncaughtExceptionHandler() {
+    const handler = (err) => {
+      if (this._reporting) return;
+      if (!this.opts.isConsented()) return;
+      try {
+        this._reporting = true;
+        const captured = this.buildFromUnknown(err, "error.unhandled", "error");
+        this.maybeReport(captured);
+      } catch {
+      } finally {
+        this._reporting = false;
+      }
+    };
+    process.on("uncaughtException", handler);
+    this.cleanups.push(() => process.off("uncaughtException", handler));
+  }
+  installUnhandledRejectionHandler() {
+    const handler = (reason) => {
+      if (this._reporting) return;
+      if (!this.opts.isConsented()) return;
+      try {
+        this._reporting = true;
+        const captured = this.buildFromUnknown(reason, "error.unhandledrejection", "error");
+        this.maybeReport(captured);
+      } catch {
+      } finally {
+        this._reporting = false;
+      }
+    };
+    process.on("unhandledRejection", handler);
+    this.cleanups.push(() => process.off("unhandledRejection", handler));
+  }
+  /**
+   * Wrap `globalThis.fetch` so failed HTTP requests get auto-captured.
+   * We do NOT call 4xx an "error" (those are often expected — auth
+   * required, validation failed). Only 5xx + network failures fire.
+   *
+   * Node 18+ exposes `fetch` natively on `globalThis`. We tolerate
+   * its absence (some sandboxed runtimes / patched globals) by
+   * skipping the wrap rather than throwing.
+   */
+  installFetchWrap() {
+    const origFetch = globalThis.fetch;
+    if (typeof origFetch !== "function") return;
+    const tracker = this;
+    const wrapped = async (...args) => {
+      const input = args[0];
+      const init = args[1] ?? {};
+      const url = typeof input === "string" ? input : input?.url ?? "";
+      const method = (init.method || "GET").toUpperCase();
+      const start = Date.now();
+      tracker.opts.breadcrumbs.add({
+        timestamp: start,
+        category: "http",
+        message: `${method} ${url}`,
+        data: { url, method }
+      });
+      try {
+        const response = await origFetch(...args);
+        if (response.status >= 500 && tracker.opts.isConsented()) {
+          if (!url.includes("api.cross-deck.com")) {
+            tracker.captureHttp({
+              url,
+              method,
+              status: response.status,
+              statusText: response.statusText
+            });
+          }
+        }
+        return response;
+      } catch (err) {
+        if (tracker.opts.isConsented() && !url.includes("api.cross-deck.com")) {
+          tracker.captureHttp({
+            url,
+            method,
+            status: 0,
+            statusText: err instanceof Error ? err.message : "network error"
+          });
+        }
+        throw err;
+      }
+    };
+    globalThis.fetch = wrapped;
+    this.cleanups.push(() => {
+      if (globalThis.fetch === wrapped) globalThis.fetch = origFetch;
+    });
+  }
+  installConsoleWrap() {
+    const orig = console.error.bind(console);
+    const tracker = this;
+    console.error = (...args) => {
+      try {
+        if (tracker.opts.isConsented()) {
+          tracker.captureMessage(args.map((a) => safeStringify3(a)).join(" "), "error");
+        }
+      } catch {
+      }
+      return orig(...args);
+    };
+    this.cleanups.push(() => {
+      console.error = orig;
+    });
+  }
+  // ============================================================
+  // Builders
+  // ============================================================
+  /**
+   * Build a `CapturedError` from any value. Handles:
+   *   - Error instances (the common case) — parses `err.stack` into
+   *     frames, fingerprints over message + top in-app frames.
+   *   - Non-Error rejections (promise rejected with a string / number
+   *     / plain object) — coerces via `safeStringify`, no frames.
+   *
+   * Verbatim port of web's `buildFromUnknown` — the logic is
+   * runtime-agnostic.
+   */
+  buildFromUnknown(err, kind, level) {
+    if (err instanceof Error) {
+      const frames = parseStack(err.stack);
+      return {
+        timestamp: Date.now(),
+        kind,
+        level,
+        message: String(err.message).slice(0, 1024),
+        errorType: err.name,
+        frames,
+        rawStack: err.stack ?? null,
+        fingerprint: fingerprintError(err.message, frames),
+        breadcrumbs: this.opts.breadcrumbs.snapshot(),
+        context: this.opts.getContext(),
+        tags: this.opts.getTags()
+      };
+    }
+    const message = safeStringify3(err).slice(0, 1024);
+    return {
+      timestamp: Date.now(),
+      kind,
+      level,
+      message,
+      errorType: null,
+      frames: [],
+      rawStack: null,
+      fingerprint: fingerprintError(message, []),
+      breadcrumbs: this.opts.breadcrumbs.snapshot(),
+      context: this.opts.getContext(),
+      tags: this.opts.getTags()
+    };
+  }
+  captureHttp(info) {
+    try {
+      const message = `HTTP ${info.status} ${info.method} ${info.url}`;
+      const captured = {
+        timestamp: Date.now(),
+        kind: "error.http",
+        level: "error",
+        message,
+        errorType: "HTTPError",
+        frames: [],
+        rawStack: null,
+        fingerprint: fingerprintError(`HTTP ${info.status} ${info.method}`, []),
+        breadcrumbs: this.opts.breadcrumbs.snapshot(),
+        context: this.opts.getContext(),
+        tags: this.opts.getTags(),
+        http: info
+      };
+      this.maybeReport(captured);
+    } catch {
+    }
+  }
+  // ============================================================
+  // Reporting pipeline — filter / sample / rate-limit / send
+  // ============================================================
+  maybeReport(err) {
+    if (this.sessionCount >= this.opts.config.maxPerSession) return;
+    if (this.shouldIgnore(err)) return;
+    if (!this.passesPathGate(err)) return;
+    if (!this.passesSample(err)) return;
+    if (!this.passesRateLimit(err)) return;
+    let finalErr = err;
+    if (this.opts.beforeSend) {
+      try {
+        finalErr = this.opts.beforeSend(err);
+      } catch {
+        finalErr = err;
+      }
+      if (!finalErr) return;
+    }
+    this.sessionCount += 1;
+    try {
+      this.opts.report(finalErr);
+    } catch {
+    }
+  }
+  shouldIgnore(err) {
+    for (const pat of this.opts.config.ignoreErrors) {
+      if (typeof pat === "string" && err.message.includes(pat)) return true;
+      if (pat instanceof RegExp && pat.test(err.message)) return true;
+    }
+    return false;
+  }
+  passesPathGate(err) {
+    const topFrame = err.frames.find((f) => f.filename) ?? null;
+    const path = topFrame?.filename ?? "";
+    if (!path) return true;
+    for (const pat of this.opts.config.denyPaths) {
+      if (typeof pat === "string" && path.includes(pat)) return false;
+      if (pat instanceof RegExp && pat.test(path)) return false;
+    }
+    if (this.opts.config.allowPaths.length > 0) {
+      for (const pat of this.opts.config.allowPaths) {
+        if (typeof pat === "string" && path.includes(pat)) return true;
+        if (pat instanceof RegExp && pat.test(path)) return true;
+      }
+      return false;
+    }
+    return true;
+  }
+  passesSample(err) {
+    if (this.opts.config.sampleRate >= 1) return true;
+    if (this.opts.config.sampleRate <= 0) return false;
+    const hashByte = parseInt(err.fingerprint.slice(0, 2), 16);
+    return hashByte / 255 < this.opts.config.sampleRate;
+  }
+  passesRateLimit(err) {
+    const now = Date.now();
+    const max = this.opts.config.maxPerFingerprintPerMinute;
+    const arr = this.fingerprintWindow.get(err.fingerprint) ?? [];
+    const fresh = arr.filter((t) => now - t < FINGERPRINT_WINDOW_MS);
+    if (fresh.length >= max) {
+      this.fingerprintWindow.set(err.fingerprint, fresh);
+      return false;
+    }
+    fresh.push(now);
+    this.fingerprintWindow.set(err.fingerprint, fresh);
+    this.maybePruneFingerprintWindow(now);
+    return true;
+  }
+  /**
+   * Bound the fingerprint Map's memory footprint. Runs opportunistically
+   * — only when the Map exceeds `MAX_FINGERPRINTS_TRACKED`. First pass:
+   * delete entries whose ENTIRE window is stale (no live timestamps
+   * inside the 60s window). Second pass (if still over): FIFO-evict
+   * the oldest entries by Map insertion order until we're under the
+   * cap. Defends against a long-running process with high-cardinality
+   * fingerprints leaking memory forever.
+   */
+  maybePruneFingerprintWindow(now) {
+    if (this.fingerprintWindow.size <= MAX_FINGERPRINTS_TRACKED) return;
+    for (const [fp, timestamps] of this.fingerprintWindow) {
+      const hasLive = timestamps.some((t) => now - t < FINGERPRINT_WINDOW_MS);
+      if (!hasLive) this.fingerprintWindow.delete(fp);
+    }
+    if (this.fingerprintWindow.size <= MAX_FINGERPRINTS_TRACKED) return;
+    const overflow = this.fingerprintWindow.size - MAX_FINGERPRINTS_TRACKED;
+    let dropped = 0;
+    for (const fp of this.fingerprintWindow.keys()) {
+      if (dropped >= overflow) break;
+      this.fingerprintWindow.delete(fp);
+      dropped += 1;
+    }
+  }
+};
+function safeStringify3(v) {
+  if (v == null) return String(v);
+  if (typeof v === "string") return v;
+  if (typeof v === "number" || typeof v === "boolean") return String(v);
+  try {
+    return JSON.stringify(v);
+  } catch {
+    return Object.prototype.toString.call(v);
+  }
+}
+
+// src/runtime-info.ts
+import { hostname as osHostname, platform as osPlatform, release as osRelease } from "os";
+var cached = null;
+function collectRuntimeInfo(options = {}) {
+  if (cached) return cached;
+  cached = detect(options);
+  return cached;
+}
+function detect(options) {
+  const env = typeof process !== "undefined" && process.env ? process.env : {};
+  const detected = detectHost(env);
+  return Object.freeze({
+    nodeVersion: typeof process !== "undefined" && process.versions ? process.versions.node : "unknown",
+    platform: safePlatform(),
+    platformRelease: safeRelease(),
+    hostname: safeHostname(),
+    host: detected.host,
+    region: detected.region,
+    serviceName: options.serviceName ?? detected.serviceName,
+    serviceVersion: options.serviceVersion ?? detected.serviceVersion,
+    instanceId: detected.instanceId,
+    appVersion: options.appVersion ?? null
+  });
+}
+function detectHost(env) {
+  const pid = safePid();
+  if (env.AWS_LAMBDA_FUNCTION_NAME) {
+    return {
+      host: "aws-lambda",
+      region: env.AWS_REGION ?? null,
+      serviceName: env.AWS_LAMBDA_FUNCTION_NAME,
+      serviceVersion: env.AWS_LAMBDA_FUNCTION_VERSION ?? null,
+      instanceId: env.AWS_LAMBDA_LOG_STREAM_NAME ?? pid
+    };
+  }
+  if (env.FUNCTIONS_WORKER_RUNTIME && env.WEBSITE_INSTANCE_ID) {
+    return {
+      host: "azure-functions",
+      region: env.REGION_NAME ?? env.WEBSITE_LOCATION ?? null,
+      serviceName: env.WEBSITE_SITE_NAME ?? null,
+      serviceVersion: env.WEBSITE_BUILD_ID ?? null,
+      instanceId: env.WEBSITE_INSTANCE_ID
+    };
+  }
+  if (env.GAE_APPLICATION) {
+    return {
+      host: "google-app-engine",
+      region: env.GAE_REGION ?? env.GOOGLE_CLOUD_REGION ?? null,
+      serviceName: env.GAE_SERVICE ?? null,
+      serviceVersion: env.GAE_VERSION ?? null,
+      instanceId: env.GAE_INSTANCE ?? pid
+    };
+  }
+  if (env.K_SERVICE && env.K_REVISION) {
+    const isFirebase = Boolean(env.FIREBASE_CONFIG || env.GCLOUD_PROJECT);
+    return {
+      host: isFirebase ? "firebase-functions-v2" : "cloud-run",
+      region: env.FUNCTION_REGION ?? env.GOOGLE_CLOUD_REGION ?? null,
+      serviceName: env.K_SERVICE,
+      serviceVersion: env.K_REVISION,
+      instanceId: `${env.K_REVISION}:${pid}`
+    };
+  }
+  if (env.FUNCTION_NAME && env.FUNCTION_REGION) {
+    return {
+      host: "firebase-functions-v1",
+      region: env.FUNCTION_REGION,
+      serviceName: env.FUNCTION_NAME,
+      serviceVersion: env.X_GOOGLE_FUNCTION_VERSION ?? null,
+      instanceId: pid
+    };
+  }
+  if (env.VERCEL === "1") {
+    return {
+      host: "vercel",
+      region: env.VERCEL_REGION ?? null,
+      serviceName: env.VERCEL_URL ?? null,
+      serviceVersion: env.VERCEL_GIT_COMMIT_SHA?.slice(0, 7) ?? null,
+      instanceId: pid
+    };
+  }
+  if (env.NETLIFY === "true" || env.NETLIFY_BUILD_BASE) {
+    return {
+      host: "netlify",
+      region: env.AWS_REGION ?? null,
+      serviceName: env.SITE_NAME ?? env.SITE_ID ?? null,
+      serviceVersion: env.COMMIT_REF?.slice(0, 7) ?? null,
+      instanceId: pid
+    };
+  }
+  if (env.DYNO) {
+    return {
+      host: "heroku",
+      region: null,
+      serviceName: env.HEROKU_APP_NAME ?? null,
+      serviceVersion: env.HEROKU_RELEASE_VERSION ?? env.HEROKU_SLUG_COMMIT?.slice(0, 7) ?? null,
+      instanceId: env.DYNO
+    };
+  }
+  if (env.RENDER === "true" || env.RENDER_INSTANCE_ID) {
+    return {
+      host: "render",
+      region: env.RENDER_SERVICE_REGION ?? null,
+      serviceName: env.RENDER_SERVICE_NAME ?? null,
+      serviceVersion: env.RENDER_GIT_COMMIT?.slice(0, 7) ?? null,
+      instanceId: env.RENDER_INSTANCE_ID ?? pid
+    };
+  }
+  if (env.RAILWAY_ENVIRONMENT) {
+    return {
+      host: "railway",
+      region: env.RAILWAY_REGION ?? null,
+      serviceName: env.RAILWAY_SERVICE_NAME ?? null,
+      serviceVersion: env.RAILWAY_GIT_COMMIT_SHA?.slice(0, 7) ?? null,
+      instanceId: env.RAILWAY_REPLICA_ID ?? pid
+    };
+  }
+  if (env.FLY_APP_NAME) {
+    return {
+      host: "fly",
+      region: env.FLY_REGION ?? null,
+      serviceName: env.FLY_APP_NAME,
+      serviceVersion: env.FLY_IMAGE_REF?.slice(-7) ?? null,
+      instanceId: env.FLY_ALLOC_ID ?? pid
+    };
+  }
+  if (env.KUBERNETES_SERVICE_HOST) {
+    return {
+      host: "kubernetes",
+      region: null,
+      serviceName: env.POD_NAME ?? env.HOSTNAME ?? null,
+      serviceVersion: null,
+      instanceId: env.POD_NAME ?? env.HOSTNAME ?? pid
+    };
+  }
+  return {
+    host: "node",
+    region: null,
+    serviceName: null,
+    serviceVersion: null,
+    instanceId: pid
+  };
+}
+function safeHostname() {
+  try {
+    return osHostname();
+  } catch {
+    return "unknown";
+  }
+}
+function safePlatform() {
+  try {
+    return osPlatform();
+  } catch {
+    return "unknown";
+  }
+}
+function safeRelease() {
+  try {
+    return osRelease();
+  } catch {
+    return "unknown";
+  }
+}
+function safePid() {
+  try {
+    return typeof process !== "undefined" && process.pid ? String(process.pid) : "0";
+  } catch {
+    return "0";
+  }
+}
+function runtimeInfoToProperties(info) {
+  const out = {
+    "runtime.nodeVersion": info.nodeVersion,
+    "runtime.platform": info.platform,
+    "runtime.platformRelease": info.platformRelease,
+    "runtime.hostname": info.hostname,
+    "runtime.host": info.host
+  };
+  if (info.region) out["runtime.region"] = info.region;
+  if (info.serviceName) out["runtime.serviceName"] = info.serviceName;
+  if (info.serviceVersion) out["runtime.serviceVersion"] = info.serviceVersion;
+  if (info.instanceId) out["runtime.instanceId"] = info.instanceId;
+  if (info.appVersion) out.appVersion = info.appVersion;
+  return out;
+}
+
+// src/flush-on-exit.ts
+var SIGNALS = ["SIGTERM", "SIGINT"];
+var DEFAULT_TIMEOUT_MS2 = 2e3;
+var FlushOnExit = class {
+  constructor(options) {
+    this.options = options;
+  }
+  options;
+  installed = false;
+  draining = false;
+  drained = false;
+  beforeExitHandler = null;
+  signalHandlers = {};
+  /**
+   * Install handlers for `beforeExit` + `SIGTERM` + `SIGINT`. Idempotent —
+   * calling twice does NOT register duplicate handlers.
+   */
+  install() {
+    if (this.installed) return;
+    this.installed = true;
+    this.beforeExitHandler = () => {
+      void this.runDrain("beforeExit");
+    };
+    process.on("beforeExit", this.beforeExitHandler);
+    for (const sig of SIGNALS) {
+      const handler = () => {
+        void this.runDrainAndExit(sig);
+      };
+      this.signalHandlers[sig] = handler;
+      process.on(sig, handler);
+    }
+  }
+  /**
+   * Remove all handlers. Tests + custom-lifecycle callers only.
+   */
+  uninstall() {
+    if (!this.installed) return;
+    this.installed = false;
+    if (this.beforeExitHandler) {
+      process.off("beforeExit", this.beforeExitHandler);
+      this.beforeExitHandler = null;
+    }
+    for (const sig of SIGNALS) {
+      const handler = this.signalHandlers[sig];
+      if (handler) {
+        process.off(sig, handler);
+        delete this.signalHandlers[sig];
+      }
+    }
+  }
+  /**
+   * Force-drain immediately (without waiting for an exit signal).
+   * Used by `wrapLambdaHandler` / `wrapFunction` — Lambda freezes the
+   * process between invocations, so we drain at the END of each
+   * invocation rather than waiting for SIGTERM.
+   */
+  async drainNow() {
+    return this.runDrain("manual");
+  }
+  /** True if the drain has already completed (one-shot lifecycle). */
+  get hasDrained() {
+    return this.drained;
+  }
+  /** True if a drain is in flight. */
+  get isDraining() {
+    return this.draining;
+  }
+  // ---------- internals ----------
+  async runDrain(_reason) {
+    if (this.drained || this.draining) return;
+    this.draining = true;
+    this.options.onStart?.();
+    const start = Date.now();
+    const timeoutMs = this.options.timeoutMs ?? DEFAULT_TIMEOUT_MS2;
+    let timedOut = false;
+    let drainError = null;
+    await new Promise((resolve) => {
+      let settled = false;
+      const timer = setTimeout(() => {
+        if (settled) return;
+        settled = true;
+        timedOut = true;
+        resolve();
+      }, timeoutMs);
+      if (typeof timer.unref === "function") {
+        try {
+          timer.unref();
+        } catch {
+        }
+      }
+      let drainPromise;
+      try {
+        drainPromise = this.options.drain();
+      } catch (syncErr) {
+        if (settled) return;
+        settled = true;
+        drainError = syncErr;
+        clearTimeout(timer);
+        resolve();
+        return;
+      }
+      drainPromise.then(
+        () => {
+          if (settled) return;
+          settled = true;
+          clearTimeout(timer);
+          resolve();
+        },
+        (err) => {
+          if (settled) return;
+          settled = true;
+          drainError = err;
+          clearTimeout(timer);
+          resolve();
+        }
+      );
+    });
+    if (drainError !== null) {
+      try {
+        this.options.onError?.(drainError);
+      } catch {
+      }
+    }
+    this.draining = false;
+    this.drained = true;
+    this.options.onComplete?.({
+      durationMs: Date.now() - start,
+      timedOut
+    });
+  }
+  /**
+   * Drain in response to a termination signal. After the drain
+   * completes, we re-raise the signal so the process exits with the
+   * correct exit code — `kill -TERM <pid>` should still terminate
+   * the process even though we installed a handler that "consumed" it.
+   *
+   * Detail: Node attaches a default SIGTERM handler that exits the
+   * process. The MOMENT we register our own handler with `process.on`,
+   * the default is removed. So we have to re-raise to mimic the
+   * default behaviour after our drain completes.
+   */
+  async runDrainAndExit(sig) {
+    await this.runDrain(sig);
+    const handler = this.signalHandlers[sig];
+    if (handler) {
+      process.off(sig, handler);
+      delete this.signalHandlers[sig];
+    }
+    try {
+      process.kill(process.pid, sig);
+    } catch {
+      const code = sig === "SIGTERM" ? 143 : 130;
+      process.exit(code);
+    }
+  }
+};
+
+// src/super-properties.ts
+var SuperPropertyStore = class {
+  superProps = {};
+  groups = {};
+  /**
+   * Merge new keys into the super-property bag. Returns a snapshot
+   * of the resulting bag. Values that are `null` are deleted
+   * (Mixpanel's explicit "stop tracking this key" idiom).
+   */
+  register(props) {
+    for (const [k, v] of Object.entries(props)) {
+      if (v === null) {
+        delete this.superProps[k];
+      } else if (v !== void 0) {
+        this.superProps[k] = v;
+      }
+    }
+    return { ...this.superProps };
+  }
+  /** Remove a single super-property key. Idempotent. */
+  unregister(key) {
+    if (key in this.superProps) {
+      delete this.superProps[key];
+    }
+  }
+  /** Defensive snapshot of the current super-property bag. */
+  getSuperProperties() {
+    return { ...this.superProps };
+  }
+  /**
+   * Set a group membership. Passing `id: null` clears the membership
+   * for that type — the SDK stops attaching it to events.
+   */
+  setGroup(type, id, traits) {
+    if (id === null) {
+      delete this.groups[type];
+    } else {
+      this.groups[type] = traits !== void 0 ? { id, traits } : { id };
+    }
+  }
+  /**
+   * Defensive snapshot of the current groups map, keyed by group type.
+   * The `traits` sub-object is the most-recent traits payload passed
+   * to `setGroup` for that type.
+   */
+  getGroups() {
+    const out = {};
+    for (const [type, membership] of Object.entries(this.groups)) {
+      out[type] = {
+        id: membership.id,
+        ...membership.traits ? { traits: { ...membership.traits } } : {}
+      };
+    }
+    return out;
+  }
+  /**
+   * Flat `{ type: id }` projection used for event-attachment. Stable
+   * for fast every-event merge — we don't JSON-clone on each
+   * `track()` call (hot path).
+   */
+  getGroupIds() {
+    const out = {};
+    for (const [type, info] of Object.entries(this.groups)) {
+      out[type] = info.id;
+    }
+    return out;
+  }
+  /** Wipe both bags. Called by `server.shutdown()`. */
+  clear() {
+    this.superProps = {};
+    this.groups = {};
+  }
+};
+
+// src/entitlement-cache.ts
+var DEFAULT_MAX_CUSTOMERS = 1e4;
+var EntitlementCache = class {
+  ttlMs;
+  maxCustomers;
+  byCustomer = /* @__PURE__ */ new Map();
+  listeners = /* @__PURE__ */ new Set();
+  listenerErrorCount = 0;
+  evicted = 0;
+  constructor(options = {}) {
+    this.ttlMs = options.ttlMs ?? 6e4;
+    this.maxCustomers = options.maxCustomers ?? DEFAULT_MAX_CUSTOMERS;
+  }
+  /**
+   * Synchronous lookup. Returns `true` iff the customer has the
+   * entitlement AND the cache entry is fresh (within `ttlMs`).
+   * Returns `false` otherwise (no entry / expired / key not active).
+   */
+  isEntitled(customerId, key) {
+    const entry = this.byCustomer.get(customerId);
+    if (!entry) return false;
+    if (Date.now() > entry.expiresAt) return false;
+    return entry.active.has(key);
+  }
+  /**
+   * Full snapshot for callers that need source / validUntil. Returns
+   * `[]` when the customer has no cached entry or the entry has
+   * expired.
+   */
+  list(customerId) {
+    const entry = this.byCustomer.get(customerId);
+    if (!entry) return [];
+    if (Date.now() > entry.expiresAt) return [];
+    return entry.all.slice();
+  }
+  /**
+   * Whether a fresh entry exists for the customer. Useful for
+   * deciding whether to warm before a hot path.
+   */
+  isFresh(customerId) {
+    const entry = this.byCustomer.get(customerId);
+    return Boolean(entry && Date.now() <= entry.expiresAt);
+  }
+  /**
+   * Replace (or insert) the cache entry for a customer. Sets the
+   * `expiresAt` to `now + ttlMs`. Re-inserting an existing customerId
+   * "touches" it — the entry moves to the end of insertion order
+   * (Map semantics) so it's treated as most-recently-used for LRU
+   * eviction. Fires listeners.
+   */
+  setForCustomer(customerId, entitlements) {
+    const now = Date.now();
+    this.byCustomer.delete(customerId);
+    this.byCustomer.set(customerId, {
+      all: entitlements.slice(),
+      active: new Set(entitlements.filter((e) => e.isActive).map((e) => e.key)),
+      expiresAt: now + this.ttlMs,
+      populatedAt: now
+    });
+    while (this.byCustomer.size > this.maxCustomers) {
+      const oldestKey = this.byCustomer.keys().next().value;
+      if (oldestKey === void 0) break;
+      this.byCustomer.delete(oldestKey);
+      this.evicted += 1;
+    }
+    this.notify(customerId, entitlements);
+  }
+  /**
+   * Drop a single customer's entry. Fires listeners with an empty
+   * list so subscribers know that customer's cache is gone.
+   */
+  clearCustomer(customerId) {
+    if (!this.byCustomer.delete(customerId)) return;
+    this.notify(customerId, []);
+  }
+  /** Wipe the whole cache. Fires listeners for each customer that had a cached entry. */
+  clear() {
+    const customers = [...this.byCustomer.keys()];
+    this.byCustomer.clear();
+    for (const id of customers) this.notify(id, []);
+  }
+  /**
+   * Subscribe to cache mutations. Returns an unsubscribe function.
+   * Listener is invoked AFTER each `setForCustomer` / `clearCustomer`
+   * / `clear` call with the affected customer ID + fresh entitlements
+   * snapshot. NOT fired on TTL expiry (passive eviction is not a
+   * mutation by design).
+   *
+   * Listener errors are swallowed — a buggy consumer must not crash
+   * the SDK or other listeners. The error count is surfaced via
+   * `listenerErrors`.
+   *
+   * Returned unsubscribe is idempotent.
+   */
+  subscribe(listener) {
+    this.listeners.add(listener);
+    let unsubscribed = false;
+    return () => {
+      if (unsubscribed) return;
+      unsubscribed = true;
+      this.listeners.delete(listener);
+    };
+  }
+  // ---------- diagnostics ----------
+  /** Total customers currently cached (counts expired entries too — eviction is lazy). */
+  get customerCount() {
+    return this.byCustomer.size;
+  }
+  /** Most-recent populatedAt across all entries, or 0 if cache empty. */
+  get lastUpdated() {
+    let max = 0;
+    for (const entry of this.byCustomer.values()) {
+      if (entry.populatedAt > max) max = entry.populatedAt;
+    }
+    return max;
+  }
+  /** Configured TTL in ms. */
+  get ttl() {
+    return this.ttlMs;
+  }
+  /** Cumulative count of listener invocations that threw. Surfaced in `diagnostics()`. */
+  get listenerErrors() {
+    return this.listenerErrorCount;
+  }
+  /** Cumulative count of entries evicted by the max-customers cap. */
+  get evictedCount() {
+    return this.evicted;
+  }
+  /** Configured max-customers cap. */
+  get maxSize() {
+    return this.maxCustomers;
+  }
+  // ---------- internals ----------
+  notify(customerId, snapshot) {
+    if (this.listeners.size === 0) return;
+    const snap = snapshot.slice();
+    const listenersSnapshot = [...this.listeners];
+    for (const listener of listenersSnapshot) {
+      try {
+        listener(customerId, snap);
+      } catch {
+        this.listenerErrorCount += 1;
+      }
+    }
+  }
+};
+
+// src/debug.ts
+var SENSITIVE_KEY_PATTERNS = [
+  /^email$/i,
+  /^password$/i,
+  /^token$/i,
+  /^secret$/i,
+  /^card$/i,
+  /^phone$/i,
+  /password/i,
+  /credit_?card/i
+];
+function findSensitivePropertyKeys(properties) {
+  if (!properties) return [];
+  const hits = [];
+  for (const k of Object.keys(properties)) {
+    if (SENSITIVE_KEY_PATTERNS.some((re) => re.test(k))) hits.push(k);
+  }
+  return hits;
+}
+var ONCE_SIGNALS = /* @__PURE__ */ new Set([
+  "sdk.configured",
+  "sdk.first_event_sent",
+  "sdk.environment_mismatch",
+  "sdk.runtime_detected"
+]);
+var ConsoleDebugLogger = class {
+  enabled = false;
+  seen = /* @__PURE__ */ new Set();
+  emit(signal, message, context) {
+    if (!this.enabled) return;
+    if (ONCE_SIGNALS.has(signal)) {
+      if (this.seen.has(signal)) return;
+      this.seen.add(signal);
+    }
+    const ctx = context ? ` ${safeJson(context)}` : "";
+    console.info(`[crossdeck:${signal}] ${message}${ctx}`);
+  }
+};
+var NullDebugLogger = class {
+  enabled = false;
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  emit(_signal, _message, _context) {
+  }
+};
+function safeJson(obj) {
+  try {
+    return JSON.stringify(obj);
+  } catch {
+    return "[unserialisable context]";
+  }
+}
+
+// src/crossdeck-server.ts
+var CrossdeckServer = class extends EventEmitter {
+  http;
+  sdkVersion;
+  baseUrl;
+  appId;
+  env;
+  secretKeyPrefix;
+  /**
+   * Process-stable pseudo-anonymous ID. Used as the default identity
+   * for `track()` / `captureError()` calls where the caller doesn't
+   * supply one (e.g. an `uncaughtException` handler has no per-request
+   * context). Stable for the SDK instance's lifetime so events from
+   * the same process correlate.
+   */
+  processAnonymousId;
+  runtime;
+  runtimeProperties;
+  breadcrumbs;
+  eventQueue;
+  errorTracker;
+  flushOnExit;
+  superProps;
+  entitlementCache;
+  debug;
+  /**
+   * Alias map — `developerUserId` / `anonymousId` → canonical
+   * `crossdeckCustomerId`. Populated by `getEntitlements()` so a
+   * subsequent `isEntitled({ userId }, "pro")` resolves to the same
+   * cache entry the prior `getEntitlements({ userId })` populated.
+   *
+   * Bounded by `MAX_CUSTOMER_ID_ALIASES` (matches the entitlement
+   * cache's default max-customers for symmetry — if the underlying
+   * cache entry was evicted, a stale alias is dead weight anyway).
+   * Long-running multi-tenant servers handling a long tail of customers
+   * are the failure mode this bound defends against.
+   */
+  customerIdAliases = /* @__PURE__ */ new Map();
+  /** Mutable error-state — modified by setTag / setContext / setErrorBeforeSend. */
+  errorContext = {};
+  errorTags = {};
+  errorBeforeSend = null;
+  constructor(options) {
+    super();
+    if (!options.secretKey || !options.secretKey.startsWith("cd_sk_")) {
+      throw new CrossdeckError({
+        type: "configuration_error",
+        code: "invalid_secret_key",
+        message: "CrossdeckServer requires a secret key starting with cd_sk_."
+      });
+    }
+    this.sdkVersion = options.sdkVersion ?? SDK_VERSION;
+    this.appId = options.appId;
+    this.baseUrl = options.baseUrl ?? DEFAULT_BASE_URL;
+    this.env = inferEnvFromKey(options.secretKey);
+    this.secretKeyPrefix = maskSecretKey(options.secretKey);
+    this.http = new HttpClient({
+      secretKey: options.secretKey,
+      baseUrl: this.baseUrl,
+      sdkVersion: this.sdkVersion,
+      timeoutMs: options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+      testMode: options.testMode,
+      onRequest: options.onRequest,
+      onResponse: options.onResponse,
+      httpRetries: options.httpRetries,
+      runtimeToken: options.runtimeToken
+    });
+    this.processAnonymousId = mintId("anon_node");
+    this.runtime = collectRuntimeInfo({
+      serviceName: options.serviceName,
+      serviceVersion: options.serviceVersion,
+      appVersion: options.appVersion
+    });
+    this.runtimeProperties = runtimeInfoToProperties(this.runtime);
+    this.breadcrumbs = new BreadcrumbBuffer(options.breadcrumbsMaxSize ?? 50);
+    this.superProps = new SuperPropertyStore();
+    this.entitlementCache = new EntitlementCache({
+      ttlMs: options.entitlementCacheTtlMs ?? 6e4
+    });
+    this.debug = options.debug === true ? new ConsoleDebugLogger() : new NullDebugLogger();
+    if (options.debug === true) this.debug.enabled = true;
+    this.debug.emit(
+      "sdk.configured",
+      `Crossdeck server SDK connected. env=${this.env}, host=${this.runtime?.host ?? "node"}`,
+      {
+        env: this.env,
+        sdkVersion: this.sdkVersion,
+        secretKeyPrefix: this.secretKeyPrefix
+      }
+    );
+    this.eventQueue = new EventQueue({
+      http: this.http,
+      batchSize: options.eventFlushBatchSize ?? 20,
+      intervalMs: options.eventFlushIntervalMs ?? 1500,
+      envelope: () => ({
+        appId: this.appId,
+        sdk: { name: SDK_NAME, version: this.sdkVersion }
+      }),
+      onDrop: (count) => {
+        this.emit("queue.dropped", { count });
+      },
+      onBufferChange: (size) => {
+        this.emit("queue.buffer_changed", { size });
+      },
+      onRetryScheduled: (info) => {
+        this.emit("queue.flush_failed", {
+          error: info.lastError,
+          attempt: info.consecutiveFailures,
+          nextRetryMs: info.delayMs
+        });
+      },
+      onFirstFlushSuccess: () => {
+        this.debug.emit("sdk.first_event_sent", "First batch landed.");
+      }
+    });
+    if (options.errorCapture === false) {
+      this.errorTracker = null;
+    } else {
+      const config = options.errorCapture && typeof options.errorCapture === "object" ? { ...DEFAULT_ERROR_CAPTURE, ...options.errorCapture } : { ...DEFAULT_ERROR_CAPTURE };
+      this.errorTracker = new ErrorTracker({
+        config,
+        breadcrumbs: this.breadcrumbs,
+        report: (err) => this.reportCapturedError(err),
+        getContext: () => ({ ...this.errorContext }),
+        getTags: () => ({ ...this.errorTags }),
+        beforeSend: null,
+        // wired via setErrorBeforeSend; ErrorTracker reads it through the live ref below
+        isConsented: () => true
+      });
+      const trackerOpts = this.errorTracker.opts;
+      Object.defineProperty(trackerOpts, "beforeSend", {
+        get: () => this.errorBeforeSend,
+        configurable: true
+      });
+      this.errorTracker.install();
+    }
+    if (options.flushOnExit === false) {
+      this.flushOnExit = null;
+    } else {
+      this.flushOnExit = new FlushOnExit({
+        drain: () => this.eventQueue.flush().then(() => void 0),
+        timeoutMs: options.flushOnExitTimeoutMs
+      });
+      this.flushOnExit.install();
+    }
+    if (options.testMode !== true && options.bootHeartbeat !== false) {
+      setImmediate(() => {
+        void this.heartbeat().catch((err) => {
+          this.debug.emit(
+            "sdk.boot_heartbeat_failed",
+            "Boot heartbeat failed (non-fatal \u2014 events will still flush).",
+            { message: err instanceof Error ? err.message : String(err) }
+          );
+        });
+      });
+    }
+  }
+  // ============================================================
+  // Identity — direct HTTP (transactional, not telemetry)
+  // ============================================================
+  async identify(userId, anonymousId, options) {
+    const { signal, timeoutMs, ...identifyOpts } = options ?? {};
+    return this.aliasIdentity(
+      { userId, anonymousId, ...identifyOpts },
+      { signal, timeoutMs }
+    );
+  }
+  async aliasIdentity(input, options) {
+    if (!input.userId) {
+      throw new CrossdeckError({
+        type: "invalid_request_error",
+        code: "missing_user_id",
+        message: "aliasIdentity requires a non-empty userId."
+      });
+    }
+    if (!input.anonymousId) {
+      throw new CrossdeckError({
+        type: "invalid_request_error",
+        code: "missing_anonymous_id",
+        message: "aliasIdentity requires a non-empty anonymousId."
+      });
+    }
+    const traits = sanitizePropertyBag(input.traits, "traits");
+    const body = {
+      userId: input.userId,
+      anonymousId: input.anonymousId
+    };
+    if (input.email) body.email = input.email;
+    if (traits && Object.keys(traits).length > 0) body.traits = traits;
+    return this.http.request("POST", "/identity/alias", {
+      body,
+      signal: options?.signal,
+      timeoutMs: options?.timeoutMs
+    });
+  }
+  async forget(hints, options) {
+    const body = this.identityPayload(hints);
+    return this.http.request("POST", "/identity/forget", {
+      body,
+      signal: options?.signal,
+      timeoutMs: options?.timeoutMs
+    });
+  }
+  // ============================================================
+  // Entitlements — direct HTTP + TTL cache (v1.0.0+)
+  //
+  // `getEntitlements()` POSTs over the wire and populates the cache
+  // under the response's canonical `crossdeckCustomerId`. Any
+  // `userId` / `anonymousId` supplied as a hint is recorded as an
+  // alias so a subsequent `isEntitled({ userId }, "pro")` resolves
+  // to the same cache entry.
+  // ============================================================
+  async getEntitlements(hints, options) {
+    const response = await this.http.request("GET", "/entitlements", {
+      query: this.identityPayload(hints),
+      signal: options?.signal,
+      timeoutMs: options?.timeoutMs
+    });
+    this.populateEntitlementCache(hints, response);
+    return response;
+  }
+  async getCustomerEntitlements(customerId, options) {
+    if (!customerId) {
+      throw new CrossdeckError({
+        type: "invalid_request_error",
+        code: "missing_customer_id",
+        message: "getCustomerEntitlements requires a customerId."
+      });
+    }
+    const response = await this.http.request(
+      "GET",
+      `/server/customers/${encodeURIComponent(customerId)}/entitlements`,
+      {
+        signal: options?.signal,
+        timeoutMs: options?.timeoutMs
+      }
+    );
+    this.populateEntitlementCache({ customerId }, response);
+    return response;
+  }
+  /**
+   * Synchronous entitlement check. Returns `true` iff the customer
+   * has the entitlement AND the cache entry is fresh (within
+   * `entitlementCacheTtlMs`, default 60s). Returns `false` when the
+   * cache is cold or expired.
+   *
+   * The hint can be any combination of `customerId` / `userId` /
+   * `anonymousId`. After `getEntitlements({ userId })` populates the
+   * cache, subsequent `isEntitled({ userId }, "pro")` calls within
+   * TTL are memory reads (no HTTP). The "warm cache" pattern that
+   * makes hot-path entitlement gates cheap.
+   *
+   *   await server.getEntitlements({ userId });    // warm
+   *   if (server.isEntitled({ userId }, "pro")) {  // synchronous
+   *     // ...
+   *   }
+   *
+   * Caller is responsible for re-warming after TTL elapses. The cache
+   * does NOT auto-refresh on read (would block the hot path).
+   */
+  isEntitled(hint, key) {
+    const customerId = this.resolveCacheCustomerId(hint);
+    if (!customerId) return false;
+    const result = this.entitlementCache.isEntitled(customerId, key);
+    if (result) {
+      this.debug.emit("sdk.entitlement_cache_used", `Cache hit for ${customerId}/${key}.`);
+    }
+    return result;
+  }
+  /**
+   * Snapshot of the customer's cached entitlements. Returns `[]` when
+   * the cache is cold or expired. Same hint resolution as
+   * `isEntitled()`.
+   */
+  listEntitlements(hint) {
+    const customerId = this.resolveCacheCustomerId(hint);
+    if (!customerId) return [];
+    return this.entitlementCache.list(customerId);
+  }
+  /**
+   * Subscribe to entitlement-cache mutations. Listener fires after
+   * `getEntitlements()` populates the cache or `shutdown()` clears
+   * it. Returns an idempotent unsubscribe function.
+   *
+   * Used by callers that want to react to entitlement changes (e.g.
+   * a websocket layer notifying connected clients of plan upgrades).
+   * Listener errors are swallowed — surfaced via
+   * `diagnostics().entitlements.listenerErrors`.
+   */
+  onEntitlementsChange(listener) {
+    return this.entitlementCache.subscribe(listener);
+  }
+  // ============================================================
+  // Events — queue-based track(); immediate ingest() for bulk imports
+  // ============================================================
+  /**
+   * Queue an event for batched delivery. Returns synchronously — the
+   * HTTP round-trip happens in the background.
+   *
+   * Behaviour parity with `@cross-deck/web`'s `track()`:
+   *   - Synchronous return, void.
+   *   - Throws sync on `missing_event_name`.
+   *   - Property bag sanitised through `validateEventProperties`.
+   *   - Runtime info (`runtime.*`) auto-merged into every event's
+   *     properties. Caller-supplied properties win on key collision.
+   *   - Breadcrumb auto-emitted (unless the name starts with `error.`,
+   *     which would cause a cycle).
+   *
+   * Differences from `@cross-deck/web`:
+   *   - Single-argument signature `track(event)` instead of
+   *     `track(name, properties)` — the Node wire shape needs the full
+   *     `ServerEvent` (identity hint, optional level + tags + categoryTags).
+   *   - Auto-fills `anonymousId` with `this.processAnonymousId` when no
+   *     identity hint is supplied. A captureError from
+   *     `uncaughtException` has no per-request context; without the
+   *     auto-fill, the event would be rejected at queue enqueue.
+   */
+  track(event) {
+    if (!event.name) {
+      throw new CrossdeckError({
+        type: "invalid_request_error",
+        code: "missing_event_name",
+        message: "track(event) requires a non-empty event.name."
+      });
+    }
+    const sanitized = sanitizePropertyBag(event.properties, "event properties") ?? {};
+    if (this.debug.enabled) {
+      const flagged = findSensitivePropertyKeys(sanitized);
+      if (flagged.length > 0) {
+        this.debug.emit(
+          "sdk.sensitive_property_warning",
+          `Event "${event.name}" has potentially sensitive property names: ${flagged.join(", ")}. Crossdeck is privacy-first \u2014 avoid sending PII unless intentional.`,
+          { eventName: event.name, flagged }
+        );
+      }
+    }
+    const properties = {
+      ...this.runtimeProperties,
+      ...this.superProps.getSuperProperties(),
+      ...sanitized
+    };
+    const groupIds = this.superProps.getGroupIds();
+    if (Object.keys(groupIds).length > 0 && properties.$groups === void 0) {
+      properties.$groups = groupIds;
+    }
+    const identity = this.resolveIdentity(event);
+    const queued = {
+      eventId: event.eventId ?? mintId("evt", 8),
+      name: event.name,
+      timestamp: event.timestamp ?? Date.now(),
+      properties,
+      ...identity
+    };
+    if (event.level !== void 0) queued.level = event.level;
+    if (event.tags !== void 0) queued.tags = event.tags;
+    if (event.categoryTags !== void 0) queued.categoryTags = event.categoryTags;
+    this.eventQueue.enqueue(queued);
+    if (!event.name.startsWith("error.")) {
+      this.breadcrumbs.add({
+        timestamp: queued.timestamp,
+        category: categoryFor(event.name),
+        message: event.name,
+        data: sanitized
+      });
+    }
+  }
+  /**
+   * Immediate POST of one or more events. For bulk imports / replay
+   * scenarios where the caller wants synchronous confirmation. Bypasses
+   * the queue — no batching, no auto-fill of identity, no
+   * runtime-enrichment.
+   *
+   * Use `track()` for the standard fire-and-forget telemetry path.
+   * Use `ingest()` when you need:
+   *   - The IngestResponse synchronously.
+   *   - Strict per-event identity validation (no auto-fill).
+   *   - Caller-controlled idempotency key.
+   */
+  async ingest(events, options = {}) {
+    if (!Array.isArray(events) || events.length === 0) {
+      throw new CrossdeckError({
+        type: "invalid_request_error",
+        code: "missing_events",
+        message: "ingest requires at least one event."
+      });
+    }
+    const normalized = events.map((event) => this.normalizeIngestEvent(event));
+    const body = {
+      events: normalized,
+      sdk: { name: SDK_NAME, version: this.sdkVersion }
+    };
+    if (this.appId) body.appId = this.appId;
+    return this.http.request("POST", "/events", {
+      body,
+      idempotencyKey: options.idempotencyKey ?? mintId("batch"),
+      signal: options.signal,
+      timeoutMs: options.timeoutMs
+    });
+  }
+  /**
+   * Validate the secret key against the Crossdeck API and return the
+   * resolved project + app metadata. Useful at boot to fail fast on a
+   * misconfigured deployment — without this, a wrong secret key only
+   * surfaces on the first event flush attempt, which may be minutes
+   * after process start.
+   *
+   *   const { projectId, appId, env, serverTime } = await server.heartbeat();
+   *
+   * Throws `CrossdeckError` on:
+   *   - `authentication_error` — secret key invalid / revoked
+   *   - `network_error` — couldn't reach the backend
+   *   - `request_timeout` — backend slow / unreachable
+   *
+   * Side effect: success records `(serverTime, clientTime)` for clock-
+   * skew detection in `diagnostics().clock` (Phase 2 — not yet exposed
+   * in this SDK release but the data is captured).
+   *
+   * Not auto-called. Caller decides whether the trade-off (one extra
+   * boot request + ~50ms p50 latency) is worth the early-failure
+   * signal. For serverless cold-starts, it usually is — cheap
+   * compared to the cost of a silent broken secret in production.
+   */
+  async heartbeat(options) {
+    const result = await this.http.request("GET", "/sdk/heartbeat", {
+      signal: options?.signal,
+      timeoutMs: options?.timeoutMs
+    });
+    return result;
+  }
+  /**
+   * Drain the event queue. Resolves when the in-flight batch completes
+   * (success or failure). On failure, events stay queued for the next
+   * scheduled retry — the resolved promise does NOT throw.
+   *
+   * Typical callers:
+   *   - End of a Lambda handler: `await server.flush()` before return
+   *     so events land before the platform freezes the process.
+   *   - Express server shutdown: `await server.flush()` inside the
+   *     SIGTERM handler.
+   *   - Tests: drain between assertions.
+   *
+   * Idempotent — flush on an empty queue is a no-op.
+   */
+  async flush() {
+    await this.eventQueue.flush();
+  }
+  async syncPurchases(input, options) {
+    if (!input.signedTransactionInfo) {
+      throw new CrossdeckError({
+        type: "invalid_request_error",
+        code: "missing_signed_transaction_info",
+        message: "syncPurchases requires a signedTransactionInfo string."
+      });
+    }
+    return this.http.request("POST", "/purchases/sync", {
+      body: { rail: input.rail ?? "apple", ...input },
+      signal: options?.signal,
+      timeoutMs: options?.timeoutMs
+    });
+  }
+  // ============================================================
+  // Manual entitlement controls + audit — direct HTTP
+  // ============================================================
+  async grantEntitlement(input, options) {
+    if (!input.customerId) {
+      throw new CrossdeckError({
+        type: "invalid_request_error",
+        code: "missing_customer_id",
+        message: "grantEntitlement requires a customerId."
+      });
+    }
+    return this.http.request(
+      "POST",
+      `/server/customers/${encodeURIComponent(input.customerId)}/grant`,
+      {
+        body: {
+          entitlementKey: input.entitlementKey,
+          duration: input.duration,
+          reason: input.reason
+        },
+        signal: options?.signal,
+        timeoutMs: options?.timeoutMs
+      }
+    );
+  }
+  /**
+   * Grant multiple entitlements in one logical call. Backend lacks a
+   * bulk endpoint today, so this is a client-side fan-out — each
+   * grant fires a separate request. Results return as a
+   * settled-promise array so partial failures don't drop the rest:
+   * the caller decides how to handle each `{ ok, value }` /
+   * `{ ok: false, error }` entry.
+   *
+   * Use for ops sweeps (e.g. "grant the entire `pro` tier a one-time
+   * `pro_q1_bonus` entitlement"). The bounded concurrency (default
+   * `maxConcurrency: 5`) avoids hammering the backend; the rate-
+   * limit policy on the server still kicks in if needed.
+   */
+  async bulkGrantEntitlement(grants, options) {
+    return runBulkOperation(
+      grants,
+      options?.maxConcurrency ?? 5,
+      (input) => this.grantEntitlement(input, { signal: options?.signal, timeoutMs: options?.timeoutMs })
+    );
+  }
+  async revokeEntitlement(input, options) {
+    if (!input.customerId) {
+      throw new CrossdeckError({
+        type: "invalid_request_error",
+        code: "missing_customer_id",
+        message: "revokeEntitlement requires a customerId."
+      });
+    }
+    return this.http.request(
+      "POST",
+      `/server/customers/${encodeURIComponent(input.customerId)}/revoke`,
+      {
+        body: {
+          entitlementKey: input.entitlementKey,
+          reason: input.reason
+        },
+        signal: options?.signal,
+        timeoutMs: options?.timeoutMs
+      }
+    );
+  }
+  /**
+   * Revoke multiple entitlements in one logical call. Same
+   * settled-array contract as `bulkGrantEntitlement` — see that
+   * doc for behaviour notes.
+   */
+  async bulkRevokeEntitlement(revokes, options) {
+    return runBulkOperation(
+      revokes,
+      options?.maxConcurrency ?? 5,
+      (input) => this.revokeEntitlement(input, { signal: options?.signal, timeoutMs: options?.timeoutMs })
+    );
+  }
+  async getAuditEntry(eventId, options) {
+    if (!eventId) {
+      throw new CrossdeckError({
+        type: "invalid_request_error",
+        code: "missing_event_id",
+        message: "getAuditEntry requires an eventId."
+      });
     }
     const result = await this.http.request(
       "GET",
-      `/server/audit/${encodeURIComponent(eventId)}`
+      `/server/audit/${encodeURIComponent(eventId)}`,
+      {
+        signal: options?.signal,
+        timeoutMs: options?.timeoutMs
+      }
     );
     return result.data;
   }
+  // ============================================================
+  // USP 1 — Error capture public surface
+  // ============================================================
+  /**
+   * Manually capture an error from a try/catch block.
+   *
+   *   try { … } catch (err) {
+   *     server.captureError(err, { context: { jobId }, tags: { flow: "checkout" } });
+   *   }
+   *
+   * The error ships through the same event queue analytics rides on
+   * (retried, idempotent, runtime-enriched). Returns silently — never
+   * throws, even if error capture is disabled.
+   */
+  captureError(error, options) {
+    if (!this.errorTracker) return;
+    this.errorTracker.captureError(error, options);
+  }
+  /**
+   * Capture a non-error signal as an issue. Sentry's `captureMessage`
+   * pattern — for "we hit the deprecated code path" / "soft-warning
+   * triggered" signals where there's no Error to throw.
+   */
+  captureMessage(message, level = "info") {
+    if (!this.errorTracker) return;
+    this.errorTracker.captureMessage(message, level);
+  }
+  /**
+   * Attach a tag to every subsequent error report. Sentry pattern.
+   * Tags are flat string key/value (queryable in the dashboard);
+   * use `setContext()` for structured blobs.
+   */
+  setTag(key, value) {
+    this.errorTags[key] = value;
+  }
+  /** Bulk-set tags. Merges with existing tags. */
+  setTags(tags) {
+    Object.assign(this.errorTags, tags);
+  }
+  /**
+   * Attach a structured context blob to every subsequent error report.
+   * Unlike tags (flat key/value), context is a named bag of arbitrary
+   * JSON-serialisable data.
+   *
+   *   server.setContext("cart", { items: 3, total: 42.99 });
+   */
+  setContext(name, data) {
+    this.errorContext[name] = data;
+  }
+  /**
+   * Add a custom breadcrumb to the rolling buffer. The last 50
+   * breadcrumbs are attached to every subsequent error report —
+   * "what was the request doing right before things broke."
+   */
+  addBreadcrumb(crumb) {
+    this.breadcrumbs.add(crumb);
+  }
+  /**
+   * Install a pre-send hook for errors. Return null to drop the report,
+   * or a modified `CapturedError` to scrub fields. Sentry's
+   * `beforeSend` pattern — the only place to add app-specific PII
+   * redaction (auth tokens in URLs, etc.) before the report leaves the
+   * process.
+   *
+   * The hook is called LAST, after rate-limit + sampling + path gates
+   * already passed. A throwing hook falls back to the original error.
+   */
+  setErrorBeforeSend(hook) {
+    this.errorBeforeSend = hook;
+  }
+  // ============================================================
+  // USP 2 — Super-properties + groups (Mixpanel pattern)
+  // ============================================================
+  /**
+   * Register super-properties — every subsequent event carries these
+   * keys on its `properties` bag automatically. Mixpanel pattern.
+   *
+   *   server.register({ tenant: "acme", plan: "pro" });
+   *   server.track({ name: "paywall_shown", developerUserId: userId });
+   *   //          ^ event carries `tenant` + `plan` in properties
+   *
+   * Values that are `null` are deleted (the explicit "stop tracking
+   * this key" idiom). Sanitised through `validateEventProperties` so
+   * a `{ avatar: <Buffer> }` payload can't poison the queue.
+   *
+   * Returns a defensive snapshot of the resulting bag.
+   *
+   * **Multi-tenant servers — read carefully.** Super-properties are
+   * PROCESS-SCOPED. In a single Node process handling requests for
+   * many tenants (the common multi-tenant SaaS shape), calling
+   * `server.register({ tenant: "acme" })` taints EVERY subsequent
+   * event from that process — including ones serving tenant "beta".
+   * That's almost never what you want.
+   *
+   * The right pattern for per-request properties is to pass them on
+   * the `track()` call itself:
+   *
+   *   server.track({
+   *     name: "paywall_shown",
+   *     developerUserId: req.user.id,
+   *     properties: { tenant: req.tenantId, plan: req.user.plan },
+   *   });
+   *
+   * Reserve `register()` for properties that genuinely apply to every
+   * event from this process — e.g. service version, region, build
+   * commit. For those, `runtime-info` already provides
+   * `runtime.serviceVersion` etc. automatically.
+   */
+  register(properties) {
+    const validation = validateEventProperties(properties);
+    const result = this.superProps.register(validation.properties);
+    this.debug.emit(
+      "sdk.super_property_registered",
+      `Super-properties updated. ${Object.keys(validation.properties).length} key(s) merged.`
+    );
+    return result;
+  }
+  /** Remove a single super-property key. Idempotent. */
+  unregister(key) {
+    this.superProps.unregister(key);
+  }
+  /** Snapshot of the current super-property bag. */
+  getSuperProperties() {
+    return this.superProps.getSuperProperties();
+  }
+  /**
+   * Associate the current SDK instance with a group (org, team,
+   * account, plan). Mixpanel / Segment Group Analytics pattern.
+   *
+   *   server.group("org", "acme_inc");
+   *   server.group("team", "design", { headcount: 12 });
+   *
+   * Once set, every subsequent event carries `$groups.<type>: id` on
+   * its `properties` bag, enabling B2B dashboard pivots. Pass
+   * `id: null` to clear a group membership.
+   *
+   * Group traits are sanitised through `validateEventProperties`.
+   */
+  group(type, id, traits) {
+    if (!type) {
+      throw new CrossdeckError({
+        type: "invalid_request_error",
+        code: "missing_group_type",
+        message: "group(type, id) requires a non-empty type."
+      });
+    }
+    const sanitisedTraits = traits ? validateEventProperties(traits).properties : void 0;
+    this.superProps.setGroup(type, id, sanitisedTraits);
+  }
+  /** Snapshot of current group memberships keyed by type. */
+  getGroups() {
+    return this.superProps.getGroups();
+  }
+  // ============================================================
+  // Diagnostics — for debugging + the dashboard's heartbeat row
+  // ============================================================
+  diagnostics() {
+    return {
+      sdkVersion: this.sdkVersion,
+      baseUrl: this.baseUrl,
+      secretKeyPrefix: this.secretKeyPrefix,
+      env: this.env,
+      runtime: {
+        nodeVersion: this.runtime.nodeVersion,
+        platform: this.runtime.platform,
+        hostname: this.runtime.hostname,
+        host: this.runtime.host,
+        region: this.runtime.region,
+        serviceName: this.runtime.serviceName,
+        serviceVersion: this.runtime.serviceVersion,
+        instanceId: this.runtime.instanceId
+      },
+      entitlements: {
+        count: this.entitlementCache.customerCount,
+        lastUpdated: this.entitlementCache.lastUpdated,
+        ttlMs: this.entitlementCache.ttl,
+        listenerErrors: this.entitlementCache.listenerErrors
+      },
+      events: this.eventQueue.getStats(),
+      errors: {
+        sessionCount: this.errorTracker?.reportedCount ?? 0,
+        fingerprintsTracked: this.errorTracker?.fingerprintsTracked ?? 0,
+        handlersInstalled: this.errorTracker?.handlersInstalled ?? false
+      }
+    };
+  }
+  /**
+   * Tear down handlers and clear in-memory state. Tests + custom
+   * lifecycle callers only. Production code should rely on
+   * `flush-on-exit` instead.
+   */
+  shutdown(reason = "shutdown") {
+    this.emit("sdk.shutdown", { reason });
+    this.errorTracker?.uninstall();
+    this.flushOnExit?.uninstall();
+    this.eventQueue.reset();
+    this.breadcrumbs.clear();
+    this.superProps.clear();
+    this.entitlementCache.clear();
+    this.customerIdAliases.clear();
+    this.errorContext = {};
+    this.errorTags = {};
+    this.errorBeforeSend = null;
+    this.removeAllListeners();
+  }
+  on(event, listener) {
+    return super.on(event, listener);
+  }
+  once(event, listener) {
+    return super.once(event, listener);
+  }
+  off(event, listener) {
+    return super.off(event, listener);
+  }
+  emit(event, ...args) {
+    return super.emit(event, ...args);
+  }
+  // ============================================================
+  // Health + readiness + lifecycle
+  // ============================================================
+  /**
+   * Synchronous readiness check — "is the SDK in a state where it
+   * should accept new traffic?". Used by Kubernetes readiness probes
+   * and backpressure-aware callers.
+   *
+   * Returns `false` if:
+   *   - The event queue is in a sustained retry storm
+   *     (`consecutiveFailures >= 5`).
+   *   - The event queue's buffered count is at >= 80% of HARD_BUFFER_CAP.
+   *
+   * Otherwise `true`. The default isn't "perfectly healthy" — the
+   * SDK is happy to enqueue events even during transient flush
+   * failures because the queue's retry path handles them. Only
+   * sustained failure flips this to `false`.
+   */
+  isReady() {
+    const stats = this.eventQueue.getStats();
+    if (stats.consecutiveFailures >= 5) return false;
+    if (stats.buffered >= 800) return false;
+    return true;
+  }
+  /**
+   * Async wait until `isReady()` returns true OR the timeout elapses.
+   * Resolves `true` on ready, `false` on timeout. Polls every 50ms by
+   * default — backpressure for callers writing high-volume servers.
+   *
+   *   if (!(await server.awaitReady(2000))) {
+   *     // shed load — SDK is in a retry storm, don't queue more
+   *   }
+   */
+  async awaitReady(timeoutMs = 5e3, pollIntervalMs = 50) {
+    if (this.isReady()) return true;
+    const start = Date.now();
+    return new Promise((resolve) => {
+      const tick = () => {
+        if (this.isReady()) {
+          resolve(true);
+          return;
+        }
+        if (Date.now() - start >= timeoutMs) {
+          resolve(false);
+          return;
+        }
+        const t = setTimeout(tick, pollIntervalMs);
+        if (typeof t.unref === "function") {
+          try {
+            t.unref();
+          } catch {
+          }
+        }
+      };
+      tick();
+    });
+  }
+  /**
+   * Snapshot for Kubernetes liveness + readiness probes. `healthy`
+   * stays true unless the SDK is in a catastrophic state (which
+   * currently can't happen without crashing the process). `ready`
+   * matches `isReady()`.
+   *
+   *   app.get("/healthz", (_req, res) => {
+   *     const h = server.getHealth();
+   *     res.status(h.healthy ? 200 : 503).json(h);
+   *   });
+   */
+  getHealth() {
+    const stats = this.eventQueue.getStats();
+    return {
+      ready: this.isReady(),
+      healthy: true,
+      bufferedEvents: stats.buffered,
+      inFlight: stats.inFlight,
+      consecutiveFailures: stats.consecutiveFailures,
+      lastFlushAt: stats.lastFlushAt,
+      lastError: stats.lastError,
+      errorHandlersInstalled: this.errorTracker?.handlersInstalled ?? false
+    };
+  }
+  /**
+   * Sync disposal hook — runs when a `using` declaration exits scope
+   * (TC39 explicit-resource-management, Node 20+ / TS 5.2+).
+   *
+   *   using server = new CrossdeckServer({ ... });
+   *   // ... use server ...
+   *   // at end of block, server[Symbol.dispose]() runs automatically
+   *
+   * `Symbol.dispose` is synchronous so we can't await `flush()` here
+   * — for that, use `await using` + `[Symbol.asyncDispose]()`. This
+   * sync variant just calls `shutdown()` (handler cleanup +
+   * in-memory state wipe).
+   */
+  [Symbol.dispose]() {
+    this.shutdown("dispose");
+  }
+  /**
+   * Async disposal hook — runs when an `await using` declaration
+   * exits scope. Awaits `flush()` THEN runs `shutdown()`. Use this
+   * variant when the caller needs the queue drained before exit
+   * (the common case for serverless handlers).
+   *
+   *   await using server = new CrossdeckServer({ ... });
+   */
+  async [Symbol.asyncDispose]() {
+    try {
+      await this.flush();
+    } catch {
+    }
+    this.shutdown("asyncDispose");
+  }
+  // ============================================================
+  reportCapturedError(captured) {
+    try {
+      this.emit("error.captured", {
+        fingerprint: captured.fingerprint,
+        kind: captured.kind,
+        message: captured.message
+      });
+    } catch {
+    }
+    const properties = {
+      fingerprint: captured.fingerprint,
+      level: captured.level,
+      errorType: captured.errorType,
+      message: captured.message,
+      stack: captured.rawStack ?? void 0,
+      frames: captured.frames,
+      tags: captured.tags,
+      context: captured.context,
+      breadcrumbs: captured.breadcrumbs,
+      http: captured.http
+    };
+    for (const k of Object.keys(properties)) {
+      if (properties[k] === void 0) delete properties[k];
+    }
+    this.track({
+      name: captured.kind,
+      timestamp: captured.timestamp,
+      properties,
+      level: captured.level,
+      tags: captured.tags
+    });
+  }
+  /**
+   * Populate the entitlement cache from a fresh server response.
+   * Records aliases so `userId` / `anonymousId` hints supplied to
+   * `getEntitlements()` resolve to the same cache entry on subsequent
+   * `isEntitled({ userId }, ...)` calls.
+   *
+   * Bounds the alias map at MAX_CUSTOMER_ID_ALIASES — once full, the
+   * oldest aliases (by insertion order) are evicted FIFO. Symmetric
+   * with the entitlement cache's max-customers cap.
+   */
+  populateEntitlementCache(hints, response) {
+    const customerId = response.crossdeckCustomerId;
+    if (!customerId) return;
+    this.entitlementCache.setForCustomer(customerId, response.data);
+    if (hints.userId) this.touchAlias(hints.userId, customerId);
+    if (hints.anonymousId) this.touchAlias(hints.anonymousId, customerId);
+    this.debug.emit(
+      "sdk.entitlement_cache_warm",
+      `Entitlement cache warmed for ${customerId} (${response.data.length} entitlement(s)).`
+    );
+    try {
+      this.emit("entitlements.warmed", {
+        customerId,
+        count: response.data.length
+      });
+    } catch {
+    }
+  }
+  touchAlias(alias, customerId) {
+    this.customerIdAliases.delete(alias);
+    this.customerIdAliases.set(alias, customerId);
+    while (this.customerIdAliases.size > MAX_CUSTOMER_ID_ALIASES) {
+      const oldest = this.customerIdAliases.keys().next().value;
+      if (oldest === void 0) break;
+      this.customerIdAliases.delete(oldest);
+    }
+  }
+  /**
+   * Resolve any hint shape (canonical customerId / userId hint /
+   * anonymousId hint / raw string) to a `crossdeckCustomerId` if we
+   * have a cache entry for it.
+   */
+  resolveCacheCustomerId(hint) {
+    if (typeof hint === "string") {
+      if (this.entitlementCache.isFresh(hint)) return hint;
+      return this.customerIdAliases.get(hint) ?? null;
+    }
+    if (hint.customerId) return hint.customerId;
+    if (hint.userId) return this.customerIdAliases.get(hint.userId) ?? null;
+    if (hint.anonymousId) return this.customerIdAliases.get(hint.anonymousId) ?? null;
+    return null;
+  }
   identityPayload(hints) {
     const payload = {};
     if (typeof hints.customerId === "string" && hints.customerId) {
@@ -507,7 +3037,27 @@ var CrossdeckServer = class {
     }
     return payload;
   }
-  normalizeEvent(event) {
+  /**
+   * Resolve event identity. Caller-supplied wins; falls back to
+   * `processAnonymousId` so events from `captureError` /
+   * uncaughtException always have at least one identity hint.
+   */
+  resolveIdentity(event) {
+    const out = {};
+    if (event.developerUserId) out.developerUserId = event.developerUserId;
+    if (event.anonymousId) out.anonymousId = event.anonymousId;
+    if (event.crossdeckCustomerId) out.crossdeckCustomerId = event.crossdeckCustomerId;
+    if (!out.developerUserId && !out.anonymousId && !out.crossdeckCustomerId) {
+      out.anonymousId = this.processAnonymousId;
+    }
+    return out;
+  }
+  /**
+   * Strict normalisation for `ingest()` — no auto-fill of identity,
+   * caller must supply at least one hint per event. Matches v0.1.0
+   * behaviour for backward compatibility with bulk-import callers.
+   */
+  normalizeIngestEvent(event) {
     if (!event.name) {
       throw new CrossdeckError({
         type: "invalid_request_error",
@@ -527,18 +3077,10 @@ var CrossdeckServer = class {
     return {
       ...event,
       properties,
-      eventId: event.eventId ?? this.mintEventId(),
+      eventId: event.eventId ?? mintId("evt", 8),
       timestamp: event.timestamp ?? Date.now()
     };
   }
-  mintEventId() {
-    const ts = Date.now().toString(36);
-    return `evt_${ts}${randomUUID().replace(/-/g, "").slice(0, 8)}`;
-  }
-  mintBatchId() {
-    const ts = Date.now().toString(36);
-    return `batch_${ts}${randomUUID().replace(/-/g, "").slice(0, 8)}`;
-  }
 };
 function sanitizePropertyBag(input, fieldName) {
   if (input === void 0) return void 0;
@@ -552,12 +3094,344 @@ function sanitizePropertyBag(input, fieldName) {
     });
   }
 }
+function categoryFor(name) {
+  if (name.startsWith("page.") || name.startsWith("navigation.")) return "navigation";
+  if (name.startsWith("element.") || name.startsWith("ui.click")) return "ui.click";
+  if (name.startsWith("http.") || name === "request.handled") return "http";
+  return "custom";
+}
+var MAX_CUSTOMER_ID_ALIASES = 1e4;
+function inferEnvFromKey(secretKey) {
+  return secretKey.startsWith("cd_sk_live_") ? "production" : "sandbox";
+}
+async function runBulkOperation(inputs, maxConcurrency, op) {
+  const results = new Array(inputs.length);
+  let cursor = 0;
+  const workers = new Array(Math.min(maxConcurrency, Math.max(1, inputs.length))).fill(0).map(async () => {
+    while (true) {
+      const index = cursor++;
+      if (index >= inputs.length) return;
+      const input = inputs[index];
+      try {
+        const value = await op(input);
+        results[index] = { input, ok: true, value };
+      } catch (err) {
+        results[index] = {
+          input,
+          ok: false,
+          error: err instanceof CrossdeckError ? err : new CrossdeckError({
+            type: "internal_error",
+            code: "bulk_operation_failed",
+            message: err instanceof Error ? err.message : String(err)
+          })
+        };
+      }
+    }
+  });
+  await Promise.all(workers);
+  return results;
+}
+function maskSecretKey(secretKey) {
+  const m = secretKey.match(/^cd_sk_(test|live)_/);
+  const prefix = m ? m[0] : secretKey.slice(0, 11);
+  const tail = secretKey.length > prefix.length + 4 ? secretKey.slice(-4) : "";
+  return `${prefix}****${tail}`;
+}
+
+// src/error-codes.ts
+var _CROSSDECK_ERROR_CODES = Object.freeze([
+  // ----- Configuration -----
+  {
+    code: "invalid_secret_key",
+    type: "configuration_error",
+    description: "The secret key passed to new CrossdeckServer({ secretKey }) doesn't start with cd_sk_.",
+    resolution: "Copy the key from your Crossdeck dashboard \u2192 API keys page. Server SDKs use cd_sk_test_\u2026 (sandbox) or cd_sk_live_\u2026 (production). Never ship this key to a browser.",
+    retryable: false
+  },
+  // ----- Argument validation -----
+  {
+    code: "missing_user_id",
+    type: "invalid_request_error",
+    description: "identify() / aliasIdentity() called with an empty userId.",
+    resolution: "Pass a stable, non-empty user identifier from your auth layer \u2014 never a hardcoded placeholder.",
+    retryable: false
+  },
+  {
+    code: "missing_anonymous_id",
+    type: "invalid_request_error",
+    description: "aliasIdentity() called with an empty anonymousId.",
+    resolution: "Pass the anonymousId originally minted by the web SDK on this user's device.",
+    retryable: false
+  },
+  {
+    code: "missing_customer_id",
+    type: "invalid_request_error",
+    description: "An operation that requires a Crossdeck customer ID was called with an empty value.",
+    resolution: "Pass the customerId returned from a prior identify() / getEntitlements() call.",
+    retryable: false
+  },
+  {
+    code: "missing_identity",
+    type: "invalid_request_error",
+    description: "An ingest / forget / entitlements call received no identity hints.",
+    resolution: "Pass at least one of customerId, userId, or anonymousId on the call (or per-event for ingest).",
+    retryable: false
+  },
+  {
+    code: "missing_event_name",
+    type: "invalid_request_error",
+    description: "track() / ingest() received an event without a name.",
+    resolution: "Pass a non-empty string as the event name. The wire shape is { name, properties? }.",
+    retryable: false
+  },
+  {
+    code: "missing_events",
+    type: "invalid_request_error",
+    description: "ingest() received an empty array.",
+    resolution: "Pass at least one event. Use server.track(event) to send a single event.",
+    retryable: false
+  },
+  {
+    code: "missing_event_id",
+    type: "invalid_request_error",
+    description: "getAuditEntry() called with an empty eventId.",
+    resolution: "Pass the eventId from the audit row you want to inspect.",
+    retryable: false
+  },
+  {
+    code: "missing_signed_transaction_info",
+    type: "invalid_request_error",
+    description: "syncPurchases() called without StoreKit 2 signed transaction info.",
+    resolution: "Pass the JWS string from Transaction.currentEntitlements / Transaction.updates.",
+    retryable: false
+  },
+  {
+    code: "missing_group_type",
+    type: "invalid_request_error",
+    description: "group(type, id) called with an empty type.",
+    resolution: 'Pass a non-empty group type (e.g. "org", "team", "plan") as the first argument.',
+    retryable: false
+  },
+  {
+    code: "serialization_failed",
+    type: "invalid_request_error",
+    description: "An event payload or trait bag could not be JSON-serialised even after sanitisation.",
+    resolution: "Inspect the payload for non-JSON-friendly values (functions, symbols, deeply circular refs). The SDK's validator drops these by default, so this usually means a bug \u2014 file an issue with the payload shape.",
+    retryable: false
+  },
+  // ----- Network / transport -----
+  {
+    code: "fetch_failed",
+    type: "network_error",
+    description: "The underlying fetch() call failed (typically a network outage, DNS, or refused connection).",
+    resolution: "Check the host's outbound network. The SDK retries automatically with exponential backoff + jitter for queued events.",
+    retryable: true
+  },
+  {
+    code: "request_timeout",
+    type: "network_error",
+    description: "A request was aborted after the configured timeoutMs (default 15s).",
+    resolution: "Check the host's network. Increase timeoutMs in CrossdeckServer options if you're on a known-slow link.",
+    retryable: true
+  },
+  {
+    code: "invalid_json_response",
+    type: "internal_error",
+    description: "The server returned a 2xx with an unparseable body.",
+    resolution: "Likely a transient backend bug. Retry; if it persists, contact support with the requestId.",
+    retryable: true
+  },
+  // ----- Lifecycle (Node-specific) -----
+  {
+    code: "flush_on_exit_failed",
+    type: "internal_error",
+    description: "The on-exit drain (beforeExit / SIGTERM / SIGINT) did not complete before flushOnExitTimeoutMs.",
+    resolution: "Increase flushOnExitTimeoutMs in CrossdeckServer options. Default is 2000ms; serverless runtimes typically allow 5-10s before SIGKILL. If events are dropping silently in production, raise this.",
+    retryable: false
+  },
+  // ----- Webhook verification (Node-specific) -----
+  {
+    code: "webhook_invalid_signature",
+    type: "authentication_error",
+    description: "The webhook signature header did not verify against the supplied secret.",
+    resolution: "Confirm the secret matches the one in your Crossdeck dashboard \u2192 Webhooks page. If the request is genuinely from Crossdeck, the secret is wrong, stale, or recently rotated.",
+    retryable: false
+  },
+  {
+    code: "webhook_replay_window_exceeded",
+    type: "authentication_error",
+    description: "The webhook timestamp is older than the replay-tolerance window (default 5 minutes).",
+    resolution: "The webhook is either replayed or your receiving clock is wildly skewed. Verify NTP on the receiving host. Increase replayToleranceMs only if you accept the replay-attack risk.",
+    retryable: false
+  },
+  {
+    code: "webhook_missing_secret",
+    type: "configuration_error",
+    description: "verifyWebhookSignature() was called without a signing secret.",
+    resolution: "Pass the secret from your Crossdeck dashboard \u2192 Webhooks page. Never hardcode in source \u2014 read from an env var.",
+    retryable: false
+  }
+]);
+function isCrossdeckErrorCode(code) {
+  return _CROSSDECK_ERROR_CODES.some((e) => e.code === code);
+}
+var CROSSDECK_ERROR_CODES = _CROSSDECK_ERROR_CODES;
+function getErrorCode(code) {
+  return CROSSDECK_ERROR_CODES.find((e) => e.code === code);
+}
+
+// src/webhooks.ts
+import { createHmac, timingSafeEqual } from "crypto";
+var DEFAULT_REPLAY_TOLERANCE_MS = 5 * 60 * 1e3;
+function verifyWebhookSignature(payload, signatureHeader, secret, options = {}) {
+  const secrets = normaliseSecrets(secret);
+  if (secrets.length === 0) {
+    throw new CrossdeckError({
+      type: "configuration_error",
+      code: "webhook_missing_secret",
+      message: "verifyWebhookSignature requires a non-empty secret. Read it from process.env.CROSSDECK_WEBHOOK_SECRET \u2014 never hardcode in source."
+    });
+  }
+  const header = normaliseHeader(signatureHeader);
+  const parsed = parseSignatureHeader(header);
+  if (!parsed) {
+    throw new CrossdeckError({
+      type: "authentication_error",
+      code: "webhook_invalid_signature",
+      message: "Webhook signature header is missing or malformed. Expected 'Crossdeck-Signature: t=<unix>,v1=<hex>'."
+    });
+  }
+  const tolerance = options.replayToleranceMs ?? DEFAULT_REPLAY_TOLERANCE_MS;
+  if (tolerance > 0) {
+    const now = (options.now ?? Date.now)();
+    const timestampMs = parsed.timestampSec * 1e3;
+    const drift = Math.abs(now - timestampMs);
+    if (drift > tolerance) {
+      throw new CrossdeckError({
+        type: "authentication_error",
+        code: "webhook_replay_window_exceeded",
+        message: `Webhook timestamp is ${drift}ms outside the ${tolerance}ms replay-tolerance window. Either the request is replayed or the receiving clock is skewed \u2014 verify NTP on the host.`
+      });
+    }
+  }
+  const signedPayload = `${parsed.timestampSec}.${payload}`;
+  const expectedBuf = Buffer.from(parsed.signature, "hex");
+  if (expectedBuf.length === 0) {
+    throw new CrossdeckError({
+      type: "authentication_error",
+      code: "webhook_invalid_signature",
+      message: "Webhook signature is not a valid hex string."
+    });
+  }
+  const anyMatch = secrets.some((s) => {
+    const computed = createHmac("sha256", s).update(signedPayload).digest();
+    return computed.length === expectedBuf.length && timingSafeEqual(computed, expectedBuf);
+  });
+  if (!anyMatch) {
+    throw new CrossdeckError({
+      type: "authentication_error",
+      code: "webhook_invalid_signature",
+      message: "Webhook signature did not verify. Confirm the secret matches your Crossdeck dashboard \u2192 Webhooks page (and that you're not on a stale rotation)."
+    });
+  }
+  try {
+    return JSON.parse(payload);
+  } catch {
+    throw new CrossdeckError({
+      type: "authentication_error",
+      code: "webhook_invalid_signature",
+      message: "Webhook signature verified but the payload is not valid JSON. Either the payload was tampered with after signing, or the webhook source is misconfigured."
+    });
+  }
+}
+function signWebhookPayload(payload, secret, timestampSec) {
+  return createHmac("sha256", secret).update(`${timestampSec}.${payload}`).digest("hex");
+}
+function parseSignatureHeader(header) {
+  if (!header) return null;
+  let timestampSec = null;
+  let signature = null;
+  for (const part of header.split(",")) {
+    const eqIdx = part.indexOf("=");
+    if (eqIdx <= 0) continue;
+    const key = part.slice(0, eqIdx).trim();
+    const value = part.slice(eqIdx + 1).trim();
+    if (key === "t") {
+      const n = Number(value);
+      if (Number.isFinite(n) && n > 0) timestampSec = Math.floor(n);
+    } else if (key === "v1") {
+      if (/^[0-9a-fA-F]+$/.test(value)) signature = value.toLowerCase();
+    }
+  }
+  if (timestampSec === null || signature === null) return null;
+  return { timestampSec, signature };
+}
+function normaliseHeader(input) {
+  if (input === void 0) return null;
+  if (Array.isArray(input)) return input[0] ?? null;
+  return input;
+}
+function normaliseSecrets(input) {
+  if (input === void 0 || input === null) return [];
+  const arr = Array.isArray(input) ? input : [input];
+  return arr.filter((s) => typeof s === "string" && s.length > 0);
+}
+
+// src/consent.ts
+var EMAIL_PATTERN = /[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/g;
+var CARD_PATTERN = /\b\d(?:[ -]?\d){12,18}\b/g;
+var REPLACEMENT_EMAIL = "[email]";
+var REPLACEMENT_CARD = "[card]";
+function scrubPii(value) {
+  if (!value) return value;
+  let out = value;
+  if (EMAIL_PATTERN.test(out)) {
+    out = out.replace(EMAIL_PATTERN, REPLACEMENT_EMAIL);
+  }
+  EMAIL_PATTERN.lastIndex = 0;
+  if (CARD_PATTERN.test(out)) {
+    out = out.replace(CARD_PATTERN, REPLACEMENT_CARD);
+  }
+  CARD_PATTERN.lastIndex = 0;
+  return out;
+}
+function scrubPiiFromProperties(properties) {
+  const out = {};
+  for (const k of Object.keys(properties)) {
+    out[k] = scrubValue(properties[k]);
+  }
+  return out;
+}
+function scrubValue(v) {
+  if (typeof v === "string") return scrubPii(v);
+  if (Array.isArray(v)) return v.map(scrubValue);
+  if (v && typeof v === "object" && v.constructor === Object) {
+    return scrubPiiFromProperties(v);
+  }
+  return v;
+}
 export {
+  CROSSDECK_API_VERSION,
+  CROSSDECK_ERROR_CODES,
+  CrossdeckAuthenticationError,
+  CrossdeckConfigurationError,
   CrossdeckError,
+  CrossdeckInternalError,
+  CrossdeckNetworkError,
+  CrossdeckPermissionError,
+  CrossdeckRateLimitError,
   CrossdeckServer,
+  CrossdeckValidationError,
   DEFAULT_BASE_URL,
   DEFAULT_TIMEOUT_MS,
   SDK_NAME,
-  SDK_VERSION
+  SDK_VERSION,
+  getErrorCode,
+  isCrossdeckErrorCode,
+  makeCrossdeckError,
+  scrubPii,
+  scrubPiiFromProperties,
+  signWebhookPayload,
+  verifyWebhookSignature
 };
 //# sourceMappingURL=index.mjs.map