@usewhisper/sdk 0.1.0

package/README.md

@@ -0,0 +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

package/index.cjs

@@ -0,0 +1,117 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/sdk/index.ts
+var index_exports = {};
+__export(index_exports, {
+  WhisperContext: () => WhisperContext,
+  default: () => index_default
+});
+module.exports = __toCommonJS(index_exports);
+var WhisperContext = class {
+  apiKey;
+  baseUrl;
+  constructor(config) {
+    if (!config.apiKey) {
+      throw new Error("API key is required");
+    }
+    this.apiKey = config.apiKey;
+    this.baseUrl = config.baseUrl || "https://context.usewhisper.dev";
+  }
+  async request(endpoint, options = {}) {
+    const response = await fetch(`${this.baseUrl}${endpoint}`, {
+      ...options,
+      headers: {
+        Authorization: `Bearer ${this.apiKey}`,
+        "Content-Type": "application/json",
+        ...options.headers
+      }
+    });
+    if (!response.ok) {
+      const error = await response.json().catch(() => ({ error: "Request failed" }));
+      throw new Error(error.error || `HTTP ${response.status}: ${response.statusText}`);
+    }
+    return response.json();
+  }
+  async query(params) {
+    return this.request("/v1/context/query", {
+      method: "POST",
+      body: JSON.stringify(params)
+    });
+  }
+  async createProject(params) {
+    return this.request("/v1/projects", {
+      method: "POST",
+      body: JSON.stringify(params)
+    });
+  }
+  async listProjects() {
+    return this.request("/v1/projects");
+  }
+  async getProject(id) {
+    return this.request(`/v1/projects/${id}`);
+  }
+  async deleteProject(id) {
+    return this.request(`/v1/projects/${id}`, { method: "DELETE" });
+  }
+  async addSource(projectId, params) {
+    return this.request(`/v1/projects/${projectId}/sources`, {
+      method: "POST",
+      body: JSON.stringify(params)
+    });
+  }
+  async syncSource(sourceId) {
+    return this.request(`/v1/sources/${sourceId}/sync`, { method: "POST" });
+  }
+  async ingest(projectId, documents) {
+    return this.request(`/v1/projects/${projectId}/ingest`, {
+      method: "POST",
+      body: JSON.stringify({ documents })
+    });
+  }
+  async addMemory(params) {
+    return this.request("/v1/memories", {
+      method: "POST",
+      body: JSON.stringify(params)
+    });
+  }
+  async searchMemories(params) {
+    return this.request("/v1/memories/search", {
+      method: "POST",
+      body: JSON.stringify(params)
+    });
+  }
+  async createApiKey(params) {
+    return this.request("/v1/keys", {
+      method: "POST",
+      body: JSON.stringify(params)
+    });
+  }
+  async listApiKeys() {
+    return this.request("/v1/keys");
+  }
+  async getUsage(days = 30) {
+    return this.request(`/v1/usage?days=${days}`);
+  }
+};
+var index_default = WhisperContext;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  WhisperContext
+});

package/index.d.cts

