@oxy.so/telemetry 0.1.0

package/README.md

@@ -0,0 +1,121 @@
+# `@oxy.so/telemetry`
+
+Framework-agnostic primitives for anonymous, real-time Oxy activity telemetry.
+The package has no runtime dependencies and does not import Express, Socket.IO,
+Redis, React, React Native or Expo.
+
+Version: `0.1.0`. This workspace package is not published yet.
+
+## Entry points
+
+- `@oxy.so/telemetry` — shared header names and aggregate interfaces.
+- `@oxy.so/telemetry/browser` — ephemeral browser metadata.
+- `@oxy.so/telemetry/server` — pure validation, route bucketing and cardinality
+  keys/interfaces.
+
+Browser code must import the browser entry point explicitly. Server code must
+import the server entry point explicitly; the root entry point has no platform
+side effects.
+
+## Browser metadata
+
+```ts
+import { getBrowserTelemetryHeaders } from '@oxy.so/telemetry/browser';
+
+const headers = await getBrowserTelemetryHeaders();
+await fetch('https://api.oxy.so/session/status', { headers });
+```
+
+`X-Oxy-Activity-Id` is generated in memory for the current page runtime and
+rotates every five minutes. It is not placed in a cookie, local storage,
+session storage, IndexedDB or a URL. Closing or reloading the page loses it.
+
+`X-Oxy-Edge-Region` contains only the three-letter Cloudflare PoP code obtained
+from the same-origin `/cdn-cgi/trace` endpoint. The helper reads no IP field and
+returns, logs and persists none of the rest of the trace response. Discovery is
+cached per runtime, has a one-second timeout and is disabled on loopback.
+
+Use `createBrowserTelemetry()` to create an isolated runtime or inject clock,
+crypto, location and trace-fetch dependencies in tests.
+
+## Server primitives
+
+```ts
+import {
+  activityFlow,
+  metadataFromHeaders,
+  presenceKeys,
+  serviceFromPath,
+  type ActivityCardinalityAdapter,
+} from '@oxy.so/telemetry/server';
+
+const metadata = metadataFromHeaders(request.headers);
+const sourceRegion = metadata.edgePop ? `edge-${metadata.edgePop}` : undefined;
+const flow = activityFlow(sourceRegion, serviceFromPath(request.path));
+const keys = sourceRegion ? presenceKeys(sourceRegion, Date.now()) : [];
+```
+
+Validation accepts a three-letter PoP and a 16–64 character opaque activity ID.
+It ignores IP and forwarding headers. `serviceFromPath` keeps only a bounded,
+static first route segment, so IDs and full paths cannot enter aggregates.
+
+`ActivityCardinalityAdapter` describes the minimal storage boundary for an
+implementation such as Redis HyperLogLog. This package does not instantiate a
+store, keep server-global maps, start timers or send realtime events.
+
+## Active-client definition
+
+An active client is one distinct ephemeral activity ID observed for an edge PoP
+during the rolling 60-second presence window. The default representation is the
+union of the current and previous 30-second buckets returned by `presenceKeys`.
+This is an operational count of active page runtimes, not authenticated users,
+people, devices or sessions. ID rotation and multiple tabs mean it must never be
+presented as an exact person count.
+
+## Privacy boundary
+
+Allowed public dimensions are PoP, bounded service group, processing region,
+request count, approximate active-client cardinality and aggregate timestamps.
+Forbidden inputs and outputs include raw or hashed IPs, coordinates derived from
+an IP, user/account/session IDs, request bodies, query strings and raw paths.
+The opaque activity ID exists only to estimate short-window cardinality and must
+not be persisted as an event log or joined to product identity.
+
+## Migration from `@oxyhq/*`
+
+The first consumers will replace browser helpers currently owned privately by
+`@oxyhq/core` with imports from `@oxy.so/telemetry/browser`. API collectors will
+replace their local validation and bucketing logic with
+`@oxy.so/telemetry/server`. This package deliberately provides no compatibility
+re-export: consumers move imports directly to the new owner, then the old
+private implementations are deleted in the same integration change.
+
+The central API uses the server entry point in `0.1.0`. Core temporarily retains
+its compatible browser helpers until this package is published and applications
+can migrate without a broken registry dependency.
+
+## Collector, realtime and reconnect
+
+The intended collector records only successful, non-control-plane requests. It
+increments request totals per `source region × bounded service × time window`
+and sends the ephemeral activity ID to a cardinality adapter, never to an event
+row or log.
+
+Realtime transport publishes aggregate buckets, not individual metadata. A
+socket event may carry `ActivityAggregate`: request count, approximate active
+clients, source/target regions, service and window timestamps. Transport and
+fan-out are application concerns and intentionally absent from this package.
+
+Realtime events are not a durable replay log. After reconnect, a consumer first
+loads the collector's current aggregate snapshot and then resumes the live
+stream, deduplicating any overlapping window by its stable flow/window identity.
+Reconnect backoff, socket lifecycle and snapshot endpoints belong to the
+consumer and collector, not these pure primitives.
+
+## Development
+
+```bash
+bun run --filter @oxy.so/telemetry typescript
+bun run --filter @oxy.so/telemetry test
+bun run --filter @oxy.so/telemetry build
+```

