@a14y/telemetry 0.1.0

package/dist/cjs/adapters/ga4-mp.d.ts

@@ -0,0 +1,10 @@
+import type { Adapter } from './types';
+export interface Ga4MpAdapterOptions {
+    measurementId: string;
+    apiSecret: string;
+    /** When true, target the GA4 DebugView endpoint (validates payload, surfaces in DebugView). */
+    debug?: boolean;
+    fetchImpl?: typeof fetch;
+    endpoint?: string;
+}
+export declare function createGa4MpAdapter(opts: Ga4MpAdapterOptions): Adapter;

package/dist/cjs/adapters/ga4-mp.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createGa4MpAdapter = createGa4MpAdapter;
+function createGa4MpAdapter(opts) {
+    const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
+    const host = opts.endpoint ?? 'https://www.google-analytics.com';
+    const path = opts.debug ? '/debug/mp/collect' : '/mp/collect';
+    return {
+        name: opts.debug ? 'ga4-mp-debug' : 'ga4-mp',
+        async send(payload) {
+            if (payload.events.length === 0)
+                return;
+            if (typeof fetchImpl !== 'function')
+                return;
+            const url = host +
+                path +
+                '?measurement_id=' +
+                encodeURIComponent(opts.measurementId) +
+                '&api_secret=' +
+                encodeURIComponent(opts.apiSecret);
+            const body = JSON.stringify({
+                client_id: payload.clientId,
+                events: payload.events.map((e) => ({ name: e.name, params: e.params })),
+            });
+            try {
+                await fetchImpl(url, {
+                    method: 'POST',
+                    headers: { 'content-type': 'application/json' },
+                    body,
+                });
+            }
+            catch {
+                // Network failures are swallowed.
+            }
+        },
+    };
+}

package/dist/cjs/adapters/noop.d.ts

@@ -0,0 +1,2 @@
+import type { Adapter } from './types';
+export declare const noopAdapter: Adapter;

package/dist/cjs/adapters/noop.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.noopAdapter = void 0;
+exports.noopAdapter = {
+    name: 'noop',
+    async send() {
+        // intentionally empty
+    },
+};

package/dist/cjs/adapters/types.d.ts

@@ -0,0 +1,9 @@
+import type { TelemetryEvent } from '../core/types';
+export interface AdapterPayload {
+    clientId: string;
+    events: TelemetryEvent[];
+}
+export interface Adapter {
+    readonly name: string;
+    send(payload: AdapterPayload): Promise<void>;
+}

package/dist/cjs/adapters/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/core/buckets.d.ts

@@ -0,0 +1,8 @@
+export type ScoreBucket = '0-25' | '26-50' | '51-75' | '76-100';
+export declare function bucketScore(n: number): ScoreBucket;
+export type PageCountBucket = '1' | '2-10' | '11-50' | '51-200' | '200+';
+export declare function bucketPageCount(n: number): PageCountBucket;
+export type IssueCountBucket = '0' | '1-2' | '3-5' | '6-10' | '11+';
+export declare function bucketIssueCount(n: number): IssueCountBucket;
+export type DurationBucket = 'lt_5s' | '5-30s' | '30s-2m' | '2-10m' | 'gt_10m';
+export declare function bucketDurationMs(ms: number): DurationBucket;

package/dist/cjs/core/buckets.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.bucketScore = bucketScore;
+exports.bucketPageCount = bucketPageCount;
+exports.bucketIssueCount = bucketIssueCount;
+exports.bucketDurationMs = bucketDurationMs;
+function bucketScore(n) {
+    if (!Number.isFinite(n) || n <= 25)
+        return '0-25';
+    if (n <= 50)
+        return '26-50';
+    if (n <= 75)
+        return '51-75';
+    return '76-100';
+}
+function bucketPageCount(n) {
+    if (!Number.isFinite(n) || n <= 1)
+        return '1';
+    if (n <= 10)
+        return '2-10';
+    if (n <= 50)
+        return '11-50';
+    if (n <= 200)
+        return '51-200';
+    return '200+';
+}
+function bucketIssueCount(n) {
+    if (!Number.isFinite(n) || n <= 0)
+        return '0';
+    if (n <= 2)
+        return '1-2';
+    if (n <= 5)
+        return '3-5';
+    if (n <= 10)
+        return '6-10';
+    return '11+';
+}
+function bucketDurationMs(ms) {
+    if (!Number.isFinite(ms) || ms < 5000)
+        return 'lt_5s';
+    if (ms < 30000)
+        return '5-30s';
+    if (ms < 120000)
+        return '30s-2m';
+    if (ms < 600000)
+        return '2-10m';
+    return 'gt_10m';
+}

package/dist/cjs/core/queue.d.ts

@@ -0,0 +1,9 @@
+/** Bounded FIFO that drops the oldest entry when full. */
+export declare class BoundedQueue<T> {
+    private readonly max;
+    private buf;
+    constructor(max: number);
+    push(item: T): void;
+    drain(maxBatch: number): T[];
+    get length(): number;
+}

