@cross-deck/node 1.0.0 → 1.1.1

package/CHANGELOG.md

@@ -4,6 +4,29 @@ All notable changes to `@cross-deck/node` will be documented here. The
 format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.1.0] — 2026-05-13
+
+### Added
+
+- **Auto-heartbeat on construction.** `new CrossdeckServer({...})` now
+  fires a heartbeat in the background the moment the SDK is
+  constructed, fire-and-forget. The dashboard's row flips LIVE within
+  ~200 ms of the customer's process boot — no explicit `.heartbeat()`
+  call required in the bootstrap. Solves the cold-start serverless
+  verification problem at its root (function boot triggers SDK
+  construction triggers heartbeat; the install-verifier's URL probe
+  doubles as a cold-start waker).
+- New option `bootHeartbeat?: boolean` (default `true`). Set `false`
+  for latency-sensitive cold paths that want the prior v1.0.0
+  caller-controlled behaviour. Implicitly disabled in `testMode`.
+
+### Why this is non-breaking
+
+The boot heartbeat is fire-and-forget and swallows its own errors —
+the caller's code never blocks on it, never throws, and a failure
+(bad key, network blip, firewall) has zero effect on subsequent
+event flushes. Equivalent to Sentry's `Sentry.init()` boot session.
+
 ## [1.0.0] — 2026-05-13
 
 Full three-USP server SDK release. Version-aligned with `@cross-deck/web@1.0.0`. Bank-grade quality bar — Stripe + Apple + Google VP-level QA review across two passes. 6,796 LOC of source / 6,230 LOC of tests / 398 unit tests + 19 e2e todos passing / Gate 3 fixture verifying the snippet against the built bundle. Web-SDK parity at the capability level: every Web SDK guarantee that has a server-side analogue ships here.

package/dist/auto-events/index.d.mts

@@ -1,4 +1,4 @@
-import { p as CrossdeckServer } from '../crossdeck-server-LvQwPKu5.mjs';
+import { p as CrossdeckServer } from '../crossdeck-server-BXQaFjVx.mjs';
 import 'node:events';
 
 /**

package/dist/auto-events/index.d.ts

@@ -1,4 +1,4 @@
-import { p as CrossdeckServer } from '../crossdeck-server-LvQwPKu5.js';
+import { p as CrossdeckServer } from '../crossdeck-server-BXQaFjVx.js';
 import 'node:events';
 
 /**

package/dist/{crossdeck-server-LvQwPKu5.d.mts → crossdeck-server-BXQaFjVx.d.mts}

@@ -236,7 +236,7 @@ interface RuntimeInfo {
 }
 
 declare const SDK_NAME = "@cross-deck/node";
-declare const SDK_VERSION = "1.0.0";
+declare const SDK_VERSION = "1.1.0";
 declare const DEFAULT_BASE_URL = "https://api.cross-deck.com/v1";
 declare const DEFAULT_TIMEOUT_MS = 15000;
 /**
@@ -430,6 +430,27 @@ interface CrossdeckServerOptions {
      * platform's own SIGKILL (typically 5-10s after SIGTERM) preempts us.
      */
     flushOnExitTimeoutMs?: number;
+    /**
+     * Fire a heartbeat in the background the moment the SDK is
+     * constructed. Default `true`.
+     *
+     * This is what makes the dashboard's "Verify install" surface
+     * actually work in cold-start serverless: the moment the customer's
+     * process boots and runs `new CrossdeckServer({...})`, we phone
+     * home, the dashboard row flips LIVE, and the caller doesn't have
+     * to add an explicit `await server.heartbeat()` to their bootstrap.
+     *
+     * Fire-and-forget. Failures are swallowed (the SDK still works for
+     * events even if this boot ping can't reach the backend). The
+     * caller's process never blocks on this.
+     *
+     * Set `false` if you want the prior v1.0.0 behaviour where the
+     * caller controlled when (or whether) the first network ping fired
+     * — e.g., very latency-sensitive cold paths, or environments where
+     * the very first request must not race with an SDK-initiated call.
+     * `testMode: true` also disables this implicitly.
+     */
+    bootHeartbeat?: boolean;
     /**
      * TTL for the entitlement cache (ms). Default 60_000 (60s).
      *

package/dist/{crossdeck-server-LvQwPKu5.d.ts → crossdeck-server-BXQaFjVx.d.ts}

@@ -236,7 +236,7 @@ interface RuntimeInfo {
 }
 
 declare const SDK_NAME = "@cross-deck/node";
-declare const SDK_VERSION = "1.0.0";
+declare const SDK_VERSION = "1.1.0";
 declare const DEFAULT_BASE_URL = "https://api.cross-deck.com/v1";
 declare const DEFAULT_TIMEOUT_MS = 15000;
 /**
@@ -430,6 +430,27 @@ interface CrossdeckServerOptions {
      * platform's own SIGKILL (typically 5-10s after SIGTERM) preempts us.
      */
     flushOnExitTimeoutMs?: number;
