@licenseseat/js 0.3.0 → 0.4.1

package/README.md

@@ -13,6 +13,8 @@ The official JavaScript/TypeScript SDK for [LicenseSeat](https://licenseseat.com
 - **License activation & deactivation** – Activate licenses with automatic device fingerprinting
 - **Online & offline validation** – Validate licenses with optional offline fallback
 - **Entitlement checking** – Check feature access with `hasEntitlement()` and `checkEntitlement()`
+- **Heartbeat** – Automatic periodic heartbeats to report device activity
+- **Telemetry** – Auto-collected device and environment data sent with each API request
 - **Local caching** – Secure localStorage-based caching with clock tamper detection
 - **Auto-retry with exponential backoff** – Resilient network handling
 - **Event-driven architecture** – Subscribe to SDK lifecycle events
@@ -138,6 +140,14 @@ const sdk = new LicenseSeat({
   autoValidateInterval: 3600000,              // 1 hour (in ms)
   autoInitialize: true,                       // Auto-validate cached license on init
 
+  // Heartbeat
+  heartbeatInterval: 300000,                  // 5 minutes (in ms), 0 to disable
+
+  // Telemetry
+  telemetryEnabled: true,                     // Set false to disable (e.g. GDPR)
+  appVersion: '1.2.0',                        // Your app version (sent in telemetry)
+  appBuild: '42',                             // Your app build number (sent in telemetry)
+
   // Offline Support
   offlineFallbackEnabled: false,              // Enable offline validation fallback
   maxOfflineDays: 0,                          // Max days offline (0 = disabled)
@@ -164,6 +174,10 @@ const sdk = new LicenseSeat({
 | `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               |
+| `heartbeatInterval`      | `number`  | `300000`                           | Heartbeat interval in ms (5 minutes). Set `0` to disable  |
+| `telemetryEnabled`       | `boolean` | `true`                             | Enable telemetry collection. Set `false` for GDPR compliance |
+| `appVersion`             | `string`  | `null`                             | Your app version string (sent as `app_version` in telemetry) |
+| `appBuild`               | `string`  | `null`                             | Your app build identifier (sent as `app_build` in telemetry) |
 | `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                   |
@@ -248,9 +262,11 @@ console.log(result);
 
 ### Entitlement Methods
 
+> **Note:** Entitlements are optional. A license may have zero entitlements if the associated plan has no entitlements configured. The `active_entitlements` array may be empty or the field may be undefined/null.
+
 #### `sdk.hasEntitlement(key)`
 
-Check if an entitlement is active. Returns a simple boolean.
+Check if an entitlement is active. Returns a simple boolean. Returns `false` if no entitlements exist.
 
 ```javascript
 if (sdk.hasEntitlement('pro')) {
@@ -308,17 +324,38 @@ console.log(status);
 
 #### `sdk.testAuth()`
 
-Test API authentication (useful for verifying API key).
+Test API connectivity by calling the `/health` endpoint. Returns health status and API version.
 
 ```javascript
 try {
   const result = await sdk.testAuth();
-  console.log('Authenticated:', result.authenticated);
+  console.log('Authenticated:', result.authenticated);  // Always true if request succeeds
+  console.log('Healthy:', result.healthy);              // API health status
+  console.log('API Version:', result.api_version);      // e.g., '1.0.0'
 } catch (error) {
-  console.error('Auth failed:', error);
+  console.error('Connection failed:', error);
 }
 ```
 
+> **Note:** This method tests API connectivity, not API key validity. A successful response means the API is reachable. Authentication errors will surface when calling protected endpoints like `activate()` or `validateLicense()`.
+
+#### `sdk.heartbeat()`
+
+Send a heartbeat to report that the current device is still active. Heartbeats are sent automatically at the configured `heartbeatInterval`, but you can also send one manually.
+
+```javascript
+try {
+  const result = await sdk.heartbeat();
+  console.log('Heartbeat received at:', result.received_at);
+} catch (error) {
+  console.error('Heartbeat failed:', error);
+}
+```
+
+Returns `undefined` if no active license is cached. When auto-heartbeat is enabled (the default), the SDK sends heartbeats every 5 minutes while a license is active. Auto-heartbeat starts automatically after `activate()` or when the SDK initializes with a cached license.
+
+To disable auto-heartbeat, set `heartbeatInterval: 0` in the configuration.
+
 #### `sdk.reset()`
 
 Clear all cached data and reset SDK state.
@@ -397,6 +434,9 @@ sdk.off('activation:success', handler);
 | **Auto-Validation**                 |                                     |                                 |
 | `autovalidation:cycle`              | Auto-validation scheduled           | `{ nextRunAt: Date }`           |
 | `autovalidation:stopped`            | Auto-validation stopped             | –                               |
+| **Heartbeat**                       |                                     |                                 |
+| `heartbeat:success`                 | Heartbeat acknowledged by server    | `HeartbeatResponse`             |
+| `heartbeat:cycle`                   | Auto-heartbeat tick completed       | `{ nextRunAt: Date }`           |
 | **Network**                         |                                     |                                 |
 | `network:online`                    | Network connectivity restored       | –                               |
 | `network:offline`                   | Network connectivity lost           | `{ error }`                     |
@@ -465,6 +505,70 @@ if (result.offline) {
 3. When offline, the SDK verifies the signature locally
 4. Clock tamper detection prevents users from bypassing expiration
 
+### Offline Methods
+
+#### `sdk.syncOfflineAssets()`
+
+Fetches the offline token and signing key from the server. Uses the currently cached license. Call this after activation to prepare for offline usage.
+
+```javascript
+// First activate (caches the license)
+await sdk.activate('LICENSE-KEY');
+
+// Then sync offline assets (uses cached license)
+const assets = await sdk.syncOfflineAssets();
+console.log('Offline token key ID:', assets.kid);
+console.log('Expires at:', assets.exp_at);
+```
+
+#### `sdk.getOfflineToken()`
+
+Fetches a signed offline token for the currently cached license. Returns the token structure containing the license data and Ed25519 signature.
+
+```javascript
+// Must have an active license cached first
+const token = await sdk.getOfflineToken();
+console.log(token);
+// {
+//   object: 'offline_token',
+//   token: { license_key, product_slug, plan_key, ... },
+//   signature: { algorithm: 'Ed25519', key_id, value },
+//   canonical: '...'
+// }
+```
+
+#### `sdk.getSigningKey(keyId)`
+
+Fetches the Ed25519 public key used for verifying offline token signatures.
+
+```javascript
+const signingKey = await sdk.getSigningKey('key-id-001');
+console.log(signingKey);
+// {
+//   object: 'signing_key',
+//   kid: 'key-id-001',
+//   public_key: 'base64-encoded-public-key',
+//   algorithm: 'Ed25519',
+//   created_at: '2024-01-01T00:00:00Z'
+// }
+```
+
+#### `sdk.verifyOfflineToken(token, publicKeyB64)`
+
+Verifies an offline token's Ed25519 signature locally. **Both parameters are required.**
+
+```javascript
+// Fetch the token and signing key first
+const token = await sdk.getOfflineToken();
+const signingKey = await sdk.getSigningKey(token.signature.key_id);
+
+// Verify the signature
+const isValid = await sdk.verifyOfflineToken(token, signingKey.public_key);
+console.log('Signature valid:', isValid);
+```
+
+> **Important:** The `verifyOfflineToken()` method requires you to pass both the token and the public key. Fetch the signing key using `getSigningKey()` with the `key_id` from the token's signature.
+
 ### Offline Token Structure
 
 ```javascript
@@ -498,6 +602,126 @@ if (result.offline) {
 
 ---
 
+## Telemetry
+
+The SDK automatically collects non-PII (non-personally-identifiable) device and environment data and includes it with every POST request sent to the LicenseSeat API. This data helps you understand what platforms and environments your customers use.
+
+Telemetry is **enabled by default** and can be disabled at any time.
+
+### Collected Fields
+
+| Field                | Type     | Example                | Description                                      |
+| -------------------- | -------- | ---------------------- | ------------------------------------------------ |
+| `sdk_name`           | `string` | `"js"`                 | Always `"js"` for this SDK                       |
+| `sdk_version`        | `string` | `"0.4.0"`              | SDK version                                      |
+| `os_name`            | `string` | `"macOS"`              | Operating system name                            |
+| `os_version`         | `string` | `"14.2.1"`             | Operating system version                         |
+| `platform`           | `string` | `"browser"`            | Runtime platform (`browser`, `node`, `electron`, `react-native`, `deno`, `bun`) |
+| `device_model`       | `string` | `null`                 | Device model (Chromium userAgentData only)        |
+| `device_type`        | `string` | `"desktop"`            | Device type (`desktop`, `phone`, `tablet`, `server`) |
+| `locale`             | `string` | `"en-US"`              | Full locale string                               |
+| `timezone`           | `string` | `"America/New_York"`   | IANA timezone                                    |
+| `language`           | `string` | `"en"`                 | 2-letter language code                           |
+| `architecture`       | `string` | `"arm64"`              | CPU architecture                                 |
+| `cpu_cores`          | `number` | `10`                   | Number of logical CPU cores                      |
+| `memory_gb`          | `number` | `16`                   | Approximate RAM in GB (Chrome/Node.js only)      |
+| `screen_resolution`  | `string` | `"1920x1080"`          | Screen resolution                                |
+| `display_scale`      | `number` | `2`                    | Device pixel ratio                               |
+| `browser_name`       | `string` | `"Chrome"`             | Browser name (browser environments only)         |
+| `browser_version`    | `string` | `"123.0"`              | Browser version (browser environments only)      |
+| `runtime_version`    | `string` | `"20.11.0"`            | Runtime version (Node.js, Deno, Bun, Electron)   |
+| `app_version`        | `string` | `"1.2.0"`              | Your app version (from `appVersion` config)      |
+| `app_build`          | `string` | `"42"`                 | Your app build (from `appBuild` config)          |
+
+Fields that cannot be detected in the current environment are omitted (not sent as `null`).
+
+### Providing App Version
+
+Pass your own app version and build number via configuration so they appear in telemetry:
+
+```javascript
+const sdk = new LicenseSeat({
+  apiKey: 'your-key',
+  productSlug: 'your-product',
+  appVersion: '1.2.0',
+  appBuild: '42'
+});
+```
+
+### Disabling Telemetry
+
+To disable telemetry collection entirely (for example, to comply with GDPR or other privacy regulations):
+
+```javascript
+const sdk = new LicenseSeat({
+  apiKey: 'your-key',
+  productSlug: 'your-product',
+  telemetryEnabled: false
+});
+```
+
+When telemetry is disabled, no device or environment data is attached to API requests.
+
+### Privacy
+
+Telemetry collects only non-personally-identifiable information. No IP addresses, user names, email addresses, or other PII are collected by the SDK. The data is used solely to help you understand the platforms and environments where your software is used.
+
+Telemetry is opt-out: set `telemetryEnabled: false` to disable it completely.
+
+---
+
+## Heartbeat
+
+The SDK sends periodic heartbeat signals to let the server know a device is still actively using the license. This enables usage analytics and helps detect inactive seats.
+
+### How It Works
+
+- After a license is activated (or when the SDK initializes with a cached license), a heartbeat timer starts automatically.
+- The default interval is **5 minutes** (`300000` ms), configurable via `heartbeatInterval`.
+- Each heartbeat sends the current `device_id` to the server.
+- Heartbeats also run alongside auto-validation cycles.
+
+### Manual Heartbeat
+
+You can send a heartbeat at any time:
+
+```javascript
+await sdk.heartbeat();
+```
+
+### Configuring the Interval
+
+```javascript
+const sdk = new LicenseSeat({
+  apiKey: 'your-key',
+  productSlug: 'your-product',
+  heartbeatInterval: 600000  // 10 minutes
+});
+```
+
+Set `heartbeatInterval: 0` to disable auto-heartbeat entirely. You can still call `sdk.heartbeat()` manually.
+
+### Heartbeat Events
+
+| Event               | Description                        | Data                    |
+| -------------------- | ---------------------------------- | ----------------------- |
+| `heartbeat:success`  | Heartbeat acknowledged by server   | `HeartbeatResponse`     |
+| `heartbeat:cycle`    | Auto-heartbeat tick completed      | `{ nextRunAt: Date }`   |
+
+```javascript
+sdk.on('heartbeat:success', (data) => {
+  console.log('Heartbeat received at:', data.received_at);
+});
+```
+
+### Heartbeat Lifecycle
+
+- **Starts** automatically after `sdk.activate()` succeeds, or on SDK init if a cached license exists.
+- **Stops** automatically when `sdk.deactivate()`, `sdk.reset()`, or `sdk.destroy()` is called.
+- Heartbeat failures are logged (in debug mode) but do not throw or interrupt the SDK.
+
+---
+
 ## Error Handling
 
 The SDK exports custom error classes for precise error handling:
@@ -564,7 +788,39 @@ Common error codes:
 
 - **Modern browsers**: Chrome 80+, Firefox 75+, Safari 14+, Edge 80+
 - **Bundlers**: Vite, Webpack, Rollup, esbuild, Parcel
-- **Node.js**: 18+ (requires polyfills for `localStorage`, `document`)
+- **Node.js**: 18+ (requires polyfills - see below)
+
+### Node.js Usage
+
+The SDK is designed for browsers but works in Node.js with polyfills. Add these before importing the SDK:
+
+```javascript
+// Required polyfills for Node.js
+const storage = {};
+globalThis.localStorage = {
+  getItem(key) { return Object.prototype.hasOwnProperty.call(storage, key) ? storage[key] : null; },
+  setItem(key, value) { storage[key] = String(value); },
+  removeItem(key) { delete storage[key]; },
+  clear() { for (const key in storage) delete storage[key]; },
+};
+
+// Override Object.keys to support localStorage iteration (used by cache.getAllKeys())
+const originalKeys = Object.keys;
+Object.keys = function(obj) {
+  if (obj === globalThis.localStorage) return originalKeys(storage);
+  return originalKeys(obj);
+};
+
+// Device fingerprinting polyfills (provides stable fallback values)
+globalThis.document = { createElement: () => ({ getContext: () => null }), querySelector: () => null };
+globalThis.window = { navigator: {}, screen: {} };
+globalThis.navigator = { userAgent: 'Node.js', language: 'en', hardwareConcurrency: 4 };
+
+// Now import the SDK
+const { default: LicenseSeat } = await import('@licenseseat/js');
+```
+
+> **Note:** In Node.js, device fingerprinting will use fallback values since browser APIs aren't available. For consistent device identification across restarts, pass an explicit `deviceId` to `activate()`.
 
 ---
 
@@ -680,6 +936,50 @@ npm install
 | `npm run test:coverage` | Run tests with coverage report            |
 | `npm run typecheck`     | Type-check without emitting               |
 
+### Integration Tests
+
+The SDK includes comprehensive integration tests that run against the live LicenseSeat API. These tests verify real-world functionality including activation, validation, deactivation, and offline cryptographic operations.
+
+#### Running Integration Tests (Node.js)
+
+```bash
+# Set environment variables
+export LICENSESEAT_API_KEY="ls_your_api_key_here"
+export LICENSESEAT_PRODUCT_SLUG="your-product"
+export LICENSESEAT_LICENSE_KEY="YOUR-LICENSE-KEY"
+
+# Run the tests
+node test-live.mjs
+```
+
+Or with inline environment variables:
+
+```bash
+LICENSESEAT_API_KEY=ls_xxx LICENSESEAT_PRODUCT_SLUG=my-app LICENSESEAT_LICENSE_KEY=XXX-XXX node test-live.mjs
+```
+
+#### Running Integration Tests (Browser)
+
+Open `test-live.html` in a browser. You'll be prompted to enter your credentials:
+
+1. **API Key** - Your LicenseSeat API key (starts with `ls_`)
+2. **Product Slug** - Your product identifier
+3. **License Key** - A valid license key for testing
+
+Credentials are stored in `localStorage` for convenience during development.
+
+#### What the Integration Tests Cover
+
+| Category | Tests |
+|----------|-------|
+| **Initialization** | SDK setup, configuration defaults |
+| **Activation** | License activation, device ID generation |
+| **Validation** | Online validation, entitlement checking |
+| **Deactivation** | License deactivation, cache clearing |
+| **Offline Crypto** | Ed25519 signature verification, offline token fetching, tamper detection |
+| **Error Handling** | Invalid licenses, missing config |
+| **Singleton** | Shared instance pattern |
+
 ### Project Structure
 
 ```
@@ -687,15 +987,18 @@ licenseseat-js/
 ├── src/
 │   ├── index.js          # Entry point, exports
 │   ├── LicenseSeat.js    # Main SDK class
+│   ├── telemetry.js      # Telemetry collection (device/environment data)
 │   ├── cache.js          # LicenseCache (localStorage)
 │   ├── errors.js         # Error classes
 │   ├── types.js          # JSDoc type definitions
 │   └── utils.js          # Utility functions
-├── tests/
+├── tests/                # Unit tests (mocked API)
 │   ├── setup.js          # Test setup
 │   ├── mocks/            # MSW handlers
 │   ├── LicenseSeat.test.js
 │   └── utils.test.js
+├── test-live.mjs         # Integration tests (Node.js)
+├── test-live.html        # Integration tests (Browser)
 ├── dist/                 # Build output
 │   ├── index.js          # ESM bundle
 │   └── types/            # TypeScript declarations
@@ -788,7 +1091,7 @@ Once published to npm, the package is automatically available on CDNs:
 **Version pinning** (recommended for production):
 ```html
 <script type="module">
-  import LicenseSeat from 'https://esm.sh/@licenseseat/js@0.3.0';
+  import LicenseSeat from 'https://esm.sh/@licenseseat/js@0.4.0';
 </script>
 ```
 
@@ -907,8 +1210,8 @@ This version introduces the v1 API with significant changes:
    await sdk.getOfflineLicense(key);
    await sdk.getPublicKey(keyId);
 
-   // After
-   await sdk.getOfflineToken(key);
+   // After (note: getOfflineToken uses cached license, no parameter needed)
+   await sdk.getOfflineToken();
    await sdk.getSigningKey(keyId);
    ```