@superatomai/sdk-node 0.0.1

package/README.md

@@ -0,0 +1,232 @@
+# @superatomai/sdk
+
+A TypeScript SDK for building applications with Superatom - a platform for creating data-driven, AI-powered applications.
+
+## Installation
+
+```bash
+npm install @superatomai/sdk
+```
+
+Or with pnpm:
+
+```bash
+pnpm add @superatomai/sdk
+```
+
+## Quick Start
+
+```typescript
+import { SuperatomSDK } from '@superatomai/sdk';
+
+// Initialize the SDK
+const sdk = new SuperatomSDK({
+  apiKey: 'your-api-key',
+  projectId: 'your-project-id',
+  userId: 'user-123', // optional, defaults to 'anonymous'
+  type: 'data-agent', // optional, defaults to 'data-agent'
+});
+
+// The SDK automatically connects to the Superatom WebSocket service
+// Wait for connection before using
+await sdk.connect();
+
+// Register a collection handler for data operations
+sdk.addCollection('users', 'list', async (params) => {
+  // Your custom logic to fetch users
+  return {
+    data: [
+      { id: 1, name: 'John Doe' },
+      { id: 2, name: 'Jane Smith' },
+    ],
+  };
+});
+
+// Listen to all incoming messages
+sdk.onMessage((message) => {
+  console.log('Received message:', message);
+});
+
+// Send messages to the Superatom service
+sdk.send({
+  type: 'custom_message',
+  data: { foo: 'bar' },
+});
+
+// Cleanup when done
+await sdk.destroy();
+```
+
+## Configuration
+
+### SuperatomSDKConfig
+
+```typescript
+interface SuperatomSDKConfig {
+  apiKey: string;                    // Required: Your Superatom API key
+  projectId: string;                 // Required: Your project ID
+  userId?: string;                   // Optional: User identifier (default: 'anonymous')
+  type?: string;                     // Optional: Agent type (default: 'data-agent')
+  bundleDir?: string;                // Optional: Directory for bundle requests
+  url?: string;                      // Optional: Custom WebSocket URL
+  ANTHROPIC_API_KEY?: string;        // Optional: Anthropic API key for LLM
+  GROQ_API_KEY?: string;             // Optional: Groq API key for LLM
+  LLM_PROVIDERS?: LLMProvider[];     // Optional: Custom LLM providers
+}
+```
+
+Environment variables are also supported:
+- `SA_WEBSOCKET_URL`: WebSocket URL (default: `wss://ws.superatom.ai/websocket`)
+- `ANTHROPIC_API_KEY`: Anthropic API key
+- `GROQ_API_KEY`: Groq API key
+
+## Key Features
+
+### Collection Handlers
+
+Register handlers for data operations:
+
+```typescript
+sdk.addCollection<ParamsType, ResultType>(
+  'collection-name',
+  'operation',
+  async (params) => {
+    // Your custom logic
+    return result;
+  }
+);
+```
+
+### Message Handling
+
+Listen to all messages:
+
+```typescript
+const unsubscribe = sdk.onMessage((message) => {
+  console.log('Message received:', message);
+});
+
+// Unsubscribe when needed
+unsubscribe();
+```
+
+Listen to specific message types:
+
+```typescript
+const unsubscribe = sdk.onMessageType('custom_type', (message) => {
+  console.log('Custom message:', message);
+});
+```
+
+### User Management
+
+```typescript
+const userManager = sdk.getUserManager();
+
+// Create a user
+await userManager.createUser({
+  id: 'user-123',
+  name: 'John Doe',
+  email: 'john@example.com',
+});
+
+// Get a user
+const user = await userManager.getUser('user-123');
+
+// Update a user
+await userManager.updateUser('user-123', { name: 'John Updated' });
+
+// Delete a user
+await userManager.deleteUser('user-123');
+```
+
+### LLM Integration
+
+```typescript
+import { LLM } from '@superatomai/sdk';
+
+const llm = new LLM({
+  apiKey: 'your-anthropic-or-groq-api-key',
+  provider: 'anthropic', // or 'groq'
+});
+
+// Generate text
+const response = await llm.text('What is the meaning of life?');
+
+// Stream responses
+for await (const chunk of llm.stream('Tell me a story')) {
+  process.stdout.write(chunk);
+}
+```
+
+### Thread Management
+
+```typescript
+import { Thread, UIBlock, ThreadManager } from '@superatomai/sdk';
+
+const threadManager = new ThreadManager();
+
+// Create a thread
+const thread = threadManager.createThread({
+  userId: 'user-123',
+  metadata: { source: 'chat' },
+});
+
+// Add UI blocks to thread
+thread.addBlock(
+  new UIBlock('block-1', 'text', { content: 'Hello, World!' })
+);
+
+// Get all threads
+const threads = threadManager.getAllThreads();
+
+// Cleanup old threads
+await threadManager.cleanup();
+```
+
+### Cleanup Service
+
+```typescript
+import { CleanupService } from '@superatomai/sdk';
+
+const cleanupService = new CleanupService();
+
+// Register cleanup tasks
+cleanupService.registerTask('threads', async () => {
+  // Your cleanup logic
+});
+
+// Start periodic cleanup (every 5 minutes by default)
+cleanupService.start();
+
+// Stop cleanup
+cleanupService.stop();
+```
+
+## API Reference
+
+### SuperatomSDK Methods
+
+- `connect(): Promise<void>` - Connect to the WebSocket service
+- `disconnect(): void` - Disconnect from the WebSocket service
+- `destroy(): Promise<void>` - Cleanup and disconnect permanently
+- `isConnected(): boolean` - Check connection status
+- `send(message: Message): void` - Send a message to Superatom
+- `onMessage(handler): () => void` - Register a message handler
+- `onMessageType(type, handler): () => void` - Register a type-specific handler
+- `addCollection(name, operation, handler): void` - Register a collection handler
+- `getUserManager(): UserManager` - Get the user manager instance
+
+## TypeScript Support
+
+This SDK is written in TypeScript and includes full type definitions. All exports are fully typed for the best development experience.
+
+## License
+
+MIT
+
+## Support
+
+For issues and questions:
+- GitHub Issues: [Report an issue](https://github.com/superatomai/sdk-nodejs/issues)
+- Email: ashish@superatom.ai