@usewhisper/sdk 1.0.1 → 2.0.0

package/README.md

@@ -1,256 +1,256 @@
-# @usewhisper/sdk
-
-Official TypeScript SDK for [Whisper Context API](https://usewhisper.dev) - Give your AI agents perfect context.
-
-## Installation
-
-```bash
-npm install @usewhisper/sdk
-```
-
-## Quick Start
-
-```typescript
-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](https://usewhisper.dev/dashboard):
-
-```typescript
-const whisper = new WhisperContext({
-  apiKey: 'wctx_...',  // Your API key
-  baseUrl: 'https://context.usewhisper.dev'  // Optional, defaults to production
-});
-```
-
-## Core Features
-
-### Context Query
-
-```typescript
-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
-
-```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
+# @usewhisper/sdk
+
+Official TypeScript SDK for [Whisper Context API](https://usewhisper.dev) - Give your AI agents perfect context.
+
+## Installation
+
+```bash
+npm install @usewhisper/sdk
+```
+
+## Quick Start
+
+```typescript
+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](https://usewhisper.dev/dashboard):
+
+```typescript
+const whisper = new WhisperContext({
+  apiKey: 'wctx_...',  // Your API key
+  baseUrl: 'https://context.usewhisper.dev'  // Optional, defaults to production
+});
+```
+
+## Core Features
+
+### Context Query
+
+```typescript
+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
+
+```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