weflayr 0.16.1 → 0.20.3

package/.prettierrc.json

@@ -0,0 +1,7 @@
+{
+  "semi": true,
+  "singleQuote": true,
+  "trailingComma": "es5",
+  "printWidth": 100,
+  "tabWidth": 2
+}

package/LICENSE-MIT

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Langfuse GmbH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE

@@ -0,0 +1,12 @@
+Weflayr Node.js SDK
+Copyright 2026 Weflayr
+
+This product includes software derived from langfuse-js
+(https://github.com/langfuse/langfuse-js), Copyright 2024 Langfuse GmbH,
+licensed under the MIT License.
+
+Specifically, the OpenTelemetry span filter, span processor, and tag-propagation
+helpers in src/otel/ are derived from langfuse-js packages/otel and packages/core
+and have been adapted for the Weflayr intake API and tag schema.
+
+See LICENSE-MIT for the full MIT license text.

package/eslint.config.mjs

@@ -0,0 +1,36 @@
+export default [
+  {
+    languageOptions: {
+      ecmaVersion: 2023,
+      sourceType: "commonjs",
+      globals: {
+        // Node.js
+        require: "readonly",
+        module: "readonly",
+        exports: "writable",
+        __dirname: "readonly",
+        __filename: "readonly",
+        process: "readonly",
+        Buffer: "readonly",
+        console: "readonly",
+        setTimeout: "readonly",
+        clearTimeout: "readonly",
+        setInterval: "readonly",
+        clearInterval: "readonly",
+        // Web platform (available in modern Node)
+        fetch: "readonly",
+        URL: "readonly",
+        ReadableStream: "readonly",
+        TransformStream: "readonly",
+        TextEncoder: "readonly",
+        TextDecoder: "readonly",
+      },
+    },
+    rules: {
+      "no-unused-vars": ["warn", { argsIgnorePattern: "^_" }],
+      "no-undef": "error",
+      "prefer-const": "warn",
+      eqeqeq: ["error", "smart"],
+    },
+  },
+];

package/index.d.ts

@@ -1,134 +1,156 @@
-/** Arbitrary key-value metadata attached to an LLM call. */
+/** Arbitrary key-value tags applied to OTel spans. */
 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.
+ * Span attributes the mask callback can read or scrub. The OpenTelemetry GenAI
+ * semantic-convention keys get autocomplete; the index signature catches user
+ * tags and provider-specific attributes (e.g. Vercel AI's `ai.*`).
  */
-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>;
+export interface OtelSpanAttributes {
+  'gen_ai.system'?: string;
+  'gen_ai.operation.name'?: string;
+  'gen_ai.request.model'?: string;
+  'gen_ai.request.temperature'?: number;
+  'gen_ai.request.max_tokens'?: number;
+  'gen_ai.response.model'?: string;
+  'gen_ai.response.id'?: string;
+  'gen_ai.response.finish_reasons'?: string[];
+  'gen_ai.usage.input_tokens'?: number;
+  'gen_ai.usage.output_tokens'?: number;
+  /** Only populated when `captureMessageContent=true`. */
+  'gen_ai.prompt'?: string;
+  /** Only populated when `captureMessageContent=true`. */
+  'gen_ai.completion'?: string;
+  'gen_ai.tool.name'?: string;
+  'gen_ai.tool.call.id'?: string;
+  'gen_ai.tool.call.arguments'?: string;
+  'error.type'?: string;
+  [key: string]: unknown;
 }
 
-/** Factory called once per stream invocation. */
-export type StreamMiddlewareFn = () => StreamAccumulator;
+/** LLM provider SDKs the `autoInstrument` registry knows how to wire up. */
+export const AiSdk: {
+  readonly OPENAI: 'openai';
+  readonly ANTHROPIC: 'anthropic';
+  readonly BEDROCK: 'bedrock';
+  readonly AZURE: 'azure';
+  readonly COHERE: 'cohere';
+  readonly TOGETHER: 'together';
+  readonly GOOGLE_VERTEX: 'google-vertex';
+  readonly GOOGLE_GENAI: 'google-genai';
+};
+export type AiSdk = (typeof AiSdk)[keyof typeof AiSdk];
 
-/** 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;
-  /**
-   * 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;
-}
+/**
+ * Allowed values for `propagateMetadata({ providerName })`: every SDK the
+ * auto-instrumentation registry knows, plus providers reached via the OpenAI
+ * SDK on the wire but reported as themselves (e.g. Vercel AI Gateway).
+ */
+export const AIProviderName: {
+  readonly OPENAI: 'openai';
+  readonly ANTHROPIC: 'anthropic';
+  readonly BEDROCK: 'bedrock';
+  readonly AZURE: 'azure';
+  readonly COHERE: 'cohere';
+  readonly TOGETHER: 'together';
+  readonly GOOGLE_VERTEX: 'google-vertex';
+  readonly GOOGLE_GENAI: 'google-genai';
+  readonly VERCEL_AI_GATEWAY: 'vercel_ai_gateway';
+};
+export type AIProviderName = (typeof AIProviderName)[keyof typeof AIProviderName];
 
-/** 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;
+export interface SetupOptions {
+  /** Weflayr API key. The server resolves your client_id from this token. */
+  apiKey: string;
+  /** Override the intake base URL. Defaults to WEFLAYR_BASE_URL or https://api.weflayr.com. */
+  baseUrl?: string;
+  /** Tags applied to every emitted span. */
+  defaultTags?: Tags;
   /**
-   * Middleware to strip sensitive fields from event payloads before sending to the intake API.
-   * Mutually exclusive with `allow_fields` — setting both blocks all events.
+   * `'batch'` (default) groups spans for throughput. `'immediate'` flushes every
+   * span synchronously — recommended for short-lived runtimes (Lambda, edge).
    */
-  ignore_fields?: ContentPolicyFn;
+  exportMode?: 'batch' | 'immediate';
   /**
-   * 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.
+   * When `false`, sets OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=false
+   * so instrumentations strip `gen_ai.prompt` / `gen_ai.completion` from spans
+   * before they're emitted. Defaults to `true`.
    */
-  allow_fields?: ContentPolicyFn;
+  captureMessageContent?: boolean;
   /**
-   * Static tags attached to every instrumented call. Can be overridden per-call
-   * via `__weflayr_tags` or at runtime via `weflayr_propagate`.
+   * Last-line-of-defense scrubber. Receives the span attribute bag just before
+   * export; return the (optionally mutated) bag.
    */
-  default_tags?: Tags;
-  /** Methods to instrument on the proxied object. */
-  methods?: MethodConfig[];
+  mask?: (attrs: OtelSpanAttributes) => OtelSpanAttributes;
 }
 
-/** 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;
+/** Initializes the OpenTelemetry tracer + exporter. Call once at app start. */
+export function setup(options: SetupOptions): void;
 
 /**
- * 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`.
+ * Loads and registers OpenTelemetry instrumentation packages for the given provider SDKs.
+ * Throws a clear "install package X" error if the matching package isn't installed.
+ *
+ * @example
+ * await weflayr.autoInstrument({ aiSdks: weflayr.AiSdk.OPENAI, apiKey: '...' });
+ * await weflayr.autoInstrument({ aiSdks: [weflayr.AiSdk.OPENAI, weflayr.AiSdk.ANTHROPIC] });
  */
-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,
-  data: Record<string, unknown>,
-): Promise<void> | undefined;
+export function autoInstrument(
+  options: { aiSdks: AiSdk | AiSdk[] } & Partial<SetupOptions>
+): Promise<void>;
 
