@oxy.so/telemetry 1.0.0 → 1.1.1

package/dist/esm/collector.js

@@ -0,0 +1,171 @@
+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',
+};
+export function trafficType(path) {
+    const parts = path.split('?')[0].split('/').filter(Boolean);
+    if (parts[0] === 'alia')
+        parts.shift();
+    if (parts[0] === 'api')
+        parts.shift();
+    if (/^v\d+$/.test(parts[0] ?? ''))
+        parts.shift();
+    return TYPES[parts[0] ?? ''] ?? 'platform';
+}
+export function createTrafficCollector(publish, now = Date.now) {
+    const pending = new Map();
+    let flushing = null;
+    return {
+        record(flow) {
+            const key = JSON.stringify(flow);
+            const existing = pending.get(key);
+            if (existing)
+                existing.requests++;
+            else if (pending.size < 512)
+                pending.set(key, { flow, requests: 1, startedAt: now() });
+        },
+        async flush() {
+            while (flushing)
+                await flushing;
+            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 }));
+            pending.clear();
+            flushing = (async () => {
+                for (let offset = 0; offset < events.length; offset += 256)
+                    await publish(events.slice(offset, offset + 256));
+            })();
+            try {
+                await flushing;
+            }
+            finally {
+                flushing = null;
+            }
+        },
+    };
+}
+export function trafficMiddleware(collector, service, region) {
+    return (request, response, next) => {
+        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/')) {
+            next();
+            return;
+        }
+        const { edgePop } = metadataFromHeaders(request.headers);
+        const activityType = trafficType(path);
+        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 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 finish = () => {
+            if (finished)
+                return;
+            finished = true;
+            const flow = inboundFlow();
+            collector.record(flow);
+            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
+        // completed outbound response when the connection closes prematurely.
+        response.once('close', () => {
+            if (finished)
+                return;
+            finished = true;
+            collector.record(inboundFlow());
+        });
+        next();
+    };
+}
+export function instrumentTrafficFetch(fetcher, collector, service, region, resolveEndpoint) {
+    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')
+            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,
+        };
+        const headers = new Headers(init?.headers ?? (input instanceof Request ? input.headers : undefined));
+        if (peer)
+            headers.set('X-Oxy-Source-Region', region);
+        let response;
+        try {
+            response = await fetcher(input, { ...init, headers });
+        }
+        catch (error) {
+            collector.record({ ...flow, targetRegion: undefined });
+            throw error;
+        }
+        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 });
+        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',
+};
+export function resolveOxyServiceEndpoint(url) {
+    const service = OXY_API_SERVICES[url.hostname];
+    return url.protocol === 'https:' && service ? { service, region: 'us-west-2' } : undefined;
+}
+const REGION_LOCATIONS = {
+    'us-west-2': { label: 'Oregon', coordinates: [-122.6765, 45.5231] },
+    'us-west-1': { label: 'Northern California', coordinates: [-121.89, 37.34] },
+    'us-east-1': { label: 'Northern Virginia', coordinates: [-77.49, 39.04] },
+    'us-east-2': { label: 'Ohio', coordinates: [-82.99, 39.96] },
+    'eu-west-1': { label: 'Ireland', coordinates: [-6.26, 53.35] },
+    'eu-west-2': { label: 'London', coordinates: [-0.1276, 51.5072] },
+    'eu-west-3': { label: 'Paris', coordinates: [2.3522, 48.8566] },
+    'eu-central-1': { label: 'Frankfurt', coordinates: [8.6821, 50.1109] },
+    'eu-central-2': { label: 'Zurich', coordinates: [8.54, 47.38] },
+    'eu-north-1': { label: 'Stockholm', coordinates: [18.07, 59.33] },
+    'eu-south-1': { label: 'Milan', coordinates: [9.19, 45.46] },
+    'eu-south-2': { label: 'Spain', coordinates: [-0.89, 41.65] },
+    'ap-northeast-1': { label: 'Tokyo', coordinates: [139.69, 35.69] },
+    'ap-northeast-2': { label: 'Seoul', coordinates: [126.98, 37.57] },
+    'ap-northeast-3': { label: 'Osaka', coordinates: [135.5, 34.69] },
+    'ap-southeast-1': { label: 'Singapore', coordinates: [103.82, 1.35] },
+    'ap-southeast-2': { label: 'Sydney', coordinates: [151.21, -33.87] },
+    'ap-southeast-3': { label: 'Jakarta', coordinates: [106.85, -6.21] },
+    'ap-southeast-4': { label: 'Melbourne', coordinates: [144.96, -37.81] },
+    'ap-south-1': { label: 'Mumbai', coordinates: [72.88, 19.08] },
+    'ap-south-2': { label: 'Hyderabad', coordinates: [78.49, 17.38] },
+    'ap-east-1': { label: 'Hong Kong', coordinates: [114.17, 22.32] },
+    'ca-central-1': { label: 'Canada', coordinates: [-73.57, 45.5] },
+    'ca-west-1': { label: 'Calgary', coordinates: [-114.07, 51.05] },
+    'sa-east-1': { label: 'São Paulo', coordinates: [-46.63, -23.55] },
+    'af-south-1': { label: 'Cape Town', coordinates: [18.42, -33.92] },
+    'me-south-1': { label: 'Bahrain', coordinates: [50.59, 26.22] },
+    '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 normalizeInfrastructureRegion(value) {
+    return typeof value === 'string' && /^[a-z]{2}(?:-[a-z]+)+-\d$/.test(value) ? value : undefined;
+}

