weflayr 0.22.0 → 0.22.1

package/src/api/index.ts

@@ -0,0 +1,45 @@
+/**
+ * Entry point for the Weflayr public API (revenue, key metrics, customer tags).
+ *
+ * The endpoint functions and types under ./generated are produced from the
+ * platform's OpenAPI spec (`make generate-sdk-api-clients`) and speak the
+ * wire's snake_case, same as the Python SDK. generated/facade.gen.ts (also
+ * produced by that command, via scripts/generate_facade.mjs) wraps every
+ * endpoint so JS callers use camelCase instead - see ./caseConversion and
+ * ./makeEndpoint. This module is the handwritten front door that configures
+ * their client:
+ *
+ *     const weflayr = require('weflayr');
+ *
+ *     const apiClient = weflayr.client({ apiKey: 'wf-...' });
+ *     const { data } = await weflayr.api.getAllRevenue({ client: apiClient, throwOnError: true });
+ */
+
+import { type Client, createClient, createConfig } from './generated/client';
+
+export const DEFAULT_BASE_URL = 'https://app.weflayr.com/api';
+
+export interface ApiClientOptions {
+  /** A project API key, created in the Weflayr dashboard. Defaults to the `WEFLAYR_API_KEY` environment variable. */
+  apiKey?: string;
+  /** Where the API lives — override for local or self-hosted deployments. */
+  baseUrl?: string;
+}
+
+/** A client for the public API, authenticated with a project API key. */
+export function client(options: ApiClientOptions = {}): Client {
+  const apiKey = options.apiKey || process.env.WEFLAYR_API_KEY;
+  if (!apiKey) {
+    throw new Error(
+      'weflayr.client: `apiKey` is required (pass it explicitly or set WEFLAYR_API_KEY)'
+    );
+  }
+  return createClient(
+    createConfig({
+      baseUrl: options.baseUrl ?? DEFAULT_BASE_URL,
+      auth: () => apiKey,
+    })
+  );
+}
+
+export * from './generated/facade.gen';

package/src/api/makeEndpoint.ts

@@ -0,0 +1,54 @@
+/**
+ * Wraps a generated public-API endpoint function so its `body`/`path`/`query`
+ * are converted from camelCase to the wire's snake_case on the way out, and
+ * its `data`/`error` are converted back to camelCase on the way in.
+ *
+ * Instantiated once per endpoint in generated/facade.gen.ts, produced by
+ * scripts/generate_facade.mjs - see that script for how the per-endpoint
+ * type arguments are derived.
+ */
+
+import { toCamelCaseDeep, toSnakeCaseDeep } from './caseConversion';
+import type { Client } from './generated/client';
+
+export interface ClientOption {
+  client: Client;
+  throwOnError?: boolean;
+  headers?: HeadersInit;
+}
+
+export interface CallResult<TData, TError> {
+  data?: TData;
+  error?: TError;
+  request?: Request;
+  response?: Response;
+}
+
+type WireResult = { data?: unknown; error?: unknown };
+
+export function makeEndpoint<TParams extends object, TData, TError>(
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  wireFn: (options: any) => Promise<WireResult>
+): (options: ClientOption & TParams) => Promise<CallResult<TData, TError>> {
+  return async (options) => {
+    const wireOptions = { ...options } as Record<string, unknown>;
+    for (const key of ['body', 'path', 'query']) {
+      if (wireOptions[key] !== undefined) {
+        wireOptions[key] = toSnakeCaseDeep(wireOptions[key]);
+      }
+    }
+
+    let result: WireResult;
+    try {
+      result = await wireFn(wireOptions);
+    } catch (error) {
+      throw toCamelCaseDeep(error as object);
+    }
+
+    return {
+      ...result,
+      data: result.data !== undefined ? (toCamelCaseDeep(result.data) as TData) : undefined,
+      error: result.error !== undefined ? (toCamelCaseDeep(result.error) as TError) : undefined,
+    };
+  };
+}

