Devabase Documentation

import { createClient } from 'devabase-sdk';

// 1. Initialize the client
const client = createClient({
  baseUrl: 'https://your-server.com',
  apiKey: 'dvb_your_api_key'
});

// 2. Set project context (required)
client.useProject('your-project-id');

// 3. Create a collection
await client.collections.create({
  name: 'knowledge-base',
  dimensions: 1536
});

// 4. Upload a document
await client.documents.upload('knowledge-base', {
  file: pdfBuffer,
  filename: 'manual.pdf'
});

// 5. Search your documents
const results = await client.search.query({
  collection: 'knowledge-base',
  query: 'How do I get started?',
  rerank: true
});

// 6. Chat with your documents (RAG)
const response = await client.chat.send({
  collection: 'knowledge-base',
  message: 'Summarize the main features'
});

console.log(response.answer);
console.log(response.sources);

const client = createClient({
  baseUrl: 'https://your-server.com',  // Required
  apiKey: 'dvb_your_api_key',         // Required: starts with 'dvb_'
  timeout: 30000,                     // Optional: request timeout in ms
  headers: { 'X-Custom': 'value' }   // Optional: custom headers
});

// Add an OpenAI LLM provider
await client.providers.llm.upsert({
  id: 'my-openai',
  type: 'openai',         // 'openai' | 'anthropic' | 'google' | 'custom'
  api_key: 'sk-...',
  model: 'gpt-4o-mini'
});

// Add a custom/self-hosted LLM
await client.providers.llm.upsert({
  id: 'local-llm',
  type: 'custom',
  api_key: 'key123',
  base_url: 'http://localhost:8080/v1',
  model: 'llama-3'
});

// Add an OpenAI embedding provider
await client.providers.embedding.upsert({
  id: 'my-embeddings',
  type: 'openai',         // 'openai' | 'cohere' | 'voyage' | 'custom'
  api_key: 'sk-...',
  model: 'text-embedding-3-small',
  dimensions: 1536
});

// List all providers
const llmProviders = await client.providers.llm.list();
const embeddingProviders = await client.providers.embedding.list();

// Test a provider connection
const result = await client.providers.llm.test({
  type: 'openai',
  api_key: 'sk-...',
  model: 'gpt-4o-mini'
});
console.log(result.success, result.message);

const collection = await client.collections.create({
  name: 'my-docs',        // Unique name
  dimensions: 1536,      // Must match embedding model
  metric: 'cosine'        // 'cosine' | 'l2' | 'ip'
});

// List all collections
const { data, pagination } = await client.collections.list({ limit: 50 });

// Get a single collection
const collection = await client.collections.get('my-docs');

// Get collection statistics
const stats = await client.collections.stats('my-docs');
// { name, document_count, chunk_count, total_size_bytes }

// Delete collection (and all documents)
await client.collections.delete('my-docs');

// Update collection RAG config
await client.collections.updateRagConfig('my-docs', {
  llm_provider_id: 'my-llm',
  model: 'gpt-4o-mini',
  system_prompt: 'You are a helpful assistant.'
});

import { readFileSync } from 'fs';

const doc = await client.documents.upload('my-docs', {
  file: readFileSync('document.pdf'),  // Buffer, Blob, or ReadableStream
  filename: 'document.pdf',           // Original filename
  metadata: { author: 'John' }        // Optional metadata
});

// Document status: 'pending' | 'processing' | 'processed' | 'failed'
console.log(doc.status);

// Poll until processed
let doc = await client.documents.upload('my-docs', { file, filename });

while (doc.status === 'pending' || doc.status === 'processing') {
  await new Promise(r => setTimeout(r, 2000));
  doc = await client.documents.get(doc.id);
}

if (doc.status === 'failed') {
  throw new Error(doc.error_message);
}

console.log('Processed!', doc.chunk_count, 'chunks');

// Upload multiple documents
const docs = await client.documents.uploadMany('my-docs', [
  { file: buffer1, filename: 'doc1.pdf' },
  { file: buffer2, filename: 'doc2.pdf' }
]);

// List documents
const { data } = await client.documents.list('my-docs', {
  status: 'processed',
  limit: 50
});

// Get document chunks
const chunks = await client.documents.chunks('document-id');

// Reprocess document (re-chunk and re-embed)
await client.documents.reprocess('document-id');

