weflayr 0.3.1 → 0.4.0

package/README.md

@@ -1,6 +1,6 @@
 # Weflayr Node.js SDK
 
-Observability for Node.js - instrument any LLM client or function with one line.
+Observability for Node.js — instrument any LLM client or function with one line.
 
 ## Install
 
@@ -8,218 +8,6 @@ Observability for Node.js - instrument any LLM client or function with one line.
 npm install weflayr
 ```
 
-## Quick start
+## Documentation
 
-```js
-const { weflayr_setup, weflayr_instrument } = require('weflayr');
-
-weflayr_setup({
-  intake_url:    'https://api.weflayr.com',
-  client_id:     'your-client-id-uuid',
-  client_secret: 'your-client-secret',
-  methods: [
-    { call: 'chat.completions.create' },
-  ],
-});
-
-const OpenAI = require('openai');
-const client = weflayr_instrument(new OpenAI({ apiKey: process.env.OPENAI_API_KEY }));
-
-const response = await client.chat.completions.create({
-  model: 'gpt-4o-mini',
-  messages: [{ role: 'user', content: 'Hello' }],
-  __weflayr_tags: { feature: 'chat', customer_id: '42' },
-});
-```
-
-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
-async function fetchModels() {
-  const res = await fetch('https://api.example.com/models');
-  return res.json();
-}
-
-weflayr_setup({
-  // ...
-  methods: [
-    {
-      call: 'fetchModels',
-      middleware: (_args, response) => ({ count: response?.data?.length ?? 0 }),
-    },
-  ],
-});
-
-const instrumented = weflayr_instrument(fetchModels);
-const models = await instrumented({ __weflayr_tags: { app: 'my-app' } });
-```
-
----
-
-## Disabling instrumentation
-
-```js
-weflayr_setup({
-  // ...
-  enabled: false,
-});
-```
-
-`weflayr_instrument` returns the original object untouched when `enabled` is `false`.
-
----
-
-## 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 }));
-```
-
-### 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,
-      };
-    },
-  },
-],
-```
+Full documentation, examples, and configuration reference: **[docs.weflayr.com](https://docs.weflayr.com)**

package/index.d.ts

@@ -36,13 +36,19 @@ export interface MethodConfig {
   call: string;
   middleware?: MiddlewareFn;
   streamMiddleware?: StreamMiddlewareFn;
+  /**
+   * Property name on the response object that holds the async iterable stream.
+   * Use when the SDK returns `{ [streamPath]: AsyncIterable }` instead of a direct AsyncIterable.
+   * e.g. `'stream'` for AWS Bedrock's `ConverseStreamCommand`.
+   */
+  streamPath?: string;
 }
 
 /** 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. */
+  /** UUID identifying the flayr credential pair. */
   client_id: string;
   /** Bearer token used when calling the intake API. */
   client_secret: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "weflayr",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Weflayr Node.js SDK — instrument any LLM client via JS Proxy",
   "main": "src/index.js",
   "types": "index.d.ts",

package/src/instrument.js

@@ -87,6 +87,12 @@ function _wrapFn(fn, methodName, methodConfig) {
         return _wrapStream(result, methodName, tags, requestArgs, settings, startTime, methodConfig, eventId);
       }
 
+      if (methodConfig.streamPath && result && _isAsyncIterable(result[methodConfig.streamPath])) {
+        _sendEvent('stream_start', { event_id: eventId, method: methodName, tags });
+        const wrappedStream = _wrapStream(result[methodConfig.streamPath], methodName, tags, requestArgs, settings, startTime, methodConfig, eventId);
+        return { ...result, [methodConfig.streamPath]: wrappedStream };
+      }
+
       const middlewareData = methodConfig.middleware
         ? methodConfig.middleware(requestArgs, result) || {}
         : {};
@@ -166,14 +172,23 @@ async function* _wrapStream(stream, methodName, tags, requestArgs, settings, sta
 
 function _extractTags(args) {
   let tags = {};
-  const cleanArgs = args.map(arg => {
-    if (arg && typeof arg === 'object' && !Array.isArray(arg) && '__weflayr_tags' in arg) {
-      const { __weflayr_tags, ...rest } = arg;
-      tags = __weflayr_tags || {};
-      return rest;
+
+  function strip(obj) {
+    if (!obj || typeof obj !== 'object' || Array.isArray(obj)) return;
+    if ('__weflayr_tags' in obj) {
+      tags = obj.__weflayr_tags || {};
+      delete obj.__weflayr_tags;
     }
+    for (const key of Object.keys(obj)) {
+      strip(obj[key]);
+    }
+  }
+
+  const cleanArgs = args.map(arg => {
+    if (arg && typeof arg === 'object' && !Array.isArray(arg)) strip(arg);
     return arg;
   });
+
   return { tags, cleanArgs };
 }
 

package/src/providers/bedrock-runtime.d.ts

@@ -0,0 +1,6 @@
+import { MethodConfig, StreamAccumulator } from '../../../index';
+
+export function createStreamAccumulator(): StreamAccumulator;
+
+/** Ready-to-use method config for `client.send(new ConverseStreamCommand(...))`. */
+export const converseStream: MethodConfig;

package/src/providers/bedrock-runtime.js

@@ -0,0 +1,28 @@
+'use strict';
+
+function createStreamAccumulator() {
+  let input_tokens = null;
+  let output_tokens = null;
+
+  return {
+    onChunk(chunk) {
+      if (chunk.metadata?.usage) {
+        input_tokens = chunk.metadata.usage.inputTokens ?? null;
+        output_tokens = chunk.metadata.usage.outputTokens ?? null;
+        return true;
+      }
+      return false;
+    },
+    finalize() {
+      return { input_tokens, output_tokens };
+    },
+  };
+}
+
+const converseStream = {
+  call: 'send',
+  streamPath: 'stream',
+  streamMiddleware: createStreamAccumulator,
+};
+
+module.exports = { converseStream, createStreamAccumulator };