SDK Usage Guide

import { Orchata } from '@orchata-ai/sdk';

const client = new Orchata({
  // Required: Your API key
  apiKey: 'oai_xxx',

  // Optional: Custom base URL (default: https://api.orchata.ai)
  baseUrl: 'https://api.orchata.ai',

  // Optional: Request timeout in ms (default: 30000)
  timeout: 30000,

  // Optional: Custom fetch implementation
  fetch: customFetch
});

const { spaces, total } = await client.spaces.list();

console.log(`Found ${total} spaces`);
spaces.forEach(space => {
  console.log(`${space.name}: ${space.id}`);
});

const { spaces } = await client.spaces.list({
  metadata: { team: 'engineering' }
});

const { space } = await client.spaces.create({
  name: 'Documentation',
  description: 'Product documentation and guides',
  icon: 'book', // Optional: 'folder', 'book', 'file-text', 'database', etc.
  metadata: { // Optional
    team: 'engineering',
    project: 'api-v2'
  }
});

console.log(`Created space: ${space.id}`);

const { space } = await client.spaces.get('space_123');
console.log(space.name, space.description);

const { space } = await client.spaces.update('space_123', {
  name: 'Updated Name',
  description: 'New description',
  icon: 'database',
  metadata: { team: 'product', priority: 'high' }
});

await client.spaces.delete('space_123');

const limits = await client.spaces.getLimits('space_123');

console.log(`${limits.documents.current} / ${limits.documents.max} documents`);
console.log(`${limits.documents.remaining} remaining`);

const { documents, total } = await client.documents.list({
  spaceId: 'space_123'
});

documents.forEach(doc => {
  console.log(`${doc.filename} - Status: ${doc.status}`);
});

const { documents } = await client.documents.list({
  spaceId: 'space_123',
  metadata: { category: 'docs', version: '2.0' }
});

const { document } = await client.documents.upload({
  spaceId: 'space_123',
  content: '# Getting Started\n\nWelcome to our product!',
  filename: 'getting-started.md',
  metadata: { // Optional
    category: 'docs',
    version: '1.0'
  }
});

console.log(`Document ID: ${document.id}`);

const result = await client.documents.batchUpload({
  spaceId: 'space_123',
  documents: [
    { filename: 'doc1.md', content: '# Doc 1\n\nContent...' },
    { filename: 'doc2.md', content: '# Doc 2\n\nContent...' }
  ]
});

console.log(`Uploaded: ${result.totalSuccessful}, Failed: ${result.totalFailed}`);

const { content } = await client.documents.getContent('doc_123', 'space_123');
console.log(content);

const { document, created } = await client.documents.upsert({
  spaceId: 'space_123',
  filename: 'readme.md',
  content: '# Updated README\n\nNew content...',
  metadata: { version: '2.0' }
});

console.log(created ? 'Created' : 'Updated', document.id);

const { document } = await client.documents.append('doc_123', {
  spaceId: 'space_123',
  content: '## New Section\n\nAdditional content...',
  separator: '\n\n---\n\n' // Optional, defaults to double newline
});

const doc = await client.documents.getByFilename({
  spaceId: 'space_123',
  filename: 'readme.md'
});

console.log(doc.content);

const { document } = await client.documents.update('doc_123', {
  spaceId: 'space_123',
  metadata: { category: 'updated' }
});

await client.documents.delete('doc_123', 'space_123');

const { results } = await client.query({
  spaceIds: 'space_123',
  query: 'How do I authenticate?'
});

results.forEach(result => {
  console.log(`Score: ${result.similarity}`);
  console.log(`Content: ${result.chunk.content}`);
  console.log(`Document: ${result.document.filename}`);
});

const { results } = await client.query({
  spaceIds: ['space_123', 'space_456'],
  query: 'authentication',
  topK: 5 // Return top 5 results
});

const { results } = await client.query({
  spaceIds: 'space_123',
  query: 'API reference',
  metadata: { category: 'docs' }
});

const { groupedBySpace } = await client.query({
  spaceIds: ['space_123', 'space_456'],
  query: 'authentication',
  groupBySpace: true
});

// Access results grouped by space
for (const [spaceId, results] of Object.entries(groupedBySpace)) {
  console.log(`Space ${spaceId}: ${results.length} results`);
}

const { relevantSpaces } = await client.smartQuery({
  query: 'How do I authenticate users?',
  maxSpaces: 3
});

relevantSpaces.forEach(rec => {
  console.log(`${rec.space.name}: ${rec.relevanceScore}`);
});

// Keyword matching
const { relevantSpaces } = await client.smartQuery({
  query: 'authentication',
  relevanceMethod: 'keyword'
});

// Embedding-based similarity
const { relevantSpaces } = await client.smartQuery({
  query: 'authentication',
  relevanceMethod: 'embedding'
});

// Hybrid (default) - combines both methods
const { relevantSpaces } = await client.smartQuery({
  query: 'authentication',
  relevanceMethod: 'hybrid',
  keywordWeight: 0.5 // Weight for keyword vs embedding (0-1)
});

// Step 1: Discover relevant spaces
const { relevantSpaces } = await client.smartQuery({
  query: 'user authentication'
});

// Step 2: Query the recommended spaces
const { results } = await client.query({
  spaceIds: relevantSpaces.map(rec => rec.space.id),
  query: 'user authentication'
});