@superatomai/sdk-web 0.0.5

package/README.md

@@ -0,0 +1,526 @@
+# @superatomai/sdk-web
+
+SuperAtom Web SDK - TypeScript SDK for browser-based WebSocket communication with the SuperAtom platform.
+
+## Features
+
+- 🔌 WebSocket client with automatic reconnection and exponential backoff
+- 🔒 Type-safe message validation using Zod v4
+- 🎯 Request/response pattern with timeout support
+- 📦 Bundle management with chunked transfer
+- 🧩 Component registration system
+- 🔐 Authentication (login and token verification)
+- 👥 User management (CRUD operations)
+- 📊 Dashboard management (CRUD operations)
+- 📈 Report management (CRUD operations)
+- 🤖 AI component suggestions
+- 💾 Data collection queries
+- 📝 UI logging support
+
+## Installation
+
+```bash
+pnpm add @superatomai/sdk-web
+```
+
+## Quick Start
+
+```typescript
+import { SuperatomClient, setup } from '@superatomai/sdk-web';
+
+// 1. Create and connect client
+const client = new SuperatomClient({
+  userId: 'your-user-id',
+  projectId: 'your-project-id',
+  type: 'runtime', // Connection type (default: 'runtime')
+  debug: true, // Enable debug logging
+});
+
+await client.connect();
+
+// 2. Setup components (optional - for component rendering)
+setup({
+  MyComponent: MyReactComponent,
+  AnotherComponent: AnotherReactComponent,
+  mount: (Component, container, props) => {
+    const root = createRoot(container);
+    root.render(createElement(Component, props));
+    return { unmount: () => root.unmount() };
+  }
+});
+
+// 3. Authenticate (optional)
+const loginResponse = await client.sendAuthLoginRequest(
+  loginDataBase64, // Base64 encoded login data
+  10000 // timeout in ms
+);
+
+// 4. Get AI component suggestions
+const result = await client.sendUserPromptSuggestionsRequest(
+  'show me a calendar component',
+  5 // limit
+);
+```
+
+## API Reference
+
+### SuperatomClient
+
+Main WebSocket client for communication.
+
+#### Configuration
+
+```typescript
+const client = new SuperatomClient({
+  userId: string,                    // Required: User ID
+  projectId: string,                 // Required: Project ID
+  type?: string,                     // Default: 'runtime'
+  baseUrl?: string,                  // Default: 'wss://ws.superatom.ai/websocket'
+  maxReconnectAttempts?: number,     // Default: Infinity
+  initialReconnectDelay?: number,    // Default: 1000ms
+  maxReconnectDelay?: number,        // Default: 30000ms
+  defaultTimeout?: number,           // Default: 30000ms
+  debug?: boolean,                   // Default: false
+});
+```
+
+#### Core Methods
+
+```typescript
+// Connection management
+await client.connect();                              // Returns Promise<void>
+client.disconnect();
+client.isConnected();                                // Returns boolean
+await client.reconnectWithConfig(partialConfig);     // Reconnect with updated config
+
+// Messaging
+client.send(message);                                // Send message without waiting for response
+await client.sendWithResponse(message, timeout);     // Send and wait for response
+await client.ask(message, { timeout });              // Alias for sendWithResponse
+
+// Event handlers
+client.onMessage((message) => { ... });              // Returns unsubscribe function
+client.onConnect(() => { ... });                     // Returns unsubscribe function
+client.onDisconnect(() => { ... });                  // Returns unsubscribe function
+client.onError((error) => { ... });                  // Returns unsubscribe function
+```
+
+### Service Methods
+
+#### Authentication
+
+```typescript
+// Login with credentials
+const loginResponse = await client.sendAuthLoginRequest(
+  loginDataBase64,  // Base64 encoded: username + SHA-1 hashed password
+  timeout          // Optional timeout in ms
+);
+
+// Verify authentication token
+const verifyResponse = await client.sendAuthVerifyRequest(
+  token,    // Base64 encoded auth token
+  timeout   // Optional timeout in ms
+);
+```
+
+#### User Management
+
+```typescript
+// Create a new user
+const result = await client.createUser(username, password, timeout);
+
+// Update an existing user
+const result = await client.updateUser(username, password, timeout);
+
+// Delete a user
+const result = await client.deleteUser(username, timeout);
+
+// Get all users
+const result = await client.getAllUsers(timeout);
+// Returns: { success, users, count, error?, message? }
+
+// Get a specific user
+const result = await client.getUser(username, timeout);
+// Returns: { success, user, error?, message? }
+```
+
+#### Dashboard Management
+
+```typescript
+// Create a new dashboard
+const result = await client.createDashboard(
+  dashboardId,
+  dashboardConfig,  // DSLRendererProps
+  timeout
+);
+
+// Update an existing dashboard
+const result = await client.updateDashboard(
+  dashboardId,
+  dashboardConfig,
+  timeout
+);
+
+// Delete a dashboard
+const result = await client.deleteDashboard(dashboardId, timeout);
+
+// Get all dashboards
+const result = await client.getAllDashboards(timeout);
+// Returns: { success, dashboards, count, error?, message? }
+
+// Get a specific dashboard
+const result = await client.getDashboard(dashboardId, timeout);
+// Returns: { success, dashboardId, dashboard, error?, message? }
+```
+
+#### Report Management
+
+```typescript
+// Create a new report
+const result = await client.createReport(
+  reportId,
+  reportConfig,  // ReportDSLRendererProps
+  timeout
+);
+
+// Update an existing report
+const result = await client.updateReport(
+  reportId,
+  reportConfig,
+  timeout
+);
+
+// Delete a report
+const result = await client.deleteReport(reportId, timeout);
+
+// Get all reports
+const result = await client.getAllReports(timeout);
+// Returns: { success, reports, count, error?, message? }
+
+// Get a specific report
+const result = await client.getReport(reportId, timeout);
+// Returns: { success, reportId, report, error?, message? }
+```
+
+#### User Prompts & AI Suggestions
+
+```typescript
+// Send a user prompt request
+const response = await client.sendUserPromptRequest(
+  prompt,
+  threadId,
+  uiBlockId,
+  timeout
+);
+
+// Get AI component suggestions
+const result = await client.sendUserPromptSuggestionsRequest(
+  'show me a form to collect user data',
+  5,       // limit (default: 5)
+  timeout  // optional timeout
+);
+```
+
+#### Bundle & Data
+
+```typescript
+// Request bundle with progress tracking
+const bundle = await client.requestBundle({
+  timeout: 60000,
+  onProgress: (progress) => {
+    console.log(`Download progress: ${progress}%`);
+  }
+});
+
+// Query data collections
+const result = await client.requestData({
+  collection: 'users',
+  operation: 'getMany',
+  params: { limit: 10 },
+  timeout: 10000
+});
+// Returns: { data?, error? }
+```
+
+### Component Setup
+
+Register your components with SuperAtom for dynamic rendering.
+
+```typescript
+import { setup } from '@superatomai/sdk-web';
+import { createRoot } from 'react-dom/client';
+import { createElement } from 'react';
+
+setup({
+  // Your components
+  DemoCard: DemoCard,
+  Calendar: Calendar,
+  Form: ComplexForm,
+
+  // Mount function (required)
+  mount: (Component, container, props) => {
+    const root = createRoot(container);
+    root.render(createElement(Component, props));
+    return { unmount: () => root.unmount() };
+  }
+});
+```
+
+## Message Types
+
+The SDK supports the following message types (all validated with Zod schemas):
+
+**Authentication**
+- `AUTH_LOGIN_REQ` / `AUTH_LOGIN_RES` - User login
+- `AUTH_VERIFY_REQ` / `AUTH_VERIFY_RES` - Token verification
+
+**User Prompts & AI**
+- `USER_PROMPT_REQ` / `USER_PROMPT_RES` - User prompt processing
+- `USER_PROMPT_SUGGESTIONS_REQ` / `USER_PROMPT_SUGGESTIONS_RES` - Component suggestions
+
+**Bundle & Data**
+- `BUNDLE_REQ` / `BUNDLE_CHUNK` - Bundle transfer with chunking
+- `DATA_REQ` / `DATA_RES` - Data collection queries
+
+**Management Operations**
+- `USERS` / `USERS_RES` - User CRUD operations
+- `DASHBOARDS` / `DASHBOARDS_RES` - Dashboard CRUD operations
+- `REPORTS` / `REPORTS_RES` - Report CRUD operations
+
+**Logging**
+- `UI_LOGS` - UI logging messages
+
+All message types are fully typed and validated using Zod v4 schemas.
+
+## Type Safety
+
+All messages are validated using Zod v4 schemas. The SDK exports comprehensive type definitions and schemas:
+
+```typescript
+import {
+  MessageSchema,
+  DataRequestMessageSchema,
+  AuthLoginRequestMessageSchema,
+  UserPromptSuggestionsRequestMessageSchema,
+  // ... and many more
+} from '@superatomai/sdk-web';
+
+// Validate any message
+const validMessage = MessageSchema.parse(incomingData);
+
+// Validate specific message types
+const dataRequest = DataRequestMessageSchema.parse(requestData);
+
+// TypeScript types are automatically inferred
+import type {
+  Message,
+  DataRequestMessage,
+  AuthLoginResponseMessage,
+  Component,
+  DSLRendererProps,
+  ReportDSLRendererProps,
+} from '@superatomai/sdk-web';
+```
+
+## Examples
+
+### Complete React Integration
+
+```typescript
+import { SuperatomClient, setup } from '@superatomai/sdk-web';
+import { createRoot } from 'react-dom/client';
+import { createElement } from 'react';
+import MyComponent from './components/MyComponent';
+
+// Initialize client
+const client = new SuperatomClient({
+  userId: 'user_123',
+  projectId: 'project_456',
+  type: 'runtime',
+  debug: true,
+});
+
+// Setup components
+setup({
+  MyComponent,
+  mount: (Component, container, props) => {
+    const root = createRoot(container);
+    root.render(createElement(Component, props));
+    return { unmount: () => root.unmount() };
+  }
+});
+
+// Connect and authenticate
+await client.connect();
+
+// Listen for messages
+client.onMessage((message) => {
+  console.log('Received:', message);
+});
+
+// Get component suggestions
+async function handleUserQuery(query: string) {
+  const result = await client.sendUserPromptSuggestionsRequest(query, 5);
+
+  if (result?.payload?.data?.suggestions) {
+    console.log('Suggestions:', result.payload.data.suggestions);
+  }
+}
+```
+
+### User Management Example
+
+```typescript
+import { SuperatomClient } from '@superatomai/sdk-web';
+
+const client = new SuperatomClient({
+  userId: 'admin_123',
+  projectId: 'project_456',
+});
+
+await client.connect();
+
+// Create a new user
+const createResult = await client.createUser('newuser', 'password123');
+if (createResult.success) {
+  console.log('User created:', createResult.username);
+}
+
+// Get all users
+const usersResult = await client.getAllUsers();
+if (usersResult.success && usersResult.users) {
+  console.log(`Found ${usersResult.count} users`);
+  usersResult.users.forEach(user => {
+    console.log(`- ${user.username} (${user.wsIds.length} connections)`);
+  });
+}
+
+// Update a user
+await client.updateUser('newuser', 'newpassword456');
+
+// Delete a user
+await client.deleteUser('newuser');
+```
+
+### Dashboard Management Example
+
+```typescript
+import { SuperatomClient } from '@superatomai/sdk-web';
+import type { DSLRendererProps } from '@superatomai/sdk-web';
+
+const client = new SuperatomClient({
+  userId: 'admin_123',
+  projectId: 'project_456',
+});
+
+await client.connect();
+
+// Create a dashboard
+const dashboardConfig: DSLRendererProps = {
+  // Your dashboard configuration
+};
+
+const result = await client.createDashboard(
+  'dashboard_001',
+  dashboardConfig
+);
+
+if (result.success) {
+  console.log('Dashboard created:', result.dashboardId);
+}
+
+// Get all dashboards
+const dashboards = await client.getAllDashboards();
+if (dashboards.success && dashboards.dashboards) {
+  console.log(`Total dashboards: ${dashboards.count}`);
+}
+
+// Get specific dashboard
+const dashboard = await client.getDashboard('dashboard_001');
+if (dashboard.success && dashboard.dashboard) {
+  console.log('Dashboard config:', dashboard.dashboard);
+}
+```
+
+### Data Query Example
+
+```typescript
+import { SuperatomClient } from '@superatomai/sdk-web';
+
+const client = new SuperatomClient({
+  userId: 'user_123',
+  projectId: 'project_456',
+});
+
+await client.connect();
+
+// Query data from a collection
+const result = await client.requestData({
+  collection: 'products',
+  operation: 'getMany',
+  params: {
+    filter: { category: 'electronics' },
+    limit: 20,
+    offset: 0
+  },
+  timeout: 10000
+});
+
+if (!result.error && result.data) {
+  console.log('Products:', result.data);
+} else {
+  console.error('Error:', result.error);
+}
+```
+
+## Advanced Usage
+
+### Direct Service Access
+
+All service functions can be imported and used directly for advanced use cases:
+
+```typescript
+import { SuperatomClient, services } from '@superatomai/sdk-web';
+
+const client = new SuperatomClient({ /* ... */ });
+
+// Use service functions directly
+const result = await services.requestData(client, {
+  collection: 'users',
+  operation: 'getMany',
+  params: {},
+  timeout: 10000
+});
+```
+
+### Event Unsubscription
+
+All event handlers return an unsubscribe function:
+
+```typescript
+const unsubscribe = client.onMessage((message) => {
+  console.log('Message:', message);
+});
+
+// Later, when you want to stop listening
+unsubscribe();
+```
+
+### Reconnection with Updated Config
+
+You can reconnect with updated configuration without creating a new client:
+
+```typescript
+await client.reconnectWithConfig({
+  userId: 'new_user_id',
+  debug: true
+});
+```
+
+## License
+
+MIT
+
+## Support
+
+For issues and questions, please contact the SuperAtom team or refer to the SuperAtom platform documentation.