@@ -0,0 +1,166 @@
+/**
+ * Whisper Context SDK
+ * TypeScript SDK for the Whisper Context API
+ */
+interface WhisperConfig {
+    apiKey: string;
+    baseUrl?: string;
+}
+interface QueryParams {
+    project: string;
+    query: string;
+    top_k?: number;
+    threshold?: number;
+    chunk_types?: string[];
+    source_ids?: string[];
+    hybrid?: boolean;
+    vector_weight?: number;
+    bm25_weight?: number;
+    rerank?: boolean;
+    include_memories?: boolean;
+    user_id?: string;
+    session_id?: string;
+    agent_id?: string;
+    include_graph?: boolean;
+    graph_depth?: number;
+    max_tokens?: number;
+    compress?: boolean;
+    compression_strategy?: "summarize" | "extract" | "delta" | "adaptive";
+    use_cache?: boolean;
+}
+interface QueryResult {
+    results: Array<{
+        id: string;
+        content: string;
+        score: number;
+        metadata: Record<string, any>;
+        source: string;
+        document: string;
+        type: string;
+        retrieval_source: string;
+    }>;
+    context: string;
+    meta: {
+        query: string;
+        total: number;
+        latency_ms: number;
+        cache_hit: boolean;
+        tokens_used: number;
+        context_hash: string;
+        compression?: any;
+    };
+}
+interface Project {
+    id: string;
+    orgId: string;
+    name: string;
+    slug: string;
+    description?: string;
+    settings?: Record<string, any>;
+    createdAt: string;
+    updatedAt: string;
+}
+interface Source {
+    id: string;
+    projectId: string;
+    name: string;
+    connectorType: string;
+    config: Record<string, any>;
+    status: string;
+    syncSchedule?: string;
+    lastSyncAt?: string;
+    syncError?: string;
+    createdAt: string;
+    updatedAt: string;
+}
+interface Memory {
+    id: string;
+    projectId: string;
+    content: string;
+    memoryType: "factual" | "episodic" | "semantic" | "procedural";
+    userId?: string;
+    sessionId?: string;
+    agentId?: string;
+    importance: number;
+    metadata: Record<string, any>;
+    accessCount: number;
+    createdAt: string;
+    updatedAt: string;
+}
+declare class WhisperContext {
+    private apiKey;
+    private baseUrl;
+    constructor(config: WhisperConfig);
+    private request;
+    query(params: QueryParams): Promise<QueryResult>;
+    createProject(params: {
+        name: string;
+        description?: string;
+        settings?: Record<string, any>;
+    }): Promise<Project>;
+    listProjects(): Promise<{
+        projects: Project[];
+    }>;
+    getProject(id: string): Promise<Project & {
+        sources: Source[];
+    }>;
+    deleteProject(id: string): Promise<{
+        deleted: boolean;
+    }>;
+    addSource(projectId: string, params: {
+        name: string;
+        connector_type: string;
+        config: Record<string, any>;
+        sync_schedule?: string;
+    }): Promise<Source>;
+    syncSource(sourceId: string): Promise<any>;
+    ingest(projectId: string, documents: Array<{
+        id?: string;
+        title: string;
+        content: string;
+        metadata?: Record<string, any>;
+        file_path?: string;
+    }>): Promise<{
+        ingested: number;
+    }>;
+    addMemory(params: {
+        project: string;
+        content: string;
+        memory_type?: "factual" | "episodic" | "semantic" | "procedural";
+        user_id?: string;
+        session_id?: string;
+        agent_id?: string;
+        importance?: number;
+        metadata?: Record<string, any>;
+        expires_in_seconds?: number;
+    }): Promise<Memory>;
+    searchMemories(params: {
+        project: string;
+        query: string;
+        user_id?: string;
+        session_id?: string;
+        agent_id?: string;
+        memory_type?: "factual" | "episodic" | "semantic" | "procedural";
+        top_k?: number;
+    }): Promise<{
+        memories: Array<Memory & {
+            score: number;
+        }>;
+    }>;
+    createApiKey(params: {
+        name: string;
+        scopes?: string[];
+        rate_limit?: number;
+        expires_in_days?: number;
+    }): Promise<{
+        key: string;
+        prefix: string;
+        name: string;
+    }>;
+    listApiKeys(): Promise<{
+        keys: any[];
+    }>;
+    getUsage(days?: number): Promise<any>;
+}
+
+export { type Memory, type Project, type QueryParams, type QueryResult, type Source, type WhisperConfig, WhisperContext, WhisperContext as default };

package/index.d.ts