package/dist/cjs/core/queue.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BoundedQueue = void 0;
+/** Bounded FIFO that drops the oldest entry when full. */
+class BoundedQueue {
+    constructor(max) {
+        this.max = max;
+        this.buf = [];
+    }
+    push(item) {
+        if (this.buf.length >= this.max)
+            this.buf.shift();
+        this.buf.push(item);
+    }
+    drain(maxBatch) {
+        return this.buf.splice(0, maxBatch);
+    }
+    get length() {
+        return this.buf.length;
+    }
+}
+exports.BoundedQueue = BoundedQueue;

package/dist/cjs/core/sanitize.d.ts

@@ -0,0 +1,8 @@
+import type { EventParamValue } from './types';
+export declare function errorClassName(e: unknown): string;
+export declare function isValidEventName(name: string): boolean;
+/**
+ * Strip PII-shaped keys, coerce values to GA4-compatible primitives, enforce
+ * GA4 length limits. Drops anything it can't safely send.
+ */
+export declare function sanitizeProps(props: Record<string, unknown>): Record<string, EventParamValue>;

package/dist/cjs/core/sanitize.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.errorClassName = errorClassName;
+exports.isValidEventName = isValidEventName;
+exports.sanitizeProps = sanitizeProps;
+const PII_KEY_RE = /url|href|host|email|\bip\b/i;
+const PATH_KEY_RE = /(^|_)path($|_)/i;
+const GA4_EVENT_NAME_RE = /^[a-zA-Z][a-zA-Z0-9_]{0,39}$/;
+const MAX_PARAM_NAME = 40;
+const MAX_STRING_VALUE = 100;
+const MAX_PARAMS_PER_EVENT = 25;
+const PATH_KEY_ALLOWLIST = new Set(['path_category']);
+function errorClassName(e) {
+    if (typeof e === 'object' &&
+        e !== null &&
+        typeof e.constructor?.name === 'string') {
+        return e.constructor.name;
+    }
+    return 'Error';
+}
+function isValidEventName(name) {
+    return GA4_EVENT_NAME_RE.test(name);
+}
+/**
+ * Strip PII-shaped keys, coerce values to GA4-compatible primitives, enforce
+ * GA4 length limits. Drops anything it can't safely send.
+ */
+function sanitizeProps(props) {
+    const out = {};
+    let count = 0;
+    for (const [key, raw] of Object.entries(props)) {
+        if (count >= MAX_PARAMS_PER_EVENT)
+            break;
+        if (raw === undefined || raw === null)
+            continue;
+        if (key.length === 0 || key.length > MAX_PARAM_NAME)
+            continue;
+        if (PII_KEY_RE.test(key))
+            continue;
+        if (PATH_KEY_RE.test(key) && !PATH_KEY_ALLOWLIST.has(key))
+            continue;
+        let value;
+        if (typeof raw === 'boolean' || typeof raw === 'number') {
+            if (typeof raw === 'number' && !Number.isFinite(raw))
+                continue;
+            value = raw;
+        }
+        else if (typeof raw === 'string') {
+            value = raw.slice(0, MAX_STRING_VALUE);
+        }
+        else {
+            continue;
+        }
+        out[key] = value;
+        count++;
+    }
+    return out;
+}

package/dist/cjs/core/session.d.ts

@@ -0,0 +1,16 @@
+import type { Adapter } from '../adapters/types';
+import type { AppName, ConfigProvider } from './types';
+export interface Session {
+    appName: AppName;
+    appVersion: string;
+    deviceId: string;
+    sessionId: string;
+    enabled: boolean;
+    adapter: Adapter;
+    configProvider: ConfigProvider;
+}
+export declare function setSession(s: Session): void;
+export declare function getSession(): Session | null;
+export declare function resetSession(): void;
+/** 16-hex-char session id. Not a security boundary — uniqueness within a run is enough. */
+export declare function newSessionId(): string;

package/dist/cjs/core/session.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setSession = setSession;
+exports.getSession = getSession;
+exports.resetSession = resetSession;
+exports.newSessionId = newSessionId;
+let session = null;
+function setSession(s) {
+    session = s;
+}
+function getSession() {
+    return session;
+}
+function resetSession() {
+    session = null;
+}
+/** 16-hex-char session id. Not a security boundary — uniqueness within a run is enough. */
+function newSessionId() {
+    const bytes = new Uint8Array(8);
+    const g = globalThis;
+    if (g.crypto?.getRandomValues) {
+        g.crypto.getRandomValues(bytes);
+    }
+    else {
+        for (let i = 0; i < 8; i++)
+            bytes[i] = Math.floor(Math.random() * 256);
+    }
+    return Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');
+}

package/dist/cjs/core/tracker.d.ts

@@ -0,0 +1,7 @@
+import type { InitOptions } from './types';
+export declare function init(opts: InitOptions): Promise<void>;
+export declare function track(name: string, props?: Record<string, unknown>): void;
+export declare function flush(): Promise<void>;
+export declare function setEnabled(enabled: boolean): Promise<void>;
+export declare function isEnabled(): boolean;
+export declare function shutdown(): void;

package/dist/cjs/core/tracker.js

