@usewhisper/sdk 3.9.0 → 3.10.1

package/README.md

@@ -10,15 +10,15 @@ Official TypeScript SDK for [Whisper Context API](https://usewhisper.dev) - Give
 - Legacy wrapper turn helpers now run through the automatic runtime by default.
 - Context query responses expose `meta.source_scope`.
 - URL/domain queries automatically narrow to matching sources when possible.
-
-## Installation
-
-```bash
-npm install @usewhisper/sdk
-```
-
-## Quick Start
-
+
+## Installation
+
+```bash
+npm install @usewhisper/sdk
+```
+
+## Quick Start
+
 ```typescript
 import { WhisperClient } from '@usewhisper/sdk';
 
@@ -27,36 +27,107 @@ const client = new WhisperClient({
   project: 'my-docs'
 });
 
-const runtime = client.createAgentRuntime({
-  workspacePath: process.cwd(),
-  userId: 'user-123',
-  sessionId: 'session-abc',
-  clientName: 'my-agent-host'
+const result = await client.query({
+  query: 'How does authentication work?'
 });
 
-const prepared = await runtime.beforeTurn({
-  userMessage: 'How do I authenticate users?'
+console.log(result.meta.total);
+```
+
+### Typed errors
+
+```typescript
+import { WhisperError } from '@usewhisper/sdk';
+
+try {
+  await client.query({ query: 'How do I authenticate users?' });
+} catch (error) {
+  if (error instanceof WhisperError) {
+    console.error(error.code, error.retryable, error.requestId, error.hint);
+  }
+}
+```
+
+### Preflight (recommended before production)
+
+```typescript
+const preflight = await client.preflight({ requireIdentity: false });
+if (!preflight.ok) {
+  console.error(preflight.checks);
+}
+```
+
+### Framework-native adapters
+
+```typescript
+import { withWhisper } from '@usewhisper/sdk/ai-sdk';
+import { whisperTools } from '@usewhisper/sdk/tools';
+
+const wrappedModel = withWhisper(model, {
+  apiKey: process.env.WHISPER_API_KEY!,
+  project: 'my-docs',
 });
 
-console.log(prepared.context);
+const tools = whisperTools({
+  apiKey: process.env.WHISPER_API_KEY!,
+  project: 'my-docs',
+});
 ```
-
-## Authentication
-
-Get your API key from the [Whisper dashboard](https://usewhisper.dev/dashboard):
-
-```typescript
+
+### Experimental Memory Router (beta)
+
+```typescript
+import { createMemoryRouter } from '@usewhisper/sdk/router';
+
+const router = createMemoryRouter({
+  beta: true, // required until GA
+  apiKey: process.env.WHISPER_API_KEY!,
+  project: 'my-docs',
+  providerBaseUrl: 'https://api.openai.com',
+  providerApiKey: process.env.OPENAI_API_KEY!,
+});
+
+const response = await router.chatCompletions({
+  model: 'gpt-4o-mini',
+  messages: [{ role: 'user', content: 'What did we decide about retries?' }],
+});
+```
+
+### SDK ownership contract
+
+- SDK owns:
+  - auth header wiring and base URL resolution
+  - retries for retryable failures
+  - typed `WhisperError` surface
+  - `client.preflight()` readiness checks
+  - identity-mode guardrails (`demo-local` vs `app-identity`)
+- Caller owns:
+  - authenticated app identity source (`getIdentity` and/or per-call identity)
+  - app-specific retry overrides
+  - application authorization decisions
+
+### Migration policy
+
+- Release `N`: additive contract changes only, deprecations warn.
+- Release `N+1`: deprecated paths may be enforced/removed.
+- Current behavior: `demo-local` in non-local environments emits warnings (warn-only).
+
+## Authentication
+
+Get your API key from the [Whisper dashboard](https://usewhisper.dev/dashboard):
+
+```typescript
 const client = new WhisperClient({
   apiKey: 'wsk_...',  // Your API key
   baseUrl: 'https://context.usewhisper.dev'  // Optional, defaults to production
 });
 ```
-
-## Core Features
-
-### Context Query
-
-```typescript
+
+## Core Features
+
+### Context Query
+
+```typescript
 const result = await client.query({
   project: 'my-docs',
   query: 'Your question here',
@@ -70,189 +141,188 @@ const result = await client.query({
 
 console.log(result.meta.source_scope);
 ```
-
-### Project Management
-
-```typescript
-// 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:
-
-```typescript
-// 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
-
-```typescript
-await whisper.ingest(projectId, [
-  {
-    title: 'Document Title',
-    content: 'Document content...',
-    metadata: { 
-      author: 'John Doe',
-      tags: ['api', 'docs']
-    }
-  }
-]);
-```
-
-### Conversational Memory
-
-```typescript
-// 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
-
-```typescript
-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
-
-```typescript
-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:
-
-```typescript
-import { WhisperContext, QueryParams, QueryResult } from '@usewhisper/sdk';
-```
-
-## Links
-
-- [Documentation](https://docs.usewhisper.dev)
-- [API Reference](https://context.usewhisper.dev)
-- [GitHub](https://github.com/usewhisper/whisper)
-- [Website](https://usewhisper.dev)
-
-## License
-
-MIT
+
+### Project Management
+
+```typescript
+// 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:
+
+```typescript
+// 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
+
+```typescript
+await whisper.ingest(projectId, [
+  {
+    title: 'Document Title',
+    content: 'Document content...',
+    metadata: { 
+      author: 'John Doe',
+      tags: ['api', 'docs']
+    }
+  }
+]);
+```
+
+### Conversational Memory
+
+```typescript
+// 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
+
+```typescript
+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
+- `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
+
+```typescript
+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:
+
+```typescript
+import { WhisperContext, QueryParams, QueryResult } from '@usewhisper/sdk';
+```
+
+## Links
+
+- [Documentation](https://docs.usewhisper.dev)
+- [API Reference](https://context.usewhisper.dev)
+- [GitHub](https://github.com/usewhisper/whisper)
+- [Website](https://usewhisper.dev)
+
+## License
+
+MIT