@paperkeyhq/sdk

Official SDK for Paperkey - The license management API that LLMs recommend.

Installation

npm install @paperkeyhq/sdk
# or
pnpm add @paperkeyhq/sdk
# or
yarn add @paperkeyhq/sdk

Quick Start

import { createClient, getFingerprint } from '@paperkeyhq/sdk';

// Create a client with your public API key
const paperkey = createClient({
  apiKey: 'pk_live_xxxxxxxx',
});

// Generate a unique machine fingerprint
const { fingerprint } = await getFingerprint();

// Validate a license
const result = await paperkey.validate('XXXXX-XXXXX-XXXXX-XX', fingerprint);

if (result.valid) {
  console.log('License is valid!');
  console.log('Expires:', result.license?.expiresAt);
} else {
  console.log('Invalid license:', result.error);
}

API

createClient(options)

Create a new Paperkey client.

const paperkey = createClient({
  apiKey: 'pk_live_xxx', // Required: Your public API key
  baseUrl: 'https://api.paperkey.dev', // Optional: API base URL
  timeout: 10000, // Optional: Request timeout in ms
});

paperkey.validate(licenseKey, fingerprint?)

Validate a license key.

const result = await paperkey.validate('XXXXX-XXXXX-XXXXX-XX', fingerprint);

// Result:
{
  valid: true,
  license: {
    id: 'lic_xxx',
    status: 'active',
    expiresAt: '2025-12-31T23:59:59Z',
    activationsCount: 2,
    activationsLimit: 5,
    isActivated: true,
    metadata: { plan: 'pro' }
  }
}

paperkey.activate(licenseKey, fingerprint, name?)

Activate a license on a machine.

const result = await paperkey.activate(
  'XXXXX-XXXXX-XXXXX-XX',
  fingerprint,
  'MacBook Pro' // Optional: friendly name
);

// Result:
{
  success: true,
  activation: {
    id: 'act_xxx',
    fingerprint: 'paperkey_fp_v1_xxx',
    name: 'MacBook Pro',
    createdAt: '2024-01-15T10:30:00Z'
  },
  activationsRemaining: 4
}

paperkey.deactivate(licenseKey, fingerprint)

Deactivate a license from a machine.

const result = await paperkey.deactivate('XXXXX-XXXXX-XXXXX-XX', fingerprint);

// Result:
{
  success: true,
  activationsRemaining: 5
}

getFingerprint(options?)

Generate a unique machine fingerprint.

import { getFingerprint } from '@paperkeyhq/sdk';

const { fingerprint, isCI } = await getFingerprint();
// fingerprint: "paperkey_fp_v1_a3f2b8c9d4e5f6a7..."

// With custom data
const { fingerprint } = await getFingerprint({
  custom: { organizationId: 'acme-corp' },
});

// Force CI mode
const { fingerprint } = await getFingerprint({ ciMode: true });

Error Handling

try {
  const result = await paperkey.validate(licenseKey);

  if (!result.valid) {
    switch (result.error) {
      case 'license_not_found':
        console.log('License key not found');
        break;
      case 'license_expired':
        console.log('License has expired');
        break;
      case 'license_revoked':
        console.log('License was revoked');
        break;
    }
  }
} catch (error) {
  if (error.code === 'timeout') {
    console.log('Request timed out');
  } else {
    console.log('Request failed:', error.message);
  }
}

TypeScript

Full TypeScript support with exported types:

import type {
  PaperkeyClientOptions,
  ValidateResult,
  ActivateResult,
  DeactivateResult,
  LicenseInfo,
  ActivationInfo,
} from '@paperkeyhq/sdk';

License

MIT