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 SIGNING_SECRET = "YOUR_SIGNING_SECRET";
   const sdk = new SelvageSDK({
     appId: APP_ID,
     apiKey: SIGNING_SECRET
   });

Requests default to the Selvage gateway at https://agw.zk.me/selvage.
Pass options: { endpoint: "https://staging.example.com/selvage" } if you need to target another environment.

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 | Critical credential. Unique application identifier issued by Selvage; sent with every API request. | | apiKey | string | Critical credential. Shared secret for signing API calls—store securely and rotate immediately if exposed. | | providerId | string | Identifier for the verification provider or scenario when calling createQRCode. |

Note: To obtain your dedicated appId and apiKey, please reach out to [email protected].

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