@sovant/sdk 1.0.4 → 1.1.0

package/CHANGELOG.md

@@ -0,0 +1,101 @@
+# Changelog
+
+All notable changes to the Sovant JavaScript/TypeScript SDK will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.1.0] - 2025-09-15
+
+### Added
+- **Chat namespace** with SSE streaming support for real-time conversations
+  - `createSession()` - Create chat sessions with provider/model selection
+  - `sendMessage()` - Stream responses with async generator pattern
+  - `getMessages()` - Retrieve chat history
+  - `getSession()` / `listSessions()` - Session management
+- **Keys namespace** for API key management
+  - `list()`, `create()`, `update()`, `revoke()` - Full key lifecycle
+- **Recall namespace** with Phase 1 profile helpers
+  - `extractProfile()` - Client-side profile entity detection
+  - `getProfileFacts()` - Retrieve canonical profile facts
+  - `saveProfileFact()` - Save facts in canonical format
+- **baseUrl** config option for custom endpoints
+- SSE parser utility for streaming responses
+- TypeScript exports for all new types
+
+### Changed
+- HttpClient properties now public for namespace access
+- Enhanced README with Chat streaming examples
+
+## [0.4.0] - 2025-01-01
+
+### Added
+- Complete alignment with live Sovant Memory API at https://sovant.ai
+- Full TypeScript support with comprehensive type definitions
+- Robust error handling with `SovantError`, `NetworkError`, and `TimeoutError` classes
+- Automatic retry logic with exponential backoff for failed requests
+- Request timeout support using AbortController
+- Debug mode for detailed request/response logging
+- Batch operations support for atomic multi-operation transactions
+- Thread management for organizing related memories
+- Comprehensive README with examples and best practices
+- Smoke test script for API verification
+- Proper ESM and CommonJS dual package support
+
+### Changed
+- **BREAKING**: Complete API redesign to match live endpoints
+- **BREAKING**: Removed `userId` from all public method signatures (now derived from API key)
+- **BREAKING**: Changed from `SovantClient` class to `Sovant` class
+- **BREAKING**: Namespace all memory operations under `sovant.memory.*`
+- Updated all endpoints to use new paths:
+  - Collection: `/api/v1/memory` (GET list, POST create)
+  - By ID: `/api/v1/memories/{id}` (GET, PUT, PATCH, DELETE)
+  - Search: `/api/v1/memory/search`
+  - Batch: `/api/v1/memory/batch`
+- All response fields now use snake_case to match API format
+- Improved error messages and request ID tracking
+
+### Fixed
+- Proper handling of 204 No Content responses
+- Correct content-type detection for response parsing
+- Retry logic for transient network failures
+- Proper timeout handling with clear error messages
+
+### Security
+- API keys are now passed as Bearer tokens in Authorization header
+- No longer expose userId in client code
+
+## [0.3.0] - 2024-11-15
+
+### Added
+- Initial TypeScript SDK implementation
+- Basic CRUD operations for memories
+- Simple search functionality
+- Thread support
+
+### Changed
+- Migrated from JavaScript to TypeScript
+
+## [0.2.0] - 2024-10-01
+
+### Added
+- Batch operations support
+- Memory metadata fields
+- Emotional tone tracking
+
+### Fixed
+- Memory pagination issues
+- Search result relevance scoring
+
+## [0.1.0] - 2024-09-01
+
+### Added
+- Initial SDK release
+- Basic memory CRUD operations
+- Simple keyword search
+- API key authentication
+
+[0.4.0]: https://github.com/sovant-ai/javascript-sdk/compare/v0.3.0...v0.4.0
+[0.3.0]: https://github.com/sovant-ai/javascript-sdk/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/sovant-ai/javascript-sdk/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/sovant-ai/javascript-sdk/releases/tag/v0.1.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Sovant
+Copyright (c) 2024 Sovant AI
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,24 +1,6 @@
-# Sovant TypeScript SDK
+# Sovant JavaScript/TypeScript SDK
 