@@ -0,0 +1,97 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.init = init;
+exports.track = track;
+exports.flush = flush;
+exports.setEnabled = setEnabled;
+exports.isEnabled = isEnabled;
+exports.shutdown = shutdown;
+const sanitize_1 = require("./sanitize");
+const queue_1 = require("./queue");
+const session_1 = require("./session");
+const DEFAULT_FLUSH_INTERVAL_MS = 5000;
+const DEFAULT_MAX_QUEUE = 100;
+const SEND_BATCH_SIZE = 25;
+let queue = new queue_1.BoundedQueue(DEFAULT_MAX_QUEUE);
+let flushTimer = null;
+async function init(opts) {
+    const enabled = opts.initiallyEnabled !== undefined
+        ? opts.initiallyEnabled
+        : await opts.configProvider.isEnabled();
+    let deviceId;
+    try {
+        deviceId = await opts.deviceIdProvider();
+    }
+    catch {
+        deviceId = (0, session_1.newSessionId)();
+    }
+    (0, session_1.setSession)({
+        appName: opts.appName,
+        appVersion: opts.appVersion,
+        deviceId,
+        sessionId: (0, session_1.newSessionId)(),
+        enabled,
+        adapter: opts.adapter,
+        configProvider: opts.configProvider,
+    });
+    queue = new queue_1.BoundedQueue(opts.maxQueue ?? DEFAULT_MAX_QUEUE);
+    if (flushTimer)
+        clearInterval(flushTimer);
+    const ms = opts.flushIntervalMs ?? DEFAULT_FLUSH_INTERVAL_MS;
+    flushTimer = setInterval(() => {
+        void flush();
+    }, ms);
+    const t = flushTimer;
+    if (typeof t.unref === 'function')
+        t.unref();
+}
+function track(name, props = {}) {
+    const s = (0, session_1.getSession)();
+    if (!s || !s.enabled)
+        return;
+    if (!(0, sanitize_1.isValidEventName)(name))
+        return;
+    const params = (0, sanitize_1.sanitizeProps)(props);
+    queue.push({ name, params, ts: Date.now() });
+}
+async function flush() {
+    const s = (0, session_1.getSession)();
+    if (!s)
+        return;
+    const batch = queue.drain(SEND_BATCH_SIZE);
+    if (batch.length === 0)
+        return;
+    const enveloped = batch.map((e) => ({
+        name: e.name,
+        ts: e.ts,
+        params: {
+            ...e.params,
+            app_name: s.appName,
+            app_version: s.appVersion,
+            session_id: s.sessionId,
+            engagement_time_msec: 1,
+        },
+    }));
+    try {
+        await s.adapter.send({ clientId: s.deviceId, events: enveloped });
+    }
+    catch {
+        // Telemetry never throws into the host app.
+    }
+}
+async function setEnabled(enabled) {
+    const s = (0, session_1.getSession)();
+    if (!s)
+        return;
+    s.enabled = enabled;
+    await s.configProvider.setEnabled(enabled);
+}
+function isEnabled() {
+    return (0, session_1.getSession)()?.enabled ?? false;
+}
+function shutdown() {
+    if (flushTimer)
+        clearInterval(flushTimer);
+    flushTimer = null;
+    (0, session_1.resetSession)();
+}

package/dist/cjs/core/types.d.ts

@@ -0,0 +1,25 @@
+import type { Adapter } from '../adapters/types';
+export type AppName = 'cli' | 'extension' | 'docs';
+export type EventName = 'cli_command_invoked' | 'cli_run_completed' | 'cli_error' | 'cli_telemetry_disabled' | 'ext_installed' | 'ext_audit_started' | 'ext_audit_completed' | 'ext_audit_error' | 'ext_settings_changed' | 'docs_section_view' | 'outbound_click';
+export type EventParamValue = string | number | boolean;
+export interface TelemetryEvent {
+    name: string;
+    params: Record<string, EventParamValue>;
+    ts: number;
+}
+export interface ConfigProvider {
+    isEnabled(): Promise<boolean>;
+    setEnabled(enabled: boolean): Promise<void>;
+}
+export type DeviceIdProvider = () => Promise<string>;
+export interface InitOptions {
+    appName: AppName;
+    appVersion: string;
+    adapter: Adapter;
+    deviceIdProvider: DeviceIdProvider;
+    configProvider: ConfigProvider;
+    flushIntervalMs?: number;
+    maxQueue?: number;
+    /** Override the resolved enabled state. When omitted, falls back to configProvider.isEnabled(). */
+    initiallyEnabled?: boolean;
+}

package/dist/cjs/core/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/index.d.ts

@@ -0,0 +1,7 @@
+export { init, track, setEnabled, isEnabled, flush, shutdown } from './core/tracker';
+export { bucketScore, bucketPageCount, bucketIssueCount, bucketDurationMs, type ScoreBucket, type PageCountBucket, type IssueCountBucket, type DurationBucket, } from './core/buckets';
+export { sanitizeProps, errorClassName, isValidEventName } from './core/sanitize';
+export type { AppName, EventName, EventParamValue, TelemetryEvent, ConfigProvider, DeviceIdProvider, InitOptions, } from './core/types';
+export { noopAdapter } from './adapters/noop';
+export { createGa4MpAdapter, type Ga4MpAdapterOptions } from './adapters/ga4-mp';
+export type { Adapter, AdapterPayload } from './adapters/types';

package/dist/cjs/index.js

