weflayr 0.2.0 → 0.3.1

package/README.md

@@ -1,6 +1,6 @@
 # Weflayr Node.js SDK
 
-Observability for Node.js - instrument any client or method with one line.
+Observability for Node.js - instrument any LLM client or function with one line.
 
 ## Install
 
@@ -8,33 +8,23 @@ Observability for Node.js - instrument any client or method with one line.
 npm install weflayr
 ```
 
-## Environment variables
-
-```bash
-WEFLAYR_INTAKE_URL=https://api.weflayr.com
-WEFLAYR_CLIENT_ID=your-client-id-uuid
-WEFLAYR_CLIENT_SECRET=your-client-secret
-```
-
-## Usage
+## Quick start
 
 ```js
 const { weflayr_setup, weflayr_instrument } = require('weflayr');
 
 weflayr_setup({
-  event_mode: 'default',      // 'default' | 'light' (light skips before events)
-  content_policy: 'ignore',   // 'ignore' removes ignore_fields | 'allow' keeps only allow_fields
-  ignore_fields: ['messages[].content', 'choices[].message.content'],
-  allow_fields: [],
+  intake_url:    'https://api.weflayr.com',
+  client_id:     'your-client-id-uuid',
+  client_secret: 'your-client-secret',
   methods: [
-    { call: 'chat.completions.create' }
+    { call: 'chat.completions.create' },
   ],
-}, { enabled: true });
+});
 
 const OpenAI = require('openai');
 const client = weflayr_instrument(new OpenAI({ apiKey: process.env.OPENAI_API_KEY }));
 
