@usewhisper/sdk 3.10.0 → 3.11.0

package/README.md

@@ -1,15 +1,15 @@
-# @usewhisper/sdk
-
-Official TypeScript SDK for [Whisper Context API](https://usewhisper.dev) - Give your AI agents perfect context.
-
-`WhisperClient` is the primary SDK surface. `WhisperContext` remains available for compatibility, but automatic memory/retrieval behavior now lives in `WhisperClient.createAgentRuntime()`.
-
-## What's New in v3.6
-
-- Automatic runtime for scope resolution, pre-retrieval, session continuity, and background capture.
-- 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.
+# @usewhisper/sdk
+
+Official TypeScript SDK for [Whisper Context API](https://usewhisper.dev) - Give your AI agents perfect context.
+
+`WhisperClient` is the primary SDK surface. `WhisperContext` remains available for compatibility, but automatic memory/retrieval behavior now lives in `WhisperClient.createAgentRuntime()`.
+
+## What's New in v3.6
+
+- Automatic runtime for scope resolution, pre-retrieval, session continuity, and background capture.
+- 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
 
@@ -17,59 +17,163 @@ Official TypeScript SDK for [Whisper Context API](https://usewhisper.dev) - Give
 npm install @usewhisper/sdk
 ```
 
+## Simple API (quickstart)
+
+Four methods cover the most common use cases. The full `learn()` / `query()` signatures with all options are documented further below for power users.
+
+```typescript
+import { WhisperClient } from '@usewhisper/sdk';
+
+const whisper = new WhisperClient({
+  apiKey: process.env.WHISPER_API_KEY!,
+  project: 'my-project',
+});
+
+// Store a conversation — sessionId is auto-generated if omitted
+await whisper.remember({
+  messages: [
+    { role: 'user', content: 'I prefer TypeScript over JavaScript' },
+    { role: 'assistant', content: 'Got it, I will use TypeScript.' },
+  ],
+  userId: req.user.id,  // required unless getIdentity() is configured on the client
+});
+
+// Index a source — type is auto-detected from the URL
+await whisper.ingest({ url: 'https://github.com/your-org/your-repo' });
+await whisper.ingest({ url: 'https://docs.example.com' });
+await whisper.ingest({ url: 'https://youtube.com/watch?v=abc123' });
+
+// Query with short aliases — include_memories defaults to true when not specified
+const { context } = await whisper.query({ q: userMessage, userId: req.user.id });
+
+// Get everything Whisper knows about a user
+const profile = await whisper.userProfile(req.user.id);
+```
+
 ## Quick Start
 
-```typescript
-import { WhisperClient } from '@usewhisper/sdk';
-
-const client = new WhisperClient({
-  apiKey: 'wsk_your_api_key_here',
-  project: 'my-docs'
-});
-
-const runtime = client.createAgentRuntime({
-  workspacePath: process.cwd(),
-  userId: 'user-123',
-  sessionId: 'session-abc',
-  clientName: 'my-agent-host'
-});
-
-const prepared = await runtime.beforeTurn({
-  userMessage: 'How do I authenticate users?'
-});
-
-console.log(prepared.context);
-```
+```typescript
+import { WhisperClient } from '@usewhisper/sdk';
+
+const client = new WhisperClient({
+  apiKey: 'wsk_your_api_key_here',
+  project: 'my-docs'
+});
+
+const result = await client.query({
+  query: 'How does authentication work?'
+});
+
+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',
+});
+
+const tools = whisperTools({
+  apiKey: process.env.WHISPER_API_KEY!,
+  project: 'my-docs',
+});
+```
+
+### 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
-});
-```
+const client = new WhisperClient({
+  apiKey: 'wsk_...',  // Your API key
+  baseUrl: 'https://context.usewhisper.dev'  // Optional, defaults to production
+});
+```
 
 ## Core Features
 
 ### Context Query
 
 ```typescript
-const result = await client.query({
-  project: 'my-docs',
-  query: 'Your question here',
-  top_k: 10,              // Number of results
-  source_ids: ['src_abc'], // Optional explicit source isolation
-  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
-});
-
-console.log(result.meta.source_scope);
-```
+const result = await client.query({
+  project: 'my-docs',
+  query: 'Your question here',
+  top_k: 10,              // Number of results
+  source_ids: ['src_abc'], // Optional explicit source isolation
+  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
+});
+
+console.log(result.meta.source_scope);
+```
 
 ### Project Management
 
@@ -197,7 +301,6 @@ new WhisperContext(config: {
 - `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:**