@@ -0,0 +1,29 @@
+"use strict";
+// Public API for @a14y/telemetry — runtime-agnostic surface only.
+// Runtime helpers live behind subpath exports:
+//   import { createNodeRuntime } from '@a14y/telemetry/node';
+//   import { createChromeExtRuntime } from '@a14y/telemetry/chrome-ext';
+// Splitting them out keeps the extension bundle from pulling in `fs`/`os`
+// and the Node consumers from pulling in the chrome.* type surface.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createGa4MpAdapter = exports.noopAdapter = exports.isValidEventName = exports.errorClassName = exports.sanitizeProps = exports.bucketDurationMs = exports.bucketIssueCount = exports.bucketPageCount = exports.bucketScore = exports.shutdown = exports.flush = exports.isEnabled = exports.setEnabled = exports.track = exports.init = void 0;
+var tracker_1 = require("./core/tracker");
+Object.defineProperty(exports, "init", { enumerable: true, get: function () { return tracker_1.init; } });
+Object.defineProperty(exports, "track", { enumerable: true, get: function () { return tracker_1.track; } });
+Object.defineProperty(exports, "setEnabled", { enumerable: true, get: function () { return tracker_1.setEnabled; } });
+Object.defineProperty(exports, "isEnabled", { enumerable: true, get: function () { return tracker_1.isEnabled; } });
+Object.defineProperty(exports, "flush", { enumerable: true, get: function () { return tracker_1.flush; } });
+Object.defineProperty(exports, "shutdown", { enumerable: true, get: function () { return tracker_1.shutdown; } });
+var buckets_1 = require("./core/buckets");
+Object.defineProperty(exports, "bucketScore", { enumerable: true, get: function () { return buckets_1.bucketScore; } });
+Object.defineProperty(exports, "bucketPageCount", { enumerable: true, get: function () { return buckets_1.bucketPageCount; } });
+Object.defineProperty(exports, "bucketIssueCount", { enumerable: true, get: function () { return buckets_1.bucketIssueCount; } });
+Object.defineProperty(exports, "bucketDurationMs", { enumerable: true, get: function () { return buckets_1.bucketDurationMs; } });
+var sanitize_1 = require("./core/sanitize");
+Object.defineProperty(exports, "sanitizeProps", { enumerable: true, get: function () { return sanitize_1.sanitizeProps; } });
+Object.defineProperty(exports, "errorClassName", { enumerable: true, get: function () { return sanitize_1.errorClassName; } });
+Object.defineProperty(exports, "isValidEventName", { enumerable: true, get: function () { return sanitize_1.isValidEventName; } });
+var noop_1 = require("./adapters/noop");
+Object.defineProperty(exports, "noopAdapter", { enumerable: true, get: function () { return noop_1.noopAdapter; } });
+var ga4_mp_1 = require("./adapters/ga4-mp");
+Object.defineProperty(exports, "createGa4MpAdapter", { enumerable: true, get: function () { return ga4_mp_1.createGa4MpAdapter; } });

package/dist/cjs/runtime/chromeExt.d.ts

@@ -0,0 +1,8 @@
+import type { ConfigProvider, DeviceIdProvider } from '../core/types';
+export interface ChromeExtRuntime {
+    deviceIdProvider: DeviceIdProvider;
+    configProvider: ConfigProvider;
+    isNoticeShown(): Promise<boolean>;
+    markNoticeShown(): Promise<void>;
+}
+export declare function createChromeExtRuntime(): ChromeExtRuntime;

package/dist/cjs/runtime/chromeExt.js

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createChromeExtRuntime = createChromeExtRuntime;
+const STORAGE_KEY_DEVICE_ID = 'a14y:device-id';
+const STORAGE_KEY_SETTINGS = 'a14y:settings';
+function getStorage() {
+    const c = globalThis.chrome;
+    if (!c?.storage?.local) {
+        throw new Error('chrome.storage.local not available');
+    }
+    return c.storage.local;
+}
+function uuid() {
+    const g = globalThis;
+    if (g.crypto?.randomUUID)
+        return g.crypto.randomUUID();
+    const bytes = new Uint8Array(16);
+    if (g.crypto?.getRandomValues)
+        g.crypto.getRandomValues(bytes);
+    else
+        for (let i = 0; i < 16; i++)
+            bytes[i] = Math.floor(Math.random() * 256);
+    bytes[6] = (bytes[6] & 0x0f) | 0x40;
+    bytes[8] = (bytes[8] & 0x3f) | 0x80;
+    const hex = Array.from(bytes, (b) => b.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));
+}
+async function readSettings(storage) {
+    const got = await storage.get(STORAGE_KEY_SETTINGS);
+    const v = got[STORAGE_KEY_SETTINGS];
+    return v && typeof v === 'object' ? v : {};
+}
+async function writeSettings(storage, patch) {
+    const cur = await readSettings(storage);
+    await storage.set({ [STORAGE_KEY_SETTINGS]: { ...cur, ...patch } });
+}
+function createChromeExtRuntime() {
+    return {
+        async deviceIdProvider() {
+            const storage = getStorage();
+            const got = await storage.get(STORAGE_KEY_DEVICE_ID);
+            const existing = got[STORAGE_KEY_DEVICE_ID];
+            if (typeof existing === 'string' && existing.length > 0)
+                return existing;
+            const id = uuid();
+            await storage.set({ [STORAGE_KEY_DEVICE_ID]: id });
+            return id;
+        },
+        configProvider: {
+            async isEnabled() {
+                const storage = getStorage();
+                const settings = await readSettings(storage);
+                return settings.telemetryEnabled !== false;
+            },
+            async setEnabled(enabled) {
+                await writeSettings(getStorage(), { telemetryEnabled: enabled });
+            },
+        },
+        async isNoticeShown() {
+            const settings = await readSettings(getStorage());
+            return settings.telemetryNoticeShown === true;
+        },
+        async markNoticeShown() {
+            await writeSettings(getStorage(), { telemetryNoticeShown: true });
+        },
+    };
+}