-// Tags are stripped from args before the API call and attached to the event
 const response = await client.chat.completions.create({
   model: 'gpt-4o-mini',
   messages: [{ role: 'user', content: 'Hello' }],
@@ -42,6 +32,108 @@ const response = await client.chat.completions.create({
 });
 ```
 
+Credentials are typically read from environment variables via `dotenv`:
+
+```js
+weflayr_setup({
+  intake_url:    process.env.WEFLAYR_INTAKE_URL,
+  client_id:     process.env.WEFLAYR_CLIENT_ID,
+  client_secret: process.env.WEFLAYR_CLIENT_SECRET,
+  methods: [...],
+});
+```
+
+```bash
+# .env
+WEFLAYR_INTAKE_URL=https://api.weflayr.com
+WEFLAYR_CLIENT_ID=your-client-id-uuid
+WEFLAYR_CLIENT_SECRET=your-client-secret
+```
+
+---
+
+## Settings reference
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `intake_url` | `string` | ✓ | Base URL of the Weflayr intake API |
+| `client_id` | `string` | ✓ | UUID identifying your Flare credential pair |
+| `client_secret` | `string` | ✓ | Bearer token used to authenticate events |
+| `event_mode` | `'default'` \| `'light'` | | `light` skips `before` events. Default: `'default'` |
+| `enabled` | `boolean` | | Set to `false` to disable instrumentation entirely. Default: `true` |
+| `ignore_fields` | `function` | | Middleware to strip sensitive fields from event payloads. Mutually exclusive with `allow_fields`. |
+| `allow_fields` | `function` | | Middleware to keep only approved fields in event payloads. Mutually exclusive with `ignore_fields`. |
+| `methods` | `MethodConfig[]` | | Methods to instrument on the proxied object |
+
+---
+
+## Filtering event payloads
+
+`ignore_fields` and `allow_fields` are **middleware functions**, not field lists. Each receives a deep clone of the event payload (request args or response body) and returns the filtered version. The original args forwarded to the real provider call are never affected.
+
+Only one may be set. Setting both logs a warning and blocks all events.
+
+### ignore_fields strip specific fields
+
+```js
+weflayr_setup({
+  // ...
+  ignore_fields: (data) => {
+    (data.messages ?? []).forEach(m => delete m.content);
+    (data.choices  ?? []).forEach(c => { if (c.message) delete c.message.content; });
+    return data;
+  },
+  methods: [{ call: 'chat.completions.create' }],
+});
+```
+
+### allow_fields keep only specific fields
+
+```js
+weflayr_setup({
+  // ...
+  allow_fields: (data) => ({
+    model:  data.model,
+    usage:  data.usage,
+  }),
+  methods: [{ call: 'chat.completions.create' }],
+});
+```
+
+---
+
+## Metadata tags
+
+Pass `__weflayr_tags` on any instrumented call to attach arbitrary key-value metadata to the event. Tags are stripped before the real provider call is made.
+
+```js
+await client.chat.completions.create({
+  model: 'gpt-4o-mini',
+  messages: [...],
+  __weflayr_tags: { feature: 'summarise', customer_id: '42' },
+});
+```
+
+---
+
+## Middleware
+
+Middleware extracts structured fields that are merged into the event payload. `response` is `null` for `before` events.
+
+```js
+methods: [
+  {
+    call: 'audio.speech.create',
+    middleware: (args, response) => ({
+      char_count:   args?.input?.length ?? 0,
+      result_count: response?.data?.length ?? 0,
+    }),
+  },
+],
+```
+
+---
+
 ## Instrumenting a plain function
 
 ```js
@@ -51,42 +143,83 @@ async function fetchModels() {
 }
 
 weflayr_setup({
-  event_mode: 'default',
-  content_policy: 'ignore',
-  ignore_fields: ['data'],
+  // ...
   methods: [
     {
       call: 'fetchModels',
       middleware: (_args, response) => ({ count: response?.data?.length ?? 0 }),
     },
   ],
-}, { enabled: true });
+});
 
 const instrumented = weflayr_instrument(fetchModels);
 const models = await instrumented({ __weflayr_tags: { app: 'my-app' } });
 ```
 
-## Settings reference
+---
 
-| Field | Type | Description |
-|---|---|---|
-| `event_mode` | `'default'` \| `'light'` | `light` skips before events |
-| `content_policy` | `'ignore'` \| `'allow'` | Which filtering mode to apply |
-| `ignore_fields` | `string[]` | Fields removed from payloads (used when `content_policy: 'ignore'`) |
-| `allow_fields` | `string[]` | Fields kept in payloads; everything else removed (used when `content_policy: 'allow'`) |
-| `methods` | `{ call, middleware? }[]` | Whitelisted method paths to instrument |
+## Disabling instrumentation
 
-Field paths support dot notation (`foo.bar`), and array traversal (`messages[].content`).
+```js
+weflayr_setup({
+  // ...
+  enabled: false,
+});
+```
 
-## Middleware
+`weflayr_instrument` returns the original object untouched when `enabled` is `false`.
 
-Middleware runs on both **before** and **after** events. `response` is `null` for before events.
+---
 
-```js
-middleware: (args, response) => ({
-  char_count: args?.input?.length ?? 0,
-  result_count: response?.data?.length ?? 0,
-})
+## TypeScript
+
+The SDK ships with full type declarations. No additional `@types` package is needed.
+
+```ts
+import { weflayr_setup, weflayr_instrument, flayred } from 'weflayr';
+import OpenAI from 'openai';
+
+weflayr_setup({
+  intake_url:    process.env.WEFLAYR_INTAKE_URL!,
+  client_id:     process.env.WEFLAYR_CLIENT_ID!,
+  client_secret: process.env.WEFLAYR_CLIENT_SECRET!,
+  methods: [{ call: 'chat.completions.create' }],
+});
+
+const client = weflayr_instrument(new OpenAI({ apiKey: process.env.OPENAI_API_KEY }));
 ```
 
-The returned object is merged into the event payload.
+### Adding tags in TypeScript
+
+Because `__weflayr_tags` is not part of the provider SDK's types, use the `flayred` helper to attach tags without casting:
+
+```ts
+const response = await client.chat.completions.create(flayred({
+  model: 'gpt-4o-mini',
+  messages: [{ role: 'user', content: 'Hello' }],
+  __weflayr_tags: { feature: 'chat', customer_id: '42' },
+}));
+```
+
+`flayred<T>(options: T & { __weflayr_tags? }): T` TypeScript sees the return type as `T`, so it is fully compatible with the provider SDK's expected parameter type.
+
+### Typing middleware
+
+Cast inside the middleware body the SDK is provider-agnostic so it cannot infer the concrete response type:
+
+```ts
+import OpenAI from 'openai';
+
+methods: [
+  {
+    call: 'chat.completions.create',
+    middleware: (_args, response) => {
+      const r = response as OpenAI.ChatCompletion | null;
+      return {
+        prompt_tokens:     r?.usage?.prompt_tokens     ?? 0,
+        completion_tokens: r?.usage?.completion_tokens ?? 0,
+      };
+    },
+  },
+],
+```

package/index.d.ts

