@superatomai/sdk-web 0.0.8 → 0.0.10

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(),
@@ -550,6 +551,44 @@ zod.z.object({
   to: MessageParticipantSchema.optional(),
   payload: ReportsResponsePayloadSchema
 });
+var BookmarkDataSchema = zod.z.object({
+  id: zod.z.number().optional(),
+  uiblock: zod.z.any(),
+  // JSON object
+  created_at: zod.z.string().optional(),
+  updated_at: zod.z.string().optional()
+});
+var BookmarksRequestPayloadSchema = zod.z.object({
+  operation: zod.z.enum(["create", "update", "delete", "getAll", "getOne"]),
+  data: zod.z.object({
+    id: zod.z.number().optional(),
+    uiblock: zod.z.any().optional()
+  }).optional()
+});
+var BookmarksRequestMessageSchema = zod.z.object({
+  id: zod.z.string(),
+  type: zod.z.literal("BOOKMARKS"),
+  from: MessageParticipantSchema,
+  to: MessageParticipantSchema.optional(),
+  payload: BookmarksRequestPayloadSchema
+});
+var BookmarksResponsePayloadSchema = zod.z.object({
+  success: zod.z.boolean(),
+  error: zod.z.string().optional(),
+  data: zod.z.union([
+    BookmarkDataSchema,
+    zod.z.array(BookmarkDataSchema)
+  ]).optional(),
+  count: zod.z.number().optional(),
+  message: zod.z.string().optional()
+});
+zod.z.object({
+  id: zod.z.string(),
+  type: zod.z.literal("BOOKMARKS_RES"),
+  from: MessageParticipantSchema,
+  to: MessageParticipantSchema.optional(),
+  payload: BookmarksResponsePayloadSchema
+});
 var ClientConfigSchema = zod.z.object({
   userId: zod.z.string(),
   projectId: zod.z.string(),
@@ -572,16 +611,20 @@ __export(services_exports, {
   QuerySpecSchema: () => QuerySpecSchema,
   UIComponentSchema: () => UIComponentSchema,
   UIElementSchema: () => UIElementSchema,
+  createBookmark: () => createBookmark,
   createDashboard: () => createDashboard,
   createReport: () => createReport,
   createUser: () => createUser,
+  deleteBookmark: () => deleteBookmark,
   deleteDashboard: () => deleteDashboard,
   deleteReport: () => deleteReport,
   deleteUser: () => deleteUser,
   getActions: () => getActions,
+  getAllBookmarks: () => getAllBookmarks,
   getAllDashboards: () => getAllDashboards,
   getAllReports: () => getAllReports,
   getAllUsers: () => getAllUsers,
+  getBookmark: () => getBookmark,
   getComponentSuggestions: () => getComponentSuggestions,
   getDashboard: () => getDashboard,
   getReport: () => getReport,
@@ -593,6 +636,7 @@ __export(services_exports, {
   sendComponents: () => sendComponents,
   sendUserPromptRequest: () => sendUserPromptRequest,
   sendUserPromptSuggestionsRequest: () => sendUserPromptSuggestionsRequest,
+  updateBookmark: () => updateBookmark,
   updateDashboard: () => updateDashboard,
   updateReport: () => updateReport,
   updateUser: () => updateUser
@@ -638,8 +682,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 +698,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) {
@@ -1160,6 +1222,122 @@ async function getReport(client, reportId, timeout) {
   };
 }
 
+// src/services/bookmarks/index.ts
+async function createBookmark(client, uiblock, timeout) {
+  const messageId = `bookmarks_create_${Date.now()}`;
+  const message = BookmarksRequestMessageSchema.parse({
+    id: messageId,
+    type: "BOOKMARKS",
+    from: { type: client.type },
+    to: { type: "data-agent" },
+    payload: {
+      operation: "create",
+      data: {
+        uiblock
+      }
+    }
+  });
+  const response = await client.sendWithResponse(message, timeout);
+  const payload = response.payload;
+  return {
+    success: payload.success,
+    error: payload.error,
+    message: payload.message,
+    data: Array.isArray(payload.data) ? payload.data[0] : payload.data
+  };
+}
+async function updateBookmark(client, id, uiblock, timeout) {
+  const messageId = `bookmarks_update_${Date.now()}`;
+  const message = BookmarksRequestMessageSchema.parse({
+    id: messageId,
+    type: "BOOKMARKS",
+    from: { type: client.type },
+    to: { type: "data-agent" },
+    payload: {
+      operation: "update",
+      data: {
+        id,
+        uiblock
+      }
+    }
+  });
+  const response = await client.sendWithResponse(message, timeout);
+  const payload = response.payload;
+  return {
+    success: payload.success,
+    error: payload.error,
+    message: payload.message,
+    data: Array.isArray(payload.data) ? payload.data[0] : payload.data
+  };
+}
+async function deleteBookmark(client, id, timeout) {
+  const messageId = `bookmarks_delete_${Date.now()}`;
+  const message = BookmarksRequestMessageSchema.parse({
+    id: messageId,
+    type: "BOOKMARKS",
+    from: { type: client.type },
+    to: { type: "data-agent" },
+    payload: {
+      operation: "delete",
+      data: {
+        id
+      }
+    }
+  });
+  const response = await client.sendWithResponse(message, timeout);
+  const payload = response.payload;
+  return {
+    success: payload.success,
+    error: payload.error,
+    message: payload.message,
+    data: Array.isArray(payload.data) ? payload.data[0] : payload.data
+  };
+}
+async function getAllBookmarks(client, timeout) {
+  const messageId = `bookmarks_getall_${Date.now()}`;
+  const message = BookmarksRequestMessageSchema.parse({
+    id: messageId,
+    type: "BOOKMARKS",
+    from: { type: client.type },
+    to: { type: "data-agent" },
+    payload: {
+      operation: "getAll"
+    }
+  });
+  const response = await client.sendWithResponse(message, timeout);
+  const payload = response.payload;
+  return {
+    success: payload.success,
+    error: payload.error,
+    data: Array.isArray(payload.data) ? payload.data : payload.data ? [payload.data] : [],
+    count: payload.count,
+    message: payload.message
+  };
+}
+async function getBookmark(client, id, timeout) {
+  const messageId = `bookmarks_getone_${Date.now()}`;
+  const message = BookmarksRequestMessageSchema.parse({
+    id: messageId,
+    type: "BOOKMARKS",
+    from: { type: client.type },
+    to: { type: "data-agent" },
+    payload: {
+      operation: "getOne",
+      data: {
+        id
+      }
+    }
+  });
+  const response = await client.sendWithResponse(message, timeout);
+  const payload = response.payload;
+  return {
+    success: payload.success,
+    error: payload.error,
+    data: Array.isArray(payload.data) ? payload.data[0] : payload.data,
+    message: payload.message
+  };
+}
+
 // src/services/actions.ts
 async function getActions(client, options) {
   const messageId = `msg_${Date.now()}_${Math.random().toString(36).substring(7)}`;
@@ -1465,10 +1643,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
@@ -1598,6 +1778,48 @@ var SuperatomClient = class {
     this.log("info", "Fetching dashboard:", dashboardId);
     return getDashboard(this, dashboardId, timeout);
   }
+  // ==================== Bookmark Management Methods ====================
+  // These methods delegate to bookmark service for bookmark CRUD operations
+  /**
+   * Create a new bookmark
+   * Delegates to bookmarks service
+   */
+  async createBookmark(uiblock, timeout) {
+    this.log("info", "Creating bookmark");
+    return createBookmark(this, uiblock, timeout);
+  }
+  /**
+   * Update an existing bookmark
+   * Delegates to bookmarks service
+   */
+  async updateBookmark(id, uiblock, timeout) {
+    this.log("info", "Updating bookmark:", id);
+    return updateBookmark(this, id, uiblock, timeout);
+  }
+  /**
+   * Delete a bookmark
+   * Delegates to bookmarks service
+   */
+  async deleteBookmark(id, timeout) {
+    this.log("info", "Deleting bookmark:", id);
+    return deleteBookmark(this, id, timeout);
+  }
+  /**
+   * Get all bookmarks
+   * Delegates to bookmarks service
+   */
+  async getAllBookmarks(timeout) {
+    this.log("info", "Fetching all bookmarks");
+    return getAllBookmarks(this, timeout);
+  }
+  /**
+   * Get a specific bookmark by ID
+   * Delegates to bookmarks service
+   */
+  async getBookmark(id, timeout) {
+    this.log("info", "Fetching bookmark:", id);
+    return getBookmark(this, id, timeout);
+  }
   // ==================== Report Management Methods ====================
   // These methods delegate to report service for admin report CRUD operations
   /**