package/dist/cjs/runtime/node.d.ts

@@ -0,0 +1,10 @@
+import type { ConfigProvider, DeviceIdProvider } from '../core/types';
+export interface NodeRuntime {
+    deviceIdProvider: DeviceIdProvider;
+    configProvider: ConfigProvider;
+    isFirstRunNoticeShown(): Promise<boolean>;
+    markFirstRunNoticeShown(): Promise<void>;
+    /** True when the on-disk config is unavailable and we're using ephemeral memory. */
+    isEphemeral(): boolean;
+}
+export declare function createNodeRuntime(): NodeRuntime;

package/dist/cjs/runtime/node.js

@@ -0,0 +1,104 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createNodeRuntime = createNodeRuntime;
+const fs_1 = require("fs");
+const os_1 = require("os");
+const path_1 = __importDefault(require("path"));
+const crypto_1 = require("crypto");
+function configDir() {
+    const xdg = process.env.XDG_CONFIG_HOME;
+    if (xdg && xdg.length > 0)
+        return path_1.default.join(xdg, 'a14y');
+    let home;
+    try {
+        home = (0, os_1.homedir)();
+    }
+    catch {
+        return null;
+    }
+    if (!home)
+        return null;
+    return path_1.default.join(home, '.a14y');
+}
+async function readConfigFile(dir) {
+    const file = path_1.default.join(dir, 'config.json');
+    try {
+        const raw = await fs_1.promises.readFile(file, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (parsed && typeof parsed === 'object')
+            return parsed;
+        return {};
+    }
+    catch {
+        return {};
+    }
+}
+async function writeConfigFile(dir, cfg) {
+    const file = path_1.default.join(dir, 'config.json');
+    const tmp = file + '.tmp';
+    await fs_1.promises.mkdir(dir, { recursive: true });
+    await fs_1.promises.writeFile(tmp, JSON.stringify(cfg, null, 2), 'utf8');
+    await fs_1.promises.rename(tmp, file);
+}
+function createNodeRuntime() {
+    const dir = configDir();
+    let ephemeral = null;
+    let forcedEphemeral = dir === null;
+    async function read() {
+        if (forcedEphemeral || dir === null) {
+            if (!ephemeral)
+                ephemeral = { deviceId: (0, crypto_1.randomUUID)(), telemetryEnabled: false };
+            return ephemeral;
+        }
+        return readConfigFile(dir);
+    }
+    async function update(updater) {
+        if (forcedEphemeral || dir === null) {
+            ephemeral = updater(ephemeral ?? {});
+            return;
+        }
+        const cur = await readConfigFile(dir);
+        const next = updater(cur);
+        try {
+            await writeConfigFile(dir, next);
+        }
+        catch {
+            forcedEphemeral = true;
+            ephemeral = { ...next, telemetryEnabled: false };
+        }
+    }
+    return {
+        async deviceIdProvider() {
+            const cfg = await read();
+            if (typeof cfg.deviceId === 'string' && cfg.deviceId.length > 0)
+                return cfg.deviceId;
+            const id = (0, crypto_1.randomUUID)();
+            await update((c) => ({ ...c, deviceId: id }));
+            return id;
+        },
+        configProvider: {
+            async isEnabled() {
+                if (forcedEphemeral)
+                    return false;
+                const cfg = await read();
+                return cfg.telemetryEnabled !== false;
+            },
+            async setEnabled(enabled) {
+                await update((c) => ({ ...c, telemetryEnabled: enabled }));
+            },
+        },
+        async isFirstRunNoticeShown() {
+            const cfg = await read();
+            return cfg.firstRunNoticeShown === true;
+        },
+        async markFirstRunNoticeShown() {
+            await update((c) => ({ ...c, firstRunNoticeShown: true }));
+        },
+        isEphemeral() {
+            return forcedEphemeral;
+        },
+    };
+}

package/dist/esm/adapters/ga4-mp.js

@@ -0,0 +1,34 @@
+export function createGa4MpAdapter(opts) {
+    const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
+    const host = opts.endpoint ?? 'https://www.google-analytics.com';
+    const path = opts.debug ? '/debug/mp/collect' : '/mp/collect';
+    return {
+        name: opts.debug ? 'ga4-mp-debug' : 'ga4-mp',
+        async send(payload) {
+            if (payload.events.length === 0)
+                return;
+            if (typeof fetchImpl !== 'function')
+                return;
+            const url = host +
+                path +
+                '?measurement_id=' +
+                encodeURIComponent(opts.measurementId) +
+                '&api_secret=' +
+                encodeURIComponent(opts.apiSecret);
+            const body = JSON.stringify({
+                client_id: payload.clientId,
+                events: payload.events.map((e) => ({ name: e.name, params: e.params })),
+            });
+            try {
+                await fetchImpl(url, {
+                    method: 'POST',
+                    headers: { 'content-type': 'application/json' },
+                    body,
+                });
+            }
+            catch {
+                // Network failures are swallowed.
+            }
+        },
+    };
+}

package/dist/esm/adapters/noop.js

@@ -0,0 +1,6 @@
+export const noopAdapter = {
+    name: 'noop',
+    async send() {
+        // intentionally empty
+    },
+};

package/dist/esm/adapters/types.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/core/buckets.js

@@ -0,0 +1,42 @@
+export function bucketScore(n) {
+    if (!Number.isFinite(n) || n <= 25)
+        return '0-25';
+    if (n <= 50)
+        return '26-50';
+    if (n <= 75)
+        return '51-75';
+    return '76-100';
+}
+export function bucketPageCount(n) {
+    if (!Number.isFinite(n) || n <= 1)
+        return '1';
+    if (n <= 10)
+        return '2-10';
+    if (n <= 50)
+        return '11-50';
+    if (n <= 200)
+        return '51-200';
+    return '200+';
+}
+export function bucketIssueCount(n) {
+    if (!Number.isFinite(n) || n <= 0)
+        return '0';
+    if (n <= 2)
+        return '1-2';
+    if (n <= 5)
+        return '3-5';
+    if (n <= 10)
+        return '6-10';
+    return '11+';
+}
+export function bucketDurationMs(ms) {
+    if (!Number.isFinite(ms) || ms < 5000)
+        return 'lt_5s';
+    if (ms < 30000)
+        return '5-30s';
+    if (ms < 120000)
+        return '30s-2m';
+    if (ms < 600000)
+        return '2-10m';
+    return 'gt_10m';
+}

package/dist/esm/core/queue.js

@@ -0,0 +1,18 @@
+/** Bounded FIFO that drops the oldest entry when full. */
+export class BoundedQueue {
+    constructor(max) {
+        this.max = max;
+        this.buf = [];
+    }
+    push(item) {
+        if (this.buf.length >= this.max)
+            this.buf.shift();
+        this.buf.push(item);
+    }
+    drain(maxBatch) {
+        return this.buf.splice(0, maxBatch);
+    }
+    get length() {
+        return this.buf.length;
+    }
+}

package/dist/esm/core/sanitize.js

@@ -0,0 +1,53 @@
+const PII_KEY_RE = /url|href|host|email|\bip\b/i;
+const PATH_KEY_RE = /(^|_)path($|_)/i;
+const GA4_EVENT_NAME_RE = /^[a-zA-Z][a-zA-Z0-9_]{0,39}$/;
+const MAX_PARAM_NAME = 40;
+const MAX_STRING_VALUE = 100;
+const MAX_PARAMS_PER_EVENT = 25;
+const PATH_KEY_ALLOWLIST = new Set(['path_category']);
+export function errorClassName(e) {
+    if (typeof e === 'object' &&
+        e !== null &&
+        typeof e.constructor?.name === 'string') {
+        return e.constructor.name;
+    }
+    return 'Error';
+}
+export function isValidEventName(name) {
+    return GA4_EVENT_NAME_RE.test(name);
+}
+/**
+ * Strip PII-shaped keys, coerce values to GA4-compatible primitives, enforce
+ * GA4 length limits. Drops anything it can't safely send.
+ */
+export function sanitizeProps(props) {
+    const out = {};
+    let count = 0;
+    for (const [key, raw] of Object.entries(props)) {
+        if (count >= MAX_PARAMS_PER_EVENT)
+            break;
+        if (raw === undefined || raw === null)
+            continue;
+        if (key.length === 0 || key.length > MAX_PARAM_NAME)
+            continue;
+        if (PII_KEY_RE.test(key))
+            continue;
+        if (PATH_KEY_RE.test(key) && !PATH_KEY_ALLOWLIST.has(key))
+            continue;
+        let value;
+        if (typeof raw === 'boolean' || typeof raw === 'number') {
+            if (typeof raw === 'number' && !Number.isFinite(raw))
+                continue;
+            value = raw;
+        }
+        else if (typeof raw === 'string') {
+            value = raw.slice(0, MAX_STRING_VALUE);
+        }
+        else {
+            continue;
+        }
+        out[key] = value;
+        count++;
+    }
+    return out;
+}

package/dist/esm/core/session.js

@@ -0,0 +1,23 @@
+let session = null;
+export function setSession(s) {
+    session = s;
+}
+export function getSession() {
+    return session;
+}
+export function resetSession() {
+    session = null;
+}
+/** 16-hex-char session id. Not a security boundary — uniqueness within a run is enough. */
+export function newSessionId() {
+    const bytes = new Uint8Array(8);
+    const g = globalThis;
+    if (g.crypto?.getRandomValues) {
+        g.crypto.getRandomValues(bytes);
+    }
+    else {
+        for (let i = 0; i < 8; i++)
+            bytes[i] = Math.floor(Math.random() * 256);
+    }
+    return Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');
+}

package/dist/esm/core/tracker.js

@@ -0,0 +1,89 @@
+import { sanitizeProps, isValidEventName } from './sanitize';
+import { BoundedQueue } from './queue';
+import { setSession, getSession, resetSession, newSessionId } from './session';
+const DEFAULT_FLUSH_INTERVAL_MS = 5000;
+const DEFAULT_MAX_QUEUE = 100;
+const SEND_BATCH_SIZE = 25;
+let queue = new BoundedQueue(DEFAULT_MAX_QUEUE);
+let flushTimer = null;
+export async function init(opts) {
+    const enabled = opts.initiallyEnabled !== undefined
+        ? opts.initiallyEnabled
+        : await opts.configProvider.isEnabled();
+    let deviceId;
+    try {
+        deviceId = await opts.deviceIdProvider();
+    }
+    catch {
+        deviceId = newSessionId();
+    }
+    setSession({
+        appName: opts.appName,
+        appVersion: opts.appVersion,
+        deviceId,
+        sessionId: newSessionId(),
+        enabled,
+        adapter: opts.adapter,
+        configProvider: opts.configProvider,
+    });
+    queue = new BoundedQueue(opts.maxQueue ?? DEFAULT_MAX_QUEUE);
+    if (flushTimer)
+        clearInterval(flushTimer);
+    const ms = opts.flushIntervalMs ?? DEFAULT_FLUSH_INTERVAL_MS;
+    flushTimer = setInterval(() => {
+        void flush();
+    }, ms);
+    const t = flushTimer;
+    if (typeof t.unref === 'function')
+        t.unref();
+}
+export function track(name, props = {}) {
+    const s = getSession();
+    if (!s || !s.enabled)
+        return;
+    if (!isValidEventName(name))
+        return;
+    const params = sanitizeProps(props);
+    queue.push({ name, params, ts: Date.now() });
+}
+export async function flush() {
+    const s = getSession();
+    if (!s)
+        return;
+    const batch = queue.drain(SEND_BATCH_SIZE);
+    if (batch.length === 0)
+        return;
+    const enveloped = batch.map((e) => ({
+        name: e.name,
+        ts: e.ts,
+        params: {
+            ...e.params,
+            app_name: s.appName,
+            app_version: s.appVersion,
+            session_id: s.sessionId,
+            engagement_time_msec: 1,
+        },
+    }));
+    try {
+        await s.adapter.send({ clientId: s.deviceId, events: enveloped });
+    }
+    catch {
+        // Telemetry never throws into the host app.
+    }
+}
+export async function setEnabled(enabled) {
+    const s = getSession();
+    if (!s)
+        return;
+    s.enabled = enabled;
+    await s.configProvider.setEnabled(enabled);
+}
+export function isEnabled() {
+    return getSession()?.enabled ?? false;
+}
+export function shutdown() {
+    if (flushTimer)
+        clearInterval(flushTimer);
+    flushTimer = null;
+    resetSession();
+}

package/dist/esm/core/types.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/index.js

@@ -0,0 +1,11 @@
+// Public API for @a14y/telemetry — runtime-agnostic surface only.
+// Runtime helpers live behind subpath exports:
+//   import { createNodeRuntime } from '@a14y/telemetry/node';
+//   import { createChromeExtRuntime } from '@a14y/telemetry/chrome-ext';
+// Splitting them out keeps the extension bundle from pulling in `fs`/`os`
+// and the Node consumers from pulling in the chrome.* type surface.
+export { init, track, setEnabled, isEnabled, flush, shutdown } from './core/tracker';
+export { bucketScore, bucketPageCount, bucketIssueCount, bucketDurationMs, } from './core/buckets';
+export { sanitizeProps, errorClassName, isValidEventName } from './core/sanitize';
+export { noopAdapter } from './adapters/noop';
+export { createGa4MpAdapter } from './adapters/ga4-mp';

package/dist/esm/runtime/chromeExt.js

@@ -0,0 +1,72 @@
+const STORAGE_KEY_DEVICE_ID = 'a14y:device-id';
+const STORAGE_KEY_SETTINGS = 'a14y:settings';
+function getStorage() {
+    const c = globalThis.chrome;
+    if (!c?.storage?.local) {
+        throw new Error('chrome.storage.local not available');
+    }
+    return c.storage.local;
+}
+function uuid() {
+    const g = globalThis;
+    if (g.crypto?.randomUUID)
+        return g.crypto.randomUUID();
+    const bytes = new Uint8Array(16);
+    if (g.crypto?.getRandomValues)
+        g.crypto.getRandomValues(bytes);
+    else
+        for (let i = 0; i < 16; i++)
+            bytes[i] = Math.floor(Math.random() * 256);
+    bytes[6] = (bytes[6] & 0x0f) | 0x40;
+    bytes[8] = (bytes[8] & 0x3f) | 0x80;
+    const hex = Array.from(bytes, (b) => b.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));
+}
+async function readSettings(storage) {
+    const got = await storage.get(STORAGE_KEY_SETTINGS);
+    const v = got[STORAGE_KEY_SETTINGS];
+    return v && typeof v === 'object' ? v : {};
+}
+async function writeSettings(storage, patch) {
+    const cur = await readSettings(storage);
+    await storage.set({ [STORAGE_KEY_SETTINGS]: { ...cur, ...patch } });
+}
+export function createChromeExtRuntime() {
+    return {
+        async deviceIdProvider() {
+            const storage = getStorage();
+            const got = await storage.get(STORAGE_KEY_DEVICE_ID);
+            const existing = got[STORAGE_KEY_DEVICE_ID];
+            if (typeof existing === 'string' && existing.length > 0)
+                return existing;
+            const id = uuid();
+            await storage.set({ [STORAGE_KEY_DEVICE_ID]: id });
+            return id;
+        },
+        configProvider: {
+            async isEnabled() {
+                const storage = getStorage();
+                const settings = await readSettings(storage);
+                return settings.telemetryEnabled !== false;
+            },
+            async setEnabled(enabled) {
+                await writeSettings(getStorage(), { telemetryEnabled: enabled });
+            },
+        },
+        async isNoticeShown() {
+            const settings = await readSettings(getStorage());
+            return settings.telemetryNoticeShown === true;
+        },
+        async markNoticeShown() {
+            await writeSettings(getStorage(), { telemetryNoticeShown: true });
+        },
+    };
+}