-/** Options for {@link weflayr_vercel_ai_middleware}. */
-export interface WeflayrVercelAiMiddlewareOptions {
-  /** Static tags attached to every event emitted by this middleware instance. */
-  tags?: Tags;
+export interface PropagateMetadataOptions {
+  /** Product-side feature triggering the LLM call (e.g. `"onboarding-summary"`). */
+  featureName: string;
+  /** Identifier of the end-user / tenant the call is made for. */
+  customerId: string;
+  /**
+   * Override for the provider seen on the wire. Set this only if it differs
+   * from the SDK auto-detected by OpenTelemetry — e.g. calls routed through
+   * `vercel_ai_gateway` that proxies to OpenAI/Anthropic but should be
+   * reported as the gateway.
+   */
+  providerName?: AIProviderName;
+  /**
+   * Arbitrary scalar key/value pairs to attach. Values must be `string`,
+   * `number`, or `boolean` so they survive the ClickHouse `Map(String,
+   * String)` column they land in. Avoid `featureName` / `customerId` keys
+   * here — they have dedicated fields.
+   */
+  extraTags?: Record<string, string | number | boolean>;
 }
 
 /**
- * Returns a Vercel AI SDK `LanguageModelV1Middleware` that emits Weflayr events.
- * Requires `weflayr_setup` to have been called first.
+ * Attach Weflayr metadata to every LLM span created inside `fn`.
+ *
+ * Every invocation mints a fresh `uuid` that is stamped on every span inside
+ * the scope, so all calls made under one `propagateMetadata` block can be
+ * correlated downstream.
  *
  * @example
- * const model = wrapLanguageModel({
- *   model: openai('gpt-4o-mini'),
- *   middleware: weflayr_vercel_ai_middleware({ tags: { feature: 'chat' } }),
- * });
+ * await weflayr.propagateMetadata(
+ *   { featureName: 'onboarding', customerId: '#3756', extraTags: { variant: 'control' } },
+ *   async () => { await openai.chat.completions.create({ ... }); },
+ * );
  */
-export function weflayr_vercel_ai_middleware(options?: WeflayrVercelAiMiddlewareOptions): object;
+export function propagateMetadata<T>(
+  options: PropagateMetadataOptions,
+  fn: () => Promise<T> | T
+): Promise<T> | T;
 
 /**
- * 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.
+ * Decorator form. Apply to a class method to propagate metadata around every call.
+ * Each invocation of the wrapped function mints its own `uuid`.
  *
  * @example
- * await openai.chat.completions.create(flayred({
- *   model: 'gpt-4o-mini',
- *   messages: [...],
- *   __weflayr_tags: { feature: 'haiku', customer_id: '42' },
- * }));
+ * class ChatService {
+ *   @weflayr.propagateMetadata({ featureName: 'chat', customerId: 'user_42' })
+ *   async reply(userId: string) { ... }
+ * }
  */
-export function flayred<T>(options: T & { __weflayr_tags?: Record<string, string | number | boolean> }): T;
+export function propagateMetadata(
+  options: PropagateMetadataOptions
+): <T>(target: T, key?: string, descriptor?: PropertyDescriptor) => T;
+
+/** Flush any pending spans. Await before a short-lived runtime exits. */
+export function flush(): Promise<void>;

package/package.json

@@ -1,11 +1,15 @@
 {
   "name": "weflayr",
-  "version": "0.16.1",
+  "version": "0.20.3",
   "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"
+    "test": "node --test tests/index.test.js",
+    "lint": "eslint src tests",
+    "lint:fix": "eslint src tests --fix",
+    "format": "prettier --write src tests",
+    "format:check": "prettier --check src tests"
   },
   "keywords": [
     "llm",
@@ -17,5 +21,17 @@
   "engines": {
     "node": ">=18.0.0"
   },
-  "dependencies": {}
+  "dependencies": {
+    "@opentelemetry/api": "^1.9.1",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.219.0",
+    "@opentelemetry/instrumentation": "^0.219.0",
+    "@opentelemetry/resources": "^2.8.0",
+    "@opentelemetry/sdk-trace-base": "^2.8.0",
+    "@opentelemetry/sdk-trace-node": "^2.8.0",
+    "async-retry": "^1.3.3"
+  },
+  "devDependencies": {
+    "eslint": "^9.18.0",
+    "prettier": "^3.4.2"
+  }
 }

package/src/auto-instrument.js

@@ -0,0 +1,114 @@
+'use strict';
+
+const { registerInstrumentations } = require('@opentelemetry/instrumentation');
+
+const { debug } = require('./logger');
+const { setup, _state } = require('./setup');
+const { patchOpenAIStreamingUsage } = require('./otel/openai-streaming-usage');
+
+const AiSdk = Object.freeze({
+  OPENAI: 'openai',
+  ANTHROPIC: 'anthropic',
+  BEDROCK: 'bedrock',
+  AZURE: 'azure',
+  COHERE: 'cohere',
+  TOGETHER: 'together',
+  GOOGLE_VERTEX: 'google-vertex',
+  GOOGLE_GENAI: 'google-genai',
+});
+
+// Allowed values for `propagateMetadata({ providerName })`: every SDK the
+// auto-instrumentation registry knows, plus providers reached via the OpenAI
+// SDK on the wire but reported as themselves (e.g. Vercel AI Gateway proxies
+// to OpenAI/Anthropic but should be reported as the gateway).
+const AIProviderName = Object.freeze({
+  ...AiSdk,
+  VERCEL_AI_GATEWAY: 'vercel_ai_gateway',
+});
+
+const REGISTRY = {
+  [AiSdk.OPENAI]: '@traceloop/instrumentation-openai',
+  [AiSdk.ANTHROPIC]: '@traceloop/instrumentation-anthropic',
+  [AiSdk.BEDROCK]: '@traceloop/instrumentation-bedrock',
+  [AiSdk.AZURE]: '@traceloop/instrumentation-azure',
+  [AiSdk.COHERE]: '@traceloop/instrumentation-cohere',
+  [AiSdk.TOGETHER]: '@traceloop/instrumentation-together',
+  [AiSdk.GOOGLE_VERTEX]: '@traceloop/instrumentation-vertexai',
+  [AiSdk.GOOGLE_GENAI]: '@traceloop/instrumentation-google-generativeai',
+};
+
+const SETUP_OPTION_KEYS = [
+  'apiKey',
+  'baseUrl',
+  'defaultTags',
+  'exportMode',
+  'mask',
+  'captureMessageContent',
+  'warnOnExportError',
+];
+
+function _instantiateInstrumentation(instrumentationPkg) {
+  for (const value of Object.values(instrumentationPkg)) {
+    if (typeof value === 'function' && /Instrumentation$/.test(value.name)) {
+      return new value();
+    }
+  }
+  if (typeof instrumentationPkg.default === 'function') return new instrumentationPkg.default();
+  throw new Error('No Instrumentation class found in module exports');
+}
+
+async function _instrumentAiSdk(aiSdk) {
+  if (!(aiSdk in REGISTRY)) {
+    throw new Error(
+      `weflayr.autoInstrument: unknown provider "${aiSdk}". Known: ${Object.keys(REGISTRY).join(', ')}`
+    );
+  }
+  const pkg = REGISTRY[aiSdk];
+
+  let instrumentationPkg;
+  try {
+    instrumentationPkg = require(pkg);
+  } catch (err) {
+    throw new Error(
+      `weflayr.autoInstrument("${aiSdk}"): failed to load "${pkg}". ` +
+        `Install it with: npm install ${pkg}\nUnderlying error: ${err.message}`
+    );
+  }
+
+  const instrumentation = _instantiateInstrumentation(instrumentationPkg);
+  if (aiSdk === AiSdk.OPENAI) {
+    // The OpenAI instrumentor drops token usage on streamed calls; backfill it.
+    patchOpenAIStreamingUsage(instrumentation);
+  }
+  registerInstrumentations({ instrumentations: [instrumentation] });
+  debug('autoInstrument: registered aiSdk=%s package=%s', aiSdk, pkg);
+}
+
+/**
+ * Register an OTel Instrumentor for one or more LLM provider SDKs.
+ *
+ * Convenience: pass `apiKey` (+ other `setup()` options) here to skip a
+ * separate `weflayr.setup()` call. If `apiKey` is omitted, `setup()` must
+ * have been called beforehand.
+ */
+async function autoInstrument({ aiSdks, ...options } = {}) {
+  if (aiSdks === undefined) {
+    throw new Error('weflayr.autoInstrument: `aiSdks` is required.');
+  }
+
+  if (!_state.processor) {
+    // setup() picks up WEFLAYR_API_KEY from the env if not passed here.
+    const setupOptions = {};
+    for (const key of SETUP_OPTION_KEYS) {
+      if (options[key] !== undefined) setupOptions[key] = options[key];
+    }
+    setup(setupOptions);
+  }
+
+  const list = Array.isArray(aiSdks) ? aiSdks : [aiSdks];
+  for (const aiSdk of list) {
+    await _instrumentAiSdk(aiSdk);
+  }
+}
+
+module.exports = { autoInstrument, AiSdk, AIProviderName, REGISTRY };

package/src/index.js

@@ -1,36 +1,14 @@
 'use strict';
 
-const { configure, weflayr_instrument, weflayr_propagate, send_event } = require('./instrument');
-const { weflayr_vercel_ai_middleware } = require('./vercel-ai-middleware');
-
-/**
- *
- * @param {*} settings: settings for weflayr
- * @returns
- */
-function weflayr_setup(settings) {
-  if (settings.enabled === false) return;
-
-  const { intake_url, client_id, client_secret } = settings;
-
-  if (!intake_url || !client_id || !client_secret) {
-    throw new Error(
-      'Weflayr: intake_url, client_id and client_secret must be set in 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, weflayr_propagate, send_event, flayred, weflayr_vercel_ai_middleware };
+const { setup, flush } = require('./setup');
+const { autoInstrument, AiSdk, AIProviderName } = require('./auto-instrument');
+const { propagateMetadata } = require('./otel/propagation');
+
+module.exports = {
+  setup,
+  flush,
+  autoInstrument,
+  AiSdk,
+  AIProviderName,
+  propagateMetadata,
+};

package/src/logger.js

@@ -0,0 +1,8 @@
+'use strict';
+
+const { debuglog } = require('node:util');
+
+// Enable with NODE_DEBUG=weflayr
+const debug = debuglog('weflayr');
+
+module.exports = { debug };