// Delete document
await client.documents.delete('document-id');

// List all documents across collections
const allDocs = await client.documents.listAll({ status: 'processed' });

const results = await client.search.query({
  collection: 'my-docs',
  query: 'authentication best practices',
  top_k: 10,
  rerank: true,
  filter: { category: 'security' }
});

// Results: Array<{ id, content, score, document_id, document_name, metadata }>

const results = await client.search.hybrid({
  collection: 'my-docs',
  query: 'JWT refresh tokens',
  vector_weight: 0.7,    // 70% vector similarity
  keyword_weight: 0.3,   // 30% keyword matching
  rerank: true
});

const results = await client.search.keyword({
  collection: 'my-docs',
  query: 'authentication',
  top_k: 10
});

// Search across ALL collections in the project
const results = await client.search.global('authentication', {
  top_k: 20,
  rerank: true
});

const response = await client.chat.send({
  collection: 'my-docs',              // string or string[]
  message: 'How do I implement OAuth?',
  include_sources: true,
  top_k: 5
});

console.log(response.answer);
console.log(response.sources);
console.log(response.tokens_used);

await client.chat.stream({
  collection: 'my-docs',
  message: 'Explain the architecture in detail'
}, {
  onSources: (sources) => {
    console.log('Found', sources.length, 'sources');
  },
  onThinking: (text) => {
    console.log('Thinking:', text);
  },
  onContent: (chunk) => {
    process.stdout.write(chunk);
  },
  onDone: (conversationId, tokensUsed) => {
    console.log('\nDone!', tokensUsed, 'tokens');
  },
  onError: (error) => {
    console.error('Error:', error);
  }
});

// Start a conversation
const response1 = await client.chat.send({
  collection: 'my-docs',
  message: 'What is authentication?'
});

// Continue the conversation
const response2 = await client.chat.continue(
  response1.conversation_id,
  'How do I implement it in Node.js?'
);

// List all conversations
const conversations = await client.chat.listConversations({ limit: 20 });

// Delete a conversation
await client.chat.deleteConversation('conversation-id');

await client.tables.create({
  name: 'users',
  columns: [
    { name: 'id', type: 'uuid', primary: true, default: 'gen_random_uuid()' },
    { name: 'email', type: 'varchar(255)', nullable: false, unique: true },
    { name: 'name', type: 'varchar(255)' },
    { name: 'role', type: 'varchar(50)', default: "'user'" },  // Note: inner quotes!
    { name: 'metadata', type: 'jsonb' },
    { name: 'created_at', type: 'timestamptz', default: 'now()' }
  ]
});

const rows = client.tables.rows('users');

// Insert single row
const user = await rows.insert({
  email: 'user@example.com',
  name: 'John Doe',
  metadata: { plan: 'pro' }
});

// Insert multiple rows
const users = await rows.insertMany([
  { email: 'a@b.com', name: 'User A' },
  { email: 'c@d.com', name: 'User B' }
]);

const { rows, pagination } = await client.tables.rows('users').query({
  filter: 'role.eq=admin&created_at.gte=2024-01-01',
  order: 'created_at:desc',
  select: 'id,name,email',
  limit: 20
});

const rows = client.tables.rows('users');

// Get by ID
const user = await rows.get('user-id');

// Find first matching
const admin = await rows.findFirst('email.eq=admin@example.com');

// Update
const updated = await rows.update('user-id', {
  name: 'Jane Doe',
  updated_at: new Date().toISOString()  // Manual timestamp
});

// Delete
await rows.delete('user-id');

// Count
const count = await rows.count('role.eq=admin');

// Check existence
const exists = await rows.exists('user-id');

// Get all (auto-paginated)
const allUsers = await rows.all({ filter: 'role.eq=user' });

// Multiple conditions with &
filter: 'age.gte=18&status.eq=active&name.like=john'

// Offset-based pagination
const page1 = await rows.query({ limit: 20, offset: 0 });
const page2 = await rows.query({ limit: 20, offset: 20 });

// Cursor-based pagination (recommended for large datasets)
const page1 = await rows.query({ limit: 50 });
const page2 = await rows.query({
  cursor: page1.pagination.next_cursor
});

// Pagination metadata
// { total, count, limit, offset, has_next, has_previous, next_cursor, prev_cursor }

