@toothfairyai/cli 1.0.16 → 1.1.0

package/README.md

@@ -205,6 +205,81 @@ toothfairy send "Hello" --agent-id "agent-123" --output json | jq '.agentRespons
 toothfairy search "documentation" --output json | jq '.[].title'
 ```
 
+## SDK Usage
+
+This package also provides a JavaScript SDK for programmatic access to ToothFairyAI.
+
+### Basic SDK Usage
+
+```javascript
+const ToothFairyAPI = require('@toothfairyai/cli/src/api');
+
+const api = new ToothFairyAPI(
+  'https://api.toothfairyai.com',    // baseUrl
+  'https://ai.toothfairyai.com',     // aiUrl
+  'https://stream.toothfairyai.com', // aiStreamUrl
+  'your-api-key',                    // apiKey
+  'your-workspace-id',               // workspaceId
+  false                              // verbose mode
+);
+
+// Send a message with streaming response
+await api.sendMessageToAgentStream(
+  'Hello!',
+  'agent-id',
+  null, // phoneNumber
+  null, // customerId
+  null, // providerId
+  {},   // customerInfo
+  (eventType, data) => {
+    console.log(`Event: ${eventType}`, data);
+  }
+);
+```
+
+### New in v1.1.0: Show Progress Flag
+
+The SDK now supports a `showProgress` flag that enables tracking of all events from the SSE endpoint, similar to the CLI's `--show-progress` flag:
+
+```javascript
+// Default behavior (standard events only)
+await api.sendMessageToAgentStream(
+  'Hello!', 
+  'agent-id', 
+  null, null, null, {}, 
+  (eventType, data) => {
+    // Receives: 'status', 'progress', 'data', 'complete', 'error', etc.
+    console.log(eventType, data);
+  }
+);
+
+// With showProgress enabled (all SSE events)
+await api.sendMessageToAgentStream(
+  'Hello!', 
+  'agent-id', 
+  null, null, null, {}, 
+  (eventType, data) => {
+    if (eventType === 'sse_event') {
+      // Raw SSE event with complete data from streaming endpoint
+      console.log('Raw SSE event:', data);
+    } else {
+      // Standard processed events
+      console.log('Standard event:', eventType, data);
+    }
+  },
+  {}, // attachments
+  true // showProgress = true
+);
+```
+
+**Event Types:**
+- `'status'`: Connection status ('connected', 'complete')
+- `'progress'`: Agent processing status updates
+- `'data'`: Streaming response text chunks
+- `'complete'`: Final response with metadata
+- `'error'`: Error events
+- `'sse_event'`: All raw SSE events (when showProgress=true)
+
 For full documentation and cross-platform examples, see the main [README.md](../README.md) in the parent directory.
 
 ## Development

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toothfairyai/cli",
-  "version": "1.0.16",
+  "version": "1.1.0",
   "description": "Command-line interface for ToothFairyAI API",
   "main": "index.js",
   "bin": {

package/src/api.js

@@ -193,14 +193,14 @@ class ToothFairyAPI {
         customerId ||
         `cli-user-${
           Math.abs(
-            message.split('').reduce((a, b) => {
+            message.split("").reduce((a, b) => {
               a = (a << 5) - a + b.charCodeAt(0);
               return a & a;
             }, 0)
           ) % 10000
         }`;
-      phoneNumber = phoneNumber || '+1234567890';
-      providerId = providerId || 'default-sms-provider';
+      phoneNumber = phoneNumber || "+1234567890";
+      providerId = providerId || "default-sms-provider";
 
       // Process file attachments if provided
       const processedAttachments = await this._processAttachments(attachments);
@@ -227,8 +227,8 @@ class ToothFairyAPI {
       const messageData = {
         chatID: createdChat.id,
         text: message,
-        role: 'user',
-        userID: 'CLI',
+        role: "user",
+        userID: "CLI",
         ...processedAttachments,
       };
       const createdMessage = await this.createMessage(messageData);
@@ -310,6 +310,8 @@ class ToothFairyAPI {
    * @param {string|null} providerId - SMS provider ID
    * @param {Object} customerInfo - Additional customer information
    * @param {Function} onEvent - Callback function called for each event
+   * @param {Object} attachments - File attachments (images, audios, videos, files)
+   * @param {boolean} showProgress - Show all progress events from SSE endpoint (default: false)
    * @returns {Promise<void>} - Promise resolves when streaming is complete
    *
    * Event Types Explained:
@@ -324,8 +326,13 @@ class ToothFairyAPI {
    * - 'data': Actual response text chunks (progressive text building)
    * - 'complete': Final response with all metadata
    * - 'error': Error occurred during streaming
+   * - 'sse_event': All raw SSE events (only when showProgress=true)
    *
    * The onEvent callback receives: (eventType, eventData) => {}
+   * 
+   * When showProgress is true, all SSE events will be emitted to the onEvent callback
+   * with the 'sse_event' type, providing access to all raw events from the streaming
+   * endpoint, similar to the CLI's --show-progress flag behavior.
    */
   async sendMessageToAgentStream(
     message,
@@ -335,7 +342,8 @@ class ToothFairyAPI {
     providerId = null,
     customerInfo = {},
     onEvent,
-    attachments = {}
+    attachments = {},
+    showProgress = false
   ) {
     try {
       // Use defaults for optional parameters
@@ -343,14 +351,14 @@ class ToothFairyAPI {
         customerId ||
         `cli-user-${
           Math.abs(
-            message.split('').reduce((a, b) => {
+            message.split("").reduce((a, b) => {
               a = (a << 5) - a + b.charCodeAt(0);
               return a & a;
             }, 0)
           ) % 10000
         }`;
-      phoneNumber = phoneNumber || '+1234567890';
-      providerId = providerId || 'default-sms-provider';
+      phoneNumber = phoneNumber || "+1234567890";
+      providerId = providerId || "default-sms-provider";
 
       // Process file attachments if provided
       const processedAttachments = await this._processAttachments(attachments);
@@ -381,8 +389,8 @@ class ToothFairyAPI {
       const messageData = {
         chatID: createdChat.id,
         text: message,
-        role: 'user',
-        userID: 'CLI',
+        role: "user",
+        userID: "CLI",
         ...processedAttachments,
       };
       const createdMessage = await this.createMessage(messageData);
@@ -442,13 +450,19 @@ class ToothFairyAPI {
                   try {
                     const eventData = JSON.parse(dataStr);
 
-                    // Determine event type based on the data structure
+                    // If showProgress is enabled, emit all events
+                    if (showProgress) {
+                      // Emit all events with their raw structure
+                      onEvent('sse_event', eventData);
+                    }
+
+                    // Standard event processing (always executed for backward compatibility)
                     if (eventData.status) {
-                      if (eventData.status === "connected") {
-                        onEvent("status", eventData);
-                      } else if (eventData.status === "complete") {
-                        onEvent("status", eventData);
-                      } else if (eventData.status === "inProgress") {
+                      if (eventData.status === 'connected') {
+                        onEvent('status', eventData);
+                      } else if (eventData.status === 'complete') {
+                        onEvent('status', eventData);
+                      } else if (eventData.status === 'inProgress') {
                         // Parse metadata to understand what's happening
                         let metadata = {};
                         if (eventData.metadata) {
@@ -463,39 +477,39 @@ class ToothFairyAPI {
                         if (metadata.agent_processing_status) {
                           const processingStatus =
                             metadata.agent_processing_status;
-                          onEvent("progress", {
+                          onEvent('progress', {
                             ...eventData,
                             processing_status: processingStatus,
                             metadata_parsed: metadata,
                           });
                         } else {
-                          onEvent("progress", {
+                          onEvent('progress', {
                             ...eventData,
                             metadata_parsed: metadata,
                           });
                         }
-                      } else if (eventData.status === "fulfilled") {
+                      } else if (eventData.status === 'fulfilled') {
                         // Final response with complete data
-                        onEvent("complete", eventData);
+                        onEvent('complete', eventData);
                       }
-                    } else if (eventData.text && eventData.type === "message") {
+                    } else if (eventData.text && eventData.type === 'message') {
                       // This is streaming text data
-                      onEvent("data", eventData);
+                      onEvent('data', eventData);
                     } else if (
-                      eventData.type === "message" &&
+                      eventData.type === 'message' &&
                       eventData.images !== undefined
                     ) {
                       // Additional message metadata (images, files, etc.)
-                      onEvent("metadata", eventData);
+                      onEvent('metadata', eventData);
                     } else if (
-                      eventData.type === "message" &&
+                      eventData.type === 'message' &&
                       eventData.callbackMetadata
                     ) {
                       // Callback metadata with function details and execution plan
-                      onEvent("callback", eventData);
+                      onEvent('callback', eventData);
                     } else {
                       // Generic event data
-                      onEvent("unknown", eventData);
+                      onEvent('unknown', eventData);
                     }
                   } catch (e) {
                     console.error(
@@ -1689,7 +1703,7 @@ class ToothFairyAPI {
 
   /**
    * Process file attachments and upload them for message inclusion
-   * 
+   *
    * @param {Object} attachments - Attachment configuration
    * @param {string[]} attachments.images - Array of image file paths (max 1)
    * @param {string[]} attachments.audios - Array of audio file paths (max 1)
@@ -1699,7 +1713,7 @@ class ToothFairyAPI {
    */
   async _processAttachments(attachments = {}) {
     const result = {};
-    
+
     if (!attachments || Object.keys(attachments).length === 0) {
       return result;
     }
@@ -1707,23 +1721,26 @@ class ToothFairyAPI {
     try {
       // Validate attachment limits
       if (attachments.images && attachments.images.length > 1) {
-        throw new Error('Maximum 1 image attachment allowed');
+        throw new Error("Maximum 1 image attachment allowed");
       }
       if (attachments.audios && attachments.audios.length > 1) {
-        throw new Error('Maximum 1 audio attachment allowed');
+        throw new Error("Maximum 1 audio attachment allowed");
       }
       if (attachments.videos && attachments.videos.length > 1) {
-        throw new Error('Maximum 1 video attachment allowed');
+        throw new Error("Maximum 1 video attachment allowed");
       }
       if (attachments.files && attachments.files.length > 5) {
-        throw new Error('Maximum 5 file attachments allowed');
+        throw new Error("Maximum 5 file attachments allowed");
       }
 
       // Process images
       if (attachments.images && attachments.images.length > 0) {
         const imageResults = [];
         for (const imagePath of attachments.images) {
-          const uploadResult = await this.uploadFile(imagePath, this.workspaceId);
+          const uploadResult = await this.uploadFile(
+            imagePath,
+            this.workspaceId
+          );
           imageResults.push(uploadResult.filename);
         }
         result.images = imageResults;
@@ -1733,7 +1750,10 @@ class ToothFairyAPI {
       if (attachments.audios && attachments.audios.length > 0) {
         const audioResults = [];
         for (const audioPath of attachments.audios) {
-          const uploadResult = await this.uploadFile(audioPath, this.workspaceId);
+          const uploadResult = await this.uploadFile(
+            audioPath,
+            this.workspaceId
+          );
           audioResults.push(uploadResult.filename);
         }
         result.audios = audioResults;
@@ -1743,7 +1763,10 @@ class ToothFairyAPI {
       if (attachments.videos && attachments.videos.length > 0) {
         const videoResults = [];
         for (const videoPath of attachments.videos) {
-          const uploadResult = await this.uploadFile(videoPath, this.workspaceId);
+          const uploadResult = await this.uploadFile(
+            videoPath,
+            this.workspaceId
+          );
           videoResults.push(uploadResult.filename);
         }
         result.videos = videoResults;
@@ -1753,17 +1776,20 @@ class ToothFairyAPI {
       if (attachments.files && attachments.files.length > 0) {
         const fileResults = [];
         for (const filePath of attachments.files) {
-          const uploadResult = await this.uploadFile(filePath, this.workspaceId);
+          const uploadResult = await this.uploadFile(
+            filePath,
+            this.workspaceId
+          );
           fileResults.push(uploadResult.filename);
         }
         result.files = fileResults;
       }
 
       if (this.verbose) {
-        const chalk = require('chalk');
-        console.error(chalk.dim('\n--- Processed Attachments ---'));
+        const chalk = require("chalk");
+        console.error(chalk.dim("\n--- Processed Attachments ---"));
         console.error(chalk.dim(`Result: ${JSON.stringify(result, null, 2)}`));
-        console.error(chalk.dim('-----------------------------\n'));
+        console.error(chalk.dim("-----------------------------\n"));
       }
 
       return result;