package/dist/esm/runtime/node.js

@@ -0,0 +1,98 @@
+import { promises as fs } from 'fs';
+import { homedir } from 'os';
+import path from 'path';
+import { randomUUID } from 'crypto';
+function configDir() {
+    const xdg = process.env.XDG_CONFIG_HOME;
+    if (xdg && xdg.length > 0)
+        return path.join(xdg, 'a14y');
+    let home;
+    try {
+        home = homedir();
+    }
+    catch {
+        return null;
+    }
+    if (!home)
+        return null;
+    return path.join(home, '.a14y');
+}
+async function readConfigFile(dir) {
+    const file = path.join(dir, 'config.json');
+    try {
+        const raw = await fs.readFile(file, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (parsed && typeof parsed === 'object')
+            return parsed;
+        return {};
+    }
+    catch {
+        return {};
+    }
+}
+async function writeConfigFile(dir, cfg) {
+    const file = path.join(dir, 'config.json');
+    const tmp = file + '.tmp';
+    await fs.mkdir(dir, { recursive: true });
+    await fs.writeFile(tmp, JSON.stringify(cfg, null, 2), 'utf8');
+    await fs.rename(tmp, file);
+}
+export function createNodeRuntime() {
+    const dir = configDir();
+    let ephemeral = null;
+    let forcedEphemeral = dir === null;
+    async function read() {
+        if (forcedEphemeral || dir === null) {
+            if (!ephemeral)
+                ephemeral = { deviceId: randomUUID(), telemetryEnabled: false };
+            return ephemeral;
+        }
+        return readConfigFile(dir);
+    }
+    async function update(updater) {
+        if (forcedEphemeral || dir === null) {
+            ephemeral = updater(ephemeral ?? {});
+            return;
+        }
+        const cur = await readConfigFile(dir);
+        const next = updater(cur);
+        try {
+            await writeConfigFile(dir, next);
+        }
+        catch {
+            forcedEphemeral = true;
+            ephemeral = { ...next, telemetryEnabled: false };
+        }
+    }
+    return {
+        async deviceIdProvider() {
+            const cfg = await read();
+            if (typeof cfg.deviceId === 'string' && cfg.deviceId.length > 0)
+                return cfg.deviceId;
+            const id = randomUUID();
+            await update((c) => ({ ...c, deviceId: id }));
+            return id;
+        },
+        configProvider: {
+            async isEnabled() {
+                if (forcedEphemeral)
+                    return false;
+                const cfg = await read();
+                return cfg.telemetryEnabled !== false;
+            },
+            async setEnabled(enabled) {
+                await update((c) => ({ ...c, telemetryEnabled: enabled }));
+            },
+        },
+        async isFirstRunNoticeShown() {
+            const cfg = await read();
+            return cfg.firstRunNoticeShown === true;
+        },
+        async markFirstRunNoticeShown() {
+            await update((c) => ({ ...c, firstRunNoticeShown: true }));
+        },
+        isEphemeral() {
+            return forcedEphemeral;
+        },
+    };
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@a14y/telemetry",
+  "version": "0.1.0",
+  "description": "Anonymous, opt-out telemetry shim shared by the a14y CLI and Chrome extension. Provider-agnostic core with a built-in GA4 Measurement Protocol adapter.",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/timothyjordan/a14y.git",
+    "directory": "packages/telemetry"
+  },
+  "homepage": "https://a14y.dev",
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "dist/cjs/index.js",
+  "module": "dist/esm/index.js",
+  "types": "dist/cjs/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/cjs/index.d.ts",
+      "import": "./dist/esm/index.js",
+      "require": "./dist/cjs/index.js"
+    },
+    "./node": {
+      "types": "./dist/cjs/runtime/node.d.ts",
+      "import": "./dist/esm/runtime/node.js",
+      "require": "./dist/cjs/runtime/node.js"
+    },
+    "./chrome-ext": {
+      "types": "./dist/cjs/runtime/chromeExt.d.ts",
+      "import": "./dist/esm/runtime/chromeExt.js",
+      "require": "./dist/cjs/runtime/chromeExt.js"
+    }
+  },
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json && tsc -p tsconfig.esm.json",
+    "test": "vitest run"
+  },
+  "devDependencies": {
+    "@types/node": "^20.10.0",
+    "typescript": "^5.3.3",
+    "vitest": "^1.6.1"
+  }
+}