npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@licenseman/electron

v1.4.0

Published

Electron SDK for licensemanager.dev

Readme

@licenseman/electron

Electron SDK for licensemanager.dev.

Documentation · API reference · Changelog

Install

pnpm add @licenseman/electron

Requires Electron 28 or later.

Usage

Create a single LicenseManager instance and treat it as a singleton for the lifetime of your app (create it after the Electron app is ready, from the main process):

import { LicenseError, LicenseManager } from "@licenseman/electron";

const license = new LicenseManager({
  productId: "your-product-id",
  // Ed25519 public key from the Security page. Hard-code it: never load it
  // from a file or fetch it at runtime.
  publicKey: "-----BEGIN PUBLIC KEY-----\n…",
});

license.onStateChange((state) => updateUi(state));
const state = await license.ready(); // e.g. "ACTIVE" or "MISSING_KEY"

// When the user types their key:
try {
  await license.setLicenseKey(input);
} catch (error) {
  if (error instanceof LicenseError) showError(error.code);
}

// On shutdown:
license.dispose();

License state

getState() returns one of:

| State | Meaning | | --- | --- | | LOADING | Startup validation in progress. | | MISSING_KEY | No key stored yet: ask the user for one. | | ACTIVE | Valid license, verified online or with the stored token. | | INVALID_KEY | The key doesn't exist for this product (not_found). | | EXPIRED | The license expired (license_expired). | | VERSION_NOT_ALLOWED | The license doesn't include this version. getLatestAllowedVersion() returns the latest allowed version, or null. | | MACHINE_LIMIT_REACHED | The license is active on its maximum number of machines. | | OFFLINE_EXPIRED | The server can't be reached and there is no valid stored token. | | CLOCK_TAMPERED | The server can't be reached and the system clock was moved back. |

Subscribe with onStateChange(listener), which returns an unsubscribe function.

getPortalUrl() returns the link to the customer portal for your product (https://app.licensemanager.dev/portal/<productId>), e.g. to let customers manage or renew their license.

Validation

The stored key is validated online on every launch. The token the server returns is a JWT, verified like an offline token (EdDSA signature, product, key, machine fingerprint and expiry) and stored in the OS secret store.

When the stored token is valid, ready() resolves with ACTIVE right away and the online validation runs in the background; a refused license then switches the state through onStateChange. Otherwise ready() waits for the server.

setLicenseKey(key) validates a key the user typed (trimmed, case kept) and stores it only on success. On failure it throws a LicenseError whose code is a server code (not_found, license_expired, version_not_allowed, machine_limit_reached, plan_limit_exceeded, validation_error, internal_error) or network_error / invalid_response, and the current license is left untouched.

Only the four license errors lock the app. When the server can't be reached, times out, or answers another error, the SDK falls back to the stored token until it expires. getOfflineState() returns { mode: "online" }, or { mode: "offline", validUntil, remainingMs } while running on the stored token.

The key is re-validated in the background at 2/3 of the token lifetime. Set minOfflineDurationMs to re-validate earlier, so that at least that much offline time remains; it never moves re-validation within 1 day of the last one. While offline, retries back off from 5 minutes to 1 hour. Call refresh() to re-validate on demand, e.g. after the customer renewed.

Each validation retries transient failures (network errors, timeouts, 408, 429 and 5xx) with exponential backoff and jitter: for up to 30 seconds when a caller is waiting (startup without a valid stored token, setLicenseKey(), refresh()), and up to 5 minutes for background validations. Answers about the key are never retried.

version (defaults to Electron's app.getVersion()) and platform (the OS name and version by default, e.g. macOS 26.5.1, Windows 11 (10.0.22631) or Linux (Ubuntu 24.04.1 LTS)) are sent with every validation, along with machineName (by default the computer name, e.g. "Jane's MacBook Pro" from scutil --get ComputerName on macOS, else the hostname). While offline, version is also checked against the token's max version (mv): a stored token for 2.x refuses 3.0 with VERSION_NOT_ALLOWED until the server can be reached, since online the server's answer is authoritative.

Device fingerprint

getFingerprint() returns a stable identifier unique to the machine, installation and product. It joins a SHA-256 digest of a machine component with a per-install random ID that is stored in the OS secret store (see below), so it survives uninstall/reinstall and is far more stable than the OS version.

The machine component defaults to the native machine GUID (IOPlatformUUID on macOS, MachineGuid on Windows, /etc/machine-id on Linux), falling back to a hardware MAC address or hostname. Override it with the fingerprint option — either a fixed string or a (sync or async) function:

new LicenseManager({
  productId,
  publicKey,
  fingerprint: () => myCustomMachineId(), // or a plain string
});

Persistence

The install ID, last-seen timestamp, license key and token are stored in the OS secret store (macOS Keychain, Windows Credential Manager, Linux Secret Service) via the optional native @napi-rs/keyring dependency, namespaced by productId so multiple apps never overlap. When no keyring is available (e.g. headless Linux), the SDK transparently falls back to redundant copies in non-obvious files.

Entries are stored under the keychainService name, which the OS shows when it asks the user for their password. It defaults to the app's bundle id on macOS (CFBundleIdentifier), and to dev.licensemanager.sdk elsewhere.

Set useKeychain: false to use only the file fallback. It defaults to Electron's app.isPackaged, so running the app unpackaged in development never triggers keychain prompts.

new LicenseManager({
  productId,
  publicKey,
  keychainService: "com.example.myapp",
  useKeychain: true,
});

Clock-tamper detection

On construction and roughly once an hour, the SDK records the newest Date.now() it has observed. If a later check sees an earlier time, isClockTampered() returns true — a signal that the system clock was rolled back (e.g. to defeat a time-limited license). Checks never throw and never block the host app.

Development

pnpm install
pnpm lint          # Biome lint + format check
pnpm lint:fix      # Apply Biome fixes
pnpm typecheck
pnpm test          # Vitest
pnpm test:coverage
pnpm build         # tsup, emits ESM + CJS + types to dist/

Releasing

Releases are managed with Changesets:

  1. Run pnpm changeset and commit the generated file with your change.
  2. On merge to main, the release workflow opens a "Version Packages" PR.
  3. Merging that PR publishes to npm.

The release workflow needs an NPM_TOKEN repository secret.

License

MIT