@superatomai/sdk-web 0.0.8 → 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
@@ -226,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
 );
 
@@ -263,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.
@@ -297,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**
@@ -308,6 +354,10 @@ 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
 
@@ -577,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(),
@@ -638,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",
@@ -654,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) {
@@ -1465,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