Apps Manager SDK Integration Guide: Client & Server SDK Reference

The official apps-manager-sdk package on NPM provides seamless integration for desktop applications (Electron, Tauri, Node.js CLI) and server backends. It handles hardware fingerprinting, asymmetric Ed25519 verification, background heartbeats, encrypted lease caching, and server-to-server subscription verification.

Jump to:

Overview & Architecture

The apps-manager-sdk package is architected with dual entry points: AppsManagerClient (for client-side desktop and hybrid applications with offline cryptographic validation) and AppsManagerServer (for server-to-server subscription validation, webhook verification, and automated provisioning).

Core Capabilities

Complete TypeScript Support: Fully typed configuration objects, return payloads, and license states.

Cross-Platform Fingerprinting: Consistent hardware hashing across Windows, macOS, and Linux without native C++ compilation.

Storage Adapters: Built-in FileStorageAdapter (desktop apps), LocalStorageAdapter (web/hybrid), and MemoryStorageAdapter (testing).

State Subscription: Reactive listener API (client.on("change", (state) => ...)) to automatically update UI on license changes.

Anti-Tamper Trial Markers: Prevents users from deleting app directories to reset free trial countdowns.

Detailed Implementation Guides

1Installation & Package Setup

Install the official package from NPM using your preferred package manager.

bash

# Install via NPM
npm install apps-manager-sdk

# Or via PNPM
pnpm add apps-manager-sdk

# Or via Yarn
yarn add apps-manager-sdk

2Electron App Architecture (Main vs. Preload vs. Renderer)

In Electron applications, always instantiate AppsManagerClient in the Main process (Node.js runtime) and expose safe, read-only methods to the Renderer process via preload.ts and contextBridge.

Main Process (`main.ts`): Instantiates AppsManagerClient, loads license from FileStorageAdapter, and handles IPC events.

Preload Script (`preload.ts`): Uses contextBridge.exposeInMainWorld to expose `window.electronAPI.activateLicense()` and `window.electronAPI.getLicenseState()`.

Renderer (`App.tsx`): React or Vue frontend displays activation modal, expiration alerts, and tier badges based on state.

Never Expose Private Secrets

Only configure AppsManagerClient with your App Public Key and Public ID. Never embed administrative API Secrets or private keys inside client binaries.

SDK Methods Reference

Method Signature	Description	Returns
activate(licenseKey: string, options?: { deviceName?: string }): Promise<ActivationResult>	Activates license key with central gateway, binds hardware fingerprint, and caches signed lease envelope.	Promise<ActivationResult>
validate(): Promise<LicenseState>	Performs instant offline cryptographic signature check and schedules background heartbeat if connected.	Promise<LicenseState>
startTrial(): Promise<ActivationResult>	Begins hardware-bound free trial and records anti-tamper marker on current physical device.	Promise<ActivationResult>
deactivate(): Promise<boolean>	Unbinds current hardware seat from license to free seat for another machine.	Promise<boolean>
getState(): LicenseState	Synchronously returns latest cached license state, days remaining, tier, and feature flags.	LicenseState
on('change', listener: (state: LicenseState) => void): () => void	Subscribes to license state changes (e.g. activation, expiration, heartbeat updates). Returns unsubscribe function.	Function
verifySubscription(options: { licenseKey?: string; customerEmail?: string; deviceId?: string }): Promise<SubscriptionVerificationResult>	Server-to-server subscription verification using x-app-secret to check active customer status.	Promise<SubscriptionVerificationResult>

Production Code Integration

Electron Main Process (main.ts)

import { app, ipcMain } from 'electron';
import { AppsManagerClient, FileStorageAdapter } from 'apps-manager-sdk';
import path from 'path';

const client = new AppsManagerClient({
  baseUrl: 'https://apps-manager.in',
  appId: 'app_pub_789456',
  publicKey: `-----BEGIN PUBLIC KEY-----
MCowBQYDK2VwAyEA...
-----END PUBLIC KEY-----`,
  storage: new FileStorageAdapter(path.join(app.getPath('userData'), 'license.json')),
  autoHeartbeat: true,
  offlineGracePeriodDays: 7,
});

app.whenReady().then(async () => {
  // Silent initial validation on startup
  const state = await client.validate();
  console.log('Initial License State:', state.status);

  // IPC handlers for renderer
  ipcMain.handle('license:activate', async (_event, key: string) => {
    return await client.activate(key);
  });

  ipcMain.handle('license:getState', () => {
    return client.getState();
  });
});

Server-Side Subscription Verification (Node.js / Express)

import { AppsManagerServer } from 'apps-manager-sdk';

const server = new AppsManagerServer({
  baseUrl: 'https://apps-manager.in',
  appId: 'app_pub_789456',
  apiSecret: process.env.APPS_MANAGER_API_SECRET!,
});

// Middleware to verify active customer license before granting API access
async function requireActiveLicense(req, res, next) {
  const licenseKey = req.headers['x-license-key'];
  if (!licenseKey) {
    return res.status(401).json({ error: 'License key header required' });
  }

  const result = await server.verifySubscription({ licenseKey });
  if (!result.isValid) {
    return res.status(403).json({ error: `Access denied: ${result.message}` });
  }

  req.customer = result.customer;
  req.license = result;
  next();
}

Frequently Asked Questions

Where does FileStorageAdapter store license tokens on the client machine?

FileStorageAdapter saves the encrypted token in the user application data directory (e.g. %APPDATA% on Windows, ~/Library/Application Support on macOS, ~/.config on Linux) with file-level encryption permissions.

← Previous GuideSoftware License Management Next Guide →Distributed Edge Workers

Start Building with Apps Manager Today

Build databases, create scraping APIs, convert websites to JSON, and issue Ed25519 cryptographic software licenses in minutes. Zero credit card required.

Get Started Free