@@ -0,0 +1,166 @@
+/**
+ * Whisper Context SDK
+ * TypeScript SDK for the Whisper Context API
+ */
+interface WhisperConfig {
+    apiKey: string;
+    baseUrl?: string;
+}
+interface QueryParams {
+    project: string;
+    query: string;
+    top_k?: number;
+    threshold?: number;
+    chunk_types?: string[];
+    source_ids?: string[];
+    hybrid?: boolean;
+    vector_weight?: number;
+    bm25_weight?: number;
+    rerank?: boolean;
+    include_memories?: boolean;
+    user_id?: string;
+    session_id?: string;
+    agent_id?: string;
+    include_graph?: boolean;
+    graph_depth?: number;
+    max_tokens?: number;
+    compress?: boolean;
+    compression_strategy?: "summarize" | "extract" | "delta" | "adaptive";
+    use_cache?: boolean;
+}
+interface QueryResult {
+    results: Array<{
+        id: string;
+        content: string;
+        score: number;
+        metadata: Record<string, any>;
+        source: string;
+        document: string;
+        type: string;
+        retrieval_source: string;
+    }>;
+    context: string;
+    meta: {
+        query: string;
+        total: number;
+        latency_ms: number;
+        cache_hit: boolean;
+        tokens_used: number;
+        context_hash: string;
+        compression?: any;
+    };
+}
+interface Project {
+    id: string;
+    orgId: string;
+    name: string;
+    slug: string;
+    description?: string;
+    settings?: Record<string, any>;
+    createdAt: string;
+    updatedAt: string;
+}
+interface Source {
+    id: string;
+    projectId: string;
+    name: string;
+    connectorType: string;
+    config: Record<string, any>;
+    status: string;
+    syncSchedule?: string;
+    lastSyncAt?: string;
+    syncError?: string;
+    createdAt: string;
+    updatedAt: string;
+}
+interface Memory {
+    id: string;
+    projectId: string;
+    content: string;
+    memoryType: "factual" | "episodic" | "semantic" | "procedural";
+    userId?: string;
+    sessionId?: string;
+    agentId?: string;
+    importance: number;
+    metadata: Record<string, any>;
+    accessCount: number;
+    createdAt: string;
+    updatedAt: string;
+}
+declare class WhisperContext {
+    private apiKey;
+    private baseUrl;
+    constructor(config: WhisperConfig);
+    private request;
+    query(params: QueryParams): Promise<QueryResult>;
+    createProject(params: {
+        name: string;
+        description?: string;
+        settings?: Record<string, any>;
+    }): Promise<Project>;
+    listProjects(): Promise<{
+        projects: Project[];
+    }>;
+    getProject(id: string): Promise<Project & {
+        sources: Source[];
+    }>;
+    deleteProject(id: string): Promise<{
+        deleted: boolean;
+    }>;
+    addSource(projectId: string, params: {
+        name: string;
+        connector_type: string;
+        config: Record<string, any>;
+        sync_schedule?: string;
+    }): Promise<Source>;
+    syncSource(sourceId: string): Promise<any>;
+    ingest(projectId: string, documents: Array<{
+        id?: string;
+        title: string;
+        content: string;
+        metadata?: Record<string, any>;
+        file_path?: string;
+    }>): Promise<{
+        ingested: number;
+    }>;
+    addMemory(params: {
+        project: string;
+        content: string;
+        memory_type?: "factual" | "episodic" | "semantic" | "procedural";
+        user_id?: string;
+        session_id?: string;
+        agent_id?: string;
+        importance?: number;
+        metadata?: Record<string, any>;
+        expires_in_seconds?: number;
+    }): Promise<Memory>;
+    searchMemories(params: {
+        project: string;
+        query: string;
+        user_id?: string;
+        session_id?: string;
+        agent_id?: string;
+        memory_type?: "factual" | "episodic" | "semantic" | "procedural";
+        top_k?: number;
+    }): Promise<{
+        memories: Array<Memory & {
+            score: number;
+        }>;
+    }>;
+    createApiKey(params: {
+        name: string;
+        scopes?: string[];
+        rate_limit?: number;
+        expires_in_days?: number;
+    }): Promise<{
+        key: string;
+        prefix: string;
+        name: string;
+    }>;
+    listApiKeys(): Promise<{
+        keys: any[];
+    }>;
+    getUsage(days?: number): Promise<any>;
+}
+
+export { type Memory, type Project, type QueryParams, type QueryResult, type Source, type WhisperConfig, WhisperContext, WhisperContext as default };