package/dist/esm/edge.js

@@ -0,0 +1,134 @@
+import { trafficType } from './collector.js';
+import { normalizeEdgePop } from './server.js';
+// Share values only: Workers prohibit I/O promises/bodies crossing request contexts.
+const tokens = new WeakMap();
+const CONTROL = /^\/(?:api\/)?(?:health|ready|live|platform-stats|platform-activity|platform-infrastructure|infra-status|internal\/activity|auth\/service-token|cdn-cgi)(?:\/|$)/;
+async function smallJson(response) {
+    if (!response.body)
+        throw new Error('Missing token response');
+    const reader = response.body.getReader();
+    const chunks = [];
+    let size = 0;
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            size += value.byteLength;
+            if (size > 16384) {
+                await reader.cancel();
+                throw new Error('Oversized token response');
+            }
+            chunks.push(value);
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+    const bytes = new Uint8Array(size);
+    let offset = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return JSON.parse(new TextDecoder().decode(bytes));
+}
+async function publish(options, events) {
+    const { env } = options;
+    const base = new URL(env.OXY_EDGE_ACTIVITY_API_URL ?? 'https://api.oxy.so');
+    if (base.protocol !== 'https:' || base.username || base.password || base.pathname !== '/' || base.search || base.hash)
+        throw new Error('Invalid activity origin');
+    const fetcher = options.fetcher ?? fetch;
+    const abort = new AbortController();
+    const timeout = setTimeout(() => abort.abort(), 4000);
+    try {
+        let token;
+        if (options.credential)
+            token = await Promise.race([
+                options.credential(),
+                new Promise((_, reject) => abort.signal.addEventListener('abort', () => reject(new Error('Activity credential timeout')), { once: true })),
+            ]);
+        else {
+            const key = env.OXY_EDGE_ACTIVITY_API_KEY;
+            const secret = env.OXY_EDGE_ACTIVITY_API_SECRET;
+            if (!key || !secret)
+                throw new Error('Missing edge activity credentials');
+            const cached = tokens.get(env);
+            if (cached && cached.key === key && cached.secret === secret && cached.origin === base.origin && cached.expiresAt > Date.now() + 60000)
+                token = cached.token;
+            else {
+                // Same exchange and expiry margin as OxyServices.getServiceToken().
+                const response = await fetcher(new URL('/auth/service-token', base), {
+                    method: 'POST', headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify({ apiKey: key, apiSecret: secret }), signal: abort.signal,
+                });
+                if (!response.ok) {
+                    await response.body?.cancel();
+                    throw new Error('Activity authentication failed');
+                }
+                const data = await smallJson(response);
+                if (typeof data.token !== 'string' || !data.token || typeof data.expiresIn !== 'number' || !Number.isFinite(data.expiresIn) || data.expiresIn <= 0)
+                    throw new Error('Invalid activity token');
+                token = data.token;
+                tokens.set(env, { key, secret, origin: base.origin, token, expiresAt: Date.now() + data.expiresIn * 1000 });
+            }
+        }
+        const response = await fetcher(new URL('/internal/activity', base), {
+            method: 'POST', headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${token}` },
+            body: JSON.stringify(events), signal: abort.signal,
+        });
+        if (response.status === 401)
+            tokens.delete(env);
+        await response.body?.cancel();
+        if (!response.ok)
+            throw new Error('Activity ingestion failed');
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+/** Returns the original response/stream and preserves original handler errors. */
+export async function observeEdgeRequest(options) {
+    const report = () => { try {
+        (options.onError ?? console.error)('Edge activity publication failed');
+    }
+    catch { /* Never break serving. */ } };
+    const enabled = options.env.OXY_EDGE_ACTIVITY_ENABLED;
+    if (enabled === undefined || enabled === 'false')
+        return options.next();
+    if (enabled !== 'true' || !/^[a-z][a-z0-9-]{0,39}$/.test(options.service)) {
+        report();
+        return options.next();
+    }
+    const path = new URL(options.request.url).pathname;
+    if (CONTROL.test(path))
+        return options.next();
+    const pop = normalizeEdgePop(typeof options.request.cf?.colo === 'string' ? options.request.cf.colo : undefined);
+    const region = pop ? `edge-${pop}` : 'unknown';
+    const startedAt = new Date().toISOString();
+    const complete = (response) => {
+        const contentType = response?.headers.get('Content-Type') ?? '';
+        const activityType = /^(?:image|audio|video)\//i.test(contentType) ? 'media' : trafficType(path);
+        const common = { service: options.service, region, scope: options.peer ? 'internal' : 'external', activityType, requests: 1, windowStartedAt: startedAt, emittedAt: new Date().toISOString() };
+        // The serving PoP is infrastructure metadata. Do not invent visitor location.
+        const events = [{ ...common, direction: 'inbound', sourceRegion: options.peer?.region, sourceService: options.peer?.service, targetRegion: region, targetService: options.service }];
+        if (response)
+            events.push({ ...common, direction: 'outbound', sourceRegion: region, sourceService: options.service, targetRegion: options.peer?.region, targetService: options.peer?.service });
+        try {
+            options.ctx.waitUntil(publish(options, events).catch(report));
+        }
+        catch {
+            report();
+        }
+    };
+    let response;
+    try {
+        response = await options.next();
+    }
+    catch (error) {
+        complete();
+        throw error;
+    }
+    complete(response);
+    return response;
+}

package/dist/esm/socket.js

@@ -0,0 +1,97 @@
+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',
+};
+/** Event names are reduced locally to five categories; payloads are never read. */
+export function socketTrafficType(event) {
+    return CATEGORIES[event.toLowerCase().split(/[:/._-]/, 1)[0]] ?? 'platform';
+}
+/**
+ * Observes application events only, once per local socket. Socket.IO catch-all
+ * hooks exclude acknowledgements, ping/pong and transport frames. Outgoing
+ * packets describe sends, not delivery acknowledgements. No connection ID,
+ * event name, IP, credential, room name or payload enters a traffic record.
+ */
+export function observeTrafficSocket(socket, collector, service, region, options = {}) {
+    if (/^\/platform-(?:activity|stats)(?:\/|$)/.test(socket.nsp?.name ?? ''))
+        return () => { };
+    let stopped = false;
+    const record = (event, direction) => {
+        if (stopped)
+            return;
+        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;
+        collector.record({
+            region, service, scope: peerService ? 'internal' : 'external', direction,
+            activityType: socketTrafficType(event),
+            sourceRegion: direction === 'inbound' ? peerRegion : region,
+            targetRegion: direction === 'inbound' ? region : peerRegion,
+            sourceService: direction === 'inbound' ? peerService : service,
+            targetService: direction === 'inbound' ? service : peerService,
+        });
+    };
+    const inbound = (event) => record(event, 'inbound');
+    const outbound = (event) => record(event, 'outbound');
+    const stop = () => {
+        if (stopped)
+            return;
+        stopped = true;
+        socket.offAny(inbound);
+        socket.offAnyOutgoing(outbound);
+        socket.off('disconnect', stop);
+    };
+    socket.onAny(inbound);
+    socket.onAnyOutgoing(outbound);
+    socket.once('disconnect', stop);
+    return stop;
+}
+/** Raw ws application messages. Sends are attempts, never delivery receipts. */
+export function observeTrafficWebSocket(socket, collector, service, region, options = {}) {
+    let stopped = false;
+    const record = (direction) => {
+        if (stopped)
+            return;
+        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;
+        collector.record({
+            service, region, scope: peerService ? 'internal' : 'external', direction,
+            activityType: options.activityType ?? 'communication',
+            sourceRegion: direction === 'inbound' ? peerRegion : region,
+            targetRegion: direction === 'inbound' ? region : peerRegion,
+            sourceService: direction === 'inbound' ? peerService : service,
+            targetService: direction === 'inbound' ? service : peerService,
+        });
+    };
+    const inbound = () => record('inbound');
+    const originalSend = socket.send;
+    const send = function (...args) {
+        const open = this.readyState === 1;
+        // Preserve overload arguments, callback identity, return value and throws.
+        const result = Reflect.apply(originalSend, this, args);
+        if (open)
+            record('outbound');
+        return result;
+    };
+    const stop = () => {
+        if (stopped)
+            return;
+        stopped = true;
+        socket.off('message', inbound);
+        socket.off('close', stop);
+        if (socket.send === send)
+            socket.send = originalSend;
+    };
+    socket.send = send;
+    socket.on('message', inbound);
+    socket.once('close', stop);
+    return stop;
+}

package/dist/types/browser.d.ts

@@ -1,5 +1,6 @@
 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;
 interface TraceResponse {
     ok: boolean;
     text(): Promise<string>;
@@ -7,6 +8,7 @@ interface TraceResponse {
 export interface BrowserTelemetryOptions {
     activityIdRotationMs?: number;
     edgeTraceTimeoutMs?: number;
+    edgeCacheMs?: number;
     now?: () => number;
     crypto?: Pick<Crypto, 'getRandomValues' | 'randomUUID'>;
     location?: Pick<Location, 'hostname' | 'protocol'>;

package/dist/types/collector.d.ts

@@ -0,0 +1,50 @@
+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 declare function trafficType(path: string): TrafficType;
+export declare function createTrafficCollector(publish: (events: TrafficAggregate[]) => Promise<unknown>, now?: () => number): {
+    record(flow: TrafficFlow): void;
+    flush(): Promise<void>;
+};
+interface HttpRequest {
+    headers: TelemetryHeaders;
+    path?: string;
+    url?: string;
+    serviceApp?: {
+        appName?: string;
+    };
+}
+interface HttpResponse {
+    once(event: string, listener: () => void): unknown;
+    setHeader?(name: string, value: string): unknown;
+}
+export declare function trafficMiddleware(collector: Pick<ReturnType<typeof createTrafficCollector>, 'record'>, service: string, region: string): (request: HttpRequest, response: HttpResponse, next: () => void) => void;
+export interface ServiceEndpoint {
+    service: string;
+    region: string;
+}
+export declare function instrumentTrafficFetch(fetcher: typeof fetch, collector: Pick<ReturnType<typeof createTrafficCollector>, 'record'>, service: string, region: string, resolveEndpoint: (url: URL) => ServiceEndpoint | undefined): typeof fetch;
+export declare function resolveOxyServiceEndpoint(url: URL): ServiceEndpoint | undefined;
+export declare function infrastructureLocation(region: string): {
+    label: string;
+    coordinates: [number, number];
+};
+export declare function normalizeInfrastructureRegion(value: unknown): string | undefined;
+export {};

package/dist/types/edge.d.ts

@@ -0,0 +1,32 @@
+/** Server-only bindings; never expose them through frontend build variables. */
+export interface EdgeActivityEnv {
+    OXY_EDGE_ACTIVITY_ENABLED?: string;
+    OXY_EDGE_ACTIVITY_API_KEY?: string;
+    OXY_EDGE_ACTIVITY_API_SECRET?: string;
+    OXY_EDGE_ACTIVITY_API_URL?: string;
+}
+export interface EdgeActivityContext {
+    waitUntil(promise: Promise<unknown>): void;
+}
+export interface EdgeActivityOptions {
+    service: string;
+    request: Request & {
+        cf?: {
+            colo?: unknown;
+        };
+    };
+    env: EdgeActivityEnv;
+    ctx: EdgeActivityContext;
+    next: () => Response | Promise<Response>;
+    credential?: () => Promise<string>;
+    fetcher?: typeof fetch;
+    /** Only supply after existing authentication verified this service identity. */
+    peer?: {
+        service: string;
+        region?: string;
+    };
+    /** Fixed message only: never credentials, URLs or upstream error bodies. */
+    onError?: (message: string) => void;
+}
+/** Returns the original response/stream and preserves original handler errors. */
+export declare function observeEdgeRequest(options: EdgeActivityOptions): Promise<Response>;

package/dist/types/socket.d.ts

@@ -0,0 +1,50 @@
+import { type TrafficFlow, type TrafficType } from './collector.js';
+import { type TelemetryHeaders } from './server.js';
+export interface TrafficSocket {
+    handshake: {
+        headers: TelemetryHeaders;
+    };
+    nsp?: {
+        name: string;
+    };
+    onAny(listener: (event: string) => void): unknown;
+    onAnyOutgoing(listener: (event: string) => void): unknown;
+    offAny(listener: (event: string) => void): unknown;
+    offAnyOutgoing(listener: (event: string) => void): unknown;
+    once(event: 'disconnect', listener: () => void): unknown;
+    off(event: 'disconnect', listener: () => void): unknown;
+}
+/** Event names are reduced locally to five categories; payloads are never read. */
+export declare function socketTrafficType(event: string): TrafficType;
+/**
+ * Observes application events only, once per local socket. Socket.IO catch-all
+ * hooks exclude acknowledgements, ping/pong and transport frames. Outgoing
+ * packets describe sends, not delivery acknowledgements. No connection ID,
+ * event name, IP, credential, room name or payload enters a traffic record.
+ */
+export declare function observeTrafficSocket(socket: TrafficSocket, collector: {
+    record(flow: TrafficFlow): void;
+}, service: string, region: string, options?: {
+    getPeer?: () => {
+        service: string;
+        region?: string;
+    } | undefined;
+}): () => void;
+export interface TrafficWebSocket {
+    readonly readyState: number;
+    send(...args: any[]): unknown;
+    on(event: 'message', listener: () => void): unknown;
+    once(event: 'close', listener: () => void): unknown;
+    off(event: 'message' | 'close', listener: () => void): unknown;
+}
+/** Raw ws application messages. Sends are attempts, never delivery receipts. */
+export declare function observeTrafficWebSocket(socket: TrafficWebSocket, collector: {
+    record(flow: TrafficFlow): void;
+}, service: string, region: string, options?: {
+    headers?: TelemetryHeaders;
+    activityType?: TrafficType;
+    getPeer?: () => {
+        service: string;
+        region?: string;
+    } | undefined;
+}): () => void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxy.so/telemetry",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "description": "Framework-agnostic anonymous activity telemetry primitives for Oxy services.",
   "type": "module",
   "main": "dist/cjs/index.js",
@@ -13,6 +13,15 @@
       ],
       "server": [
         "dist/types/server.d.ts"
+      ],
+      "collector": [
+        "dist/types/collector.d.ts"
+      ],
+      "socket": [
+        "dist/types/socket.d.ts"
+      ],
+      "edge": [
+        "dist/types/edge.d.ts"
       ]
     }
   },
@@ -62,7 +71,37 @@
         "default": "./dist/cjs/server.js"
       }
     },
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./collector": {
+      "import": {
+        "types": "./dist/types/collector.d.ts",
+        "default": "./dist/esm/collector.js"
+      },
+      "require": {
+        "types": "./dist/types/collector.d.ts",
+        "default": "./dist/cjs/collector.js"
+      }
+    },
+    "./socket": {
+      "import": {
+        "types": "./dist/types/socket.d.ts",
+        "default": "./dist/esm/socket.js"
+      },
+      "require": {
+        "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": [
     "dist",

package/src/__tests__/browser.test.ts

@@ -44,4 +44,25 @@ describe('browser telemetry', () => {
     await expect(telemetry.getEdgeRegionHeader()).resolves.toEqual({});
     expect(fetchTrace).not.toHaveBeenCalled();
   });
+  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 });
+    await expect(telemetry.getEdgeRegionHeader()).resolves.toEqual({ 'X-Oxy-Edge-Region': 'mad' });
+    edge = 'NRT';
+    now += 15_000;
+    await expect(telemetry.getEdgeRegionHeader()).resolves.toEqual({ 'X-Oxy-Edge-Region': 'nrt' });
+    expect(fetchTrace).toHaveBeenCalledTimes(2);
+  });
+
+  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 });
+    await expect(telemetry.getEdgeRegionHeader()).resolves.toEqual({});
+    now += 15_000;
+    await expect(telemetry.getEdgeRegionHeader()).resolves.toEqual({ 'X-Oxy-Edge-Region': 'syd' });
+  });
+
 });