weflayr 0.8.1 → 0.9.0

package/index.d.ts

@@ -66,6 +66,11 @@ export interface WeflayrSettings {
    * Mutually exclusive with `ignore_fields` — setting both blocks all events.
    */
   allow_fields?: ContentPolicyFn;
+  /**
+   * Static tags attached to every instrumented call. Can be overridden per-call
+   * via `__weflayr_tags` or at runtime via `weflayr_propagate`.
+   */
+  default_tags?: Tags;
   /** Methods to instrument on the proxied object. */
   methods?: MethodConfig[];
 }
@@ -80,6 +85,14 @@ export function weflayr_setup(settings: WeflayrSettings): void;
  */
 export function weflayr_instrument<T>(target: T): T;
 
+/**
+ * Adds or overrides a single key in the runtime default tags.
+ * Equivalent to adding the key to `default_tags` in `weflayr_setup`, but callable at any
+ * point during execution (e.g. inside a request handler to propagate a customer ID).
+ * Propagated tags are overridden by per-call `__weflayr_tags`.
+ */
+export function weflayr_propagate(key: string, value: string | number | boolean): void;
+
 /** 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,

package/package.json

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

package/src/index.js

@@ -1,6 +1,6 @@
 'use strict';
 
-const { configure, weflayr_instrument, send_event } = require('./instrument');
+const { configure, weflayr_instrument, weflayr_propagate, send_event } = require('./instrument');
 
 /**
  *
@@ -32,4 +32,4 @@ function flayred(options) {
   return options;
 }
 
-module.exports = { weflayr_setup, weflayr_instrument, send_event, flayred };
+module.exports = { weflayr_setup, weflayr_instrument, weflayr_propagate, send_event, flayred };

package/src/instrument.js

@@ -7,6 +7,7 @@ const { version: SDK_VERSION } = require('../package.json');
 const SDK_LANGUAGE = 'javascript';
 
 let _config = null;
+let _propagated = {};
 
 function configure(intakeUrl, clientId, clientSecret, settings) {
   if (settings.ignore_fields && settings.allow_fields) {
@@ -173,12 +174,12 @@ async function* _wrapStream(stream, methodName, tags, requestArgs, settings, sta
 }
 
 function _extractTags(args) {
-  let tags = {};
+  let callTags = {};
 
   function strip(obj) {
     if (!obj || typeof obj !== 'object' || Array.isArray(obj)) return;
     if ('__weflayr_tags' in obj) {
-      tags = obj.__weflayr_tags || {};
+      callTags = obj.__weflayr_tags || {};
       delete obj.__weflayr_tags;
     }
     for (const key of Object.keys(obj)) {
@@ -191,9 +192,19 @@ function _extractTags(args) {
     return arg;
   });
 
+  const tags = {
+    ...(_config.settings.default_tags || {}),
+    ..._propagated,
+    ...callTags,
+  };
+
   return { tags, cleanArgs };
 }
 
+function weflayr_propagate(key, value) {
+  _propagated[key] = value;
+}
+
 function _isAsyncIterable(value) {
   return value != null && typeof value[Symbol.asyncIterator] === 'function';
 }
@@ -297,4 +308,4 @@ function send_event(eventType, data) {
   return _sendEvent(eventType, data);
 }
 
-module.exports = { configure, weflayr_instrument, send_event };
+module.exports = { configure, weflayr_instrument, weflayr_propagate, send_event };

package/tests/index.test.js

@@ -268,6 +268,10 @@ test('snippet quickstart_setup: wraps client, sends before+after events', async
       intake_url:    process.env.WEFLAYR_INTAKE_URL,
       client_id:     process.env.WEFLAYR_CLIENT_ID,
       client_secret: process.env.WEFLAYR_CLIENT_SECRET,
+      default_tags: {
+        app: 'my-app',
+        version: '1.0.0',
+      },
       methods: [
         { call: 'chat.completions.create' },
       ],
@@ -283,6 +287,8 @@ test('snippet quickstart_setup: wraps client, sends before+after events', async
   assert.ok(sent.some(e => e.event_type === 'before'), 'before event sent');
   assert.ok(sent.some(e => e.event_type === 'after'),  'after event sent');
   assert.equal(sent[0].method, 'chat.completions.create');
+  assert.equal(sent[0].tags.app, 'my-app');
+  assert.equal(sent[0].tags.version, '1.0.0');
 });
 
 test('snippet quickstart_call: tags stripped from call, tags in telemetry', async () => {
@@ -427,3 +433,150 @@ test('snippet openai_image_generation: b64_json stripped from telemetry, url pre
   assert.ok(after.response.data[0].url, 'url preserved in telemetry');
 });
 
+// ---------------------------------------------------------------------------
+// default_tags and weflayr_propagate — behavioural tests
+// ---------------------------------------------------------------------------
+
+test('default_tags appear in before and after events', async () => {
+  const { weflayr_setup, weflayr_instrument } = freshSDK();
+
+  weflayr_setup({
+    ...TEST_CREDS,
+    default_tags: { app: 'my-app', version: '1.2.0' },
+    methods: [{ call: 'chat.completions.create' }],
+  });
+
+  const client = weflayr_instrument(fakeClient());
+  const sent = await captureHttp(async () => {
+    await client.chat.completions.create({ model: 'gpt-4o-mini', messages: [] });
+  });
+
+  const before = sent.find(e => e.event_type === 'before');
+  assert.equal(before.tags.app, 'my-app');
+  assert.equal(before.tags.version, '1.2.0');
+  const after = sent.find(e => e.event_type === 'after');
+  assert.equal(after.tags.app, 'my-app');
+  assert.equal(after.tags.version, '1.2.0');
+});
+
+test('weflayr_propagate adds a tag to before and after events', async () => {
+  const { weflayr_setup, weflayr_instrument, weflayr_propagate } = freshSDK();
+
+  weflayr_setup({
+    ...TEST_CREDS,
+    methods: [{ call: 'chat.completions.create' }],
+  });
+
+  weflayr_propagate('customer_id', 'acme-corp');
+
+  const client = weflayr_instrument(fakeClient());
+  const sent = await captureHttp(async () => {
+    await client.chat.completions.create({ model: 'gpt-4o-mini', messages: [] });
+  });
+
+  const before = sent.find(e => e.event_type === 'before');
+  assert.equal(before.tags.customer_id, 'acme-corp');
+  const after = sent.find(e => e.event_type === 'after');
+  assert.equal(after.tags.customer_id, 'acme-corp');
+});
+
+test('tag priority: __weflayr_tags > weflayr_propagate > default_tags', async () => {
+  const { weflayr_setup, weflayr_instrument, weflayr_propagate } = freshSDK();
+
+  weflayr_setup({
+    ...TEST_CREDS,
+    default_tags: { env: 'production', app: 'my-app' },
+    methods: [{ call: 'chat.completions.create' }],
+  });
+
+  weflayr_propagate('env', 'staging');  // overrides default_tags.env
+
+  const client = weflayr_instrument(fakeClient());
+  const sent = await captureHttp(async () => {
+    await client.chat.completions.create({
+      model: 'gpt-4o-mini',
+      messages: [],
+      __weflayr_tags: { env: 'test' },  // overrides both
+    });
+  });
+
+  const before = sent.find(e => e.event_type === 'before');
+  assert.equal(before.tags.env, 'test');      // per-call wins
+  assert.equal(before.tags.app, 'my-app');    // from default_tags, untouched
+});
+
+// ---------------------------------------------------------------------------
+// Propagate — documentation snippets
+// ---------------------------------------------------------------------------
+
+test('snippet propagate_default_tags: default_tags in every event', async () => {
+  freshSDK();
+  setSnippetEnv();
+
+  const sent = await captureHttp(async () => {
+    // SNIPPET_START: propagate_default_tags
+    const { weflayr_setup, weflayr_instrument } = require('weflayr');
+
+    weflayr_setup({
+      intake_url:    process.env.WEFLAYR_INTAKE_URL,
+      client_id:     process.env.WEFLAYR_CLIENT_ID,
+      client_secret: process.env.WEFLAYR_CLIENT_SECRET,
+      default_tags: {
+        app: 'my-app',
+        version: '1.2.0',
+        env: 'production',
+      },
+      methods: [{ call: 'chat.completions.create' }],
+    });
+
+    const OpenAI = require('openai');
+    const client = weflayr_instrument(new OpenAI({ apiKey: process.env.OPENAI_API_KEY }));
+    // SNIPPET_END: propagate_default_tags
+
+    await client.chat.completions.create({ model: 'gpt-4o-mini', messages: [] });
+  });
+
+  const before = sent.find(e => e.event_type === 'before');
+  assert.ok(before, 'before event sent');
+  assert.equal(before.tags.app, 'my-app');
+  assert.equal(before.tags.version, '1.2.0');
+  assert.equal(before.tags.env, 'production');
+  const after = sent.find(e => e.event_type === 'after');
+  assert.ok(after, 'after event sent');
+  assert.equal(after.tags.app, 'my-app');
+});
+
+test('snippet propagate_runtime: propagated tag in before and after', async () => {
+  const { weflayr_setup, weflayr_instrument, weflayr_propagate } = freshSDK();
+  setSnippetEnv();
+
+  let capturedArgs;
+  const raw = {
+    chat: { completions: { create: async (args) => { capturedArgs = args; return { id: 'res-1' }; } } },
+  };
+  weflayr_setup({ ...TEST_CREDS, methods: [{ call: 'chat.completions.create' }] });
+  const client = weflayr_instrument(raw);
+
+  const sent = await captureHttp(async () => {
+    // SNIPPET_START: propagate_runtime
+    const { weflayr_propagate } = require('weflayr');
+
+    // In a request handler — tags every LLM call made during this execution
+    weflayr_propagate('customer_id', 'acme-corp');
+
+    await client.chat.completions.create({
+      model: 'gpt-4o-mini',
+      messages: [{ role: 'user', content: 'Hello!' }],
+    });
+    // SNIPPET_END: propagate_runtime
+  });
+
+  assert.ok(!('__weflayr_tags' in capturedArgs), 'no tags leaked to provider');
+  const before = sent.find(e => e.event_type === 'before');
+  assert.ok(before, 'before event sent');
+  assert.equal(before.tags.customer_id, 'acme-corp');
+  const after = sent.find(e => e.event_type === 'after');
+  assert.ok(after, 'after event sent');
+  assert.equal(after.tags.customer_id, 'acme-corp');
+});
+