package/src/auto-instrument.js

@@ -12,16 +12,24 @@ const AiSdk = Object.freeze({
   COHERE: 'cohere',
   GOOGLE_GENAI: 'google-genai',
   ELEVENLABS: 'elevenlabs',
+  VERCEL_AI_GATEWAY: 'vercel_ai_gateway',
 });
 
-// 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
-// Those are instrumented via `autoInstrument({ aiSdks: 'openai' })` and labelled
-// through `propagateMetadata({ providerName })`, not their own instrumentor.
+// Allowed values for `propagateMetadata({ providerName })`: the actual AI
+// providers a call can be attributed to. Unlike AiSdk this names providers,
+// not SDKs — google-genai is an SDK whose calls are labelled gemini or vertex,
+// and mistral has no Node OTel instrumentor so it is reached through the
+// OpenAI SDK (OpenAI-compatible endpoint) but reported as itself.
 const AIProviderName = Object.freeze({
-  ...AiSdk,
+  OPENAI: 'openai',
+  ANTHROPIC: 'anthropic',
+  BEDROCK: 'bedrock',
+  COHERE: 'cohere',
+  ELEVENLABS: 'elevenlabs',
+  MISTRAL: 'mistral',
   VERCEL_AI_GATEWAY: 'vercel_ai_gateway',
+  GEMINI: 'gemini',
+  VERTEX: 'vertex',
 });
 
 // The primary instrumentor for each provider SDK. Most are third-party
@@ -40,6 +48,11 @@ const REGISTRY = {
     requirePath: './instrumentation/elevenlabs/full_instrumentation',
     className: 'ElevenLabsInstrumentor',
   },
+  [AiSdk.VERCEL_AI_GATEWAY]: {
+    package: 'ai',
+    requirePath: './instrumentation/vercel/full_instrumentation',
+    className: 'VercelAiSdkInstrumentor',
+  },
 };
 
 // One complementary instrumentor per provider: a `set_telemetry_attributes`

package/src/index.js

@@ -3,6 +3,9 @@
 const { setup, flush } = require('./setup');
 const { autoInstrument, AiSdk, AIProviderName } = require('./auto-instrument');
 const { propagateMetadata } = require('./otel/propagation');