package/dist/cjs/browser.js

@@ -0,0 +1,84 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getBrowserTelemetryHeaders = exports.getBrowserEdgeRegionHeader = exports.getBrowserActivityIdHeader = exports.DEFAULT_EDGE_TRACE_TIMEOUT_MS = exports.DEFAULT_ACTIVITY_ID_ROTATION_MS = void 0;
+exports.createBrowserTelemetry = createBrowserTelemetry;
+const index_js_1 = require("./index.js");
+exports.DEFAULT_ACTIVITY_ID_ROTATION_MS = 5 * 60 * 1000;
+exports.DEFAULT_EDGE_TRACE_TIMEOUT_MS = 1000;
+function createUuid(cryptoApi) {
+    if (!cryptoApi)
+        return null;
+    if (typeof cryptoApi.randomUUID === 'function')
+        return cryptoApi.randomUUID();
+    const bytes = cryptoApi.getRandomValues(new Uint8Array(16));
+    bytes[6] = (bytes[6] & 0x0f) | 0x40;
+    bytes[8] = (bytes[8] & 0x3f) | 0x80;
+    const hex = Array.from(bytes, (byte) => byte.toString(16).padStart(2, '0')).join('');
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+function eligibleLocation(location) {
+    if (!location || (location.protocol !== 'https:' && location.protocol !== 'http:'))
+        return false;
+    return location.hostname !== 'localhost'
+        && location.hostname !== '127.0.0.1'
+        && location.hostname !== '[::1]';
+}
+function createBrowserTelemetry(options = {}) {
+    let activityId = null;
+    let activityIdCreatedAt = 0;
+    let edgePopPromise = null;
+    const getActivityIdHeader = () => {
+        const browserLocation = options.location ?? (typeof window === 'undefined' ? undefined : window.location);
+        if (!browserLocation)
+            return {};
+        const now = (options.now ?? Date.now)();
+        if (!activityId || now < activityIdCreatedAt || now - activityIdCreatedAt >= (options.activityIdRotationMs ?? exports.DEFAULT_ACTIVITY_ID_ROTATION_MS)) {
+            activityId = createUuid(options.crypto ?? globalThis.crypto);
+            if (!activityId)
+                return {};
+            activityIdCreatedAt = now;
+        }
+        return { [index_js_1.OXY_ACTIVITY_ID_HEADER]: activityId };
+    };
+    const discoverEdgePop = async () => {
+        const browserLocation = options.location ?? (typeof window === 'undefined' ? undefined : window.location);
+        if (!eligibleLocation(browserLocation))
+            return null;
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), options.edgeTraceTimeoutMs ?? exports.DEFAULT_EDGE_TRACE_TIMEOUT_MS);
+        try {
+            const response = await (options.fetchTrace
+                ? options.fetchTrace(controller.signal)
+                : fetch('/cdn-cgi/trace', { cache: 'no-store', credentials: 'omit', signal: controller.signal }));
+            if (!response.ok)
+                return null;
+            const match = (await response.text()).match(/^colo=([a-z]{3})$/im);
+            return match ? match[1].toLowerCase() : null;
+        }
+        catch {
+            return null;
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    };
+    const getEdgeRegionHeader = async () => {
+        edgePopPromise ?? (edgePopPromise = discoverEdgePop());
+        const edgePop = await edgePopPromise;
+        return edgePop ? { [index_js_1.OXY_EDGE_REGION_HEADER]: edgePop } : {};
+    };
+    return {
+        getActivityIdHeader,
+        getEdgeRegionHeader,
+        async getHeaders() {
+            return { ...await getEdgeRegionHeader(), ...getActivityIdHeader() };
+        },
+    };
+}
+const defaultBrowserTelemetry = createBrowserTelemetry();
+const getBrowserActivityIdHeader = () => defaultBrowserTelemetry.getActivityIdHeader();
+exports.getBrowserActivityIdHeader = getBrowserActivityIdHeader;
+const getBrowserEdgeRegionHeader = () => defaultBrowserTelemetry.getEdgeRegionHeader();
+exports.getBrowserEdgeRegionHeader = getBrowserEdgeRegionHeader;
+const getBrowserTelemetryHeaders = () => defaultBrowserTelemetry.getHeaders();
+exports.getBrowserTelemetryHeaders = getBrowserTelemetryHeaders;

