DCID Server SDK

A TypeScript/JavaScript SDK for interacting with the DCID Server API. This SDK provides a simple, type-safe interface for authentication and OTP operations.

Installation

npm install @dcid/server-sdk
# or
yarn add @dcid/server-sdk
# or
pnpm add @dcid/server-sdk

Quick Start

ES Modules (Modern JavaScript/TypeScript)

import { DCIDServerSDK } from "@dcid/server-sdk";

// Initialize the SDK
const sdk = new DCIDServerSDK({
  apiKey: "your-api-key",
  environment: "prod",
});

// Register/Sign-in with OTP
await sdk.auth.registerOTP({ email: "[email protected]" });

// Confirm OTP and get tokens
const tokens = await sdk.auth.confirmOTP({
  email: "[email protected]",
  otp: "123456",
});

console.log("Access Token:", tokens.access_token);
console.log("Refresh Token:", tokens.refresh_token);

CommonJS (Node.js)

const { DCIDServerSDK } = require("@dcid/server-sdk");

// Initialize the SDK
const sdk = new DCIDServerSDK({
  apiKey: "your-api-key",
  environment: "prod",
});

// Use the SDK the same way...
await sdk.auth.registerOTP({ email: "[email protected]" });

Universal Import Syntax

The SDK automatically detects your module system! Use the same import syntax regardless of whether you're using ES modules or CommonJS:

// Works in both ES modules AND CommonJS projects
import { DCIDServerSDK } from "@dcid/server-sdk";

The SDK is built as a dual package that supports both:

• ES Modules (import/export) - for modern bundlers (Vite, Webpack 5, Rollup, etc.)
• CommonJS (require/module.exports) - for Node.js and older bundlers

When you import the SDK, Node.js or your bundler automatically selects the correct format based on your project's module system.

API Reference

Initialization

const sdk = new DCIDServerSDK({
  environment?: "dev" | "prod", // Optional: Environment (default: "prod")
  apiKey: string, // Required: API key
  timeout?: number, // Optional: Request timeout (default: 30000ms)
  defaultHeaders?: Record<string, string>, // Optional: Default headers
  logger?: Logger, // Optional: Custom logger
  enableRequestLogging?: boolean, // Optional: Enable request logging
});

Authentication Methods

auth.registerOTP(options)

Initiates OTP registration/sign-in process. Covers POST /auth/sign-in/initiate.

Parameters:

• email?: string - User's email address
• phone?: string - User's phone number (with country code)

Returns: Promise<InitiateOTPResponse>

• otp?: string - OTP code (only in dev environment)

Example:

// With email
await sdk.auth.registerOTP({ email: "[email protected]" });

// With phone
await sdk.auth.registerOTP({ phone: "+1234567890" });

auth.confirmOTP(options)

Confirms OTP and completes registration/sign-in. Covers POST /auth/sign-in/confirm.

Parameters:

• email?: string - User's email address
• phone?: string - User's phone number
• otp: string - The OTP code received by the user

Returns: Promise<TokenResponse>

• access_token: string - JWT access token
• refresh_token: string - JWT refresh token

Example:

const tokens = await sdk.auth.confirmOTP({
  email: "[email protected]",
  otp: "123456",
});

// Set tokens for authenticated requests
sdk.setTokens(tokens);

Analytics Methods

if (sdk.analytics) {
  // Start a session
  await sdk.analytics.startSession({
    user_id?: string;
    anonymous_id?: string;
    page_location?: string;
    page_title?: string;
    timestamp?: number;
    engagement_time_msec?: number;
    device_type?: string;
  });
}

Identity Methods

Encryption

// Generate encryption key (will auto-refresh token if expired)
await sdk.identity.encryption.generateKey({
  did: "did:iden3:dcid:main:...",
  ownerEmail: "[email protected]",
});

// Get encrypted key
await sdk.identity.encryption.getKey({
  did: "did:iden3:dcid:main:...",
});

Issuer

// Issue a credential
await sdk.identity.issuer.issueCredential({
  did: "did:iden3:dcid:main:...",
  credentialName: "KYCAgeCredential",
  values: { birthday: 25, documentType: 2 },
});

// Get credential offer (for MTP credentials)
await sdk.identity.issuer.getCredentialOffer({
  claimId: "abc123...",
  txId: "0x1234567890abcdef...",
});

IPFS

// Store credential to IPFS
await sdk.identity.ipfs.storeCredential({
  did: "did:iden3:dcid:main:...",
  credentialType: "KYCAgeCredential",
  credential: "U2FsdGVkX1+vupppZksvRf...",
  encrypted: true,
});

// Retrieve user credential
await sdk.identity.ipfs.retrieveUserCredential({
  did: "did:iden3:dcid:main:...",
  credentialType: "KYCAgeCredential",
  includeCidOnly: false,
});

// Get all user credentials
await sdk.identity.ipfs.getAllUserCredentials({
  did: "did:iden3:dcid:main:...",
  includeCredentialData: false,
});

Module System Support

This SDK uses the Package Exports feature to automatically provide the correct module format:

• ES Modules: Automatically used when your project uses import/export or has "type": "module" in package.json
• CommonJS: Automatically used when your project uses require() or doesn't specify module type

You don't need to change your import syntax - it works the same way in both systems!

TypeScript Support

Full TypeScript support is included. Types are automatically resolved based on your module system.

License

ISC