@licenseseat/js 0.3.0 → 0.4.1

package/dist/types/LicenseSeat.d.ts

@@ -16,6 +16,11 @@ export function configure(config: import("./types.js").LicenseSeatConfig, force?
  * @returns {void}
  */
 export function resetSharedInstance(): void;
+/**
+ * SDK version constant
+ * @type {string}
+ */
+export const SDK_VERSION: string;
 /**
  * LicenseSeat SDK Main Class
  *
@@ -61,6 +66,12 @@ export class LicenseSeatSDK {
      * @private
      */
     private validationTimer;
+    /**
+     * Heartbeat timer ID (separate from auto-validation)
+     * @type {ReturnType<typeof setInterval>|null}
+     * @private
+     */
+    private heartbeatTimer;
     /**
      * License cache manager
      * @type {LicenseCache}
@@ -192,13 +203,26 @@ export class LicenseSeatSDK {
      */
     getStatus(): import("./types.js").LicenseStatus;
     /**
-     * Test server authentication
-     * Useful for verifying API key/session is valid.
-     * @returns {Promise<Object>} Result from the server
-     * @throws {ConfigurationError} When API key is not configured
-     * @throws {APIError} When authentication fails
+     * Test API connectivity
+     * Makes a request to the health endpoint to verify connectivity.
+     * Note: To fully verify API key validity, attempt an actual operation like activate() or validateLicense().
+     * @returns {Promise<{authenticated: boolean, healthy: boolean, api_version: string}>}
+     * @throws {ConfigurationError} If API key is not configured
+     * @throws {APIError} If the health check fails
+     */
+    testAuth(): Promise<{
+        authenticated: boolean;
+        healthy: boolean;
+        api_version: string;
+    }>;
+    /**
+     * Send a heartbeat for the current license.
+     * Heartbeats let the server know the device is still active.
+     * @returns {Promise<Object|undefined>} Heartbeat response, or undefined if no active license
+     * @throws {ConfigurationError} When productSlug is not configured
+     * @throws {APIError} When the API request fails
      */
-    testAuth(): Promise<any>;
+    heartbeat(): Promise<any | undefined>;
     /**
      * Clear all data and reset SDK state
      * @returns {void}
@@ -246,6 +270,19 @@ export class LicenseSeatSDK {
      * @private
      */
     private stopAutoValidation;
+    /**
+     * Start separate heartbeat timer
+     * Sends periodic heartbeats between auto-validation cycles.
+     * @returns {void}
+     * @private
+     */
+    private startHeartbeat;
+    /**
+     * Stop the separate heartbeat timer
+     * @returns {void}
+     * @private
+     */
+    private stopHeartbeat;
     /**
      * Start connectivity polling (when offline)
      * @returns {void}
@@ -259,12 +296,12 @@ export class LicenseSeatSDK {
      */
     private stopConnectivityPolling;
     /**
-     * Fetch and cache offline token and signing key
-     * Uses a lock to prevent concurrent calls from causing race conditions
+     * Download and cache the offline token and its corresponding public signing key.
+     * Emits `offlineToken:ready` on success. Safe to call multiple times — concurrent
+     * calls are deduplicated automatically.
      * @returns {Promise<void>}
-     * @private
      */
-    private syncOfflineAssets;
+    syncOfflineAssets(): Promise<void>;
     /**
      * Schedule periodic offline license refresh
      * @returns {void}
@@ -272,11 +309,12 @@ export class LicenseSeatSDK {
      */
     private scheduleOfflineRefresh;
     /**
-     * Verify cached offline token
+     * Verify the cached offline token and return a validation result.
+     * Use this to validate the license when the device is offline.
+     * The offline token must have been previously downloaded via {@link syncOfflineAssets}.
      * @returns {Promise<import('./types.js').ValidationResult>}
-     * @private
      */
-    private verifyCachedOffline;
+    verifyCachedOffline(): Promise<import("./types.js").ValidationResult>;
     /**
      * Quick offline verification using only local data (no network)
      * Performs signature verification plus basic validity checks (expiry, license key match)

package/dist/types/LicenseSeat.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"LicenseSeat.d.ts","sourceRoot":"","sources":["../../src/LicenseSeat.js"],"names":[],"mappings":"AA0uCA;;;;GAIG;AACH,2CAHW,OAAO,YAAY,EAAE,iBAAiB,GACpC,cAAc,CAO1B;AAED;;;;;GAKG;AACH,kCAJW,OAAO,YAAY,EAAE,iBAAiB,UACtC,OAAO,GACL,cAAc,CAW1B;AAED;;;GAGG;AACH,uCAFa,IAAI,CAOhB;AAztCD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH;IACE;;;OAGG;IACH,qBAFW,OAAO,YAAY,EAAE,iBAAiB,EA+FhD;IA5FC;;;OAGG;IACH,QAFU,OAAO,YAAY,EAAE,iBAAiB,CAK/C;IAED;;;;OAIG;IACH,uBAAwB;IAExB;;;;OAIG;IACH,wBAA2B;IAE3B;;;;OAIG;IACH,cAAwD;IAExD;;;;OAIG;IACH,eAAkB;IAElB;;;;OAIG;IACH,8BAAiC;IAEjC;;;;OAIG;IACH,0BAA6B;IAE7B;;;;OAIG;IACH,4BAA+B;IAE/B;;;;OAIG;IACH,8BAAiC;IAEjC;;;;OAIG;IACH,6BAAiC;IAEjC;;;;OAIG;IACH,kBAAsB;IAiBxB;;;;;OAKG;IACH,cAFa,IAAI,CAkDhB;IAED;;;;;;;OAOG;IACH,qBANW,MAAM,YACN,OAAO,YAAY,EAAE,iBAAiB,GACpC,OAAO,CAAC,OAAO,YAAY,EAAE,aAAa,CAAC,CAoDvD;IAED;;;;;;OAMG;IACH,cALa,OAAO,KAAQ,CAuC3B;IAED;;;;;;;OAOG;IACH,4BANW,MAAM,YACN,OAAO,YAAY,EAAE,iBAAiB,GACpC,OAAO,CAAC,OAAO,YAAY,EAAE,gBAAgB,CAAC,CA6G1D;IAED;;;;OAIG;IACH,iCAHW,MAAM,GACJ,OAAO,YAAY,EAAE,sBAAsB,CA6BvD;IAED;;;;;;OAMG;IACH,+BAHW,MAAM,GACJ,OAAO,CAInB;IAED;;;;;;;;;OASG;IACH,0BAPG;QAAyB,QAAQ,GAAzB,MAAM;QACW,OAAO,GAAxB,MAAM;KACd,GAAU,OAAO,CAAC,OAAO,YAAY,EAAE,YAAY,CAAC,CAsDtD;IAED;;;;;OAKG;IACH,qBAJW,MAAM,GACJ,OAAO,CAAC,OAAO,YAAY,EAAE,UAAU,CAAC,CAyBpD;IAED;;;;;;;OAOG;IACH,qCANW,OAAO,YAAY,EAAE,YAAY,gBACjC,MAAM,GACJ,OAAO,CAAC,OAAO,CAAC,CA6C5B;IAED;;;OAGG;IACH,aAFa,OAAO,YAAY,EAAE,aAAa,CA6C9C;IAED;;;;;;OAMG;IACH,YAJa,OAAO,KAAQ,CAoB3B;IAED;;;OAGG;IACH,SAFa,IAAI,CAahB;IAED;;;;;OAKG;IACH,WAFa,IAAI,CAehB;IAMD;;;;;OAKG;IACH,UAJW,MAAM,YACN,OAAO,YAAY,EAAE,aAAa,GAChC,OAAO,YAAY,EAAE,gBAAgB,CAQjD;IAED;;;;;OAKG;IACH,WAJW,MAAM,YACN,OAAO,YAAY,EAAE,aAAa,GAChC,IAAI,CAQhB;IAED;;;;;;OAMG;IACH,aAWC;IAMD;;;;;OAKG;IACH,4BAqBC;IAED;;;;OAIG;IACH,2BAMC;IAED;;;;OAIG;IACH,iCA6BC;IAED;;;;OAIG;IACH,gCAKC;IAMD;;;;;OAKG;IACH,0BAwCC;IAED;;;;OAIG;IACH,+BAMC;IAED;;;;OAIG;IACH,4BAuEC;IAED;;;;;OAKG;IACH,sCA4CC;IAMD;;;;;;;;;;OAUG;IACH,gBAsFC;IAED;;;;;OAKG;IACH,yBAsBC;IAMD;;;OAGG;IACH,gBAFa,MAAM,CAIlB;IAED;;;;;OAKG;IACH,YAIC;CACF"}
+{"version":3,"file":"LicenseSeat.d.ts","sourceRoot":"","sources":["../../src/LicenseSeat.js"],"names":[],"mappings":"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"}

package/dist/types/index.d.ts

@@ -1,7 +1,8 @@
 export { LicenseCache } from "./cache.js";
+export { collectTelemetry } from "./telemetry.js";
 export default LicenseSeatSDK;
 import { LicenseSeatSDK } from "./LicenseSeat.js";
-export { LicenseSeatSDK, getSharedInstance, configure, resetSharedInstance } from "./LicenseSeat.js";
+export { LicenseSeatSDK, SDK_VERSION, getSharedInstance, configure, resetSharedInstance } from "./LicenseSeat.js";
 export { APIError, ConfigurationError, LicenseError, CryptoError } from "./errors.js";
 export { parseActiveEntitlements, constantTimeEqual, canonicalJsonStringify, base64UrlDecode, generateDeviceId, getCsrfToken } from "./utils.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/types/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.js"],"names":[],"mappings":";;+BA4D+B,kBAAkB"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.js"],"names":[],"mappings":";;;+BAiE+B,kBAAkB"}

package/dist/types/telemetry.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Collect telemetry data for the current environment.
+ * Returns a plain object with snake_case keys matching the server schema.
+ * Null/undefined values are filtered out.
+ *
+ * @param {string} sdkVersion - The SDK version string
+ * @param {Object} [options] - Additional options
+ * @param {string} [options.appVersion] - User-provided app version
+ * @param {string} [options.appBuild] - User-provided app build
+ * @returns {Object} Telemetry data object
+ */
+export function collectTelemetry(sdkVersion: string, options?: {
+    appVersion?: string;
+    appBuild?: string;
+}): any;
+//# sourceMappingURL=telemetry.d.ts.map

package/dist/types/telemetry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry.d.ts","sourceRoot":"","sources":["../../src/telemetry.js"],"names":[],"mappings":"AAwdA;;;;;;;;;;GAUG;AACH,6CANW,MAAM,YAEd;IAAyB,UAAU,GAA3B,MAAM;IACW,QAAQ,GAAzB,MAAM;CACd,OAoCF"}

package/dist/types/types.d.ts

@@ -58,6 +58,22 @@ export type LicenseSeatConfig = {
      * - Automatically initialize and validate cached license on construction
      */
     autoInitialize?: boolean;
+    /**
+     * - Enable telemetry collection on POST requests (set false for GDPR compliance)
+     */
+    telemetryEnabled?: boolean;
+    /**
+     * - Interval in ms between automatic heartbeats (default: 5 minutes, set 0 to disable)
+     */
+    heartbeatInterval?: number;
+    /**
+     * - User-provided app version string, sent as app_version in telemetry
+     */
+    appVersion?: string;
+    /**
+     * - User-provided app build identifier, sent as app_build in telemetry
+     */
+    appBuild?: string;
 };
 /**
  * License activation options
@@ -504,6 +520,23 @@ export type SigningKey = {
      */
     status: string;
 };
