@oxy.so/telemetry 2.0.0 → 2.2.0

package/dist/esm/browser.js

@@ -26,6 +26,12 @@ function eligibleLocation(location) {
         location.hostname !== '127.0.0.1' &&
         location.hostname !== '[::1]');
 }
+/**
+ * @deprecated No Oxy repo constructs its own runtime: use the module-level
+ * `getBrowserActivityIdHeader`, `getBrowserEdgeRegionHeader` and
+ * `peekBrowserEdgeRegionHeader`. The factory remains the test seam. Removal from
+ * the public surface is planned for the next major.
+ */
 export function createBrowserTelemetry(options = {}) {
     let activityId = null;
     let activityIdCreatedAt = 0;
@@ -118,4 +124,9 @@ const defaultBrowserTelemetry = createBrowserTelemetry();
 export const getBrowserActivityIdHeader = () => defaultBrowserTelemetry.getActivityIdHeader();
 export const getBrowserEdgeRegionHeader = () => defaultBrowserTelemetry.getEdgeRegionHeader();
 export const peekBrowserEdgeRegionHeader = () => defaultBrowserTelemetry.peekEdgeRegionHeader();
+/**
+ * @deprecated Unused by any Oxy repo. `@oxy.so/core` sends
+ * `peekBrowserEdgeRegionHeader()` and `getBrowserActivityIdHeader()` per request.
+ * Removal is planned for the next major.
+ */
 export const getBrowserTelemetryHeaders = () => defaultBrowserTelemetry.getHeaders();

package/dist/esm/collector.js

@@ -1,4 +1,5 @@
-import { metadataFromHeaders } from './server.js';
+import { OXY_REGION_HEADER, OXY_SOURCE_REGION_HEADER, } from './index.js';
+import { metadataFromHeaders, sourceRegionFromEdgePop } from './server.js';
 const TYPES = {
     auth: 'identity',
     session: 'identity',
@@ -39,6 +40,35 @@ export function trafficType(path) {
         parts.shift();
     return TYPES[parts[0] ?? ''] ?? 'platform';
 }
+/**
+ * Every path a reporter does not observe, in ONE table. Each entry says which
+ * directions it applies to: the inbound and outbound sets differ today (an
+ * outbound call to a probe or to `/platform-stats` IS recorded), and that is
+ * preserved exactly. Unifying them is a separate, deliberate decision.
+ */
+export const UNOBSERVED_PATHS = [
+    {
+        directions: 'inbound',
+        matches: (path) => /^\/(?:api\/)?(?:health|ready|live|platform-stats|platform-activity|infra-status)(?:\/|$)/.test(path),
+    },
+    {
+        directions: 'inbound',
+        matches: (path) => /^\/(?:api\/)?platform-infrastructure(?:\/|$)/.test(path),
+    },
+    { directions: 'outbound', matches: (path) => path === '/platform-infrastructure' },
+    { directions: 'both', matches: (path) => path.startsWith('/internal/activity') },
+    { directions: 'both', matches: (path) => path.startsWith('/auth/service-token') },
+    { directions: 'inbound', matches: (path) => path.startsWith('/cdn-cgi/') },
+];
+/**
+ * Is this path part of what a reporter observes in this direction? Collection
+ * itself, service-token minting and (inbound) probes and the dashboard
+ * transport are control traffic: observing them would feed back into the very
+ * activity they carry.
+ */
+export function isObservedPath(path, direction) {
+    return !UNOBSERVED_PATHS.some((entry) => (entry.directions === 'both' || entry.directions === direction) && entry.matches(path));
+}
 export function createTrafficCollector(publish, now = Date.now) {
     const pending = new Map();
     let flushing = null;
@@ -79,13 +109,10 @@ export function createTrafficCollector(publish, now = Date.now) {
 }
 export function trafficMiddleware(collector, service, region) {
     return (request, response, next) => {
-        response.setHeader?.('X-Oxy-Region', region);
+        response.setHeader?.(OXY_REGION_HEADER, region);
         const path = request.path ?? request.url ?? '/';
         // Never report collection itself, probes or the dashboard transport.
-        if (/^\/(?:api\/)?(?:health|ready|live|platform-stats|platform-activity|platform-infrastructure|infra-status)(?:\/|$)/.test(path) ||
-            path.startsWith('/internal/activity') ||
-            path.startsWith('/auth/service-token') ||
-            path.startsWith('/cdn-cgi/')) {
+        if (!isObservedPath(path, 'inbound')) {
             next();
             return;
         }
@@ -99,12 +126,10 @@ export function trafficMiddleware(collector, service, region) {
                 .replace(/[^a-z0-9-]/g, '-')
                 .slice(0, 40);
             const internal = Boolean(name);
-            const forwardedRegion = request.headers['x-oxy-source-region'];
+            const forwardedRegion = request.headers[OXY_SOURCE_REGION_HEADER.toLowerCase()];
             const peerRegion = internal
                 ? normalizeInfrastructureRegion(forwardedRegion)
-                : edgePop
-                    ? `edge-${edgePop}`
-                    : undefined;
+                : sourceRegionFromEdgePop(edgePop);
             return {
                 region,
                 service,
@@ -148,9 +173,7 @@ export function instrumentTrafficFetch(fetcher, collector, service, region, reso
     return Object.assign(async (input, init) => {
         const url = new URL(typeof input === 'string' ? input : input instanceof URL ? input.href : input.url);
         // Collection/auth control traffic cannot generate a feedback loop.
-        if (url.pathname.startsWith('/internal/activity') ||
-            url.pathname.startsWith('/auth/service-token') ||
-            url.pathname === '/platform-infrastructure')
+        if (!isObservedPath(url.pathname, 'outbound'))
             return fetcher(input, init);
         const peer = resolveEndpoint(url);
         const flow = {
@@ -166,7 +189,7 @@ export function instrumentTrafficFetch(fetcher, collector, service, region, reso
         };
         const headers = new Headers(init?.headers ?? (input instanceof Request ? input.headers : undefined));
         if (peer)
-            headers.set('X-Oxy-Source-Region', region);
+            headers.set(OXY_SOURCE_REGION_HEADER, region);
         let response;
         try {
             response = await fetcher(input, { ...init, headers });
@@ -176,7 +199,7 @@ export function instrumentTrafficFetch(fetcher, collector, service, region, reso
             throw error;
         }
         const targetRegion = peer
-            ? normalizeInfrastructureRegion(response.headers.get('X-Oxy-Region') ?? undefined)
+            ? normalizeInfrastructureRegion(response.headers.get(OXY_REGION_HEADER) ?? undefined)
             : undefined;
         collector.record({ ...flow, targetRegion });
         collector.record({
@@ -194,11 +217,12 @@ export function instrumentTrafficFetch(fetcher, collector, service, region, reso
 // to be an internal service. Region is infrastructure metadata, never IP geo.
 const OXY_API_SERVICES = {
     'api.oxy.so': 'oxy-api',
-    'api.website.oxy.so': 'website',
     'website-api.oxy.so': 'website',
     'api.mention.earth': 'mention',
     'api.mercaria.co': 'mercaria',
+    // Old Alia app builds still call it; goes when api.alia.onl is retired (Gemies ADR 0034).
     'api.alia.onl': 'alia',
+    'api.gemies.ai': 'gemies',
     'kaana.ai': 'kaana',
     'api.homiio.com': 'homiio',
     'api.syra.fm': 'syra',

package/dist/esm/index.js

@@ -1,2 +1,23 @@
+/** Request header a browser sends: the ephemeral anonymous activity ID. */
 export const OXY_ACTIVITY_ID_HEADER = 'X-Oxy-Activity-Id';
+/** Request header a browser sends: the three-letter Cloudflare PoP code. */
 export const OXY_EDGE_REGION_HEADER = 'X-Oxy-Edge-Region';
+/** Response header a reporting service sets: the region that processed the request. */
+export const OXY_REGION_HEADER = 'X-Oxy-Region';
+/** Request header one Oxy service sends another: the caller's infrastructure region. */
+export const OXY_SOURCE_REGION_HEADER = 'X-Oxy-Source-Region';
+/**
+ * Request headers a browser may send and a CORS allow-list must therefore
+ * permit (`Access-Control-Allow-Headers`). `X-Oxy-Source-Region` is service to
+ * service only and is deliberately absent. The list is derived from the
+ * constants above, so a CORS list built from it cannot drift from them.
+ */
+export const OXY_TELEMETRY_REQUEST_HEADERS = Object.freeze([
+    OXY_ACTIVITY_ID_HEADER,
+    OXY_EDGE_REGION_HEADER,
+]);
+/**
+ * Response headers a browser client may need to read
+ * (`Access-Control-Expose-Headers`).
+ */
+export const OXY_TELEMETRY_EXPOSED_HEADERS = Object.freeze([OXY_REGION_HEADER]);

package/dist/esm/metrics.js

@@ -0,0 +1,212 @@
+/**
+ * Operational metrics for Oxy services, published as CloudWatch Embedded Metric
+ * Format (EMF) log lines.
+ *
+ * WHY EMF ON STDOUT: every Oxy backend runs on ECS with the `awslogs` driver, and
+ * CloudWatch Logs extracts metrics from any log event shaped as EMF — no agent,
+ * no sidecar, no scraper, no IAM grant beyond the logging the task already has.
+ * A registry that only an HTTP scrape can read (Prometheus) measures into a void
+ * when nothing scrapes it, which is how Mention's counters lost every value on
+ * every deploy.
+ *
+ * WHY AGGREGATED: values are folded in memory and flushed once per interval as
+ * ONE line per (metric, label set), not one line per observation. A latency is
+ * kept as a distribution (`Values`/`Counts`), so CloudWatch still answers
+ * SampleCount, p50 and p99 for it — the request COUNT is the distribution's
+ * SampleCount, so a service needs no separate counter for it.
+ *
+ * WHY MOST LABELS ARE NOT DIMENSIONS: every distinct combination of dimension
+ * values is a billed custom metric. Route x method as dimensions once measured
+ * 405 metrics and ~80 % of the account's CloudWatch bill (Mention #1334). So a
+ * label becomes a DIMENSION only when a metric definition names it in
+ * `dimensionSets`, and only labels with a small, closed value set belong there.
+ * Every other label is written as a plain property of the line: free to store,
+ * and grouped in Logs Insights (`stats sum(RequestLatency.Count) by Route`).
+ */
+/** One HTTP request: SampleCount is the request count, percentiles the latency. */
+export const HTTP_REQUEST_LATENCY = {
+    name: 'RequestLatency',
+    unit: 'Milliseconds',
+    kind: 'distribution',
+    dimensionSets: [['StatusClass'], ['Caller']],
+};
+/** One request a rate limiter refused (429), per calling application. */
+export const HTTP_RATE_LIMITED = {
+    name: 'RateLimited',
+    unit: 'Count',
+    kind: 'sum',
+    dimensionSets: [['Caller']],
+};
+/** `2xx`, `4xx`, … — a closed set, safe as a dimension. */
+export function statusClass(status) {
+    return Number.isInteger(status) && status >= 100 && status <= 599
+        ? `${Math.floor(status / 100)}xx`
+        : 'other';
+}
+/** EMF allows at most 100 distinct values per metric on one line. */
+const MAX_DISTRIBUTION_VALUES = 100;
+/** Neighbouring values within ~5 % share a bucket, which bounds the set. */
+const BUCKET_BASE = 1.05;
+const LABEL_NAME = /^[A-Za-z][A-Za-z0-9_]{0,63}$/;
+const MAX_LABEL_VALUE_LENGTH = 128;
+const RESERVED = new Set(['_aws', 'Service']);
+/** Representative value of a bucket: values within ~5 % collapse together. */
+function bucketOf(value) {
+    if (value <= 0)
+        return 0;
+    const exponent = Math.round(Math.log(value) / Math.log(BUCKET_BASE));
+    return Number((BUCKET_BASE ** exponent).toPrecision(3));
+}
+/** Merge adjacent buckets (keeping the larger value) until EMF accepts them. */
+function boundedDistribution(buckets) {
+    let entries = [...buckets.entries()].sort(([left], [right]) => left - right);
+    while (entries.length > MAX_DISTRIBUTION_VALUES) {
+        const merged = [];
+        for (let index = 0; index < entries.length; index += 2) {
+            const [value, count] = entries[index];
+            const next = entries[index + 1];
+            merged.push(next ? [next[0], count + next[1]] : [value, count]);
+        }
+        entries = merged;
+    }
+    return { values: entries.map(([value]) => value), counts: entries.map(([, count]) => count) };
+}
+function cleanLabels(metric, labels) {
+    const clean = {};
+    for (const [name, raw] of Object.entries(labels ?? {})) {
+        if (!LABEL_NAME.test(name) || RESERVED.has(name) || name === metric.name)
+            continue;
+        const value = String(raw).slice(0, MAX_LABEL_VALUE_LENGTH);
+        clean[name] = value.length > 0 ? value : 'unknown';
+    }
+    // A dimension named by the definition must be present on every line, or
+    // CloudWatch drops the metric from that line.
+    for (const set of metric.dimensionSets ?? []) {
+        for (const name of set)
+            clean[name] ?? (clean[name] = 'unknown');
+    }
+    return clean;
+}
+function seriesKey(metric, labels) {
+    const pairs = Object.keys(labels)
+        .sort()
+        .map((name) => `${name}=${labels[name]}`);
+    return `${metric.name}\u0000${pairs.join('\u0000')}`;
+}
+/** One line on stdout. Reached through `globalThis`: this package carries no Node types. */
+function defaultWrite(line) {
+    globalThis.process?.stdout?.write?.(`${line}\n`);
+}
+/** Set by ECS on every task: the one reliable signal that `awslogs` is capturing stdout. */
+const ECS_METADATA_ENV = 'ECS_CONTAINER_METADATA_URI_V4';
+/**
+ * `createEmfPublisher` on ECS, `null` everywhere else (a laptop, CI, a test):
+ * the gate oxy-api and Mention each repeated. `env` is injectable for tests.
+ */
+export function createEmfPublisherIfDeployed(options, env = globalThis.process?.env ?? {}) {
+    return env[ECS_METADATA_ENV] ? createEmfPublisher(options) : null;
+}
+export function createEmfPublisher(options) {
+    const flushIntervalMs = options.flushIntervalMs ?? 60000;
+    const maxSeries = options.maxSeries ?? 2000;
+    const write = options.write ?? defaultWrite;
+    const now = options.now ?? Date.now;
+    let series = new Map();
+    const line = (entry, timestamp) => {
+        const { metric } = entry;
+        const dimensions = [
+            ['Service'],
+            ...(metric.dimensionSets ?? []).map((set) => ['Service', ...set]),
+        ];
+        let value;
+        if (metric.kind === 'sum')
+            value = entry.sum;
+        else if (metric.kind === 'gauge')
+            value = entry.last;
+        else {
+            const { values, counts } = boundedDistribution(entry.buckets);
+            value = {
+                Values: values,
+                Counts: counts,
+                Max: entry.max,
+                Min: entry.min,
+                Count: entry.count,
+                Sum: entry.sum,
+            };
+        }
+        return JSON.stringify({
+            _aws: {
+                Timestamp: timestamp,
+                CloudWatchMetrics: [
+                    {
+                        Namespace: options.namespace,
+                        Dimensions: dimensions,
+                        Metrics: [{ Name: metric.name, Unit: metric.unit }],
+                    },
+                ],
+            },
+            ...entry.labels,
+            Service: options.service,
+            [metric.name]: value,
+        });
+    };
+    const flush = () => {
+        if (series.size === 0)
+            return;
+        const current = series;
+        series = new Map();
+        const timestamp = now();
+        for (const entry of current.values()) {
+            try {
+                write(line(entry, timestamp));
+            }
+            catch {
+                // Metrics are best effort; a failed write must never reach a request.
+            }
+        }
+    };
+    const timer = setInterval(flush, flushIntervalMs);
+    timer.unref?.();
+    return {
+        record(metric, value, labels) {
+            if (!Number.isFinite(value))
+                return;
+            if (metric.kind !== 'gauge' && value < 0)
+                return;
+            let clean = cleanLabels(metric, labels);
+            let key = seriesKey(metric, clean);
+            if (!series.has(key) && series.size >= maxSeries) {
+                clean = Object.fromEntries(Object.keys(clean).map((name) => [name, 'other']));
+                key = seriesKey(metric, clean);
+            }
+            let entry = series.get(key);
+            if (!entry) {
+                entry = {
+                    metric,
+                    labels: clean,
+                    sum: 0,
+                    last: 0,
+                    count: 0,
+                    min: Number.POSITIVE_INFINITY,
+                    max: Number.NEGATIVE_INFINITY,
+                    buckets: new Map(),
+                };
+                series.set(key, entry);
+            }
+            entry.sum += value;
+            entry.last = value;
+            entry.count += 1;
+            entry.min = Math.min(entry.min, value);
+            entry.max = Math.max(entry.max, value);
+            if (metric.kind === 'distribution') {
+                const bucket = bucketOf(value);
+                entry.buckets.set(bucket, (entry.buckets.get(bucket) ?? 0) + 1);
+            }
+        },
+        flush,
+        stop() {
+            clearInterval(timer);
+            flush();
+        },
+    };
+}

package/dist/esm/server.js

@@ -1,4 +1,6 @@
+import { OXY_ACTIVITY_ID_HEADER, OXY_EDGE_REGION_HEADER, } from './index.js';
 export const DEFAULT_PRESENCE_BUCKET_MS = 30000;
+/** @deprecated Unused by any Oxy repo; `presenceKeys` already encodes the window. Removal is planned for the next major. */
 export const DEFAULT_ACTIVE_CLIENT_WINDOW_MS = 60000;
 function firstHeaderValue(value) {
     if (typeof value === 'string')
@@ -15,23 +17,43 @@ export function normalizeActivityId(value) {
     const candidate = firstHeaderValue(value);
     return candidate && /^[a-z0-9_-]{16,64}$/i.test(candidate) ? candidate : undefined;
 }
+/**
+ * The collector's source region for a normalised edge PoP (`edge-<pop>`), the
+ * one derivation every reporter shares. `undefined` when there is no PoP.
+ */
+export function sourceRegionFromEdgePop(edgePop) {
+    return edgePop ? `edge-${edgePop}` : undefined;
+}
 export function metadataFromHeaders(headers) {
-    const forwardedPop = normalizeEdgePop(headers['x-oxy-edge-region']);
+    const forwardedPop = normalizeEdgePop(headers[OXY_EDGE_REGION_HEADER.toLowerCase()]);
     const ray = firstHeaderValue(headers['cf-ray']);
     const rayPop = ray?.match(/-([a-z]{3})$/i)?.[1]?.toLowerCase();
-    const activityId = normalizeActivityId(headers['x-oxy-activity-id']);
+    const activityId = normalizeActivityId(headers[OXY_ACTIVITY_ID_HEADER.toLowerCase()]);
     return {
         ...(activityId ? { activityId } : {}),
         ...(forwardedPop || rayPop ? { edgePop: forwardedPop ?? rayPop } : {}),
     };
 }
+/**
+ * @deprecated Unused by any Oxy repo. For the bounded activity category of a
+ * path use `trafficType` from `@oxy.so/telemetry/collector`. Removal is planned
+ * for the next major.
+ */
 export function serviceFromPath(path) {
     const segment = path.split('/').filter(Boolean)[0];
     return segment && /^[a-z][a-z0-9-]{0,31}$/i.test(segment) ? segment.toLowerCase() : 'platform';
 }
+/**
+ * @deprecated Unused by any Oxy repo; `createTrafficCollector` keys its own
+ * flows. Removal is planned for the next major.
+ */
 export function activityFlow(sourceRegion, service) {
     return { sourceRegion, service, key: `${sourceRegion ?? ''}|${service}` };
 }
+/**
+ * @deprecated Unused outside `presenceKeys`; call `presenceKeys` for the
+ * current and previous bucket keys. Removal is planned for the next major.
+ */
 export function presenceBucket(observedAt, bucketMs = DEFAULT_PRESENCE_BUCKET_MS) {
     if (!Number.isFinite(observedAt) || !Number.isFinite(bucketMs) || bucketMs <= 0) {
         throw new RangeError('observedAt and bucketMs must define a finite positive bucket');

package/dist/esm/socket.js

@@ -1,5 +1,5 @@
 import { normalizeInfrastructureRegion } from './collector.js';
-import { metadataFromHeaders } from './server.js';
+import { metadataFromHeaders, sourceRegionFromEdgePop } from './server.js';
 const CATEGORIES = {
     auth: 'identity',
     session: 'identity',
@@ -44,9 +44,7 @@ export function observeTrafficSocket(socket, collector, service, region, options
         const edgePop = metadataFromHeaders(socket.handshake.headers).edgePop;
         const peerRegion = peerService
             ? normalizeInfrastructureRegion(peer?.region)
-            : edgePop
-                ? `edge-${edgePop}`
-                : undefined;
+            : sourceRegionFromEdgePop(edgePop);
         collector.record({
             region,
             service,
@@ -85,9 +83,7 @@ export function observeTrafficWebSocket(socket, collector, service, region, opti
         const edgePop = metadataFromHeaders(options.headers ?? {}).edgePop;
         const peerRegion = peerService
             ? normalizeInfrastructureRegion(peer?.region)
-            : edgePop
-                ? `edge-${edgePop}`
-                : undefined;
+            : sourceRegionFromEdgePop(edgePop);
         collector.record({
             service,
             region,

package/dist/types/browser.d.ts

@@ -32,9 +32,20 @@ export interface BrowserTelemetry {
     peekEdgeRegionHeader(): Record<string, string>;
     getHeaders(): Promise<Record<string, string>>;
 }
+/**
+ * @deprecated No Oxy repo constructs its own runtime: use the module-level
+ * `getBrowserActivityIdHeader`, `getBrowserEdgeRegionHeader` and
+ * `peekBrowserEdgeRegionHeader`. The factory remains the test seam. Removal from
+ * the public surface is planned for the next major.
+ */
 export declare function createBrowserTelemetry(options?: BrowserTelemetryOptions): BrowserTelemetry;
 export declare const getBrowserActivityIdHeader: () => Record<string, string>;
 export declare const getBrowserEdgeRegionHeader: () => Promise<Record<string, string>>;
 export declare const peekBrowserEdgeRegionHeader: () => Record<string, string>;
+/**
+ * @deprecated Unused by any Oxy repo. `@oxy.so/core` sends
+ * `peekBrowserEdgeRegionHeader()` and `getBrowserActivityIdHeader()` per request.
+ * Removal is planned for the next major.
+ */
 export declare const getBrowserTelemetryHeaders: () => Promise<Record<string, string>>;
 export {};

package/dist/types/collector.d.ts

@@ -1,24 +1,26 @@
+import { type TrafficAggregate, type TrafficFlow, type TrafficType } from './index.js';
 import { type TelemetryHeaders } from './server.js';
-export type TrafficScope = 'internal' | 'external';
-export type TrafficDirection = 'inbound' | 'outbound';
-export type TrafficType = 'identity' | 'ai' | 'communication' | 'media' | 'platform';
-export interface TrafficFlow {
-    region: string;
-    sourceRegion?: string;
-    targetRegion?: string;
-    sourceService?: string;
-    targetService?: string;
-    service: string;
-    scope: TrafficScope;
-    direction: TrafficDirection;
-    activityType: TrafficType;
-}
-export interface TrafficAggregate extends TrafficFlow {
-    requests: number;
-    windowStartedAt: string;
-    emittedAt: string;
-}
+export type { TrafficAggregate, TrafficDirection, TrafficFlow, TrafficScope, TrafficType, } from './index.js';
 export declare function trafficType(path: string): TrafficType;
+/** Which side of a request a reporter is observing. */
+export type ObservationDirection = 'inbound' | 'outbound';
+/**
+ * Every path a reporter does not observe, in ONE table. Each entry says which
+ * directions it applies to: the inbound and outbound sets differ today (an
+ * outbound call to a probe or to `/platform-stats` IS recorded), and that is
+ * preserved exactly. Unifying them is a separate, deliberate decision.
+ */
+export declare const UNOBSERVED_PATHS: readonly {
+    readonly directions: ObservationDirection | 'both';
+    readonly matches: (path: string) => boolean;
+}[];
+/**
+ * Is this path part of what a reporter observes in this direction? Collection
+ * itself, service-token minting and (inbound) probes and the dashboard
+ * transport are control traffic: observing them would feed back into the very
+ * activity they carry.
+ */
+export declare function isObservedPath(path: string, direction: ObservationDirection): boolean;
 export declare function createTrafficCollector(publish: (events: TrafficAggregate[]) => Promise<unknown>, now?: () => number): {
     record(flow: TrafficFlow): void;
     flush(): Promise<void>;
@@ -47,4 +49,3 @@ export declare function infrastructureLocation(region: string): {
     coordinates: [number, number];
 };
 export declare function normalizeInfrastructureRegion(value: unknown): string | undefined;
-export {};

package/dist/types/index.d.ts

@@ -1,16 +1,69 @@
+/** Request header a browser sends: the ephemeral anonymous activity ID. */
 export declare const OXY_ACTIVITY_ID_HEADER = "X-Oxy-Activity-Id";
+/** Request header a browser sends: the three-letter Cloudflare PoP code. */
 export declare const OXY_EDGE_REGION_HEADER = "X-Oxy-Edge-Region";
+/** Response header a reporting service sets: the region that processed the request. */
+export declare const OXY_REGION_HEADER = "X-Oxy-Region";
+/** Request header one Oxy service sends another: the caller's infrastructure region. */
+export declare const OXY_SOURCE_REGION_HEADER = "X-Oxy-Source-Region";
+/**
+ * Request headers a browser may send and a CORS allow-list must therefore
+ * permit (`Access-Control-Allow-Headers`). `X-Oxy-Source-Region` is service to
+ * service only and is deliberately absent. The list is derived from the
+ * constants above, so a CORS list built from it cannot drift from them.
+ */
+export declare const OXY_TELEMETRY_REQUEST_HEADERS: readonly string[];
+/**
+ * Response headers a browser client may need to read
+ * (`Access-Control-Expose-Headers`).
+ */
+export declare const OXY_TELEMETRY_EXPOSED_HEADERS: readonly string[];
 export interface AnonymousActivityMetadata {
     activityId?: string;
     edgePop?: string;
 }
-export interface ActivityAggregate {
+export type TrafficScope = 'internal' | 'external';
+export type TrafficDirection = 'inbound' | 'outbound';
+export type TrafficType = 'identity' | 'ai' | 'communication' | 'media' | 'platform';
+/** One observed flow, as a reporter records it. */
+export interface TrafficFlow {
+    region: string;
     sourceRegion?: string;
-    targetRegion: string;
+    targetRegion?: string;
+    sourceService?: string;
+    targetService?: string;
     service: string;
+    scope: TrafficScope;
+    direction: TrafficDirection;
+    activityType: TrafficType;
+}
+/**
+ * A flow with its request count and window: the exact shape the API's strict
+ * `platformActivityBatchSchema` accepts on `POST /internal/activity`.
+ */
+export interface TrafficAggregate extends TrafficFlow {
     requests: number;
-    activeClients: number;
     windowStartedAt: string;
     emittedAt: string;
-    direction: 'inbound';
+}
+/**
+ * The `platform_activity` socket payload: an aggregate plus the approximate
+ * active-client count for its origin.
+ */
+export type ActivityAggregate = TrafficAggregate & {
+    activeClients: number;
+};
+/** One region in the `platform_infrastructure` snapshot. */
+export interface InfrastructureNode {
+    region: string;
+    label: string;
+    coordinates: [number, number];
+    services: string[];
+    instances: number;
+    status: 'online' | 'degraded' | 'offline' | 'unknown';
+}
+/** The `platform_infrastructure` socket payload. */
+export interface InfrastructureSnapshot {
+    emittedAt: string;
+    nodes: InfrastructureNode[];
 }