Get started with Node.js and Electron

What you need

• Node.js 20 or later. The SDK is plain JavaScript ES modules, with no native module and no other package to pull in.
• An app on the dashboard. Its Integration › Connect software page has the API address, the App ID, the public key and a Make a test key button. The API address ends in /api, with no /v1: https://<your ClavisAUH site>/api.

1. Install the SDK

Download clavisauh-sdk-js-0.1.0.tgz from Downloads, check its SHA-256 as that page shows, put the file in your project folder and install it:

npm install ./clavisauh-sdk-js-0.1.0.tgz

The package is named @clavisauh/sdk and ships its TypeScript declarations. If your file has a newer version number, change the file name in the command to match. The SDK is not on npm yet; once it is, this guide will show that way too.

Want a test run before touching your own project? Download the starter (.zip) on the Connect software page gives a folder with the SDK, the five scenarios K1 to K5 and run scripts already filled in with your app's settings.

2. The minimal code

The blocks below are parts of one file; the whole file, with its imports and helpers, is in step 3.

Create the client once, when your software starts. baseUrl, appId and appPublicKey are the three values on the Connect software page: the sample reads them from environment variables, your software writes them in its code. The device key lives in a file: sessions and offline tokens are bound to it, while the seat on the license follows the machine's hashed identifiers:

const client = new ClavisClient({
  baseUrl: env.CLAVIS_BASE_URL,
  appId: env.CLAVIS_APP_ID,
  appPublicKey: env.CLAVIS_APP_KEY,
  device: defaultDevice(),
  // The same key every run: sessions and offline tokens stay with this machine.
  deviceKey: loadOrCreateDeviceKey(join(STATE, "device.key")),
  appVersion: "1.0.0",
});

Activate the customer's key. Without a network, the offline token saved last time keeps the software running:

let grant = null;
try {
  await client.init();
  grant = await client.activate(env.CLAVIS_LICENSE);
} catch (err) {
  if (!(err instanceof ClavisError)) throw err;
  // No answer (network_error, timeout...): a token saved last time keeps the software working.
  const offline = err.retryable && existsSync(SAVED) ? client.verifyOffline(readFileSync(SAVED, "utf8")) : null;
  if (!offline) {
    console.log(err.userMessage(LANG));
    console.log("FAIL", err.code);
    process.exit(1);
  }
  console.log("Offline: using the license saved on this machine");
}

The public key only checks signatures, so embedding it in your software is safe. Never embed any secret key.

3. Run it

1. On the Connect software page, select Make a test key. A TEST key expires after 24 hours and does not count against your limits.
2. Save the whole file below as k1_key.mjs (the starter has it), set the four settings and run it:

// K1 · License key only: activate on this machine, keep the session alive, work offline for a while.
// Run: CLAVIS_BASE_URL=... CLAVIS_APP_ID=... CLAVIS_APP_KEY=... CLAVIS_LICENSE=... node k1_key.mjs
import { existsSync, readFileSync, writeFileSync } from "node:fs";
import { join } from "node:path";
import { ClavisClient, ClavisError } from "@clavisauh/sdk";
import { defaultDevice, loadOrCreateDeviceKey } from "@clavisauh/sdk/node";

const env = process.env;
const LANG = env.CLAVIS_LANG ?? "en";
const STATE = env.CLAVIS_STATE_DIR ?? ".clavis";
const SAVED = join(STATE, "offline.token");

const client = new ClavisClient({
  baseUrl: env.CLAVIS_BASE_URL,
  appId: env.CLAVIS_APP_ID,
  appPublicKey: env.CLAVIS_APP_KEY,
  device: defaultDevice(),
  // The same key every run: sessions and offline tokens stay with this machine.
  deviceKey: loadOrCreateDeviceKey(join(STATE, "device.key")),
  appVersion: "1.0.0",
});

let grant = null;
try {
  await client.init();
  grant = await client.activate(env.CLAVIS_LICENSE);
} catch (err) {
  if (!(err instanceof ClavisError)) throw err;
  // No answer (network_error, timeout...): a token saved last time keeps the software working.
  const offline = err.retryable && existsSync(SAVED) ? client.verifyOffline(readFileSync(SAVED, "utf8")) : null;
  if (!offline) {
    console.log(err.userMessage(LANG));
    console.log("FAIL", err.code);
    process.exit(1);
  }
  console.log("Offline: using the license saved on this machine");
}

if (grant) {
  console.log("License", grant.license.status, "until", grant.license.expiresAt ?? "forever");
  // Every few minutes while the software runs; sessions end after an hour without one.
  const beat = await client.heartbeat();
  if (beat.offlineToken ?? grant.offlineToken) writeFileSync(SAVED, beat.offlineToken ?? grant.offlineToken);
  await client.logout();
}
console.log("OK k1", grant ? grant.license.status : "offline");