-**AI Infrastructure: Memory-as-a-Service for AI systems.**  
-The official TypeScript/JavaScript client for the Sovant Memory API.
-
-[![npm version](https://img.shields.io/npm/v/@sovant/sdk)](https://www.npmjs.com/package/@sovant/sdk)
-[![Documentation](https://img.shields.io/badge/docs-sovant.ai-blue)](https://sovant.ai/docs)
-[![GitHub](https://img.shields.io/badge/github-sovant-lightgrey)](https://github.com/sovant-ai/sovant)
-
----
-
-## What is Sovant?
-
-Sovant is an **AI infrastructure company** providing the **memory layer for AI systems**.  
-Our platform makes it simple to persist, search, and manage conversational and contextual data securely across sessions, channels, and applications.
-
-- **Problem:** Most AI systems forget everything once a session ends. This causes compliance risks, knowledge loss, and poor user experience.  
-- **Solution:** Sovant provides a **Memory-as-a-Service API** — a single SDK and API key that lets you store, retrieve, and search memories with audit-ready controls.  
-- **Target audience:** Developers, startups, and enterprises building AI agents, copilots, or compliance-driven apps who need context persistence.
-
----
+Official JavaScript/TypeScript SDK for the Sovant Memory API - Universal memory layer for AI applications.
 
 ## Installation
 
@@ -30,74 +12,422 @@ yarn add @sovant/sdk
 pnpm add @sovant/sdk
 ```
 
-## 60-Second Quickstart
+## Quick Start
 
 ```typescript
-import { Sovant } from "@sovant/sdk";
+import { Sovant } from '@sovant/sdk';
 
-const sv = new Sovant({ apiKey: process.env.SOVANT_API_KEY! });
+// Initialize the client
+const sovant = new Sovant({
+  apiKey: 'sk_live_your_api_key_here',
+  baseUrl: 'https://sovant.ai', // Optional, defaults to https://sovant.ai
+});
 
 // Create a memory
-await sv.memory.create({ 
-  data: { note: "User prefers morning meetings" }, 
-  type: "preference"
+const memory = await sovant.memory.create({
+  content: 'User prefers dark mode interfaces',
+  type: 'preference',
+  tags: ['ui', 'settings'],
 });
 
 // Search memories
-const results = await sv.memory.search({ 
-  query: "meeting preferences", 
-  topK: 3 
+const results = await sovant.memory.search({
+  query: 'user preferences',
+  limit: 10,
+});
+
+// Update a memory
+const updated = await sovant.memory.update(memory.id, {
+  tags: ['ui', 'settings', 'theme'],
 });
 
-console.log(results);
+// Delete a memory
+await sovant.memory.delete(memory.id);
 ```
 
-## Features
+## Chat in 60 Seconds
 
-- **Memory CRUD** — create, retrieve, update, delete memories
-- **Semantic Search** — query memories with filters and topK ranking
-- **Threads** — link related memories via thread_id (REST API)
-- **Batch Operations (Beta)** — atomic multi-operation support
-- **Compliance-ready** — audit trails, PDPA/GDPR-friendly by design
-- **SDKs** — official TypeScript and Python SDKs, with REST API reference
+Stream real-time chat responses with memory context:
+
+```typescript
+import { Sovant } from '@sovant/sdk';
+
+const sovant = new Sovant({ apiKey: process.env.SOVANT_API_KEY });
+
+// Create a chat session
+const session = await sovant.chat.createSession({
+  provider: 'openai',
+  model: 'gpt-4o-mini',
+});
+
+// Stream a response
+for await (const event of sovant.chat.sendMessage(session.id, 'Hey there!', { useMemory: true })) {
+  if (event.type === 'delta') process.stdout.write(event.data);
+  if (event.type === 'done') console.log('\n[done]');
+}
+
+// Get chat history
+const messages = await sovant.chat.getMessages(session.id);
+```
 
-## SDKs and Documentation
+## Profile Recall Helpers
 
-- [TypeScript SDK Documentation](https://sovant.ai/docs/sdk/typescript)
-- [Python SDK on PyPI](https://pypi.org/project/sovant/)
-- [REST API Reference](https://sovant.ai/docs/api)
-- [Full Documentation](https://sovant.ai/docs)
+Save and recall user profile facts with canonical patterns:
 
-## API Overview
+```typescript
+// Extract profile entity from text
+const extraction = sovant.recall.extractProfile("My name is Sarah");
+// { entity: 'name', value: 'Sarah' }
+
+// Save profile fact in canonical form
+await sovant.recall.saveProfileFact('location', 'Singapore');
+// Saves as: "user location is Singapore"
+
+// Get all profile facts
+const facts = await sovant.recall.getProfileFacts();
+// { name: 'Sarah', location: 'Singapore', age: '28', preferences: ['dark mode', 'email updates'] }
+```
+
+## Configuration
+
+```typescript
+const sovant = new Sovant({
+  apiKey: 'sk_live_your_api_key_here',  // Required
+  baseUrl: 'https://sovant.ai',          // Optional, API endpoint
+  timeout: 30000,                        // Optional, request timeout in ms (default: 30000)
+  maxRetries: 3,                         // Optional, max retry attempts (default: 3)
+  debug: false,                          // Optional, enable debug logging (default: false)
+});
+```
+
+## API Reference
+
+### Memory Operations
+
+#### Create Memory
+
+```typescript
+const memory = await sovant.memory.create({
+  content: 'Customer contacted support about billing',
+  type: 'observation',              // 'journal' | 'insight' | 'observation' | 'task' | 'preference'
+  tags: ['support', 'billing'],
+  metadata: { ticketId: '12345' },
+  thread_id: 'thread_abc123',       // Optional thread association
+  importance_score: 0.8,            // 0-1 importance rating
+  emotional_tone: 'frustrated',
+  source: 'zendesk',
+});
+```
 
-### Endpoints Summary
-- `POST /api/v1/memory` — Create memory
-- `GET /api/v1/memory` — List memories
-- `GET /api/v1/memories/{id}` — Get memory by ID
-- `PATCH|PUT /api/v1/memories/{id}` — Update memory
-- `DELETE /api/v1/memories/{id}` — Delete memory
-- `GET /api/v1/memory/search` — Search memories
-- `POST /api/v1/memory/batch` — Batch operations (Beta)
+#### List Memories
 
-## Field Mapping Note
+```typescript
+const list = await sovant.memory.list({
+  limit: 20,                        // Max items per page (default: 20)
+  offset: 0,                        // Pagination offset
+  tags: ['billing'],                // Filter by tags
+  type: 'observation',              // Filter by type
+  is_archived: false,               // Filter archived status
+});
+
+console.log(list.memories);         // Array of memories
+console.log(list.total);           // Total count
+console.log(list.has_more);        // More pages available
+```
+
+#### Get Memory by ID
+
+```typescript
+const memory = await sovant.memory.get('mem_123abc');
+```
+
+#### Update Memory (Partial)
+
+```typescript
+const updated = await sovant.memory.update('mem_123abc', {
+  tags: ['support', 'billing', 'resolved'],
+  metadata: { 
+    ...memory.metadata,
+    resolved: true,
+  },
+  is_archived: true,
+});
+```
+
+#### Replace Memory (Full)
+
+```typescript
+const replaced = await sovant.memory.put('mem_123abc', {
+  content: 'Updated content here',  // Required for PUT
+  type: 'observation',
+  tags: ['updated'],
+});
+```
+
+#### Delete Memory
+
+```typescript
+await sovant.memory.delete('mem_123abc');
+```
+
+#### Search Memories
+
+```typescript
+// Semantic search
+const semanticResults = await sovant.memory.search({
+  query: 'customer preferences about notifications',
+  limit: 10,
+  type: 'preference',
+});
+
+// Filter-based search
+const filterResults = await sovant.memory.search({
+  tags: ['settings', 'notifications'],
+  from_date: '2024-01-01',
+  to_date: '2024-12-31',
+  emotional_tone: 'positive',
+  limit: 20,
+});
+```
+
+#### Batch Operations
+
+```typescript
+const batch = await sovant.memory.batch({
+  operations: [
+    {
+      op: 'create',
+      data: {
+        content: 'First memory',
+        type: 'journal',
+      },
+    },
+    {
+      op: 'update',
+      id: 'mem_123abc',
+      data: {
+        tags: ['updated'],
+      },
+    },
+    {
+      op: 'delete',
+      id: 'mem_456def',
+    },
+  ],
+});
+
+console.log(batch.ok);              // All operations succeeded
+console.log(batch.results);         // Individual operation results
+console.log(batch.summary);         // Summary statistics
+```
+
+## Memory Types
+
+- **journal** - Chronological entries and logs
+- **insight** - Derived patterns and conclusions
+- **observation** - Factual, observed information
+- **task** - Action items and todos
+- **preference** - User preferences and settings
+
+## Error Handling
+
+The SDK provides typed errors for better error handling:
+
+```typescript
+import { Sovant, SovantError, NetworkError, TimeoutError } from '@sovant/sdk';
+
+try {
+  const memory = await sovant.memory.get('invalid_id');
+} catch (error) {
+  if (error instanceof SovantError) {
+    console.error('API Error:', error.message);
+    console.error('Error Code:', error.code);
+    console.error('Status:', error.status);
+    console.error('Request ID:', error.requestId);
+    
+    switch (error.status) {
+      case 401:
+        // Handle authentication error
+        break;
+      case 404:
+        // Handle not found
+        break;
+      case 429:
+        // Handle rate limiting
+        break;
+    }
+  } else if (error instanceof TimeoutError) {
+    console.error('Request timed out');
+  } else if (error instanceof NetworkError) {
+    console.error('Network error:', error.message);
+  }
+}
+```
+
+## Thread Management
+
+Associate memories with conversation threads:
+
+```typescript
+// Create memories within a thread
+const memory1 = await sovant.memory.create({
+  content: 'User asked about pricing',
+  thread_id: 'thread_conversation_123',
+});
+
+const memory2 = await sovant.memory.create({
+  content: 'User selected enterprise plan',
+  thread_id: 'thread_conversation_123',
+});
+
+// List memories in a thread
+const threadMemories = await sovant.memory.list({
+  thread_id: 'thread_conversation_123',
+});
+```
+
+## Advanced Features
+
+### Retry Configuration
+
+The SDK automatically retries failed requests with exponential backoff:
+
+```typescript
+const sovant = new Sovant({
+  apiKey: 'sk_live_...',
+  maxRetries: 5,           // Increase retry attempts
+  timeout: 60000,          // Increase timeout for slow connections
+});
+```
+
+### Debug Mode
+
+Enable debug logging to see detailed request/response information:
+
+```typescript
+const sovant = new Sovant({
+  apiKey: 'sk_live_...',
+  debug: true,             // Enable debug output
+});
+```
+
+### Custom Base URL
+
+Connect to different environments:
+
+```typescript
+const sovant = new Sovant({
+  apiKey: 'sk_live_...',
+  baseUrl: 'https://staging.sovant.ai',
+});
+```
+
+## TypeScript Support
+
+The SDK is written in TypeScript and provides full type definitions:
+
+```typescript
+import type {
+  Memory,
+  MemoryType,
+  CreateMemoryInput,
+  SearchParams,
+  SearchResults,
+  BatchRequest,
+  BatchResponse,
+} from '@sovant/sdk';
+
+// All types are fully typed
+const createInput: CreateMemoryInput = {
+  content: 'Typed content',
+  type: 'journal',
+  tags: ['typed'],
+};
+
+const memory: Memory = await sovant.memory.create(createInput);
+```
+
+## Best Practices
+
+1. **Use appropriate memory types** - Choose the correct type for your use case
+2. **Add meaningful tags** - Tags improve searchability and organization
+3. **Set importance scores** - Help prioritize critical memories
+4. **Use threads** - Group related memories together
+5. **Handle errors gracefully** - Implement proper error handling
+6. **Batch operations** - Use batch API for multiple operations
+7. **Archive don't delete** - Consider archiving instead of deleting
+
+## Examples
+
+### Customer Support Integration
+
+```typescript
+// Track customer interaction
+const interaction = await sovant.memory.create({
+  content: 'Customer reported slow dashboard loading',
+  type: 'observation',
+  thread_id: `ticket_${ticketId}`,
+  tags: ['support', 'performance', 'dashboard'],
+  metadata: {
+    ticketId,
+    customerId,
+    priority: 'high',
+  },
+  emotional_tone: 'frustrated',
+  source: 'zendesk',
+});
+
+// Record resolution
+const resolution = await sovant.memory.create({
+  content: 'Resolved by clearing cache and upgrading plan',
+  type: 'insight',
+  thread_id: `ticket_${ticketId}`,
+  tags: ['support', 'resolved'],
+  metadata: {
+    ticketId,
+    resolutionTime: '2h',
+  },
+});
+```
+
+### User Preference Tracking
+
+```typescript
+// Store preference
+const preference = await sovant.memory.create({
+  content: 'User prefers email notifications over SMS',
+  type: 'preference',
+  tags: ['notifications', 'email', 'settings'],
+  metadata: {
+    userId,
+    setting: 'notification_channel',
+    value: 'email',
+  },
+  importance_score: 0.9,
+});
+
+// Query preferences
+const preferences = await sovant.memory.search({
+  type: 'preference',
+  tags: ['notifications'],
+});
+```
 
-- **SDK level:** accepts `data`
-- **API level:** expects `content`
-- SDK automatically converts `data` → `content`.
-- `subject` is deprecated (ignored by API). Use `thread_id`, `tags`, or `metadata` for grouping.
+## Rate Limiting
 
-## Status of Advanced Features
+The API implements rate limiting. The SDK automatically handles rate limit responses with retries. Rate limit headers are included in responses:
 
-- **Batch API:** Available, marked Beta.
-- **Threads:** Fully supported via REST API.
-- **Webhooks, personalization, multi-channel sync:** Coming soon.
+- `X-RateLimit-Limit` - Request limit per window
+- `X-RateLimit-Remaining` - Remaining requests
+- `X-RateLimit-Reset` - Reset timestamp
 
-## Versioning & Changelog
+## Support
 
-- **Stable release:** 1.0.3
-- Earlier build 1.0.0 was experimental and is deprecated.
-- See [CHANGELOG.md](./CHANGELOG.md) for details.
+- Documentation: [https://docs.sovant.ai](https://docs.sovant.ai)
+- API Reference: [https://docs.sovant.ai/api](https://docs.sovant.ai/api)
+- Issues: [GitHub Issues](https://github.com/sovant-ai/javascript-sdk/issues)
+- Support: support@sovant.ai
 
 ## License
 
-MIT © Sovant AI
+MIT - See [LICENSE](LICENSE) file for details.