weflayr 0.21.0 → 0.22.1

package/src/instrumentation/openai/get_embeddings_telemetry.js

@@ -60,6 +60,18 @@ class OpenAIEmbeddingsInstrumentor {
       if (body && body.model) {
         span.setAttribute('gen_ai.request.model', body.model);
       }
+      // One user message per input element, matching the shape the chat
+      // instrumentors emit. The span processor strips it when message-content
+      // capture is disabled.
+      if (body && body.input != null) {
+        const inputs = Array.isArray(body.input) ? body.input : [body.input];
+        span.setAttribute(
+          'gen_ai.input.messages',
+          JSON.stringify(
+            inputs.map((content) => ({ role: 'user', parts: [{ type: 'text', content }] }))
+          )
+        );
+      }
       return Promise.resolve(original.call(this, body, ...rest)).then(
         (response) => {
           if (response && response.model) {

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/exporter.js

@@ -77,7 +77,6 @@ function buildExporter({
   });
   const originalExport = exporter.export.bind(exporter);
   const wrappedExport = _exportWithRetry(originalExport, { maxRetries, maxRetryMs });
-  let warned = false;
   exporter.export = (spans, resultCallback) => {
     const start = Date.now();
     debug('exporter.export: posting count=%d', spans.length);
@@ -93,11 +92,7 @@ function buildExporter({
           result?.code,
           result?.error?.message || result?.error || '(none)'
         );
-        // Surface the first failure on stderr so users notice broken setups
-        // even without NODE_DEBUG=weflayr. Stay quiet after — repeated warns
-        // on a misconfigured key would just spam.
-        if (warnOnExportError && !warned) {
-          warned = true;
+        if (warnOnExportError) {
           // console.warn writes to stderr synchronously. process.emitWarning
           // is queued for the next tick, so a caller doing process.exit() from
           // their error handler races past it and the warning is lost.

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,8 +20,35 @@ 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
+// official OTel GenAI one). Instrumentors gate content on their own knobs
+// (openllmetry reads its own config and captures by default), so the processor
+// enforces the flag itself: when the env var is "false", message content is
+// stripped from every span before export.
+const CONTENT_CAPTURE_ENV = 'OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT';
+
+// The new-semconv JSON message attributes and the legacy indexed
+// `gen_ai.prompt.{i}.*` / `gen_ai.completion.{i}.*` attributes.
+const CONTENT_ATTRIBUTES = [
+  'gen_ai.input.messages',
+  'gen_ai.output.messages',
+  'gen_ai.system_instructions',
+];
+const CONTENT_ATTRIBUTE_PREFIXES = ['gen_ai.prompt.', 'gen_ai.completion.'];
+
+function _isContentAttribute(key) {
+  return (
+    CONTENT_ATTRIBUTES.includes(key) ||
+    CONTENT_ATTRIBUTE_PREFIXES.some((prefix) => key.startsWith(prefix))
+  );
+}
+
 class WeflayrSpanProcessor {
   constructor({ exporter, exportMode = 'batch', defaultTags = {}, mask, shouldExportSpan } = {}) {
     if (!exporter) {
@@ -34,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
@@ -52,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,
@@ -64,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,
@@ -77,6 +110,12 @@ class WeflayrSpanProcessor {
     }
     debug('span end: exporting name=%s scope=%s', span.name, span.instrumentationScope?.name);
 
+    if ((process.env[CONTENT_CAPTURE_ENV] || '').toLowerCase() === 'false') {
+      for (const key of Object.keys(span.attributes)) {
+        if (_isContentAttribute(key)) delete span.attributes[key];
+      }
+    }
+
     if (this._mask) {
       try {
         const masked = this._mask(span.attributes);
@@ -120,4 +159,4 @@ class WeflayrSpanProcessor {
   }
 }
 
-module.exports = { WeflayrSpanProcessor };
+module.exports = { CONTENT_CAPTURE_ENV, WeflayrSpanProcessor };

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 };

package/src/setup.js

@@ -5,13 +5,12 @@ const { NodeTracerProvider } = require('@opentelemetry/sdk-trace-node');
 const { resourceFromAttributes } = require('@opentelemetry/resources');
 
 const { buildExporter } = require('./otel/exporter');
-const { WeflayrSpanProcessor } = require('./otel/span-processor');
+const { CONTENT_CAPTURE_ENV, WeflayrSpanProcessor } = require('./otel/span-processor');
 const { debug } = require('./logger');
 const { version: SDK_VERSION } = require('../package.json');
 
 const SDK_LANGUAGE = 'javascript';
 const DEFAULT_BASE_URL = 'https://api.weflayr.com';
-const CONTENT_CAPTURE_ENV = 'OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT';
 
 const _state = {
   tracerProvider: null,

package/tests/api/index.test.js

@@ -0,0 +1,330 @@
+'use strict';
+
+// Tests for the public-API client: auth and base-URL wiring of the
+// client facade, plus the request/response wiring of every generated
+// endpoint (server behavior is covered by the dashboard's app_api tests).
+
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const http = require('node:http');
+
+const weflayr = require('../../src/index');
+const { api } = weflayr;
+
+// A client whose server records requests and returns a canned response.
+async function withClientReturning(responseBody, statusCode, run, clientOptions = {}) {
+  const seenRequests = [];
+  const server = http.createServer((request, response) => {
+    let requestBody = '';
+    request.on('data', (chunk) => {
+      requestBody += chunk;
+    });
+    request.on('end', () => {
+      seenRequests.push({
+        method: request.method,
+        url: request.url,
+        authorization: request.headers.authorization,
+        body: requestBody === '' ? null : JSON.parse(requestBody),
+      });
+      response.statusCode = statusCode;
+      response.setHeader('content-type', 'application/json');
+      response.end(JSON.stringify(responseBody));
+    });
+  });
+  await new Promise((resolve) => server.listen(0, resolve));
+  const client = api.client({
+    apiKey: 'wf-test-key',
+    ...clientOptions,
+    baseUrl: `http://127.0.0.1:${server.address().port}/api`,
+  });
+  try {
+    await run(client, seenRequests);
+  } finally {
+    server.close();
+  }
+}
+
+// ── client facade ─────────────────────────────────────────────────────────
+
+test('client sends the bearer key to the configured host', async () => {
+  await withClientReturning({ rows: [] }, 200, async (client, seenRequests) => {
+    const { data } = await api.getAllRevenue({ client, throwOnError: true });
+    assert.deepEqual(data, { rows: [] });
+    assert.deepEqual(seenRequests, [
+      { method: 'GET', url: '/api/revenue/', authorization: 'Bearer wf-test-key', body: null },
+    ]);
+  });
+});
+
+test('weflayr.client is the same function as api.client', () => {
+  assert.equal(weflayr.client, api.client);
+});
+
+test('client defaults to the production API host', () => {
+  const client = api.client({ apiKey: 'wf-test-key' });
+  assert.equal(client.getConfig().baseUrl, 'https://app.weflayr.com/api');
+});
+
+test('client throws without apiKey', () => {
+  const saved = process.env.WEFLAYR_API_KEY;
+  delete process.env.WEFLAYR_API_KEY;
+  try {
+    assert.throws(() => api.client(), /apiKey/);
+  } finally {
+    if (saved !== undefined) process.env.WEFLAYR_API_KEY = saved;
+  }
+});
+
+test('client picks up apiKey from WEFLAYR_API_KEY env var', async () => {
+  process.env.WEFLAYR_API_KEY = 'env-key';
+  try {
+    await withClientReturning(
+      { rows: [] },
+      200,
+      async (client, seenRequests) => {
+        await api.getAllRevenue({ client, throwOnError: true });
+        assert.equal(seenRequests[0].authorization, 'Bearer env-key');
+      },
+      { apiKey: undefined }
+    );
+  } finally {
+    delete process.env.WEFLAYR_API_KEY;
+  }
+});
+
+// ── Revenue ───────────────────────────────────────────────────────────────────
+
+test('setRevenue posts the rows in snake_case and parses the booked count', async () => {
+  await withClientReturning({ ok: true, rows_inserted: 2 }, 200, async (client, seenRequests) => {
+    const rows = [
+      { customerName: 'c_1', amount: '1200.50', month: '2026-06' },
+      { customerName: 'c_2', amount: '800', month: '2026-06' },
+    ];
+    const { data } = await api.setRevenue({ client, throwOnError: true, body: { rows } });
+    assert.deepEqual(data, { ok: true, rowsInserted: 2 });
+    const request = seenRequests[0];
+    assert.equal(request.method, 'POST');
+    assert.equal(request.url, '/api/revenue/');
+    assert.deepEqual(request.body, {
+      rows: [
+        { customer_name: 'c_1', amount: '1200.50', month: '2026-06' },
+        { customer_name: 'c_2', amount: '800', month: '2026-06' },
+      ],
+    });
+  });
+});
+
+test('getAllRevenue parses the returned rows into camelCase', async () => {
+  const wireRow = {
+    customer_name: 'c_1',
+    metric_name: 'revenue',
+    month: '2026-06',
+    amount: '1200.50000000',
+    source: 'api',
+  };
+  await withClientReturning({ rows: [wireRow] }, 200, async (client) => {
+    const { data } = await api.getAllRevenue({ client, throwOnError: true });
+    assert.deepEqual(data.rows, [
+      {
+        customerName: 'c_1',
+        metricName: 'revenue',
+        month: '2026-06',
+        amount: '1200.50000000',
+        source: 'api',
+      },
+    ]);
+  });
+});
+
+test('getCustomerRevenue requests the customer path', async () => {
+  await withClientReturning({ rows: [] }, 200, async (client, seenRequests) => {
+    const { data } = await api.getCustomerRevenue({
+      client,
+      throwOnError: true,
+      path: { customerName: 'c_1' },
+    });
+    assert.deepEqual(data, { rows: [] });
+    assert.equal(seenRequests[0].url, '/api/revenue/c_1/');
+  });
+});
+
+test('getCustomerRevenue surfaces a 404 and its error', async () => {
+  const rejection = { error: 'No revenue for this customer.' };
+  await withClientReturning(rejection, 404, async (client) => {
+    const { error, response } = await api.getCustomerRevenue({
+      client,
+      path: { customerName: 'nobody' },
+    });
+    assert.equal(response.status, 404);
+    assert.deepEqual(error, rejection);
+  });
+});
+
+test('deleteCustomerRevenue parses the deleted count', async () => {
+  await withClientReturning({ ok: true, rows_deleted: 1 }, 200, async (client, seenRequests) => {
+    const { data } = await api.deleteCustomerRevenue({
+      client,
+      throwOnError: true,
+      path: { customerName: 'c_1' },
+    });
+    assert.deepEqual(data, { ok: true, rowsDeleted: 1 });
+    const request = seenRequests[0];
+    assert.equal(request.method, 'DELETE');
+    assert.equal(request.url, '/api/revenue/c_1/');
+  });
+});
+
+// ── Key metrics ───────────────────────────────────────────────────────────────
+
+test('setKeyMetrics posts the rows in snake_case and parses the booked count', async () => {
+  await withClientReturning({ ok: true, rows_inserted: 1 }, 200, async (client, seenRequests) => {
+    const rows = [
+      { userName: 'u_1', metricName: 'Meetings booked', amount: '3', month: '2026-06' },
+    ];
+    const { data } = await api.setKeyMetrics({ client, throwOnError: true, body: { rows } });
+    assert.deepEqual(data, { ok: true, rowsInserted: 1 });
+    const request = seenRequests[0];
+    assert.equal(request.method, 'POST');
+    assert.equal(request.url, '/api/key-metrics/');
+    assert.deepEqual(request.body, {
+      rows: [{ user_name: 'u_1', metric_name: 'Meetings booked', amount: '3', month: '2026-06' }],
+    });
+  });
+});
+
+test('getAllKeyMetrics parses the returned rows into camelCase', async () => {
+  const wireRow = {
+    user_name: 'u_1',
+    metric_name: 'Meetings booked',
+    month: '2026-06',
+    amount: '3.00000000',
+    source: 'api',
+  };
+  await withClientReturning({ rows: [wireRow] }, 200, async (client) => {
+    const { data } = await api.getAllKeyMetrics({ client, throwOnError: true });
+    assert.deepEqual(data.rows, [
+      {
+        userName: 'u_1',
+        metricName: 'Meetings booked',
+        month: '2026-06',
+        amount: '3.00000000',
+        source: 'api',
+      },
+    ]);
+  });
+});
+
+test('getUserKeyMetrics requests the user path', async () => {
+  await withClientReturning({ rows: [] }, 200, async (client, seenRequests) => {
+    const { data } = await api.getUserKeyMetrics({
+      client,
+      throwOnError: true,
+      path: { userName: 'u_1' },
+    });
+    assert.deepEqual(data, { rows: [] });
+    assert.equal(seenRequests[0].url, '/api/key-metrics/u_1/');
+  });
+});
+
+test('setKeyMetrics surfaces a 422 and its details', async () => {
+  const rejection = {
+    error: 'Invalid payload.',
+    detail: [{ field: 'rows.0.metric_name', error: 'Unknown metric.' }],
+  };
+  await withClientReturning(rejection, 422, async (client) => {
+    const { error, response } = await api.setKeyMetrics({ client, body: { rows: [] } });
+    assert.equal(response.status, 422);
+    assert.deepEqual(error, rejection);
+  });
+});
+
+test('deleteUserKeyMetrics parses the deleted count', async () => {
+  await withClientReturning({ ok: true, rows_deleted: 1 }, 200, async (client, seenRequests) => {
+    const { data } = await api.deleteUserKeyMetrics({
+      client,
+      throwOnError: true,
+      path: { userName: 'u_1' },
+    });
+    assert.deepEqual(data, { ok: true, rowsDeleted: 1 });
+    const request = seenRequests[0];
+    assert.equal(request.method, 'DELETE');
+    assert.equal(request.url, '/api/key-metrics/u_1/');
+  });
+});
+
+// ── Customer tags ─────────────────────────────────────────────────────────────
+
+test('setCustomersTags posts the customers in snake_case and parses the updated count', async () => {
+  await withClientReturning(
+    { ok: true, customers_updated: 1 },
+    200,
+    async (client, seenRequests) => {
+      const customers = [{ customerName: 'c_1', tags: { plan: 'pro' } }];
+      const { data } = await api.setCustomersTags({
+        client,
+        throwOnError: true,
+        body: { customers },
+      });
+      assert.deepEqual(data, { ok: true, customersUpdated: 1 });
+      const request = seenRequests[0];
+      assert.equal(request.method, 'POST');
+      assert.equal(request.url, '/api/customer-tags/');
+      assert.deepEqual(request.body, {
+        customers: [{ customer_name: 'c_1', tags: { plan: 'pro' } }],
+      });
+    }
+  );
+});
+
+test('setCustomersTags leaves tag keys untouched, even when they contain underscores', async () => {
+  await withClientReturning(
+    { ok: true, customers_updated: 1 },
+    200,
+    async (client, seenRequests) => {
+      const customers = [{ customerName: 'c_1', tags: { utm_source: 'ads', plan_tier: 'pro' } }];
+      await api.setCustomersTags({ client, throwOnError: true, body: { customers } });
+      assert.deepEqual(seenRequests[0].body, {
+        customers: [{ customer_name: 'c_1', tags: { utm_source: 'ads', plan_tier: 'pro' } }],
+      });
+    }
+  );
+});
+
+test('getAllCustomersTags parses the returned customers into camelCase', async () => {
+  const wireCustomer = { customer_name: 'c_1', tags: { plan: 'pro' } };
+  await withClientReturning(
+    { customers: [wireCustomer], next_cursor: null, has_more: false },
+    200,
+    async (client) => {
+      const { data } = await api.getAllCustomersTags({ client, throwOnError: true });
+      assert.deepEqual(data.customers, [{ customerName: 'c_1', tags: { plan: 'pro' } }]);
+    }
+  );
+});
+
+test('getCustomerTags parses the customer tags, leaving tag keys untouched', async () => {
+  const wireTags = { customer_name: 'c_1', tags: { plan: 'pro', utm_source: 'ads' } };
+  await withClientReturning(wireTags, 200, async (client, seenRequests) => {
+    const { data } = await api.getCustomerTags({
+      client,
+      throwOnError: true,
+      path: { customerName: 'c_1' },
+    });
+    assert.deepEqual(data, { customerName: 'c_1', tags: { plan: 'pro', utm_source: 'ads' } });
+    assert.equal(seenRequests[0].url, '/api/customer-tags/c_1/');
+  });
+});
+
+test('deleteCustomerTags parses the deleted count', async () => {
+  await withClientReturning({ ok: true, tags_deleted: 1 }, 200, async (client, seenRequests) => {
+    const { data } = await api.deleteCustomerTags({
+      client,
+      throwOnError: true,
+      path: { customerName: 'c_1' },
+    });
+    assert.deepEqual(data, { ok: true, tagsDeleted: 1 });
+    const request = seenRequests[0];
+    assert.equal(request.method, 'DELETE');
+    assert.equal(request.url, '/api/customer-tags/c_1/');
+  });
+});