@superatomai/sdk-node 0.0.3 → 0.0.5

package/README.md

@@ -79,6 +79,7 @@ interface SuperatomSDKConfig {
   ANTHROPIC_API_KEY?: string;        // Optional: Anthropic API key for LLM
   GROQ_API_KEY?: string;             // Optional: Groq API key for LLM
   LLM_PROVIDERS?: LLMProvider[];     // Optional: Custom LLM providers
+  logLevel?: LogLevel;               // Optional: Log level (errors, warnings, info, verbose) (default: 'info')
 }
 ```
 
@@ -87,6 +88,7 @@ interface SuperatomSDKConfig {
 - `SA_WEBSOCKET_URL` - WebSocket URL (default: `wss://ws.superatom.ai/websocket`)
 - `ANTHROPIC_API_KEY` - Anthropic API key for Claude models
 - `GROQ_API_KEY` - Groq API key for open-source models
+- `SUPERATOM_LOG_LEVEL` - Log level for SDK logging (errors, warnings, info, verbose) (default: 'info')
 
 ## Core Features
 
@@ -379,44 +381,91 @@ threadManager.deleteThread(thread.getId());
 - `form` - Interactive forms
 - Custom types as needed
 
-### 8. Log Collection
+### 8. Logging System
 
-Capture and send logs to the UI:
+The SDK includes a comprehensive logging system with environment-based log levels for both terminal and UI log collection.
 
-```typescript
-import { UILogCollector } from '@superatomai/sdk-node';
+#### Log Levels
+
+The SDK supports hierarchical log levels:
 
-const collector = new UILogCollector();
+- **`errors`** - Only error logs are shown
+- **`warnings`** - Warning and error logs are shown
+- **`info`** - Info, warning, and error logs are shown (default)
+- **`verbose`** - All logs including debug messages are shown
 
-// Start collecting logs
-collector.start();
+#### Configuring Log Level
 
-// Logs are automatically captured
-console.log('This will be captured');
-console.error('Error messages too');
+You can set the log level in three ways:
 
-// Add custom logs
-collector.addLog({
-  level: 'info',
-  message: 'Processing data...',
-  type: 'explanation',
-  data: { progress: 50 },
+**1. Via environment variable (recommended for deployment):**
+
+```bash
+export SUPERATOM_LOG_LEVEL=verbose
+node your-app.js
+```
+
+**2. Via SDK configuration (overrides environment variable):**
+
+```typescript
+import { SuperatomSDK } from '@superatomai/sdk-node';
+
+const sdk = new SuperatomSDK({
+  apiKey: 'your-api-key',
+  projectId: 'your-project-id',
+  logLevel: 'verbose', // errors | warnings | info | verbose
 });
+```
 
-// Get captured logs
-const logs = collector.getLogs();
+**3. Programmatically at runtime:**
+
+```typescript
+import { logger } from '@superatomai/sdk-node';
+
+// Change log level at runtime
+logger.setLogLevel('verbose');
 
-// Send logs to UI (via SDK)
-const message = collector.createMessage('uiblock-123');
-sdk.send(message);
+// Get current log level
+const currentLevel = logger.getLogLevel(); // returns 'verbose'
+```
 
-// Stop collecting
-collector.stop();
+#### Using the Logger
+
+```typescript
+import { logger } from '@superatomai/sdk-node';
 
