@superatomai/sdk-web 0.0.7 → 0.0.9

package/README.md

@@ -8,13 +8,14 @@ SuperAtom Web SDK - TypeScript SDK for browser-based WebSocket communication wit
 - 🔒 Type-safe message validation using Zod v4
 - 🎯 Request/response pattern with timeout support
 - 📦 Bundle management with chunked transfer
-- 🧩 Component registration system
+- 🧩 Component registration and communication system
 - 🔐 Authentication (login and token verification)
 - 👥 User management (CRUD operations)
 - 📊 Dashboard management (CRUD operations)
 - 📈 Report management (CRUD operations)
-- 🤖 AI component suggestions
+- 🤖 AI component suggestions with text streaming support
 - 💾 Data collection queries
+- ⚡ Actions API for runtime operations
 - 📝 UI logging support
 
 ## Installation
@@ -127,21 +128,42 @@ const verifyResponse = await client.sendAuthVerifyRequest(
 
 ```typescript
 // Create a new user
-const result = await client.createUser(username, password, timeout);
+const result = await client.createUser(
+  username,
+  password,
+  email?,      // Optional: User email
+  fullname?,   // Optional: User full name
+  role?,       // Optional: User role
+  timeout?
+);
+// Returns: { success, username?, email?, fullname?, role?, message?, error? }
 
 // Update an existing user
-const result = await client.updateUser(username, password, timeout);
+const result = await client.updateUser(
+  username,
+  {
+    password?: string,   // Optional: New password
+    email?: string,      // Optional: New email
+    fullname?: string,   // Optional: New full name
+    role?: string,       // Optional: New role
+  },
+  timeout?
+);
+// Returns: { success, username?, email?, fullname?, role?, message?, error? }
 
 // Delete a user
 const result = await client.deleteUser(username, timeout);
+// Returns: { success, username?, email?, fullname?, role?, message?, error? }
 
 // Get all users
 const result = await client.getAllUsers(timeout);
 // Returns: { success, users, count, error?, message? }
+// User object: { username, email?, fullname?, role?, wsIds }
 
 // Get a specific user
 const result = await client.getUser(username, timeout);
 // Returns: { success, user, error?, message? }
+// User object: { username, email?, fullname?, role?, wsIds }
 ```
 
 #### Dashboard Management
@@ -205,11 +227,25 @@ const result = await client.getReport(reportId, timeout);
 #### User Prompts & AI Suggestions
 
 ```typescript
-// Send a user prompt request
+// Send a user prompt request (component mode - default)
 const response = await client.sendUserPromptRequest(
   prompt,
   threadId,
   uiBlockId,
+  'component',  // responseMode: 'component' (default) or 'text'
+  undefined,    // onStream callback (only used for text mode)
+  timeout
+);
+
+// Send a user prompt request with text streaming
+const response = await client.sendUserPromptRequest(
+  prompt,
+  threadId,
+  uiBlockId,
+  'text',       // responseMode: 'text' for streaming
+  (chunk) => {  // onStream callback receives text chunks
+    console.log('Stream chunk:', chunk);
+  },
   timeout
 );
 
@@ -242,6 +278,36 @@ const result = await client.requestData({
 // Returns: { data?, error? }
 ```
 
+#### Actions API
+
+```typescript
+// Get available actions for the current context
+const result = await client.getActions({
+  SA_RUNTIME: {
+    threadId: 'thread_123',
+    uiBlockId: 'block_456'
+  },
+  timeout: 10000
+});
+// Returns: { success, data?, error? }
+```
+
+#### Component Management
+
+```typescript
+// Send component list to server
+await client.sendComponents([
+  {
+    id: 'comp_1',
+    name: 'MyComponent',
+    type: 'custom',
+    description: 'A custom component',
+    props: { /* ... */ }
+  },
+  // ... more components
+]);
+```
+
 ### Component Setup
 
 Register your components with SuperAtom for dynamic rendering.
@@ -276,6 +342,7 @@ The SDK supports the following message types (all validated with Zod schemas):
 
 **User Prompts & AI**
 - `USER_PROMPT_REQ` / `USER_PROMPT_RES` - User prompt processing
+- `USER_PROMPT_STREAM` - Real-time text streaming from AI responses
 - `USER_PROMPT_SUGGESTIONS_REQ` / `USER_PROMPT_SUGGESTIONS_RES` - Component suggestions
 
 **Bundle & Data**
@@ -287,11 +354,76 @@ The SDK supports the following message types (all validated with Zod schemas):
 - `DASHBOARDS` / `DASHBOARDS_RES` - Dashboard CRUD operations
 - `REPORTS` / `REPORTS_RES` - Report CRUD operations
 
+**Actions & Components**
+- `ACTIONS` / `ACTIONS_RES` - Runtime actions API
+- `COMPONENT_LIST_RES` - Send component list to server
+
 **Logging**
 - `UI_LOGS` - UI logging messages
 
 All message types are fully typed and validated using Zod v4 schemas.
 
+### USERS Schema
+
+The USERS message type supports comprehensive user management with the following structure:
+
+**Request Payload** (`USERS`):
+```typescript
+{
+  operation: 'create' | 'update' | 'delete' | 'getAll' | 'getOne',
+  data?: {
+    username?: string,        // Required for all operations except getAll
+    email?: string,           // Optional: User email (validated)
+    password?: string,        // Required for create, optional for update
+    fullname?: string,        // Optional: User's full name
+    role?: string,            // Optional: User's role
+  }
+}
+```
+
+**Response Payload** (`USERS_RES`):
+```typescript
+{
+  success: boolean,
+  error?: string,
+  data?: {
+    username?: string,
+    email?: string,
+    fullname?: string,
+    role?: string,
+    message?: string,
+    // For getAll operation
+    users?: Array<{
+      username: string,
+      email?: string,
+      fullname?: string,
+      role?: string,
+      wsIds: string[]
+    }>,
+    count?: number,
+    // For getOne operation
+    user?: {
+      username: string,
+      email?: string,
+      fullname?: string,
+      role?: string,
+      wsIds: string[]
+    }
+  }
+}
+```
+
+**User Object Structure**:
+```typescript
+interface User {
+  username: string;          // Required: Unique username
+  email?: string;            // Optional: Validated email address
+  fullname?: string;         // Optional: User's full name
+  role?: string;             // Optional: User role (e.g., 'admin', 'editor', 'viewer')
+  wsIds: string[];           // WebSocket connection IDs (in-memory only)
+}
+```
+
 ## Type Safety
 
 All messages are validated using Zod v4 schemas. The SDK exports comprehensive type definitions and schemas:
@@ -380,10 +512,19 @@ const client = new SuperatomClient({
 
 await client.connect();
 
-// Create a new user
-const createResult = await client.createUser('newuser', 'password123');
+// Create a new user with all fields
+const createResult = await client.createUser(
+  'newuser',
+  'password123',
+  'user@example.com',     // email
+  'John Doe',             // fullname
+  'editor'                // role
+);
 if (createResult.success) {
   console.log('User created:', createResult.username);
+  console.log('Email:', createResult.email);
+  console.log('Full name:', createResult.fullname);
+  console.log('Role:', createResult.role);
 }
 
 // Get all users
@@ -391,12 +532,25 @@ 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)`);
+    console.log(`- ${user.username} (${user.email || 'no email'})`);
+    console.log(`  Full name: ${user.fullname || 'N/A'}`);
+    console.log(`  Role: ${user.role || 'N/A'}`);
+    console.log(`  Connections: ${user.wsIds.length}`);
   });
 }
 
-// Update a user
-await client.updateUser('newuser', 'newpassword456');
+// Update a user - change multiple fields
+await client.updateUser('newuser', {
+  password: 'newpassword456',
+  email: 'newemail@example.com',
+  fullname: 'Jane Doe',
+  role: 'admin'
+});
+
+// Update a user - change only specific fields
+await client.updateUser('newuser', {
+  role: 'viewer'  // Only update role
+});
 
 // Delete a user
 await client.deleteUser('newuser');
@@ -473,6 +627,81 @@ if (!result.error && result.data) {
 }
 ```
 
+### Text Streaming Example
+
+```typescript
+import { SuperatomClient } from '@superatomai/sdk-web';
+
+const client = new SuperatomClient({
+  userId: 'user_123',
+  projectId: 'project_456',
+});
+
+await client.connect();
+
+// Use text streaming for real-time AI responses
+let streamedText = '';
+
+const response = await client.sendUserPromptRequest(
+  'Explain how photosynthesis works',
+  'thread_123',
+  'block_456',
+  'text',  // Enable text streaming mode
+  (chunk) => {
+    // Receive text chunks in real-time
+    streamedText += chunk;
+    console.log('Received chunk:', chunk);
+    // Update UI with streaming text
+    updateUIWithText(streamedText);
+  },
+  30000
+);
+
+console.log('Streaming complete. Final response:', response);
+```
+
+### Actions API Example
+
+```typescript
+import { SuperatomClient } from '@superatomai/sdk-web';
+
+const client = new SuperatomClient({
+  userId: 'user_123',
+  projectId: 'project_456',
+});
+
+await client.connect();
+
+// Get available actions for the current runtime context
+const result = await client.getActions({
+  SA_RUNTIME: {
+    threadId: 'thread_123',
+    uiBlockId: 'block_456'
+  },
+  timeout: 10000
+});
+
+if (result.success && result.data) {
+  console.log('Available actions:', result.data);
+} else {
+  console.error('Error:', result.error);
+}
+
+// Send component list to server
+await client.sendComponents([
+  {
+    id: 'my_component_1',
+    name: 'DataTable',
+    type: 'table',
+    description: 'Display data in table format',
+    props: {
+      columns: ['name', 'email', 'status'],
+      data: []
+    }
+  }
+]);
+```
+
 ## Advanced Usage
 
 ### Direct Service Access

package/dist/index.cjs

@@ -252,7 +252,8 @@ var UserPromptRequestPayloadSchema = zod.z.object({
   SA_RUNTIME: zod.z.object({
     threadId: zod.z.string(),
     uiBlockId: zod.z.string()
-  }).optional()
+  }).optional(),
+  responseMode: zod.z.enum(["component", "text"]).optional()
 });
 var UserPromptRequestMessageSchema = zod.z.object({
   id: zod.z.string(),
@@ -434,7 +435,10 @@ var UsersRequestPayloadSchema = zod.z.object({
   operation: zod.z.enum(["create", "update", "delete", "getAll", "getOne"]),
   data: zod.z.object({
     username: zod.z.string().optional(),
-    password: zod.z.string().optional()
+    email: zod.z.string().email("Invalid email format").optional(),
+    password: zod.z.string().optional(),
+    fullname: zod.z.string().optional(),
+    role: zod.z.string().optional()
   }).optional()
 });
 var UsersRequestMessageSchema = zod.z.object({
@@ -449,13 +453,22 @@ var UsersResponsePayloadSchema = zod.z.object({
   error: zod.z.string().optional(),
   data: zod.z.object({
     username: zod.z.string().optional(),
+    email: zod.z.string().optional(),
+    fullname: zod.z.string().optional(),
+    role: zod.z.string().optional(),
     message: zod.z.string().optional(),
     users: zod.z.array(zod.z.object({
       username: zod.z.string(),
+      email: zod.z.string().optional(),
+      fullname: zod.z.string().optional(),
+      role: zod.z.string().optional(),
       wsIds: zod.z.array(zod.z.string())
     })).optional(),
     user: zod.z.object({
       username: zod.z.string(),
+      email: zod.z.string().optional(),
+      fullname: zod.z.string().optional(),
+      role: zod.z.string().optional(),
       wsIds: zod.z.array(zod.z.string())
     }).optional(),
     count: zod.z.number().optional()
@@ -626,8 +639,8 @@ async function sendAuthVerifyRequest(client, token, timeout) {
 }
 
 // src/services/userPrompt.ts
-async function sendUserPromptRequest(client, prompt, threadId, uiBlockId, timeout) {
-  const messageId = `msg_${Date.now()}`;
+async function sendUserPromptRequest(client, prompt, threadId, uiBlockId, responseMode, onStream, timeout) {
+  const messageId = `user_prompt_req_msg_${Date.now()}`;
   const message = UserPromptRequestMessageSchema.parse({
     id: messageId,
     type: "USER_PROMPT_REQ",
@@ -642,11 +655,29 @@ async function sendUserPromptRequest(client, prompt, threadId, uiBlockId, timeou
       SA_RUNTIME: {
         threadId,
         uiBlockId
-      }
+      },
+      responseMode
     }
   });
-  const response = await client.sendWithResponse(message, timeout);
-  return response;
+  let streamUnsubscribe = null;
+  if (responseMode === "text" && onStream) {
+    streamUnsubscribe = client.onMessage((msg) => {
+      if (msg.type === "USER_PROMPT_STREAM" && msg.id === `stream_${uiBlockId}`) {
+        const chunk = msg.payload?.chunk;
+        if (chunk) {
+          onStream(chunk);
+        }
+      }
+    });
+  }
+  try {
+    const response = await client.sendWithResponse(message, timeout);
+    return response;
+  } finally {
+    if (streamUnsubscribe) {
+      streamUnsubscribe();
+    }
+  }
 }
 async function sendUserPromptSuggestionsRequest(client, prompt, limit = 5, timeout) {
   if (!prompt || prompt.trim().length === 0) {
@@ -780,7 +811,7 @@ async function sendComponents(client, components) {
 }
 
 // src/services/users.ts
-async function createUser(client, username, password, timeout) {
+async function createUser(client, username, password, email, fullname, role, timeout) {
   const messageId = `users_create_${Date.now()}`;
   const message = UsersRequestMessageSchema.parse({
     id: messageId,
@@ -791,7 +822,10 @@ async function createUser(client, username, password, timeout) {
       operation: "create",
       data: {
         username,
-        password
+        password,
+        email,
+        fullname,
+        role
       }
     }
   });
@@ -801,10 +835,13 @@ async function createUser(client, username, password, timeout) {
     success: payload.success,
     error: payload.error,
     message: payload.data?.message,
-    username: payload.data?.username
+    username: payload.data?.username,
+    email: payload.data?.email,
+    fullname: payload.data?.fullname,
+    role: payload.data?.role
   };
 }
-async function updateUser(client, username, password, timeout) {
+async function updateUser(client, username, updates, timeout) {
   const messageId = `users_update_${Date.now()}`;
   const message = UsersRequestMessageSchema.parse({
     id: messageId,
@@ -815,7 +852,7 @@ async function updateUser(client, username, password, timeout) {
       operation: "update",
       data: {
         username,
-        password
+        ...updates
       }
     }
   });
@@ -825,7 +862,10 @@ async function updateUser(client, username, password, timeout) {
     success: payload.success,
     error: payload.error,
     message: payload.data?.message,
-    username: payload.data?.username
+    username: payload.data?.username,
+    email: payload.data?.email,
+    fullname: payload.data?.fullname,
+    role: payload.data?.role
   };
 }
 async function deleteUser(client, username, timeout) {
@@ -848,7 +888,10 @@ async function deleteUser(client, username, timeout) {
     success: payload.success,
     error: payload.error,
     message: payload.data?.message,
-    username: payload.data?.username
+    username: payload.data?.username,
+    email: payload.data?.email,
+    fullname: payload.data?.fullname,
+    role: payload.data?.role
   };
 }
 async function getAllUsers(client, timeout) {
@@ -1441,10 +1484,12 @@ var SuperatomClient = class {
   /**
    * Send a user prompt request
    * Delegates to user prompt service
+   * @param responseMode - 'component' for component response (default), 'text' for text streaming
+   * @param onStream - Optional callback for streaming text chunks (only for text mode)
    */
-  async sendUserPromptRequest(prompt, threadId, uiBlockId, timeout) {
-    this.log("info", "Sending user prompt request");
-    return sendUserPromptRequest(this, prompt, threadId, uiBlockId, timeout);
+  async sendUserPromptRequest(prompt, threadId, uiBlockId, responseMode, onStream, timeout) {
+    this.log("info", "Sending user prompt request with streaming support");
+    return sendUserPromptRequest(this, prompt, threadId, uiBlockId, responseMode, onStream, timeout);
   }
   /**
    * Send a user prompt suggestions request
@@ -1496,17 +1541,17 @@ var SuperatomClient = class {
    * Create a new user
    * Delegates to users service
    */
-  async createUser(username, password, timeout) {
+  async createUser(username, password, email, fullname, role, timeout) {
     this.log("info", "Creating user:", username);
-    return createUser(this, username, password, timeout);
+    return createUser(this, username, password, email, fullname, role, timeout);
   }
   /**
    * Update an existing user
    * Delegates to users service
    */
-  async updateUser(username, password, timeout) {
+  async updateUser(username, updates, timeout) {
     this.log("info", "Updating user:", username);
-    return updateUser(this, username, password, timeout);
+    return updateUser(this, username, updates, timeout);
   }
   /**
    * Delete a user