TypeScript SDK

Fully-typed client library covering every Dual API endpoint with smart retries, rich error hierarchy, and dual auth modes.

The TypeScript SDK (v1.0.0) is a fully-typed client library covering every Dual API endpoint. Every method returns a concrete TypeScript type, no any. Includes smart retries, rich error hierarchy, and dual auth modes.

Installation

bash
npm install dual-sdk

Quick Start

typescript
import { DualClient } from 'dual-sdk';



const dual = new DualClient({

  token: process.env.DUAL_API_KEY,

  authMode: 'api_key',  // 'api_key' | 'bearer' | 'both'

});



// Every method returns typed responses, no `any`

const wallet = await dual.wallets.me();

console.log(wallet.id, wallet.email);  // Wallet type



// Cursor-based pagination with generics

const page = await dual.templates.list({ limit: 20 });

console.log(page.items[0].name);  // Template type

console.log(page.next);           // string | null



// Create an object from a template

const obj = await dual.objects.create({

  templateId: 'tmpl_abc123',

  properties: { name: 'My First Object' }

});

console.log(obj.id);  // DualObject type

Configuration

Supports API key, Bearer token, or both auth modes. Smart retries only on 429 and 5xx with exponential backoff. Custom timeouts and base URL for different environments.

typescript
const dual = new DualClient({

  token: process.env.DUAL_API_KEY,

  authMode: 'api_key',          // 'api_key' | 'bearer' | 'both'

  baseUrl: 'https://api-testnet.dual.network',  // default

  timeout: 30_000,              // 30s default

  retry: {

    maxAttempts: 3,             // retries on 429 and 5xx only

    backoffMs: 1000,            // exponential backoff base

  },

});

Error Handling

All API errors are thrown as typed error subclasses. Catch specific error types for targeted handling, DualAuthError (401), DualNotFoundError (404), DualRateLimitError (429).

typescript
import {

  DualClient,

  DualError,

  DualAuthError,

  DualNotFoundError,

  DualRateLimitError,

} from 'dual-sdk';



const dual = new DualClient({ token: process.env.DUAL_API_KEY, authMode: 'api_key' });



try {

  const obj = await dual.objects.get('missing-id');

} catch (err) {

  if (err instanceof DualNotFoundError) {

    console.error('Not found:', err.code);          // 404

  } else if (err instanceof DualRateLimitError) {

    console.error('Retry after:', err.retryAfter);  // seconds from header

  } else if (err instanceof DualAuthError) {

    console.error('Auth failed, check your token'); // 401

  } else if (err instanceof DualError) {

    console.error('API Error [' + err.status + ']: ' + err.code);

  }

}

Modules

The SDK is organized into 14 modules, each covering a domain of the Dual API. Access them via client.moduleName.

View the full source on GitHub · 14 modules · Fully typed

InstallationQuick StartConfigurationError HandlingModules