@@ -0,0 +1,97 @@
+/** Arbitrary key-value metadata attached to an LLM call. */
+export type Tags = Record<string, string | number | boolean>;
+
+/**
+ * Receives a deep clone of the request args or response, mutates or replaces
+ * fields, and returns the filtered object sent to the intake API.
+ */
+export type ContentPolicyFn = (data: Record<string, unknown>) => Record<string, unknown>;
+
+/**
+ * Extracts extra structured fields merged into the intake event.
+ * Called with `(args, null)` for the `before` event and `(args, result)` for `after`.
+ */
+export type MiddlewareFn = (
+  args: Record<string, unknown>,
+  response: Record<string, unknown> | null,
+) => Record<string, unknown>;
+
+/** Per-chunk accumulator returned by a `streamMiddleware` factory. */
+export interface StreamAccumulator {
+  /** Return `true` to emit a `stream_pending` event immediately. */
+  onChunk: (chunk: unknown) => boolean;
+  /** Called once the stream ends; returns extra fields for the `after` event. */
+  finalize: () => Record<string, unknown>;
+}
+
+/** Factory called once per stream invocation. */
+export type StreamMiddlewareFn = () => StreamAccumulator;
+
+/** Instrumentation configuration for a single method path. */
+export interface MethodConfig {
+  /**
+   * Dot-separated path to the method on the instrumented object
+   * (e.g. `'chat.completions.create'`), or the function name for bare functions.
+   */
+  call: string;
+  middleware?: MiddlewareFn;
+  streamMiddleware?: StreamMiddlewareFn;
+}
+
+/** Full configuration object passed to `weflayr_setup`. */
+export interface WeflayrSettings {
+  /** Base URL of the Weflayr intake API (e.g. `'https://api.weflayr.com'`). */
+  intake_url: string;
+  /** UUID identifying the Flare credential pair. */
+  client_id: string;
+  /** Bearer token used when calling the intake API. */
+  client_secret: string;
+  /** `'default'` emits before + after events; `'light'` emits only after. */
+  event_mode?: 'default' | 'light';
+  /** Set to `false` to disable instrumentation entirely. Defaults to `true`. */
+  enabled?: boolean;
+  /**
+   * Middleware to strip sensitive fields from event payloads before sending to the intake API.
+   * Mutually exclusive with `allow_fields` — setting both blocks all events.
+   */
+  ignore_fields?: ContentPolicyFn;
+  /**
+   * Middleware to keep only approved fields in event payloads before sending to the intake API.
+   * Mutually exclusive with `ignore_fields` — setting both blocks all events.
+   */
+  allow_fields?: ContentPolicyFn;
+  /** Methods to instrument on the proxied object. */
+  methods?: MethodConfig[];
+}
+
+/** Configures weflayr with your credentials and instrumentation settings. */
+export function weflayr_setup(settings: WeflayrSettings): void;
+
+/**
+ * Wraps an LLM client object or async function so matching method calls emit
+ * events to the intake API. Returns the original value unchanged when weflayr
+ * is disabled or the target has no matching method config.
+ */
+export function weflayr_instrument<T>(target: T): T;
+
+/** Sends a custom event to the intake API from user code. No-ops if `weflayr_setup` hasn't been called. */
+export function send_event(
+  eventType: string,
+  data: Record<string, unknown>,
+): Promise<void> | undefined;
+
+/**
+ * Attaches weflayr metadata tags to any SDK call options object.
+ *
+ * `__weflayr_tags` is stripped by the instrumented proxy before the real provider call
+ * is made, so it never reaches the underlying SDK. At runtime this is the identity
+ * function — the generic signature is its only purpose.
+ *
+ * @example
+ * await openai.chat.completions.create(flayred({
+ *   model: 'gpt-4o-mini',
+ *   messages: [...],
+ *   __weflayr_tags: { feature: 'haiku', customer_id: '42' },
+ * }));
+ */
+export function flayred<T>(options: T & { __weflayr_tags?: Record<string, string | number | boolean> }): T;

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "weflayr",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Weflayr Node.js SDK — instrument any LLM client via JS Proxy",
   "main": "src/index.js",
+  "types": "index.d.ts",
   "scripts": {
-    "test": "node --test tests/"
+    "test": "node --test tests/index.test.js"
   },
   "keywords": ["llm", "observability", "weflayr"],
   "author": "Weflayr <contact@weflayr.com>",
@@ -12,7 +13,5 @@
   "engines": {
     "node": ">=18.0.0"
   },
-  "dependencies": {
-    "dotenv": "^16.0.0"
-  }
+  "dependencies": {}
 }

