@agent-relay/telemetry 2.0.5

package/dist/client.d.ts

@@ -0,0 +1,19 @@
+/**
+ * PostHog telemetry client singleton.
+ */
+import { getAnonymousId } from './config.js';
+import type { TelemetryEventName, TelemetryEventMap } from './events.js';
+export declare function initTelemetry(options?: {
+    showNotice?: boolean;
+}): void;
+export declare function track<E extends TelemetryEventName>(event: E, properties?: TelemetryEventMap[E]): void;
+export declare function shutdown(): Promise<void>;
+export declare function isEnabled(): boolean;
+export { getAnonymousId };
+export declare function getStatus(): {
+    enabled: boolean;
+    disabledByEnv: boolean;
+    anonymousId: string;
+    notifiedAt: string | undefined;
+};
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;GAEG;AAOH,OAAO,EAEL,cAAc,EAKf,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAEV,kBAAkB,EAClB,iBAAiB,EAClB,MAAM,aAAa,CAAC;AA8DrB,wBAAgB,aAAa,CAAC,OAAO,GAAE;IAAE,UAAU,CAAC,EAAE,OAAO,CAAA;CAAO,GAAG,IAAI,CAqB1E;AAED,wBAAgB,KAAK,CAAC,CAAC,SAAS,kBAAkB,EAChD,KAAK,EAAE,CAAC,EACR,UAAU,CAAC,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAChC,IAAI,CAWN;AAED,wBAAsB,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAa9C;AAED,wBAAgB,SAAS,IAAI,OAAO,CAEnC;AAED,OAAO,EAAE,cAAc,EAAE,CAAC;AAE1B,wBAAgB,SAAS,IAAI;IAC3B,OAAO,EAAE,OAAO,CAAC;IACjB,aAAa,EAAE,OAAO,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;CAChC,CAQA"}

package/dist/client.js

