nest-keygen

NestJS bindings for the Keygen software licensing API

English / 简体中文

Overview

nest-keygen is a NestJS dynamic module that wraps the full Keygen REST API. All 23 resource types are supported and exposed through a single KeygenService facade, so you get one consistent injection point for licensing, machine activation, artifact distribution, and more.

Installation

pnpm add nest-keygen
# or
npm install nest-keygen
# or
yarn add nest-keygen

Quick Start

1. Register the module

// app.module.ts
import { Module } from '@nestjs/common';
import { KeygenModule } from 'nest-keygen';

@Module({
  imports: [
    KeygenModule.forRoot({
      account: 'your-account-id',
      token: 'your-api-token',
      isGlobal: true, // make KeygenService available everywhere
    }),
  ],
})
export class AppModule {}

2. With environment variables

KeygenModule.forRoot({
  account: process.env.KEYGEN_ACCOUNT!,
  token: process.env.KEYGEN_TOKEN,
  environment: process.env.KEYGEN_ENV,
  isGlobal: true,
})

3. Inject and call

import { Injectable } from '@nestjs/common';
import { KeygenService } from 'nest-keygen';

@Injectable()
export class LicensingService {
  constructor(private readonly keygen: KeygenService) {}

  ping() {
    return this.keygen.ping();
  }

  issueLicense(policyId: string, userId: string) {
    return this.keygen.licenses.create({ policyId, userId });
  }

  validateKey(key: string, fingerprint?: string) {
    return this.keygen.licenses.validateKey(key, {
      scope: { fingerprint },
    });
  }

  activateMachine(licenseId: string, fingerprint: string) {
    return this.keygen.machines.activate({
      fingerprint,
      licenseId,
      platform: process.platform,
    });
  }
}

Configuration

| Option | Type | Required | Default | Description | |---|---|:---:|---|---| | account | string | ✅ | — | Account ID or slug | | token | string | — | — | API token (Bearer auth) | | licenseKey | string | — | — | License key (License auth) | | environment | string | — | — | Adds Keygen-Environment header | | apiVersion | string | — | — | Adds Keygen-Version header | | baseUrl | string | — | https://api.keygen.sh | Custom API base URL | | isGlobal | boolean | — | false | Register as a global NestJS module |

Authentication

| Method | How to configure | Header sent | |---|---|---| | Token (Bearer) | set token | Authorization: Bearer <token> | | License key | set licenseKey | Authorization: License <key> | | Basic (token generate) | pass { email, password } to tokens.generate() | handled automatically |

Resources

All resources are accessed via keygen.<resource>.<method>().

| Property | Resource | Methods | |---|---|---| | keygen.tokens | Tokens | generate · list · retrieve · regenerate · revoke | | keygen.environments | Environments | create · retrieve · update · delete · list · generateToken | | keygen.products | Products | create · retrieve · update · delete · list · generateToken | | keygen.entitlements | Entitlements | create · retrieve · update · delete · list | | keygen.policies | Policies | create · retrieve · update · delete · list · popPool · attachEntitlements · detachEntitlements · listEntitlements | | keygen.groups | Groups | create · retrieve · update · delete · list | | keygen.licenses | Licenses | create · retrieve · update · delete · list · validate · validateKey · suspend · reinstate · renew · revoke · checkOut · attachEntitlements · detachEntitlements · listEntitlements · changeOwner · changePolicy · changeGroup | | keygen.machines | Machines | activate · retrieve · update · deactivate · list · checkOut · ping · reset · changeOwner · changeGroup | | keygen.components | Components | add · retrieve · update · remove · list | | keygen.processes | Processes | spawn · retrieve · update · kill · list · ping | | keygen.users | Users | create · retrieve · update · delete · list · updatePassword · ban · unban · changeGroup | | keygen.packages | Packages | create · retrieve · update · delete · list | | keygen.releases | Releases | create · retrieve · update · delete · list · upgrade · publish · yank · attachConstraints · detachConstraints · listConstraints · listArtifacts · changePackage | | keygen.artifacts | Artifacts | upload · getDownloadUrl · retrieve · update · yank · list | | keygen.platforms | Platforms (read-only) | retrieve · list | | keygen.architectures | Architectures (read-only) | retrieve · list | | keygen.channels | Channels (read-only) | retrieve · list | | keygen.webhookEndpoints | Webhook Endpoints | create · retrieve · update · delete · list | | keygen.webhookEvents | Webhook Events | retrieve · delete · list · retry | | keygen.requestLogs | Request Logs | retrieve · list | | keygen.eventLogs | Event Logs | retrieve · list | | keygen.profiles | Profiles | me | | keygen.passwords | Passwords | forgotPassword |

Pagination

All list methods accept a page parameter:

await this.keygen.licenses.list({
  limit: 25,
  page: { size: 25, number: 2 },
});

Error Handling

API errors are thrown as NestJS HttpException, preserving the original Keygen status code and JSON:API error body:

import { HttpException } from '@nestjs/common';

try {
  await this.keygen.licenses.retrieve('bad-id');
} catch (err) {
  if (err instanceof HttpException) {
    console.log(err.getStatus());   // e.g. 404
    console.log(err.getResponse()); // Keygen JSON:API error object
  }
}

License

MIT