package/dist/cjs/index.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OXY_EDGE_REGION_HEADER = exports.OXY_ACTIVITY_ID_HEADER = void 0;
+exports.OXY_ACTIVITY_ID_HEADER = 'X-Oxy-Activity-Id';
+exports.OXY_EDGE_REGION_HEADER = 'X-Oxy-Edge-Region';

package/dist/cjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

package/dist/cjs/server.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_ACTIVE_CLIENT_WINDOW_MS = exports.DEFAULT_PRESENCE_BUCKET_MS = void 0;
+exports.normalizeEdgePop = normalizeEdgePop;
+exports.normalizeActivityId = normalizeActivityId;
+exports.metadataFromHeaders = metadataFromHeaders;
+exports.serviceFromPath = serviceFromPath;
+exports.activityFlow = activityFlow;
+exports.presenceBucket = presenceBucket;
+exports.presenceKeys = presenceKeys;
+exports.DEFAULT_PRESENCE_BUCKET_MS = 30000;
+exports.DEFAULT_ACTIVE_CLIENT_WINDOW_MS = 60000;
+function firstHeaderValue(value) {
+    if (typeof value === 'string')
+        return value;
+    const first = value?.[0];
+    return typeof first === 'string' ? first : undefined;
+}
+function normalizeEdgePop(value) {
+    return firstHeaderValue(value)?.match(/^[a-z]{3}$/i)?.[0]?.toLowerCase();
+}
+function normalizeActivityId(value) {
+    const candidate = firstHeaderValue(value);
+    return candidate && /^[a-z0-9_-]{16,64}$/i.test(candidate) ? candidate : undefined;
+}
+function metadataFromHeaders(headers) {
+    const forwardedPop = normalizeEdgePop(headers['x-oxy-edge-region']);
+    const ray = firstHeaderValue(headers['cf-ray']);
+    const rayPop = ray?.match(/-([a-z]{3})$/i)?.[1]?.toLowerCase();
+    const activityId = normalizeActivityId(headers['x-oxy-activity-id']);
+    return {
+        ...(activityId ? { activityId } : {}),
+        ...(forwardedPop || rayPop ? { edgePop: forwardedPop ?? rayPop } : {}),
+    };
+}
+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';
+}
+function activityFlow(sourceRegion, service) {
+    return { sourceRegion, service, key: `${sourceRegion ?? ''}|${service}` };
+}
+function presenceBucket(observedAt, bucketMs = exports.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');
+    }
+    return Math.floor(observedAt / bucketMs);
+}
+function presenceKeys(sourceRegion, observedAt, bucketMs = exports.DEFAULT_PRESENCE_BUCKET_MS) {
+    const current = presenceBucket(observedAt, bucketMs);
+    return [
+        `platform-activity:clients:${sourceRegion}:${current}`,
+        `platform-activity:clients:${sourceRegion}:${current - 1}`,
+    ];
+}

package/dist/esm/browser.js