+    /**
+     * Fire a heartbeat in the background the moment the SDK is
+     * constructed. Default `true`.
+     *
+     * This is what makes the dashboard's "Verify install" surface
+     * actually work in cold-start serverless: the moment the customer's
+     * process boots and runs `new CrossdeckServer({...})`, we phone
+     * home, the dashboard row flips LIVE, and the caller doesn't have
+     * to add an explicit `await server.heartbeat()` to their bootstrap.
+     *
+     * Fire-and-forget. Failures are swallowed (the SDK still works for
+     * events even if this boot ping can't reach the backend). The
+     * caller's process never blocks on this.
+     *
+     * Set `false` if you want the prior v1.0.0 behaviour where the
+     * caller controlled when (or whether) the first network ping fired
+     * — e.g., very latency-sensitive cold paths, or environments where
+     * the very first request must not race with an SDK-initiated call.
+     * `testMode: true` also disables this implicitly.
+     */
+    bootHeartbeat?: boolean;
     /**
      * TTL for the entitlement cache (ms). Default 60_000 (60s).
      *

package/dist/index.cjs

@@ -365,7 +365,7 @@ function byteLength(s) {
 
 // src/http.ts
 var SDK_NAME = "@cross-deck/node";
-var SDK_VERSION = "1.0.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";
@@ -1084,13 +1084,21 @@ function isInAppFrame(filename) {
   if (/^internal[\\/]/.test(filename)) return false;
   return true;
 }
-function fingerprintError(message, frames) {
+function fingerprintError(message, frames, location) {
   const inAppFrames = frames.filter((f) => f.in_app).slice(0, 3);
-  const key = [
+  const parts = [
     (message || "").slice(0, 200),
     ...inAppFrames.map((f) => `${f.function}@${f.filename}:${f.lineno}`)
-  ].join("|");
-  return djb2Hex(key);
+  ];
+  if (inAppFrames.length === 0 && location) {
+    const loc = [
+      location.errorType ?? "",
+      location.filename ?? "",
+      location.lineno ?? ""
+    ].join(":");
+    if (loc !== "::") parts.push(loc);
+  }
+  return djb2Hex(parts.join("|"));
 }
 function djb2Hex(input) {
   let h = 5381;
@@ -1321,34 +1329,30 @@ var ErrorTracker = class {
    * 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);
+    const payload = coerceErrorPayload(err);
+    const message = (payload.message || "Unknown error").slice(0, 1024);
+    const stack = err instanceof Error ? err.stack ?? null : null;
+    const frames = parseStack(stack);
+    const errorType = payload.errorType ?? null;
+    const context = payload.extras ? { ...this.opts.getContext(), __error_extras: payload.extras } : this.opts.getContext();
     return {
       timestamp: Date.now(),
       kind,
       level,
       message,
-      errorType: null,
-      frames: [],
-      rawStack: null,
-      fingerprint: fingerprintError(message, []),
+      errorType,
+      frames,
+      rawStack: stack,
+      // Location fallback ensures distinct call sites stay separate
+      // even when the message is generic and there are no parseable
+      // frames (e.g. `throw "boom"` from a middleware).
+      fingerprint: fingerprintError(message, frames, {
+        filename: frames[0]?.filename ?? null,
+        lineno: frames[0]?.lineno ?? null,
+        errorType
+      }),
       breadcrumbs: this.opts.breadcrumbs.snapshot(),
-      context: this.opts.getContext(),
+      context,
       tags: this.opts.getTags()
     };
   }
@@ -1363,7 +1367,10 @@ var ErrorTracker = class {
         errorType: "HTTPError",
         frames: [],
         rawStack: null,
-        fingerprint: fingerprintError(`HTTP ${info.status} ${info.method}`, []),
+        fingerprint: fingerprintError(`HTTP ${info.status} ${info.method}`, [], {
+          filename: info.url,
+          errorType: "HTTPError"
+        }),
         breadcrumbs: this.opts.breadcrumbs.snapshot(),
         context: this.opts.getContext(),
         tags: this.opts.getTags(),
@@ -1466,16 +1473,151 @@ var ErrorTracker = class {
     }
   }
 };
-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);
+function coerceErrorPayload(v) {
+  if (v === null) return { message: "(thrown: null)", errorType: null, extras: null };
+  if (v === void 0) return { message: "(thrown: undefined)", errorType: null, extras: null };
+  if (typeof v === "string") {
+    return { message: v, errorType: null, extras: null };
+  }
+  if (typeof v === "number" || typeof v === "boolean" || typeof v === "bigint") {
+    return { message: String(v), errorType: typeof v, extras: null };
+  }
+  if (typeof v === "symbol") {
+    return { message: v.toString(), errorType: "symbol", extras: null };
+  }
+  if (typeof v === "function") {
+    return { message: `(thrown function: ${v.name || "anonymous"})`, errorType: "function", extras: null };
+  }
+  if (v instanceof Error) {
+    const errorType = v.name || v.constructor?.name || "Error";
+    const message = typeof v.message === "string" && v.message.length > 0 ? v.message : safeToString(v) || errorType;
+    const extras = {};
+    const causeChain = collectCauseChain(v);
+    if (causeChain.length > 0) extras.cause = causeChain;
+    const aggErrors = v.errors;
+    if (Array.isArray(aggErrors)) {
+      extras.aggregatedErrors = aggErrors.slice(0, 10).map((inner) => {
+        if (inner instanceof Error) {
+          return { name: inner.name || "Error", message: inner.message || "" };
+        }
+        return { name: "non-Error", message: safeToString(inner) };
+      });
+    }
+    for (const key of [
+      "code",
+      "errno",
+      "syscall",
+      "path",
+      "status",
+      "statusCode",
+      "response",
+      "data",
+      "detail",
+      "details"
+    ]) {
+      const val = v[key];
+      if (val !== void 0 && typeof val !== "function") {
+        extras[key] = safeClone(val);
+      }
+    }
+    for (const key of Object.keys(v)) {
+      if (key === "message" || key === "stack" || key === "name" || key === "cause" || key === "errors") continue;
+      if (key in extras) continue;
+      const val = v[key];
+      if (typeof val === "function") continue;
+      extras[key] = safeClone(val);
+    }
+    return {
+      message,
+      errorType,
+      extras: Object.keys(extras).length > 0 ? extras : null
+    };
+  }
+  if (typeof Response !== "undefined" && v instanceof Response) {
+    return {
+      message: `HTTP ${v.status} ${v.statusText || ""}${v.url ? ` ${v.url}` : ""}`.trim(),
+      errorType: "Response",
+      extras: { status: v.status, statusText: v.statusText, url: v.url, type: v.type }
+    };
+  }
+  if (typeof v === "object") {
+    const obj = v;
+    const ctorName = obj.constructor && typeof obj.constructor === "function" && obj.constructor.name || null;
+    const ownMessage = typeof obj.message === "string" && obj.message ? obj.message : null;
+    const ownName = typeof obj.name === "string" && obj.name ? obj.name : null;
+    let jsonForm = null;
+    try {
+      const serialised = JSON.stringify(obj);
+      jsonForm = serialised === "{}" ? null : serialised;
+    } catch {
+      jsonForm = null;
+    }
+    const fallbackString = safeToString(obj);
+    const message = ownMessage ?? jsonForm ?? (fallbackString && fallbackString !== "[object Object]" ? fallbackString : null) ?? (ctorName ? `(thrown ${ctorName} with no message)` : "(thrown object with no message)");
+    const errorType = ownName ?? ctorName ?? null;
+    const extras = {};
+    let count = 0;
+    for (const key of Object.keys(obj)) {
+      if (count >= 20) break;
+      if (key === "message" || key === "name") continue;
+      const val = obj[key];
+      if (typeof val === "function") continue;
+      extras[key] = safeClone(val);
+      count++;
+    }
+    return {
+      message,
+      errorType,
+      extras: Object.keys(extras).length > 0 ? extras : null
+    };
+  }
+  return { message: safeToString(v) || "(unstringifiable thrown value)", errorType: null, extras: null };
+}
+function collectCauseChain(err) {
+  const out = [];
+  let cur = err.cause;
+  let depth = 0;
+  while (cur != null && depth < 5) {
+    if (cur instanceof Error) {
+      out.push({ name: cur.name || "Error", message: cur.message || "" });
+      cur = cur.cause;
+    } else {
+      out.push({ name: "non-Error", message: safeToString(cur) });
+      cur = null;
+    }
+    depth++;
+  }
+  return out;
+}
+function safeToString(v) {
+  try {
+    const s = Object.prototype.toString.call(v);
+    if (s !== "[object Object]") return s;
+    const own = v?.toString;
+    if (typeof own === "function" && own !== Object.prototype.toString) {
+      const r = own.call(v);
+      if (typeof r === "string") return r;
+    }
+    return s;
+  } catch {
+    return "(throwing toString)";
+  }
+}
+function safeClone(v) {
+  if (v == null) return v;
+  const t = typeof v;
+  if (t === "string" || t === "number" || t === "boolean") return v;
+  if (t === "bigint") return String(v);
   try {
-    return JSON.stringify(v);
+    const s = JSON.stringify(v);
+    return s === void 0 ? safeToString(v) : JSON.parse(s);
   } catch {
-    return Object.prototype.toString.call(v);
+    return safeToString(v);
   }
 }
+function safeStringify3(v) {
+  return coerceErrorPayload(v).message;
+}
 
 // src/runtime-info.ts
 var import_node_os = require("os");
@@ -2239,6 +2381,17 @@ var CrossdeckServer = class extends import_node_events.EventEmitter {
       });
       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)