-// Clear logs
-collector.clear();
+// These will be filtered based on the configured log level
+logger.error('Critical error occurred');        // Shown at all levels
+logger.warn('Something might be wrong');        // Hidden when level is 'errors'
+logger.info('Processing completed');            // Hidden when level is 'errors' or 'warnings'
+logger.debug('Detailed debug information');     // Only shown when level is 'verbose'
 ```
 
+#### UI Log Collection
+
+The `UILogCollector` also respects the log level configuration. Logs are sent to the frontend and displayed in the terminal based on the configured level.
+
+```typescript
+import { UILogCollector } from '@superatomai/sdk-node';
+
+const collector = new UILogCollector(
+  clientId,
+  (msg) => sdk.send(msg),
+  'uiblock-123'
+);
+
+// These logs are filtered based on log level before being sent to UI
+collector.error('Error message');      // Always sent
+collector.warn('Warning message');     // Sent unless level is 'errors'
+collector.info('Info message');        // Sent unless level is 'errors' or 'warnings'
+collector.debug('Debug message');      // Only sent when level is 'verbose'
+
+// Get all collected logs
+const logs = collector.getLogs();
+```
+
+**Note:** The log level affects both terminal output and UI log collection, ensuring consistent logging behavior across your application.
+
 ### 9. Cleanup Service
 
 Automatic memory management for threads and UI blocks:

package/dist/index.d.mts

@@ -1,5 +1,55 @@
 import { z } from 'zod';
 
+/**
+ * Log levels in hierarchical order
+ * - errors: only error logs
+ * - warnings: warning + error logs
+ * - info: info + warning + error logs
+ * - verbose: all logs including debug
+ */
+type LogLevel = 'errors' | 'warnings' | 'info' | 'verbose';
+/**
+ * Logger class with environment-based log level support
+ */
+declare class Logger {
+    private currentLevel;
+    private currentLevelPriority;
+    constructor();
+    /**
+     * Check if a string is a valid log level
+     */
+    private isValidLogLevel;
+    /**
+     * Check if a message should be logged based on current log level
+     */
+    private shouldLog;
+    /**
+     * Get current log level
+     */
+    getLogLevel(): LogLevel;
+    /**
+     * Set log level programmatically
+     */
+    setLogLevel(level: LogLevel): void;
+    /**
+     * Log info message (shown for info and verbose levels)
+     */
+    info(...args: any[]): void;
+    /**
+     * Log error message (shown for all levels)
+     */
+    error(...args: any[]): void;
+    /**
+     * Log warning message (shown for warnings, info, and verbose levels)
+     */
+    warn(...args: any[]): void;
+    /**
+     * Log debug message (only shown for verbose level)
+     */
+    debug(...args: any[]): void;
+}
+declare const logger: Logger;
+
 declare const DSLRendererPropsSchema$1: z.ZodObject<{
     dsl: z.ZodObject<{
         id: z.ZodString;
@@ -326,6 +376,72 @@ declare const DSLRendererPropsSchema: z.ZodObject<{
 }>;
 type DSLRendererProps = z.infer<typeof DSLRendererPropsSchema>;
 
+declare const UserSchema: z.ZodObject<{
+    username: z.ZodString;
+    email: z.ZodOptional<z.ZodString>;
+    password: z.ZodString;
+    fullname: z.ZodOptional<z.ZodString>;
+    role: z.ZodOptional<z.ZodString>;
+    wsIds: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    username: string;
+    password: string;
+    email?: string | undefined;
+    fullname?: string | undefined;
+    role?: string | undefined;
+    wsIds?: string[] | undefined;
+}, {
+    username: string;
+    password: string;
+    email?: string | undefined;
+    fullname?: string | undefined;
+    role?: string | undefined;
+    wsIds?: string[] | undefined;
+}>;
+type User = z.infer<typeof UserSchema>;
+declare const UsersDataSchema: z.ZodObject<{
+    users: z.ZodArray<z.ZodObject<{
+        username: z.ZodString;
+        email: z.ZodOptional<z.ZodString>;
+        password: z.ZodString;
+        fullname: z.ZodOptional<z.ZodString>;
+        role: z.ZodOptional<z.ZodString>;
+        wsIds: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        username: string;
+        password: string;
+        email?: string | undefined;
+        fullname?: string | undefined;
+        role?: string | undefined;
+        wsIds?: string[] | undefined;
+    }, {
+        username: string;
+        password: string;
+        email?: string | undefined;
+        fullname?: string | undefined;
+        role?: string | undefined;
+        wsIds?: string[] | undefined;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    users: {
+        username: string;
+        password: string;
+        email?: string | undefined;
+        fullname?: string | undefined;
+        role?: string | undefined;
+        wsIds?: string[] | undefined;
+    }[];
+}, {
+    users: {
+        username: string;
+        password: string;
+        email?: string | undefined;
+        fullname?: string | undefined;
+        role?: string | undefined;
+        wsIds?: string[] | undefined;
+    }[];
+}>;
+type UsersData = z.infer<typeof UsersDataSchema>;
 declare const MessageSchema: z.ZodObject<{
     id: z.ZodOptional<z.ZodString>;
     type: z.ZodString;
@@ -429,6 +545,7 @@ type IncomingMessage = z.infer<typeof IncomingMessageSchema>;
 type CollectionOperation = 'getMany' | 'getOne' | 'query' | 'mutation' | 'updateOne' | 'deleteOne' | 'createOne';
 type CollectionHandler<TParams = any, TResult = any> = (params: TParams) => Promise<TResult> | TResult;
 type LLMProvider = 'anthropic' | 'groq';
+
 interface SuperatomSDKConfig {
     url?: string;
     apiKey: string;
@@ -440,16 +557,9 @@ interface SuperatomSDKConfig {
     ANTHROPIC_API_KEY?: string;
     GROQ_API_KEY?: string;
     LLM_PROVIDERS?: LLMProvider[];
+    logLevel?: LogLevel;
 }
 
-interface User {
-    username: string;
-    password: string;
-    wsIds: string[];
-}
-interface UsersData {
-    users: User[];
-}
 /**
  * UserManager class to handle CRUD operations on users with file persistence
  * and in-memory caching. Changes are synced to file periodically.
@@ -503,6 +613,18 @@ declare class UserManager {
      * @returns The user if found, undefined otherwise
      */
     getUser(username: string): User | undefined;
+    /**
+     * Read a user by email
+     * @param email - Email to retrieve
+     * @returns The user if found, undefined otherwise
+     */
+    getUserByEmail(email: string): User | undefined;
+    /**
+     * Find user by username or email
+     * @param identifier - Username or email to search for
+     * @returns The user if found, undefined otherwise
+     */
+    getUserByUsernameOrEmail(identifier: string): User | undefined;
     /**
      * Read all users
      * @returns Array of all users
@@ -747,19 +869,26 @@ interface CapturedLog {
  * UILogCollector captures logs during user prompt processing
  * and sends them to runtime via ui_logs message with uiBlockId as the message id
  * Logs are sent in real-time for streaming effect in the UI
+ * Respects the global log level configuration
  */
 declare class UILogCollector {
     private logs;
     private uiBlockId;
     private clientId;
     private sendMessage;
+    private currentLogLevel;
     constructor(clientId: string, sendMessage: (message: Message) => void, uiBlockId?: string);
     /**
      * Check if logging is enabled (uiBlockId is provided)
      */
     isEnabled(): boolean;
+    /**
+     * Check if a message should be logged based on current log level
+     */
+    private shouldLog;
     /**
      * Add a log entry with timestamp and immediately send to runtime
+     * Only logs that pass the log level filter are captured and sent
      */
     private addLog;
     /**
@@ -820,13 +949,14 @@ interface Action {
 
 /**
  * UIBlock represents a single user and assistant message block in a thread
- * Contains user question, component metadata, component data, and available actions
+ * Contains user question, component metadata, component data, text response, and available actions
  */
 declare class UIBlock {
     private id;
     private userQuestion;
     private generatedComponentMetadata;
     private componentData;
+    private textResponse;
     private actions;
     private createdAt;
     /**
@@ -836,8 +966,9 @@ declare class UIBlock {
      * @param generatedComponentMetadata - Optional metadata about the generated component
      * @param actions - Optional array of available actions
      * @param id - Optional custom ID, generates UUID if not provided
+     * @param textResponse - Optional text response from LLM
      */
-    constructor(userQuestion: string, componentData?: Record<string, any>, generatedComponentMetadata?: Record<string, any>, actions?: Action[], id?: string);
+    constructor(userQuestion: string, componentData?: Record<string, any>, generatedComponentMetadata?: Record<string, any>, actions?: Action[], id?: string, textResponse?: string | null);
     /**
      * Get the UIBlock ID
      */
@@ -882,6 +1013,14 @@ declare class UIBlock {
      * Set or update component data with size and row limits
      */
     setComponentData(data: Record<string, any>): void;
+    /**
+     * Get text response
+     */
+    getTextResponse(): string | null;
+    /**
+     * Set or update text response
+     */
+    setTextResponse(textResponse: string | null): void;
     /**
      * Get all actions (only if they are resolved, not if fetching)
      */
@@ -1241,4 +1380,4 @@ declare class SuperatomSDK {
     private storeComponents;
 }
 
-export { type Action, CONTEXT_CONFIG, type CapturedLog, CleanupService, type CollectionHandler, type CollectionOperation, type IncomingMessage, LLM, type Message, SDK_VERSION, STORAGE_CONFIG, SuperatomSDK, type SuperatomSDKConfig, Thread, ThreadManager, UIBlock, UILogCollector, type User, UserManager, type UsersData };
+export { type Action, CONTEXT_CONFIG, type CapturedLog, CleanupService, type CollectionHandler, type CollectionOperation, type IncomingMessage, LLM, type LogLevel, type Message, SDK_VERSION, STORAGE_CONFIG, SuperatomSDK, type SuperatomSDKConfig, Thread, ThreadManager, UIBlock, UILogCollector, type User, UserManager, type UsersData, logger };

package/dist/index.d.ts

@@ -1,5 +1,55 @@
 import { z } from 'zod';
 
+/**
+ * Log levels in hierarchical order
+ * - errors: only error logs
+ * - warnings: warning + error logs
+ * - info: info + warning + error logs
+ * - verbose: all logs including debug
+ */
+type LogLevel = 'errors' | 'warnings' | 'info' | 'verbose';
+/**
+ * Logger class with environment-based log level support
+ */
+declare class Logger {
+    private currentLevel;
+    private currentLevelPriority;
+    constructor();
+    /**
+     * Check if a string is a valid log level
+     */
+    private isValidLogLevel;
+    /**
+     * Check if a message should be logged based on current log level
+     */
+    private shouldLog;
+    /**
+     * Get current log level
+     */
+    getLogLevel(): LogLevel;
+    /**
+     * Set log level programmatically
+     */
+    setLogLevel(level: LogLevel): void;
+    /**
+     * Log info message (shown for info and verbose levels)
+     */
+    info(...args: any[]): void;
+    /**
+     * Log error message (shown for all levels)
+     */
+    error(...args: any[]): void;
+    /**
+     * Log warning message (shown for warnings, info, and verbose levels)
+     */
+    warn(...args: any[]): void;
+    /**
+     * Log debug message (only shown for verbose level)
+     */
+    debug(...args: any[]): void;
+}
+declare const logger: Logger;
+
 declare const DSLRendererPropsSchema$1: z.ZodObject<{
     dsl: z.ZodObject<{
         id: z.ZodString;
@@ -326,6 +376,72 @@ declare const DSLRendererPropsSchema: z.ZodObject<{
 }>;
 type DSLRendererProps = z.infer<typeof DSLRendererPropsSchema>;
 
+declare const UserSchema: z.ZodObject<{
+    username: z.ZodString;
+    email: z.ZodOptional<z.ZodString>;
+    password: z.ZodString;
+    fullname: z.ZodOptional<z.ZodString>;
+    role: z.ZodOptional<z.ZodString>;
+    wsIds: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    username: string;
+    password: string;
+    email?: string | undefined;
+    fullname?: string | undefined;
+    role?: string | undefined;
+    wsIds?: string[] | undefined;
+}, {
+    username: string;
+    password: string;
+    email?: string | undefined;
+    fullname?: string | undefined;
+    role?: string | undefined;
+    wsIds?: string[] | undefined;
+}>;
+type User = z.infer<typeof UserSchema>;
+declare const UsersDataSchema: z.ZodObject<{
+    users: z.ZodArray<z.ZodObject<{
+        username: z.ZodString;
+        email: z.ZodOptional<z.ZodString>;
+        password: z.ZodString;
+        fullname: z.ZodOptional<z.ZodString>;
+        role: z.ZodOptional<z.ZodString>;
+        wsIds: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        username: string;
+        password: string;
+        email?: string | undefined;
+        fullname?: string | undefined;
+        role?: string | undefined;
+        wsIds?: string[] | undefined;
+    }, {
+        username: string;
+        password: string;
+        email?: string | undefined;
+        fullname?: string | undefined;
+        role?: string | undefined;
+        wsIds?: string[] | undefined;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    users: {
+        username: string;
+        password: string;
+        email?: string | undefined;
+        fullname?: string | undefined;
+        role?: string | undefined;
+        wsIds?: string[] | undefined;
+    }[];
+}, {
+    users: {
+        username: string;
+        password: string;
+        email?: string | undefined;
+        fullname?: string | undefined;
+        role?: string | undefined;
+        wsIds?: string[] | undefined;
+    }[];
+}>;
+type UsersData = z.infer<typeof UsersDataSchema>;
 declare const MessageSchema: z.ZodObject<{
     id: z.ZodOptional<z.ZodString>;
     type: z.ZodString;
@@ -429,6 +545,7 @@ type IncomingMessage = z.infer<typeof IncomingMessageSchema>;
 type CollectionOperation = 'getMany' | 'getOne' | 'query' | 'mutation' | 'updateOne' | 'deleteOne' | 'createOne';
 type CollectionHandler<TParams = any, TResult = any> = (params: TParams) => Promise<TResult> | TResult;
 type LLMProvider = 'anthropic' | 'groq';
+
 interface SuperatomSDKConfig {
     url?: string;
     apiKey: string;
@@ -440,16 +557,9 @@ interface SuperatomSDKConfig {
     ANTHROPIC_API_KEY?: string;
     GROQ_API_KEY?: string;
     LLM_PROVIDERS?: LLMProvider[];
+    logLevel?: LogLevel;
 }
 
-interface User {
-    username: string;
-    password: string;
-    wsIds: string[];
-}
-interface UsersData {
-    users: User[];
-}
 /**
  * UserManager class to handle CRUD operations on users with file persistence
  * and in-memory caching. Changes are synced to file periodically.
@@ -503,6 +613,18 @@ declare class UserManager {
      * @returns The user if found, undefined otherwise
      */
     getUser(username: string): User | undefined;
+    /**
+     * Read a user by email
+     * @param email - Email to retrieve
+     * @returns The user if found, undefined otherwise
+     */
+    getUserByEmail(email: string): User | undefined;
+    /**
+     * Find user by username or email
+     * @param identifier - Username or email to search for
+     * @returns The user if found, undefined otherwise
+     */
+    getUserByUsernameOrEmail(identifier: string): User | undefined;
     /**
      * Read all users
      * @returns Array of all users
@@ -747,19 +869,26 @@ interface CapturedLog {
  * UILogCollector captures logs during user prompt processing
  * and sends them to runtime via ui_logs message with uiBlockId as the message id
  * Logs are sent in real-time for streaming effect in the UI
+ * Respects the global log level configuration
  */
 declare class UILogCollector {
     private logs;
     private uiBlockId;
     private clientId;
     private sendMessage;
+    private currentLogLevel;
     constructor(clientId: string, sendMessage: (message: Message) => void, uiBlockId?: string);
     /**
      * Check if logging is enabled (uiBlockId is provided)
      */
     isEnabled(): boolean;
+    /**
+     * Check if a message should be logged based on current log level
+     */
+    private shouldLog;
     /**
      * Add a log entry with timestamp and immediately send to runtime
+     * Only logs that pass the log level filter are captured and sent
      */
     private addLog;
     /**
@@ -820,13 +949,14 @@ interface Action {
 
 /**
  * UIBlock represents a single user and assistant message block in a thread
- * Contains user question, component metadata, component data, and available actions
+ * Contains user question, component metadata, component data, text response, and available actions
  */
 declare class UIBlock {
     private id;
     private userQuestion;
     private generatedComponentMetadata;
     private componentData;
+    private textResponse;
     private actions;
     private createdAt;
     /**
@@ -836,8 +966,9 @@ declare class UIBlock {
      * @param generatedComponentMetadata - Optional metadata about the generated component
      * @param actions - Optional array of available actions
      * @param id - Optional custom ID, generates UUID if not provided
+     * @param textResponse - Optional text response from LLM
      */
-    constructor(userQuestion: string, componentData?: Record<string, any>, generatedComponentMetadata?: Record<string, any>, actions?: Action[], id?: string);
+    constructor(userQuestion: string, componentData?: Record<string, any>, generatedComponentMetadata?: Record<string, any>, actions?: Action[], id?: string, textResponse?: string | null);
     /**
      * Get the UIBlock ID
      */
@@ -882,6 +1013,14 @@ declare class UIBlock {
      * Set or update component data with size and row limits
      */
     setComponentData(data: Record<string, any>): void;
+    /**
+     * Get text response
+     */
+    getTextResponse(): string | null;
+    /**
+     * Set or update text response
+     */
+    setTextResponse(textResponse: string | null): void;
     /**
      * Get all actions (only if they are resolved, not if fetching)
      */
@@ -1241,4 +1380,4 @@ declare class SuperatomSDK {
     private storeComponents;
 }
 
-export { type Action, CONTEXT_CONFIG, type CapturedLog, CleanupService, type CollectionHandler, type CollectionOperation, type IncomingMessage, LLM, type Message, SDK_VERSION, STORAGE_CONFIG, SuperatomSDK, type SuperatomSDKConfig, Thread, ThreadManager, UIBlock, UILogCollector, type User, UserManager, type UsersData };
+export { type Action, CONTEXT_CONFIG, type CapturedLog, CleanupService, type CollectionHandler, type CollectionOperation, type IncomingMessage, LLM, type LogLevel, type Message, SDK_VERSION, STORAGE_CONFIG, SuperatomSDK, type SuperatomSDKConfig, Thread, ThreadManager, UIBlock, UILogCollector, type User, UserManager, type UsersData, logger };