@@ -0,0 +1,77 @@
+import { OXY_ACTIVITY_ID_HEADER, OXY_EDGE_REGION_HEADER } from './index.js';
+export const DEFAULT_ACTIVITY_ID_ROTATION_MS = 5 * 60 * 1000;
+export const DEFAULT_EDGE_TRACE_TIMEOUT_MS = 1000;
+function createUuid(cryptoApi) {
+    if (!cryptoApi)
+        return null;
+    if (typeof cryptoApi.randomUUID === 'function')
+        return cryptoApi.randomUUID();
+    const bytes = cryptoApi.getRandomValues(new Uint8Array(16));
+    bytes[6] = (bytes[6] & 0x0f) | 0x40;
+    bytes[8] = (bytes[8] & 0x3f) | 0x80;
+    const hex = Array.from(bytes, (byte) => byte.toString(16).padStart(2, '0')).join('');
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+function eligibleLocation(location) {
+    if (!location || (location.protocol !== 'https:' && location.protocol !== 'http:'))
+        return false;
+    return location.hostname !== 'localhost'
+        && location.hostname !== '127.0.0.1'
+        && location.hostname !== '[::1]';
+}
+export function createBrowserTelemetry(options = {}) {
+    let activityId = null;
+    let activityIdCreatedAt = 0;
+    let edgePopPromise = null;
+    const getActivityIdHeader = () => {
+        const browserLocation = options.location ?? (typeof window === 'undefined' ? undefined : window.location);
+        if (!browserLocation)
+            return {};
+        const now = (options.now ?? Date.now)();
+        if (!activityId || now < activityIdCreatedAt || now - activityIdCreatedAt >= (options.activityIdRotationMs ?? DEFAULT_ACTIVITY_ID_ROTATION_MS)) {
+            activityId = createUuid(options.crypto ?? globalThis.crypto);
+            if (!activityId)
+                return {};
+            activityIdCreatedAt = now;
+        }
+        return { [OXY_ACTIVITY_ID_HEADER]: activityId };
+    };
+    const discoverEdgePop = async () => {
+        const browserLocation = options.location ?? (typeof window === 'undefined' ? undefined : window.location);
+        if (!eligibleLocation(browserLocation))
+            return null;
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), options.edgeTraceTimeoutMs ?? DEFAULT_EDGE_TRACE_TIMEOUT_MS);
+        try {
+            const response = await (options.fetchTrace
+                ? options.fetchTrace(controller.signal)
+                : fetch('/cdn-cgi/trace', { cache: 'no-store', credentials: 'omit', signal: controller.signal }));
+            if (!response.ok)
+                return null;
+            const match = (await response.text()).match(/^colo=([a-z]{3})$/im);
+            return match ? match[1].toLowerCase() : null;
+        }
+        catch {
+            return null;
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    };
+    const getEdgeRegionHeader = async () => {
+        edgePopPromise ?? (edgePopPromise = discoverEdgePop());
+        const edgePop = await edgePopPromise;
+        return edgePop ? { [OXY_EDGE_REGION_HEADER]: edgePop } : {};
+    };
+    return {
+        getActivityIdHeader,
+        getEdgeRegionHeader,
+        async getHeaders() {
+            return { ...await getEdgeRegionHeader(), ...getActivityIdHeader() };
+        },
+    };
+}
+const defaultBrowserTelemetry = createBrowserTelemetry();
+export const getBrowserActivityIdHeader = () => defaultBrowserTelemetry.getActivityIdHeader();
+export const getBrowserEdgeRegionHeader = () => defaultBrowserTelemetry.getEdgeRegionHeader();
+export const getBrowserTelemetryHeaders = () => defaultBrowserTelemetry.getHeaders();

package/dist/esm/index.js

@@ -0,0 +1,2 @@
+export const OXY_ACTIVITY_ID_HEADER = 'X-Oxy-Activity-Id';
+export const OXY_EDGE_REGION_HEADER = 'X-Oxy-Edge-Region';

package/dist/esm/server.js

@@ -0,0 +1,45 @@
+export const DEFAULT_PRESENCE_BUCKET_MS = 30000;
+export const DEFAULT_ACTIVE_CLIENT_WINDOW_MS = 60000;
+function firstHeaderValue(value) {
+    if (typeof value === 'string')
+        return value;
+    const first = value?.[0];
+    return typeof first === 'string' ? first : undefined;
+}
+export function normalizeEdgePop(value) {
+    return firstHeaderValue(value)?.match(/^[a-z]{3}$/i)?.[0]?.toLowerCase();
+}
+export function normalizeActivityId(value) {
+    const candidate = firstHeaderValue(value);
+    return candidate && /^[a-z0-9_-]{16,64}$/i.test(candidate) ? candidate : undefined;
+}
+export function metadataFromHeaders(headers) {
+    const forwardedPop = normalizeEdgePop(headers['x-oxy-edge-region']);
+    const ray = firstHeaderValue(headers['cf-ray']);
+    const rayPop = ray?.match(/-([a-z]{3})$/i)?.[1]?.toLowerCase();
+    const activityId = normalizeActivityId(headers['x-oxy-activity-id']);
+    return {
+        ...(activityId ? { activityId } : {}),
+        ...(forwardedPop || rayPop ? { edgePop: forwardedPop ?? rayPop } : {}),
+    };
+}
+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';
+}
+export function activityFlow(sourceRegion, service) {
+    return { sourceRegion, service, key: `${sourceRegion ?? ''}|${service}` };
+}
+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');
+    }
+    return Math.floor(observedAt / bucketMs);
+}
+export function presenceKeys(sourceRegion, observedAt, bucketMs = DEFAULT_PRESENCE_BUCKET_MS) {
+    const current = presenceBucket(observedAt, bucketMs);
+    return [
+        `platform-activity:clients:${sourceRegion}:${current}`,
+        `platform-activity:clients:${sourceRegion}:${current - 1}`,
+    ];
+}

package/dist/types/browser.d.ts