+/**
+ * Heartbeat response from the API
+ */
+export type HeartbeatResponse = {
+    /**
+     * - Object type ("heartbeat")
+     */
+    object: string;
+    /**
+     * - ISO8601 timestamp of when the heartbeat was received
+     */
+    received_at: string;
+    /**
+     * - The license object
+     */
+    license: LicenseObject;
+};
 /**
  * Health check response
  */

package/dist/types/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.js"],"names":[],"mappings":";;;;;;;iBASc,MAAM;;;;kBACN,MAAM;;;;aACN,MAAM;;;;oBACN,MAAM;;;;2BACN,MAAM;;;;6BACN,MAAM;;;;iBACN,MAAM;;;;iBACN,MAAM;;;;YACN,OAAO;;;;oCACP,MAAM;;;;6BACN,OAAO;;;;qBACP,MAAM;;;;qBACN,MAAM;;;;qBACN,OAAO;;;;;;;;;eAMP,MAAM;;;;iBACN,MAAM;;;;;;;;;;;;;eAON,MAAM;;;;;;;;;YAMN,MAAM;;;;QACN,MAAM;;;;eACN,MAAM;;;;kBACN,MAAM;;;;iBACN,MAAM;;;;kBACN,MAAM;;;;qBACN,MAAM,GAAC,IAAI;;;;iBACX,MAAM;;;;;;;;aAEN,aAAa;;;;;;;;;YAMb,MAAM;;;;mBACN,MAAM;;;;oBACN,MAAM;;;;;;;;;SAMN,MAAM;;;;YACN,MAAM;;;;gBACN,MAAM;;;;iBACN,MAAM,GAAC,IAAI;;;;UACX,MAAM;;;;cACN,MAAM;;;;iBACN,MAAM;;;;kBACN,MAAM;;;;yBACN,WAAW,EAAE;;;;;;;;aAEb,WAAW;;;;;;;;;UAMX,MAAM;;;;UACN,MAAM;;;;;;;;;iBAMN,MAAM;;;;eACN,MAAM;;;;iBACN,kBAAkB;;;;kBAClB,MAAM;;;;oBACN,MAAM;;;;iBACN,gBAAgB;;;;;;;;;SAMhB,MAAM;;;;gBACN,MAAM,GAAC,IAAI;;;;cACX,MAAO,IAAI;;;;;;;;;WAMX,OAAO;;;;cACP,OAAO;;;;WACP,MAAM;;;;cACN,MAAM;;;;eACN,iBAAiB,EAAE;;;;cACnB,aAAa;;;;iBACb,kBAAkB;;;;0BAClB,WAAW,EAAE;;;;iBACb,OAAO;;;;;;;;;UAMP,MAAM;;;;aACN,MAAM;;;;;;;;;YAMN,OAAO;;;;aACP,MAAM;;;;iBACN,MAAM;;;;kBACN,WAAW;;;;;;;;;YAMX,MAAM;;;;cACN,MAAM;;;;cACN,MAAM;;;;aACN,MAAM;;;;mBACN,MAAM;;;;qBACN,MAAM;;;;mBACN,WAAW,EAAE;;;;;;;;;YAMb,MAAM;;;;WACN,mBAAmB;;;;eACnB,qBAAqB;;;;eACrB,MAAM;;;;;;;;;oBAMN,MAAM;;;;iBACN,MAAM;;;;kBACN,MAAM;;;;cACN,MAAM;;;;UACN,MAAM;;;;iBACN,MAAM,GAAC,IAAI;;;;gBACX,MAAM,GAAC,IAAI;;;;SACX,MAAM;;;;SACN,MAAM;;;;SACN,MAAM;;;;yBACN,MAAM,GAAC,IAAI;;;;SACX,MAAM;;;;kBACN,kBAAkB,EAAE;;;;;;;;;;;;;SAOpB,MAAM;;;;iBACN,MAAM,GAAC,IAAI;;;;;;;;;eAMX,MAAM;;;;YACN,MAAM;;;;WACN,MAAM;;;;;;;;;YAMN,MAAM;;;;YACN,MAAM;;;;eACN,MAAM;;;;gBACN,MAAM;;;;iBACN,MAAM;;;;YACN,MAAM;;;;;;;;;YAMN,MAAM;;;;YACN,MAAM;;;;iBACN,MAAM;;;;eACN,MAAM;;;;;mCAMT,GAAC,KACC,IAAI;;;;qCAMJ,IAAI;;;;;;;;YAMH,cAAc;;;;WACd,MAAM;;;;cACN,MAAM;;;;;;;;;UAMN,MAAM;;;;aACN,MAAM"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.js"],"names":[],"mappings":";;;;;;;iBASc,MAAM;;;;kBACN,MAAM;;;;aACN,MAAM;;;;oBACN,MAAM;;;;2BACN,MAAM;;;;6BACN,MAAM;;;;iBACN,MAAM;;;;iBACN,MAAM;;;;YACN,OAAO;;;;oCACP,MAAM;;;;6BACN,OAAO;;;;qBACP,MAAM;;;;qBACN,MAAM;;;;qBACN,OAAO;;;;uBACP,OAAO;;;;wBACP,MAAM;;;;iBACN,MAAM;;;;eACN,MAAM;;;;;;;;;eAMN,MAAM;;;;iBACN,MAAM;;;;;;;;;;;;;eAON,MAAM;;;;;;;;;YAMN,MAAM;;;;QACN,MAAM;;;;eACN,MAAM;;;;kBACN,MAAM;;;;iBACN,MAAM;;;;kBACN,MAAM;;;;qBACN,MAAM,GAAC,IAAI;;;;iBACX,MAAM;;;;;;;;aAEN,aAAa;;;;;;;;;YAMb,MAAM;;;;mBACN,MAAM;;;;oBACN,MAAM;;;;;;;;;SAMN,MAAM;;;;YACN,MAAM;;;;gBACN,MAAM;;;;iBACN,MAAM,GAAC,IAAI;;;;UACX,MAAM;;;;cACN,MAAM;;;;iBACN,MAAM;;;;kBACN,MAAM;;;;yBACN,WAAW,EAAE;;;;;;;;aAEb,WAAW;;;;;;;;;UAMX,MAAM;;;;UACN,MAAM;;;;;;;;;iBAMN,MAAM;;;;eACN,MAAM;;;;iBACN,kBAAkB;;;;kBAClB,MAAM;;;;oBACN,MAAM;;;;iBACN,gBAAgB;;;;;;;;;SAMhB,MAAM;;;;gBACN,MAAM,GAAC,IAAI;;;;cACX,MAAO,IAAI;;;;;;;;;WAMX,OAAO;;;;cACP,OAAO;;;;WACP,MAAM;;;;cACN,MAAM;;;;eACN,iBAAiB,EAAE;;;;cACnB,aAAa;;;;iBACb,kBAAkB;;;;0BAClB,WAAW,EAAE;;;;iBACb,OAAO;;;;;;;;;UAMP,MAAM;;;;aACN,MAAM;;;;;;;;;YAMN,OAAO;;;;aACP,MAAM;;;;iBACN,MAAM;;;;kBACN,WAAW;;;;;;;;;YAMX,MAAM;;;;cACN,MAAM;;;;cACN,MAAM;;;;aACN,MAAM;;;;mBACN,MAAM;;;;qBACN,MAAM;;;;mBACN,WAAW,EAAE;;;;;;;;;YAMb,MAAM;;;;WACN,mBAAmB;;;;eACnB,qBAAqB;;;;eACrB,MAAM;;;;;;;;;oBAMN,MAAM;;;;iBACN,MAAM;;;;kBACN,MAAM;;;;cACN,MAAM;;;;UACN,MAAM;;;;iBACN,MAAM,GAAC,IAAI;;;;gBACX,MAAM,GAAC,IAAI;;;;SACX,MAAM;;;;SACN,MAAM;;;;SACN,MAAM;;;;yBACN,MAAM,GAAC,IAAI;;;;SACX,MAAM;;;;kBACN,kBAAkB,EAAE;;;;;;;;;;;;;SAOpB,MAAM;;;;iBACN,MAAM,GAAC,IAAI;;;;;;;;;eAMX,MAAM;;;;YACN,MAAM;;;;WACN,MAAM;;;;;;;;;YAMN,MAAM;;;;YACN,MAAM;;;;eACN,MAAM;;;;gBACN,MAAM;;;;iBACN,MAAM;;;;YACN,MAAM;;;;;;;;;YAMN,MAAM;;;;iBACN,MAAM;;;;aACN,aAAa;;;;;;;;;YAMb,MAAM;;;;YACN,MAAM;;;;iBACN,MAAM;;;;eACN,MAAM;;;;;mCAMT,GAAC,KACC,IAAI;;;;qCAMJ,IAAI;;;;;;;;YAMH,cAAc;;;;WACd,MAAM;;;;cACN,MAAM;;;;;;;;;UAMN,MAAM;;;;aACN,MAAM"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@licenseseat/js",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "Official JavaScript SDK for LicenseSeat – simple, secure software licensing.",
   "main": "dist/index.js",
   "module": "dist/index.js",

