@sovant/sdk 1.0.0 → 1.0.2

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024 Sovant AI
+Copyright (c) 2025 Sovant
 
 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,370 +1,30 @@
-# Sovant JavaScript/TypeScript SDK
-
-Official JavaScript/TypeScript SDK for the Sovant Memory API. Build AI applications with persistent memory, semantic search, and intelligent context management.
-
-> **Note: Coming Soon!** This SDK is currently in development and will be available on npm soon. In the meantime, you can use our REST API directly.
-
-## Installation
+# Sovant TypeScript SDK
+[![npm version](https://img.shields.io/npm/v/@sovant/sdk)](https://www.npmjs.com/package/@sovant/sdk)
 
+## Install
 ```bash
-# Coming soon
-npm install @sovant/sdk
-# or
-yarn add @sovant/sdk
-# or
-pnpm add @sovant/sdk
-```
-
-## Quick Start
-
-```javascript
-import { SovantClient } from "@sovant/sdk";
-
-// Initialize the client
-const client = new SovantClient("YOUR_API_KEY");
-
-// Create a memory
-const memory = await client.memories.create({
-  content: "User prefers dark mode interfaces",
-  type: "preference",
-  metadata: {
-    category: "ui_preferences",
-    confidence: 0.95,
-  },
-});
-
-console.log("Created memory:", memory.id);
-
-// Search memories
-const results = await client.memories.search({
-  query: "What are the user's UI preferences?",
-  limit: 5,
-});
-
-results.forEach((result) => {
-  console.log(`- ${result.content} (relevance: ${result.relevance_score})`);
-});
-```
-
-## Features
-
-- 🚀 **Full TypeScript Support** - Complete type definitions for all methods
-- 🔄 **Async/Await** - Modern promise-based API
-- 🔁 **Automatic Retries** - Built-in retry logic for network failures
-- 📦 **Batch Operations** - Efficient bulk create/delete operations
-- 🎯 **Smart Search** - Semantic, keyword, and hybrid search modes
-- 🧵 **Thread Management** - Organize memories into contextual threads
-- 📊 **Analytics** - Built-in insights and statistics
-- ⚡ **Tree-Shakeable** - Only import what you need
-
-## Configuration
-
-```javascript
-const client = new SovantClient({
-  apiKey: "YOUR_API_KEY",
-  baseUrl: "https://api.sovant.ai/v1", // Optional
-  timeout: 30000, // Request timeout in ms
-  maxRetries: 3, // Number of retries for failed requests
-  retryDelay: 1000, // Delay between retries in ms
-});
-```
-
-You can also use environment variables:
-
-```bash
-export SOVANT_API_KEY="YOUR_API_KEY"
-```
-
-```javascript
-const client = new SovantClient(process.env.SOVANT_API_KEY);
+npm i @sovant/sdk
 ```
 
-## Memory Operations
-
-### Create a Memory
-
-```javascript
-const memory = await client.memories.create({
-  content: "The user completed the onboarding tutorial",
-  type: "event",
-  importance: 0.8,
-  metadata: {
-    step_completed: "tutorial",
-    duration_seconds: 180,
-  },
-  tags: ["onboarding", "milestone"],
-  emotion: {
-    type: "positive",
-    intensity: 0.7,
-  },
-  action_items: ["Send welcome email", "Unlock advanced features"],
-});
-```
-
-### Update a Memory
-
-```javascript
-const updated = await client.memories.update(memory.id, {
-  importance: 0.9,
-  follow_up_required: true,
-  follow_up_due: "2024-12-31T23:59:59Z",
-});
-```
-
-### Search Memories
-
-```javascript
-// Semantic search
-const semanticResults = await client.memories.search({
-  query: "user achievements and milestones",
-  search_type: "semantic",
-  limit: 10,
-});
-
-// Filtered search
-const filteredResults = await client.memories.search({
-  query: "preferences",
-  type: ["preference", "decision"],
-  tags: ["important"],
-  created_after: "2024-01-01",
-  sort_by: "importance",
-  sort_order: "desc",
-});
-```
-
-### Batch Operations
-
-```javascript
-// Batch create
-const batchResult = await client.memories.createBatch([
-  { content: "Memory 1", type: "observation" },
-  { content: "Memory 2", type: "reflection" },
-  { content: "Memory 3", type: "learning" },
-]);
-
-console.log(`Created ${batchResult.success_count} memories`);
-console.log(`Failed ${batchResult.failed_count} memories`);
-
-// Batch delete
-const deleteResult = await client.memories.deleteBatch([
-  "mem_123",
-  "mem_456",
-  "mem_789",
-]);
-```
-
-## Thread Management
-
-### Create a Thread
-
-```javascript
-const thread = await client.threads.create({
-  name: "Project Planning Discussion",
-  description: "Capturing all decisions and ideas for Q1 project",
-  tags: ["project", "planning", "q1-2024"],
-});
-```
-
-### Add Memories to Thread
-
-```javascript
-// Add existing memories
-await client.threads.addMemories(thread.id, [memory1.id, memory2.id]);
-
-// Create and add in one operation
-const newMemory = await client.memories.create({
-  content: "Decided to use TypeScript for the project",
-  type: "decision",
-  thread_ids: [thread.id],
-});
-```
-
-### Get Thread with Memories
-
-```javascript
-const threadWithMemories = await client.threads.get(thread.id, true);
-
-console.log(`Thread: ${threadWithMemories.name}`);
-console.log(`Memories: ${threadWithMemories.memories.length}`);
-
-threadWithMemories.memories.forEach((memory) => {
-  console.log(`- ${memory.content}`);
-});
-```
-
-### Thread Analytics
-
-```javascript
-const stats = await client.threads.getStats(thread.id);
-
-console.log(`Total memories: ${stats.memory_count}`);
-console.log(`Average importance: ${stats.avg_importance}`);
-console.log(`Decisions made: ${stats.total_decisions}`);
-console.log(`Open questions: ${stats.total_questions}`);
-```
-
-## Error Handling
-
-The SDK provides typed error classes for different scenarios:
-
-```javascript
-import {
-  AuthenticationError,
-  RateLimitError,
-  ValidationError,
-  NotFoundError,
-} from "@sovant/sdk";
-
-try {
-  const memory = await client.memories.get("invalid_id");
-} catch (error) {
-  if (error instanceof NotFoundError) {
-    console.error("Memory not found");
-  } else if (error instanceof RateLimitError) {
-    console.error(`Rate limited. Retry after ${error.retryAfter} seconds`);
-  } else if (error instanceof ValidationError) {
-    console.error("Validation errors:", error.errors);
-  }
-}
-```
-
-## TypeScript Support
-
-The SDK is written in TypeScript and provides comprehensive type definitions:
-
+## 60s Quickstart
 ```typescript
-import {
-  Memory,
-  Thread,
-  SearchResult,
-  MemoryType,
-  EmotionType,
-} from "@sovant/sdk";
-
-// All methods are fully typed
-const createMemory = async (
-  content: string,
-  type: MemoryType,
-): Promise<Memory> => {
-  return client.memories.create({ content, type });
-};
-
-// Type-safe emotion handling
-const emotions: EmotionType[] = ["happy", "excited", "calm"];
-```
-
-## Advanced Usage
-
-### Memory Insights
+import { Sovant } from "@sovant/sdk";
 
-```javascript
-const insights = await client.memories.getInsights({
-  time_range: "last_30_days",
-  group_by: "type",
-});
-
-console.log("Memory distribution:", insights.type_distribution);
-console.log("Emotion distribution:", insights.emotion_distribution);
-console.log("Growth rate:", `${insights.growth_rate}%`);
-```
-
-### Related Memories
+const sv = new Sovant({ apiKey: process.env.SOVANT_API_KEY! });
 
-```javascript
-const related = await client.memories.getRelated(memory.id, {
-  limit: 5,
-  threshold: 0.7,
+await sv.memory.create({ 
+  data: { note: "hello" }, 
+  type: "preference",
+  ttl: "30d" 
 });
 
-console.log("Related memories:");
-related.forEach((r) => {
-  console.log(`- ${r.content} (similarity: ${r.relevance_score})`);
+const res = await sv.memory.search({ 
+  query: "hello", 
+  topK: 3 
 });
-```
-
-### Thread Merging
-
-```javascript
-// Merge multiple threads into one
-const mergedThread = await client.threads.merge(mainThread.id, [
-  thread2.id,
-  thread3.id,
-]);
-```
-
-## React Hooks (Coming Soon)
-
-```javascript
-import { useMemory, useThread, useSearch } from "@sovant/sdk/react";
-
-function MyComponent() {
-  const { memories, loading, error } = useMemory({
-    type: "preference",
-    limit: 10,
-  });
-
-  const { results, search } = useSearch();
 
-  // Component logic...
-}
+console.log(res);
 ```
 
-## API Reference
-
-### Client Methods
-
-- `new SovantClient(apiKey)` - Create a new client instance
-- `client.ping()` - Test API connection
-- `client.getUsage()` - Get current API usage and quota
-
-### Memory Methods
-
-- `client.memories.create(data)` - Create a new memory
-- `client.memories.get(id)` - Get a memory by ID
-- `client.memories.update(id, data)` - Update a memory
-- `client.memories.delete(id)` - Delete a memory
-- `client.memories.list(options)` - List memories with pagination
-- `client.memories.search(options)` - Search memories
-- `client.memories.createBatch(memories)` - Batch create memories
-- `client.memories.deleteBatch(ids)` - Batch delete memories
-- `client.memories.getInsights(options)` - Get memory analytics
-- `client.memories.archive(id)` - Archive a memory
-- `client.memories.pin(id)` - Pin a memory
-- `client.memories.getRelated(id, options)` - Get related memories
-
-### Thread Methods
-
-- `client.threads.create(data)` - Create a new thread
-- `client.threads.get(id, includeMemories)` - Get a thread
-- `client.threads.update(id, data)` - Update a thread
-- `client.threads.delete(id, deleteMemories)` - Delete a thread
-- `client.threads.list(options)` - List threads with pagination
-- `client.threads.addMemories(id, memoryIds)` - Add memories to thread
-- `client.threads.removeMemories(id, memoryIds)` - Remove memories from thread
-- `client.threads.getMemories(id, options)` - Get memories in thread
-- `client.threads.getStats(id)` - Get thread statistics
-- `client.threads.search(options)` - Search threads
-- `client.threads.merge(targetId, sourceIds)` - Merge threads
-- `client.threads.clone(id, options)` - Clone a thread
-
-## Examples
-
-Check out the [examples directory](https://github.com/sovant-ai/javascript-sdk/tree/main/examples) for complete working examples:
-
-- Basic CRUD operations
-- Advanced search techniques
-- Thread management workflows
-- Error handling patterns
-- TypeScript usage
-- React integration
-
-## Support
-
-- 📚 [Documentation](https://docs.sovant.ai)
-- 💬 [Discord Community](https://discord.gg/sovant)
-- 🐛 [Issue Tracker](https://github.com/sovant-ai/javascript-sdk/issues)
-- 📧 [Email Support](mailto:support@sovant.ai)
-
-## License
-
-MIT © Sovant AI
+## Errors
+Throws `SovantError(code, status, details)`.