@@ -0,0 +1,24 @@
+export declare const DEFAULT_ACTIVITY_ID_ROTATION_MS: number;
+export declare const DEFAULT_EDGE_TRACE_TIMEOUT_MS = 1000;
+interface TraceResponse {
+    ok: boolean;
+    text(): Promise<string>;
+}
+export interface BrowserTelemetryOptions {
+    activityIdRotationMs?: number;
+    edgeTraceTimeoutMs?: number;
+    now?: () => number;
+    crypto?: Pick<Crypto, 'getRandomValues' | 'randomUUID'>;
+    location?: Pick<Location, 'hostname' | 'protocol'>;
+    fetchTrace?: (signal: AbortSignal) => Promise<TraceResponse>;
+}
+export interface BrowserTelemetry {
+    getActivityIdHeader(): Record<string, string>;
+    getEdgeRegionHeader(): Promise<Record<string, string>>;
+    getHeaders(): Promise<Record<string, string>>;
+}
+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 getBrowserTelemetryHeaders: () => Promise<Record<string, string>>;
+export {};

package/dist/types/index.d.ts

@@ -0,0 +1,16 @@
+export declare const OXY_ACTIVITY_ID_HEADER = "X-Oxy-Activity-Id";
+export declare const OXY_EDGE_REGION_HEADER = "X-Oxy-Edge-Region";
+export interface AnonymousActivityMetadata {
+    activityId?: string;
+    edgePop?: string;
+}
+export interface ActivityAggregate {
+    sourceRegion?: string;
+    targetRegion: string;
+    service: string;
+    requests: number;
+    activeClients: number;
+    windowStartedAt: string;
+    emittedAt: string;
+    direction: 'inbound';
+}

package/dist/types/server.d.ts

@@ -0,0 +1,22 @@
+import type { ActivityAggregate, AnonymousActivityMetadata } from './index.js';
+export declare const DEFAULT_PRESENCE_BUCKET_MS = 30000;
+export declare const DEFAULT_ACTIVE_CLIENT_WINDOW_MS = 60000;
+export type TelemetryHeaderValue = string | readonly string[] | undefined;
+export type TelemetryHeaders = Readonly<Record<string, TelemetryHeaderValue>>;
+export interface ActivityCardinalityAdapter {
+    add(key: string, activityId: string, ttlSeconds: number): Promise<void>;
+    count(keys: readonly string[]): Promise<number>;
+}
+export interface ActivityFlow {
+    sourceRegion?: string;
+    service: string;
+    key: string;
+}
+export declare function normalizeEdgePop(value: TelemetryHeaderValue): string | undefined;
+export declare function normalizeActivityId(value: TelemetryHeaderValue): string | undefined;
+export declare function metadataFromHeaders(headers: TelemetryHeaders): AnonymousActivityMetadata;
+export declare function serviceFromPath(path: string): string;
+export declare function activityFlow(sourceRegion: string | undefined, service: string): ActivityFlow;
+export declare function presenceBucket(observedAt: number, bucketMs?: number): number;
+export declare function presenceKeys(sourceRegion: string, observedAt: number, bucketMs?: number): readonly [string, string];
+export type ActivityBucket = ActivityAggregate;

package/package.json

@@ -0,0 +1,84 @@
+{
+  "name": "@oxy.so/telemetry",
+  "version": "0.1.0",
+  "description": "Framework-agnostic anonymous activity telemetry primitives for Oxy services.",
+  "type": "module",
+  "main": "dist/cjs/index.js",
+  "module": "dist/esm/index.js",
+  "types": "dist/types/index.d.ts",
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/types/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/types/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
+    },
+    "./browser": {
+      "browser": {
+        "types": "./dist/types/browser.d.ts",
+        "default": "./dist/esm/browser.js"
+      },
+      "import": {
+        "types": "./dist/types/browser.d.ts",
+        "default": "./dist/esm/browser.js"
+      },
+      "require": {
+        "types": "./dist/types/browser.d.ts",
+        "default": "./dist/cjs/browser.js"
+      }
+    },
+    "./server": {
+      "import": {
+        "types": "./dist/types/server.d.ts",
+        "default": "./dist/esm/server.js"
+      },
+      "require": {
+        "types": "./dist/types/server.d.ts",
+        "default": "./dist/cjs/server.js"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/oxyhq/sdk",
+    "directory": "packages/telemetry"
+  },
+  "license": "Apache-2.0",
+  "author": "Oxy",
+  "homepage": "https://oxy.so",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "build": "bun run clean && bun run build:cjs && bun run build:esm && bun run build:types",
+    "build:cjs": "tsc -p tsconfig.cjs.json && node scripts/mark-cjs.mjs",
+    "build:esm": "tsc -p tsconfig.esm.json",
+    "build:types": "tsc -p tsconfig.types.json",
+    "clean": "rm -rf dist",
+    "typescript": "tsc --noEmit",
+    "test": "jest",
+    "lint": "biome lint --error-on-warnings ./src",
+    "prepublishOnly": "node ../../scripts/assert-bun-publish.mjs && bun run typescript && bun run test && bun run build"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^1.9.4",
+    "@types/jest": "^30.0.0",
+    "jest": "^30.5.1",
+    "jest-environment-jsdom": "^30.5.1",
+    "ts-jest": "^29.4.12",
+    "typescript": "^5.9.2"
+  }
+}

