@superatomai/sdk-node 0.0.29 → 0.0.31

package/dist/index.d.mts

@@ -1650,6 +1650,10 @@ declare class SuperatomSDK {
     private userManager;
     private dashboardManager;
     private reportManager;
+    private pingInterval;
+    private lastPong;
+    private readonly PING_INTERVAL_MS;
+    private readonly PONG_TIMEOUT_MS;
     constructor(config: SuperatomSDKConfig);
     /**
      * Initialize PromptLoader and load prompts into memory
@@ -1717,6 +1721,19 @@ declare class SuperatomSDK {
      */
     addCollection<TParams = any, TResult = any>(collectionName: string, operation: CollectionOperation | string, handler: CollectionHandler<TParams, TResult>): void;
     private handleReconnect;
+    /**
+     * Start heartbeat to keep WebSocket connection alive
+     * Sends PING every 3 minutes to prevent idle timeout from cloud infrastructure
+     */
+    private startHeartbeat;
+    /**
+     * Stop the heartbeat interval
+     */
+    private stopHeartbeat;
+    /**
+     * Handle PONG response from server
+     */
+    private handlePong;
     private storeComponents;
     /**
      * Set tools for the SDK instance

package/dist/index.d.ts

@@ -1650,6 +1650,10 @@ declare class SuperatomSDK {
     private userManager;
     private dashboardManager;
     private reportManager;
+    private pingInterval;
+    private lastPong;
+    private readonly PING_INTERVAL_MS;
+    private readonly PONG_TIMEOUT_MS;
     constructor(config: SuperatomSDKConfig);
     /**
      * Initialize PromptLoader and load prompts into memory
@@ -1717,6 +1721,19 @@ declare class SuperatomSDK {
      */
     addCollection<TParams = any, TResult = any>(collectionName: string, operation: CollectionOperation | string, handler: CollectionHandler<TParams, TResult>): void;
     private handleReconnect;
+    /**
+     * Start heartbeat to keep WebSocket connection alive
+     * Sends PING every 3 minutes to prevent idle timeout from cloud infrastructure
+     */
+    private startHeartbeat;
+    /**
+     * Stop the heartbeat interval
+     */
+    private stopHeartbeat;
+    /**
+     * Handle PONG response from server
+     */
+    private handlePong;
     private storeComponents;
     /**
      * Set tools for the SDK instance

package/dist/index.js

@@ -4832,20 +4832,25 @@ ${JSON.stringify(tool.requiredFields || [], null, 2)}`;
       logCollector?.info("Generating text response with query execution capability...");
       const tools = [{
         name: "execute_query",
-        description: "Executes a SQL query against the database and returns the results. Use this when the user asks for data. If the query fails, you will receive the error and can retry with a corrected query.",
+        description: "Executes a parameterized SQL query against the database. CRITICAL: NEVER hardcode literal values in WHERE/HAVING conditions - ALWAYS use $paramName placeholders and pass actual values in params object.",
         input_schema: {
           type: "object",
           properties: {
-            query: {
+            sql: {
               type: "string",
-              description: "The SQL query to execute. Must be valid SQL syntax using table and column names from the schema."
+              description: "SQL query with $paramName placeholders for ALL literal values in WHERE/HAVING conditions. NEVER hardcode values like WHERE status = 'Delivered' - instead use WHERE status = $status. Table names, column names, and SQL keywords stay as-is."
+            },
+            params: {
+              type: "object",
+              description: 'REQUIRED when SQL has WHERE/HAVING conditions. Maps each $paramName placeholder (without $) to its actual value. Pattern: WHERE col = $name \u2192 params: { "name": "value" }. Every placeholder in SQL MUST have a corresponding entry here.',
+              additionalProperties: true
             },
             reasoning: {
               type: "string",
               description: "Brief explanation of what this query does and why it answers the user's question."
             }
           },
-          required: ["query"],
+          required: ["sql"],
           additionalProperties: false
         }
       }];
@@ -4940,14 +4945,18 @@ ${JSON.stringify(tool.requiredFields || [], null, 2)}`;
       } : void 0;
       const toolHandler = async (toolName, toolInput) => {
         if (toolName === "execute_query") {
-          let query = toolInput.query;
+          let sql = toolInput.sql;
+          const params = toolInput.params || {};
           const reasoning = toolInput.reasoning;
           const { ensureQueryLimit: ensureQueryLimit2 } = await Promise.resolve().then(() => (init_utils(), utils_exports));
-          query = ensureQueryLimit2(query, 32, 32);
-          const queryKey = query.toLowerCase().replace(/\s+/g, " ").trim();
+          sql = ensureQueryLimit2(sql, 32, 32);
+          const queryKey = sql.toLowerCase().replace(/\s+/g, " ").trim();
           const attempts = (queryAttempts.get(queryKey) || 0) + 1;
           queryAttempts.set(queryKey, attempts);
-          logger.info(`[${this.getProviderName()}] Executing query (attempt ${attempts}/${MAX_QUERY_ATTEMPTS}): ${query.substring(0, 100)}...`);
+          logger.info(`[${this.getProviderName()}] Executing query (attempt ${attempts}/${MAX_QUERY_ATTEMPTS}): ${sql.substring(0, 100)}...`);
+          if (Object.keys(params).length > 0) {
+            logger.info(`[${this.getProviderName()}] Query params: ${JSON.stringify(params)}`);
+          }
           if (reasoning) {
             logCollector?.info(`Query reasoning: ${reasoning}`);
           }
@@ -4969,6 +4978,8 @@ Please try rephrasing your question or simplifying your request.
           }
           try {
             if (wrappedStreamCallback) {
+              const paramsDisplay = Object.keys(params).length > 0 ? `
+**Parameters:** ${JSON.stringify(params)}` : "";
               if (attempts === 1) {
                 wrappedStreamCallback(`
 
@@ -4982,8 +4993,8 @@ Please try rephrasing your question or simplifying your request.
                 }
                 wrappedStreamCallback(`\u{1F4DD} **Generated SQL Query:**
 \`\`\`sql
-${query}
-\`\`\`
+${sql}
+\`\`\`${paramsDisplay}
 
 `);
                 wrappedStreamCallback(`\u26A1 **Executing query...**
@@ -5002,8 +5013,8 @@ ${query}
                 }
                 wrappedStreamCallback(`\u{1F4DD} **Corrected SQL Query:**
 \`\`\`sql
-${query}
-\`\`\`
+${sql}
+\`\`\`${paramsDisplay}
 
 `);
                 wrappedStreamCallback(`\u26A1 **Executing query...**
@@ -5013,13 +5024,14 @@ ${query}
             }
             logCollector?.logQuery(
               `Executing SQL query (attempt ${attempts})`,
-              query,
+              { sql, params },
               { reasoning, attempt: attempts }
             );
             if (!collections || !collections["database"] || !collections["database"]["execute"]) {
               throw new Error("Database collection not registered. Please register database.execute collection to execute queries.");
             }
-            const result2 = await collections["database"]["execute"]({ sql: query });
+            const queryPayload = Object.keys(params).length > 0 ? { sql: JSON.stringify({ sql, values: params }) } : { sql };
+            const result2 = await collections["database"]["execute"](queryPayload);
             const data = result2?.data || result2;
             const rowCount = result2?.count ?? (Array.isArray(data) ? data.length : "N/A");
             logger.info(`[${this.getProviderName()}] Query executed successfully, rows returned: ${rowCount}`);
@@ -9781,6 +9793,7 @@ init_logger();
 var SDK_VERSION = "0.0.8";
 var DEFAULT_WS_URL = "wss://ws.superatom.ai/websocket";
 var SuperatomSDK = class {
+  // 3.5 minutes (PING_INTERVAL + 30s grace)
   constructor(config) {
     this.ws = null;
     this.messageHandlers = /* @__PURE__ */ new Map();
@@ -9791,6 +9804,12 @@ var SuperatomSDK = class {
     this.collections = {};
     this.components = [];
     this.tools = [];
+    // Heartbeat properties for keeping WebSocket connection alive
+    this.pingInterval = null;
+    this.lastPong = Date.now();
+    this.PING_INTERVAL_MS = 18e4;
+    // 3 minutes
+    this.PONG_TIMEOUT_MS = 21e4;
     if (config.logLevel) {
       logger.setLogLevel(config.logLevel);
     }
@@ -9904,6 +9923,7 @@ var SuperatomSDK = class {
           this.connected = true;
           this.reconnectAttempts = 0;
           logger.info("WebSocket connected successfully");
+          this.startHeartbeat();
           resolve();
         });
         this.ws.addEventListener("message", (event) => {
@@ -9932,6 +9952,9 @@ var SuperatomSDK = class {
       const message = IncomingMessageSchema.parse(parsed);
       logger.debug("Received message:", message.type);
       switch (message.type) {
+        case "PONG":
+          this.handlePong();
+          break;
         case "DATA_REQ":
           handleDataRequest(parsed, this.collections, (msg) => this.send(msg)).catch((error) => {
             logger.error("Failed to handle data request:", error);
@@ -10054,6 +10077,7 @@ var SuperatomSDK = class {
    * Disconnect from the WebSocket service
    */
   disconnect() {
+    this.stopHeartbeat();
     if (this.ws) {
       this.ws.close();
       this.ws = null;
@@ -10064,6 +10088,7 @@ var SuperatomSDK = class {
    * Cleanup and disconnect - stops reconnection attempts and closes the connection
    */
   async destroy() {
+    this.stopHeartbeat();
     this.maxReconnectAttempts = 0;
     this.reconnectAttempts = 0;
     this.messageHandlers.clear();
@@ -10105,6 +10130,59 @@ var SuperatomSDK = class {
       logger.error("Max reconnection attempts reached");
     }
   }
+  /**
+   * Start heartbeat to keep WebSocket connection alive
+   * Sends PING every 3 minutes to prevent idle timeout from cloud infrastructure
+   */
+  startHeartbeat() {
+    this.stopHeartbeat();
+    this.lastPong = Date.now();
+    this.pingInterval = setInterval(() => {
+      if (!this.ws || this.ws.readyState !== this.ws.OPEN) {
+        logger.warn("WebSocket not open during heartbeat check, stopping heartbeat");
+        this.stopHeartbeat();
+        return;
+      }
+      const timeSinceLastPong = Date.now() - this.lastPong;
+      if (timeSinceLastPong > this.PONG_TIMEOUT_MS) {
+        logger.warn(`No PONG received for ${timeSinceLastPong}ms, connection may be dead. Reconnecting...`);
+        this.stopHeartbeat();
+        this.ws.close();
+        return;
+      }
+      try {
+        const pingMessage = {
+          type: "PING",
+          from: { type: this.type },
+          payload: { timestamp: Date.now() }
+        };
+        this.ws.send(JSON.stringify(pingMessage));
+        logger.debug("Heartbeat PING sent");
+      } catch (error) {
+        logger.error("Failed to send PING:", error);
+        this.stopHeartbeat();
+        this.ws.close();
+      }
+    }, this.PING_INTERVAL_MS);
+    logger.info(`Heartbeat started (PING every ${this.PING_INTERVAL_MS / 1e3}s)`);
+  }
+  /**
+   * Stop the heartbeat interval
+   */
+  stopHeartbeat() {
+    if (this.pingInterval) {
+      clearInterval(this.pingInterval);
+      this.pingInterval = null;
+      logger.debug("Heartbeat stopped");
+    }
+  }
+  /**
+   * Handle PONG response from server
+   */
+  handlePong() {
+    this.lastPong = Date.now();
+    logger.debug("Heartbeat PONG received");
+  }
   storeComponents(components) {
     this.components = components;
   }