primeorbit 0.1.1

package/build/index.d.cts

@@ -0,0 +1,277 @@
+/**
+ * Wraps a synchronous function and logs its execution latency.
+ *
+ * @param fn - The synchronous function to be wrapped.
+ * @param agentId - Identifier for the agent.
+ * @param actionId - Identifier for the action. Defaults to the function name.
+ * @returns A wrapped function that logs latency and returns the same result.
+ */
+declare function wrapSyncToRecordLatency<TArgs extends unknown[], TResult>(fn: (...args: TArgs) => TResult, agentId: string, actionId?: string): (...args: TArgs) => TResult;
+/**
+ * Wraps an asynchronous function and logs its execution latency.
+ *
+ * @param fn - The asynchronous function to be wrapped.
+ * @param agentId - Identifier for the agent.
+ * @param actionId - Identifier for the action. Defaults to the function name.
+ * @returns A wrapped function that logs latency and returns the same Promise.
+ */
+declare function wrapAsyncToRecordLatency<TArgs extends unknown[], TResult>(fn: (...args: TArgs) => Promise<TResult>, agentId: string, actionId?: string): (...args: TArgs) => Promise<TResult>;
+/**
+ * Wraps a synchronous or asynchronous function and logs its execution latency.
+ *
+ * @template TArgs - The argument types of the function.
+ * @template TResult - The return type of the function.
+ * @param fn - The function to be wrapped.
+ * @param agentId - Identifier for the agent.
+ * @param actionId - Identifier for the action. Defaults to the function name.
+ * @returns A wrapped function that logs latency and returns the same result.
+ *
+ * @example
+ * // Wrap a sync function
+ * const wrappedSync = wrapToRecordLatency(myFunction, 'agent-1');
+ *
+ * // Wrap an async function
+ * const wrappedAsync = wrapToRecordLatency(myAsyncFunction, 'agent-1', 'custom-action');
+ */
+declare function wrapToRecordLatency<TArgs extends unknown[], TResult>(fn: (...args: TArgs) => TResult | Promise<TResult>, agentId: string, actionId?: string): (...args: TArgs) => TResult | Promise<TResult>;
+
+declare function setPrimeOrbitApiUrl(url: string): void;
+declare function getPrimeOrbitApiUrl(): string;
+
+/**
+ * Records a star rating for an agent after task completion.
+ *
+ * @param agentId - Unique identifier for the agent
+ * @param rating - Star rating given (e.g. 1–5)
+ * @param taskName - Name of completed task
+ * @param userId - Optional ID of the user giving the rating
+ */
+declare function record_star_rating(agentId: string, rating: number, taskName: string, userId?: string): Promise<void>;
+
+/**
+ * Sends thumbs-up/down feedback to the backend.
+ *
+ * @param agentId - ID of the agent being rated
+ * @param isThumbsUp - true if thumbs up, false if thumbs down
+ * @param taskName - summary of the task
+ * @param userId - ID of the user who provided the feedback; defaults to ''.
+ */
+declare function record_thumbs_feedback(agentId: string, isThumbsUp: boolean, taskName: string, userId?: string): Promise<void>;
+
+/**
+ * EventQueue - Handles batching, rate limiting, and retry logic for event recording.
+ *
+ * This queue buffers events and sends them in batches to reduce HTTP overhead
+ * and prevent socket exhaustion in high-throughput scenarios.
+ */
+interface EventQueueOptions {
+    /** Maximum number of events to batch in a single request (default: 100) */
+    batchSize?: number;
+    /** Maximum time in ms to wait before flushing a partial batch (default: 5000) */
+    flushIntervalMs?: number;
+    /** Maximum number of concurrent HTTP requests (default: 5) */
+    maxConcurrentRequests?: number;
+    /** Maximum number of retry attempts for failed requests (default: 3) */
+    maxRetries?: number;
+    /** Base delay in ms for exponential backoff (default: 1000) */
+    retryBaseDelayMs?: number;
+    /** Maximum queue size before dropping events (default: 100000) */
+    maxQueueSize?: number;
+    /** Callback for when events are dropped due to queue overflow */
+    onEventDropped?: (event: QueuedEvent, reason: string) => void;
+    /** Callback for when a batch fails after all retries */
+    onBatchFailed?: (events: QueuedEvent[], error: Error) => void;
+    /** Callback for when a batch succeeds */
+    onBatchSuccess?: (events: QueuedEvent[], response: unknown) => void;
+}
+interface QueuedEvent {
+    payload: Record<string, unknown>;
+    timestamp: number;
+    retryCount: number;
+}
+declare class EventQueue {
+    private queue;
+    private readonly batchSize;
+    private readonly flushIntervalMs;
+    private readonly maxConcurrentRequests;
+    private readonly maxRetries;
+    private readonly retryBaseDelayMs;
+    private readonly maxQueueSize;
+    private readonly onEventDropped;
+    private readonly onBatchFailed;
+    private readonly onBatchSuccess;
+    private flushTimer;
+    private activeBatches;
+    private isShuttingDown;
+    private isFlushing;
+    private readonly endpoint;
+    private readonly headers;
+    private readonly sendBatch;
+    constructor(endpoint: string, headers: Record<string, string>, options?: EventQueueOptions);
+    /**
+     * Add an event to the queue. Events are batched and sent automatically.
+     */
+    enqueue(payload: Record<string, unknown>): boolean;
+    /**
+     * Flush all pending events. Call this before your application exits.
+     */
+    flush(): Promise<void>;
+    /**
+     * Shutdown the queue gracefully. Flushes all pending events and stops the timer.
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Get current queue statistics.
+     */
+    getStats(): {
+        queuedEvents: number;
+        activeBatches: number;
+        isShuttingDown: boolean;
+    };
+    private startFlushTimer;
+    private stopFlushTimer;
+    private cleanupCompletedBatches;
+    private processBatch;
+    private createBatchSender;
+    private sleep;
+}
+
+interface PrimeOrbitClientOptions {
+    /** Your PrimeOrbit API key */
+    apiKey?: string;
+    /** Custom endpoint URL */
+    endpoint?: string;
+    /** Enable verbose logging for missing optional fields */
+    verbose?: boolean;
+    /**
+     * Enable event batching for high-throughput scenarios.
+     * When enabled, events are queued and sent in batches instead of immediately.
+     * Default: false (for backward compatibility)
+     */
+    enableBatching?: boolean;
+    /** Options for the event queue (only used when enableBatching is true) */
+    queueOptions?: EventQueueOptions;
+}
+declare class PrimeOrbitClient {
+    private apiKey;
+    private baseUrl;
+    private baseProperties;
+    private verbose;
+    private enableBatching;
+    private eventQueue;
+    /**
+     * @param {string} apiKey - Your PrimeOrbit API key
+     * @param {string} [endpoint] - endpoint URL
+     * @deprecated Use the options object constructor instead for new features
+     */
+    constructor(apiKey?: string, endpoint?: string);
+    /**
+     * @param {PrimeOrbitClientOptions} options - Configuration options
+     */
+    constructor(options: PrimeOrbitClientOptions);
+    private initializeEventQueue;
+    add_properties(props: Record<string, unknown>): void;
+    _headers(): Record<string, string>;
+    /**
+     * Enable or disable event batching at runtime.
+     * When enabled, events are queued and sent in batches.
+     * When disabled, events are sent immediately (original behavior).
+     *
+     * @param enable - Whether to enable batching
+     * @param queueOptions - Optional queue configuration (only used when enabling)
+     */
+    setBatching(enable: boolean, queueOptions?: EventQueueOptions): void;
+    /**
+     * Flush all queued events immediately.
+     * Call this before your application exits to ensure all events are sent.
+     * Only applicable when batching is enabled.
+     */
+    flush(): Promise<void>;
+    /**
+     * Shutdown the client gracefully.
+     * Flushes all pending events and releases resources.
+     * Call this when your application is shutting down.
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Get queue statistics.
+     * Only applicable when batching is enabled.
+     */
+    getQueueStats(): {
+        queuedEvents: number;
+        activeBatches: number;
+        isShuttingDown: boolean;
+    } | null;
+    /**
+     * Records any agent interaction event such as user_message, agent_response, or user_feedback.
+     *
+     * @param eventType - Type of event. Can be:
+     *   - 'user_message' – when the user sends a message
+     *   - 'agent_response' – when the agent replies
+     *   - 'user_feedback' – when the user gives feedback
+     *
+     * @param params - Object containing event details:
+     *   - conversationId: string – Unique conversation identifier
+     *   - agentId: string – Agent ID
+     *   - userId: string – User ID
+     *   - productId?: string – Optional product ID
+     *   - content: string – Text content of the event (user message, agent reply, or feedback)
+     *   - sessionId?: string – Optional session ID
+     *   - messageId?: string – Optional message ID (for tracking within conversation)
+     *   - inputMode?: string – Optional input mode (e.g., 'text', 'voice')
+     *   - device?: string – Optional device name or model (e.g., 'iPhone 13')
+     *   - country?: string – Optional country of the user (ISO country code, e.g., 'US')
+     *   - platform?: string – Optional platform or OS (e.g., 'iOS', 'Android', 'Web')
+     *   - language?: string – Optional language of the user (e.g., 'en-US')
+     *   - Any additional properties will be captured in additional_properties
+     *
+     * @returns Promise that resolves when the event is queued (batching) or sent (non-batching).
+     *          When batching is enabled, returns true if queued successfully, false if dropped.
+     */
+    record_raw_event(eventType: 'user_message' | 'agent_response' | 'user_feedback', params: Record<string, unknown>): Promise<boolean | undefined>;
+}
+
+/**
+ * Logger module for PrimeOrbit SDK
+ *
+ * Provides configurable logging with different levels and formatting.
+ * All logs are prefixed with [PrimeOrbit] for easy filtering.
+ */
+type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'silent';
+/**
+ * Sets the log level for the SDK.
+ * Messages below this level will not be logged.
+ *
+ * @param level - The minimum log level to display
+ */
+declare function setLogLevel(level: LogLevel): void;
+/**
+ * Gets the current log level.
+ *
+ * @returns The current log level
+ */
+declare function getLogLevel(): LogLevel;
+/**
+ * Logger instance with methods for each log level.
+ * Console usage is intentional here as this is the logging implementation.
+ */
+declare const logger: {
+    /**
+     * Log a debug message. Only shown when log level is 'debug'.
+     */
+    debug(message: string, ...args: unknown[]): void;
+    /**
+     * Log an informational message.
+     */
+    info(message: string, ...args: unknown[]): void;
+    /**
+     * Log a warning message.
+     */
+    warn(message: string, ...args: unknown[]): void;
+    /**
+     * Log an error message.
+     */
+    error(message: string, ...args: unknown[]): void;
+};
+
+export { EventQueue, type EventQueueOptions, type LogLevel, PrimeOrbitClient, type PrimeOrbitClientOptions, type QueuedEvent, getLogLevel, getPrimeOrbitApiUrl, logger, record_star_rating, record_thumbs_feedback, setLogLevel, setPrimeOrbitApiUrl, wrapAsyncToRecordLatency, wrapSyncToRecordLatency, wrapToRecordLatency };

