Zyphe SDK – Node

⚠️ This package is now ESM-only.

• You must use import syntax, not require().
• Node.js v16.17+ or v18+ is recommended.
• CommonJS (require()) is not supported.

This is the Node.js SDK package for Zyphe. It contains utilities to interact with the Zyphe platform, including webhook signature verification and verification session management.

Installing package

If you want to use the SDK outside of this monorepo, you can install it directly from npm:

pnpm install @zyphe-sdk/node

ESM-only usage:

// Correct: ESM import
import { verifyWebhookSignatureHeader } from "@zyphe-sdk/node";

// ❌ Not supported:
// const sdk = require("@zyphe-sdk/node");

Then import and use the package in your project as described in the Usage section.

1. Webhook Signature Verification

This package provides the core webhook signature verification logic for Zyphe. It enables secure verification of incoming webhook requests in both Node.js and browser environments using HMAC-SHA256 signatures.

Basic Usage

import { verifyWebhookSignatureHeader } from "@zyphe-sdk/node";

const secretHex = "<your-hex-encoded-secret>";
const rawBodyString = "..."; // The raw request body as a string
const signatureHeader = "t=1234567890,v0=abcdef..."; // The signature header from the webhook

const isValid = verifyWebhookSignatureHeader(
  secretHex,
  rawBodyString,
  signatureHeader
);
if (isValid) {
  // Signature is valid
} else {
  // Signature is invalid
}

• secretHex: The hex-encoded secret key used to sign the webhook.
• rawBodyString: The raw request body as a string (must match exactly what was sent).
• signatureHeader: The signature header string, e.g. t=1234567890,v0=abcdef....
• Returns: true if the signature is valid, or false otherwise.

Advanced Utilities

• parseSignatureHeader(signatureHeader) – Parse the signature header into timestamp and signature.
• hexToBytes(hex) / bufferToHex(buffer) – Convert between hex and bytes.
• timingSafeEqual(a, b) – Constant-time string comparison.
• Error codes/messages for robust error handling.

2. Verification Session Management

You can programmatically create verification sessions and construct user-facing URLs for onboarding flows.

Create a Verification Session

import { createVerificationSession } from "@zyphe-sdk/node";

const response = await createVerificationSession(
  {
    email: "[email protected]", // required
    flowId: "<flowId>", // required
    flowStepId: "<flowStepId>", // required
    isSandbox: false, // required
    customData: {
      // optional
      walletAddress: "0x123...",
      // ...any extra data you want to pass
    },
  },
  {
    apiKey: "<your-api-key>",
    environment: "staging", // or "production", "local"
    handoffBaseUrl: "https://your-app.com", // optional
    primaryColor: "#000000", // optional
    secondaryColor: "#ffffff", // optional
    isFullscreen: true, // optional
  }
);

• customData (optional): Pass any extra data you want to associate with the verification session. This will be available in the webhook payload and session data.
• The function returns a Promise resolving to the API response. Handle errors as needed (e.g., try/catch or checking for error fields).

Construct a Verification Session URL

import { constructVerificationSessionUrl } from "@zyphe-sdk/node";

const url = constructVerificationSessionUrl({
  flowParams: {
    flowId: "...",
    flowStepId: "...",
    email: "[email protected]",
    product: "kyc", // or "kyb" if supported
    isSandbox: false,
    customData: { walletAddress: "0x123..." }, // optional
  },
  verificationSession: response.data, // from createVerificationSession
  opts: {
    apiKey: "<your-api-key>",
    environment: "staging",
    handoffBaseUrl: "https://your-app.com", // optional
    primaryColor: "#000000", // optional
    secondaryColor: "#ffffff", // optional
    isFullscreen: true, // optional
  },
});

• The constructed URL includes all relevant parameters and can be used to embed or redirect users to the verification flow.
• Optional fields (like handoffBaseUrl, primaryColor, etc.) will be appended as query parameters if provided.

Types

• InitializeZypheFlowParams: Parameters for initializing a verification flow (see types.ts).
• SDKOptions: Configuration for the SDK (see types.ts).
• SdkCreateVerificationRequestResponse: API response type for session creation.

Error Handling

• If session creation fails, the function may throw or return an error object depending on usage context. Always check for errors and handle them appropriately.
• Example:

try {
  const response = await createVerificationSession(...);
  if (response.error) {
    // Handle error
    console.error(response.error);
  } else {
    // Success
  }
} catch (err) {
  // Handle thrown errors (e.g., network issues)
  console.error(err);
}

3. Types and Configuration

• InitializeZypheFlowParams, SDKOptions, SdkCreateVerificationRequestResponse – for type-safe integration.
• Environments, EnvironmentConfigs, API_KEY_HEADER – for environment and API configuration.

Resources

• See the dedicated middleware packages for Express, Fastify, Hono, and NestJS for webhook signature verification in those frameworks.

Made with ❤️ by Zyphe Inc