// Register
const auth = await client.appAuth.register({
  email: 'user@example.com',
  password: 'securePassword123',
  name: 'John Doe',
  metadata: { plan: 'free' }
});
// Returns: { user, access_token, refresh_token, expires_in }

// Login
const auth = await client.appAuth.login({
  email: 'user@example.com',
  password: 'securePassword123'
});

// Get current user
const user = await client.appAuth.me();

// Update profile
await client.appAuth.updateProfile({ name: 'Jane Doe' });

// Logout
await client.appAuth.logout();

// Request password reset
await client.appAuth.forgotPassword('user@example.com');

// Reset password with token
await client.appAuth.resetPassword(token, 'newPassword123');

// Change password (when logged in)
await client.appAuth.changePassword({
  current_password: 'oldPassword',
  new_password: 'newPassword123'
});

// Refresh token
const newAuth = await client.appAuth.refresh(refreshToken);

// Set token manually
client.appAuth.setToken(accessToken);

// List users
const { data } = await client.appAuth.users.list({ limit: 20 });

// Get user
const user = await client.appAuth.users.get('user-id');

// Update user
await client.appAuth.users.update('user-id', {
  status: 'suspended',
  email_verified: true
});

// Delete user
await client.appAuth.users.delete('user-id');

import {
  DevabaseError,
  AuthenticationError,
  AuthorizationError,
  NotFoundError,
  ValidationError,
  RateLimitError,
  DatabaseError,
  ConfigurationError,
  ExternalServiceError
} from 'devabase-sdk';

try {
  await client.collections.get('non-existent');
} catch (error) {
  if (error instanceof NotFoundError) {
    // Resource not found (404)
  } else if (error instanceof AuthenticationError) {
    // Invalid credentials (401)
  } else if (error instanceof AuthorizationError) {
    // Insufficient permissions (403)
  } else if (error instanceof ValidationError) {
    // Invalid input (400)
    console.log(error.details);
  } else if (error instanceof RateLimitError) {
    // Too many requests (429)
    console.log('Retry after:', error.retryAfter);
  } else if (error instanceof DevabaseError) {
    // Other API error
    console.log(error.code, error.status, error.message);
  }
}

import type {
  Collection,
  Document,
  SearchResult,
  RagChatResponse,
  Table,
  AppUser,
  PaginatedResponse,
  QueryOptions,
  RagStreamCallbacks
} from 'devabase-sdk';

import { createClient } from 'devabase-sdk';
import { readFileSync } from 'fs';

const client = createClient({
  baseUrl: process.env.DEVABASE_URL!,
  apiKey: process.env.DEVABASE_API_KEY!
});
client.useProject(process.env.PROJECT_ID!);

// Setup: Create collection and upload docs
async function setup() {
  await client.collections.create({
    name: 'support-docs',
    dimensions: 1536
  });

  await client.documents.upload('support-docs', {
    file: readFileSync('./docs/faq.pdf'),
    filename: 'faq.pdf'
  });
}

// Chat function
async function chat(message: string, conversationId?: string) {
  return client.chat.send({
    collection: 'support-docs',
    message,
    conversation_id: conversationId,
    include_sources: true
  });
}

// Usage
const response = await chat('How do I reset my password?');
console.log(response.answer);

import { createClient } from 'devabase-sdk';

const client = createClient({ baseUrl: URL, apiKey: KEY });
client.useProject(PROJECT_ID);

// Create posts table
await client.tables.create({
  name: 'posts',
  columns: [
    { name: 'id', type: 'uuid', primary: true, default: 'gen_random_uuid()' },
    { name: 'title', type: 'text', nullable: false },
    { name: 'content', type: 'text' },
    { name: 'author_id', type: 'uuid' },
    { name: 'published', type: 'boolean', default: 'false' },
    { name: 'created_at', type: 'timestamptz', default: 'now()' }
  ]
});

// CRUD operations
const posts = client.tables.rows('posts');

// Create
const post = await posts.insert({
  title: 'Hello World',
  content: 'My first post'
});

// Read
const { rows } = await posts.query({
  filter: 'published.eq=true',
  order: 'created_at:desc',
  limit: 10
});

// Update
await posts.update(post.id, { published: true });

// Delete
await posts.delete(post.id);