@brizz/sdk 0.1.3 → 0.1.4

package/README.md

@@ -50,6 +50,7 @@ pnpm add @brizz/sdk
 ## Quick Start
 
 First, set up your environment variables:
+
 ```bash
 BRIZZ_API_KEY=your-api-key
 BRIZZ_BASE_URL=https://telemetry.brizz.dev  # Optional
@@ -60,6 +61,7 @@ BRIZZ_LOG_LEVEL=info                        # Optional: debug, info, warn, error
 ### CommonJS Projects
 
 **Option 1: Preload Only (Zero Config)**
+
 ```bash
 node --require @brizz/sdk/preload your-app.js
 ```
@@ -74,10 +76,11 @@ generateText({
   model: openai('gpt-3.5-turbo'),
   prompt: 'Hello, world!',
   experimental_telemetry: { isEnabled: true },
-}).then(result => console.log(result.text));
+}).then((result) => console.log(result.text));
 ```
 
 **Option 2: Preload + Initialize (Custom Config)**
+
 ```bash
 node --require @brizz/sdk/preload your-app.js
 ```
@@ -97,6 +100,7 @@ const { generateText } = require('ai');
 ```
 
 **Option 3: Manual Import + Initialize**
+
 ```javascript
 // Must be first import
 const { Brizz } = require('@brizz/sdk');
@@ -113,9 +117,11 @@ const { openai } = require('@ai-sdk/openai');
 
 ### ESM Projects
 
-> ⚠️ **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.
+> ⚠️ **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
 ```
@@ -147,10 +153,12 @@ const result = await generateText({
 ## Module System Support
 
 ### CommonJS
+
 - **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
 
@@ -208,6 +216,7 @@ const stream = streamText({
 ```
 
 This enables automatic tracing of:
+
 - Model calls and responses
 - Token usage and costs
 - Tool calls and executions
@@ -250,25 +259,81 @@ API keys, crypto addresses, IPs, and more.
 
 Group related operations under a session context:
 
+### Function Wrapper Pattern
+
 ```typescript
-import { WithSessionId, emitEvent } from '@brizz/sdk';
+import { withSessionId, emitEvent } from '@brizz/sdk';
 
 async function processUserWorkflow(userId: string) {
-  // All traces within this function will include session-123
+  // All traces within this function will include the session ID
   const result = await generateText({
     model: openai('gpt-4'),
     messages: [{ role: 'user', content: 'Hello' }],
     experimental_telemetry: { isEnabled: true },
   });
 
-  emitEvent('workflow.completed', { userId, result: result.text });
   return result;
 }
 
-// Wrap function with session context
-await WithSessionId('session-123', processUserWorkflow, null, 'user-456');
+// Create a wrapped function that always executes with session context
+const sessionedWorkflow = withSessionId('session-123', processUserWorkflow);
+
+// Call multiple times, each with the same session context
+await sessionedWorkflow('user-456');
+await sessionedWorkflow('user-789');
+```
+
+### Immediate Execution Pattern
+
+```typescript
+import { callWithSessionId } from '@brizz/sdk';
+
+// Execute function immediately with session context
+await callWithSessionId('session-123', processUserWorkflow, null, 'user-456');
 ```
 
+### Handling Method Context
+
+When wrapping methods that use `this`, you have several options:
+
+#### Option 1: Arrow Function (Recommended)
+
+```typescript
+class ChatService {
+  async processMessage(userId: string, message: string) {
+    // This method uses 'this' context
+    return `Processed by ${this.serviceName}: ${message}`;
+  }
+}
+
+const service = new ChatService();
+// Wrap with arrow function to preserve 'this' context
+const sessionedProcess = withSessionId('session-123', (userId: string, message: string) =>
+  service.processMessage(userId, message),
+);
+```
+
+#### Option 2: Using bind()
+
+```typescript
+// Pre-bind the method to preserve 'this' context
+const sessionedProcess = withSessionId('session-123', service.processMessage.bind(service));
+```
+
+#### Option 3: Explicit thisArg Parameter
+
+```typescript
+// Pass 'this' context explicitly as third parameter
+const sessionedProcess = withSessionId(
+  'session-123',
+  service.processMessage,
+  service, // explicit 'this' context
+);
+```
+
+**Note:** The arrow function approach (Option 1) is recommended as it's more explicit, avoids lint
+warnings, and is less prone to `this` binding issues.
+
 ## Custom Events & Logging
 
 Emit custom events and structured logs:

package/dist/index.cjs

@@ -34,7 +34,7 @@ __export(src_exports, {
   DEFAULT_PII_PATTERNS: () => DEFAULT_PII_PATTERNS,
   LogLevel: () => LogLevel,
   SeverityNumber: () => import_api_logs2.SeverityNumber,
-  WithSessionId: () => WithSessionId,
+  callWithSessionId: () => callWithSessionId,
   detectRuntime: () => detectRuntime,
   emitEvent: () => emitEvent,
   getLogLevel: () => getLogLevel,
@@ -46,7 +46,8 @@ __export(src_exports, {
   logger: () => logger,
   maskAttributes: () => maskAttributes,
   maskValue: () => maskValue,
-  setLogLevel: () => setLogLevel
+  setLogLevel: () => setLogLevel,
+  withSessionId: () => withSessionId
 });
 module.exports = __toCommonJS(src_exports);
 
@@ -1791,7 +1792,15 @@ function withProperties(properties, fn, thisArg, ...args) {
   const newContext = import_api5.context.active().setValue(PROPERTIES_CONTEXT_KEY, properties);
   return import_api5.context.with(newContext, fn, thisArg, ...args);
 }
-function WithSessionId(sessionId, fn, thisArg, ...args) {
+function withSessionId(sessionId, fn, thisArg) {
+  return function wrapped(...args) {
+    const base = import_api5.context.active();
+    const prev = base.getValue(PROPERTIES_CONTEXT_KEY);
+    const next = base.setValue(PROPERTIES_CONTEXT_KEY, prev ? { ...prev, [SESSION_ID]: sessionId } : { [SESSION_ID]: sessionId });
+    return import_api5.context.with(next, fn, thisArg ?? this, ...args);
+  };
+}
+function callWithSessionId(sessionId, fn, thisArg, ...args) {
   return withProperties({ [SESSION_ID]: sessionId }, fn, thisArg, ...args);
 }
 
@@ -2035,7 +2044,7 @@ var init_exports = {};
   DEFAULT_PII_PATTERNS,
   LogLevel,
   SeverityNumber,
-  WithSessionId,
+  callWithSessionId,
   detectRuntime,
   emitEvent,
   getLogLevel,
@@ -2047,6 +2056,7 @@ var init_exports = {};
   logger,
   maskAttributes,
   maskValue,
-  setLogLevel
+  setLogLevel,
+  withSessionId
 });
 //# sourceMappingURL=index.cjs.map