@licenseseat/js 0.2.1 → 0.2.2

package/README.md

@@ -1,10 +1,10 @@
-# LicenseSeat JavaScript SDK
-
-Official JavaScript/TypeScript SDK for [LicenseSeat](https://licenseseat.com) – the simple, secure licensing platform for apps, games, and plugins.
+# LicenseSeat - JavaScript SDK
 
 [![CI](https://github.com/licenseseat/licenseseat-js/actions/workflows/ci.yml/badge.svg)](https://github.com/licenseseat/licenseseat-js/actions/workflows/ci.yml)
 [![npm version](https://img.shields.io/npm/v/@licenseseat/js.svg)](https://www.npmjs.com/package/@licenseseat/js)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+Official JavaScript/TypeScript SDK for [LicenseSeat](https://licenseseat.com) – the simple, secure licensing platform for apps, games, and plugins.
 
 ---
 
@@ -148,18 +148,18 @@ const sdk = new LicenseSeat({
 
 ### Configuration Options
 
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `apiKey` | `string` | `null` | API key for authentication (required for most operations) |
-| `apiBaseUrl` | `string` | `'https://licenseseat.com/api'` | API base URL |
-| `storagePrefix` | `string` | `'licenseseat_'` | Prefix for localStorage keys |
-| `autoValidateInterval` | `number` | `3600000` | Auto-validation interval in ms (1 hour) |
-| `autoInitialize` | `boolean` | `true` | Auto-initialize and validate cached license |
-| `offlineFallbackEnabled` | `boolean` | `false` | Enable offline validation on network errors |
-| `maxOfflineDays` | `number` | `0` | Maximum days license works offline (0 = disabled) |
-| `maxRetries` | `number` | `3` | Max retry attempts for failed API calls |
-| `retryDelay` | `number` | `1000` | Initial retry delay in ms (exponential backoff) |
-| `debug` | `boolean` | `false` | Enable debug logging to console |
+| Option                   | Type      | Default                         | Description                                               |
+| ------------------------ | --------- | ------------------------------- | --------------------------------------------------------- |
+| `apiKey`                 | `string`  | `null`                          | API key for authentication (required for most operations) |
+| `apiBaseUrl`             | `string`  | `'https://licenseseat.com/api'` | API base URL                                              |
+| `storagePrefix`          | `string`  | `'licenseseat_'`                | Prefix for localStorage keys                              |
+| `autoValidateInterval`   | `number`  | `3600000`                       | Auto-validation interval in ms (1 hour)                   |
+| `autoInitialize`         | `boolean` | `true`                          | Auto-initialize and validate cached license               |
+| `offlineFallbackEnabled` | `boolean` | `false`                         | Enable offline validation on network errors               |
+| `maxOfflineDays`         | `number`  | `0`                             | Maximum days license works offline (0 = disabled)         |
+| `maxRetries`             | `number`  | `3`                             | Max retry attempts for failed API calls                   |
+| `retryDelay`             | `number`  | `1000`                          | Initial retry delay in ms (exponential backoff)           |
+| `debug`                  | `boolean` | `false`                         | Enable debug logging to console                           |
 
 ---
 
@@ -339,42 +339,42 @@ sdk.off('activation:success', handler);
 
 ### Available Events
 
-| Event | Description | Data |
-|-------|-------------|------|
-| **Lifecycle** | | |
-| `license:loaded` | Cached license loaded on init | `CachedLicense` |
-| `sdk:reset` | SDK was reset | – |
-| `sdk:destroyed` | SDK was destroyed | – |
-| `sdk:error` | General SDK error | `{ message, error? }` |
-| **Activation** | | |
-| `activation:start` | Activation started | `{ licenseKey, deviceId }` |
-| `activation:success` | Activation succeeded | `CachedLicense` |
-| `activation:error` | Activation failed | `{ licenseKey, error }` |
-| **Deactivation** | | |
-| `deactivation:start` | Deactivation started | `CachedLicense` |
-| `deactivation:success` | Deactivation succeeded | `Object` |
-| `deactivation:error` | Deactivation failed | `{ error, license }` |
-| **Validation** | | |
-| `validation:start` | Validation started | `{ licenseKey }` |
-| `validation:success` | Online validation succeeded | `ValidationResult` |
-| `validation:failed` | Validation failed (invalid license) | `ValidationResult` |
-| `validation:error` | Validation error (network, etc.) | `{ licenseKey, error }` |
-| `validation:offline-success` | Offline validation succeeded | `ValidationResult` |
-| `validation:offline-failed` | Offline validation failed | `ValidationResult` |
-| `validation:auth-failed` | Auth failed during validation | `{ licenseKey, error, cached }` |
-| **Auto-Validation** | | |
-| `autovalidation:cycle` | Auto-validation scheduled | `{ nextRunAt: Date }` |
-| `autovalidation:stopped` | Auto-validation stopped | – |
-| **Network** | | |
-| `network:online` | Network connectivity restored | – |
-| `network:offline` | Network connectivity lost | `{ error }` |
-| **Offline License** | | |
-| `offlineLicense:fetching` | Fetching offline license | `{ licenseKey }` |
-| `offlineLicense:fetched` | Offline license fetched | `{ licenseKey, data }` |
-| `offlineLicense:fetchError` | Offline license fetch failed | `{ licenseKey, error }` |
-| `offlineLicense:ready` | Offline assets synced | `{ kid, exp_at }` |
-| `offlineLicense:verified` | Offline signature verified | `{ payload }` |
-| `offlineLicense:verificationFailed` | Offline signature invalid | `{ payload }` |
+| Event                               | Description                         | Data                            |
+| ----------------------------------- | ----------------------------------- | ------------------------------- |
+| **Lifecycle**                       |                                     |                                 |
+| `license:loaded`                    | Cached license loaded on init       | `CachedLicense`                 |
+| `sdk:reset`                         | SDK was reset                       | –                               |
+| `sdk:destroyed`                     | SDK was destroyed                   | –                               |
+| `sdk:error`                         | General SDK error                   | `{ message, error? }`           |
+| **Activation**                      |                                     |                                 |
+| `activation:start`                  | Activation started                  | `{ licenseKey, deviceId }`      |
+| `activation:success`                | Activation succeeded                | `CachedLicense`                 |
+| `activation:error`                  | Activation failed                   | `{ licenseKey, error }`         |
+| **Deactivation**                    |                                     |                                 |
+| `deactivation:start`                | Deactivation started                | `CachedLicense`                 |
+| `deactivation:success`              | Deactivation succeeded              | `Object`                        |
+| `deactivation:error`                | Deactivation failed                 | `{ error, license }`            |
+| **Validation**                      |                                     |                                 |
+| `validation:start`                  | Validation started                  | `{ licenseKey }`                |
+| `validation:success`                | Online validation succeeded         | `ValidationResult`              |
+| `validation:failed`                 | Validation failed (invalid license) | `ValidationResult`              |
+| `validation:error`                  | Validation error (network, etc.)    | `{ licenseKey, error }`         |
+| `validation:offline-success`        | Offline validation succeeded        | `ValidationResult`              |
+| `validation:offline-failed`         | Offline validation failed           | `ValidationResult`              |
+| `validation:auth-failed`            | Auth failed during validation       | `{ licenseKey, error, cached }` |
+| **Auto-Validation**                 |                                     |                                 |
+| `autovalidation:cycle`              | Auto-validation scheduled           | `{ nextRunAt: Date }`           |
+| `autovalidation:stopped`            | Auto-validation stopped             | –                               |
+| **Network**                         |                                     |                                 |
+| `network:online`                    | Network connectivity restored       | –                               |
+| `network:offline`                   | Network connectivity lost           | `{ error }`                     |
+| **Offline License**                 |                                     |                                 |
+| `offlineLicense:fetching`           | Fetching offline license            | `{ licenseKey }`                |
+| `offlineLicense:fetched`            | Offline license fetched             | `{ licenseKey, data }`          |
+| `offlineLicense:fetchError`         | Offline license fetch failed        | `{ licenseKey, error }`         |
+| `offlineLicense:ready`              | Offline assets synced               | `{ kid, exp_at }`               |
+| `offlineLicense:verified`           | Offline signature verified          | `{ payload }`                   |
+| `offlineLicense:verificationFailed` | Offline signature invalid           | `{ payload }`                   |
 
 ---
 
@@ -454,12 +454,12 @@ try {
 
 ### Error Types
 
-| Error | Description |
-|-------|-------------|
-| `APIError` | HTTP request failures (includes `status` and `data`) |
-| `LicenseError` | License operation failures (includes `code`) |
-| `ConfigurationError` | SDK misconfiguration |
-| `CryptoError` | Cryptographic operation failures |
+| Error                | Description                                          |
+| -------------------- | ---------------------------------------------------- |
+| `APIError`           | HTTP request failures (includes `status` and `data`) |
+| `LicenseError`       | License operation failures (includes `code`)         |
+| `ConfigurationError` | SDK misconfiguration                                 |
+| `CryptoError`        | Cryptographic operation failures                     |
 
 ---
 
@@ -561,17 +561,17 @@ npm install
 
 ### Scripts
 
-| Command | Description |
-|---------|-------------|
-| `npm run build` | Build JS bundle + TypeScript declarations |
-| `npm run build:js` | Build JavaScript bundle only |
-| `npm run build:types` | Generate TypeScript declarations |
-| `npm run build:iife` | Build global/IIFE bundle |
-| `npm run dev` | Watch mode for development |
-| `npm test` | Run tests |
-| `npm run test:watch` | Run tests in watch mode |
-| `npm run test:coverage` | Run tests with coverage report |
-| `npm run typecheck` | Type-check without emitting |
+| Command                 | Description                               |
+| ----------------------- | ----------------------------------------- |
+| `npm run build`         | Build JS bundle + TypeScript declarations |
+| `npm run build:js`      | Build JavaScript bundle only              |
+| `npm run build:types`   | Generate TypeScript declarations          |
+| `npm run build:iife`    | Build global/IIFE bundle                  |
+| `npm run dev`           | Watch mode for development                |
+| `npm test`              | Run tests                                 |
+| `npm run test:watch`    | Run tests in watch mode                   |
+| `npm run test:coverage` | Run tests with coverage report            |
+| `npm run typecheck`     | Type-check without emitting               |
 
 ### Project Structure
 
@@ -671,12 +671,12 @@ This ensures:
 
 Once published to npm, the package is automatically available on CDNs:
 
-| CDN | URL |
-|-----|-----|
-| **esm.sh** | `https://esm.sh/@licenseseat/js` |
-| **unpkg** | `https://unpkg.com/@licenseseat/js/dist/index.js` |
+| CDN          | URL                                                          |
+| ------------ | ------------------------------------------------------------ |
+| **esm.sh**   | `https://esm.sh/@licenseseat/js`                             |
+| **unpkg**    | `https://unpkg.com/@licenseseat/js/dist/index.js`            |
 | **jsDelivr** | `https://cdn.jsdelivr.net/npm/@licenseseat/js/dist/index.js` |
-| **Skypack** | `https://cdn.skypack.dev/@licenseseat/js` |
+| **Skypack**  | `https://cdn.skypack.dev/@licenseseat/js`                    |
 
 **Version pinning** (recommended for production):
 ```html
@@ -731,10 +731,10 @@ This project follows [Semantic Versioning](https://semver.org/):
 
 ### Breaking Changes in v0.2.0
 
-| Change | Before | After | Migration |
-|--------|--------|-------|-----------|
-| `apiBaseUrl` default | `/api` | `https://licenseseat.com/api` | Set `apiBaseUrl` explicitly if using a relative URL |
-| `offlineFallbackEnabled` default | `true` | `false` | Set `offlineFallbackEnabled: true` if you need offline fallback |
+| Change                           | Before | After                         | Migration                                                       |
+| -------------------------------- | ------ | ----------------------------- | --------------------------------------------------------------- |
+| `apiBaseUrl` default             | `/api` | `https://licenseseat.com/api` | Set `apiBaseUrl` explicitly if using a relative URL             |
+| `offlineFallbackEnabled` default | `true` | `false`                       | Set `offlineFallbackEnabled: true` if you need offline fallback |
 
 ### New Features in v0.2.0
 

package/dist/index.js

@@ -260,7 +260,14 @@ function base64UrlDecode(base64UrlString) {
   while (base64.length % 4) {
     base64 += "=";
   }
-  const raw = window.atob(base64);
+  let raw;
+  if (typeof atob === "function") {
+    raw = atob(base64);
+  } else if (typeof Buffer !== "undefined") {
+    raw = Buffer.from(base64, "base64").toString("binary");
+  } else {
+    throw new Error("No base64 decoder available (neither atob nor Buffer found)");
+  }
   const outputArray = new Uint8Array(raw.length);
   for (let i = 0; i < raw.length; ++i) {
     outputArray[i] = raw.charCodeAt(i);
@@ -289,6 +296,11 @@ function getCanvasFingerprint() {
   }
 }
 function generateDeviceId() {
+  if (typeof window === "undefined" || typeof navigator === "undefined") {
+    const os = typeof process !== "undefined" ? process.platform : "unknown";
+    const arch = typeof process !== "undefined" ? process.arch : "unknown";
+    return `node-${hashCode(os + "|" + arch)}`;
+  }
   const nav = window.navigator;
   const screen = window.screen;
   const data = [
@@ -300,7 +312,7 @@ function generateDeviceId() {
     nav.hardwareConcurrency,
     getCanvasFingerprint()
   ].join("|");
-  return `web-${hashCode(data)}-${Date.now().toString(36)}`;
+  return `web-${hashCode(data)}`;
 }
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
@@ -748,12 +760,12 @@ var LicenseSeatSDK = class {
    * Test server authentication
    * Useful for verifying API key/session is valid.
    * @returns {Promise<Object>} Result from the server
-   * @throws {Error} When API key is not configured
+   * @throws {ConfigurationError} When API key is not configured
    * @throws {APIError} When authentication fails
    */
   async testAuth() {
     if (!this.config.apiKey) {
-      const err = new Error("API key is required for auth test");
+      const err = new ConfigurationError("API key is required for auth test");
       this.emit("auth_test:error", { error: err });
       throw err;
     }

package/dist/types/LicenseSeat.d.ts

@@ -57,7 +57,7 @@ export class LicenseSeatSDK {
     private eventListeners;
     /**
      * Auto-validation timer ID
-     * @type {number|null}
+     * @type {ReturnType<typeof setInterval>|null}
      * @private
      */
     private validationTimer;
@@ -81,13 +81,13 @@ export class LicenseSeatSDK {
     private currentAutoLicenseKey;
     /**
      * Connectivity polling timer ID
-     * @type {number|null}
+     * @type {ReturnType<typeof setInterval>|null}
      * @private
      */
     private connectivityTimer;
     /**
      * Offline license refresh timer ID
-     * @type {number|null}
+     * @type {ReturnType<typeof setInterval>|null}
      * @private
      */
     private offlineRefreshTimer;
@@ -185,7 +185,7 @@ export class LicenseSeatSDK {
      * Test server authentication
      * Useful for verifying API key/session is valid.
      * @returns {Promise<Object>} Result from the server
-     * @throws {Error} When API key is not configured
+     * @throws {ConfigurationError} When API key is not configured
      * @throws {APIError} When authentication fails
      */
     testAuth(): Promise<any>;

package/dist/types/utils.d.ts

@@ -20,6 +20,7 @@ export function constantTimeEqual(a?: string, b?: string): boolean;
 export function canonicalJsonStringify(obj: any): string;
 /**
  * Decode a Base64URL string to a Uint8Array
+ * Works in both browser and Node.js environments.
  * @param {string} base64UrlString - The Base64URL encoded string
  * @returns {Uint8Array} Decoded bytes
  */
@@ -36,8 +37,9 @@ export function hashCode(str: string): string;
  */
 export function getCanvasFingerprint(): string;
 /**
- * Generate a unique device identifier based on browser characteristics
- * @returns {string} Unique device identifier
+ * Generate a stable device identifier based on browser characteristics.
+ * The ID is deterministic - same device will produce the same ID across calls.
+ * @returns {string} Stable device identifier
  */
 export function generateDeviceId(): string;
 /**

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

@@ -1 +1 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/utils.js"],"names":[],"mappings":"AAQA;;;;GAIG;AACH,wDAFa,OAAO,YAAY,EAAE,WAAW,EAAE,CAS9C;AAED;;;;;GAKG;AACH,sCAJW,MAAM,MACN,MAAM,GACJ,OAAO,CASnB;AAED;;;;;GAKG;AACH,kDAFa,MAAM,CAuBlB;AAED;;;;GAIG;AACH,iDAHW,MAAM,GACJ,UAAU,CAatB;AAED;;;;GAIG;AACH,8BAHW,MAAM,GACJ,MAAM,CAUlB;AAED;;;GAGG;AACH,wCAFa,MAAM,CAalB;AAED;;;GAGG;AACH,oCAFa,MAAM,CAgBlB;AAED;;;;GAIG;AACH,0BAHW,MAAM,GACJ,OAAO,CAAC,IAAI,CAAC,CAIzB;AAED;;;GAGG;AACH,gCAFa,MAAM,CAMlB"}
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/utils.js"],"names":[],"mappings":"AAQA;;;;GAIG;AACH,wDAFa,OAAO,YAAY,EAAE,WAAW,EAAE,CAS9C;AAED;;;;;GAKG;AACH,sCAJW,MAAM,MACN,MAAM,GACJ,OAAO,CASnB;AAED;;;;;GAKG;AACH,kDAFa,MAAM,CAuBlB;AAED;;;;;GAKG;AACH,iDAHW,MAAM,GACJ,UAAU,CA0BtB;AAED;;;;GAIG;AACH,8BAHW,MAAM,GACJ,MAAM,CAUlB;AAED;;;GAGG;AACH,wCAFa,MAAM,CAalB;AAED;;;;GAIG;AACH,oCAFa,MAAM,CAyBlB;AAED;;;;GAIG;AACH,0BAHW,MAAM,GACJ,OAAO,CAAC,IAAI,CAAC,CAIzB;AAED;;;GAGG;AACH,gCAFa,MAAM,CAMlB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@licenseseat/js",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Official JavaScript SDK for LicenseSeat – simple, secure software licensing.",
   "main": "dist/index.js",
   "module": "dist/index.js",
@@ -62,6 +62,7 @@
     "node": ">=18.0.0"
   },
   "devDependencies": {
+    "@types/node": "^25.0.9",
     "@vitest/coverage-v8": "^1.6.0",
     "esbuild": "^0.20.2",
     "jsdom": "^24.1.3",

package/src/LicenseSeat.js

@@ -21,7 +21,7 @@ import * as ed from "@noble/ed25519";
 import { sha512 } from "@noble/hashes/sha512";
 
 import { LicenseCache } from "./cache.js";
-import { APIError, LicenseError, CryptoError } from "./errors.js";
+import { APIError, ConfigurationError, LicenseError, CryptoError } from "./errors.js";
 import {
   parseActiveEntitlements,
   constantTimeEqual,
@@ -98,7 +98,7 @@ export class LicenseSeatSDK {
 
     /**
      * Auto-validation timer ID
-     * @type {number|null}
+     * @type {ReturnType<typeof setInterval>|null}
      * @private
      */
     this.validationTimer = null;
@@ -126,14 +126,14 @@ export class LicenseSeatSDK {
 
     /**
      * Connectivity polling timer ID
-     * @type {number|null}
+     * @type {ReturnType<typeof setInterval>|null}
      * @private
      */
     this.connectivityTimer = null;
 
     /**
      * Offline license refresh timer ID
-     * @type {number|null}
+     * @type {ReturnType<typeof setInterval>|null}
      * @private
      */
     this.offlineRefreshTimer = null;
@@ -637,12 +637,12 @@ export class LicenseSeatSDK {
    * Test server authentication
    * Useful for verifying API key/session is valid.
    * @returns {Promise<Object>} Result from the server
-   * @throws {Error} When API key is not configured
+   * @throws {ConfigurationError} When API key is not configured
    * @throws {APIError} When authentication fails
    */
   async testAuth() {
     if (!this.config.apiKey) {
-      const err = new Error("API key is required for auth test");
+      const err = new ConfigurationError("API key is required for auth test");
       this.emit("auth_test:error", { error: err });
       throw err;
     }

package/src/utils.js

@@ -66,6 +66,7 @@ export function canonicalJsonStringify(obj) {
 
 /**
  * Decode a Base64URL string to a Uint8Array
+ * Works in both browser and Node.js environments.
  * @param {string} base64UrlString - The Base64URL encoded string
  * @returns {Uint8Array} Decoded bytes
  */
@@ -74,7 +75,20 @@ export function base64UrlDecode(base64UrlString) {
   while (base64.length % 4) {
     base64 += "=";
   }
-  const raw = window.atob(base64);
+
+  // Cross-platform base64 decoding
+  /** @type {string} */
+  let raw;
+  if (typeof atob === "function") {
+    // Browser environment (or Node.js 16+ with global atob)
+    raw = atob(base64);
+  } else if (typeof Buffer !== "undefined") {
+    // Node.js environment
+    raw = Buffer.from(base64, "base64").toString("binary");
+  } else {
+    throw new Error("No base64 decoder available (neither atob nor Buffer found)");
+  }
+
   const outputArray = new Uint8Array(raw.length);
   for (let i = 0; i < raw.length; ++i) {
     outputArray[i] = raw.charCodeAt(i);
@@ -115,10 +129,19 @@ export function getCanvasFingerprint() {
 }
 
 /**
- * Generate a unique device identifier based on browser characteristics
- * @returns {string} Unique device identifier
+ * Generate a stable device identifier based on browser characteristics.
+ * The ID is deterministic - same device will produce the same ID across calls.
+ * @returns {string} Stable device identifier
  */
 export function generateDeviceId() {
+  // Check if we're in a browser environment
+  if (typeof window === "undefined" || typeof navigator === "undefined") {
+    // Node.js or non-browser environment - use a fallback
+    const os = typeof process !== "undefined" ? process.platform : "unknown";
+    const arch = typeof process !== "undefined" ? process.arch : "unknown";
+    return `node-${hashCode(os + "|" + arch)}`;
+  }
+
   const nav = window.navigator;
   const screen = window.screen;
   const data = [
@@ -131,7 +154,8 @@ export function generateDeviceId() {
     getCanvasFingerprint(),
   ].join("|");
 
-  return `web-${hashCode(data)}-${Date.now().toString(36)}`;
+  // Stable ID without timestamp - same device produces same ID
+  return `web-${hashCode(data)}`;
 }
 
 /**