Node.js integration

Node.js · supported

Supported baseline: Node.js 20+, ESM, Linux x64 or Windows x64. Electron applications must use the Electron helper instead.

Install from the private registry

Your onboarding configuration supplies the npm registry and authentication method for the @p2psdk scope.

# .npmrc — use environment expansion; do not commit a registry token.
@p2psdk:registry=${P2PSDK_NPM_REGISTRY}
//YOUR_PRIVATE_REGISTRY_HOST/:_authToken=${P2PSDK_NPM_TOKEN}

npm install --save-exact @p2psdk/[email protected]

For an onboarding tarball:

npm install --save-exact ./artifacts/p2psdk-node-1.0.0.tgz

consentReceipt is required. The deprecated consent: true option cannot initialize SDK 1.0.0. A non-Electron Node host must receive the approved compact receipt through the product's P2PSDK onboarding flow and protected local state.

Never hard-code or log a real receipt. It is bound to the application API key and device identity and must not be copied between installations.

Native library loading

The package first checks its prebuilds/linux-x64 or prebuilds/win32-x64 directory. Use an override only for an onboarding artifact or controlled diagnostic:

P2P_SDK_NATIVE_LIB=/absolute/path/to/libp2p_sdk.so node app.js

The wrapper and native library must come from the same release.

Create and connect

import P2PSdk, {
  SDKConnectionError,
  SDKInitError,
} from '@p2psdk/node';

let sdk;

export function startSdk({ apiKey, consentReceipt, identityPath }) {
  try {
    sdk = new P2PSdk(apiKey, {
      consentReceipt,
      identityPath,
      debug: process.env.NODE_ENV !== 'production',
      onConnect: () => console.info('P2PSDK connected'),
      onDisconnect: (reason) => console.warn('P2PSDK disconnected', reason),
    });

    sdk.on('connected', () => {
      console.info('P2PSDK online:', sdk.isOnline());
    });

    sdk.connect();
  } catch (error) {
    sdk?.free();
    sdk = undefined;
    if (error instanceof SDKInitError || error instanceof SDKConnectionError) {
      throw new Error(`P2PSDK startup failed: ${error.message}`);
    }
    throw error;
  }
}

The wrapper polls native state and emits events on the JavaScript event loop. connect() returning true means the native supervisor started, not that the peer is online.

Device identity

When no seed is supplied, the wrapper stores a generated per-install seed in a versioned JSON file using locking and atomic rename. Keep that file in persistent application data. Set identityPath or P2P_SDK_IDENTITY_FILE before construction when the default location is not suitable.

Revoke

Configure the onboarding revoke URL before calling revoke:

P2P_SDK_CONSENT_REVOKE_URL=https://your-onboarding-revoke-url.example

const result = await sdk.revokeConsent();
if (result.isRevoked) {
  sdk = undefined; // The wrapper freed the active instance.
}

On non-2xx or network failure, SDKConsentRevokeError is thrown and the active instance remains valid for retry.

Process shutdown

function shutdown() {
  if (!sdk) return;
  sdk.disconnect();
  sdk.free();
  sdk = undefined;
}

process.once('SIGINT', shutdown);
process.once('SIGTERM', shutdown);

Call free() exactly once and never call methods afterward. The wrapper does not install a service, autostart, or sleep blocker.

Node verification

Run on each packaged OS/architecture and validate the final prebuild layout.
Test receipt missing, invalid, expired, and bound to a different identity.
Wait for connected, interrupt the network, verify the reason, and confirm reconnect.
Revoke, shut down, and ensure a second free() is neither needed nor attempted.