@csaimonitor/sdk 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-01-01
+
+### Added
+
+- Initial release of @csaimonitor/sdk
+- Synchronous `CSMonitor` client with decorator pattern support
+- Asynchronous `AsyncCSMonitor` client with full async/await support
+- Automatic event batching (default: 10 events per batch)
+- Background flushing (default: every 5 seconds)
+- Error handling with exponential backoff retry logic
+- Data redaction for sensitive fields
+- Context manager pattern for fine-grained control
+- Manual event logging API
+- Complete TypeScript type definitions
+- Comprehensive documentation and examples
+
+### Features
+
+- Decorator pattern: `@monitor.track()` for automatic function tracking
+- Context manager: `monitor.trackEvent()` for manual event control
+- Manual tracking: `monitor.logEvent()` for direct event logging
+- Auto-batching: Configurable batch size (1-100 events)
+- Background flushing: Configurable flush interval
+- Error handling: Never crashes user applications
+- TypeScript: Full type support with strict mode
+- Async support: Native async/await with AsyncCSMonitor
+

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Customer Support AI Monitor
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,315 @@
+# @csaimonitor/sdk
+
+[![npm version](https://badge.fury.io/js/%40csaimonitor%2Fsdk.svg)](https://badge.fury.io/js/%40csaimonitor%2Fsdk)
+[![Node.js Support](https://img.shields.io/node/v/@csaimonitor/sdk.svg)](https://nodejs.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Production-ready Node.js/TypeScript SDK for **Customer Support AI Monitor**. Track events, measure performance, analyze costs, and gain insights into your AI systems.
+
+## Features
+
+- **Zero Boilerplate**: One decorator and it works
+- **Automatic Tracking**: Input, output, timing, and errors captured automatically
+- **Batching**: 10x reduction in API calls with smart batching (default: 10 events per batch)
+- **Background Flushing**: Automatic flush every 5 seconds
+- **Async Support**: Full async/await compatibility with `AsyncCSMonitor`
+- **Reliable**: Never crashes your application - all errors are caught and handled
+- **Type Safe**: Complete TypeScript definitions for excellent IDE support
+- **Flexible**: Decorator, context manager, or manual tracking patterns
+
+## Quick Start (< 5 minutes)
+
+### Installation
+
+```bash
+npm install @csaimonitor/sdk
+```
+
+### Basic Usage
+
+```typescript
+import { CSMonitor } from '@csaimonitor/sdk';
+
+// Initialize monitor
+const monitor = new CSMonitor({
+  apiKey: 'your_api_key_here_minimum_32_characters_long',
+  agentId: 'my_agent',
+  apiUrl: 'http://localhost:3002/api/v1'
+});
+
+// Track any function with a decorator
+@monitor.track()
+function chatWithUser(message: string): string {
+  return `AI response to: ${message}`;
+}
+
+// Call your function normally
+const result = chatWithUser('Hello!');
+
+// Flush events before exit
+monitor.flush();
+monitor.close();
+```
+
+That's it! Events are now flowing to your dashboard.
+
+## Usage Patterns
+
+### 1. Decorator Pattern (Recommended)
+
+The simplest way to track functions:
+
+```typescript
+@monitor.track()
+function myAgentFunction(inputData: string): string {
+  // Your AI logic here
+  return process(inputData);
+}
+```
+
+With custom event type and metadata:
+
+```typescript
+@monitor.track({
+  eventType: 'query',
+  metadata: { model: 'gpt-4', version: '1.0' }
+})
+function askQuestion(question: string): string {
+  return generateAnswer(question);
+}
+```
+
+### 2. Context Manager Pattern
+
+For fine-grained control:
+
+```typescript
+const event = monitor.trackEvent('llm_call', { prompt: 'Hello' });
+
+try {
+  const result = callLLM('Hello');
+  
+  // Set output and metadata
+  event.setOutput({ response: result });
+  event.setCost(0.0042);  // Track cost in USD
+  event.setMetadata({ model: 'gpt-4', tokens: 150 });
+  event.finish();
+} catch (error) {
+  event.finish(error);
+  throw error;
+}
+```
+
+### 3. Manual Tracking
+
+For legacy code or maximum control:
+
+```typescript
+monitor.logEvent({
+  eventType: 'decision',
+  inputData: { query: 'user input' },
+  outputData: { answer: 'AI response' },
+  metadata: { model: 'gpt-4' },
+  costUsd: 0.01,
+  latencyMs: 250,
+  status: 'success'
+});
+```
+
+### 4. Async/Await Support
+
+For async functions, use `AsyncCSMonitor`:
+
+```typescript
+import { AsyncCSMonitor } from '@csaimonitor/sdk';
+
+const monitor = new AsyncCSMonitor({
+  apiKey: 'your_key',
+  agentId: 'async_agent',
+  apiUrl: 'http://localhost:3002/api/v1'
+});
+
+await monitor.start();
+
+@monitor.track()
+async function asyncFunction(data: string): Promise<string> {
+  await someAsyncOperation();
+  return `Processed: ${data}`;
+}
+
+const result = await asyncFunction('test');
+await monitor.flush();
+await monitor.stop();
+```
+
+## Configuration Options
+
+| Option | Type | Required | Default | Description |
+|--------|------|----------|---------|-------------|
+| `apiKey` | `string` | Yes | - | API key for authentication (min 32 chars) |
+| `agentId` | `string` | Yes | - | Identifier for the agent being monitored |
+| `apiUrl` | `string` | No | Production URL | Base URL for the API |
+| `batchSize` | `number` | No | `10` | Number of events to batch before sending (1-100) |
+| `flushInterval` | `number` | No | `5.0` | Seconds between automatic flushes |
+| `retryAttempts` | `number` | No | `3` | Maximum retry attempts for failed requests (0-10) |
+| `timeout` | `number` | No | `30` | Request timeout in seconds |
+| `debug` | `boolean` | No | `false` | Enable debug logging |
+| `enabled` | `boolean` | No | `true` | Enable/disable tracking |
+| `redactKeys` | `string[]` | No | `[]` | Array of keys to redact from event data |
+| `onError` | `function` | No | - | Callback function for error handling |
+
+### Example Configuration
+
+```typescript
+const monitor = new CSMonitor({
+  apiKey: 'your_key_here',
+  agentId: 'my_agent',
+  apiUrl: 'http://localhost:3002/api/v1',
+  batchSize: 20,
+  flushInterval: 10.0,
+  retryAttempts: 5,
+  timeout: 60,
+  debug: true,
+  redactKeys: ['password', 'api_key', 'token'],
+  onError: (error) => {
+    console.error('CSMonitor error:', error);
+    // Log to your error tracking service
+  }
+});
+```
+
+## Error Handling
+
+The SDK is designed to never crash your application. All errors are caught and handled gracefully:
+
+```typescript
+const monitor = new CSMonitor({
+  apiKey: 'your_key',
+  agentId: 'my_agent',
+  onError: (error) => {
+    // Handle errors (log to Sentry, etc.)
+    console.error('Monitoring error:', error);
+  }
+});
+
+// Even if the API is down, your app continues to work
+@monitor.track()
+function myFunction() {
+  return 'result';
+}
+```
+
+## Data Redaction
+
+Automatically redact sensitive data:
+
+```typescript
+const monitor = new CSMonitor({
+  apiKey: 'your_key',
+  agentId: 'my_agent',
+  redactKeys: ['password', 'api_key', 'token', 'secret']
+});
+
+@monitor.track()
+function login(username: string, password: string) {
+  // password will be redacted as [REDACTED] in events
+  return authenticate(username, password);
+}
+```
+
+## Performance
+
+- **Minimal Overhead**: < 1ms per tracked function call
+- **Non-Blocking**: All API calls happen in the background
+- **Efficient Batching**: 10x reduction in API calls
+- **Automatic Flushing**: Events are sent automatically every 5 seconds
+
+## API Reference
+
+### CSMonitor
+
+Main synchronous client for tracking events.
+
+#### Methods
+
+- `track(options?)`: Decorator for tracking functions
+- `trackEvent(eventType, inputData?)`: Create a context manager for tracking
+- `logEvent(options)`: Manually log an event
+- `flush()`: Flush all pending events immediately (blocking)
+- `close()`: Close the monitor and cleanup resources
+
+### AsyncCSMonitor
+
+Asynchronous client for tracking events with full async/await support.
+
+#### Methods
+
+- `start()`: Start the background flushing task
+- `stop()`: Stop the background task and flush remaining events
+- `track(options?)`: Decorator for tracking async functions
+- `trackEvent(eventType, inputData?)`: Create an async context manager
+- `logEvent(options)`: Manually log an event (async)
+- `flush()`: Flush all pending events immediately (async)
+
+## Examples
+
+See the `examples/` directory for complete examples:
+
+- `basic-usage.ts` - Simple decorator pattern
+- `async-usage.ts` - Async/await examples
+- `context-manager.ts` - Context manager pattern
+- `manual-tracking.ts` - Direct event logging
+- `error-handling.ts` - Error handling and redaction
+
+## TypeScript Support
+
+Full TypeScript support with complete type definitions:
+
+```typescript
+import { CSMonitor, Event, EventMetadata, CSMonitorConfig } from '@csaimonitor/sdk';
+
+const monitor: CSMonitor = new CSMonitor({
+  apiKey: 'your_key',
+  agentId: 'my_agent'
+});
+```
+
+## Troubleshooting
+
+### Events not appearing in dashboard
+
+1. Check that `apiUrl` is correct
+2. Verify `apiKey` is valid (min 32 characters)
+3. Ensure `agentId` matches your agent
+4. Call `monitor.flush()` before application exit
+5. Enable `debug: true` to see detailed logs
+
+### High memory usage
+
+- Reduce `batchSize` if you have many events
+- Reduce `flushInterval` to flush more frequently
+- Call `monitor.flush()` periodically in long-running applications
+
+### Network errors
+
+- Increase `timeout` for slow networks
+- Increase `retryAttempts` for unreliable connections
+- Check `onError` callback for detailed error information
+
+## Requirements
+
+- Node.js 16.0.0 or higher
+- TypeScript 5.0.0 or higher (for TypeScript projects)
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+
+## Support
+
+For issues, questions, or contributions, please visit our [GitHub repository](https://github.com/csaimonitor/sdk-nodejs).
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for version history.
+

package/dist/async-client.d.ts

@@ -0,0 +1,143 @@
+/**
+ * Asynchronous client for CSMonitor SDK.
+ *
+ * This module provides the AsyncCSMonitor class for async/await tracking.
+ */
+import { CSMonitorConfig, CSMonitorConfigOptions } from './config';
+import { Event } from './models';
+import { createTrackDecorator } from './decorators';
+import { setupLogger } from './utils';
+/**
+ * Async context manager for tracking events.
+ */
+export declare class AsyncTrackedEvent {
+    private readonly monitor;
+    readonly eventType: string;
+    private inputData?;
+    private outputData?;
+    private metadata;
+    private costUsd?;
+    private status;
+    private errorMessage?;
+    private startTime?;
+    private startTimestamp?;
+    constructor(monitor: AsyncCSMonitor, eventType: string, inputData?: Record<string, unknown>);
+    /**
+     * Set output data for the event.
+     */
+    setOutput(outputData: unknown): void;
+    /**
+     * Set metadata fields.
+     */
+    setMetadata(metadata: Record<string, unknown>): void;
+    /**
+     * Set cost in USD.
+     */
+    setCost(costUsd: number): void;
+    /**
+     * Set event status.
+     */
+    setStatus(status: string): void;
+    /**
+     * Set error message and status.
+     */
+    setError(errorMessage: string): void;
+    /**
+     * Enter async context manager.
+     */
+    start(): Promise<void>;
+    /**
+     * Exit async context manager and log event.
+     */
+    finish(error?: unknown): Promise<void>;
+}
+/**
+ * Asynchronous client for tracking agent events.
+ *
+ * This class provides async/await support for event tracking.
+ *
+ * @example
+ * ```typescript
+ * const monitor = new AsyncCSMonitor({
+ *   apiKey: 'your_key',
+ *   agentId: 'my_agent',
+ *   apiUrl: 'http://localhost:3002/api/v1'
+ * });
+ *
+ * @monitor.track()
+ * async function myAsyncFunction(x: number): Promise<number> {
+ *   await someAsyncOperation();
+ *   return x * 2;
+ * }
+ *
+ * const result = await myAsyncFunction(5);
+ * await monitor.flush();
+ * await monitor.stop();
+ * ```
+ */
+export declare class AsyncCSMonitor {
+    readonly config: CSMonitorConfig;
+    readonly logger: ReturnType<typeof setupLogger>;
+    private readonly eventQueue;
+    private flushTimer?;
+    private readonly onError?;
+    private started;
+    constructor(options: CSMonitorConfigOptions);
+    /**
+     * Start the background flushing task.
+     */
+    start(): Promise<void>;
+    /**
+     * Stop the background task and flush remaining events.
+     */
+    stop(): Promise<void>;
+    /**
+     * Decorator to automatically track async function execution.
+     * @param options - Tracking options
+     * @returns Decorator function
+     */
+    track(options?: Parameters<ReturnType<typeof createTrackDecorator>>[0]): <T extends (...args: unknown[]) => unknown>(target: T, _propertyKey?: string | symbol, descriptor?: PropertyDescriptor) => T | PropertyDescriptor;
+    /**
+     * Create an async context manager for tracking an event.
+     * @param eventType - Type of event
+     * @param inputData - Initial input data
+     * @returns AsyncTrackedEvent context manager
+     */
+    trackEvent(eventType: string, inputData?: Record<string, unknown>): AsyncTrackedEvent;
+    /**
+     * Manually log an event (async).
+     * @param options - Event data
+     */
+    logEvent(options: {
+        eventType: string;
+        inputData?: Record<string, unknown>;
+        outputData?: Record<string, unknown>;
+        metadata?: Record<string, unknown>;
+        costUsd?: number;
+        latencyMs?: number;
+        status?: string;
+        errorMessage?: string;
+        timestamp?: string;
+    }): Promise<void>;
+    /**
+     * Add event to async queue (internal method).
+     */
+    _addEventAsync(event: Event): Promise<void>;
+    /**
+     * Flush all pending events immediately (async).
+     */
+    flush(): Promise<void>;
+    /**
+     * Send a batch of events to the API with retry logic (async).
+     */
+    private sendBatch;
+    /**
+     * Sleep for a given number of seconds.
+     */
+    private sleep;
+    /**
+     * String representation.
+     */
+    toString(): string;
+}
+//# sourceMappingURL=async-client.d.ts.map

package/dist/async-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"async-client.d.ts","sourceRoot":"","sources":["../src/async-client.ts"],"names":[],"mappings":"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"}