DUAL SDK

Fully-typed TypeScript client library for the DUAL Platform API v3. Provides 102 methods across 14 modules with built-in retry logic, error handling, and automatic token management.

Features

• 102 API Methods across 14 modules
• Fully Typed TypeScript interfaces and classes
• Automatic Retry Logic with exponential backoff
• Token Management with JWT bearer authentication
• Request Timeout configuration
• Zero Dependencies for production (TypeScript only)
• Modular Organization with focused domain modules

Installation

npm install @dual/sdk
# or
yarn add @dual/sdk

Quick Start

import { DualClient, DualConfig } from '@dual/sdk';

const client = new DualClient({
  token: 'your-jwt-token',
  baseUrl: 'https://blockv-labs.io',
  timeout: 30000,
  retry: {
    maxAttempts: 3,
    backoffMs: 1000
  }
});

// Get current wallet
const wallet = await client.wallets.getCurrentWallet();
console.log(wallet);

// List templates
const templates = await client.templates.listTemplates();

// List objects with pagination
const objects = await client.objects.listObjects({ limit: 10 });

API Modules

The SDK is organized into 14 focused modules:

1. Payments (2 methods)

• getPaymentConfig() - Retrieve payment configuration
• listDeposits() - List all deposits

2. Support (4 methods)

• requestAccess() - Request access to a feature
• listSupportMessages() - Retrieve support messages
• sendSupportMessage() - Send a support message
• getSupportMessage() - Retrieve a specific message

3. Organizations (17 methods)

• listOrganizations() - List all organizations
• createOrganization() - Create new organization
• getOrganization() - Get organization details
• updateOrganization() - Update organization
• getOrganizationBalance() - Get balance
• getBalanceHistory() - Get balance history
• listMembers() - List members
• addMember() - Add member
• removeMember() - Remove member
• updateMemberRole() - Update member role
• listRoles() - List roles
• createRole() - Create role
• updateRole() - Update role
• deleteRole() - Delete role
• createInvitation() - Create invitation
• listInvitations() - List invitations
• deleteInvitation() - Delete invitation
• acceptInvitation() - Accept invitation

4. Event Bus / Actions (8 methods)

• executeAction() - Execute an action
• listActions() - List available actions
• getAction() - Get action details
• executeBatchActions() - Execute batch actions
• listActionTypes() - List action types
• createActionType() - Create action type
• getActionType() - Get action type details
• updateActionType() - Update action type

5. Wallets (14 methods)

• login() - Login with wallet
• guestLogin() - Guest login
• requestResetCode() - Request password reset
• verifyResetCode() - Verify reset code
• register() - Register new wallet
• verifyRegistration() - Verify registration
• getCurrentWallet() - Get current wallet
• updateCurrentWallet() - Update current wallet
• deleteCurrentWallet() - Delete current wallet
• getLinkedWallets() - Get linked wallets
• getWalletById() - Get wallet by ID
• getLinkedWalletsById() - Get linked wallets by ID
• linkWallet() - Link wallet
• refreshToken() - Refresh access token

6. API Keys (3 methods)

• listApiKeys() - List API keys
• createApiKey() - Create API key
• deleteApiKey() - Delete API key

7. Templates (7 methods)

• listTemplates() - List templates
• createTemplate() - Create template
• getTemplate() - Get template
• updateTemplate() - Update template
• deleteTemplate() - Delete template
• listVariations() - List template variations
• createVariation() - Create template variation

8. Objects (9 methods)

• listObjects() - List objects
• getObject() - Get object
• updateObject() - Update object
• getObjectChildren() - Get object children
• getObjectParents() - Get object parents
• getObjectActivity() - Get object activity
• getObjectsByGeo() - Get objects by geo location
• searchObjects() - Search objects
• countObjects() - Count objects

9. Faces (6 methods)

• listFaces() - List faces
• createFace() - Create face
• getFace() - Get face
• updateFace() - Update face
• deleteFace() - Delete face
• getFacesByTemplate() - Get faces by template

10. Storage (5 methods)

• uploadFile() - Upload file
• getFile() - Get file
• deleteFile() - Delete file
• getTemplateAssets() - Get template assets
• uploadTemplateAsset() - Upload template asset

11. Notifications (7 methods)

• listMessages() - List messages
• sendMessage() - Send message
• listMessageTemplates() - List message templates
• getMessageTemplate() - Get message template
• createMessageTemplate() - Create message template
• updateMessageTemplate() - Update message template
• deleteMessageTemplate() - Delete message template

12. Webhooks (6 methods)

• listWebhooks() - List webhooks
• createWebhook() - Create webhook
• getWebhook() - Get webhook
• updateWebhook() - Update webhook
• deleteWebhook() - Delete webhook
• testWebhook() - Test webhook

13. Sequencer (4 methods)

