weflayr 0.3.0 → 0.3.2

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,85 +8,6 @@ Observability for Node.js - instrument any client or method with one line.
 npm install weflayr
 ```
 
-## Environment variables
+## Documentation
 
-```bash
-WEFLAYR_INTAKE_URL=https://api.weflayr.com
-WEFLAYR_CLIENT_ID=your-client-id-uuid
-WEFLAYR_CLIENT_SECRET=your-client-secret
-```
-
-## Usage
-
-```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: [],
-  methods: [
-    { 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' }],
-  __weflayr_tags: { feature: 'chat', customer_id: '42' },
-});
-```
-
-## Instrumenting a plain function
-
-```js
-async function fetchModels() {
-  const res = await fetch('https://api.example.com/models');
-  return res.json();
-}
-
-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 |
-
-Field paths support dot notation (`foo.bar`), and array traversal (`messages[].content`).
-
-## Middleware
-
-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,
-})
-```
-
-The returned object is merged into the event payload.
+Full documentation, examples, and configuration reference: **[docs.weflayr.com](https://docs.weflayr.com)**

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 flayr 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,8 +1,9 @@
 {
   "name": "weflayr",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "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/index.test.js"
   },
@@ -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, 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, send_event };
+module.exports = { weflayr_setup, weflayr_instrument, send_event, flayred };

package/src/instrument.js

@@ -7,7 +7,12 @@ 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) {
@@ -185,73 +190,29 @@ function _toPlain(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 === 'ignore') {
-    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 _pickFields(clone, settings.allow_fields || []);
-}
-
-function _pickFields(obj, allowFields) {
-  if (!obj || typeof obj !== 'object' || allowFields.length === 0) return obj;
-
-  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]);
-    }
-  }
-  return result;
-}
-
-function _deleteField(obj, path) {
-  if (!obj || typeof obj !== 'object') return;
-
-  const arrayMatch = path.match(/^(\w+)\[\]\.(.+)$/);
-  if (arrayMatch) {
-    const [, arrayKey, rest] = arrayMatch;
-    if (Array.isArray(obj[arrayKey])) {
-      obj[arrayKey].forEach(item => _deleteField(item, rest));
-    }
-    return;
-  }
-
-  const dotIdx = path.indexOf('.');
-  if (dotIdx === -1) {
-    delete obj[path];
-  } else {
-    _deleteField(obj[path.slice(0, dotIdx)], path.slice(dotIdx + 1));
-  }
 }
 
 const _debug = process.env.WEFLAYR_DEBUG === 'true';
 
 function _sendEvent(eventType, data) {
+  if (_config._blocked) {
+    console.warn(`[weflayr] is blocked and can't send event, ensure your configuration is valid`);
+    return;
+  }
   const { intakeUrl, clientId, clientSecret } = _config;
   const endpoint = `${intakeUrl.replace(/\/$/, '')}/${clientId}/`;
 

package/tests/index.test.js

@@ -3,13 +3,16 @@
 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')];
-  process.env.WEFLAYR_INTAKE_URL = 'http://localhost:19999'; // nothing listening — fire-and-forget is fine
-  process.env.WEFLAYR_CLIENT_ID = 'test-client-id';
-  process.env.WEFLAYR_CLIENT_SECRET = 'test-secret';
   return require('../src/index');
 }
 
@@ -25,16 +28,16 @@ function fakeClient() {
 }
 
 // ---------------------------------------------------------------------------
-// Missing options don't crash
+// Content policy — function-based middleware
 // ---------------------------------------------------------------------------
 
