JavaScript SDK

# npm
npm install @licenseseat/[email protected]

# yarn
yarn add @licenseseat/[email protected]

# pnpm
pnpm add @licenseseat/[email protected]

<!-- ESM via esm.sh (recommended) -->
<script type="module">
  import LicenseSeat from 'https://esm.sh/@licenseseat/[email protected]';
</script>

<!-- ESM via unpkg -->
<script type="module">
  import LicenseSeat from 'https://unpkg.com/@licenseseat/[email protected]/dist/index.js';
</script>

<!-- ESM via jsDelivr -->
<script type="module">
  import LicenseSeat from 'https://cdn.jsdelivr.net/npm/@licenseseat/[email protected]/dist/index.js';
</script>

import LicenseSeat from '@licenseseat/js';

// Create SDK instance
const sdk = new LicenseSeat({
  apiKey: 'pk_live_xxxxxxxx',
  productSlug: 'your-product',  // Required
  debug: true
});

// Activate a license
await sdk.activate('YOUR-LICENSE-KEY');

// Check entitlements (simple boolean)
if (sdk.hasEntitlement('pro')) {
  enableProFeatures();
}

// Get current status
const status = sdk.getStatus();
console.log('License status:', status.status);

import LicenseSeat, {
  type LicenseSeatConfig,
  type ValidationResult,
  type EntitlementCheckResult,
  type LicenseStatus
} from '@licenseseat/js';

const config: LicenseSeatConfig = {
  apiKey: 'pk_live_xxxxxxxx',
  productSlug: 'your-product',
  debug: true
};

const sdk = new LicenseSeat(config);

// Full type inference
const result: ValidationResult = await sdk.validateLicense('LICENSE-KEY');
const status: LicenseStatus = sdk.getStatus();
const hasPro: boolean = sdk.hasEntitlement('pro');

const sdk = new LicenseSeat({
  // Required
  productSlug: 'your-product',              // Your product slug from dashboard

  // Required for authenticated operations
  apiKey: 'pk_live_xxxxxxxx',

  // API Configuration
  apiBaseUrl: 'https://licenseseat.com/api/v1',  // Default
  requestTimeoutMs: 15000,                       // Per-attempt request/body deadline
  maxResponseBytes: 1048576,                     // Request/response JSON size ceiling
  allowInsecureHttp: false,                      // HTTP only for explicit loopback development

  // Storage
  storagePrefix: 'licenseseat_',              // localStorage key prefix

  // Initialization
  autoInitialize: true,                       // Auto-validate cached license on init

  // Auto-Validation
  autoValidateInterval: 3600000,              // 1 hour (in ms)

  // Heartbeat
  heartbeatInterval: 300000,                  // 5 minutes (in ms)

  // Telemetry and app info
  telemetryEnabled: true,                       // Attach optional bounded telemetry
  browserHighEntropyTelemetryEnabled: false,    // Opt in to Chromium UA-CH enrichment
  appVersion: null,                           // Your app version (e.g., '2.1.0')
  appBuild: null,                             // Your app build number (e.g., '42')

  // Offline Support
  offlineFallbackEnabled: false,              // Enable offline validation fallback
  maxOfflineDays: 0,                          // Max days offline (0 = disabled)
  offlineLicenseRefreshInterval: 259200000,   // 72 hours
  maxClockSkewMs: 300000,                     // 5 minutes
  signingPublicKeys: {                        // Trusted keys for offline use after reload
    'key-id-001': 'base64url-encoded-32-byte-public-key'
  },

  // Network
  maxRetries: 3,                              // Retry attempts for failed requests
  retryDelay: 1000,                           // Initial retry delay (ms)
  networkRecheckInterval: 30000,              // Check connectivity every 30s when offline

  // Debug
  debug: false                                // Enable console logging
});

// Omit the second argument for default device identification.
const result = await sdk.activate('LICENSE-KEY', {
  deviceId: 'custom-device-id',         // Optional: auto-generated if not provided
  deviceName: "John's MacBook Pro",     // Optional: human-readable device name
  metadata: { version: '1.0.0' }        // Optional: custom metadata
});

console.log('Activation ID:', result.activation?.id);
// {
//   license_key: 'LICENSE-KEY',
//   device_id: 'web-abc123',
//   activated_at: '2024-01-15T10:30:00Z',
//   activation: {
//     object: 'activation',
//     id: 123,
//     device_id: 'web-abc123',
//     license_key: 'LICENSE-KEY',
//     activated_at: '2024-01-15T10:30:00Z',
//     license: { ... }
//   }
// }