export CLAVIS_BASE_URL="<API address>"
export CLAVIS_APP_ID="<App ID>"
export CLAVIS_APP_KEY="<public key>"
export CLAVIS_LICENSE="<test key>"
node k1_key.mjs

On Windows, in PowerShell:

$env:CLAVIS_BASE_URL = "<API address>"
$env:CLAVIS_APP_ID = "<App ID>"
$env:CLAVIS_APP_KEY = "<public key>"
$env:CLAVIS_LICENSE = "<test key>"
node k1_key.mjs

It prints License active until <date>, then OK k1 active on the last line. Run it again on the same machine and it still succeeds without using another seat: the server knows the machine by its hashed identifiers (Devices, HWID and transfers). The device key, which signs the requests, stays in the .clavis folder under the folder you run it from (or in CLAVIS_STATE_DIR). A container started afresh for each run looks like a new machine every time, see Questions.

4. See it on the dashboard

• Integration › Connect software: step 4 turns to Connected, with js/0.1.0 and the machine's operating system.
• Licensing & releases › Licenses: the key goes from Unused to Active.
• End users › Devices & sessions: the machine that ran it, and the session it opened.

5. Handle errors

Every refusal is a ClavisError with three things you need:

• code: a code from the error codes table, such as invalid_credentials or device_limit.
• userMessage("en"): a sentence for the person using your software, in English or "vi", ready to show.
• retryable: true when no answer arrived (no network, too slow, a busy server); trying again later may work.

An answer without your app's valid signature is refused with a ClavisVerificationError (also a ClavisError), code unsigned_response, invalid_response_signature, unknown_key or stale_response. Treat it as no answer at all; usually the API address or the public key in your software is wrong.

While your software runs, send a heartbeat regularly to keep the session, every 5 to 30 minutes or so: a session ends after 60 minutes without one.

// Every few minutes while the software runs; sessions end after an hour without one.
const beat = await client.heartbeat();

Save the latest offline token, so the software still opens next time without a network:

if (beat.offlineToken ?? grant.offlineToken) writeFileSync(SAVED, beat.offlineToken ?? grant.offlineToken);

Offline tokens come on every plan and last 7 days by default; Premium chooses the length, and Online-Only Mode turns them off. See Offline licenses.

6. Package and release

• Write the API address, App ID and public key in your code or in a config file shipped with the build. Customers' machines need no environment variables.
• Put the state folder (device key, offline token) where the user can write, one per user: %APPDATA%\YourApp on Windows, ~/Library/Application Support/YourApp on macOS, ~/.config/your-app on Linux. Never in the install folder.
• Pass appVersion as the version you release: the server uses it to block builds that are too old and to announce new ones, see Signed releases and updates.
• Bundlers (esbuild, webpack, Vite) and Node packaging tools take the SDK like any other JavaScript: nothing to rebuild per operating system.
• Before you sell, turn on Publicly released in Integration › App settings. Every TEST key stops working, so a test key that got out cannot be used.

With Electron

• Call the SDK in the main process. @clavisauh/sdk/node reads machine details and writes files, which is the main process's job; the renderer only gets results (license state, error sentence) over IPC, with a preload script and contextBridge.
• State folder: path.join(app.getPath("userData"), "clavis").
• The SDK is an ES module. An ES module main process (Electron 28 or later) imports it as the sample does; a CommonJS main process loads it with const { ClavisClient } = await import("@clavisauh/sdk").
• electron-builder and Electron Forge package the SDK with node_modules like any JavaScript package, app.asar included. The state folder is in userData, outside the app package, so it stays writable.

Questions

Does the software need a network every time it opens? Activation and heartbeats do. Without a network, the saved token keeps the software running for 7 days by default, or the length chosen on Premium, checked on the machine without the server.

What if a customer reinstalls the system or changes machines? After a reinstall on the same machine, the server still recognizes it from its hashed hardware identifiers. A new machine takes a new seat; when none is left the customer gets device_limit, and you Reset devices on the Licenses page. See Devices, HWID and transfers.

Can the SDK run in a browser? The main @clavisauh/sdk entry runs in browsers (the Connect software page uses it for its try-it button), while @clavisauh/sdk/node runs only in Node.js and Electron. ClavisAUH is made for software installed on a machine, where the device key is kept.

Does it work with TypeScript? Yes. The package ships its declarations; Grant, ClavisOptions and the other types are exported.

Where is the whole API? JavaScript SDK lists every option and method; How the system works explains each call of each scenario.

Related

• Downloads
• JavaScript SDK
• Error codes
• How the system works