@salesforce/b2c-tooling-sdk 1.18.0 → 1.19.1

package/dist/esm/operations/metrics/index.js

@@ -0,0 +1,478 @@
+import { toOrganizationId } from '../../clients/custom-apis.js';
+import { getApiErrorMessage } from '../../clients/error-utils.js';
+import { getLogger } from '../../logging/logger.js';
+import { parseSinceTime, parseRelativeTime } from '../logs/filter.js';
+/**
+ * All metric categories exposed by the Metrics API, in a stable, documented order.
+ *
+ * Values match the API path segments (e.g. `overall` → `/metrics/overall`).
+ */
+export const METRIC_CATEGORIES = [
+    'overall',
+    'sales',
+    'ecdn',
+    'third-party',
+    'scapi',
+    'scapi-hooks',
+    'mrt',
+    'controller',
+    'ocapi',
+];
+/**
+ * How far back the Metrics API retains data: `from` must be no older than
+ * `serverNow - 30 days`, or the API returns 400.
+ */
+export const METRICS_RETENTION_MS = 30 * 24 * 60 * 60 * 1000;
+/**
+ * Default (and maximum) width of a metrics time window: 24 hours.
+ *
+ * The Metrics API pairs a request that omits `to` with its own `now` and then
+ * enforces a maximum window of `to - from ≤ 24h`, rejecting anything wider with a
+ * 400. An open-ended `from` older than 24h therefore always fails. To make the
+ * behavior predictable, {@link resolveMetricsWindow} fills in a 24-hour window
+ * (clamped so `to` never exceeds `now`) for any bound the caller leaves open, and
+ * always sends both `from` and `to`. This is only a *default* for derivation — an
+ * explicit `from`+`to` range wider than 24h is still sent as-is, letting the API
+ * remain authoritative and return its own error.
+ */
+export const METRICS_DEFAULT_WINDOW_MS = 24 * 60 * 60 * 1000;
+/**
+ * Safety margin kept *inside* the retention window when clamping `from`. Because
+ * the server evaluates retention against its own clock at request time, a `from`
+ * computed as exactly "30 days ago" on the client is reliably rejected once
+ * request latency and client/server clock skew are added. {@link resolveMetricsWindow}
+ * therefore clamps a `from` that lands within this margin of the retention floor
+ * up to `now - 30 days + margin`, so edge requests (e.g. `--from 30d`) succeed.
+ * 5 minutes comfortably covers latency and typical skew while costing a
+ * negligible fraction of the 30-day window.
+ */
+export const METRICS_RETENTION_SAFETY_MARGIN_MS = 5 * 60 * 1000;
+/**
+ * Parses a single metrics time bound (`from` or `to`) into a {@link Date}.
+ *
+ * This is the shared bound parser for the CLI `metrics get` command and the MCP
+ * `metrics_get` tool. It resolves a single bound in isolation; deriving the
+ * companion bound and applying the 24-hour default window is the job of
+ * {@link resolveMetricsWindow}.
+ *
+ * @param value - The bound: a Date, epoch milliseconds, a relative duration
+ *   (`5m`/`1h`/`2d`, relative to `now`), or an ISO 8601 timestamp
+ * @param now - Reference time for relative durations (defaults to the current
+ *   time; injectable for deterministic tests)
+ * @returns The resolved {@link Date}
+ * @throws TypeError if a string value is neither a valid relative duration nor
+ *   a parseable ISO 8601 timestamp
+ *
+ * @example
+ * ```typescript
+ * const from = parseMetricsBound('2d');            // 2 days ago
+ * const to = parseMetricsBound('2026-01-25T12:00:00Z');
+ * await getSalesMetrics(client, tenantId, {from, to});
+ * ```
+ */
+export function parseMetricsBound(value, now = new Date()) {
+    if (value instanceof Date)
+        return value;
+    if (typeof value === 'number')
+        return new Date(value);
+    return parseSinceTime(value, now);
+}
+/**
+ * Parses a `--window`/`--for` duration into milliseconds. Accepts a relative
+ * string (`1h`, `30m`, `2d`) or a raw number of milliseconds.
+ *
+ * @throws TypeError if a string is not a valid relative duration
+ */
+function parseWindowMs(window) {
+    if (typeof window === 'number')
+        return window;
+    const ms = parseRelativeTime(window);
+    if (ms === null) {
+        throw new TypeError(`Invalid window duration: "${window}". Use a relative duration like "30m", "1h", or "2d".`);
+    }
+    return ms;
+}
+/**
+ * Resolves `from`/`to`/`window` inputs into the concrete bounds to send to the
+ * Metrics API. This is the shared resolver for the CLI `metrics get` command and
+ * the MCP `metrics_get` tool, so both share identical, tested semantics.
+ *
+ * The resolver always produces an explicit `from`+`to` pair. The Metrics API
+ * pairs a request that omits `to` with its own `now` and enforces a 24-hour
+ * maximum window, so an open-ended `from` older than 24 hours always fails; to
+ * make the behavior predictable, any bound the caller leaves open is filled from
+ * the 24-hour default window (see {@link METRICS_DEFAULT_WINDOW_MS}) rather than
+ * relying on the server's implicit end.
+ *
+ * The `window` duration makes fixed-width lookbacks easy without hand-computing
+ * a second timestamp — e.g. "a 1-hour window starting 7 days ago" is
+ * `{from: '7d', window: '1h'}`. Resolution rules:
+ *
+ * - `from` + `to` — used as given; `window` must NOT also be set. An explicit
+ *   range wider than the 24-hour maximum is still sent as-is, leaving the API to
+ *   return its own error.
+ * - `from` + `window` — `to = from + window`.
+ * - `to` + `window` — `from = to - window`.
+ * - `window` only — the last `window`: `to = now`, `from = now - window`.
+ * - `from` only — a 24-hour window forward from `from`: `to = min(from + 24h, now)`.
+ * - `to` only — a 24-hour window back from `to`: `from = to - 24h`.
+ * - nothing — the last 24 hours: `to = now`, `from = now - 24h`.
+ *
+ * Bounds filled from the 24-hour default (the last three rules) set
+ * {@link ResolvedMetricsWindow.defaultedWindow}. Validation is structural
+ * (over-specification and `from` after `to`). Additionally, a `from` that lands
+ * at or beyond the 30-day retention floor is clamped *forward* to
+ * `now - 30 days + margin` (see {@link METRICS_RETENTION_SAFETY_MARGIN_MS}) so
+ * requests like `--from 30d` are not rejected by the server's own slightly-later
+ * clock; the clamp is applied before deriving the companion bound so the window
+ * width is preserved, only ever moves `from` toward `now`, and is reported via
+ * {@link ResolvedMetricsWindow.clampedFrom}.
+ *
+ * @param input - The raw `from`/`to`/`window` inputs
+ * @param now - Reference time for relative bounds, default/window modes, and the
+ *   retention clamp (defaults to the current time; injectable for deterministic tests)
+ * @returns The resolved bounds plus ISO/epoch-second echoes and clamp/default flags
+ * @throws TypeError if a bound or the window string is unparseable
+ * @throws RangeError if all three are supplied, or the resolved `from` is after `to`
+ *
+ * @example
+ * ```typescript
+ * // A 1-hour window starting 7 days ago:
+ * const w = resolveMetricsWindow({from: '7d', window: '1h'});
+ * await getScapiMetrics(client, tenantId, {from: w.from, to: w.to});
+ * ```
+ */
+export function resolveMetricsWindow(input = {}, now = new Date()) {
+    const hasFrom = input.from !== undefined && input.from !== '';
+    const hasTo = input.to !== undefined && input.to !== '';
+    const hasWindow = input.window !== undefined && input.window !== '';
+    if (hasFrom && hasTo && hasWindow) {
+        throw new RangeError('Specify at most two of from, to, and window — not all three.');
+    }
+    // Clamp a `from` forward if it predates the retention floor, to survive the
+    // server evaluating retention against its own (slightly later) clock. Only
+    // ever moves `from` toward `now`, never fetches out-of-range data.
+    const earliestSafe = now.getTime() - METRICS_RETENTION_MS + METRICS_RETENTION_SAFETY_MARGIN_MS;
+    let clampedFrom = false;
+    const clampFrom = (d) => {
+        if (d.getTime() < earliestSafe) {
+            clampedFrom = true;
+            return new Date(earliestSafe);
+        }
+        return d;
+    };
+    // Clamp a provided `from` up front so a window derived from it stays inside
+    // retention (and a full-width window fits).
+    let from = hasFrom ? clampFrom(parseMetricsBound(input.from, now)) : undefined;
+    let to = hasTo ? parseMetricsBound(input.to, now) : undefined;
+    let defaultedWindow = false;
+    if (hasWindow) {
+        const windowMs = parseWindowMs(input.window);
+        if (from && !to) {
+            to = new Date(from.getTime() + windowMs);
+        }
+        else if (to && !from) {
+            from = new Date(to.getTime() - windowMs);
+        }
+        else {
+            // window alone → the last {window}
+            to = now;
+            from = new Date(now.getTime() - windowMs);
+        }
+    }
+    else if (!(from && to)) {
+        // No explicit window and at least one bound open → fill it from the 24-hour
+        // default window, sending an explicit range instead of relying on the
+        // server's implicit `to = now` + 24h-maximum behavior.
+        defaultedWindow = true;
+        if (from && !to) {
+            // A window forward from `from`, but never past `now` (no future data).
+            to = new Date(Math.min(from.getTime() + METRICS_DEFAULT_WINDOW_MS, now.getTime()));
+        }
+        else if (to && !from) {
+            from = new Date(to.getTime() - METRICS_DEFAULT_WINDOW_MS);
+        }
+        else {
+            // Nothing supplied → the last 24 hours.
+            to = now;
+            from = new Date(now.getTime() - METRICS_DEFAULT_WINDOW_MS);
+        }
+    }
+    // A `from` derived from `to` (via window or the default) may itself predate
+    // retention; clamp it forward too. Idempotent for an already-clamped bound.
+    from = clampFrom(from);
+    if (from.getTime() > to.getTime()) {
+        throw new RangeError(`Invalid time window: from (${from.toISOString()}) must be before to (${to.toISOString()}).`);
+    }
+    return {
+        from: from,
+        to: to,
+        fromIso: from.toISOString(),
+        toIso: to.toISOString(),
+        fromEpochSeconds: toEpochSeconds(from),
+        toEpochSeconds: toEpochSeconds(to),
+        clampedFrom,
+        defaultedWindow,
+    };
+}
+/**
+ * Converts a millisecond time input ({@link Date} or epoch ms) to the epoch
+ * **seconds** the Metrics API expects on the wire.
+ */
+function toEpochSeconds(value) {
+    const ms = value instanceof Date ? value.getTime() : value;
+    return Math.floor(ms / 1000);
+}
+/**
+ * Normalizes an optional time-window into the query object openapi-fetch expects.
+ * Converts millisecond inputs to epoch seconds and drops undefined values so they
+ * are not serialized.
+ */
+function timeWindowQuery(options) {
+    const query = {};
+    if (options?.from !== undefined)
+        query.from = toEpochSeconds(options.from);
+    if (options?.to !== undefined)
+        query.to = toEpochSeconds(options.to);
+    return query;
+}
+/**
+ * Normalizes a successful metrics response for JS consumers: rewrites every data
+ * point timestamp from the API's epoch **seconds** to epoch **milliseconds** so
+ * that `new Date(point.timestamp)` yields the correct instant. Returns a new
+ * response object; the input is not mutated.
+ */
+function normalizeResponse(data) {
+    return {
+        ...data,
+        data: (data.data ?? []).map((metric) => ({
+            ...metric,
+            dataSeries: (metric.dataSeries ?? []).map((series) => ({
+                ...series,
+                data: (series.data ?? []).map((point) => ({ ...point, timestamp: point.timestamp * 1000 })),
+            })),
+        })),
+    };
+}
+/**
+ * Wraps a failed metrics request in a descriptive Error.
+ */
+function metricsError(category, error, response) {
+    return new Error(`Failed to get ${category} metrics: ${getApiErrorMessage(error, response)}`, { cause: error });
+}
+/**
+ * Retrieves overall application metrics for an organization.
+ *
+ * @param client - Metrics API client from {@link createMetricsClient}
+ * @param tenantId - Tenant ID (with or without the `f_ecom_` prefix)
+ * @param options - Optional time window (epoch milliseconds)
+ * @returns The metrics data response
+ * @throws Error if the request fails
+ */
+export async function getOverallMetrics(client, tenantId, options) {
+    getLogger().debug({ tenantId, options }, 'Fetching overall metrics');
+    const { data, error, response } = await client.GET('/organizations/{organizationId}/metrics/overall', {
+        params: { path: { organizationId: toOrganizationId(tenantId) }, query: timeWindowQuery(options) },
+    });
+    if (error || !data)
+        throw metricsError('overall', error, response);
+    return normalizeResponse(data);
+}
+/**
+ * Retrieves sales metrics for an organization.
+ *
+ * @param client - Metrics API client from {@link createMetricsClient}
+ * @param tenantId - Tenant ID (with or without the `f_ecom_` prefix)
+ * @param options - Optional time window (epoch milliseconds)
+ * @returns The metrics data response
+ * @throws Error if the request fails
+ */
+export async function getSalesMetrics(client, tenantId, options) {
+    getLogger().debug({ tenantId, options }, 'Fetching sales metrics');
+    const { data, error, response } = await client.GET('/organizations/{organizationId}/metrics/sales', {
+        params: { path: { organizationId: toOrganizationId(tenantId) }, query: timeWindowQuery(options) },
+    });
+    if (error || !data)
+        throw metricsError('sales', error, response);
+    return normalizeResponse(data);
+}
+/**
+ * Retrieves embedded CDN (eCDN) metrics for an organization.
+ *
+ * @param client - Metrics API client from {@link createMetricsClient}
+ * @param tenantId - Tenant ID (with or without the `f_ecom_` prefix)
+ * @param options - Optional time window (epoch milliseconds)
+ * @returns The metrics data response
+ * @throws Error if the request fails
+ */
+export async function getEcdnMetrics(client, tenantId, options) {
+    getLogger().debug({ tenantId, options }, 'Fetching ecdn metrics');
+    const { data, error, response } = await client.GET('/organizations/{organizationId}/metrics/ecdn', {
+        params: { path: { organizationId: toOrganizationId(tenantId) }, query: timeWindowQuery(options) },
+    });
+    if (error || !data)
+        throw metricsError('ecdn', error, response);
+    return normalizeResponse(data);
+}
+/**
+ * Retrieves third-party service call metrics for an organization.
+ *
+ * @param client - Metrics API client from {@link createMetricsClient}
+ * @param tenantId - Tenant ID (with or without the `f_ecom_` prefix)
+ * @param options - Optional time window and `thirdPartyServiceId` filter
+ * @returns The metrics data response
+ * @throws Error if the request fails
+ */
+export async function getThirdPartyMetrics(client, tenantId, options) {
+    getLogger().debug({ tenantId, options }, 'Fetching third-party metrics');
+    const { data, error, response } = await client.GET('/organizations/{organizationId}/metrics/third-party', {
+        params: {
+            path: { organizationId: toOrganizationId(tenantId) },
+            query: { ...timeWindowQuery(options), thirdPartyServiceId: options?.thirdPartyServiceId },
+        },
+    });
+    if (error || !data)
+        throw metricsError('third-party', error, response);
+    return normalizeResponse(data);
+}
+/**
+ * Retrieves SCAPI request metrics for an organization.
+ *
+ * @param client - Metrics API client from {@link createMetricsClient}
+ * @param tenantId - Tenant ID (with or without the `f_ecom_` prefix)
+ * @param options - Optional time window and `apiFamily`/`apiName` filters
+ * @returns The metrics data response
+ * @throws Error if the request fails
+ */
+export async function getScapiMetrics(client, tenantId, options) {
+    getLogger().debug({ tenantId, options }, 'Fetching scapi metrics');
+    const { data, error, response } = await client.GET('/organizations/{organizationId}/metrics/scapi', {
+        params: {
+            path: { organizationId: toOrganizationId(tenantId) },
+            query: { ...timeWindowQuery(options), apiFamily: options?.apiFamily, apiName: options?.apiName },
+        },
+    });
+    if (error || !data)
+        throw metricsError('scapi', error, response);
+    return normalizeResponse(data);
+}
+/**
+ * Retrieves SCAPI hook execution metrics for an organization.
+ *
+ * @param client - Metrics API client from {@link createMetricsClient}
+ * @param tenantId - Tenant ID (with or without the `f_ecom_` prefix)
+ * @param options - Optional time window (epoch milliseconds)
+ * @returns The metrics data response
+ * @throws Error if the request fails
+ */
+export async function getScapiHooksMetrics(client, tenantId, options) {
+    getLogger().debug({ tenantId, options }, 'Fetching scapi-hooks metrics');
+    const { data, error, response } = await client.GET('/organizations/{organizationId}/metrics/scapi-hooks', {
+        params: { path: { organizationId: toOrganizationId(tenantId) }, query: timeWindowQuery(options) },
+    });
+    if (error || !data)
+        throw metricsError('scapi-hooks', error, response);
+    return normalizeResponse(data);
+}
+/**
+ * Retrieves Managed Runtime (MRT) metrics for an organization.
+ *
+ * @param client - Metrics API client from {@link createMetricsClient}
+ * @param tenantId - Tenant ID (with or without the `f_ecom_` prefix)
+ * @param options - Optional time window (epoch milliseconds)
+ * @returns The metrics data response
+ * @throws Error if the request fails
+ */
+export async function getMrtMetrics(client, tenantId, options) {
+    getLogger().debug({ tenantId, options }, 'Fetching mrt metrics');
+    const { data, error, response } = await client.GET('/organizations/{organizationId}/metrics/mrt', {
+        params: { path: { organizationId: toOrganizationId(tenantId) }, query: timeWindowQuery(options) },
+    });
+    if (error || !data)
+        throw metricsError('mrt', error, response);
+    return normalizeResponse(data);
+}
+/**
+ * Retrieves controller/pipeline metrics for an organization.
+ *
+ * @param client - Metrics API client from {@link createMetricsClient}
+ * @param tenantId - Tenant ID (with or without the `f_ecom_` prefix)
+ * @param options - Optional time window (epoch milliseconds)
+ * @returns The metrics data response
+ * @throws Error if the request fails
+ */
+export async function getControllerMetrics(client, tenantId, options) {
+    getLogger().debug({ tenantId, options }, 'Fetching controller metrics');
+    const { data, error, response } = await client.GET('/organizations/{organizationId}/metrics/controller', {
+        params: { path: { organizationId: toOrganizationId(tenantId) }, query: timeWindowQuery(options) },
+    });
+    if (error || !data)
+        throw metricsError('controller', error, response);
+    return normalizeResponse(data);
+}
+/**
+ * Retrieves OCAPI request metrics for an organization.
+ *
+ * @param client - Metrics API client from {@link createMetricsClient}
+ * @param tenantId - Tenant ID (with or without the `f_ecom_` prefix)
+ * @param options - Optional time window and `ocapiCategory`/`ocapiApi` filters
+ * @returns The metrics data response
+ * @throws Error if the request fails
+ */
+export async function getOcapiMetrics(client, tenantId, options) {
+    getLogger().debug({ tenantId, options }, 'Fetching ocapi metrics');
+    const { data, error, response } = await client.GET('/organizations/{organizationId}/metrics/ocapi', {
+        params: {
+            path: { organizationId: toOrganizationId(tenantId) },
+            query: { ...timeWindowQuery(options), ocapiCategory: options?.ocapiCategory, ocapiApi: options?.ocapiApi },
+        },
+    });
+    if (error || !data)
+        throw metricsError('ocapi', error, response);
+    return normalizeResponse(data);
+}
+/**
+ * Retrieves metrics for a category by name, dispatching to the category-specific
+ * function. Category-specific filters (`thirdPartyServiceId`, `apiFamily`,
+ * `apiName`, `ocapiCategory`, `ocapiApi`) are applied only for the categories
+ * that support them and ignored otherwise.
+ *
+ * @param client - Metrics API client from {@link createMetricsClient}
+ * @param tenantId - Tenant ID (with or without the `f_ecom_` prefix)
+ * @param category - One of {@link METRIC_CATEGORIES}
+ * @param options - Optional time window and category-specific filters
+ * @returns The metrics data response
+ * @throws Error if the request fails or the category is unknown
+ */
+export async function getMetricsByCategory(client, tenantId, category, options) {
+    switch (category) {
+        case 'overall':
+            return getOverallMetrics(client, tenantId, options);
+        case 'sales':
+            return getSalesMetrics(client, tenantId, options);
+        case 'ecdn':
+            return getEcdnMetrics(client, tenantId, options);
+        case 'third-party':
+            return getThirdPartyMetrics(client, tenantId, options);
+        case 'scapi':
+            return getScapiMetrics(client, tenantId, options);
+        case 'scapi-hooks':
+            return getScapiHooksMetrics(client, tenantId, options);
+        case 'mrt':
+            return getMrtMetrics(client, tenantId, options);
+        case 'controller':
+            return getControllerMetrics(client, tenantId, options);
+        case 'ocapi':
+            return getOcapiMetrics(client, tenantId, options);
+        default: {
+            // Exhaustiveness guard: if a new category is added to METRIC_CATEGORIES
+            // without a case here, this line fails to compile.
+            const exhaustive = category;
+            throw new Error(`Unknown metric category: ${String(exhaustive)}`);
+        }
+    }
+}
+// Client-side dimension/tag extraction for series (interim until the API
+// exposes structured tags server-side). See ./tags.ts.
+export { parseSeriesTags, enrichMetricsTags } from './tags.js';
+//# sourceMappingURL=index.js.map