package/src/LicenseSeat.js

@@ -31,6 +31,13 @@ import {
   sleep,
   getCsrfToken,
 } from "./utils.js";
+import { collectTelemetry } from "./telemetry.js";
+
+/**
+ * SDK version constant
+ * @type {string}
+ */
+export const SDK_VERSION = "0.4.1";
 
 /**
  * Default configuration values
@@ -41,6 +48,7 @@ const DEFAULT_CONFIG = {
   productSlug: null, // Required: Product slug for API calls (e.g., "my-app")
   storagePrefix: "licenseseat_",
   autoValidateInterval: 3600000, // 1 hour
+  heartbeatInterval: 300000, // 5 minutes
   networkRecheckInterval: 30000, // 30 seconds
   maxRetries: 3,
   retryDelay: 1000,
@@ -51,6 +59,9 @@ const DEFAULT_CONFIG = {
   maxOfflineDays: 0, // 0 = disabled
   maxClockSkewMs: 5 * 60 * 1000, // 5 minutes
   autoInitialize: true,
+  telemetryEnabled: true, // Set false to disable telemetry (e.g. for GDPR compliance)
+  appVersion: null, // User-provided app version, sent as app_version in telemetry
+  appBuild: null, // User-provided app build, sent as app_build in telemetry
 };
 
 /**
@@ -104,6 +115,13 @@ export class LicenseSeatSDK {
      */
     this.validationTimer = null;
 
