@digital-nature/licence-verifier

JavaScript/TypeScript client for the Digital Nature licence verification API.

Installation

npm install @digital-nature/licence-verifier

Usage

import { LicenceVerifier } from '@digital-nature/licence-verifier'

const verifier = new LicenceVerifier({
  baseUrl: 'https://verify.software.digital-nature.co.uk',
})

// Check a licence is valid
const result = await verifier.verify('XXXX-XXXX-XXXX-XXXX')
// { valid: true, licenceKey: '...', productSlug: '...', status: 'active', expiresAt: null }

// Activate a domain
const activation = await verifier.activate('XXXX-XXXX-XXXX-XXXX', 'example.com')
// { activated: true, domain: 'example.com', domainType: 'production', activationsUsed: 1, activationLimit: 2 }

// Deactivate a domain
await verifier.deactivate('XXXX-XXXX-XXXX-XXXX', 'example.com')

// Get full licence info
const info = await verifier.info('XXXX-XXXX-XXXX-XXXX')
// { licenceKey: '...', productSlug: '...', status: 'active', activationsUsed: 1, activationLimit: 2, domains: [...] }

Packages, add-ons and free trials

verify and info also say what the licence grants:

const { package: pkg, addons, trials } = await verifier.verify(key)
// pkg:    'club-platform'            — or null for an ordinary product
// addons: ['club-platform-pitch-x-3'] — everything granted RIGHT NOW
// trials: [{ addon: 'club-platform-pitch-x-3', endsAt: '2026-10-17T09:00:00.000Z' }]

• addons never includes a trial that has ended, so gating on addons alone already enforces a trial's end.
• trials says which of addons are on a free trial and when each stops. Use it to show "N days left". [] when none, and from a server older than trials.
• A cached verify/info result is never kept past the soonest trial end.

Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | baseUrl | string | — | Base URL of the verify service | | cacheTtl | number | 30000 | Cache TTL in ms for verify and info responses. Set to 0 to disable. | | fetch | typeof fetch | globalThis.fetch | Override the fetch implementation (useful for testing) |

Error handling

All methods throw typed errors you can instanceof check:

import {
  LicenceNotFoundError,
  LicenceExpiredError,
  LicenceInactiveError,
  ActivationLimitReachedError,
  DomainAlreadyActiveError,
  LicenceVerifierError,  // base class
} from '@digital-nature/licence-verifier'

try {
  await verifier.activate(key, domain)
} catch (err) {
  if (err instanceof ActivationLimitReachedError) {
    // handle limit
  } else if (err instanceof LicenceNotFoundError) {
    // handle not found
  }
}

Requirements

Node.js 18 or later (uses native fetch).