@usewhisper/sdk

Official TypeScript SDK for Whisper Context API - Give your AI agents perfect context.

Installation

npm install @usewhisper/sdk

Quick Start

import { WhisperContext } from '@usewhisper/sdk';

const whisper = new WhisperContext({ 
  apiKey: 'wctx_your_api_key_here'
});

// Create a project
const project = await whisper.createProject({
  name: 'my-docs',
  description: 'Documentation context'
});

// Ingest documents
await whisper.ingest(project.id, [
  {
    title: 'Authentication Guide',
    content: 'To authenticate users, use JWT tokens...',
    metadata: { category: 'auth' }
  }
]);

// Query context
const result = await whisper.query({
  project: 'my-docs',
  query: 'How do I authenticate users?',
  top_k: 5
});

console.log(result.context);

Authentication

Get your API key from the Whisper dashboard:

const whisper = new WhisperContext({
  apiKey: 'wctx_...',  // Your API key
  baseUrl: 'https://context.usewhisper.dev'  // Optional, defaults to production
});

Core Features

Context Query

const result = await whisper.query({
  project: 'my-docs',
  query: 'Your question here',
  top_k: 10,              // Number of results
  include_memories: true,  // Include conversational memory
  include_graph: true,     // Include knowledge graph
  hybrid: true,            // Hybrid vector + keyword search
  rerank: true            // Rerank results for better relevance
});

Project Management

// Create project
await whisper.createProject({ name: 'my-project' });

// List projects
const { projects } = await whisper.listProjects();

// Get project details
const project = await whisper.getProject(projectId);

// Delete project
await whisper.deleteProject(projectId);

Data Sources

Connect 15+ auto-sync sources:

// GitHub repository
await whisper.addSource(projectId, {
  name: 'GitHub Repo',
  connector_type: 'github',
  config: { 
    repo: 'owner/repo',
    token: 'ghp_...',
    branch: 'main'
  },
  sync_schedule: '0 */6 * * *'  // Sync every 6 hours
});

// Notion workspace
await whisper.addSource(projectId, {
  name: 'Notion Docs',
  connector_type: 'notion',
  config: { 
    token: 'secret_...',
    database_id: '...'
  }
});

// Sync source manually
await whisper.syncSource(sourceId);

Direct Ingestion

await whisper.ingest(projectId, [
  {
    title: 'Document Title',
    content: 'Document content...',
    metadata: { 
      author: 'John Doe',
      tags: ['api', 'docs']
    }
  }
]);

Conversational Memory

// Add memory
await whisper.addMemory({
  project: 'my-docs',
  content: 'User prefers dark mode',
  memory_type: 'factual',
  user_id: 'user123',
  importance: 0.8
});

// Search memories
const { memories } = await whisper.searchMemories({
  project: 'my-docs',
  query: 'user preferences',
  user_id: 'user123',
  top_k: 10
});

Supported Connectors

• GitHub - Repositories, issues, PRs
• GitLab - Projects, issues, MRs
• Notion - Pages, databases
• Confluence - Spaces, pages
• Slack - Channels, messages
• Discord - Channels, messages
• URLs - Web pages
• Sitemaps - Entire websites
• PDFs - PDF documents
• API Specs - OpenAPI/Swagger
• Databases - PostgreSQL, MySQL
• npm - Package documentation
• PyPI - Package documentation
• arXiv - Research papers
• HuggingFace - Model docs

API Reference

WhisperContext

Constructor

new WhisperContext(config: {
  apiKey: string;
  baseUrl?: string;
})

Methods

Projects:

• createProject(params) - Create a new project
• listProjects() - List all projects
• getProject(id) - Get project details
• deleteProject(id) - Delete a project

Sources:

• addSource(projectId, params) - Add a data source
• listSources(projectId) - List project sources
• syncSource(sourceId) - Manually sync a source
• updateSource(sourceId, params) - Update source config
• deleteSource(sourceId) - Delete a source

Context:

• query(params) - Query context from your data
• ingest(projectId, documents) - Directly ingest documents

Memory:

• addMemory(params) - Add conversational memory
• searchMemories(params) - Search memories
• listMemories(params) - List all memories
• updateMemory(id, params) - Update a memory
• deleteMemory(id) - Delete a memory

API Keys:

• createApiKey(params) - Create a new API key
• listApiKeys() - List all API keys
• deleteApiKey(id) - Delete an API key

Usage:

• getUsage(days) - Get usage statistics

Error Handling

try {
  const result = await whisper.query({
    project: 'my-docs',
    query: 'test'
  });
} catch (error) {
  if (error.message.includes('401')) {
    console.error('Invalid API key');
  } else if (error.message.includes('404')) {
    console.error('Project not found');
  } else {
    console.error('Query failed:', error.message);
  }
}

TypeScript Support

Full TypeScript support with type definitions included:

import { WhisperContext, QueryParams, QueryResult } from '@usewhisper/sdk';

Links

• Documentation
• API Reference
• GitHub
• Website

License

MIT