package/index.js

@@ -0,0 +1,92 @@
+// src/sdk/index.ts
+var WhisperContext = class {
+  apiKey;
+  baseUrl;
+  constructor(config) {
+    if (!config.apiKey) {
+      throw new Error("API key is required");
+    }
+    this.apiKey = config.apiKey;
+    this.baseUrl = config.baseUrl || "https://context.usewhisper.dev";
+  }
+  async request(endpoint, options = {}) {
+    const response = await fetch(`${this.baseUrl}${endpoint}`, {
+      ...options,
+      headers: {
+        Authorization: `Bearer ${this.apiKey}`,
+        "Content-Type": "application/json",
+        ...options.headers
+      }
+    });
+    if (!response.ok) {
+      const error = await response.json().catch(() => ({ error: "Request failed" }));
+      throw new Error(error.error || `HTTP ${response.status}: ${response.statusText}`);
+    }
+    return response.json();
+  }
+  async query(params) {
+    return this.request("/v1/context/query", {
+      method: "POST",
+      body: JSON.stringify(params)
+    });
+  }
+  async createProject(params) {
+    return this.request("/v1/projects", {
+      method: "POST",
+      body: JSON.stringify(params)
+    });
+  }
+  async listProjects() {
+    return this.request("/v1/projects");
+  }
+  async getProject(id) {
+    return this.request(`/v1/projects/${id}`);
+  }
+  async deleteProject(id) {
+    return this.request(`/v1/projects/${id}`, { method: "DELETE" });
+  }
+  async addSource(projectId, params) {
+    return this.request(`/v1/projects/${projectId}/sources`, {
+      method: "POST",
+      body: JSON.stringify(params)
+    });
+  }
+  async syncSource(sourceId) {
+    return this.request(`/v1/sources/${sourceId}/sync`, { method: "POST" });
+  }
+  async ingest(projectId, documents) {
+    return this.request(`/v1/projects/${projectId}/ingest`, {
+      method: "POST",
+      body: JSON.stringify({ documents })
+    });
+  }
+  async addMemory(params) {
+    return this.request("/v1/memories", {
+      method: "POST",
+      body: JSON.stringify(params)
+    });
+  }
+  async searchMemories(params) {
+    return this.request("/v1/memories/search", {
+      method: "POST",
+      body: JSON.stringify(params)
+    });
+  }
+  async createApiKey(params) {
+    return this.request("/v1/keys", {
+      method: "POST",
+      body: JSON.stringify(params)
+    });
+  }
+  async listApiKeys() {
+    return this.request("/v1/keys");
+  }
+  async getUsage(days = 30) {
+    return this.request(`/v1/usage?days=${days}`);
+  }
+};
+var index_default = WhisperContext;
+export {
+  WhisperContext,
+  index_default as default
+};

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@usewhisper/sdk",
+  "version": "0.1.0",
+  "description": "TypeScript SDK for Whisper Context API - Add reliable context to your AI agents",
+  "main": "index.cjs",
+  "module": "index.js",
+  "types": "index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./index.js",
+      "require": "./index.cjs",
+      "types": "./index.d.ts"
+    }
+  },
+  "files": [
+    "index.js",
+    "index.cjs",
+    "index.d.ts",
+    "index.d.cts",
+    "README.md"
+  ],
+  "keywords": [
+    "whisper",
+    "context",
+    "ai",
+    "llm",
+    "rag",
+    "embeddings",
+    "vector-search",
+    "knowledge-graph",
+    "semantic-search"
+  ],
+  "author": "Whisper",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Alixus/whisper"
+  },
+  "homepage": "https://usewhisper.dev",
+  "bugs": {
+    "url": "https://github.com/Alinxus/whisper/issues"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsup": "^8.3.0",
+    "typescript": "^5.7.0"
+  },
+  "peerDependencies": {},
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}