+// Public-API client (revenue, key metrics, customer tags), compiled from the
+// TypeScript in src/api by `npm run build`.
+const api = require('../dist/api');
 
 module.exports = {
   setup,
@@ -11,4 +14,6 @@ module.exports = {
   AiSdk,
   AIProviderName,
   propagateMetadata,
+  client: api.client,
+  api,
 };

package/src/instrumentation/google/get_provider_name.js

@@ -7,7 +7,8 @@
  * `gen_ai.provider.name = "gcp.gen_ai"` and can't tell Vertex from the Gemini
  * Developer API. We read the client's Vertex flag and return the value to set as
  * `gen_ai.system` (which the normalizer prefers): `vertex_ai` / `gemini`,
- * matching what the Python google-genai instrumentor reports natively. Node-only.
+ * matching what the Python google-genai instrumentor reports natively. The
+ * worker normalizes `vertex_ai` to the canonical `vertex`. Node-only.
  */
 
 // Read the Vertex-vs-Dev backend off the Models instance's api client.

package/src/instrumentation/vercel/full_instrumentation.js

@@ -0,0 +1,44 @@
+'use strict';
+
+/**
+ * Instrumentor for the Vercel AI SDK (`ai` package, v7+).
+ *
+ * The AI SDK ships its own OTel integration in `@ai-sdk/otel`; instrumenting
+ * is registering it globally so every generateText/streamText/embed call emits
+ * GenAI semconv spans through the tracer provider weflayr's setup() installed.
+ * `usage: true` adds the `ai.usage.*` token details (reasoning tokens, uncached
+ * input) that the semconv attributes do not carry.
+ *
+ * The aggregate spans the integration emits around each model call
+ * (invoke_agent, agent_step, duplicated embeddings spans) are filtered out
+ * before export by otel/vercel-ai-sdk-span-filter.js.
+ */
+class VercelAiSdkInstrumentor {
+  instrument() {
+    let registerTelemetry;
+    let OpenTelemetry;
+    try {
+      ({ registerTelemetry } = require('ai'));
+      ({ OpenTelemetry } = require('@ai-sdk/otel'));
+    } catch (err) {
+      throw new Error(
+        'weflayr.autoInstrument("vercel_ai_gateway"): failed to load "ai" / "@ai-sdk/otel". ' +
+          `Install them with: npm install ai @ai-sdk/otel\nUnderlying error: ${err.message}`
+      );
+    }
+    // registerTelemetry only exists since v7.
+    if (typeof registerTelemetry !== 'function') {
+      throw new Error(
+        'weflayr.autoInstrument("vercel_ai_gateway") requires version 7+ of the Vercel AI SDK ' +
+          '(the "ai" package), which added global telemetry registration. ' +
+          'Upgrade with: npm install ai@latest @ai-sdk/otel.\n' +
+          'On ai <= 6 telemetry can only be enabled per call: remove "vercel_ai_gateway" from ' +
+          'aiSdks (pass an empty list if no other sdks need to be instrumented). Instead, make sure ' +
+          'experimental_telemetry: { isEnabled: true } is passed on each generateText/streamText call.'
+      );
+    }
+    registerTelemetry(new OpenTelemetry({ usage: true }));
+  }
+}
+
+module.exports = { VercelAiSdkInstrumentor };

package/src/otel/propagation.js

@@ -6,7 +6,7 @@
 // This file has been modified from its original form:
 //   - Translated from TypeScript to JavaScript
 //   - Replaced Langfuse's fixed schema with Weflayr's structured metadata
-//     (featureName, customerId, providerName, extraTags) plus an
+//     (featureName, customerName, providerName, extraTags) plus an
 //     auto-generated per-call uuid
 //   - Removed asBaggage cross-process propagation (not needed yet)
 //   - Removed experiment framework keys
@@ -23,7 +23,7 @@ const { context: otelContext, trace, createContextKey } = require('@opentelemetr
 const WEFLAYR_METADATA_CONTEXT_KEY = createContextKey('weflayr_metadata');
 
 const FEATURE_NAME_ATTR = 'weflayr.feature_name';
-const CUSTOMER_ID_ATTR = 'weflayr.customer_id';
+const CUSTOMER_NAME_ATTR = 'weflayr.customer_name';
 const PROVIDER_NAME_ATTR = 'weflayr.provider_name';
 const UUID_ATTR = 'weflayr.uuid';
 // Prefix for user-supplied `extraTags` so downstream normalizers can pick
@@ -36,10 +36,10 @@ function getMergedMetadataFromContext(parentContext) {
   return existing && typeof existing === 'object' ? { ...existing } : {};
 }
 
-function _buildAttributes({ featureName, customerId, providerName, extraTags, spanUuid }) {
+function _buildAttributes({ featureName, customerName, providerName, extraTags, spanUuid }) {
   const attributes = {
     [FEATURE_NAME_ATTR]: featureName,
-    [CUSTOMER_ID_ATTR]: customerId,
+    [CUSTOMER_NAME_ATTR]: customerName,
     [UUID_ATTR]: spanUuid,
   };
   for (const [key, value] of Object.entries(extraTags)) {
@@ -63,25 +63,34 @@ function _buildAttributes({ featureName, customerId, providerName, extraTags, sp
  */
 function propagateMetadata(options, fn) {
   const { featureName, customerId } = options ?? {};
-  if (featureName == null || customerId == null) {
-    throw new Error('propagateMetadata: `featureName` and `customerId` are required');
+  let { customerName } = options ?? {};
+  if (customerId != null) {
+    process.emitWarning(
+      'propagateMetadata: `customerId` is deprecated, use `customerName`',
+      'DeprecationWarning'
+    );
+    customerName = customerName ?? customerId;
   }
+  if (featureName == null || customerName == null) {
+    throw new Error('propagateMetadata: `featureName` and `customerName` are required');
+  }
+  const normalizedOptions = { ...options, customerName };
 
   if (typeof fn === 'function') {
-    return _runWithMetadata(options, fn);
+    return _runWithMetadata(normalizedOptions, fn);
   }
 
   return function decorator(target, key, descriptor) {
     if (descriptor && typeof descriptor.value === 'function') {
       const original = descriptor.value;
       descriptor.value = function wrapped(...args) {
-        return _runWithMetadata(options, () => original.apply(this, args));
+        return _runWithMetadata(normalizedOptions, () => original.apply(this, args));
       };
       return descriptor;
     }
     if (typeof target === 'function') {
       return function wrapped(...args) {
-        return _runWithMetadata(options, () => target.apply(this, args));
+        return _runWithMetadata(normalizedOptions, () => target.apply(this, args));
       };
     }
     return target;
@@ -89,10 +98,10 @@ function propagateMetadata(options, fn) {
 }
 
 function _runWithMetadata(options, fn) {
-  const { featureName, customerId, providerName, extraTags } = options;
+  const { featureName, customerName, providerName, extraTags } = options;
   const attributes = _buildAttributes({
     featureName,
-    customerId,
+    customerName,
     providerName,
     extraTags: extraTags ?? {},
     spanUuid: randomUUID().replace(/-/g, ''),
@@ -117,7 +126,7 @@ module.exports = {
   getMergedMetadataFromContext,
   WEFLAYR_METADATA_CONTEXT_KEY,
   FEATURE_NAME_ATTR,
-  CUSTOMER_ID_ATTR,
+  CUSTOMER_NAME_ATTR,
   PROVIDER_NAME_ATTR,
   UUID_ATTR,
   EXTRA_TAG_PREFIX,

package/src/otel/span-processor.js

@@ -20,6 +20,10 @@ const { SpanStatusCode } = require('@opentelemetry/api');
 const { BatchSpanProcessor, SimpleSpanProcessor } = require('@opentelemetry/sdk-trace-base');
 const { EXTRA_TAG_PREFIX, getMergedMetadataFromContext } = require('./propagation');
 const { isDefaultExportSpan, isKnownLLMInstrumentor } = require('./span-filter');
+const {
+  VercelAiSdkSpanFilter,
+  stampVercelGatewayProviderName,
+} = require('./vercel-ai-sdk-span-filter');
 const { debug } = require('../logger');
 
 // setup({captureMessageContent: ...}) records the choice in this env var (the
@@ -57,6 +61,7 @@ class WeflayrSpanProcessor {
     this._defaultTags = defaultTags;
     this._mask = mask;
     this._shouldExportSpan = shouldExportSpan ?? isDefaultExportSpan;
+    this._vercelAiSdkSpanFilter = new VercelAiSdkSpanFilter();
     // LLM spans we've started but not yet seen end. On forceFlush we end any
     // leftovers with ERROR status — covers cases like openllmetry's anthropic
     // streaming wrapper, which leaks the span when the underlying call
@@ -75,6 +80,7 @@ class WeflayrSpanProcessor {
     if (isKnownLLMInstrumentor(span)) {
       this._openLlmSpans.add(span);
     }
+    this._vercelAiSdkSpanFilter.onStart(span);
     debug(
       'span start: name=%s defaultTags=%d propagatedMetadata=%d',
       span.name,
@@ -87,7 +93,11 @@ class WeflayrSpanProcessor {
   onEnd(span) {
     this._openLlmSpans.delete(span);
     try {
-      if (!this._shouldExportSpan(span)) {
+      const vercelVerdict = this._vercelAiSdkSpanFilter.shouldExport(span);
+      if (vercelVerdict === true) {
+        stampVercelGatewayProviderName(span);
+      }
+      if (vercelVerdict === false || (vercelVerdict === null && !this._shouldExportSpan(span))) {
         debug(
           'span end: filtered out name=%s scope=%s',
           span.name,

package/src/otel/vercel-ai-sdk-span-filter.js

@@ -0,0 +1,79 @@
+'use strict';
+
+// The Vercel AI SDK's OTel integrations emit aggregate spans around each model
+// call, all repeating the same usage counts:
+//   - `@ai-sdk/otel` (ai >= 7, scope "gen_ai"): per-call "chat" spans are
+//     wrapped in "agent_step" + "invoke_agent" spans, and embed/embedMany
+//     emits an outer "embeddings" operation span around the model-call
+//     "embeddings" span(s).
+//   - the legacy integration (ai <= 6, scope "ai"): `ai.<fn>.do<Call>` spans
+//     are wrapped in an outer `ai.<fn>` span.
+// Exactly one span per model call may reach the exporter — exporting an
+// aggregate alongside its children would bill every call twice.
+
+const VERCEL_SEMCONV_SCOPE = 'gen_ai';
+const VERCEL_LEGACY_SCOPE = 'ai';
+
+const LEGACY_MODEL_CALL_SPAN_NAME = /\.do(Generate|Stream|Embed)$/;
+
+function _parentSpanId(span) {
+  return span.parentSpanContext?.spanId ?? span.parentSpanId;
+}
+
+class VercelAiSdkSpanFilter {
+  constructor() {
+    // spanId -> gen_ai.operation.name for open "gen_ai"-scope spans, so a
+    // span can check what its parent is (children end before their parent).
+    this._openSpanOperations = new Map();
+  }
+
+  onStart(span) {
+    if (span.instrumentationScope?.name !== VERCEL_SEMCONV_SCOPE) return;
+    this._openSpanOperations.set(
+      span.spanContext().spanId,
+      span.attributes['gen_ai.operation.name']
+    );
+  }
+
+  /**
+   * Export verdict for a Vercel AI SDK span, or null when the span is not
+   * one (the caller falls back to the default filter).
+   */
+  shouldExport(span) {
+    const scope = span.instrumentationScope?.name;
+    if (scope === VERCEL_LEGACY_SCOPE) {
+      return LEGACY_MODEL_CALL_SPAN_NAME.test(span.name);
+    }
+    if (scope !== VERCEL_SEMCONV_SCOPE) {
+      return null;
+    }
+    const operation = span.attributes['gen_ai.operation.name'];
+    this._openSpanOperations.delete(span.spanContext().spanId);
+    if (operation === 'chat') {
+      return true;
+    }
+    if (operation === 'embeddings') {
+      // Keep the outer aggregate (one event per embed/embedMany call, with the
+      // total usage) and drop the nested model-call span(s) repeating it.
+      return this._openSpanOperations.get(_parentSpanId(span)) !== 'embeddings';
+    }
+    // invoke_agent / agent_step (usage aggregates) and execute_tool (no usage).
+    return false;
+  }
+}
+
+// `@ai-sdk/otel` reports the Vercel AI Gateway as the bare provider id
+// "gateway" — too generic a name to special-case downstream. Stamp the weflayr
+// provider override (which the normalizer prefers) with the canonical name.
+// A providerName set through propagateMetadata was stamped at span start and
+// wins.
+function stampVercelGatewayProviderName(span) {
+  if (
+    span.attributes['gen_ai.provider.name'] === 'gateway' &&
+    span.attributes['weflayr.provider_name'] === undefined
+  ) {
+    span.attributes['weflayr.provider_name'] = 'vercel_ai_gateway';
+  }
+}
+
+module.exports = { VercelAiSdkSpanFilter, stampVercelGatewayProviderName };