@@ -0,0 +1,125 @@
+/**
+ * PostHog telemetry client singleton.
+ */
+import { PostHog } from 'posthog-node';
+import os from 'node:os';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { isTelemetryEnabled, getAnonymousId, wasNotified, markNotified, isDisabledByEnv, loadPrefs, } from './config.js';
+import { getPostHogConfig } from './posthog-config.js';
+let client = null;
+let commonProps = null;
+let anonymousId = null;
+let initialized = false;
+function findPackageJson(startDir) {
+    let dir = startDir;
+    while (dir !== path.dirname(dir)) {
+        const candidate = path.join(dir, 'package.json');
+        if (fs.existsSync(candidate)) {
+            return candidate;
+        }
+        dir = path.dirname(dir);
+    }
+    return null;
+}
+function getVersion() {
+    try {
+        const __filename = fileURLToPath(import.meta.url);
+        const __dirname = path.dirname(__filename);
+        const packageJsonPath = findPackageJson(__dirname);
+        if (packageJsonPath) {
+            const pkg = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'));
+            return pkg.version || 'unknown';
+        }
+    }
+    catch {
+        // Fall through
+    }
+    return 'unknown';
+}
+function buildCommonProperties() {
+    return {
+        agent_relay_version: getVersion(),
+        os: process.platform,
+        os_version: os.release(),
+        node_version: process.version.slice(1),
+        arch: process.arch,
+    };
+}
+function showFirstRunNotice() {
+    if (wasNotified())
+        return;
+    if (isDisabledByEnv()) {
+        markNotified();
+        return;
+    }
+    console.log('');
+    console.log('Agent Relay collects anonymous usage data to improve the product.');
+    console.log('Run `agent-relay telemetry disable` to opt out.');
+    console.log('Learn more: https://agent-relay.com/telemetry');
+    console.log('');
+    markNotified();
+}
+export function initTelemetry(options = {}) {
+    if (initialized)
+        return;
+    initialized = true;
+    if (options.showNotice !== false) {
+        showFirstRunNotice();
+    }
+    if (!isTelemetryEnabled())
+        return;
+    const posthogConfig = getPostHogConfig();
+    if (!posthogConfig)
+        return;
+    client = new PostHog(posthogConfig.apiKey, {
+        host: posthogConfig.host,
+        flushAt: 10,
+        flushInterval: 10000,
+    });
+    commonProps = buildCommonProperties();
+    anonymousId = getAnonymousId();
+}
+export function track(event, properties) {
+    if (!client || !commonProps || !anonymousId)
+        return;
+    client.capture({
+        distinctId: anonymousId,
+        event,
+        properties: {
+            ...commonProps,
+            ...properties,
+        },
+    });
+}
+export async function shutdown() {
+    if (!client)
+        return;
+    try {
+        await client.shutdown();
+    }
+    catch {
+        // Ignore
+    }
+    finally {
+        client = null;
+        commonProps = null;
+        anonymousId = null;
+        initialized = false;
+    }
+}
+export function isEnabled() {
+    return isTelemetryEnabled();
+}
+export { getAnonymousId };
+export function getStatus() {
+    const prefs = loadPrefs();
+    return {
+        enabled: isTelemetryEnabled(),
+        disabledByEnv: isDisabledByEnv(),
+        anonymousId: prefs.anonymousId,
+        notifiedAt: prefs.notifiedAt,
+    };
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/config.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Telemetry preference storage (~/.agent-relay/telemetry.json)
+ */
+export interface TelemetryPrefs {
+    enabled: boolean;
+    notifiedAt?: string;
+    anonymousId: string;
+}
+export declare function getPrefsPath(): string;
+export declare function loadPrefs(): TelemetryPrefs;
+export declare function savePrefs(prefs: TelemetryPrefs): void;
+export declare function isDisabledByEnv(): boolean;
+/**
+ * Check if telemetry is enabled.
+ * Priority: env var > stored pref > default (enabled)
+ */
+export declare function isTelemetryEnabled(): boolean;
+export declare function enableTelemetry(): void;
+export declare function disableTelemetry(): void;
+export declare function markNotified(): void;
+export declare function wasNotified(): boolean;
+export declare function getAnonymousId(): string;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;GAEG;AAOH,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,wBAAgB,YAAY,IAAI,MAAM,CAIrC;AAED,wBAAgB,SAAS,IAAI,cAAc,CA2B1C;AAED,wBAAgB,SAAS,CAAC,KAAK,EAAE,cAAc,GAAG,IAAI,CAUrD;AAED,wBAAgB,eAAe,IAAI,OAAO,CAGzC;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,IAAI,OAAO,CAK5C;AAED,wBAAgB,eAAe,IAAI,IAAI,CAItC;AAED,wBAAgB,gBAAgB,IAAI,IAAI,CAIvC;AAED,wBAAgB,YAAY,IAAI,IAAI,CAInC;AAED,wBAAgB,WAAW,IAAI,OAAO,CAErC;AAED,wBAAgB,cAAc,IAAI,MAAM,CAEvC"}

package/dist/config.js

@@ -0,0 +1,84 @@
+/**
+ * Telemetry preference storage (~/.agent-relay/telemetry.json)
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { createAnonymousId } from './machine-id.js';
+export function getPrefsPath() {
+    const configDir = process.env.AGENT_RELAY_DATA_DIR ||
+        path.join(os.homedir(), '.agent-relay');
+    return path.join(configDir, 'telemetry.json');
+}
+export function loadPrefs() {
+    const prefsPath = getPrefsPath();
+    try {
+        if (fs.existsSync(prefsPath)) {
+            const content = fs.readFileSync(prefsPath, 'utf-8');
+            const prefs = JSON.parse(content);
+            if (!prefs.anonymousId) {
+                prefs.anonymousId = createAnonymousId();
+                savePrefs(prefs);
+            }
+            return {
+                enabled: prefs.enabled ?? true,
+                notifiedAt: prefs.notifiedAt,
+                anonymousId: prefs.anonymousId,
+            };
+        }
+    }
+    catch {
+        // Fall through to defaults
+    }
+    return {
+        enabled: true,
+        anonymousId: createAnonymousId(),
+    };
+}
+export function savePrefs(prefs) {
+    const prefsPath = getPrefsPath();
+    const configDir = path.dirname(prefsPath);
+    try {
+        fs.mkdirSync(configDir, { recursive: true });
+        fs.writeFileSync(prefsPath, JSON.stringify(prefs, null, 2), 'utf-8');
+    }
+    catch (err) {
+        console.error('[telemetry] Failed to save preferences:', err);
+    }
+}
+export function isDisabledByEnv() {
+    const envValue = process.env.AGENT_RELAY_TELEMETRY_DISABLED;
+    return envValue === '1' || envValue === 'true';
+}
+/**
+ * Check if telemetry is enabled.
+ * Priority: env var > stored pref > default (enabled)
+ */
+export function isTelemetryEnabled() {
+    if (isDisabledByEnv()) {
+        return false;
+    }
+    return loadPrefs().enabled;
+}
+export function enableTelemetry() {
+    const prefs = loadPrefs();
+    prefs.enabled = true;
+    savePrefs(prefs);
+}
+export function disableTelemetry() {
+    const prefs = loadPrefs();
+    prefs.enabled = false;
+    savePrefs(prefs);
+}
+export function markNotified() {
+    const prefs = loadPrefs();
+    prefs.notifiedAt = new Date().toISOString();
+    savePrefs(prefs);
+}
+export function wasNotified() {
+    return loadPrefs().notifiedAt !== undefined;
+}
+export function getAnonymousId() {
+    return loadPrefs().anonymousId;
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}

package/dist/events.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Telemetry event definitions (PostHog naming: snake_case, present tense)
+ */
+export type ActionSource = 'human_cli' | 'human_dashboard' | 'agent' | 'protocol';
+export type ReleaseReason = 'explicit' | 'crash' | 'timeout' | 'shutdown';
+export interface CommonProperties {
+    agent_relay_version: string;
+    os: string;
+    os_version: string;
+    node_version: string;
+    arch: string;
+}
+export interface DaemonStartEvent {
+}
+export interface DaemonStopEvent {
+    uptime_seconds: number;
+    agent_spawn_count: number;
+}
+export interface AgentSpawnEvent {
+    cli: string;
+    spawn_source: ActionSource;
+    has_task: boolean;
+    is_shadow: boolean;
+}
+export interface AgentReleaseEvent {
+    cli: string;
+    release_reason: ReleaseReason;
+    lifetime_seconds: number;
+    release_source: ActionSource;
+}
+export interface AgentCrashEvent {
+    cli: string;
+    lifetime_seconds: number;
+    exit_code?: number;
+}
+export interface MessageSendEvent {
+    is_broadcast: boolean;
+    has_thread: boolean;
+}
+export interface CliCommandRunEvent {
+    command_name: string;
+}
+export type TelemetryEventName = 'daemon_start' | 'daemon_stop' | 'agent_spawn' | 'agent_release' | 'agent_crash' | 'message_send' | 'cli_command_run';
+export interface TelemetryEventMap {
+    daemon_start: DaemonStartEvent;
+    daemon_stop: DaemonStopEvent;
+    agent_spawn: AgentSpawnEvent;
+    agent_release: AgentReleaseEvent;
+    agent_crash: AgentCrashEvent;
+    message_send: MessageSendEvent;
+    cli_command_run: CliCommandRunEvent;
+}
+//# sourceMappingURL=events.d.ts.map

package/dist/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,MAAM,YAAY,GAAG,WAAW,GAAG,iBAAiB,GAAG,OAAO,GAAG,UAAU,CAAC;AAClF,MAAM,MAAM,aAAa,GAAG,UAAU,GAAG,OAAO,GAAG,SAAS,GAAG,UAAU,CAAC;AAE1E,MAAM,WAAW,gBAAgB;IAC/B,mBAAmB,EAAE,MAAM,CAAC;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,gBAAgB;CAAG;AAEpC,MAAM,WAAW,eAAe;IAC9B,cAAc,EAAE,MAAM,CAAC;IACvB,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,EAAE,YAAY,CAAC;IAC3B,QAAQ,EAAE,OAAO,CAAC;IAClB,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,iBAAiB;IAChC,GAAG,EAAE,MAAM,CAAC;IACZ,cAAc,EAAE,aAAa,CAAC;IAC9B,gBAAgB,EAAE,MAAM,CAAC;IACzB,cAAc,EAAE,YAAY,CAAC;CAC9B;AAED,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,gBAAgB,EAAE,MAAM,CAAC;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,gBAAgB;IAC/B,YAAY,EAAE,OAAO,CAAC;IACtB,UAAU,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,kBAAkB;IACjC,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,MAAM,kBAAkB,GAC1B,cAAc,GACd,aAAa,GACb,aAAa,GACb,eAAe,GACf,aAAa,GACb,cAAc,GACd,iBAAiB,CAAC;AAEtB,MAAM,WAAW,iBAAiB;IAChC,YAAY,EAAE,gBAAgB,CAAC;IAC/B,WAAW,EAAE,eAAe,CAAC;IAC7B,WAAW,EAAE,eAAe,CAAC;IAC7B,aAAa,EAAE,iBAAiB,CAAC;IACjC,WAAW,EAAE,eAAe,CAAC;IAC7B,YAAY,EAAE,gBAAgB,CAAC;IAC/B,eAAe,EAAE,kBAAkB,CAAC;CACrC"}

package/dist/events.js

@@ -0,0 +1,5 @@
+/**
+ * Telemetry event definitions (PostHog naming: snake_case, present tense)
+ */
+export {};
+//# sourceMappingURL=events.js.map

package/dist/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * @agent-relay/telemetry - Anonymous usage analytics (opt-out via env or CLI)
+ */
+export { initTelemetry, track, shutdown, isEnabled, getAnonymousId, getStatus, } from './client.js';
+export { isTelemetryEnabled, enableTelemetry, disableTelemetry, wasNotified, markNotified, loadPrefs, savePrefs, getPrefsPath, isDisabledByEnv, type TelemetryPrefs, } from './config.js';
+export type { CommonProperties, ActionSource, ReleaseReason, DaemonStartEvent, DaemonStopEvent, AgentSpawnEvent, AgentReleaseEvent, AgentCrashEvent, MessageSendEvent, CliCommandRunEvent, TelemetryEventName, TelemetryEventMap, } from './events.js';
+export { loadMachineId, createAnonymousId, getMachineIdPath, } from './machine-id.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EACL,aAAa,EACb,KAAK,EACL,QAAQ,EACR,SAAS,EACT,cAAc,EACd,SAAS,GACV,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,kBAAkB,EAClB,eAAe,EACf,gBAAgB,EAChB,WAAW,EACX,YAAY,EACZ,SAAS,EACT,SAAS,EACT,YAAY,EACZ,eAAe,EACf,KAAK,cAAc,GACpB,MAAM,aAAa,CAAC;AAErB,YAAY,EACV,gBAAgB,EAChB,YAAY,EACZ,aAAa,EACb,gBAAgB,EAChB,eAAe,EACf,eAAe,EACf,iBAAiB,EACjB,eAAe,EACf,gBAAgB,EAChB,kBAAkB,EAClB,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,aAAa,EACb,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,iBAAiB,CAAC"}

package/dist/index.js

@@ -0,0 +1,7 @@
+/**
+ * @agent-relay/telemetry - Anonymous usage analytics (opt-out via env or CLI)
+ */
+export { initTelemetry, track, shutdown, isEnabled, getAnonymousId, getStatus, } from './client.js';
+export { isTelemetryEnabled, enableTelemetry, disableTelemetry, wasNotified, markNotified, loadPrefs, savePrefs, getPrefsPath, isDisabledByEnv, } from './config.js';
+export { loadMachineId, createAnonymousId, getMachineIdPath, } from './machine-id.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EACL,aAAa,EACb,KAAK,EACL,QAAQ,EACR,SAAS,EACT,cAAc,EACd,SAAS,GACV,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,kBAAkB,EAClB,eAAe,EACf,gBAAgB,EAChB,WAAW,EACX,YAAY,EACZ,SAAS,EACT,SAAS,EACT,YAAY,EACZ,eAAe,GAEhB,MAAM,aAAa,CAAC;AAiBrB,OAAO,EACL,aAAa,EACb,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,iBAAiB,CAAC"}

package/dist/machine-id.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Machine ID utilities for anonymous user identification.
+ * Uses existing machine-id file at ~/.local/share/agent-relay/machine-id
+ */
+export declare function getMachineIdPath(): string;
+/**
+ * Load or generate machine ID using atomic file creation to avoid race conditions.
+ */
+export declare function loadMachineId(): string;
+/** SHA256 hash of machine ID, truncated to 16 chars */
+export declare function createAnonymousId(): string;
+//# sourceMappingURL=machine-id.d.ts.map

package/dist/machine-id.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"machine-id.d.ts","sourceRoot":"","sources":["../src/machine-id.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAOH,wBAAgB,gBAAgB,IAAI,MAAM,CAIzC;AAED;;GAEG;AACH,wBAAgB,aAAa,IAAI,MAAM,CAkCtC;AAED,uDAAuD;AACvD,wBAAgB,iBAAiB,IAAI,MAAM,CAM1C"}

package/dist/machine-id.js

@@ -0,0 +1,58 @@
+/**
+ * Machine ID utilities for anonymous user identification.
+ * Uses existing machine-id file at ~/.local/share/agent-relay/machine-id
+ */
+import { createHash, randomBytes } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+export function getMachineIdPath() {
+    const dataDir = process.env.AGENT_RELAY_DATA_DIR ||
+        path.join(os.homedir(), '.local', 'share', 'agent-relay');
+    return path.join(dataDir, 'machine-id');
+}
+/**
+ * Load or generate machine ID using atomic file creation to avoid race conditions.
+ */
+export function loadMachineId() {
+    const machineIdPath = getMachineIdPath();
+    try {
+        return fs.readFileSync(machineIdPath, 'utf-8').trim();
+    }
+    catch (readErr) {
+        if (readErr.code !== 'ENOENT') {
+            return `${os.hostname()}-${Date.now().toString(36)}`;
+        }
+        try {
+            const dataDir = path.dirname(machineIdPath);
+            fs.mkdirSync(dataDir, { recursive: true });
+            const machineId = `${os.hostname()}-${randomBytes(8).toString('hex')}`;
+            // O_CREAT | O_EXCL fails if file exists - prevents race condition
+            const fd = fs.openSync(machineIdPath, fs.constants.O_CREAT | fs.constants.O_EXCL | fs.constants.O_WRONLY, 0o600);
+            fs.writeSync(fd, machineId);
+            fs.closeSync(fd);
+            return machineId;
+        }
+        catch (writeErr) {
+            // Another process created the file first
+            if (writeErr.code === 'EEXIST') {
+                try {
+                    return fs.readFileSync(machineIdPath, 'utf-8').trim();
+                }
+                catch {
+                    // Fall through
+                }
+            }
+            return `${os.hostname()}-${Date.now().toString(36)}`;
+        }
+    }
+}
+/** SHA256 hash of machine ID, truncated to 16 chars */
+export function createAnonymousId() {
+    const machineId = loadMachineId();
+    return createHash('sha256')
+        .update(machineId)
+        .digest('hex')
+        .substring(0, 16);
+}
+//# sourceMappingURL=machine-id.js.map

package/dist/machine-id.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"machine-id.js","sourceRoot":"","sources":["../src/machine-id.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,MAAM,SAAS,CAAC;AAEzB,MAAM,UAAU,gBAAgB;IAC9B,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,oBAAoB;QAC9C,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,QAAQ,EAAE,OAAO,EAAE,aAAa,CAAC,CAAC;IAC5D,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC;AAC1C,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,aAAa;IAC3B,MAAM,aAAa,GAAG,gBAAgB,EAAE,CAAC;IAEzC,IAAI,CAAC;QACH,OAAO,EAAE,CAAC,YAAY,CAAC,aAAa,EAAE,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC;IACxD,CAAC;IAAC,OAAO,OAAgB,EAAE,CAAC;QAC1B,IAAK,OAAiC,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YACzD,OAAO,GAAG,EAAE,CAAC,QAAQ,EAAE,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAC;QACvD,CAAC;QAED,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC;YAC5C,EAAE,CAAC,SAAS,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;YAE3C,MAAM,SAAS,GAAG,GAAG,EAAE,CAAC,QAAQ,EAAE,IAAI,WAAW,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;YAEvE,kEAAkE;YAClE,MAAM,EAAE,GAAG,EAAE,CAAC,QAAQ,CAAC,aAAa,EAAE,EAAE,CAAC,SAAS,CAAC,OAAO,GAAG,EAAE,CAAC,SAAS,CAAC,MAAM,GAAG,EAAE,CAAC,SAAS,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;YACjH,EAAE,CAAC,SAAS,CAAC,EAAE,EAAE,SAAS,CAAC,CAAC;YAC5B,EAAE,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;YAEjB,OAAO,SAAS,CAAC;QACnB,CAAC;QAAC,OAAO,QAAiB,EAAE,CAAC;YAC3B,yCAAyC;YACzC,IAAK,QAAkC,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;gBAC1D,IAAI,CAAC;oBACH,OAAO,EAAE,CAAC,YAAY,CAAC,aAAa,EAAE,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC;gBACxD,CAAC;gBAAC,MAAM,CAAC;oBACP,eAAe;gBACjB,CAAC;YACH,CAAC;YACD,OAAO,GAAG,EAAE,CAAC,QAAQ,EAAE,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAC;QACvD,CAAC;IACH,CAAC;AACH,CAAC;AAED,uDAAuD;AACvD,MAAM,UAAU,iBAAiB;IAC/B,MAAM,SAAS,GAAG,aAAa,EAAE,CAAC;IAClC,OAAO,UAAU,CAAC,QAAQ,CAAC;SACxB,MAAM,CAAC,SAAS,CAAC;SACjB,MAAM,CAAC,KAAK,CAAC;SACb,SAAS,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AACtB,CAAC"}

package/dist/posthog-config.d.ts

@@ -0,0 +1,16 @@
+/**
+ * PostHog configuration.
+ *
+ * Environment variables:
+ *   POSTHOG_API_KEY     - Override API key (any environment)
+ *   POSTHOG_HOST        - Override host URL
+ *
+ * Key selection:
+ *   1. POSTHOG_API_KEY (if set, always used)
+ *   3. PROD_API_KEY (fallback)
+ */
+export declare function getPostHogConfig(): {
+    apiKey: string;
+    host: string;
+} | null;
+//# sourceMappingURL=posthog-config.d.ts.map

package/dist/posthog-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"posthog-config.d.ts","sourceRoot":"","sources":["../src/posthog-config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAcH,wBAAgB,gBAAgB,IAAI;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAc1E"}

package/dist/posthog-config.js

@@ -0,0 +1,33 @@
+/**
+ * PostHog configuration.
+ *
+ * Environment variables:
+ *   POSTHOG_API_KEY     - Override API key (any environment)
+ *   POSTHOG_HOST        - Override host URL
+ *
+ * Key selection:
+ *   1. POSTHOG_API_KEY (if set, always used)
+ *   3. PROD_API_KEY (fallback)
+ */
+// =============================================================================
+// Configure your PostHog production key here
+// =============================================================================
+/** Production PostHog API key (write-only, safe for client-side) */
+const PROD_API_KEY = 'phc_2uDu01GtnLABJpVkWw4ri1OgScLU90aEmXmDjufGdqr';
+const HOST = 'https://us.i.posthog.com';
+// =============================================================================
+// Exports
+// =============================================================================
+export function getPostHogConfig() {
+    const host = process.env.POSTHOG_HOST || HOST;
+    // Explicit override for any environment
+    if (process.env.POSTHOG_API_KEY) {
+        return { apiKey: process.env.POSTHOG_API_KEY, host };
+    }
+    // Fallback to production key
+    if (!PROD_API_KEY) {
+        return null;
+    }
+    return { apiKey: PROD_API_KEY, host };
+}
+//# sourceMappingURL=posthog-config.js.map

package/dist/posthog-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"posthog-config.js","sourceRoot":"","sources":["../src/posthog-config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,gFAAgF;AAChF,6CAA6C;AAC7C,gFAAgF;AAEhF,oEAAoE;AACpE,MAAM,YAAY,GAAG,iDAAiD,CAAC;AACvE,MAAM,IAAI,GAAG,0BAA0B,CAAC;AAExC,gFAAgF;AAChF,UAAU;AACV,gFAAgF;AAEhF,MAAM,UAAU,gBAAgB;IAC9B,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,YAAY,IAAI,IAAI,CAAC;IAE9C,wCAAwC;IACxC,IAAI,OAAO,CAAC,GAAG,CAAC,eAAe,EAAE,CAAC;QAChC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,GAAG,CAAC,eAAe,EAAE,IAAI,EAAE,CAAC;IACvD,CAAC;IAED,6BAA6B;IAC7B,IAAI,CAAC,YAAY,EAAE,CAAC;QAClB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC;AACxC,CAAC"}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@agent-relay/telemetry",
+  "version": "2.0.5",
+  "description": "Anonymous telemetry for Agent Relay usage analytics",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "posthog-node": "^4.0.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.3",
+    "typescript": "^5.9.3",
+    "vitest": "^3.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AgentWorkforce/relay.git",
+    "directory": "packages/telemetry"
+  }
+}