package/src/__tests__/browser.test.ts

@@ -0,0 +1,47 @@
+import { createBrowserTelemetry } from '../browser';
+
+describe('browser telemetry', () => {
+  it('rotates an ephemeral activity id without persistence', () => {
+    let now = 1_000;
+    let sequence = 0;
+    const telemetry = createBrowserTelemetry({
+      location: { hostname: 'mention.earth', protocol: 'https:' } as Location,
+      now: () => now,
+      crypto: {
+        randomUUID: () => `00000000-0000-4000-8000-${String(++sequence).padStart(12, '0')}`,
+        getRandomValues: crypto.getRandomValues.bind(crypto),
+      },
+      activityIdRotationMs: 100,
+    });
+
+    const first = telemetry.getActivityIdHeader()['X-Oxy-Activity-Id'];
+    expect(telemetry.getActivityIdHeader()['X-Oxy-Activity-Id']).toBe(first);
+    now += 100;
+    expect(telemetry.getActivityIdHeader()['X-Oxy-Activity-Id']).not.toBe(first);
+  });
+
+  it('extracts only the Cloudflare serving PoP and caches discovery', async () => {
+    const fetchTrace = jest.fn(async () => ({
+      ok: true,
+      text: async () => 'ip=203.0.113.8\ncolo=MAD\nloc=ES',
+    }));
+    const telemetry = createBrowserTelemetry({
+      location: { hostname: 'alia.onl', protocol: 'https:' } as Location,
+      fetchTrace,
+    });
+
+    await expect(telemetry.getEdgeRegionHeader()).resolves.toEqual({ 'X-Oxy-Edge-Region': 'mad' });
+    await telemetry.getEdgeRegionHeader();
+    expect(fetchTrace).toHaveBeenCalledTimes(1);
+  });
+
+  it('does not query trace from loopback', async () => {
+    const fetchTrace = jest.fn();
+    const telemetry = createBrowserTelemetry({
+      location: { hostname: 'localhost', protocol: 'http:' } as Location,
+      fetchTrace,
+    });
+    await expect(telemetry.getEdgeRegionHeader()).resolves.toEqual({});
+    expect(fetchTrace).not.toHaveBeenCalled();
+  });
+});

package/src/__tests__/server.test.ts

@@ -0,0 +1,45 @@
+import {
+  activityFlow,
+  metadataFromHeaders,
+  normalizeActivityId,
+  normalizeEdgePop,
+  presenceBucket,
+  presenceKeys,
+  serviceFromPath,
+} from '../server';
+
+describe('server telemetry primitives', () => {
+  it('prefers a validated forwarded PoP and accepts Cloudflare ray fallback', () => {
+    expect(metadataFromHeaders({
+      'x-oxy-edge-region': 'MAD',
+      'cf-ray': 'deadbeef-CDG',
+      'x-oxy-activity-id': 'anonymous-runtime-a1',
+    })).toEqual({ edgePop: 'mad', activityId: 'anonymous-runtime-a1' });
+    expect(metadataFromHeaders({ 'cf-ray': 'deadbeef-CDG' })).toEqual({ edgePop: 'cdg' });
+  });
+
+  it('rejects identifying or malformed metadata', () => {
+    expect(normalizeEdgePop('Madrid')).toBeUndefined();
+    expect(normalizeActivityId('short')).toBeUndefined();
+    expect(metadataFromHeaders({ 'x-forwarded-for': '203.0.113.8' })).toEqual({});
+  });
+
+  it('reduces paths to bounded route groups', () => {
+    expect(serviceFromPath('/messages/private-id')).toBe('messages');
+    expect(serviceFromPath('/123/private-id')).toBe('platform');
+    expect(activityFlow('edge-mad', 'messages')).toEqual({
+      sourceRegion: 'edge-mad',
+      service: 'messages',
+      key: 'edge-mad|messages',
+    });
+  });
+
+  it('creates current and previous cardinality buckets', () => {
+    expect(presenceBucket(65_000)).toBe(2);
+    expect(presenceKeys('edge-mad', 65_000)).toEqual([
+      'platform-activity:clients:edge-mad:2',
+      'platform-activity:clients:edge-mad:1',
+    ]);
+    expect(() => presenceBucket(1, 0)).toThrow(RangeError);
+  });
+});

