@licenseseat/js 0.2.2 → 0.3.0

package/src/cache.js

@@ -62,12 +62,12 @@ export class LicenseCache {
   }
 
   /**
-   * Get the device identifier from the cached license
-   * @returns {string|null} Device identifier or null if not found
+   * Get the device ID from the cached license
+   * @returns {string|null} Device ID or null if not found
    */
   getDeviceId() {
     const license = this.getLicense();
-    return license ? license.device_identifier : null;
+    return license ? license.device_id : null;
   }
 
   /**
@@ -79,41 +79,41 @@ export class LicenseCache {
   }
 
   /**
-   * Get the cached offline license
-   * @returns {import('./types.js').SignedOfflineLicense|null} Offline license or null if not found
+   * Get the cached offline token
+   * @returns {import('./types.js').OfflineToken|null} Offline token or null if not found
    */
-  getOfflineLicense() {
+  getOfflineToken() {
     try {
-      const data = localStorage.getItem(this.prefix + "offline_license");
+      const data = localStorage.getItem(this.prefix + "offline_token");
       return data ? JSON.parse(data) : null;
     } catch (e) {
-      console.error("Failed to read offline license cache:", e);
+      console.error("Failed to read offline token cache:", e);
       return null;
     }
   }
 
   /**
-   * Store offline license data in cache
-   * @param {import('./types.js').SignedOfflineLicense} data - Signed offline license to cache
+   * Store offline token data in cache
+   * @param {import('./types.js').OfflineToken} data - Offline token to cache
    * @returns {void}
    */
-  setOfflineLicense(data) {
+  setOfflineToken(data) {
     try {
       localStorage.setItem(
-        this.prefix + "offline_license",
+        this.prefix + "offline_token",
         JSON.stringify(data)
       );
     } catch (e) {
-      console.error("Failed to cache offline license:", e);
+      console.error("Failed to cache offline token:", e);
     }
   }
 
   /**
-   * Clear the cached offline license
+   * Clear the cached offline token
    * @returns {void}
    */
-  clearOfflineLicense() {
-    localStorage.removeItem(this.prefix + "offline_license");
+  clearOfflineToken() {
+    localStorage.removeItem(this.prefix + "offline_token");
   }
 
   /**
@@ -161,8 +161,6 @@ export class LicenseCache {
         localStorage.removeItem(key);
       }
     });
-    this.clearOfflineLicense();
-    localStorage.removeItem(this.prefix + "last_seen_ts");
   }
 
   /**

package/src/types.js

@@ -7,7 +7,8 @@
 /**
  * SDK Configuration options
  * @typedef {Object} LicenseSeatConfig
- * @property {string} [apiBaseUrl="https://licenseseat.com/api"] - Base URL for the LicenseSeat API
+ * @property {string} [apiBaseUrl="https://licenseseat.com/api/v1"] - Base URL for the LicenseSeat API
+ * @property {string} [productSlug] - Product slug (required for API calls, e.g., "my-app")
  * @property {string} [apiKey] - API key for authentication (required for most operations)
  * @property {string} [storagePrefix="licenseseat_"] - Prefix for localStorage keys
  * @property {number} [autoValidateInterval=3600000] - Interval in ms for automatic license validation (default: 1 hour)
@@ -15,7 +16,7 @@
  * @property {number} [maxRetries=3] - Maximum number of retry attempts for failed API calls
  * @property {number} [retryDelay=1000] - Initial delay in ms between retries (exponential backoff applied)
  * @property {boolean} [debug=false] - Enable debug logging to console
- * @property {number} [offlineLicenseRefreshInterval=259200000] - Interval in ms to refresh offline license (default: 72 hours)
+ * @property {number} [offlineLicenseRefreshInterval=259200000] - Interval in ms to refresh offline token (default: 72 hours)
  * @property {boolean} [offlineFallbackEnabled=false] - Enable offline validation fallback on network errors
  * @property {number} [maxOfflineDays=0] - Maximum days a license can be used offline (0 = disabled)
  * @property {number} [maxClockSkewMs=300000] - Maximum allowed clock skew in ms for offline validation (default: 5 minutes)
@@ -25,33 +26,68 @@
 /**
  * License activation options
  * @typedef {Object} ActivationOptions
- * @property {string} [deviceIdentifier] - Custom device identifier (auto-generated if not provided)
- * @property {string} [softwareReleaseDate] - ISO8601 date string for version-aware activation
+ * @property {string} [deviceId] - Custom device ID (auto-generated if not provided)
+ * @property {string} [deviceName] - Human-readable device name (e.g., "John's MacBook Pro")
  * @property {Object} [metadata] - Additional metadata to include with the activation
  */
 
 /**
  * License validation options
  * @typedef {Object} ValidationOptions
- * @property {string} [deviceIdentifier] - Device identifier to validate against
- * @property {string} [productSlug] - Product slug for product-specific validation
+ * @property {string} [deviceId] - Device ID to validate against (required for hardware_locked mode)
  */
 
 /**
  * Activation response from the API
  * @typedef {Object} ActivationResponse
- * @property {string} id - Activation ID
+ * @property {string} object - Object type ("activation")
+ * @property {number} id - Activation ID
+ * @property {string} device_id - Device ID used for activation
+ * @property {string} [device_name] - Human-readable device name
  * @property {string} license_key - The activated license key
- * @property {string} device_identifier - Device identifier used for activation
  * @property {string} activated_at - ISO8601 timestamp of activation
+ * @property {string|null} [deactivated_at] - ISO8601 timestamp of deactivation (null if active)
+ * @property {string} [ip_address] - IP address of activation request
  * @property {Object} [metadata] - Additional metadata
+ * @property {LicenseObject} license - The license object
+ */
+
+/**
+ * Deactivation response from the API
+ * @typedef {Object} DeactivationResponse
+ * @property {string} object - Object type ("deactivation")
+ * @property {number} activation_id - The deactivated activation ID
+ * @property {string} deactivated_at - ISO8601 timestamp of deactivation
+ */
+
+/**
+ * License object from API responses
+ * @typedef {Object} LicenseObject
+ * @property {string} key - The license key
+ * @property {string} status - License status ("active", "revoked", "suspended", etc.)
+ * @property {string} [starts_at] - ISO8601 start timestamp
+ * @property {string|null} [expires_at] - ISO8601 expiration timestamp (null for perpetual)
+ * @property {string} mode - License mode ("hardware_locked", "floating", "named_user")
+ * @property {string} plan_key - License plan key
+ * @property {number} [seat_limit] - Maximum allowed seats
+ * @property {number} active_seats - Currently active seats
+ * @property {Entitlement[]} active_entitlements - List of active entitlements
+ * @property {Object} [metadata] - Additional metadata
+ * @property {ProductInfo} product - Product information
+ */
+
+/**
+ * Product information
+ * @typedef {Object} ProductInfo
+ * @property {string} slug - Product slug
+ * @property {string} name - Product display name
  */
 
 /**
  * Cached license data
  * @typedef {Object} CachedLicense
  * @property {string} license_key - The license key
- * @property {string} device_identifier - Device identifier
+ * @property {string} device_id - Device ID
  * @property {ActivationResponse} [activation] - Original activation response
  * @property {string} activated_at - ISO8601 timestamp of activation
  * @property {string} last_validated - ISO8601 timestamp of last validation
@@ -60,10 +96,9 @@
 
 /**
  * Entitlement object
- * Note: API returns only key, expires_at, and metadata. Name/description are not provided.
  * @typedef {Object} Entitlement
  * @property {string} key - Unique entitlement key
- * @property {string|null} expires_at - ISO8601 expiration timestamp
+ * @property {string|null} expires_at - ISO8601 expiration timestamp (null for perpetual)
  * @property {Object|null} metadata - Additional metadata
  */
 
@@ -72,12 +107,22 @@
  * @typedef {Object} ValidationResult
  * @property {boolean} valid - Whether the license is valid
  * @property {boolean} [offline] - Whether this was an offline validation
- * @property {string} [reason] - Reason for invalid status (online)
- * @property {string} [reason_code] - Machine-readable reason code (offline)
+ * @property {string} [code] - Machine-readable reason code (when invalid)
+ * @property {string} [message] - Human-readable message (when invalid)
+ * @property {ValidationWarning[]} [warnings] - Non-fatal warnings (e.g., expiring soon)
+ * @property {LicenseObject} [license] - The license object (online validation)
+ * @property {ActivationResponse} [activation] - The activation object (if device_id provided)
  * @property {Entitlement[]} [active_entitlements] - List of active entitlements
  * @property {boolean} [optimistic] - Whether this is an optimistic validation (pending server confirmation)
  */
 
+/**
+ * Validation warning
+ * @typedef {Object} ValidationWarning
+ * @property {string} code - Warning code (e.g., "license_expiring_soon")
+ * @property {string} message - Human-readable warning message
+ */
+
 /**
  * Entitlement check result
  * @typedef {Object} EntitlementCheckResult
@@ -93,33 +138,73 @@
  * @property {string} status - Status string ("inactive" | "pending" | "invalid" | "offline-invalid" | "offline-valid" | "active")
  * @property {string} [message] - Human-readable status message
  * @property {string} [license] - License key (if active)
- * @property {string} [device] - Device identifier (if active)
+ * @property {string} [device] - Device ID (if active)
  * @property {string} [activated_at] - ISO8601 activation timestamp
  * @property {string} [last_validated] - ISO8601 last validation timestamp
  * @property {Entitlement[]} [entitlements] - List of active entitlements
  */
 
 /**
- * Offline license payload
- * @typedef {Object} OfflineLicensePayload
- * @property {number} [v] - Payload version (currently 1)
- * @property {string} [lic_k] - License key
- * @property {string} [prod_s] - Product slug
- * @property {string} [plan_k] - License plan key
- * @property {string|null} [exp_at] - ISO8601 expiration timestamp (null for perpetual)
- * @property {number|null} [sl] - Seat limit (null for unlimited)
- * @property {string} [kid] - Key ID for public key lookup
- * @property {Array<{key: string, expires_at: string|null, metadata: Object|null}>} [active_ents] - Active entitlements
- * @property {Array<{key: string, expires_at: string|null, metadata: Object|null}>} [active_entitlements] - Active entitlements (alternative key)
+ * Offline token data (new v1 format)
+ * @typedef {Object} OfflineToken
+ * @property {string} object - Object type ("offline_token")
+ * @property {OfflineTokenPayload} token - The token payload
+ * @property {OfflineTokenSignature} signature - Signature information
+ * @property {string} canonical - Canonical JSON string that was signed
+ */
+
+/**
+ * Offline token payload
+ * @typedef {Object} OfflineTokenPayload
+ * @property {number} schema_version - Token schema version (currently 1)
+ * @property {string} license_key - License key
+ * @property {string} product_slug - Product slug
+ * @property {string} plan_key - License plan key
+ * @property {string} mode - License mode ("hardware_locked", "floating", "named_user")
+ * @property {number|null} [seat_limit] - Seat limit (null for unlimited)
+ * @property {string|null} [device_id] - Device ID (required for hardware_locked mode)
+ * @property {number} iat - Issued at (Unix timestamp in seconds)
+ * @property {number} exp - Expires at (Unix timestamp in seconds)
+ * @property {number} nbf - Not before (Unix timestamp in seconds)
+ * @property {number|null} [license_expires_at] - License expiration (Unix timestamp in seconds, null for perpetual)
+ * @property {string} kid - Key ID for signature verification
+ * @property {OfflineEntitlement[]} entitlements - Active entitlements
  * @property {Object} [metadata] - Additional metadata
  */
 
 /**
- * Signed offline license data
- * @typedef {Object} SignedOfflineLicense
- * @property {OfflineLicensePayload} payload - The license payload
- * @property {string} signature_b64u - Base64URL-encoded Ed25519 signature
- * @property {string} [kid] - Key ID for public key lookup
+ * Offline token entitlement
+ * @typedef {Object} OfflineEntitlement
+ * @property {string} key - Entitlement key
+ * @property {number|null} [expires_at] - Expiration (Unix timestamp in seconds)
+ */
+
+/**
+ * Offline token signature
+ * @typedef {Object} OfflineTokenSignature
+ * @property {string} algorithm - Signature algorithm (e.g., "Ed25519")
+ * @property {string} key_id - Key ID for public key lookup
+ * @property {string} value - Base64URL-encoded signature value
+ */
+
+/**
+ * Signing key response from API
+ * @typedef {Object} SigningKey
+ * @property {string} object - Object type ("signing_key")
+ * @property {string} key_id - Key ID
+ * @property {string} algorithm - Algorithm (e.g., "Ed25519")
+ * @property {string} public_key - Base64-encoded public key
+ * @property {string} [created_at] - ISO8601 creation timestamp
+ * @property {string} status - Key status ("active", "revoked")
+ */
+
+/**
+ * Health check response
+ * @typedef {Object} HealthResponse
+ * @property {string} object - Object type ("health")
+ * @property {string} status - Health status ("healthy")
+ * @property {string} api_version - API version string
+ * @property {string} timestamp - ISO8601 timestamp
  */
 
 /**
@@ -136,11 +221,18 @@
  */
 
 /**
- * API Error data
+ * API Error data (new format)
  * @typedef {Object} APIErrorData
- * @property {string} [error] - Error message
- * @property {string} [reason_code] - Machine-readable reason code (e.g., "license_not_found", "expired", "revoked")
- * @property {string} [code] - Legacy error code (deprecated, use reason_code)
+ * @property {APIErrorObject} [error] - Error object (new format)
+ * @property {string} [code] - Machine-readable error code (fallback)
+ * @property {string} [message] - Human-readable error message (fallback)
+ */
+
+/**
+ * API Error object
+ * @typedef {Object} APIErrorObject
+ * @property {string} code - Machine-readable error code
+ * @property {string} message - Human-readable error message
  * @property {Object} [details] - Additional error details
  */
 

package/src/utils.js

@@ -8,11 +8,12 @@ import CJSON from "canonical-json";
 
 /**
  * Parse active entitlements from a raw API payload into a consistent shape
- * @param {Object} [payload={}] - Raw payload from API or offline license
+ * @param {Object} [payload={}] - Raw payload from API or offline token
  * @returns {import('./types.js').Entitlement[]} Normalized entitlements array
  */
 export function parseActiveEntitlements(payload = {}) {
-  const raw = payload.active_ents || payload.active_entitlements || [];
+  // New v1 API uses "entitlements" or "active_entitlements"
+  const raw = payload.entitlements || payload.active_entitlements || [];
   return raw.map((e) => ({
     key: e.key,
     expires_at: e.expires_at ?? null,