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