package/src/browser.ts

@@ -0,0 +1,104 @@
+import { OXY_ACTIVITY_ID_HEADER, OXY_EDGE_REGION_HEADER } from './index.js';
+
+export const DEFAULT_ACTIVITY_ID_ROTATION_MS = 5 * 60 * 1_000;
+export const DEFAULT_EDGE_TRACE_TIMEOUT_MS = 1_000;
+
+interface TraceResponse {
+  ok: boolean;
+  text(): Promise<string>;
+}
+
+export interface BrowserTelemetryOptions {
+  activityIdRotationMs?: number;
+  edgeTraceTimeoutMs?: number;
+  now?: () => number;
+  crypto?: Pick<Crypto, 'getRandomValues' | 'randomUUID'>;
+  location?: Pick<Location, 'hostname' | 'protocol'>;
+  fetchTrace?: (signal: AbortSignal) => Promise<TraceResponse>;
+}
+
+export interface BrowserTelemetry {
+  getActivityIdHeader(): Record<string, string>;
+  getEdgeRegionHeader(): Promise<Record<string, string>>;
+  getHeaders(): Promise<Record<string, string>>;
+}
+
+function createUuid(cryptoApi: Pick<Crypto, 'getRandomValues' | 'randomUUID'> | undefined): string | null {
+  if (!cryptoApi) return null;
+  if (typeof cryptoApi.randomUUID === 'function') return cryptoApi.randomUUID();
+
+  const bytes = cryptoApi.getRandomValues(new Uint8Array(16));
+  bytes[6] = (bytes[6] & 0x0f) | 0x40;
+  bytes[8] = (bytes[8] & 0x3f) | 0x80;
+  const hex = Array.from(bytes, (byte) => byte.toString(16).padStart(2, '0')).join('');
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+
+function eligibleLocation(location: Pick<Location, 'hostname' | 'protocol'> | undefined): boolean {
+  if (!location || (location.protocol !== 'https:' && location.protocol !== 'http:')) return false;
+  return location.hostname !== 'localhost'
+    && location.hostname !== '127.0.0.1'
+    && location.hostname !== '[::1]';
+}
+
+export function createBrowserTelemetry(options: BrowserTelemetryOptions = {}): BrowserTelemetry {
+  let activityId: string | null = null;
+  let activityIdCreatedAt = 0;
+  let edgePopPromise: Promise<string | null> | null = null;
+
+  const getActivityIdHeader = (): Record<string, string> => {
+    const browserLocation = options.location ?? (typeof window === 'undefined' ? undefined : window.location);
+    if (!browserLocation) return {};
+    const now = (options.now ?? Date.now)();
+    if (!activityId || now < activityIdCreatedAt || now - activityIdCreatedAt >= (options.activityIdRotationMs ?? DEFAULT_ACTIVITY_ID_ROTATION_MS)) {
+      activityId = createUuid(options.crypto ?? globalThis.crypto);
+      if (!activityId) return {};
+      activityIdCreatedAt = now;
+    }
+    return { [OXY_ACTIVITY_ID_HEADER]: activityId };
+  };
+
+  const discoverEdgePop = async (): Promise<string | null> => {
+    const browserLocation = options.location ?? (typeof window === 'undefined' ? undefined : window.location);
+    if (!eligibleLocation(browserLocation)) return null;
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), options.edgeTraceTimeoutMs ?? DEFAULT_EDGE_TRACE_TIMEOUT_MS);
+    try {
+      const response = await (options.fetchTrace
+        ? options.fetchTrace(controller.signal)
+        : fetch('/cdn-cgi/trace', { cache: 'no-store', credentials: 'omit', signal: controller.signal }));
+      if (!response.ok) return null;
+      const match = (await response.text()).match(/^colo=([a-z]{3})$/im);
+      return match ? match[1].toLowerCase() : null;
+    } catch {
+      return null;
+    } finally {
+      clearTimeout(timeout);
+    }
+  };
+
+  const getEdgeRegionHeader = async (): Promise<Record<string, string>> => {
+    edgePopPromise ??= discoverEdgePop();
+    const edgePop = await edgePopPromise;
+    return edgePop ? { [OXY_EDGE_REGION_HEADER]: edgePop } : {};
+  };
+
+  return {
+    getActivityIdHeader,
+    getEdgeRegionHeader,
+    async getHeaders(): Promise<Record<string, string>> {
+      return { ...await getEdgeRegionHeader(), ...getActivityIdHeader() };
+    },
+  };
+}
+
+const defaultBrowserTelemetry = createBrowserTelemetry();
+
+export const getBrowserActivityIdHeader = (): Record<string, string> =>
+  defaultBrowserTelemetry.getActivityIdHeader();
+
+export const getBrowserEdgeRegionHeader = (): Promise<Record<string, string>> =>
+  defaultBrowserTelemetry.getEdgeRegionHeader();
+
+export const getBrowserTelemetryHeaders = (): Promise<Record<string, string>> =>
+  defaultBrowserTelemetry.getHeaders();