+    /**
+     * Heartbeat timer ID (separate from auto-validation)
+     * @type {ReturnType<typeof setInterval>|null}
+     * @private
+     */
+    this.heartbeatTimer = null;
+
     /**
      * License cache manager
      * @type {LicenseCache}
@@ -205,9 +223,10 @@ export class LicenseSeatSDK {
           .catch(() => {});
       }
 
-      // Start auto-validation if API key is configured
+      // Start auto-validation and heartbeat if API key is configured
       if (this.config.apiKey) {
         this.startAutoValidation(cachedLicense.license_key);
+        this.startHeartbeat();
 
         // Validate in background
         this.validateLicense(cachedLicense.license_key).catch((err) => {
@@ -278,6 +297,7 @@ export class LicenseSeatSDK {
       this.cache.setLicense(licenseData);
       this.cache.updateValidation({ valid: true, optimistic: true });
       this.startAutoValidation(licenseKey);
+      this.startHeartbeat();
       this.syncOfflineAssets();
       this.scheduleOfflineRefresh();
 
@@ -323,6 +343,7 @@ export class LicenseSeatSDK {
       this.cache.clearLicense();
       this.cache.clearOfflineToken();
       this.stopAutoValidation();
+      this.stopHeartbeat();
 
       this.emit("deactivation:success", response);
       return response;
@@ -527,8 +548,8 @@ export class LicenseSeatSDK {
         body.ttl_days = options.ttlDays;
       }
 
-      // New v1 API: POST /products/{slug}/licenses/{key}/offline-token
-      const path = `/products/${this.config.productSlug}/licenses/${encodeURIComponent(license.license_key)}/offline-token`;
+      // New v1 API: POST /products/{slug}/licenses/{key}/offline_token
+      const path = `/products/${this.config.productSlug}/licenses/${encodeURIComponent(license.license_key)}/offline_token`;
 
       const response = await this.apiCall(path, {
         method: "POST",
@@ -565,8 +586,8 @@ export class LicenseSeatSDK {
     }
     try {
       this.log(`Fetching signing key for kid: ${keyId}`);
-      // New v1 API: GET /signing-keys/{key_id}
-      const response = await this.apiCall(`/signing-keys/${encodeURIComponent(keyId)}`, {
+      // New v1 API: GET /signing_keys/{key_id}
+      const response = await this.apiCall(`/signing_keys/${encodeURIComponent(keyId)}`, {
         method: "GET",
       });
       if (response && response.public_key) {
@@ -684,11 +705,12 @@ export class LicenseSeatSDK {
   }
 
   /**
-   * Test server authentication
-   * Useful for verifying API key/session is valid.
-   * @returns {Promise<Object>} Result from the server
-   * @throws {ConfigurationError} When API key is not configured
-   * @throws {APIError} When authentication fails
+   * Test API connectivity
+   * Makes a request to the health endpoint to verify connectivity.
+   * Note: To fully verify API key validity, attempt an actual operation like activate() or validateLicense().
+   * @returns {Promise<{authenticated: boolean, healthy: boolean, api_version: string}>}
+   * @throws {ConfigurationError} If API key is not configured
+   * @throws {APIError} If the health check fails
    */
   async testAuth() {
     if (!this.config.apiKey) {
@@ -699,21 +721,61 @@ export class LicenseSeatSDK {
 
     try {
       this.emit("auth_test:start");
-      const response = await this.apiCall("/auth_test", { method: "GET" });
-      this.emit("auth_test:success", response);
-      return response;
+      // Use health endpoint to verify API connectivity
+      const response = await this.apiCall("/health", { method: "GET" });
+      const result = {
+        authenticated: true, // API key was included in request
+        healthy: response.status === "healthy",
+        api_version: response.api_version,
+      };
+      this.emit("auth_test:success", result);
+      return result;
     } catch (error) {
       this.emit("auth_test:error", { error });
       throw error;
     }
   }
 
+  /**
+   * Send a heartbeat for the current license.
+   * Heartbeats let the server know the device is still active.
+   * @returns {Promise<Object|undefined>} Heartbeat response, or undefined if no active license
+   * @throws {ConfigurationError} When productSlug is not configured
+   * @throws {APIError} When the API request fails
+   */
+  async heartbeat() {
+    if (!this.config.productSlug) {
+      throw new ConfigurationError("productSlug is required for heartbeat");
+    }
+
+    const cached = this.cache.getLicense();
+    if (!cached) {
+      this.log("No active license for heartbeat");
+      return;
+    }
+
+    const body = { device_id: cached.device_id };
+
+    const response = await this.apiCall(
+      `/products/${this.config.productSlug}/licenses/${encodeURIComponent(cached.license_key)}/heartbeat`,
+      {
+        method: "POST",
+        body: body,
+      }
+    );
+
+    this.emit("heartbeat:success", response);
+    this.log("Heartbeat sent successfully");
+    return response;
+  }
+
   /**
    * Clear all data and reset SDK state
    * @returns {void}
    */
   reset() {
     this.stopAutoValidation();
+    this.stopHeartbeat();
     this.stopConnectivityPolling();
     if (this.offlineRefreshTimer) {
       clearInterval(this.offlineRefreshTimer);
@@ -734,6 +796,7 @@ export class LicenseSeatSDK {
   destroy() {
     this.destroyed = true;
     this.stopAutoValidation();
+    this.stopHeartbeat();
     this.stopConnectivityPolling();
     if (this.offlineRefreshTimer) {
       clearInterval(this.offlineRefreshTimer);
@@ -814,11 +877,21 @@ export class LicenseSeatSDK {
     this.currentAutoLicenseKey = licenseKey;
     const validationInterval = this.config.autoValidateInterval;
 
+    // Don't start auto-validation if interval is 0 or negative
+    if (!validationInterval || validationInterval <= 0) {
+      this.log("Auto-validation disabled (interval:", validationInterval, ")");
+      return;
+    }
+
     const performAndReschedule = () => {
-      this.validateLicense(licenseKey).catch((err) => {
-        this.log("Auto-validation failed:", err);
-        this.emit("validation:auto-failed", { licenseKey, error: err });
-      });
+      this.validateLicense(licenseKey)
+        .then(() => {
+          this.heartbeat().catch((err) => this.log("Heartbeat failed:", err));
+        })
+        .catch((err) => {
+          this.log("Auto-validation failed:", err);
+          this.emit("validation:auto-failed", { licenseKey, error: err });
+        });
       this.emit("autovalidation:cycle", {
         nextRunAt: new Date(Date.now() + validationInterval),
       });
@@ -844,6 +917,42 @@ export class LicenseSeatSDK {
     }
   }
 
+  /**
+   * Start separate heartbeat timer
+   * Sends periodic heartbeats between auto-validation cycles.
+   * @returns {void}
+   * @private
+   */
+  startHeartbeat() {
+    this.stopHeartbeat();
+
+    const interval = this.config.heartbeatInterval;
+    if (!interval || interval <= 0) {
+      this.log("Heartbeat timer disabled (interval:", interval, ")");
+      return;
+    }
+
+    this.heartbeatTimer = setInterval(() => {
+      this.heartbeat()
+        .then(() => this.emit("heartbeat:cycle", { nextRunAt: new Date(Date.now() + interval) }))
+        .catch((err) => this.log("Heartbeat timer failed:", err));
+    }, interval);
+
+    this.log("Heartbeat timer started (interval:", interval, "ms)");
+  }
+
+  /**
+   * Stop the separate heartbeat timer
+   * @returns {void}
+   * @private
+   */
+  stopHeartbeat() {
+    if (this.heartbeatTimer) {
+      clearInterval(this.heartbeatTimer);
+      this.heartbeatTimer = null;
+    }
+  }
+
   /**
    * Start connectivity polling (when offline)
    * @returns {void}
@@ -855,10 +964,12 @@ export class LicenseSeatSDK {
     const healthCheck = async () => {
       try {
         // New v1 API: GET /health
-        await fetch(`${this.config.apiBaseUrl}/health`, {
+        const res = await fetch(`${this.config.apiBaseUrl}/health`, {
           method: "GET",
           credentials: "omit",
         });
+        // Consume the response body to release the connection
+        await res.text().catch(() => {});
 
         if (!this.online) {
           this.online = true;
@@ -897,10 +1008,10 @@ export class LicenseSeatSDK {
   // ============================================================
 
   /**
-   * Fetch and cache offline token and signing key
-   * Uses a lock to prevent concurrent calls from causing race conditions
+   * Download and cache the offline token and its corresponding public signing key.
+   * Emits `offlineToken:ready` on success. Safe to call multiple times — concurrent
+   * calls are deduplicated automatically.
    * @returns {Promise<void>}
-   * @private
    */
   async syncOfflineAssets() {
     // Prevent concurrent syncs
@@ -958,9 +1069,10 @@ export class LicenseSeatSDK {
   }
 
   /**
-   * Verify cached offline token
+   * Verify the cached offline token and return a validation result.
+   * Use this to validate the license when the device is offline.
+   * The offline token must have been previously downloaded via {@link syncOfflineAssets}.
    * @returns {Promise<import('./types.js').ValidationResult>}
-   * @private
    */
   async verifyCachedOffline() {
     const signed = this.cache.getOfflineToken();
@@ -1120,12 +1232,22 @@ export class LicenseSeatSDK {
       );
     }
 
+    // Inject telemetry into POST request bodies
+    const method = options.method || "GET";
+    let body = options.body;
+    if (method === "POST" && body && this.config.telemetryEnabled !== false) {
+      body = { ...body, telemetry: collectTelemetry(SDK_VERSION, {
+        appVersion: this.config.appVersion,
+        appBuild: this.config.appBuild,
+      }) };
+    }
+
     for (let attempt = 0; attempt <= this.config.maxRetries; attempt++) {
       try {
         const response = await fetch(url, {
-          method: options.method || "GET",
+          method: method,
           headers: headers,
-          body: options.body ? JSON.stringify(options.body) : undefined,
+          body: body ? JSON.stringify(body) : undefined,
           credentials: "omit",
         });
 

package/src/global.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Type augmentations for non-standard browser APIs used by the telemetry module.
+ * These APIs exist in Chromium-based browsers but are not part of the standard
+ * TypeScript DOM lib.
+ */
+
+interface NavigatorUABrandVersion {
+  brand: string;
+  version: string;
+}
+
+interface NavigatorUAData {
+  brands: NavigatorUABrandVersion[];
+  mobile: boolean;
+  platform: string;
+  architecture?: string;
+  model?: string;
+}
+
+interface Navigator {
+  userAgentData?: NavigatorUAData;
+  deviceMemory?: number;
+}

package/src/index.js

@@ -5,7 +5,7 @@
  * for apps, games, and plugins.
  *
  * @module @licenseseat/js
- * @version 0.2.0
+ * @version 0.4.1
  *
  * @example
  * ```js
@@ -13,6 +13,7 @@
  *
  * const sdk = new LicenseSeat({
  *   apiKey: 'your-api-key',
+ *   productSlug: 'your-product',  // Required: your product slug
  *   debug: true
  * });
  *
@@ -30,9 +31,10 @@
  * ```
  */
 
-// Re-export the main SDK class
+// Re-export the main SDK class and version
 export {
   LicenseSeatSDK,
+  SDK_VERSION,
   getSharedInstance,
   configure,
   resetSharedInstance,
@@ -57,6 +59,9 @@ export {
   getCsrfToken,
 } from "./utils.js";
 
+// Re-export telemetry collection (for advanced use cases)
+export { collectTelemetry } from "./telemetry.js";
+
 // Default export - the main SDK class
 import { LicenseSeatSDK } from "./LicenseSeat.js";
 export default LicenseSeatSDK;