const result = await sdk.deactivate();
console.log('Deactivated activation:', result.activation_id);
// {
//   object: 'deactivation',
//   activation_id: 123,
//   deactivated_at: '2024-01-15T12:00:00Z'
// }

const result = await sdk.validateLicense('LICENSE-KEY', {
  deviceId: 'device-id'  // Optional: required for hardware_locked mode
});

console.log('License valid:', result.valid);
// {
//   valid: true,
//   license: {
//     key: 'LICENSE-KEY',
//     status: 'active',
//     mode: 'hardware_locked',
//     plan_key: 'pro',
//     active_seats: 1,
//     seat_limit: 3,
//     active_entitlements: [
//       { key: 'pro', expires_at: null, metadata: null },
//       { key: 'beta', expires_at: '2024-12-31T23:59:59Z', metadata: null }
//     ],
//     product: { slug: 'your-product', name: 'Your Product' }
//   },
//   active_entitlements: [...]
// }

if (sdk.hasEntitlement('pro')) {
  enableProFeatures();
}

if (sdk.hasEntitlement('beta')) {
  showBetaUI();
}

const result = sdk.checkEntitlement('pro');

if (result.active) {
  console.log('Entitlement:', result.entitlement);
  console.log('Expires:', result.entitlement.expires_at);
} else {
  console.log('Reason:', result.reason);
  // Possible reasons: 'no_license', 'not_found', 'expired'
}

const status = sdk.getStatus();

switch (status.status) {
  case 'inactive':
    showActivationScreen();
    break;
  case 'pending':
    showLoadingIndicator();
    break;
  case 'active':
    enableFeatures(status.entitlements);
    break;
  case 'offline-valid':
    enableFeatures(status.entitlements);
    showOfflineBanner();
    break;
  case 'invalid':
    showErrorScreen(status.message);
    break;
  case 'offline-invalid':
    showRenewalScreen();
    break;
}

// Subscribe
const unsubscribe = sdk.on('activation:success', () => {
  console.log('License activated');
});

// Unsubscribe
unsubscribe();
// or
sdk.off('activation:success', handler);

import { configure, getSharedInstance, resetSharedInstance } from '@licenseseat/js';

// Configure once at app startup
configure({
  apiKey: 'pk_live_xxxxxxxx',
  productSlug: 'your-product'
});

// Use anywhere in your app
const sdk = getSharedInstance();
await sdk.activate('LICENSE-KEY');

// Reset if needed (clears all state)
resetSharedInstance();

const sdk = new LicenseSeat({
  apiKey: 'pk_live_xxxxxxxx',
  productSlug: 'your-product',
  autoInitialize: false  // Don't auto-initialize
});

// Later, when ready:
sdk.initialize();

const sdk = new LicenseSeat({
  apiKey: 'pk_live_xxxxxxxx',
  productSlug: 'your-product',
  offlineFallbackEnabled: true,  // Enable offline fallback
  maxOfflineDays: 7,             // Allow at most 7 days offline
  signingPublicKeys: {
    'key-id-001': 'base64url-encoded-32-byte-public-key'
  }
});

// Sync offline assets (downloads the legacy token + signing key, caches them)
await sdk.syncOfflineAssets();

// Verify cached offline token (use when offline)
const result = await sdk.verifyCachedOffline();
// { valid: true, offline: true, license: {...}, activation: {...} }

// Get offline token from server
const token = await sdk.getOfflineToken();

// Get signing key
const signingKey = await sdk.getSigningKey('key-id-001');

// Verify a specific token manually
const isValid = await sdk.verifyOfflineToken(token, signingKey.public_key);

{
  object: 'offline_token',
  token: {
    schema_version: 1,
    license_key: 'LICENSE-KEY',
    product_slug: 'your-product',
    plan_key: 'pro',
    mode: 'hardware_locked',
    device_id: 'web-abc123',
    iat: 1704067200,        // Issued at (Unix timestamp)
    exp: 1706659200,        // Expires at (Unix timestamp)
    nbf: 1704067200,        // Not before (Unix timestamp)
    license_expires_at: null,
    kid: 'key-id-001',
    entitlements: [
      { key: 'pro', expires_at: null }
    ],
    metadata: {}
  },
  signature: {
    algorithm: 'Ed25519',
    key_id: 'key-id-001',
    value: 'base64url-encoded-signature'
  },
  canonical: '{"entitlements":[...],"exp":...}'
}

