workos 0.15.2 → 0.17.0

package/dist/utils/telemetry-client.js

@@ -1,12 +1,36 @@
-import { debug } from './debug.js';
-import { getCredentials } from '../lib/credentials.js';
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { debug, isDebugEnabled } from './debug.js';
+import { getCredentials, isTokenExpired } from '../lib/credentials.js';
+function summarizeEvent(event) {
+    switch (event.type) {
+        case 'session.start':
+            return `session.start(mode=${event.attributes['installer.mode']}, os=${event.attributes['env.os']})`;
+        case 'session.end':
+            return `session.end(outcome=${event.attributes['installer.outcome']}, duration=${event.attributes['installer.duration_ms']}ms)`;
+        case 'step':
+            return `step(${event.name}, ${event.durationMs}ms, success=${event.success})`;
+        case 'agent.tool':
+            return `agent.tool(${event.toolName}, ${event.durationMs}ms)`;
+        case 'agent.llm':
+            return `agent.llm(${event.model}, in=${event.inputTokens}, out=${event.outputTokens})`;
+        case 'command':
+            return `command(${event.attributes['command.name']}, ${event.attributes['command.duration_ms']}ms, success=${event.attributes['command.success']})`;
+        case 'crash':
+            return `crash(${event.attributes['crash.error_type']}: ${event.attributes['crash.error_message']})`;
+    }
+}
 /**
- * HTTP client that queues telemetry events and flushes them to the gateway.
+ * HTTP client that queues telemetry events and flushes them to the API.
  * Failures are silent—telemetry should never crash the wizard.
  */
 export class TelemetryClient {
     events = [];
+    flushInFlight = null;
     accessToken = null;
+    claimToken = null;
+    clientId = null;
+    apiKey = null;
     gatewayUrl = null;
     setGatewayUrl(url) {
         this.gatewayUrl = url;
@@ -14,48 +38,134 @@ export class TelemetryClient {
     setAccessToken(token) {
         this.accessToken = token;
     }
+    setApiKeyAuth(apiKey) {
+        this.apiKey = apiKey;
+    }
+    /**
+     * Set claim-token auth for unclaimed environments.
+     * The API accepts either a JWT (Bearer), claim token
+     * (x-workos-claim-token + x-workos-client-id), or API key
+     * (x-workos-api-key).
+     */
+    setClaimTokenAuth(clientId, claimToken) {
+        this.clientId = clientId;
+        this.claimToken = claimToken;
+    }
     queueEvent(event) {
         this.events.push(event);
     }
+    /**
+     * Queue multiple pre-formed events (used by store-forward recovery).
+     */
+    queueEvents(events) {
+        this.events.push(...events);
+    }
+    /**
+     * Flush queued events. Returns true if events were sent or intentionally
+     * dropped (4xx), false if they should be retried (5xx/network error).
+     * Uses splice to only remove the events that were in the snapshot,
+     * protecting any events queued concurrently during the fetch.
+     */
     async flush() {
+        // Coalesce overlapping flushes: a second caller during an in-flight flush
+        // would otherwise snapshot and POST the same events again (duplicate send),
+        // and its splice() could drop events queued after the first flush started.
+        if (this.flushInFlight)
+            return this.flushInFlight;
+        this.flushInFlight = this.flushInternal();
+        try {
+            return await this.flushInFlight;
+        }
+        finally {
+            this.flushInFlight = null;
+        }
+    }
+    async flushInternal() {
         if (this.events.length === 0)
-            return;
+            return true;
         if (!this.gatewayUrl) {
-            debug('[Telemetry] No gateway URL configured, skipping flush');
-            return;
+            debug('[Telemetry] No telemetry URL configured, skipping flush');
+            return false;
         }
-        const payload = { events: [...this.events] };
-        this.events = [];
+        const count = this.events.length;
+        const payload = { events: this.events.slice(0, count) };
         const headers = {
             'Content-Type': 'application/json',
         };
-        // Read fresh credentials to handle token refresh mid-session
+        // Read fresh credentials to handle token refresh mid-session. Skip an
+        // expired stored token — sending a dead Bearer 401s and the event is
+        // dropped, so fall through to claim-token / api-key auth instead.
         const freshCreds = getCredentials();
-        const token = freshCreds?.accessToken ?? this.accessToken;
+        const token = freshCreds?.accessToken
+            ? isTokenExpired(freshCreds)
+                ? null
+                : freshCreds.accessToken
+            : this.accessToken;
         if (token) {
             headers['Authorization'] = `Bearer ${token}`;
         }
+        else if (this.claimToken && this.clientId) {
+            // Unclaimed environment auth path — guard accepts this instead of JWT
+            headers['x-workos-claim-token'] = this.claimToken;
+            headers['x-workos-client-id'] = this.clientId;
+        }
+        else if (this.apiKey) {
+            headers['x-workos-api-key'] = this.apiKey;
+        }
         const controller = new AbortController();
         const timeout = setTimeout(() => controller.abort(), 3000);
         try {
-            debug(`[Telemetry] Sending ${payload.events.length} events to ${this.gatewayUrl}/telemetry`);
+            if (isDebugEnabled()) {
+                const eventSummary = payload.events.map(summarizeEvent).join('\n  ');
+                debug(`[Telemetry] Sending ${payload.events.length} events to ${this.gatewayUrl}/telemetry:\n  ${eventSummary}`);
+            }
             const response = await fetch(`${this.gatewayUrl}/telemetry`, {
                 method: 'POST',
                 headers,
                 body: JSON.stringify(payload),
                 signal: controller.signal,
             });
-            if (!response.ok) {
+            if (response.ok) {
+                this.events.splice(0, count);
+                return true;
+            }
+            else {
                 debug(`[Telemetry] Failed to send: ${response.status}`);
+                // Drop on 4xx (permanent failures like 401/403 won't succeed on retry).
+                // Retain on 5xx (transient server errors) for store-forward.
+                if (response.status >= 400 && response.status < 500) {
+                    this.events.splice(0, count);
+                    return true; // intentionally dropped
+                }
+                return false;
             }
         }
         catch (error) {
             debug(`[Telemetry] Error sending events: ${error}`);
+            // Events remain in queue for store-forward to persist
+            return false;
         }
         finally {
             clearTimeout(timeout);
         }
     }
+    /**
+     * Synchronously write pending events to a file.
+     * Used as last resort in process.on('exit') handler.
+     */
+    persistToFile(filePath) {
+        if (this.events.length === 0)
+            return;
+        try {
+            // Restrictive modes — the payload carries device/user identifiers.
+            mkdirSync(dirname(filePath), { recursive: true, mode: 0o700 });
+            writeFileSync(filePath, JSON.stringify(this.events), { encoding: 'utf-8', mode: 0o600 });
+            this.events = [];
+        }
+        catch {
+            // Silent failure — telemetry must never block exit
+        }
+    }
 }
 export const telemetryClient = new TelemetryClient();
 //# sourceMappingURL=telemetry-client.js.map

package/dist/utils/telemetry-client.js.map

@@ -1 +1 @@
-{"version":3,"file":"telemetry-client.js","sourceRoot":"","sources":["../../src/utils/telemetry-client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAEnC,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAEvD;;;GAGG;AACH,MAAM,OAAO,eAAe;IAClB,MAAM,GAAqB,EAAE,CAAC;IAC9B,WAAW,GAAkB,IAAI,CAAC;IAClC,UAAU,GAAkB,IAAI,CAAC;IAEzC,aAAa,CAAC,GAAW;QACvB,IAAI,CAAC,UAAU,GAAG,GAAG,CAAC;IACxB,CAAC;IAED,cAAc,CAAC,KAAa;QAC1B,IAAI,CAAC,WAAW,GAAG,KAAK,CAAC;IAC3B,CAAC;IAED,UAAU,CAAC,KAAqB;QAC9B,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC1B,CAAC;IAED,KAAK,CAAC,KAAK;QACT,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO;QACrC,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,CAAC;YACrB,KAAK,CAAC,uDAAuD,CAAC,CAAC;YAC/D,OAAO;QACT,CAAC;QAED,MAAM,OAAO,GAAqB,EAAE,MAAM,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;QAC/D,IAAI,CAAC,MAAM,GAAG,EAAE,CAAC;QAEjB,MAAM,OAAO,GAA2B;YACtC,cAAc,EAAE,kBAAkB;SACnC,CAAC;QACF,6DAA6D;QAC7D,MAAM,UAAU,GAAG,cAAc,EAAE,CAAC;QACpC,MAAM,KAAK,GAAG,UAAU,EAAE,WAAW,IAAI,IAAI,CAAC,WAAW,CAAC;QAC1D,IAAI,KAAK,EAAE,CAAC;YACV,OAAO,CAAC,eAAe,CAAC,GAAG,UAAU,KAAK,EAAE,CAAC;QAC/C,CAAC;QAED,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;QACzC,MAAM,OAAO,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,IAAI,CAAC,CAAC;QAE3D,IAAI,CAAC;YACH,KAAK,CAAC,uBAAuB,OAAO,CAAC,MAAM,CAAC,MAAM,cAAc,IAAI,CAAC,UAAU,YAAY,CAAC,CAAC;YAE7F,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,IAAI,CAAC,UAAU,YAAY,EAAE;gBAC3D,MAAM,EAAE,MAAM;gBACd,OAAO;gBACP,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC;gBAC7B,MAAM,EAAE,UAAU,CAAC,MAAM;aAC1B,CAAC,CAAC;YAEH,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;gBACjB,KAAK,CAAC,+BAA+B,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;YAC1D,CAAC;QACH,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,KAAK,CAAC,qCAAqC,KAAK,EAAE,CAAC,CAAC;QACtD,CAAC;gBAAS,CAAC;YACT,YAAY,CAAC,OAAO,CAAC,CAAC;QACxB,CAAC;IACH,CAAC;CACF;AAED,MAAM,CAAC,MAAM,eAAe,GAAG,IAAI,eAAe,EAAE,CAAC","sourcesContent":["import { debug } from './debug.js';\nimport type { TelemetryEvent, TelemetryRequest } from './telemetry-types.js';\nimport { getCredentials } from '../lib/credentials.js';\n\n/**\n * HTTP client that queues telemetry events and flushes them to the gateway.\n * Failures are silent—telemetry should never crash the wizard.\n */\nexport class TelemetryClient {\n  private events: TelemetryEvent[] = [];\n  private accessToken: string | null = null;\n  private gatewayUrl: string | null = null;\n\n  setGatewayUrl(url: string) {\n    this.gatewayUrl = url;\n  }\n\n  setAccessToken(token: string) {\n    this.accessToken = token;\n  }\n\n  queueEvent(event: TelemetryEvent) {\n    this.events.push(event);\n  }\n\n  async flush(): Promise<void> {\n    if (this.events.length === 0) return;\n    if (!this.gatewayUrl) {\n      debug('[Telemetry] No gateway URL configured, skipping flush');\n      return;\n    }\n\n    const payload: TelemetryRequest = { events: [...this.events] };\n    this.events = [];\n\n    const headers: Record<string, string> = {\n      'Content-Type': 'application/json',\n    };\n    // Read fresh credentials to handle token refresh mid-session\n    const freshCreds = getCredentials();\n    const token = freshCreds?.accessToken ?? this.accessToken;\n    if (token) {\n      headers['Authorization'] = `Bearer ${token}`;\n    }\n\n    const controller = new AbortController();\n    const timeout = setTimeout(() => controller.abort(), 3000);\n\n    try {\n      debug(`[Telemetry] Sending ${payload.events.length} events to ${this.gatewayUrl}/telemetry`);\n\n      const response = await fetch(`${this.gatewayUrl}/telemetry`, {\n        method: 'POST',\n        headers,\n        body: JSON.stringify(payload),\n        signal: controller.signal,\n      });\n\n      if (!response.ok) {\n        debug(`[Telemetry] Failed to send: ${response.status}`);\n      }\n    } catch (error) {\n      debug(`[Telemetry] Error sending events: ${error}`);\n    } finally {\n      clearTimeout(timeout);\n    }\n  }\n}\n\nexport const telemetryClient = new TelemetryClient();\n"]}
+{"version":3,"file":"telemetry-client.js","sourceRoot":"","sources":["../../src/utils/telemetry-client.ts"],"names":[],"mappings":"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","sourcesContent":["import { mkdirSync, writeFileSync } from 'node:fs';\nimport { dirname } from 'node:path';\nimport { debug, isDebugEnabled } from './debug.js';\nimport type { TelemetryEvent, TelemetryRequest } from './telemetry-types.js';\nimport { getCredentials, isTokenExpired } from '../lib/credentials.js';\n\nfunction summarizeEvent(event: TelemetryEvent): string {\n  switch (event.type) {\n    case 'session.start':\n      return `session.start(mode=${event.attributes['installer.mode']}, os=${event.attributes['env.os']})`;\n    case 'session.end':\n      return `session.end(outcome=${event.attributes['installer.outcome']}, duration=${event.attributes['installer.duration_ms']}ms)`;\n    case 'step':\n      return `step(${event.name}, ${event.durationMs}ms, success=${event.success})`;\n    case 'agent.tool':\n      return `agent.tool(${event.toolName}, ${event.durationMs}ms)`;\n    case 'agent.llm':\n      return `agent.llm(${event.model}, in=${event.inputTokens}, out=${event.outputTokens})`;\n    case 'command':\n      return `command(${event.attributes['command.name']}, ${event.attributes['command.duration_ms']}ms, success=${event.attributes['command.success']})`;\n    case 'crash':\n      return `crash(${event.attributes['crash.error_type']}: ${event.attributes['crash.error_message']})`;\n  }\n}\n\n/**\n * HTTP client that queues telemetry events and flushes them to the API.\n * Failures are silent—telemetry should never crash the wizard.\n */\nexport class TelemetryClient {\n  private events: TelemetryEvent[] = [];\n  private flushInFlight: Promise<boolean> | null = null;\n  private accessToken: string | null = null;\n  private claimToken: string | null = null;\n  private clientId: string | null = null;\n  private apiKey: string | null = null;\n  private gatewayUrl: string | null = null;\n\n  setGatewayUrl(url: string) {\n    this.gatewayUrl = url;\n  }\n\n  setAccessToken(token: string) {\n    this.accessToken = token;\n  }\n\n  setApiKeyAuth(apiKey: string) {\n    this.apiKey = apiKey;\n  }\n\n  /**\n   * Set claim-token auth for unclaimed environments.\n   * The API accepts either a JWT (Bearer), claim token\n   * (x-workos-claim-token + x-workos-client-id), or API key\n   * (x-workos-api-key).\n   */\n  setClaimTokenAuth(clientId: string, claimToken: string) {\n    this.clientId = clientId;\n    this.claimToken = claimToken;\n  }\n\n  queueEvent(event: TelemetryEvent) {\n    this.events.push(event);\n  }\n\n  /**\n   * Queue multiple pre-formed events (used by store-forward recovery).\n   */\n  queueEvents(events: TelemetryEvent[]): void {\n    this.events.push(...events);\n  }\n\n  /**\n   * Flush queued events. Returns true if events were sent or intentionally\n   * dropped (4xx), false if they should be retried (5xx/network error).\n   * Uses splice to only remove the events that were in the snapshot,\n   * protecting any events queued concurrently during the fetch.\n   */\n  async flush(): Promise<boolean> {\n    // Coalesce overlapping flushes: a second caller during an in-flight flush\n    // would otherwise snapshot and POST the same events again (duplicate send),\n    // and its splice() could drop events queued after the first flush started.\n    if (this.flushInFlight) return this.flushInFlight;\n    this.flushInFlight = this.flushInternal();\n    try {\n      return await this.flushInFlight;\n    } finally {\n      this.flushInFlight = null;\n    }\n  }\n\n  private async flushInternal(): Promise<boolean> {\n    if (this.events.length === 0) return true;\n    if (!this.gatewayUrl) {\n      debug('[Telemetry] No telemetry URL configured, skipping flush');\n      return false;\n    }\n\n    const count = this.events.length;\n    const payload: TelemetryRequest = { events: this.events.slice(0, count) };\n\n    const headers: Record<string, string> = {\n      'Content-Type': 'application/json',\n    };\n    // Read fresh credentials to handle token refresh mid-session. Skip an\n    // expired stored token — sending a dead Bearer 401s and the event is\n    // dropped, so fall through to claim-token / api-key auth instead.\n    const freshCreds = getCredentials();\n    const token = freshCreds?.accessToken\n      ? isTokenExpired(freshCreds)\n        ? null\n        : freshCreds.accessToken\n      : this.accessToken;\n    if (token) {\n      headers['Authorization'] = `Bearer ${token}`;\n    } else if (this.claimToken && this.clientId) {\n      // Unclaimed environment auth path — guard accepts this instead of JWT\n      headers['x-workos-claim-token'] = this.claimToken;\n      headers['x-workos-client-id'] = this.clientId;\n    } else if (this.apiKey) {\n      headers['x-workos-api-key'] = this.apiKey;\n    }\n\n    const controller = new AbortController();\n    const timeout = setTimeout(() => controller.abort(), 3000);\n\n    try {\n      if (isDebugEnabled()) {\n        const eventSummary = payload.events.map(summarizeEvent).join('\\n  ');\n        debug(\n          `[Telemetry] Sending ${payload.events.length} events to ${this.gatewayUrl}/telemetry:\\n  ${eventSummary}`,\n        );\n      }\n\n      const response = await fetch(`${this.gatewayUrl}/telemetry`, {\n        method: 'POST',\n        headers,\n        body: JSON.stringify(payload),\n        signal: controller.signal,\n      });\n\n      if (response.ok) {\n        this.events.splice(0, count);\n        return true;\n      } else {\n        debug(`[Telemetry] Failed to send: ${response.status}`);\n        // Drop on 4xx (permanent failures like 401/403 won't succeed on retry).\n        // Retain on 5xx (transient server errors) for store-forward.\n        if (response.status >= 400 && response.status < 500) {\n          this.events.splice(0, count);\n          return true; // intentionally dropped\n        }\n        return false;\n      }\n    } catch (error) {\n      debug(`[Telemetry] Error sending events: ${error}`);\n      // Events remain in queue for store-forward to persist\n      return false;\n    } finally {\n      clearTimeout(timeout);\n    }\n  }\n\n  /**\n   * Synchronously write pending events to a file.\n   * Used as last resort in process.on('exit') handler.\n   */\n  persistToFile(filePath: string): void {\n    if (this.events.length === 0) return;\n    try {\n      // Restrictive modes — the payload carries device/user identifiers.\n      mkdirSync(dirname(filePath), { recursive: true, mode: 0o700 });\n      writeFileSync(filePath, JSON.stringify(this.events), { encoding: 'utf-8', mode: 0o600 });\n      this.events = [];\n    } catch {\n      // Silent failure — telemetry must never block exit\n    }\n  }\n}\n\nexport const telemetryClient = new TelemetryClient();\n"]}

package/dist/utils/telemetry-store-forward.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Register a sync exit handler that persists unsent events to disk.
+ * Called once at startup. Uses PID in filename to prevent concurrent
+ * CLI invocations from colliding.
+ */
+export declare function installStoreForward(): void;
+/**
+ * On startup, check for ANY pending files from previous invocations
+ * (could be from different PIDs) and send them. Non-blocking, fire-and-forget.
+ */
+export declare function recoverPendingEvents(): Promise<void>;

package/dist/utils/telemetry-store-forward.js

@@ -0,0 +1,94 @@
+import { readFileSync, readdirSync, statSync, unlinkSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { telemetryClient } from './telemetry-client.js';
+import { debug } from './debug.js';
+const PENDING_DIR = join(tmpdir(), 'workos-cli-telemetry');
+const PENDING_FILE = join(PENDING_DIR, `pending-${process.pid}.json`);
+const MAX_PENDING_FILES = 100;
+const MAX_PENDING_AGE_MS = 7 * 24 * 60 * 60 * 1000;
+function safeUnlink(filePath) {
+    try {
+        unlinkSync(filePath);
+    }
+    catch {
+        /* ignore */
+    }
+}
+/**
+ * Register a sync exit handler that persists unsent events to disk.
+ * Called once at startup. Uses PID in filename to prevent concurrent
+ * CLI invocations from colliding.
+ */
+export function installStoreForward() {
+    process.on('exit', () => {
+        telemetryClient.persistToFile(PENDING_FILE);
+    });
+}
+/**
+ * On startup, check for ANY pending files from previous invocations
+ * (could be from different PIDs) and send them. Non-blocking, fire-and-forget.
+ */
+export async function recoverPendingEvents() {
+    try {
+        if (!existsSync(PENDING_DIR))
+            return;
+        const files = readdirSync(PENDING_DIR).filter((f) => f.startsWith('pending-') && f.endsWith('.json'));
+        const now = Date.now();
+        const pendingFiles = [];
+        for (const file of files) {
+            const filePath = join(PENDING_DIR, file);
+            try {
+                const { mtimeMs } = statSync(filePath);
+                if (now - mtimeMs > MAX_PENDING_AGE_MS) {
+                    debug(`[Telemetry] Dropping stale pending file: ${file}`);
+                    safeUnlink(filePath);
+                }
+                else {
+                    pendingFiles.push({ file, filePath, mtimeMs });
+                }
+            }
+            catch {
+                debug(`[Telemetry] Dropping unreadable pending file: ${file}`);
+                safeUnlink(filePath);
+            }
+        }
+        pendingFiles.sort((a, b) => b.mtimeMs - a.mtimeMs);
+        const filesToRecover = pendingFiles.slice(0, MAX_PENDING_FILES);
+        for (const dropped of pendingFiles.slice(MAX_PENDING_FILES)) {
+            debug(`[Telemetry] Dropping excess pending file: ${dropped.file}`);
+            safeUnlink(dropped.filePath);
+        }
+        const recoveredFiles = [];
+        for (const { filePath } of filesToRecover) {
+            try {
+                const raw = readFileSync(filePath, 'utf-8');
+                const events = JSON.parse(raw);
+                if (Array.isArray(events) && events.length > 0) {
+                    telemetryClient.queueEvents(events);
+                    recoveredFiles.push(filePath);
+                }
+                else {
+                    // Empty file — delete immediately
+                    safeUnlink(filePath);
+                }
+            }
+            catch {
+                // Corrupted file — delete and move on
+                safeUnlink(filePath);
+            }
+        }
+        // Delete source files — events are now in memory regardless of flush outcome.
+        // If flush succeeds: events sent, done.
+        // If flush fails: events stay in memory, exit handler re-persists to new PID file.
+        for (const filePath of recoveredFiles) {
+            safeUnlink(filePath);
+        }
+        // Flush all recovered events in one batch
+        await telemetryClient.flush();
+    }
+    catch {
+        debug('[Telemetry] Store-forward recovery failed silently');
+    }
+}
+//# sourceMappingURL=telemetry-store-forward.js.map

package/dist/utils/telemetry-store-forward.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry-store-forward.js","sourceRoot":"","sources":["../../src/utils/telemetry-store-forward.ts"],"names":[],"mappings":"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","sourcesContent":["import { readFileSync, readdirSync, statSync, unlinkSync, existsSync } from 'node:fs';\nimport { join } from 'node:path';\nimport { tmpdir } from 'node:os';\nimport { telemetryClient } from './telemetry-client.js';\nimport { debug } from './debug.js';\n\nconst PENDING_DIR = join(tmpdir(), 'workos-cli-telemetry');\nconst PENDING_FILE = join(PENDING_DIR, `pending-${process.pid}.json`);\nconst MAX_PENDING_FILES = 100;\nconst MAX_PENDING_AGE_MS = 7 * 24 * 60 * 60 * 1000;\n\nfunction safeUnlink(filePath: string): void {\n  try {\n    unlinkSync(filePath);\n  } catch {\n    /* ignore */\n  }\n}\n\n/**\n * Register a sync exit handler that persists unsent events to disk.\n * Called once at startup. Uses PID in filename to prevent concurrent\n * CLI invocations from colliding.\n */\nexport function installStoreForward(): void {\n  process.on('exit', () => {\n    telemetryClient.persistToFile(PENDING_FILE);\n  });\n}\n\n/**\n * On startup, check for ANY pending files from previous invocations\n * (could be from different PIDs) and send them. Non-blocking, fire-and-forget.\n */\nexport async function recoverPendingEvents(): Promise<void> {\n  try {\n    if (!existsSync(PENDING_DIR)) return;\n    const files = readdirSync(PENDING_DIR).filter((f) => f.startsWith('pending-') && f.endsWith('.json'));\n    const now = Date.now();\n    const pendingFiles: Array<{ file: string; filePath: string; mtimeMs: number }> = [];\n\n    for (const file of files) {\n      const filePath = join(PENDING_DIR, file);\n      try {\n        const { mtimeMs } = statSync(filePath);\n        if (now - mtimeMs > MAX_PENDING_AGE_MS) {\n          debug(`[Telemetry] Dropping stale pending file: ${file}`);\n          safeUnlink(filePath);\n        } else {\n          pendingFiles.push({ file, filePath, mtimeMs });\n        }\n      } catch {\n        debug(`[Telemetry] Dropping unreadable pending file: ${file}`);\n        safeUnlink(filePath);\n      }\n    }\n\n    pendingFiles.sort((a, b) => b.mtimeMs - a.mtimeMs);\n    const filesToRecover = pendingFiles.slice(0, MAX_PENDING_FILES);\n    for (const dropped of pendingFiles.slice(MAX_PENDING_FILES)) {\n      debug(`[Telemetry] Dropping excess pending file: ${dropped.file}`);\n      safeUnlink(dropped.filePath);\n    }\n\n    const recoveredFiles: string[] = [];\n    for (const { filePath } of filesToRecover) {\n      try {\n        const raw = readFileSync(filePath, 'utf-8');\n        const events = JSON.parse(raw);\n        if (Array.isArray(events) && events.length > 0) {\n          telemetryClient.queueEvents(events);\n          recoveredFiles.push(filePath);\n        } else {\n          // Empty file — delete immediately\n          safeUnlink(filePath);\n        }\n      } catch {\n        // Corrupted file — delete and move on\n        safeUnlink(filePath);\n      }\n    }\n\n    // Delete source files — events are now in memory regardless of flush outcome.\n    // If flush succeeds: events sent, done.\n    // If flush fails: events stay in memory, exit handler re-persists to new PID file.\n    for (const filePath of recoveredFiles) {\n      safeUnlink(filePath);\n    }\n\n    // Flush all recovered events in one batch\n    await telemetryClient.flush();\n  } catch {\n    debug('[Telemetry] Store-forward recovery failed silently');\n  }\n}\n"]}

package/dist/utils/telemetry-types.d.ts

@@ -2,31 +2,49 @@
  * Telemetry event types for installer → gateway communication.
  * The gateway converts these to OTel format.
  */
-export interface TelemetryEvent {
-    type: 'session.start' | 'session.end' | 'step' | 'agent.tool' | 'agent.llm';
+export interface BaseTelemetryEvent {
+    type: 'session.start' | 'session.end' | 'step' | 'agent.tool' | 'agent.llm' | 'command' | 'crash';
     sessionId: string;
     timestamp: string;
-    attributes?: Record<string, string | number | boolean>;
 }
-export interface SessionStartEvent extends TelemetryEvent {
+export type AuthMode = 'jwt' | 'claim_token' | 'api_key' | 'none';
+/**
+ * Structured outcome dimension for command events. Supersedes the boolean
+ * `command.success` as the primary categorization (`command.success` remains
+ * for backward-compat). Populated by `analytics.emitCommandEvent()` from the
+ * top-level command lifecycle.
+ */
+export type TerminationReason = 'success' | 'cancelled' | 'auth_required' | 'validation_error' | 'api_error' | 'crash';
+export interface EnvFingerprint {
+    'device.id': string;
+    'auth.mode': AuthMode;
+    'env.os': string;
+    'env.os_version': string;
+    'env.node_version': string;
+    'env.shell': string;
+    'env.ci': boolean;
+    'env.ci_provider'?: string;
+}
+export interface SessionStartEvent extends BaseTelemetryEvent {
     type: 'session.start';
     attributes: {
         'installer.version': string;
         'installer.mode': 'cli' | 'tui' | 'headless';
         'workos.user_id'?: string;
         'workos.org_id'?: string;
-    };
+    } & EnvFingerprint;
 }
-export interface SessionEndEvent extends TelemetryEvent {
+export interface SessionEndEvent extends BaseTelemetryEvent {
     type: 'session.end';
     attributes: {
         'installer.outcome': 'success' | 'error' | 'cancelled';
         'installer.duration_ms': number;
     } & Record<string, string | number | boolean>;
 }
-export interface StepEvent extends TelemetryEvent {
+export interface StepEvent extends BaseTelemetryEvent {
     type: 'step';
     name: string;
+    startTimestamp: string;
     durationMs: number;
     success: boolean;
     error?: {
@@ -34,18 +52,49 @@ export interface StepEvent extends TelemetryEvent {
         message: string;
     };
 }
-export interface AgentToolEvent extends TelemetryEvent {
+export interface AgentToolEvent extends BaseTelemetryEvent {
     type: 'agent.tool';
     toolName: string;
+    startTimestamp: string;
     durationMs: number;
     success: boolean;
 }
-export interface AgentLLMEvent extends TelemetryEvent {
+export interface AgentLLMEvent extends BaseTelemetryEvent {
     type: 'agent.llm';
     model: string;
     inputTokens: number;
     outputTokens: number;
 }
+export interface CommandEvent extends BaseTelemetryEvent {
+    type: 'command';
+    attributes: {
+        'command.name': string;
+        'command.duration_ms': number;
+        'command.success': boolean;
+        'command.error_type'?: string;
+        'command.error_message'?: string;
+        'command.flags'?: string;
+        'termination.reason'?: TerminationReason;
+        'error.code'?: string;
+        'api.status'?: number;
+        'api.code'?: string;
+        'api.resource'?: string;
+        'cli.version': string;
+        'workos.user_id'?: string;
+    } & EnvFingerprint;
+}
+export interface CrashEvent extends BaseTelemetryEvent {
+    type: 'crash';
+    attributes: {
+        'crash.error_type': string;
+        'crash.error_message': string;
+        'crash.stack': string;
+        'crash.command'?: string;
+        'cli.version': string;
+        'workos.user_id'?: string;
+    } & EnvFingerprint;
+}
 export interface TelemetryRequest {
     events: TelemetryEvent[];
 }
+export type TelemetryEvent = SessionStartEvent | SessionEndEvent | StepEvent | AgentToolEvent | AgentLLMEvent | CommandEvent | CrashEvent;

package/dist/utils/telemetry-types.js.map

@@ -1 +1 @@
-{"version":3,"file":"telemetry-types.js","sourceRoot":"","sources":["../../src/utils/telemetry-types.ts"],"names":[],"mappings":"AAAA;;;GAGG","sourcesContent":["/**\n * Telemetry event types for installer → gateway communication.\n * The gateway converts these to OTel format.\n */\n\nexport interface TelemetryEvent {\n  type: 'session.start' | 'session.end' | 'step' | 'agent.tool' | 'agent.llm';\n  sessionId: string;\n  timestamp: string;\n  attributes?: Record<string, string | number | boolean>;\n}\n\nexport interface SessionStartEvent extends TelemetryEvent {\n  type: 'session.start';\n  attributes: {\n    'installer.version': string;\n    'installer.mode': 'cli' | 'tui' | 'headless';\n    'workos.user_id'?: string;\n    'workos.org_id'?: string;\n  };\n}\n\nexport interface SessionEndEvent extends TelemetryEvent {\n  type: 'session.end';\n  attributes: {\n    'installer.outcome': 'success' | 'error' | 'cancelled';\n    'installer.duration_ms': number;\n  } & Record<string, string | number | boolean>;\n}\n\nexport interface StepEvent extends TelemetryEvent {\n  type: 'step';\n  name: string;\n  durationMs: number;\n  success: boolean;\n  error?: {\n    type: string;\n    message: string;\n  };\n}\n\nexport interface AgentToolEvent extends TelemetryEvent {\n  type: 'agent.tool';\n  toolName: string;\n  durationMs: number;\n  success: boolean;\n}\n\nexport interface AgentLLMEvent extends TelemetryEvent {\n  type: 'agent.llm';\n  model: string;\n  inputTokens: number;\n  outputTokens: number;\n}\n\nexport interface TelemetryRequest {\n  events: TelemetryEvent[];\n}\n"]}
+{"version":3,"file":"telemetry-types.js","sourceRoot":"","sources":["../../src/utils/telemetry-types.ts"],"names":[],"mappings":"AAAA;;;GAGG","sourcesContent":["/**\n * Telemetry event types for installer → gateway communication.\n * The gateway converts these to OTel format.\n */\n\nexport interface BaseTelemetryEvent {\n  type: 'session.start' | 'session.end' | 'step' | 'agent.tool' | 'agent.llm' | 'command' | 'crash';\n  sessionId: string;\n  timestamp: string;\n}\n\nexport type AuthMode = 'jwt' | 'claim_token' | 'api_key' | 'none';\n\n/**\n * Structured outcome dimension for command events. Supersedes the boolean\n * `command.success` as the primary categorization (`command.success` remains\n * for backward-compat). Populated by `analytics.emitCommandEvent()` from the\n * top-level command lifecycle.\n */\nexport type TerminationReason = 'success' | 'cancelled' | 'auth_required' | 'validation_error' | 'api_error' | 'crash';\n\nexport interface EnvFingerprint {\n  'device.id': string;\n  'auth.mode': AuthMode;\n  'env.os': string;\n  'env.os_version': string;\n  'env.node_version': string;\n  'env.shell': string;\n  'env.ci': boolean;\n  'env.ci_provider'?: string;\n}\n\nexport interface SessionStartEvent extends BaseTelemetryEvent {\n  type: 'session.start';\n  attributes: {\n    'installer.version': string;\n    'installer.mode': 'cli' | 'tui' | 'headless';\n    'workos.user_id'?: string;\n    'workos.org_id'?: string;\n  } & EnvFingerprint;\n}\n\nexport interface SessionEndEvent extends BaseTelemetryEvent {\n  type: 'session.end';\n  attributes: {\n    'installer.outcome': 'success' | 'error' | 'cancelled';\n    'installer.duration_ms': number;\n  } & Record<string, string | number | boolean>;\n}\n\nexport interface StepEvent extends BaseTelemetryEvent {\n  type: 'step';\n  name: string;\n  startTimestamp: string;\n  durationMs: number;\n  success: boolean;\n  error?: {\n    type: string;\n    message: string;\n  };\n}\n\nexport interface AgentToolEvent extends BaseTelemetryEvent {\n  type: 'agent.tool';\n  toolName: string;\n  startTimestamp: string;\n  durationMs: number;\n  success: boolean;\n}\n\nexport interface AgentLLMEvent extends BaseTelemetryEvent {\n  type: 'agent.llm';\n  model: string;\n  inputTokens: number;\n  outputTokens: number;\n}\n\nexport interface CommandEvent extends BaseTelemetryEvent {\n  type: 'command';\n  attributes: {\n    'command.name': string;\n    'command.duration_ms': number;\n    'command.success': boolean;\n    'command.error_type'?: string;\n    'command.error_message'?: string;\n    'command.flags'?: string;\n    'termination.reason'?: TerminationReason;\n    'error.code'?: string;\n    'api.status'?: number;\n    'api.code'?: string;\n    'api.resource'?: string;\n    'cli.version': string;\n    'workos.user_id'?: string;\n  } & EnvFingerprint;\n}\n\nexport interface CrashEvent extends BaseTelemetryEvent {\n  type: 'crash';\n  attributes: {\n    'crash.error_type': string;\n    'crash.error_message': string;\n    'crash.stack': string;\n    'crash.command'?: string;\n    'cli.version': string;\n    'workos.user_id'?: string;\n  } & EnvFingerprint;\n}\n\nexport interface TelemetryRequest {\n  events: TelemetryEvent[];\n}\n\nexport type TelemetryEvent =\n  | SessionStartEvent\n  | SessionEndEvent\n  | StepEvent\n  | AgentToolEvent\n  | AgentLLMEvent\n  | CommandEvent\n  | CrashEvent;\n"]}

package/dist/utils/types.d.ts

@@ -54,10 +54,6 @@ export type InstallerOptions = {
      * Event emitter for dashboard mode
      */
     emitter?: import('../lib/events.js').InstallerEventEmitter;
-    /**
-     * Pre-selected framework integration (bypasses detection)
-     */
-    integration?: import('../lib/constants.js').Integration;
     /**
      * Enable XState inspector - opens browser to visualize state machine live
      */
@@ -93,6 +89,16 @@ export type InstallerOptions = {
      * Default: 2. Set to 0 to disable retries entirely.
      */
     maxRetries?: number;
+    /**
+     * Scaffold a new Next.js app when run in an empty directory.
+     * Auto-enabled in headless mode; opt-in via --scaffold in interactive mode.
+     */
+    scaffold?: boolean;
+    /**
+     * Package manager for the scaffolded app (npm/pnpm/yarn/bun).
+     * Overrides detection from npm_config_user_agent.
+     */
+    pm?: string;
 };
 export interface Feature {
     id: string;

package/dist/utils/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/utils/types.ts"],"names":[],"mappings":"","sourcesContent":["export type InstallerOptions = {\n  /**\n   * Whether to enable debug mode.\n   */\n  debug: boolean;\n\n  /**\n   * Whether to force install the SDK package to continue with the installation in case\n   * any package manager checks are failing (e.g. peer dependency versions).\n   *\n   * Use with caution and only if you know what you're doing.\n   *\n   * Does not apply to all wizard flows (currently NPM only)\n   */\n  forceInstall: boolean;\n\n  /**\n   * The directory to run the wizard in.\n   */\n  installDir: string;\n\n  /**\n   * Whether to use local services (LLM gateway on localhost:8000)\n   */\n  local: boolean;\n\n  /**\n   * CI mode - non-interactive execution\n   */\n  ci: boolean;\n\n  /**\n   * Skip authentication check (for local development only)\n   */\n  skipAuth: boolean;\n\n  /**\n   * WorkOS API key (sk_xxx)\n   */\n  apiKey?: string;\n\n  /**\n   * WorkOS Client ID (client_xxx)\n   */\n  clientId?: string;\n\n  /**\n   * App homepage URL for WorkOS dashboard config.\n   * Defaults to http://localhost:{detected_port}\n   */\n  homepageUrl?: string;\n\n  /**\n   * Redirect URI for WorkOS callback.\n   * Defaults to framework-specific convention (e.g., /api/auth/callback)\n   */\n  redirectUri?: string;\n\n  /**\n   * [Experimental] Enable visual dashboard mode\n   */\n  dashboard?: boolean;\n\n  /**\n   * Event emitter for dashboard mode\n   */\n  emitter?: import('../lib/events.js').InstallerEventEmitter;\n\n  /**\n   * Pre-selected framework integration (bypasses detection)\n   */\n  integration?: import('../lib/constants.js').Integration;\n\n  /**\n   * Enable XState inspector - opens browser to visualize state machine live\n   */\n  inspect?: boolean;\n\n  /**\n   * Skip post-installation validation (includes build check)\n   */\n  noValidate?: boolean;\n\n  /**\n   * Skip post-install commit and PR workflow\n   */\n  noCommit?: boolean;\n\n  /**\n   * Skip branch creation (continue on current branch)\n   */\n  noBranch?: boolean;\n\n  /**\n   * Auto-create pull request after installation\n   */\n  createPr?: boolean;\n\n  /**\n   * Skip git dirty working tree check\n   */\n  noGitCheck?: boolean;\n\n  /**\n   * Direct mode - bypass llm-gateway and use user's own Anthropic API key.\n   * Requires ANTHROPIC_API_KEY environment variable.\n   */\n  direct?: boolean;\n\n  /**\n   * Max correction attempts after initial agent run.\n   * The agent gets this many chances to fix validation failures (typecheck/build).\n   * Default: 2. Set to 0 to disable retries entirely.\n   */\n  maxRetries?: number;\n};\n\nexport interface Feature {\n  id: string;\n  prompt: string;\n  enabledHint?: string;\n  disabledHint?: string;\n}\n\nexport type FileChange = {\n  filePath: string;\n  oldContent?: string;\n  newContent: string;\n};\n"]}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/utils/types.ts"],"names":[],"mappings":"","sourcesContent":["export type InstallerOptions = {\n  /**\n   * Whether to enable debug mode.\n   */\n  debug: boolean;\n\n  /**\n   * Whether to force install the SDK package to continue with the installation in case\n   * any package manager checks are failing (e.g. peer dependency versions).\n   *\n   * Use with caution and only if you know what you're doing.\n   *\n   * Does not apply to all wizard flows (currently NPM only)\n   */\n  forceInstall: boolean;\n\n  /**\n   * The directory to run the wizard in.\n   */\n  installDir: string;\n\n  /**\n   * Whether to use local services (LLM gateway on localhost:8000)\n   */\n  local: boolean;\n\n  /**\n   * CI mode - non-interactive execution\n   */\n  ci: boolean;\n\n  /**\n   * Skip authentication check (for local development only)\n   */\n  skipAuth: boolean;\n\n  /**\n   * WorkOS API key (sk_xxx)\n   */\n  apiKey?: string;\n\n  /**\n   * WorkOS Client ID (client_xxx)\n   */\n  clientId?: string;\n\n  /**\n   * App homepage URL for WorkOS dashboard config.\n   * Defaults to http://localhost:{detected_port}\n   */\n  homepageUrl?: string;\n\n  /**\n   * Redirect URI for WorkOS callback.\n   * Defaults to framework-specific convention (e.g., /api/auth/callback)\n   */\n  redirectUri?: string;\n\n  /**\n   * [Experimental] Enable visual dashboard mode\n   */\n  dashboard?: boolean;\n\n  /**\n   * Event emitter for dashboard mode\n   */\n  emitter?: import('../lib/events.js').InstallerEventEmitter;\n\n  /**\n   * Enable XState inspector - opens browser to visualize state machine live\n   */\n  inspect?: boolean;\n\n  /**\n   * Skip post-installation validation (includes build check)\n   */\n  noValidate?: boolean;\n\n  /**\n   * Skip post-install commit and PR workflow\n   */\n  noCommit?: boolean;\n\n  /**\n   * Skip branch creation (continue on current branch)\n   */\n  noBranch?: boolean;\n\n  /**\n   * Auto-create pull request after installation\n   */\n  createPr?: boolean;\n\n  /**\n   * Skip git dirty working tree check\n   */\n  noGitCheck?: boolean;\n\n  /**\n   * Direct mode - bypass llm-gateway and use user's own Anthropic API key.\n   * Requires ANTHROPIC_API_KEY environment variable.\n   */\n  direct?: boolean;\n\n  /**\n   * Max correction attempts after initial agent run.\n   * The agent gets this many chances to fix validation failures (typecheck/build).\n   * Default: 2. Set to 0 to disable retries entirely.\n   */\n  maxRetries?: number;\n\n  /**\n   * Scaffold a new Next.js app when run in an empty directory.\n   * Auto-enabled in headless mode; opt-in via --scaffold in interactive mode.\n   */\n  scaffold?: boolean;\n\n  /**\n   * Package manager for the scaffolded app (npm/pnpm/yarn/bun).\n   * Overrides detection from npm_config_user_agent.\n   */\n  pm?: string;\n};\n\nexport interface Feature {\n  id: string;\n  prompt: string;\n  enabledHint?: string;\n  disabledHint?: string;\n}\n\nexport type FileChange = {\n  filePath: string;\n  oldContent?: string;\n  newContent: string;\n};\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "workos",
-  "version": "0.15.2",
+  "version": "0.17.0",
   "type": "module",
   "description": "The Official Workos CLI",
   "repository": {