@brizz/sdk 0.1.2-rc.1 → 0.1.3-rc.0

package/README.md

@@ -1,10 +1,32 @@
 # Brizz SDK
 
 [![npm version](https://img.shields.io/npm/v/@brizz/sdk.svg)](https://www.npmjs.com/package/@brizz/sdk)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![License: Apache-2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 [![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
 
-OpenTelemetry-based observability SDK for AI applications. Automatically instruments popular AI libraries including OpenAI, Anthropic, Vercel AI SDK, and more.
+OpenTelemetry-based observability SDK for AI applications. Automatically instruments popular AI
+libraries including OpenAI, Anthropic, Vercel AI SDK, and more.
+
+## Table of Contents
+
+- [Features](#features)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+  - [CommonJS Projects](#commonjs-projects)
+  - [ESM Projects](#esm-projects)
+- [Module System Support](#module-system-support)
+- [Supported Libraries](#supported-libraries)
+- [PII Protection & Data Masking](#pii-protection--data-masking)
+- [Session Tracking](#session-tracking)
+- [Custom Events & Logging](#custom-events--logging)
+- [Environment Variables](#environment-variables)
+- [Advanced Configuration](#advanced-configuration)
+- [Testing & Development](#testing--development)
+- [Package.json Examples](#packagejson-examples)
+- [Examples](#examples)
+- [Troubleshooting](#troubleshooting)
+- [Contributing](#contributing)
+- [License](#license)
 
 ## Features
 
@@ -27,11 +49,7 @@ pnpm add @brizz/sdk
 
 ## Quick Start
 
-### Method 1: Preload (Recommended for Production)
-
-The preload method automatically initializes the SDK and instruments libraries at startup using Node.js preload hooks.
-
-**Environment Variables:**
+First, set up your environment variables:
 ```bash
 BRIZZ_API_KEY=your-api-key
 BRIZZ_BASE_URL=https://telemetry.brizz.dev  # Optional
@@ -39,103 +57,103 @@ BRIZZ_APP_NAME=my-app                       # Optional
 BRIZZ_LOG_LEVEL=info                        # Optional: debug, info, warn, error, none
 ```
 
-**ESM Usage:**
-```bash
-# Run with ESM preload
-node --import @brizz/sdk/preload your-app.mjs
-```
+### CommonJS Projects
 
-**CommonJS Usage:**
+**Option 1: Preload Only (Zero Config)**
 ```bash
-# Run with CJS preload
 node --require @brizz/sdk/preload your-app.js
 ```
 
-**Package.json Scripts:**
-```json
-{
-  "scripts": {
-    "start": "node --import @brizz/sdk/preload src/index.js",
-    "dev": "node --import @brizz/sdk/preload --watch src/index.js"
-  }
-}
-```
-
-Your application code remains clean:
-```typescript
+```javascript
 // your-app.js - No SDK setup needed!
-import { generateText } from 'ai';
-import { openai } from '@ai-sdk/openai';
+const { generateText } = require('ai');
+const { openai } = require('@ai-sdk/openai');
 
-// Just use your AI libraries - they're automatically instrumented
-const result = await generateText({
+// Libraries are automatically instrumented
+generateText({
   model: openai('gpt-3.5-turbo'),
   prompt: 'Hello, world!',
-});
+}).then(result => console.log(result.text));
 ```
 
-### Method 2: ESM Loader Hook
-
-For ESM projects, you can use the ESM loader for automatic instrumentation by using the `--import` flag:
-
+**Option 2: Preload + Initialize (Custom Config)**
 ```bash
-node --import @brizz/sdk/loader your-app.mjs
+node --require @brizz/sdk/preload your-app.js
 ```
 
-```typescript
-// your-app.mjs
-import { Brizz } from '@brizz/sdk';
+```javascript
+// your-app.js - Custom configuration
+const { Brizz } = require('@brizz/sdk');
 
-// Initialize SDK
 Brizz.initialize({
   apiKey: 'your-api-key',
   appName: 'my-app',
+  // custom config here
 });
 
-// Import AI libraries - they'll be automatically instrumented
-import { generateText } from 'ai';
-import { openai } from '@ai-sdk/openai';
+const { generateText } = require('ai');
+// ... rest of your code
+```
 
-const result = await generateText({
-  model: openai('gpt-3.5-turbo'),
-  prompt: 'Hello, world!',
+**Option 3: Manual Import + Initialize**
+```javascript
+// Must be first import
+const { Brizz } = require('@brizz/sdk');
+
+Brizz.initialize({
+  apiKey: 'your-api-key',
+  appName: 'my-app',
 });
+
+// Import AI libraries after initialization
+const { generateText } = require('ai');
+const { openai } = require('@ai-sdk/openai');
 ```
 
-### Method 3: Manual Initialization
+### ESM Projects
 
-For CommonJS or custom setups:
+> ⚠️ **ESM Requirement**: ESM projects **must** use the `--import @brizz/sdk/loader` flag for instrumentation to work. Manual import without the loader will not instrument AI libraries.
+
+**Loader + Initialize (Required for ESM)**
+```bash
+node --import @brizz/sdk/loader your-app.mjs
+```
 
 ```typescript
+// your-app.mjs
 import { Brizz } from '@brizz/sdk';
 
-// Initialize before importing AI libraries
+// Must initialize SDK manually in ESM
 Brizz.initialize({
   apiKey: 'your-api-key',
   appName: 'my-app',
-  baseUrl: 'https://telemetry.brizz.dev', // Optional
-  logLevel: 'info', // Optional: debug, info, warn, error, none
 });
 
 // Import AI libraries after initialization
 import { generateText } from 'ai';
 import { openai } from '@ai-sdk/openai';
+
+const result = await generateText({
+  model: openai('gpt-3.5-turbo'),
+  prompt: 'Hello, world!',
+});
 ```
 
-> **Important**: Initialize Brizz before importing any libraries you want to instrument. If using `dotenv`, use `import "dotenv/config"` before importing `@brizz/sdk`.
+> **Important**: Initialize Brizz before importing any libraries you want to instrument. If using
+> `dotenv`, use `import "dotenv/config"` before importing `@brizz/sdk`.
 
 ## Module System Support
 
-### ESM (ES Modules)
-- **Preload**: `node --import @brizz/sdk/preload app.mjs` ⭐
-- **Loader**: `node --import @brizz/sdk/loader app.mjs`
-- **Manual**: Import and initialize manually
-
 ### CommonJS
-- **Preload**: `node --require @brizz/sdk/preload app.js` ⭐
-- **Manual**: Require and initialize manually
+- **Preload**: `node --require @brizz/sdk/preload app.js` ⭐ (with optional `Brizz.initialize()`)
+- **Manual**: Require `@brizz/sdk` first, then `Brizz.initialize()`, then AI libraries
+
+### ESM (ES Modules)
+- **Loader**: `node --import @brizz/sdk/loader app.mjs` + `Brizz.initialize()` ⭐
+- **Manual**: Import `@brizz/sdk` first, then `Brizz.initialize()`, then AI libraries
 
-For Next.js and Webpack environments that don't support automatic instrumentation, use manual instrumentation:
+For Next.js and Webpack environments that don't support automatic instrumentation, use manual
+instrumentation:
 
 ```typescript
 // For problematic bundlers
@@ -193,15 +211,8 @@ Brizz.initialize({
 });
 ```
 
-**Built-in PII patterns** automatically detect and mask:
-- Email addresses
-- Phone numbers
-- Social Security Numbers
-- Credit card numbers
-- API keys (OpenAI, Anthropic, etc.)
-- Cryptocurrency addresses
-- IP addresses
-- And more...
+**Built-in PII patterns** automatically detect and mask emails, phone numbers, SSNs, credit cards,
+API keys, crypto addresses, IPs, and more.
 
 ## Session Tracking
 
@@ -236,13 +247,13 @@ import { emitEvent, logger } from '@brizz/sdk';
 emitEvent('user.signup', {
   userId: '123',
   plan: 'pro',
-  source: 'website'
+  source: 'website',
 });
 
 emitEvent('ai.request.completed', {
   model: 'gpt-4',
   tokens: 150,
-  latency: 1200
+  latency: 1200,
 });
 
 // Structured logging
@@ -279,7 +290,7 @@ Brizz.initialize({
   // Custom headers for authentication
   headers: {
     'X-API-Version': '2024-01',
-    'X-Environment': 'production'
+    'X-Environment': 'production',
   },
 
   // Disable batching for immediate export (testing)
@@ -293,7 +304,7 @@ Brizz.initialize({
   disableNodeSdk: false,
 
   // Log level for SDK diagnostics
-  logLevel: 'info' // debug, info, warn, error, none
+  logLevel: 'info', // debug, info, warn, error, none
 });
 ```
 
@@ -309,7 +320,7 @@ const spanExporter = new InMemorySpanExporter();
 Brizz.initialize({
   apiKey: 'test-key',
   customSpanExporter: spanExporter,
-  logLevel: 'debug'
+  logLevel: 'debug',
 });
 
 // Later in tests
@@ -320,34 +331,26 @@ expect(spans[0].name).toBe('openai.chat');
 
 ## Package.json Examples
 
-**ESM with Preload (Recommended):**
-```json
-{
-  "type": "module",
-  "scripts": {
-    "start": "node --import @brizz/sdk/preload src/index.js",
-    "dev": "node --import @brizz/sdk/preload --watch src/index.js",
-    "debug": "node --import @brizz/sdk/preload --inspect src/index.js"
-  }
-}
-```
+**CommonJS Projects:**
 
-**CommonJS with Preload:**
 ```json
 {
   "scripts": {
     "start": "node --require @brizz/sdk/preload src/index.js",
-    "dev": "node --require @brizz/sdk/preload --watch src/index.js"
+    "dev": "node --require @brizz/sdk/preload --watch src/index.js",
+    "debug": "node --require @brizz/sdk/preload --inspect src/index.js"
   }
 }
 ```
 
-**ESM with Loader:**
+**ESM Projects:**
+
 ```json
 {
   "type": "module",
   "scripts": {
-    "start": "node --import @brizz/sdk/loader src/index.js"
+    "start": "node --import @brizz/sdk/loader src/index.js",
+    "dev": "node --import @brizz/sdk/loader --watch src/index.js"
   }
 }
 ```
@@ -367,15 +370,19 @@ Check out the [examples](./examples/) directory for complete working examples:
 ### Common Issues
 
 **"Could not find declaration file"**
+
 - Make sure to build the SDK: `pnpm build`
 - Check that `dist/` contains `.d.ts` files
 
 **Instrumentation not working**
+
 - Ensure SDK is initialized before importing AI libraries
-- For ESM, use preload or loader methods
+- For ESM, use loader + `Brizz.initialize()`
+- For CommonJS, use preload (with optional `Brizz.initialize()`)
 - Check that `BRIZZ_API_KEY` is set
 
 **CJS/ESM compatibility issues**
+
 - Use dynamic imports in CommonJS: `const ai = await import('ai')`
 - For bundlers, use manual instrumentation with `instrumentModules`