const result = await sdk.validateLicense('LICENSE-KEY');

if (result.offline) {
  console.log('Validated offline');
}

import LicenseSeat, {
  APIError,
  LicenseError,
  ConfigurationError,
  CryptoError
} from '@licenseseat/js';

try {
  await sdk.activate('INVALID-KEY');
} catch (error) {
  if (error instanceof APIError) {
    console.log('HTTP Status:', error.status);
    console.log('Error Code:', error.data?.error?.code);
  } else if (error instanceof LicenseError) {
    console.log('License error:', error.code);
  } else if (error instanceof CryptoError) {
    console.log('Crypto error:', error.message);
  }
}

{
  error: {
    code: 'license_not_found',       // Machine-readable error code
    message: 'License not found.',   // Human-readable message
    details: { ... }                 // Optional additional details
  }
}

try {
  const result = await sdk.testAuth();
  console.log('Authenticated:', result.authenticated);  // Always true if 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?.status ?? 'client_error');
}

sdk.reset();

sdk.destroy();
// Do not use sdk after this

import type {
  LicenseSeatConfig,
  ActivationOptions,
  ValidationOptions,
  ValidationResult,
  EntitlementCheckResult,
  LicenseStatus,
  Entitlement,
  CachedLicense,
  ActivationResponse,
  DeactivationResponse,
  OfflineToken
} from '@licenseseat/js';

import { useState, useEffect, createContext, useContext } from 'react';
import LicenseSeat from '@licenseseat/js';

// Context
const LicenseContext = createContext(null);

// Provider
export function LicenseProvider({ children, config }) {
  const [sdk] = useState(() => new LicenseSeat(config));
  const [status, setStatus] = useState(sdk.getStatus());

  useEffect(() => {
    const events = [
      'activation:success',
      'deactivation:success',
      'validation:success',
      'validation:failed',
      'validation:offline-success',
      'validation:offline-failed'
    ];

    const unsubscribers = events.map(event =>
      sdk.on(event, () => setStatus(sdk.getStatus()))
    );

    return () => {
      unsubscribers.forEach(unsub => unsub());
      sdk.destroy();  // Clean up on unmount
    };
  }, [sdk]);

  return (
    <LicenseContext.Provider value={{ sdk, status }}>
      {children}
    </LicenseContext.Provider>
  );
}

// Hook
export function useLicense() {
  return useContext(LicenseContext);
}

// Usage
function App() {
  return (
    <LicenseProvider config={{ apiKey: 'pk_live_xxxxxxxx', productSlug: 'your-product' }}>
      <MainApp />
    </LicenseProvider>
  );
}

function MainApp() {
  const { sdk, status } = useLicense();

  if (status.status === 'active') {
    return <Dashboard hasPro={sdk.hasEntitlement('pro')} />;
  }

  return <ActivationForm sdk={sdk} />;
}

<!DOCTYPE html>
<html>
<head>
  <title>LicenseSeat Demo</title>
</head>
<body>
  <input id="license-key" placeholder="Enter license key" />
  <button id="activate-btn">Activate</button>
  <div id="status"></div>

  <script type="module">
    import LicenseSeat from 'https://esm.sh/@licenseseat/[email protected]';

    const sdk = new LicenseSeat({
      apiKey: 'pk_live_xxxxxxxx',
      productSlug: 'your-product',
      debug: true
    });

    // Display current status
    function updateUI() {
      const status = sdk.getStatus();
      document.getElementById('status').textContent =
        `Status: ${status.status}`;
    }

    // Listen for changes
    sdk.on('activation:success', updateUI);
    sdk.on('validation:success', updateUI);

    // Handle activation
    document.getElementById('activate-btn').onclick = async () => {
      const key = document.getElementById('license-key').value;
      try {
        await sdk.activate(key);
        alert('License activated!');
      } catch (e) {
        alert('Activation failed: ' + e.message);
      }
    };

    updateUI();
  </script>
</body>
</html>

// 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]; },
};

const originalKeys = Object.keys;
Object.keys = function(obj) {
  if (obj === globalThis.localStorage) return originalKeys(storage);
  return originalKeys(obj);
};

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');