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.

Project Setup

The SDK uses top-level await in examples. Add "type": "module" to your package.json, or wrap code in an async function.

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();

Methods

Method	Description	Reference
createDialogue(input)	Create a new dialogue	Dialogues
getDialogue(id, opts?)	Get a dialogue by ID (returns null if not found)	Dialogues
getOrCreateDialogue(input?)	Get or create a dialogue	Dialogues
listDialogues(opts?)	List dialogues with filters	Dialogues
deleteDialogue(id, opts?)	Delete a dialogue	Dialogues
createMemory(input)	Create a memory	Memory & Search
getMemory(id, opts?)	Get a memory by ID	Memory & Search
listMemories(opts?)	List memories	Memory & Search
deleteMemory(id, opts?)	Delete a memory	Memory & Search
searchDialogues(query, opts?)	Semantic search over dialogues	Memory & Search
searchMessages(query, opts?)	Semantic search over messages	Memory & Search
searchMemories(query, opts?)	Semantic search over memories	Memory & Search

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 {
  // Note: getDialogue() returns null for not-found - it doesn't throw.
  // Methods that modify data (saveMessage, end, delete) throw on errors.
  const dialogue = await db.createDialogue({
    messages: [{ role: 'user', content: 'Hello' }]
  });
  await dialogue.saveMessage({ role: 'user', content: '' }); // empty content → error
} catch (error) {
  if (error instanceof DialogueDBError) {
    console.log(error.message);    // Human-readable description
    console.log(error.code);       // e.g., 'MESSAGE_CONTENT_EMPTY'
    console.log(error.type);       // e.g., 'validation_error'
    console.log(error.statusCode); // e.g., 400
    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: validation_error, authentication_error, authorization_error, not_found, conflict, rate_limit_exceeded, server_error, service_unavailable
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