package/dist/esm/operations/metrics/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/operations/metrics/index.ts"],"names":[],"mappings":"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"}

package/dist/esm/operations/metrics/tags.d.ts

@@ -0,0 +1,148 @@
+/**
+ * Client-side dimension extraction for Metrics API series.
+ *
+ * The Metrics API returns each series as `{id, name, data}`, where `id`/`name`
+ * pack every identifying dimension into a single display string using
+ * inconsistent delimiters — e.g. `bdpx.product` (realm `.` apiFamily),
+ * `bdpx.product HIT` (realm `.` family ` ` cacheStatus), `2xx bdpx.host` (status
+ * class *before* the realm), or `bdpx.host.socketReadTimeout` (realm `.` host —
+ * whose own dots are ambiguous — `.` exceptionType). This makes the strings
+ * effectively unparseable in general and awkward to chart, group, or merge
+ * across realms.
+ *
+ * This module derives a structured, InfluxDB/Prometheus-style `tags` map for
+ * each series so consumers (dashboards, a Grafana plugin, ad-hoc analysis) can
+ * group and filter by dimension instead of regexing display strings. Two design
+ * rules keep it robust:
+ *
+ * 1. **Identity comes from the request, not the string.** `realm` and
+ *    `environment` are derived from the tenant/organization the request targeted
+ *    (`f_ecom_bdpx_prd` → `realm=bdpx`, `environment=prd`), never scraped from
+ *    the packed id. This is reliable regardless of the id's delimiter soup and
+ *    correctly distinguishes the *org's* environment from, say, eCDN hosts that
+ *    span dev/stg/prod within a single prod request.
+ * 2. **Never throw, never drop data.** An id that matches no known pattern still
+ *    gets `{realm, environment}` plus the unrecognized remainder under `series`,
+ *    so enrichment only ever adds information.
+ *
+ * This is an interim client-side convenience. The intent is for the Metrics API
+ * to expose a `tags` object on each series server-side; when it does, this layer
+ * becomes a thin fallback (or is retired).
+ *
+ * @module operations/metrics/tags
+ */
+import type { MetricsDataResponse } from '../../clients/metrics.js';
+import type { MetricCategory } from './index.js';
+/**
+ * A flat map of a series' identifying dimensions (string → string), following
+ * the InfluxDB/Prometheus/CloudWatch "tag"/"label"/"dimension" convention.
+ *
+ * Always contains `realm` and `environment` (derived from the request context).
+ * Category-specific keys (`apiFamily`, `host`, `cacheStatus`, `statusClass`,
+ * `ocapiCategory`, `controller`, `exceptionType`) are added when recognized. A
+ * rollup/aggregation series carries `aggregation` (a *statistic*, not a
+ * dimension — kept distinct so consumers can separate "how it was computed" from
+ * "what it describes"). An unrecognized remainder is preserved under `series`.
+ */
+export type MetricSeriesTags = Record<string, string>;
+/**
+ * The request identity and applied filters used to derive authoritative tags.
+ *
+ * `realm`/`environment` are parsed from `tenantId`. The optional filter fields
+ * mirror the Metrics API's category filters; when a filter was sent, that
+ * dimension is *known from the request* and is stamped onto every series as an
+ * authoritative tag — rather than being (mis)parsed from a drilled-down series
+ * id. For example, requesting `apiFamily=shopper` makes the server return
+ * finer-grained ids like `bdpx.shopper.auth.v1`; folding the filter in yields the
+ * correct `apiFamily: "shopper"` instead of the string-parser's wrong
+ * `apiFamily: "shopper.auth.v1"`.
+ */
+export interface MetricsTagContext {
+    /** Tenant or organization id the request targeted (with or without `f_ecom_`). */
+    tenantId: string;
+    /** The `apiFamily` filter sent with a scapi request, if any. */
+    apiFamily?: string;
+    /** The `apiName` filter sent with a scapi request, if any. */
+    apiName?: string;
+    /** The `ocapiCategory` filter sent with an ocapi request, if any. */
+    ocapiCategory?: string;
+    /** The `ocapiApi` filter sent with an ocapi request, if any. */
+    ocapiApi?: string;
+    /** The `thirdPartyServiceId` filter sent with a third-party request, if any. */
+    thirdPartyServiceId?: string;
+}
+/**
+ * Extracts the dimension tags for a single series id.
+ *
+ * Combines three tiers, most-authoritative last:
+ * 1. **Request identity** — `realm`/`environment` from the tenant id (never parsed
+ *    from the series string).
+ * 2. **String heuristics** — category/metric-specific dimensions parsed from the
+ *    packed id (`apiFamily`, `host`, `cacheStatus`, …), or the raw remainder under
+ *    `series` when no rule matches.
+ * 3. **Applied filters** — any filter that was sent with the request
+ *    ({@link MetricsTagContext}) is stamped last, overriding a heuristic guess.
+ *    This corrects drill-down ids: with `apiFamily=shopper` the server returns
+ *    `bdpx.shopper.auth.v1`, which heuristics would mis-tag as
+ *    `apiFamily: "shopper.auth.v1"`; the filter restores `apiFamily: "shopper"`.
+ *
+ * The result is always a superset of the request context and never throws.
+ *
+ * @param params - The series' category, metric id, series id, and request context
+ * @returns The extracted {@link MetricSeriesTags}
+ *
+ * @example
+ * ```typescript
+ * parseSeriesTags({
+ *   category: 'scapi', metricId: 'cacheHitRate',
+ *   seriesId: 'bdpx.product HIT', context: {tenantId: 'f_ecom_bdpx_prd'},
+ * });
+ * // → { realm: 'bdpx', environment: 'prd', apiFamily: 'product', cacheStatus: 'HIT' }
+ * ```
+ */
+export declare function parseSeriesTags(params: {
+    category: MetricCategory;
+    metricId: string;
+    seriesId: string;
+    context: MetricsTagContext;
+}): MetricSeriesTags;
+/**
+ * Enriches a metrics response by adding a structured `tags` map to every series,
+ * in place-safe fashion (returns a new response; the input is not mutated).
+ *
+ * This is the batch counterpart to {@link parseSeriesTags}: it walks every
+ * metric and series and attaches `series.tags` derived from the series id, the
+ * metric id, the category, and the request context. Existing fields (`id`,
+ * `name`, `data`) are preserved exactly, so the enriched response is a
+ * structural superset — consumers that ignore `tags` are unaffected. The
+ * category must be supplied because a {@link MetricsDataResponse} does not carry
+ * it (it is implied by the endpoint that produced the response).
+ *
+ * @param response - The metrics response to enrich
+ * @param category - The metric category the response was fetched for
+ * @param context - The request identity used to derive `realm`/`environment`
+ * @returns A new response with `tags` added to each series
+ *
+ * @example
+ * ```typescript
+ * const raw = await getScapiMetrics(client, tenantId);
+ * const enriched = enrichMetricsTags(raw, 'scapi', {tenantId});
+ * for (const metric of enriched.data) {
+ *   for (const series of metric.dataSeries) {
+ *     console.log(series.tags, series.data);
+ *   }
+ * }
+ * ```
+ */
+export declare function enrichMetricsTags(response: MetricsDataResponse, category: MetricCategory, context: MetricsTagContext): MetricsTaggedResponse;
+/**
+ * A metrics response whose series carry the structured {@link MetricSeriesTags}.
+ * Structurally a superset of {@link MetricsDataResponse}.
+ */
+export interface MetricsTaggedResponse extends MetricsDataResponse {
+    data: Array<MetricsDataResponse['data'][number] & {
+        dataSeries: Array<MetricsDataResponse['data'][number]['dataSeries'][number] & {
+            tags: MetricSeriesTags;
+        }>;
+    }>;
+}