@brizz/sdk 0.1.27 → 0.1.29

package/README.md

@@ -21,6 +21,7 @@ libraries including OpenAI, Anthropic, Vercel AI SDK, and more.
 - [Custom Events & Logging](#custom-events--logging)
 - [Environment Variables](#environment-variables)
 - [Disable Span Export](#disable-span-export)
+- [Dropping Spans](#dropping-spans)
 - [Advanced Configuration](#advanced-configuration)
 - [Testing & Development](#testing--development)
 - [Package.json Examples](#packagejson-examples)
@@ -290,6 +291,7 @@ const result = await startSession(
 - `session.setOutput(text, context?)` - (Optional) Manually track output text; optional context bag
   attaches per-turn metadata rendered in the dashboard's Context panel
 - `session.setTitle(text)` - Set a session title (typically used with `mode: 'title'`)
+- `session.addExternalLink(url, options?)` - (Optional) Attach an external link (e.g. a Datadog trace or dashboard) to the session; it appears on the session detail panel. Also available as the top-level `addExternalLink(url, options?)`.
 
 **Per-turn context example:**
 
@@ -329,6 +331,20 @@ await startSession('session-456', async (session) => {
 });
 ```
 
+**External link example:**
+
+```typescript
+import { addExternalLink, startSession } from '@brizz/sdk';
+
+startSession('session-123', (session) => {
+  // Top-level function — resolves the active session from context.
+  addExternalLink('https://app.datadoghq.com/trace/abc', { title: 'Datadog trace' });
+});
+
+// Outside a session — pass the id explicitly.
+addExternalLink('https://sentry.io/issues/456', { sessionId: 'session-123', linkType: 'sentry' });
+```
+
 ### Session Title Generation
 
 If you use an LLM call to generate session titles, wrap it so those spans don't appear as part of
@@ -495,7 +511,7 @@ Brizz.initialize({
 Emit custom events and structured logs:
 
 ```typescript
-import { emitEvent, logger } from '@brizz/sdk';
+import { emitEvent, emitEventWithSessionId, logger } from '@brizz/sdk';
 
 // Emit custom events
 emitEvent('user.signup', {
@@ -510,6 +526,11 @@ emitEvent('ai.request.completed', {
   latency: 1200,
 });
 
+// Emit with a known session ID, outside any session scope
+emitEventWithSessionId('session-123', 'user.feedback.submitted', {
+  rating: 5,
+});
+
 // Structured logging
 logger.info('Processing user request', { userId: '123', requestId: 'req-456' });
 logger.error('AI request failed', { error: err.message, model: 'gpt-4' });
@@ -546,6 +567,37 @@ Brizz.initialize({ apiKey: 'your-api-key', disableSpanExporter: true });
 
 Or via env var: `BRIZZ_DISABLE_SPAN_EXPORTER=true`.
 
+## Dropping Spans
+
+Filter spans before export with `beforeSendSpan`. Return `false` to drop a span, `true` to keep it. Useful for stripping noisy paths (health checks, internal tooling) or excluding telemetry for specific end-users.
+
+```typescript
+Brizz.initialize({
+  apiKey: 'your-api-key',
+  beforeSendSpan: (span) => {
+    // OpenInference (LangChain JS, LangGraph JS) packs per-call
+    // `config.metadata` into a JSON-stringified `metadata` attribute.
+    const raw = span.attributes['metadata'];
+    if (typeof raw !== 'string') return true;
+    try {
+      return JSON.parse(raw).customer_id !== 'cust_42';
+    } catch {
+      return true;
+    }
+  },
+});
+```
+
+Tag the call so the filter has something to match on:
+
+```typescript
+await llm.invoke([new HumanMessage('Hello')], {
+  metadata: { customer_id: 'cust_42' },
+});
+```
+
+Both sync and async filters are supported. Exceptions are caught and the span passes through.
+
 ## Advanced Configuration
 
 ```typescript