• listBatches() - List batches
• getBatch() - Get batch
• listCheckpoints() - List checkpoints
• getCheckpoint() - Get checkpoint

14. Indexer / Public API (7 methods)

• listPublicTemplates() - List public templates
• getPublicTemplate() - Get public template
• getPublicObject() - Get public object
• searchPublicObjects() - Search public objects
• getPublicFacesByTemplate() - Get public faces by template
• getPublicOrganization() - Get public organization
• getPublicStats() - Get public statistics

Configuration

DualConfig Interface

interface DualConfig {
  /** API access token (JWT) */
  token?: string;

  /** Base URL for API requests */
  baseUrl?: string;

  /** Request timeout in milliseconds */
  timeout?: number;

  /** Custom fetch implementation */
  fetch?: typeof fetch;

  /** Retry configuration */
  retry?: {
    maxAttempts?: number;
    backoffMs?: number;
  };
}

Default Values

• baseUrl: https://blockv-labs.io
• timeout: 30000 (30 seconds)
• maxAttempts: 3
• backoffMs: 1000

Error Handling

DualError Class

All API errors are thrown as DualError instances:

export class DualError extends Error {
  public status: number;      // HTTP status code
  public code: string;        // Error code
  public body: any;           // Response body
}

Error Handling Example

import { DualClient, DualError } from '@dual/sdk';

try {
  await client.wallets.getCurrentWallet();
} catch (error) {
  if (error instanceof DualError) {
    console.error(`Error [${error.code}]: ${error.status}`);
    console.error(error.body);
  } else {
    console.error('Unknown error:', error);
  }
}

Authentication

Bearer JWT Token

The SDK uses JWT bearer token authentication by default:

const client = new DualClient({
  token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'
});

Getting a Token

curl -X POST https://blockv-labs.io/wallets/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "password"
  }'

Response:

{
  "token": "eyJhbGc...",
  "refreshToken": "refresh_token_here"
}

API Key Authentication

For service-to-service communication, use API keys:

POST /api-keys
Authorization: Bearer <jwt_token>
Content-Type: application/json

{
  "name": "My Service"
}

Then use the key in requests:

// Pass via config (custom implementation needed)
const client = new DualClient({
  token: 'api_key_...'
});

Pagination

The SDK uses cursor-based pagination. Include a cursor parameter in query options:

// First page
const result = await client.objects.listObjects({ limit: 10 });
console.log(result.data);

// Next page
if (result.hasMore) {
  const nextPage = await client.objects.listObjects({
    cursor: result.cursor,
    limit: 10
  });
}

Response format:

{
  "data": [...],
  "cursor": "next_cursor_value",
  "hasMore": true
}

Retry & Timeout Configuration

Automatic Retry

The SDK automatically retries failed requests with exponential backoff:

const client = new DualClient({
  retry: {
    maxAttempts: 3,      // Retry up to 3 times
    backoffMs: 1000      // Start with 1s delay, then 2s, 4s, etc.
  }
});

Request Timeout

Configure request timeout in milliseconds:

const client = new DualClient({
  timeout: 60000  // 60 seconds
});

API Reference

For the complete API reference, visit: https://dual-docs.vercel.app/docs/developer-kit/sdk

Examples

Get Current Wallet

const wallet = await client.wallets.getCurrentWallet();
console.log(wallet);

List Templates

const templates = await client.templates.listTemplates({
  limit: 20
});
console.log(templates);

Create Object

const obj = await client.objects.updateObject('object_id', {
  properties: { name: 'Updated Name' }
});

Search Objects

const results = await client.objects.searchObjects({
  query: 'my items',
  limit: 50
});

Execute Action

const result = await client.ebus.executeAction({
  objectId: 'obj_123',
  actionType: 'transfer',
  target: 'user_456'
});

Create Webhook

const webhook = await client.webhooks.createWebhook({
  url: 'https://myapp.com/webhook',
  events: ['object.created', 'object.updated']
});

List Organizations

const orgs = await client.organizations.listOrganizations();
console.log(orgs);

Testing

npm test

Building

Compile TypeScript to JavaScript:

npm run build

Output goes to the dist/ directory with type definitions.

Contributing

Contributions are welcome! Please ensure:

1. Code follows TypeScript best practices
2. All methods are properly typed
3. Error handling is comprehensive
4. Documentation is updated

Support

• Documentation: https://dual-docs.vercel.app
• GitHub Issues: https://github.com/ro-ro-b/dual-sdk/issues
• Discord: https://discord.gg/dual

Related Repositories

• dual-cli - Command-line interface
• dual-postman - Postman collection
• dual-openapi - OpenAPI specification
• dual-migration-guide - v2 to v3 migration
• dual-developer-kit - Complete developer kit

License

MIT - Copyright (c) 2025 DUAL Platform