SDK Overview

The DialogueDB TypeScript SDK provides a high-level interface for managing AI conversations. It handles authentication, retries, pagination, and state tracking so you can focus on your application logic.

Installation

npm install dialogue-db

Requirements: Node.js 18 or higher. The SDK is designed for server-side use only — do not use it directly in browser code. See the Troubleshooting FAQ for how to set up a backend proxy.

Quick Start

import { DialogueDB } from 'dialogue-db';

const db = new DialogueDB({ apiKey: process.env.DIALOGUE_DB_API_KEY });

// Create a dialogue with an initial message
const dialogue = await db.createDialogue({
  messages: [{ role: 'user', content: 'Hello!' }]
});

// Add a response (saved immediately)
await dialogue.saveMessage({
  role: 'assistant',
  content: 'Hi there!'
});

// Update conversation state (saved on .save())
dialogue.state = { topic: 'greeting' };
await dialogue.save();

Configuration

DialogueDB Constructor

The recommended way to configure the SDK — each instance carries its own settings:

import { DialogueDB } from 'dialogue-db';

const db = new DialogueDB({
  apiKey: process.env.DIALOGUE_DB_API_KEY,
  endpoint: 'https://api.dialoguedb.com', // default
  retries: 3,           // default, set to 0 to disable
  retryMinTimeout: 1000, // default, in ms
  retryMaxTimeout: 10000 // default, in ms
});

Global Configuration

For the Direct API pattern, configure a global singleton:

import { createConfig, setGlobalConfig } from 'dialogue-db';

// Create a new settings container (does not mutate global)
const settings = createConfig({ apiKey: process.env.DIALOGUE_DB_API_KEY });

// Or mutate the global singleton (used by `api.*` calls)
setGlobalConfig({ apiKey: process.env.DIALOGUE_DB_API_KEY });

Environment Variables

Set DIALOGUE_DB_API_KEY and the SDK picks it up automatically — no explicit configuration needed:

export DIALOGUE_DB_API_KEY=your-api-key

Settings Reference

Setting	Type	Default	Description
apiKey	string	DIALOGUE_DB_API_KEY env var	API key for authentication
endpoint	string	https://api.dialoguedb.com	API base URL
retries	number	3	Max retry attempts for transient errors (0 to disable)
retryMinTimeout	number	1000	Minimum retry delay in milliseconds
retryMaxTimeout	number	10000	Maximum retry delay in milliseconds

Usage Patterns

Class Pattern

The DialogueDB class returns Dialogue, Message, and Memory instances with methods, state tracking, and pagination:

import { DialogueDB } from 'dialogue-db';

const db = new DialogueDB({ apiKey: process.env.DIALOGUE_DB_API_KEY });

const dialogue = await db.createDialogue({
  messages: [{ role: 'user', content: 'Hello' }]
});

// Class instances track dirty state
dialogue.state = { step: 1 };
console.log(dialogue.isDirty); // true
await dialogue.save();
console.log(dialogue.isDirty); // false

Direct API Pattern

The api object provides simple function calls that map 1:1 with REST endpoints and return plain data objects:

import { api, createConfig } from 'dialogue-db';

createConfig({ apiKey: process.env.DIALOGUE_DB_API_KEY });

const dialogue = await api.dialogue.create({
  messages: [{ role: 'user', content: 'Hello' }]
});

const messages = await api.messages.list({ dialogueId: dialogue.id });

Use the class pattern when you need stateful conversation management. Use the direct API when you want straightforward CRUD operations.

Error Handling

All SDK errors are instances of DialogueDBError:

import { DialogueDB, DialogueDBError } from 'dialogue-db';

try {
  const dialogue = await db.getDialogue('nonexistent');
} catch (error) {
  if (error instanceof DialogueDBError) {
    console.log(error.message);    // Human-readable description
    console.log(error.code);       // e.g., 'NOT_FOUND'
    console.log(error.type);       // e.g., 'NOT_FOUND'
    console.log(error.statusCode); // e.g., 404
    console.log(error.requestId);  // For support debugging
    console.log(error.details);    // Field-level validation errors
    console.log(error.retryable);  // true for 429, 5xx, network errors
  }
}

Error Properties

Property	Type	Description
message	string	Human-readable error description
code	string	Machine-readable error code
type	ErrorType	Category: NOT_FOUND, VALIDATION, CONFLICT, RATE_LIMIT, SERVER
statusCode	number	HTTP status code (0 for network errors)
requestId	string?	Request ID from API response
details	ErrorDetail[]?	Field-level validation errors
retryable	boolean	true for network errors, 429, and 5xx

Automatic Retries

The SDK automatically retries transient errors (network failures, 429 rate limits, 5xx server errors) with exponential backoff. Configure via the retries, retryMinTimeout, and retryMaxTimeout settings.

Exported Types

// Classes
import { DialogueDB, Dialogue, Message, Memory, DialogueDBError } from 'dialogue-db';

// Types (use `import type`)
import type {
  IDialogue,
  IMessage,
  IMemory,
  CreateDialogueInput,
  UpdateDialogueInput,
  GetDialogueInput,
  CreateMessageInput,
  CreateMemoryInput,
  ListDialogueFilters,
  ListMessageFilters,
  ListMemoriesFilters,
  ListResponse,
  MessageContent,
  SearchOptions,
  SearchFilterOptions,
  Settings,
  ErrorType
} from 'dialogue-db';

Next Steps

• Dialogue Reference — DialogueDB and Dialogue class methods
• Messages Reference — Message class and creation patterns
• Memory & Search Reference — Memory management and semantic search