@brizz/sdk 0.1.2-rc.1 → 0.1.2

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`
 

package/dist/index.cjs

@@ -47,7 +47,6 @@ __export(src_exports, {
   logger: () => logger,
   maskAttributes: () => maskAttributes,
   maskValue: () => maskValue,
-  maybeRegisterESMLoader: () => maybeRegisterESMLoader,
   setLogLevel: () => setLogLevel
 });
 module.exports = __toCommonJS(src_exports);
@@ -1116,19 +1115,19 @@ var VercelAIInstrumentation = class _VercelAIInstrumentation extends import_inst
    * Manual instrumentation hook for bundlers/Next.js. Applies in-place wrapping
    * on the provided module namespace.
    */
-  manuallyInstrument(module3) {
+  manuallyInstrument(module2) {
     try {
-      const result = this._patchModuleExports(module3);
+      const result = this._patchModuleExports(module2);
       if (result !== null) {
         logger.debug("Applied manual Vercel AI instrumentation");
         this._vercelAiNamespace = result;
         return result;
       }
       logger.warn("Manual Vercel AI instrumentation received invalid module");
-      return module3;
+      return module2;
     } catch (error) {
       logger.error(`Failed manual Vercel AI instrumentation: ${String(error)}`);
-      return this._vercelAiNamespace || module3;
+      return this._vercelAiNamespace || module2;
     }
   }
   /**
@@ -2839,77 +2838,6 @@ function detectRuntime() {
   };
 }
 
-// src/node/loader.ts
-var import_node_module = __toESM(require("module"), 1);
-var import_import_in_the_middle = require("import-in-the-middle");
-var import_meta = {};
-var loaderDebug = (() => {
-  const isDebug = process.env["BRIZZ_ESM_DEBUG"] === "true" || process.env["BRIZZ_LOG_LEVEL"] === "debug";
-  return {
-    log: (msg, data) => {
-      if (!isDebug) {
-        return;
-      }
-      const timestamp = (/* @__PURE__ */ new Date()).toISOString();
-      const dataStr = data ? ` ${JSON.stringify(data)}` : "";
-      console.log(`[${timestamp}] [ESM-LOADER] ${msg}${dataStr}`);
-    },
-    error: (msg, error) => {
-      if (!isDebug) {
-        return;
-      }
-      const timestamp = (/* @__PURE__ */ new Date()).toISOString();
-      const errorStr = error instanceof Error ? ` ${error.message}` : error ? ` ${JSON.stringify(error)}` : "";
-      console.error(`[${timestamp}] [ESM-LOADER] ERROR: ${msg}${errorStr}`);
-    }
-  };
-})();
-var LOADER_REGISTERED_KEY = Symbol.for("__brizz_esm_loader_registered__");
-function checkLoaderAPISupport() {
-  const [major, minor] = process.versions.node.split(".").map(Number);
-  if (major === void 0 || minor === void 0) {
-    loaderDebug.log("Failed to detect Node version, assuming loader API is supported");
-    return true;
-  }
-  const supported = major >= 21 || major === 20 && minor >= 6 || major === 18 && minor >= 19;
-  loaderDebug.log("Loader API support check:", {
-    nodeVersion: `${major}.${minor}`,
-    supportsLoaderAPI: supported
-  });
-  return supported;
-}
-function maybeRegisterESMLoader() {
-  if (globalThis[LOADER_REGISTERED_KEY] === true) {
-    loaderDebug.log("ESM loader already registered, skipping");
-    return false;
-  }
-  globalThis[LOADER_REGISTERED_KEY] = true;
-  loaderDebug.log("Starting ESM loader registration...");
-  if (!checkLoaderAPISupport()) {
-    loaderDebug.log("Node.js version does not support loader API, skipping");
-    return false;
-  }
-  try {
-    loaderDebug.log("Creating MessageChannel for import-in-the-middle...");
-    const { addHookMessagePort } = (0, import_import_in_the_middle.createAddHookMessageChannel)();
-    loaderDebug.log("Registering import-in-the-middle/hook.mjs...");
-    import_node_module.default.register("import-in-the-middle/hook.mjs", import_meta.url, {
-      data: { addHookMessagePort },
-      transferList: [addHookMessagePort]
-    });
-    loaderDebug.log("ESM loader successfully registered!");
-    return true;
-  } catch (error) {
-    loaderDebug.error("Failed to register ESM loader:", error);
-    globalThis[LOADER_REGISTERED_KEY] = false;
-    return false;
-  }
-}
-if (globalThis[LOADER_REGISTERED_KEY] !== true) {
-  loaderDebug.log("Loader module imported, attempting to register...");
-  maybeRegisterESMLoader();
-}
-
 // src/init.ts
 var init_exports = {};
 // Annotate the CommonJS export names for ESM import in node:
@@ -2931,7 +2859,6 @@ var init_exports = {};
   logger,
   maskAttributes,
   maskValue,
-  maybeRegisterESMLoader,
   setLogLevel
 });
 //# sourceMappingURL=index.cjs.map