Server SDK

The Server SDK provides a type-safe Node.js client for the DialStack API. Use it to manage accounts, users, and create session tokens for embedded components.

Installation

npm install @dialstack/sdk

Quick Start

import { DialStack } from '@dialstack/sdk/server';

const dialstack = new DialStack(process.env.DIALSTACK_API_KEY);

// Create an account
const account = await dialstack.accounts.create({
  email: 'customer@example.com',
});

// Create a user (account context passed in options)
const user = await dialstack.users.create(
  { name: 'John Doe', email: 'john@example.com' },
  { dialstackAccount: account.id }
);

// Create a session for embedded components
const session = await dialstack.accountSessions.create({
  account: account.id,
  components: {
    call_logs: { enabled: true },
    voicemails: { enabled: true },
  },
});

// Return session to frontend
console.log(session.client_secret);

Configuration

Basic Configuration

const dialstack = new DialStack(process.env.DIALSTACK_API_KEY);

Advanced Configuration

const dialstack = new DialStack(process.env.DIALSTACK_API_KEY, {
  apiUrl: 'https://api.dialstack.ai', // Custom API URL
  timeout: 80000, // Request timeout (ms)
  maxNetworkRetries: 2, // Retry count
  telemetry: true, // Enable telemetry
  appInfo: {
    // Your app info (for User-Agent)
    name: 'MyApp',
    version: '1.0.0',
    url: 'https://myapp.com',
  },
});

DialStackConfig Options

Option	Type	Default	Description
apiUrl	string	https://api.dialstack.ai	API base URL
timeout	number	80000	Request timeout in ms
maxNetworkRetries	number	2	Max retry attempts
telemetry	boolean	true	Send usage telemetry
appInfo	AppInfo	-	Application identification

Resources

The SDK provides these resource namespaces:

Resource	Description
accounts	Create and manage customer accounts
users	Manage users within accounts
accountSessions	Create session tokens

Request Options

All methods accept an optional RequestOptions parameter:

const account = await dialstack.accounts.retrieve('acct_123', {
  timeout: 30000, // Override timeout
  maxNetworkRetries: 5, // Override retries
  idempotencyKey: 'abc123', // For safe retries
});

RequestOptions

Option	Type	Description
timeout	number	Override request timeout
maxNetworkRetries	number	Override retry count
idempotencyKey	string	Idempotency key for safe retries
dialstackAccount	string	Account context (for account-scoped ops)

Auto-Pagination

List methods return paginated results with auto-pagination helpers:

Iterate with autoPagingEach

for await (const account of dialstack.accounts.list().autoPagingEach()) {
  console.log(account.id);
}

Collect with autoPagingToArray

const accounts = await dialstack.accounts.list().autoPagingToArray({ limit: 100 });

console.log(`Found ${accounts.length} accounts`);

Manual Pagination

// First page
const page1 = await dialstack.accounts.list({ limit: 10 });
console.log(page1.data);
console.log('Has more:', page1.has_more);

// Next page
if (page1.has_more) {
  const lastId = page1.data[page1.data.length - 1].id;
  const page2 = await dialstack.accounts.list({
    limit: 10,
    starting_after: lastId,
  });
}

Event Listeners

Monitor SDK activity:

dialstack.on('request', (event) => {
  console.log(`${event.method} ${event.path}`);
});

dialstack.on('response', (event) => {
  console.log(`${event.statusCode} in ${event.elapsed}ms`);
});

Event Types

RequestEvent:

interface RequestEvent {
  method: string;
  path: string;
  dialstackAccount?: string;
  idempotencyKey?: string;
  requestStartTime: number;
}

ResponseEvent:

interface ResponseEvent {
  method: string;
  path: string;
  statusCode: number;
  requestId?: string;
  dialstackAccount?: string;
  elapsed: number;
}

Error Handling

The SDK throws typed errors:

import {
  DialStack,
  DialStackError,
  DialStackAuthenticationError,
  DialStackNotFoundError,
  DialStackRateLimitError,
} from '@dialstack/sdk/server';

try {
  await dialstack.accounts.retrieve('invalid_id');
} catch (error) {
  if (error instanceof DialStackNotFoundError) {
    console.log('Account not found');
  } else if (error instanceof DialStackAuthenticationError) {
    console.log('Invalid API key');
  } else if (error instanceof DialStackRateLimitError) {
    console.log(`Rate limited. Retry after ${error.retryAfter}s`);
  } else if (error instanceof DialStackError) {
    console.log('API error:', error.message);
  }
}

Error Classes

Error	HTTP Status	Description
DialStackAuthenticationError	401	Invalid API key
DialStackPermissionError	403	Access denied
DialStackNotFoundError	404	Resource not found
DialStackConflictError	409	Resource conflict
DialStackValidationError	400	Validation failed
DialStackInvalidRequestError	400	Invalid request
DialStackRateLimitError	429	Rate limit exceeded
DialStackAPIError	5xx	Server error
DialStackConnectionError	-	Network error

TypeScript

Full TypeScript support with exported types:

import { DialStack } from '@dialstack/sdk/server';
import type {
  Account,
  AccountCreateParams,
  User,
  UserCreateParams,
  AccountSessionCreateParams,
  AccountSessionCreateResponse,
  DialStackConfig,
  RequestOptions,
} from '@dialstack/sdk/server';

Next Steps

• Accounts - Manage accounts
• Users - Manage users
• Sessions - Create session tokens
• Authentication - Session-based auth flow