package/build/index.d.ts

@@ -0,0 +1,277 @@
+/**
+ * Wraps a synchronous function and logs its execution latency.
+ *
+ * @param fn - The synchronous function to be wrapped.
+ * @param agentId - Identifier for the agent.
+ * @param actionId - Identifier for the action. Defaults to the function name.
+ * @returns A wrapped function that logs latency and returns the same result.
+ */
+declare function wrapSyncToRecordLatency<TArgs extends unknown[], TResult>(fn: (...args: TArgs) => TResult, agentId: string, actionId?: string): (...args: TArgs) => TResult;
+/**
+ * Wraps an asynchronous function and logs its execution latency.
+ *
+ * @param fn - The asynchronous function to be wrapped.
+ * @param agentId - Identifier for the agent.
+ * @param actionId - Identifier for the action. Defaults to the function name.
+ * @returns A wrapped function that logs latency and returns the same Promise.
+ */
+declare function wrapAsyncToRecordLatency<TArgs extends unknown[], TResult>(fn: (...args: TArgs) => Promise<TResult>, agentId: string, actionId?: string): (...args: TArgs) => Promise<TResult>;
+/**
+ * Wraps a synchronous or asynchronous function and logs its execution latency.
+ *
+ * @template TArgs - The argument types of the function.
+ * @template TResult - The return type of the function.
+ * @param fn - The function to be wrapped.
+ * @param agentId - Identifier for the agent.
+ * @param actionId - Identifier for the action. Defaults to the function name.
+ * @returns A wrapped function that logs latency and returns the same result.
+ *
+ * @example
+ * // Wrap a sync function
+ * const wrappedSync = wrapToRecordLatency(myFunction, 'agent-1');
+ *
+ * // Wrap an async function
+ * const wrappedAsync = wrapToRecordLatency(myAsyncFunction, 'agent-1', 'custom-action');
+ */
+declare function wrapToRecordLatency<TArgs extends unknown[], TResult>(fn: (...args: TArgs) => TResult | Promise<TResult>, agentId: string, actionId?: string): (...args: TArgs) => TResult | Promise<TResult>;
+
+declare function setPrimeOrbitApiUrl(url: string): void;
+declare function getPrimeOrbitApiUrl(): string;
+
+/**
+ * Records a star rating for an agent after task completion.
+ *
+ * @param agentId - Unique identifier for the agent
+ * @param rating - Star rating given (e.g. 1–5)
+ * @param taskName - Name of completed task
+ * @param userId - Optional ID of the user giving the rating
+ */
+declare function record_star_rating(agentId: string, rating: number, taskName: string, userId?: string): Promise<void>;
+
+/**
+ * Sends thumbs-up/down feedback to the backend.
+ *
+ * @param agentId - ID of the agent being rated
+ * @param isThumbsUp - true if thumbs up, false if thumbs down
+ * @param taskName - summary of the task
+ * @param userId - ID of the user who provided the feedback; defaults to ''.
+ */
+declare function record_thumbs_feedback(agentId: string, isThumbsUp: boolean, taskName: string, userId?: string): Promise<void>;
+
+/**
+ * EventQueue - Handles batching, rate limiting, and retry logic for event recording.
+ *
+ * This queue buffers events and sends them in batches to reduce HTTP overhead
+ * and prevent socket exhaustion in high-throughput scenarios.
+ */
+interface EventQueueOptions {
+    /** Maximum number of events to batch in a single request (default: 100) */
+    batchSize?: number;
+    /** Maximum time in ms to wait before flushing a partial batch (default: 5000) */
+    flushIntervalMs?: number;
+    /** Maximum number of concurrent HTTP requests (default: 5) */
+    maxConcurrentRequests?: number;
+    /** Maximum number of retry attempts for failed requests (default: 3) */
+    maxRetries?: number;
+    /** Base delay in ms for exponential backoff (default: 1000) */
+    retryBaseDelayMs?: number;
+    /** Maximum queue size before dropping events (default: 100000) */
+    maxQueueSize?: number;
+    /** Callback for when events are dropped due to queue overflow */
+    onEventDropped?: (event: QueuedEvent, reason: string) => void;
+    /** Callback for when a batch fails after all retries */
+    onBatchFailed?: (events: QueuedEvent[], error: Error) => void;
+    /** Callback for when a batch succeeds */
+    onBatchSuccess?: (events: QueuedEvent[], response: unknown) => void;
+}
+interface QueuedEvent {
+    payload: Record<string, unknown>;
+    timestamp: number;
+    retryCount: number;
+}
+declare class EventQueue {
+    private queue;
+    private readonly batchSize;
+    private readonly flushIntervalMs;
+    private readonly maxConcurrentRequests;
+    private readonly maxRetries;
+    private readonly retryBaseDelayMs;
+    private readonly maxQueueSize;
+    private readonly onEventDropped;
+    private readonly onBatchFailed;
+    private readonly onBatchSuccess;
+    private flushTimer;
+    private activeBatches;
+    private isShuttingDown;
+    private isFlushing;
+    private readonly endpoint;
+    private readonly headers;
+    private readonly sendBatch;
+    constructor(endpoint: string, headers: Record<string, string>, options?: EventQueueOptions);
+    /**
+     * Add an event to the queue. Events are batched and sent automatically.
+     */
+    enqueue(payload: Record<string, unknown>): boolean;
+    /**
+     * Flush all pending events. Call this before your application exits.
+     */
+    flush(): Promise<void>;
+    /**
+     * Shutdown the queue gracefully. Flushes all pending events and stops the timer.
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Get current queue statistics.
+     */
+    getStats(): {
+        queuedEvents: number;
+        activeBatches: number;
+        isShuttingDown: boolean;
+    };
+    private startFlushTimer;
+    private stopFlushTimer;
+    private cleanupCompletedBatches;
+    private processBatch;
+    private createBatchSender;
+    private sleep;
+}
+
+interface PrimeOrbitClientOptions {
+    /** Your PrimeOrbit API key */
+    apiKey?: string;
+    /** Custom endpoint URL */
+    endpoint?: string;
+    /** Enable verbose logging for missing optional fields */
+    verbose?: boolean;
+    /**
+     * Enable event batching for high-throughput scenarios.
+     * When enabled, events are queued and sent in batches instead of immediately.
+     * Default: false (for backward compatibility)
+     */
+    enableBatching?: boolean;
+    /** Options for the event queue (only used when enableBatching is true) */
+    queueOptions?: EventQueueOptions;
+}
+declare class PrimeOrbitClient {
+    private apiKey;
+    private baseUrl;
+    private baseProperties;
+    private verbose;
+    private enableBatching;
+    private eventQueue;
+    /**
+     * @param {string} apiKey - Your PrimeOrbit API key
+     * @param {string} [endpoint] - endpoint URL
+     * @deprecated Use the options object constructor instead for new features
+     */
+    constructor(apiKey?: string, endpoint?: string);
+    /**
+     * @param {PrimeOrbitClientOptions} options - Configuration options
+     */
+    constructor(options: PrimeOrbitClientOptions);
+    private initializeEventQueue;
+    add_properties(props: Record<string, unknown>): void;
+    _headers(): Record<string, string>;
+    /**
+     * Enable or disable event batching at runtime.
+     * When enabled, events are queued and sent in batches.
+     * When disabled, events are sent immediately (original behavior).
+     *
+     * @param enable - Whether to enable batching
+     * @param queueOptions - Optional queue configuration (only used when enabling)
+     */
+    setBatching(enable: boolean, queueOptions?: EventQueueOptions): void;
+    /**
+     * Flush all queued events immediately.
+     * Call this before your application exits to ensure all events are sent.
+     * Only applicable when batching is enabled.
+     */
+    flush(): Promise<void>;
+    /**
+     * Shutdown the client gracefully.
+     * Flushes all pending events and releases resources.
+     * Call this when your application is shutting down.
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Get queue statistics.
+     * Only applicable when batching is enabled.
+     */
+    getQueueStats(): {
+        queuedEvents: number;
+        activeBatches: number;
+        isShuttingDown: boolean;
+    } | null;
+    /**
+     * Records any agent interaction event such as user_message, agent_response, or user_feedback.
+     *
+     * @param eventType - Type of event. Can be:
+     *   - 'user_message' – when the user sends a message
+     *   - 'agent_response' – when the agent replies
+     *   - 'user_feedback' – when the user gives feedback
+     *
+     * @param params - Object containing event details:
+     *   - conversationId: string – Unique conversation identifier
+     *   - agentId: string – Agent ID
+     *   - userId: string – User ID
+     *   - productId?: string – Optional product ID
+     *   - content: string – Text content of the event (user message, agent reply, or feedback)
+     *   - sessionId?: string – Optional session ID
+     *   - messageId?: string – Optional message ID (for tracking within conversation)
+     *   - inputMode?: string – Optional input mode (e.g., 'text', 'voice')
+     *   - device?: string – Optional device name or model (e.g., 'iPhone 13')
+     *   - country?: string – Optional country of the user (ISO country code, e.g., 'US')
+     *   - platform?: string – Optional platform or OS (e.g., 'iOS', 'Android', 'Web')
+     *   - language?: string – Optional language of the user (e.g., 'en-US')
+     *   - Any additional properties will be captured in additional_properties
+     *
+     * @returns Promise that resolves when the event is queued (batching) or sent (non-batching).
+     *          When batching is enabled, returns true if queued successfully, false if dropped.
+     */
+    record_raw_event(eventType: 'user_message' | 'agent_response' | 'user_feedback', params: Record<string, unknown>): Promise<boolean | undefined>;
+}
+
+/**
+ * Logger module for PrimeOrbit SDK
+ *
+ * Provides configurable logging with different levels and formatting.
+ * All logs are prefixed with [PrimeOrbit] for easy filtering.
+ */
+type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'silent';
+/**
+ * Sets the log level for the SDK.
+ * Messages below this level will not be logged.
+ *
+ * @param level - The minimum log level to display
+ */
+declare function setLogLevel(level: LogLevel): void;
+/**
+ * Gets the current log level.
+ *
+ * @returns The current log level
+ */
+declare function getLogLevel(): LogLevel;
+/**
+ * Logger instance with methods for each log level.
+ * Console usage is intentional here as this is the logging implementation.
+ */
+declare const logger: {
+    /**
+     * Log a debug message. Only shown when log level is 'debug'.
+     */
+    debug(message: string, ...args: unknown[]): void;
+    /**
+     * Log an informational message.
+     */
+    info(message: string, ...args: unknown[]): void;
+    /**
+     * Log a warning message.
+     */
+    warn(message: string, ...args: unknown[]): void;
+    /**
+     * Log an error message.
+     */
+    error(message: string, ...args: unknown[]): void;
+};
+
+export { EventQueue, type EventQueueOptions, type LogLevel, PrimeOrbitClient, type PrimeOrbitClientOptions, type QueuedEvent, getLogLevel, getPrimeOrbitApiUrl, logger, record_star_rating, record_thumbs_feedback, setLogLevel, setPrimeOrbitApiUrl, wrapAsyncToRecordLatency, wrapSyncToRecordLatency, wrapToRecordLatency };