package/src/index.js

@@ -1,29 +1,35 @@
 'use strict';
 
-require('dotenv').config();
-
-const { configure, weflayr_instrument } = require('./instrument');
+const { configure, weflayr_instrument, send_event } = require('./instrument');
 
 /**
- * 
+ *
  * @param {*} settings: settings for weflayr
- * @param {*} on/off: easily enable or disable weflayr 
- * @returns 
+ * @returns
  */
-function weflayr_setup(settings, { enabled = true } = {}) {
-  if (!enabled) return;
+function weflayr_setup(settings) {
+  if (settings.enabled === false) return;
 
-  const intakeUrl    = process.env.WEFLAYR_INTAKE_URL;
-  const clientId     = process.env.WEFLAYR_CLIENT_ID;
-  const clientSecret = process.env.WEFLAYR_CLIENT_SECRET;
+  const { intake_url, client_id, client_secret } = settings;
 
-  if (!intakeUrl || !clientId || !clientSecret) {
+  if (!intake_url || !client_id || !client_secret) {
     throw new Error(
-      'Weflayr: WEFLAYR_INTAKE_URL, WEFLAYR_CLIENT_ID and WEFLAYR_CLIENT_SECRET must be set'
+      'Weflayr: intake_url, client_id and client_secret must be set in settings'
     );
   }
 
-  configure(intakeUrl, clientId, clientSecret, settings);
+  configure(intake_url, client_id, client_secret, settings);
+}
+
+/**
+ * Attaches weflayr metadata tags to any SDK call options object.
+ *
+ * @template T
+ * @param {T & { __weflayr_tags?: Record<string, string | number | boolean> }} options
+ * @returns {T}
+ */
+function flayred(options) {
+  return options;
 }
 
-module.exports = { weflayr_setup, weflayr_instrument };
+module.exports = { weflayr_setup, weflayr_instrument, send_event, flayred };

package/src/instrument.js

@@ -7,14 +7,19 @@ const { randomUUID } = require('crypto');
 let _config = null;
 
 function configure(intakeUrl, clientId, clientSecret, settings) {
-  _config = { intakeUrl, clientId, clientSecret, settings };
+  if (settings.ignore_fields && settings.allow_fields) {
+    console.warn('[weflayr] both ignore_fields and allow_fields are set - no events will be sent to the intake API');
+    _config = { intakeUrl, clientId, clientSecret, settings, _blocked: true };
+    return;
+  }
+  _config = { intakeUrl, clientId, clientSecret, settings, _blocked: false };
 }
 
 function weflayr_instrument(target) {
   if (!_config) return target;
 
   if (typeof target === 'function') {
-    const methodConfig = _config.settings.methods.find(m => m.call === target.name);
+    const methodConfig = (_config.settings.methods || []).find(m => m.call === target.name);
     if (!methodConfig) return target;
     return _wrapFn(target, target.name, methodConfig);
   }
@@ -35,7 +40,7 @@ function _makeProxy(target, pathPrefix) {
       const fullPath = pathPrefix ? `${pathPrefix}.${prop}` : prop;
 
       if (typeof value === 'function') {
-        const methodConfig = _config.settings.methods.find(m => m.call === fullPath);
+        const methodConfig = (_config.settings.methods || []).find(m => m.call === fullPath);
         if (methodConfig) {
           return _wrapFn(value.bind(obj), fullPath, methodConfig);
         }
@@ -57,16 +62,19 @@ function _wrapFn(fn, methodName, methodConfig) {
     const startTime = Date.now();
     const { settings } = _config;
     const eventId = randomUUID();
+    // For multi-arg methods (e.g. convert(voiceId, request)), use the last arg as the
+    // request object so middleware and content policy see the options, not the id.
+    const requestArgs = cleanArgs[cleanArgs.length - 1];
 
     if (settings.event_mode !== 'light') {
       const beforeMiddlewareData = methodConfig.middleware
-        ? methodConfig.middleware(cleanArgs[0], null) || {}
+        ? methodConfig.middleware(requestArgs, null) || {}
         : {};
       _sendEvent('before', {
         event_id: eventId,
         method: methodName,
         tags,
-        args: _applyContentPolicy(cleanArgs[0], settings),
+        args: _applyContentPolicy(requestArgs, settings),
         ...beforeMiddlewareData,
       });
     }
@@ -76,18 +84,18 @@ function _wrapFn(fn, methodName, methodConfig) {
 
       if (_isAsyncIterable(result)) {
         _sendEvent('stream_start', { event_id: eventId, method: methodName, tags });
-        return _wrapStream(result, methodName, tags, cleanArgs[0], settings, startTime, methodConfig, eventId);
+        return _wrapStream(result, methodName, tags, requestArgs, settings, startTime, methodConfig, eventId);
       }
 
       const middlewareData = methodConfig.middleware
-        ? methodConfig.middleware(cleanArgs[0], result) || {}
+        ? methodConfig.middleware(requestArgs, result) || {}
         : {};
 
       _sendEvent('after', {
         event_id: eventId,
         method: methodName,
         tags,
-        args: _applyContentPolicy(cleanArgs[0], settings),
+        args: _applyContentPolicy(requestArgs, settings),
         response: _applyContentPolicy(_toPlain(result), settings),
         elapsed_ms: Date.now() - startTime,
         ...middlewareData,
@@ -95,13 +103,13 @@ function _wrapFn(fn, methodName, methodConfig) {
 
       return result;
     } catch (err) {
-      _sendEvent('after', {
+      await _sendEvent('after', {
         event_id: eventId,
         method: methodName,
         tags,
-        args: _applyContentPolicy(cleanArgs[0], settings),
-        error: err.message,
-        status_code: err.status,
+        args: _applyContentPolicy(requestArgs, settings),
+        error: err.message ?? 'unknown',
+        status_code: err.status ?? err.statusCode ?? 'unknown',
         elapsed_ms: Date.now() - startTime,
       });
       throw err;
@@ -111,16 +119,27 @@ function _wrapFn(fn, methodName, methodConfig) {
 
 async function* _wrapStream(stream, methodName, tags, requestArgs, settings, startTime, methodConfig, eventId) {
   let lastChunk = null;
+  const accumulator = methodConfig.streamMiddleware ? methodConfig.streamMiddleware() : null;
 
   try {
     for await (const chunk of stream) {
       lastChunk = chunk;
+      if (accumulator && accumulator.onChunk(chunk)) {
+        _sendEvent('stream_pending', {
+          event_id: eventId,
+          method: methodName,
+          tags,
+          elapsed_ms: Date.now() - startTime,
+          ...accumulator.finalize(),
+        });
+      }
       yield chunk;
     }
 
-    const middlewareData = methodConfig.middleware && lastChunk
-      ? methodConfig.middleware(requestArgs, lastChunk) || {}
-      : {};
+    const middlewareData = accumulator
+      ? accumulator.finalize()
+      : (methodConfig.middleware && lastChunk ? methodConfig.middleware(requestArgs, lastChunk) || {}
+      : {});
 
     _sendEvent('after', {
       event_id: eventId,
@@ -132,12 +151,13 @@ async function* _wrapStream(stream, methodName, tags, requestArgs, settings, sta
       ...middlewareData,
     });
   } catch (err) {
-    _sendEvent('after', {
+    await _sendEvent('after', {
       event_id: eventId,
       method: methodName,
       tags,
       args: _applyContentPolicy(requestArgs, settings),
-      error: err.message,
+      error: err.message ?? 'unknown',
+      status_code: err.status ?? err.statusCode ?? 'unknown',
       elapsed_ms: Date.now() - startTime,
     });
     throw err;
@@ -163,86 +183,54 @@ function _isAsyncIterable(value) {
 
 function _toPlain(value) {
   if (!value) return value;
+  if (Buffer.isBuffer(value) || value instanceof Uint8Array || value instanceof ArrayBuffer) return null;
   if (typeof value.toJSON === 'function') return value.toJSON();
   return value;
 }
 
 function _applyContentPolicy(data, settings) {
   if (!data) return data;
-
+  const fn = settings.ignore_fields || settings.allow_fields;
+  if (!fn) return data;
   let clone;
   try {
     clone = JSON.parse(JSON.stringify(data));
   } catch {
     return data;
   }
-
-  if (settings.content_policy === 'allow') {
-    return _pickFields(clone, settings.allow_fields || []);
-  }
-
-  for (const field of (settings.ignore_fields || [])) {
-    _deleteField(clone, field);
+  try {
+    return fn(clone) ?? clone;
+  } catch (err) {
+    console.warn('[weflayr] content policy function error:', err.message);
+    return clone;
   }
-
-  return clone;
 }
 
-function _pickFields(obj, allowFields) {
-  if (!obj || typeof obj !== 'object' || allowFields.length === 0) return obj;
+const _debug = process.env.WEFLAYR_DEBUG === 'true';
 
-  const result = {};
-  for (const field of allowFields) {
-    const arrayMatch = field.match(/^(\w+)\[\]\.(.+)$/);
-    if (arrayMatch) {
-      const [, arrayKey, rest] = arrayMatch;
-      if (Array.isArray(obj[arrayKey])) {
-        result[arrayKey] = obj[arrayKey].map(item => _pickFields(item, [rest]));
-      }
-      continue;
-    }
-
-    const dotIdx = field.indexOf('.');
-    if (dotIdx === -1) {
-      if (field in obj) result[field] = obj[field];
-    } else {
-      const key = field.slice(0, dotIdx);
-      const rest = field.slice(dotIdx + 1);
-      if (key in obj) result[key] = _pickFields(obj[key], [rest]);
-    }
+function _sendEvent(eventType, data) {
+  if (_config._blocked) {
+    console.warn(`[weflayr] is blocked and can't send event, ensure your configuration is valid`);
+    return;
   }
-  return result;
-}
-
-function _deleteField(obj, path) {
-  if (!obj || typeof obj !== 'object') return;
+  const { intakeUrl, clientId, clientSecret } = _config;
+  const endpoint = `${intakeUrl.replace(/\/$/, '')}/${clientId}/`;
 
-  const arrayMatch = path.match(/^(\w+)\[\]\.(.+)$/);
-  if (arrayMatch) {
-    const [, arrayKey, rest] = arrayMatch;
-    if (Array.isArray(obj[arrayKey])) {
-      obj[arrayKey].forEach(item => _deleteField(item, rest));
-    }
+  let body;
+  try {
+    body = JSON.stringify({
+      event_type: eventType,
+      timestamp: new Date().toISOString(),
+      ...data,
+    });
+  } catch (err) {
+    console.warn(`[weflayr] could not serialize event "${eventType}":`, err.message);
     return;
   }
 
-  const dotIdx = path.indexOf('.');
-  if (dotIdx === -1) {
-    delete obj[path];
-  } else {
-    _deleteField(obj[path.slice(0, dotIdx)], path.slice(dotIdx + 1));
+  if (_debug) {
+    console.debug(`[weflayr] → ${eventType}`, JSON.parse(body));
   }
-}
-
-function _sendEvent(eventType, data) {
-  const { intakeUrl, clientId, clientSecret } = _config;
-  const endpoint = `${intakeUrl.replace(/\/$/, '')}/${clientId}/`;
-
-  const body = JSON.stringify({
-    event_type: eventType,
-    timestamp: new Date().toISOString(),
-    ...data,
-  });
 
   let parsed;
   try {
@@ -252,30 +240,42 @@ function _sendEvent(eventType, data) {
   }
 
   const lib = parsed.protocol === 'https:' ? https : http;
-  const req = lib.request({
-    hostname: parsed.hostname,
-    port: parsed.port || (parsed.protocol === 'https:' ? 443 : 80),
-    path: parsed.pathname,
-    method: 'POST',
-    headers: {
-      'Content-Type': 'application/json',
-      'Content-Length': Buffer.byteLength(body),
-      'Authorization': `Bearer ${clientSecret}`,
-    },
-  }, res => {
-    res.resume();
-    if (res.statusCode >= 400) {
-      console.warn(`[weflayr] intake returned ${res.statusCode} for event "${eventType}"`);
-    }
-  });
+  return new Promise((resolve) => {
+    const req = lib.request({
+      hostname: parsed.hostname,
+      port: parsed.port || (parsed.protocol === 'https:' ? 443 : 80),
+      path: parsed.pathname,
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Content-Length': Buffer.byteLength(body),
+        'Authorization': `Bearer ${clientSecret}`,
+      },
+    }, res => {
+      res.resume();
+      if (_debug) {
+        console.debug(`[weflayr] ← ${eventType} status ${res.statusCode}`);
+      }
+      if (res.statusCode >= 400) {
+        console.warn(`[weflayr] intake returned ${res.statusCode} for event "${eventType}"`);
+      }
+      resolve();
+    });
 
-  req.on('error', (err) => {
-    console.warn(`[weflayr] send error for event "${eventType}":`, err.message);
+    req.on('error', (err) => {
+      console.warn(`[weflayr] send error for event "${eventType}":`, err.message);
+      resolve();
+    });
+
+    req.write(body);
+    req.end();
   });
+}
 
-  req.write(body);
-  
-  req.end();
+// Send an arbitrary event to the intake. Requires configure() to have been called first.
+function send_event(eventType, data) {
+  if (!_config) return;
+  return _sendEvent(eventType, data);
 }
 
-module.exports = { configure, weflayr_instrument };
+module.exports = { configure, weflayr_instrument, send_event };

package/src/providers/anthropic-ai-sdk.js

@@ -0,0 +1,63 @@
+'use strict';
+
+// Non-streaming: extract usage from the completed message response.
+function middleware(request, response) {
+  if (!response) return { model: request?.model ?? null };
+  return {
+    model: response.model ?? request?.model ?? null,
+    input_tokens: response.usage?.input_tokens ?? null,
+    output_tokens: response.usage?.output_tokens ?? null,
+    cache_creation_input_tokens: response.usage?.cache_creation_input_tokens ?? null,
+    cache_read_input_tokens: response.usage?.cache_read_input_tokens ?? null,
+  };
+}
+
+// Streaming: Anthropic splits usage across two events.
+//   message_start  → usage.input_tokens  (prompt cost)
+//   message_delta  → usage.output_tokens (completion cost, cumulative final value)
+//   message_stop   → no usage data
+// onChunk returns true only when usage state changes, so _wrapStream fires
+// stream_pending exactly twice: once after message_start, once after message_delta.
+function createStreamAccumulator() {
+  let input_tokens = null;
+  let output_tokens = null;
+  let cache_creation_input_tokens = null;
+  let cache_read_input_tokens = null;
+  let model = null;
+
+  return {
+    onChunk(chunk) {
+      if (chunk.type === 'message_start') {
+        const usage = chunk.message?.usage;
+        model = chunk.message?.model ?? null;
+        input_tokens = usage?.input_tokens ?? null;
+        cache_creation_input_tokens = usage?.cache_creation_input_tokens ?? null;
+        cache_read_input_tokens = usage?.cache_read_input_tokens ?? null;
+        return true;
+      }
+      if (chunk.type === 'message_delta') {
+        output_tokens = chunk.usage?.output_tokens ?? null;
+        return true;
+      }
+      return false;
+    },
+    finalize() {
+      return {
+        model,
+        input_tokens,
+        output_tokens,
+        cache_creation_input_tokens,
+        cache_read_input_tokens,
+      };
+    },
+  };
+}
+
+// Ready-to-use method config for client.messages.create.
+const messagesCreate = {
+  call: 'messages.create',
+  middleware: middleware,
+  streamMiddleware: createStreamAccumulator,
+};
+
+module.exports = { messagesCreate, middleware, createStreamAccumulator };

package/tests/index.test.js

@@ -0,0 +1,188 @@
+'use strict';
+
+const { test } = require('node:test');
+const assert = require('assert/strict');
+
+const TEST_CREDS = {
+  intake_url: 'http://localhost:19999', // nothing listening — fire-and-forget is fine
+  client_id: 'test-client-id',
+  client_secret: 'test-secret',
+};
+
+// Reset module cache between tests so _config doesn't leak
+function freshSDK() {
+  delete require.cache[require.resolve('../src/instrument')];
+  delete require.cache[require.resolve('../src/index')];
+  return require('../src/index');
+}
+
+// Minimal fake client: one async method at a nested path
+function fakeClient() {
+  return {
+    chat: {
+      completions: {
+        create: async (args) => ({ id: 'res-1', model: args.model, choices: [] }),
+      },
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Content policy — function-based middleware
+// ---------------------------------------------------------------------------
+
+test('ignore_fields function filters event data', async () => {
+  const { weflayr_setup, weflayr_instrument } = freshSDK();
+
+  weflayr_setup({
+    ...TEST_CREDS,
+    event_mode: 'default',
+    ignore_fields: (data) => { delete data.messages; return data; },
+    methods: [{ call: 'chat.completions.create' }],
+  });
+
+  const client = weflayr_instrument(fakeClient());
+  const result = await client.chat.completions.create({ model: 'gpt-4o-mini', messages: [] });
+
+  assert.equal(result.id, 'res-1');
+});
+
+test('allow_fields function filters event data', async () => {
+  const { weflayr_setup, weflayr_instrument } = freshSDK();
+
+  weflayr_setup({
+    ...TEST_CREDS,
+    event_mode: 'default',
+    allow_fields: (data) => ({ model: data.model }),
+    methods: [{ call: 'chat.completions.create' }],
+  });
+
+  const client = weflayr_instrument(fakeClient());
+  const result = await client.chat.completions.create({ model: 'gpt-4o-mini', messages: [] });
+
+  assert.equal(result.id, 'res-1');
+});
+
+test('both ignore_fields and allow_fields set — no events sent, function still works', async () => {
+  const { weflayr_setup, weflayr_instrument } = freshSDK();
+
+  weflayr_setup({
+    ...TEST_CREDS,
+    event_mode: 'default',
+    ignore_fields: (data) => data,
+    allow_fields: (data) => data,
+    methods: [{ call: 'chat.completions.create' }],
+  });
+
+  const client = weflayr_instrument(fakeClient());
+  const result = await client.chat.completions.create({ model: 'gpt-4o-mini', messages: [] });
+
+  assert.equal(result.id, 'res-1');
+});
+
+test('no content policy — pass-through, function still works', async () => {
+  const { weflayr_setup, weflayr_instrument } = freshSDK();
+
+  weflayr_setup({
+    ...TEST_CREDS,
+    event_mode: 'default',
+    methods: [{ call: 'chat.completions.create' }],
+  });
+
+  const client = weflayr_instrument(fakeClient());
+  const result = await client.chat.completions.create({ model: 'gpt-4o-mini', messages: [] });
+
+  assert.equal(result.id, 'res-1');
+});
+
+test('ignore_fields does not mutate actual call args', async () => {
+  const { weflayr_setup, weflayr_instrument } = freshSDK();
+
+  let capturedArgs;
+  const client = {
+    chat: {
+      completions: {
+        create: async (args) => { capturedArgs = args; return { id: 'res-1' }; },
+      },
+    },
+  };
+
+  weflayr_setup({
+    ...TEST_CREDS,
+    event_mode: 'default',
+    ignore_fields: (data) => { delete data.messages; return data; },
+    methods: [{ call: 'chat.completions.create' }],
+  });
+
+  const instrumented = weflayr_instrument(client);
+  await instrumented.chat.completions.create({ model: 'gpt-4o-mini', messages: [{ role: 'user', content: 'hello' }] });
+
+  assert.ok(Array.isArray(capturedArgs.messages));
+  assert.equal(capturedArgs.messages[0].content, 'hello');
+});
+
+test('missing methods does not crash on object instrumentation', async () => {
+  const { weflayr_setup, weflayr_instrument } = freshSDK();
+
+  weflayr_setup({
+    ...TEST_CREDS,
+    event_mode: 'default',
+    // methods intentionally omitted
+  });
+
+  const client = weflayr_instrument(fakeClient());
+  const result = await client.chat.completions.create({ model: 'gpt-4o-mini', messages: [] });
+
+  assert.equal(result.id, 'res-1');
+});
+
+test('missing methods does not crash on function instrumentation', async () => {
+  const { weflayr_setup, weflayr_instrument } = freshSDK();
+
+  weflayr_setup({
+    ...TEST_CREDS,
+    event_mode: 'default',
+    // methods intentionally omitted
+  });
+
+  async function myFn(x) { return x * 2; }
+  const instrumented = weflayr_instrument(myFn);
+
+  assert.equal(await instrumented(5), 10);
+});
+
+// ---------------------------------------------------------------------------
+// enabled: false — target passes through unchanged, calls still work
+// ---------------------------------------------------------------------------
+
+test('enabled:false returns the original object untouched', () => {
+  const { weflayr_setup, weflayr_instrument } = freshSDK();
+
+  weflayr_setup({ methods: [{ call: 'chat.completions.create' }] , enabled: false });
+
+  const client = fakeClient();
+  const result = weflayr_instrument(client);
+
+  assert.strictEqual(result, client);
+});
+
+test('enabled:false returns the original function untouched', () => {
+  const { weflayr_setup, weflayr_instrument } = freshSDK();
+
+  async function myFn(x) { return x * 2; }
+  weflayr_setup({ methods: [{ call: 'myFn' }] , enabled: false });
+
+  assert.strictEqual(weflayr_instrument(myFn), myFn);
+});
+
+test('enabled:false — original function still executes correctly', async () => {
+  const { weflayr_setup, weflayr_instrument } = freshSDK();
+
+  weflayr_setup({ methods: [{ call: 'chat.completions.create' }] , enabled: false });
+
+  const client = weflayr_instrument(fakeClient());
+  const result = await client.chat.completions.create({ model: 'gpt-4o-mini', messages: [] });
+
+  assert.equal(result.id, 'res-1');
+});
+