@cross-deck/node 1.0.0 → 1.1.0

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";
@@ -2239,6 +2239,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)