API Reference

Complete API reference for the .do SDK including database, AI, user, and event APIs

Complete API reference for all core SDK objects and methods in the .do platform.

Overview

The .do SDK provides a unified, semantic interface for building autonomous business applications. All APIs follow the $.Subject.predicate.Object pattern for consistency and discoverability.

Core APIs

Database API

CRUD operations, queries, and relationships

AI API

Text generation, chat, embeddings, and batch operations

User API

Authentication, sessions, and permissions

Events API

Pub/sub messaging, webhooks, and scheduled tasks

Quick Start

import { db, ai, user, on, send, every } from 'sdk.do'

// Database operations
db.Users.list()
db.Users.get('user-123')
db.Users.create({ name: 'Alice' })

// AI operations
ai.generate('Write a blog post')
ai.chat([{ role: 'user', content: 'Hello' }])
ai.embed('semantic search')

// User operations
user.current()
user.session()
user.hasPermission('posts:edit')

// Event operations
on.User.created((event) => {
  sendWelcomeEmail(event.data.user)
})

send.User.created({ user: newUser })

every.Cleanup.sessions('1 hour', () => {
  cleanupExpiredSessions()
})

API Design Principles

Semantic Naming

All APIs use semantic, human-readable names:

// Database - clear CRUD operations
db.Posts.list()
db.Posts.get(id)
db.Posts.create(data)
db.Posts.update(id, data)
db.Posts.delete(id)
db.Users.related(id, 'posts')

// AI - semantic generators
ai.generate('prompt')
ai.generatePost('topic')
ai.generateEmail('subject')
ai.chat(messages)
ai.embed('text')

// User - straightforward auth
user.current()
user.session()
user.hasPermission('posts:edit')

// Events - pub/sub pattern
on.User.created(handler)
send.User.created(data)
every.Task('1 hour', task)

Type Safety

Full TypeScript support with generated types:

import type { User, Post } from 'sdk.do/types'

db.Users.get(id).then((user: User) => {
  db.Posts.list().then((result) => {
    const posts: Post[] = result.docs
  })
})

// Type-safe event payloads
interface UserCreatedEvent {
  user: User
}

on.User.created<UserCreatedEvent>((event) => {
  console.log(event.data.user.email)
})

Promise-Based

All async operations return promises:

// All async operations
db.Posts.create(data)
ai.generate('prompt')
user.current()
send.Event(data)

// capnweb RPC handles errors automatically

Consistent Error Handling

capnweb RPC provides automatic error handling at the protocol level, eliminating the need for explicit try-catch blocks in most cases.

Common Patterns

CRUD Operations

// List with filters
db.Posts.list({
  where: { status: { equals: 'published' } },
  sort: '-createdAt',
  limit: 10,
})

// Get with relationships
db.Posts.get(id, { depth: 1 })

// Create with validation
db.Posts.create({
  title: 'New Post',
  content: '...',
  author: user.id,
})

// Update partial fields
db.Posts.update(id, {
  title: 'Updated Title',
})

// Delete
db.Posts.delete(id)

AI Operations

// Generate text
ai.generate('Write a blog post about AI')

// Chat conversation
ai.chat([{ role: 'user', content: 'What is TypeScript?' }])

// Generate embeddings
ai.embed('Machine learning')

// Batch operations
ai.batch([
  { type: 'generate', prompt: 'Summarize...' },
  { type: 'embed', text: 'Search query' },
])

Authentication

// Check authentication
user.current().then((currentUser) => {
  if (!currentUser) {
    window.location.href = '/login'
  }
})

// Check permissions
user.hasPermission('posts:edit').then((canEdit) => {
  if (canEdit) {
    db.Posts.update(id, updates)
  }
})

// Session management
user.session().then((session) => {
  if (session.expiresAt < new Date()) {
    user.refreshSession()
  }
})

Event-Driven

// Subscribe to events
on.Post.published((event) => {
  send.Cache.invalidate({ pattern: 'posts/*' })
  send.Search.index({ post: event.data.post })
  send.Notification({ subscribers: event.data.subscribers })
})

// Publish events
send.Post.published({
  post,
  author,
  subscribers,
})

// Schedule tasks
every.Cleanup.sessions('1 hour', () => {
  cleanupExpiredSessions()
})

Authentication

All API calls respect authentication and permissions:

// Authenticated automatically from session
db.Posts.list()

// Access control enforced (capnweb RPC handles automatically)
db.Posts.delete(id)

// Permission checks
user.hasPermission('posts:delete')

Rate Limiting

capnweb RPC handles rate limiting automatically at the protocol level.

Error Codes

Standard error codes across all APIs:

400 - Bad Request (validation errors)
401 - Unauthorized (not authenticated)
403 - Forbidden (insufficient permissions)
404 - Not Found (resource doesn't exist)
409 - Conflict (duplicate or constraint violation)
422 - Unprocessable Entity (invalid data)
429 - Too Many Requests (rate limited)
500 - Internal Server Error

Environment

All APIs work in multiple environments:

// Client-side (browser)
user.current()

// Server-side (Node.js)
db.Posts.list()

// Edge runtime (Cloudflare Workers)
ai.generate('prompt')

// Mobile (React Native)
user.session()

SDK Overview - Introduction to the .do SDK
Getting Started - Quick start guide
Examples - Code examples
Best Practices - API usage patterns

API Reference

Database API

AI API

User API

Events API

On this page