@oxy.so/telemetry 1.1.1 → 2.0.0

package/dist/esm/collector.js

@@ -1,10 +1,33 @@
 import { metadataFromHeaders } from './server.js';
 const TYPES = {
-    auth: 'identity', session: 'identity', users: 'identity', profiles: 'identity', accounts: 'identity',
-    ai: 'ai', inference: 'ai', models: 'ai', chat: 'ai', completions: 'ai',
-    stream: 'media', tracks: 'media', episodes: 'media', recordings: 'media', rooms: 'media',
-    messages: 'communication', notifications: 'communication', mail: 'communication',
-    media: 'media', files: 'media', assets: 'media', upload: 'media', uploads: 'media', cdn: 'media', storage: 'media', images: 'media', audio: 'media', videos: 'media',
+    auth: 'identity',
+    session: 'identity',
+    users: 'identity',
+    profiles: 'identity',
+    accounts: 'identity',
+    ai: 'ai',
+    inference: 'ai',
+    models: 'ai',
+    chat: 'ai',
+    completions: 'ai',
+    stream: 'media',
+    tracks: 'media',
+    episodes: 'media',
+    recordings: 'media',
+    rooms: 'media',
+    messages: 'communication',
+    notifications: 'communication',
+    mail: 'communication',
+    media: 'media',
+    files: 'media',
+    assets: 'media',
+    upload: 'media',
+    uploads: 'media',
+    cdn: 'media',
+    storage: 'media',
+    images: 'media',
+    audio: 'media',
+    videos: 'media',
 };
 export function trafficType(path) {
     const parts = path.split('?')[0].split('/').filter(Boolean);
@@ -34,7 +57,12 @@ export function createTrafficCollector(publish, now = Date.now) {
             if (pending.size === 0)
                 return;
             const emittedAt = new Date(now()).toISOString();
-            const events = [...pending.values()].map(({ flow, requests, startedAt }) => ({ ...flow, requests, windowStartedAt: new Date(startedAt).toISOString(), emittedAt }));
+            const events = [...pending.values()].map(({ flow, requests, startedAt }) => ({
+                ...flow,
+                requests,
+                windowStartedAt: new Date(startedAt).toISOString(),
+                emittedAt,
+            }));
             pending.clear();
             flushing = (async () => {
                 for (let offset = 0; offset < events.length; offset += 256)
@@ -54,7 +82,10 @@ export function trafficMiddleware(collector, service, region) {
         response.setHeader?.('X-Oxy-Region', 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 (/^\/(?: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/')) {
             next();
             return;
         }
@@ -63,11 +94,28 @@ export function trafficMiddleware(collector, service, region) {
         let finished = false;
         const inboundFlow = () => {
             // Read service identity AFTER the route's shared auth middleware resolved it.
-            const name = request.serviceApp?.appName?.toLowerCase().replace(/[^a-z0-9-]/g, '-').slice(0, 40);
+            const name = request.serviceApp?.appName
+                ?.toLowerCase()
+                .replace(/[^a-z0-9-]/g, '-')
+                .slice(0, 40);
             const internal = Boolean(name);
             const forwardedRegion = request.headers['x-oxy-source-region'];
-            const peerRegion = internal ? normalizeInfrastructureRegion(forwardedRegion) : edgePop ? `edge-${edgePop}` : undefined;
-            return { region, service, activityType, scope: internal ? 'internal' : 'external', direction: 'inbound', sourceRegion: peerRegion, targetRegion: region, sourceService: name, targetService: service };
+            const peerRegion = internal
+                ? normalizeInfrastructureRegion(forwardedRegion)
+                : edgePop
+                    ? `edge-${edgePop}`
+                    : undefined;
+            return {
+                region,
+                service,
+                activityType,
+                scope: internal ? 'internal' : 'external',
+                direction: 'inbound',
+                sourceRegion: peerRegion,
+                targetRegion: region,
+                sourceService: name,
+                targetService: service,
+            };
         };
         const finish = () => {
             if (finished)
@@ -75,7 +123,14 @@ export function trafficMiddleware(collector, service, region) {
             finished = true;
             const flow = inboundFlow();
             collector.record(flow);
-            collector.record({ ...flow, direction: 'outbound', sourceRegion: region, targetRegion: flow.sourceRegion, sourceService: service, targetService: flow.sourceService });
+            collector.record({
+                ...flow,
+                direction: 'outbound',
+                sourceRegion: region,
+                targetRegion: flow.sourceRegion,
+                sourceService: service,
+                targetService: flow.sourceService,
+            });
         };
         response.once('finish', finish);
         // Failed/aborted requests are still real inbound activity. Do not invent a
@@ -93,13 +148,21 @@ 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 (url.pathname.startsWith('/internal/activity') ||
+            url.pathname.startsWith('/auth/service-token') ||
+            url.pathname === '/platform-infrastructure')
             return fetcher(input, init);
         const peer = resolveEndpoint(url);
         const flow = {
-            service, region, scope: peer ? 'internal' : 'external', direction: 'outbound',
-            activityType: trafficType(url.pathname), sourceRegion: region, targetRegion: peer?.region,
-            sourceService: service, targetService: peer?.service,
+            service,
+            region,
+            scope: peer ? 'internal' : 'external',
+            direction: 'outbound',
+            activityType: trafficType(url.pathname),
+            sourceRegion: region,
+            targetRegion: peer?.region,
+            sourceService: service,
+            targetService: peer?.service,
         };
         const headers = new Headers(init?.headers ?? (input instanceof Request ? input.headers : undefined));
         if (peer)
@@ -112,23 +175,43 @@ export function instrumentTrafficFetch(fetcher, collector, service, region, reso
             collector.record({ ...flow, targetRegion: undefined });
             throw error;
         }
-        const targetRegion = peer ? normalizeInfrastructureRegion(response.headers.get('X-Oxy-Region') ?? undefined) : undefined;
+        const targetRegion = peer
+            ? normalizeInfrastructureRegion(response.headers.get('X-Oxy-Region') ?? undefined)
+            : undefined;
         collector.record({ ...flow, targetRegion });
-        collector.record({ ...flow, direction: 'inbound', sourceRegion: targetRegion, targetRegion: region, sourceService: peer?.service, targetService: service });
+        collector.record({
+            ...flow,
+            direction: 'inbound',
+            sourceRegion: targetRegion,
+            targetRegion: region,
+            sourceService: peer?.service,
+            targetService: service,
+        });
         return response;
     }, fetcher);
 }
 // Exact deployed API hosts; an arbitrary caller-supplied hostname cannot claim
 // 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', 'api.alia.onl': 'alia', 'kaana.ai': 'kaana',
-    'api.homiio.com': 'homiio', 'api.syra.fm': 'syra',
-    'mention.earth': 'mention', 'mcp.mention.earth': 'mention-mcp',
-    'api.clarity.surf': 'clarity', 'api.peable.to': 'peable',
-    'api.crowdsource.oxy.so': 'crowdsource', 'api.moovo.now': 'moovo',
-    'api.allo.you': 'allo', 'api.noted.oxy.so': 'noted', 'api.schedio.app': 'schedio', 'api.tnp.network': 'tnp-api',
+    'api.oxy.so': 'oxy-api',
+    'api.website.oxy.so': 'website',
+    'website-api.oxy.so': 'website',
+    'api.mention.earth': 'mention',
+    'api.mercaria.co': 'mercaria',
+    'api.alia.onl': 'alia',
+    'kaana.ai': 'kaana',
+    'api.homiio.com': 'homiio',
+    'api.syra.fm': 'syra',
+    'mention.earth': 'mention',
+    'mcp.mention.earth': 'mention-mcp',
+    'api.clarity.surf': 'clarity',
+    'api.peable.to': 'peable',
+    'api.crowdsource.oxy.so': 'crowdsource',
+    'api.moovo.now': 'moovo',
+    'api.allo.you': 'allo',
+    'api.noted.oxy.so': 'noted',
+    'api.schedio.app': 'schedio',
+    'api.tnp.network': 'tnp-api',
 };
 export function resolveOxyServiceEndpoint(url) {
     const service = OXY_API_SERVICES[url.hostname];
@@ -165,7 +248,9 @@ const REGION_LOCATIONS = {
     'me-central-1': { label: 'UAE', coordinates: [54.37, 24.45] },
     'il-central-1': { label: 'Tel Aviv', coordinates: [34.78, 32.09] },
 };
-export function infrastructureLocation(region) { return REGION_LOCATIONS[region]; }
+export function infrastructureLocation(region) {
+    return REGION_LOCATIONS[region];
+}
 export function normalizeInfrastructureRegion(value) {
     return typeof value === 'string' && /^[a-z]{2}(?:-[a-z]+)+-\d$/.test(value) ? value : undefined;
 }

package/dist/esm/server.js

@@ -7,7 +7,9 @@ function firstHeaderValue(value) {
     return typeof first === 'string' ? first : undefined;
 }
 export function normalizeEdgePop(value) {
-    return firstHeaderValue(value)?.match(/^[a-z]{3}$/i)?.[0]?.toLowerCase();
+    return firstHeaderValue(value)
+        ?.match(/^[a-z]{3}$/i)?.[0]
+        ?.toLowerCase();
 }
 export function normalizeActivityId(value) {
     const candidate = firstHeaderValue(value);

package/dist/esm/socket.js

@@ -1,11 +1,26 @@
 import { normalizeInfrastructureRegion } from './collector.js';
 import { metadataFromHeaders } from './server.js';
 const CATEGORIES = {
-    auth: 'identity', session: 'identity', user: 'identity', profile: 'identity',
-    chat: 'ai', agent: 'ai', inference: 'ai', completion: 'ai',
-    message: 'communication', notification: 'communication', typing: 'communication',
-    media: 'media', audio: 'media', video: 'media', stream: 'media', player: 'media',
-    track: 'media', playback: 'media', playlist: 'media', room: 'media',
+    auth: 'identity',
+    session: 'identity',
+    user: 'identity',
+    profile: 'identity',
+    chat: 'ai',
+    agent: 'ai',
+    inference: 'ai',
+    completion: 'ai',
+    message: 'communication',
+    notification: 'communication',
+    typing: 'communication',
+    media: 'media',
+    audio: 'media',
+    video: 'media',
+    stream: 'media',
+    player: 'media',
+    track: 'media',
+    playback: 'media',
+    playlist: 'media',
+    room: 'media',
 };
 /** Event names are reduced locally to five categories; payloads are never read. */
 export function socketTrafficType(event) {
@@ -27,9 +42,16 @@ export function observeTrafficSocket(socket, collector, service, region, options
         const peer = options.getPeer?.();
         const peerService = peer && /^[a-z][a-z0-9-]{0,39}$/.test(peer.service) ? peer.service : undefined;
         const edgePop = metadataFromHeaders(socket.handshake.headers).edgePop;
-        const peerRegion = peerService ? normalizeInfrastructureRegion(peer?.region) : edgePop ? `edge-${edgePop}` : undefined;
+        const peerRegion = peerService
+            ? normalizeInfrastructureRegion(peer?.region)
+            : edgePop
+                ? `edge-${edgePop}`
+                : undefined;
         collector.record({
-            region, service, scope: peerService ? 'internal' : 'external', direction,
+            region,
+            service,
+            scope: peerService ? 'internal' : 'external',
+            direction,
             activityType: socketTrafficType(event),
             sourceRegion: direction === 'inbound' ? peerRegion : region,
             targetRegion: direction === 'inbound' ? region : peerRegion,
@@ -61,9 +83,16 @@ export function observeTrafficWebSocket(socket, collector, service, region, opti
         const peer = options.getPeer?.();
         const peerService = peer && /^[a-z][a-z0-9-]{0,39}$/.test(peer.service) ? peer.service : undefined;
         const edgePop = metadataFromHeaders(options.headers ?? {}).edgePop;
-        const peerRegion = peerService ? normalizeInfrastructureRegion(peer?.region) : edgePop ? `edge-${edgePop}` : undefined;
+        const peerRegion = peerService
+            ? normalizeInfrastructureRegion(peer?.region)
+            : edgePop
+                ? `edge-${edgePop}`
+                : undefined;
         collector.record({
-            service, region, scope: peerService ? 'internal' : 'external', direction,
+            service,
+            region,
+            scope: peerService ? 'internal' : 'external',
+            direction,
             activityType: options.activityType ?? 'communication',
             sourceRegion: direction === 'inbound' ? peerRegion : region,
             targetRegion: direction === 'inbound' ? region : peerRegion,

package/dist/types/browser.d.ts

@@ -1,6 +1,12 @@
 export declare const DEFAULT_ACTIVITY_ID_ROTATION_MS: number;
 export declare const DEFAULT_EDGE_TRACE_TIMEOUT_MS = 1000;
 export declare const DEFAULT_EDGE_CACHE_MS = 15000;
+/**
+ * How long `peekEdgeRegionHeader` trusts a known PoP before refreshing it in the
+ * background. A client's serving PoP rarely changes within minutes, and the
+ * peek never blocks, so this only bounds the trace traffic.
+ */
+export declare const DEFAULT_EDGE_PEEK_REFRESH_MS: number;
 interface TraceResponse {
     ok: boolean;
     text(): Promise<string>;
@@ -9,6 +15,7 @@ export interface BrowserTelemetryOptions {
     activityIdRotationMs?: number;
     edgeTraceTimeoutMs?: number;
     edgeCacheMs?: number;
+    edgePeekRefreshMs?: number;
     now?: () => number;
     crypto?: Pick<Crypto, 'getRandomValues' | 'randomUUID'>;
     location?: Pick<Location, 'hostname' | 'protocol'>;
@@ -17,10 +24,17 @@ export interface BrowserTelemetryOptions {
 export interface BrowserTelemetry {
     getActivityIdHeader(): Record<string, string>;
     getEdgeRegionHeader(): Promise<Record<string, string>>;
+    /**
+     * The last known edge-region header, synchronously, never waiting on the
+     * trace: `{}` until the first discovery lands. A stale or missing value
+     * starts a refresh in the background.
+     */
+    peekEdgeRegionHeader(): 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 peekBrowserEdgeRegionHeader: () => Record<string, string>;
 export declare const getBrowserTelemetryHeaders: () => Promise<Record<string, string>>;
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxy.so/telemetry",
-  "version": "1.1.1",
+  "version": "2.0.0",
   "description": "Framework-agnostic anonymous activity telemetry primitives for Oxy services.",
   "type": "module",
   "main": "dist/cjs/index.js",
@@ -19,9 +19,6 @@
       ],
       "socket": [
         "dist/types/socket.d.ts"
-      ],
-      "edge": [
-        "dist/types/edge.d.ts"
       ]
     }
   },
@@ -91,16 +88,6 @@
         "types": "./dist/types/socket.d.ts",
         "default": "./dist/cjs/socket.js"
       }
-    },
-    "./edge": {
-      "import": {
-        "types": "./dist/types/edge.d.ts",
-        "default": "./dist/esm/edge.js"
-      },
-      "require": {
-        "types": "./dist/types/edge.d.ts",
-        "default": "./dist/cjs/edge.js"
-      }
     }
   },
   "files": [
@@ -109,10 +96,10 @@
   ],
   "repository": {
     "type": "git",
-    "url": "https://github.com/oxyhq/sdk",
+    "url": "git+https://github.com/OxyHQ/oxy.git",
     "directory": "packages/telemetry"
   },
-  "license": "Apache-2.0",
+  "license": "SEE LICENSE IN LICENSE",
   "author": "Oxy",
   "homepage": "https://oxy.so",
   "engines": {
@@ -130,10 +117,11 @@
     "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",
+    "socket.io": "^4.8.1",
+    "socket.io-client": "^4.8.1",
     "ts-jest": "^29.4.12",
     "typescript": "^5.9.2"
   }

package/src/__tests__/browser.test.ts

@@ -47,8 +47,15 @@ describe('browser telemetry', () => {
   it('rediscovers the edge after a VPN change without reloading the page', async () => {
     let now = 1_000;
     let edge = 'MAD';
-    const fetchTrace = jest.fn(async () => ({ ok: true, text: async () => `colo=${edge}\nip=203.0.113.8\nloc=ES` }));
-    const telemetry = createBrowserTelemetry({ location: { hostname: 'oxy.so', protocol: 'https:' }, now: () => now, fetchTrace });
+    const fetchTrace = jest.fn(async () => ({
+      ok: true,
+      text: async () => `colo=${edge}\nip=203.0.113.8\nloc=ES`,
+    }));
+    const telemetry = createBrowserTelemetry({
+      location: { hostname: 'oxy.so', protocol: 'https:' },
+      now: () => now,
+      fetchTrace,
+    });
     await expect(telemetry.getEdgeRegionHeader()).resolves.toEqual({ 'X-Oxy-Edge-Region': 'mad' });
     edge = 'NRT';
     now += 15_000;
@@ -58,11 +65,42 @@ describe('browser telemetry', () => {
 
   it('retries failed discovery on the next window instead of caching failure for the session', async () => {
     let now = 1_000;
-    const fetchTrace = jest.fn().mockRejectedValueOnce(new Error('offline')).mockResolvedValue({ ok: true, text: async () => 'colo=SYD' });
-    const telemetry = createBrowserTelemetry({ location: { hostname: 'oxy.so', protocol: 'https:' }, now: () => now, fetchTrace });
+    const fetchTrace = jest
+      .fn()
+      .mockRejectedValueOnce(new Error('offline'))
+      .mockResolvedValue({ ok: true, text: async () => 'colo=SYD' });
+    const telemetry = createBrowserTelemetry({
+      location: { hostname: 'oxy.so', protocol: 'https:' },
+      now: () => now,
+      fetchTrace,
+    });
     await expect(telemetry.getEdgeRegionHeader()).resolves.toEqual({});
     now += 15_000;
     await expect(telemetry.getEdgeRegionHeader()).resolves.toEqual({ 'X-Oxy-Edge-Region': 'syd' });
   });
+});
+
+describe('peekEdgeRegionHeader', () => {
+  it('never waits: {} first, the PoP once discovered, refreshed in the background', async () => {
+    let clock = 0;
+    const pops = ['mad', 'nrt'];
+    const telemetry = createBrowserTelemetry({
+      now: () => clock,
+      location: { hostname: 'app.oxy.so', protocol: 'https:' },
+      edgePeekRefreshMs: 1000,
+      fetchTrace: async () => ({
+        ok: true,
+        text: async () => `colo=${pops.shift()?.toUpperCase()}\n`,
+      }),
+    });
 
+    expect(telemetry.peekEdgeRegionHeader()).toEqual({});
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    expect(telemetry.peekEdgeRegionHeader()).toEqual({ 'X-Oxy-Edge-Region': 'mad' });
+
+    clock = 1000;
+    expect(telemetry.peekEdgeRegionHeader()).toEqual({ 'X-Oxy-Edge-Region': 'mad' });
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    expect(telemetry.peekEdgeRegionHeader()).toEqual({ 'X-Oxy-Edge-Region': 'nrt' });
+  });
 });