-test('missing ignore_fields does not crash', async () => {
+test('ignore_fields function filters event data', async () => {
   const { weflayr_setup, weflayr_instrument } = freshSDK();
 
   weflayr_setup({
+    ...TEST_CREDS,
     event_mode: 'default',
-    content_policy: 'ignore',
-    // ignore_fields intentionally omitted
+    ignore_fields: (data) => { delete data.messages; return data; },
     methods: [{ call: 'chat.completions.create' }],
   });
 
@@ -44,13 +47,13 @@ test('missing ignore_fields does not crash', async () => {
   assert.equal(result.id, 'res-1');
 });
 
-test('missing allow_fields does not crash', async () => {
+test('allow_fields function filters event data', async () => {
   const { weflayr_setup, weflayr_instrument } = freshSDK();
 
   weflayr_setup({
+    ...TEST_CREDS,
     event_mode: 'default',
-    content_policy: 'allow',
-    // allow_fields intentionally omitted
+    allow_fields: (data) => ({ model: data.model }),
     methods: [{ call: 'chat.completions.create' }],
   });
 
@@ -60,13 +63,15 @@ test('missing allow_fields does not crash', async () => {
   assert.equal(result.id, 'res-1');
 });
 
-test('missing methods does not crash on object instrumentation', async () => {
+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',
-    content_policy: 'ignore',
-    // methods intentionally omitted
+    ignore_fields: (data) => data,
+    allow_fields: (data) => data,
+    methods: [{ call: 'chat.completions.create' }],
   });
 
   const client = weflayr_instrument(fakeClient());
@@ -75,49 +80,55 @@ test('missing methods does not crash on object instrumentation', async () => {
   assert.equal(result.id, 'res-1');
 });
 
-test('missing methods does not crash on function instrumentation', async () => {
+test('no content policy — pass-through, function still works', async () => {
   const { weflayr_setup, weflayr_instrument } = freshSDK();
 
   weflayr_setup({
+    ...TEST_CREDS,
     event_mode: 'default',
-    content_policy: 'ignore',
-    // methods intentionally omitted
+    methods: [{ call: 'chat.completions.create' }],
   });
 
-  async function myFn(x) { return x * 2; }
-  const instrumented = weflayr_instrument(myFn);
+  const client = weflayr_instrument(fakeClient());
+  const result = await client.chat.completions.create({ model: 'gpt-4o-mini', messages: [] });
 
-  assert.equal(await instrumented(5), 10);
+  assert.equal(result.id, 'res-1');
 });
 
-// ---------------------------------------------------------------------------
-// enabled: false — target passes through unchanged, calls still work
-// ---------------------------------------------------------------------------
-
-test('enabled:false returns the original object untouched', () => {
+test('ignore_fields does not mutate actual call args', async () => {
   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);
-});
+  let capturedArgs;
+  const client = {
+    chat: {
+      completions: {
+        create: async (args) => { capturedArgs = args; return { id: 'res-1' }; },
+      },
+    },
+  };
 
-test('enabled:false returns the original function untouched', () => {
-  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' }],
+  });
 
-  async function myFn(x) { return x * 2; }
-  weflayr_setup({ methods: [{ call: 'myFn' }] }, { enabled: false });
+  const instrumented = weflayr_instrument(client);
+  await instrumented.chat.completions.create({ model: 'gpt-4o-mini', messages: [{ role: 'user', content: 'hello' }] });
 
-  assert.strictEqual(weflayr_instrument(myFn), myFn);
+  assert.ok(Array.isArray(capturedArgs.messages));
+  assert.equal(capturedArgs.messages[0].content, 'hello');
 });
 
-test('enabled:false — original function still executes correctly', async () => {
+test('missing methods does not crash on object instrumentation', async () => {
   const { weflayr_setup, weflayr_instrument } = freshSDK();
 
-  weflayr_setup({ methods: [{ call: 'chat.completions.create' }] }, { enabled: false });
+  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: [] });
@@ -125,67 +136,53 @@ test('enabled:false — original function still executes correctly', async () =>
   assert.equal(result.id, 'res-1');
 });
 
-// ---------------------------------------------------------------------------
-// Invalid content_policy falls back to allow — function still works correctly
-// ---------------------------------------------------------------------------
-
-test('invalid content_policy does not crash', async () => {
+test('missing methods does not crash on function instrumentation', async () => {
   const { weflayr_setup, weflayr_instrument } = freshSDK();
 
   weflayr_setup({
+    ...TEST_CREDS,
     event_mode: 'default',
-    content_policy: 'not_a_real_policy',
-    allow_fields: [],
-    methods: [{ call: 'chat.completions.create' }],
+    // methods intentionally omitted
   });
 
-  const client = weflayr_instrument(fakeClient());
-  const result = await client.chat.completions.create({ model: 'gpt-4o-mini', messages: [] });
+  async function myFn(x) { return x * 2; }
+  const instrumented = weflayr_instrument(myFn);
 
-  assert.equal(result.id, 'res-1');
+  assert.equal(await instrumented(5), 10);
 });
 
-test('invalid content_policy does not apply ignore_fields', async () => {
+// ---------------------------------------------------------------------------
+// enabled: false — target passes through unchanged, calls still work
+// ---------------------------------------------------------------------------
+
+test('enabled:false returns the original object untouched', () => {
   const { weflayr_setup, weflayr_instrument } = freshSDK();
 
-  let capturedArgs;
-  const client = {
-    chat: {
-      completions: {
-        create: async (args) => { capturedArgs = args; return { id: 'res-1' }; },
-      },
-    },
-  };
+  weflayr_setup({ methods: [{ call: 'chat.completions.create' }] , enabled: false });
 
-  weflayr_setup({
-    event_mode: 'default',
-    content_policy: 'not_a_real_policy',
-    ignore_fields: ['messages'],
-    allow_fields: [],
-    methods: [{ call: 'chat.completions.create' }],
-  });
+  const client = fakeClient();
+  const result = weflayr_instrument(client);
 
-  const instrumented = weflayr_instrument(client);
-  await instrumented.chat.completions.create({ model: 'gpt-4o-mini', messages: [{ role: 'user', content: 'hello' }] });
+  assert.strictEqual(result, client);
+});
 
-  // ignore_fields must NOT have been applied — the real call receives the original args
-  assert.ok(Array.isArray(capturedArgs.messages));
-  assert.equal(capturedArgs.messages[0].content, 'hello');
+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('undefined content_policy falls back to allow (pass-through)', async () => {
+test('enabled:false — original function still executes correctly', async () => {
   const { weflayr_setup, weflayr_instrument } = freshSDK();
 
-  weflayr_setup({
-    event_mode: 'default',
-    // content_policy intentionally omitted
-    ignore_fields: ['messages'],
-    allow_fields: [],
-    methods: [{ call: 'chat.completions.create' }],
-  });
+  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');
 });
+