package/src/index.ts

@@ -0,0 +1,18 @@
+export const OXY_ACTIVITY_ID_HEADER = 'X-Oxy-Activity-Id';
+export const OXY_EDGE_REGION_HEADER = 'X-Oxy-Edge-Region';
+
+export interface AnonymousActivityMetadata {
+  activityId?: string;
+  edgePop?: string;
+}
+
+export interface ActivityAggregate {
+  sourceRegion?: string;
+  targetRegion: string;
+  service: string;
+  requests: number;
+  activeClients: number;
+  windowStartedAt: string;
+  emittedAt: string;
+  direction: 'inbound';
+}

package/src/server.ts

@@ -0,0 +1,70 @@
+import type { ActivityAggregate, AnonymousActivityMetadata } from './index.js';
+
+export const DEFAULT_PRESENCE_BUCKET_MS = 30_000;
+export const DEFAULT_ACTIVE_CLIENT_WINDOW_MS = 60_000;
+
+export type TelemetryHeaderValue = string | readonly string[] | undefined;
+export type TelemetryHeaders = Readonly<Record<string, TelemetryHeaderValue>>;
+
+export interface ActivityCardinalityAdapter {
+  add(key: string, activityId: string, ttlSeconds: number): Promise<void>;
+  count(keys: readonly string[]): Promise<number>;
+}
+
+export interface ActivityFlow {
+  sourceRegion?: string;
+  service: string;
+  key: string;
+}
+
+function firstHeaderValue(value: TelemetryHeaderValue): string | undefined {
+  if (typeof value === 'string') return value;
+  const first = value?.[0];
+  return typeof first === 'string' ? first : undefined;
+}
+
+export function normalizeEdgePop(value: TelemetryHeaderValue): string | undefined {
+  return firstHeaderValue(value)?.match(/^[a-z]{3}$/i)?.[0]?.toLowerCase();
+}
+
+export function normalizeActivityId(value: TelemetryHeaderValue): string | undefined {
+  const candidate = firstHeaderValue(value);
+  return candidate && /^[a-z0-9_-]{16,64}$/i.test(candidate) ? candidate : undefined;
+}
+
+export function metadataFromHeaders(headers: TelemetryHeaders): AnonymousActivityMetadata {
+  const forwardedPop = normalizeEdgePop(headers['x-oxy-edge-region']);
+  const ray = firstHeaderValue(headers['cf-ray']);
+  const rayPop = ray?.match(/-([a-z]{3})$/i)?.[1]?.toLowerCase();
+  const activityId = normalizeActivityId(headers['x-oxy-activity-id']);
+  return {
+    ...(activityId ? { activityId } : {}),
+    ...(forwardedPop || rayPop ? { edgePop: forwardedPop ?? rayPop } : {}),
+  };
+}
+
+export function serviceFromPath(path: string): string {
+  const segment = path.split('/').filter(Boolean)[0];
+  return segment && /^[a-z][a-z0-9-]{0,31}$/i.test(segment) ? segment.toLowerCase() : 'platform';
+}
+
+export function activityFlow(sourceRegion: string | undefined, service: string): ActivityFlow {
+  return { sourceRegion, service, key: `${sourceRegion ?? ''}|${service}` };
+}
+
+export function presenceBucket(observedAt: number, bucketMs = DEFAULT_PRESENCE_BUCKET_MS): number {
+  if (!Number.isFinite(observedAt) || !Number.isFinite(bucketMs) || bucketMs <= 0) {
+    throw new RangeError('observedAt and bucketMs must define a finite positive bucket');
+  }
+  return Math.floor(observedAt / bucketMs);
+}
+
+export function presenceKeys(sourceRegion: string, observedAt: number, bucketMs = DEFAULT_PRESENCE_BUCKET_MS): readonly [string, string] {
+  const current = presenceBucket(observedAt, bucketMs);
+  return [
+    `platform-activity:clients:${sourceRegion}:${current}`,
+    `platform-activity:clients:${sourceRegion}:${current - 1}`,
+  ];
+}
+
+export type ActivityBucket = ActivityAggregate;