Selvage SDK

Selvage SDK is a TypeScript/JavaScript package for integrating the Selvage verification flow. It provides QR-code generation, session polling, and status queries, and ships both ESM and CommonJS builds.

Installation

npm install @zkmelabs/selvage-sdk

# or
pnpm add @zkmelabs/selvage-sdk

# or
yarn add @zkmelabs/selvage-sdk

Quick Start

1. Import the core class

   import SelvageSDK from "@zkmelabs/selvage-sdk";

2. Create an SDK instance

   const APP_ID = "YOUR_APPLICATION_ID";
   const API_KEY = "YOUR_API_KEY";
   const sdk = new SelvageSDK({
     appId: APP_ID,
     apiKey: API_KEY,
   });

3. Generate and render a QR code

   const PROVIDER_ID = "YOUR_PROVIDER_ID";
   const { sessionId, qrCodeBase64, shortUrl } = await sdk.createQRCode({
     providerId: PROVIDER_ID,
     width: 240,
     height: 240,
   });
   
   sdk.renderQRCode("#qrcode", qrCodeBase64); // browser usage
   
   // Or render the shortUrl with your own QR generator (common on mobile)
   // e.g., use a third-party library to draw the shortUrl onto canvas

4. Listen for session completion

   const result = await sdk.waitForCompletion(sessionId, {
     onStatusChange(status) {
       console.log("status:", status);
     },
   });
   
   console.log("session completed:", result);

See API.md for the full type surface and advanced options.

Key Parameters

| Parameter | Type | Description | | --------------- | -------- | ------------------------------------------------------------------------------------------------------- | | appId | string | A unique identifier for your Dashboard account. You can find it in your Dashboard. | | apiKey | string | A secret key associated with your App ID. You can find it under Integration Settings in your Dashboard. | | providerId | string | An identifier that specifies which data source and verification logic to run. To obtain the available provider IDs, please reach out to [email protected]. |

Note: If you do not have a Dashboard account yet, please refer to the onboarding guide here: https://docs.zk.me/hub/start/onboarding

Example: Composed Query Logic

The SDK exposes both querySession and waitForCompletion. You can combine them to fit your workflow—for example, verifying the latest session state before starting a polling loop:

import SelvageSDK from "@zkmelabs/selvage-sdk";

const sdk = new SelvageSDK({
  /* ...config */
});

async function ensureVerified(sessionId: string) {
  const currentStatus = await sdk.querySession(sessionId);

  if (currentStatus?.state !== "completed") {
    const result = await sdk.waitForCompletion(sessionId, {
      onStatusChange(status) {
        console.log("status:", status);
      },
    });
    return result;
  }

  return currentStatus;
}

License

MIT © Selvage Contributors