@amplitude/wizard 1.0.0-beta.0 → 1.0.0-beta.1

package/dist/src/ui/tui/screens/IntroScreen.js

@@ -46,7 +46,7 @@ export const IntroScreen = ({ store }) => {
                             { label: 'Cancel', value: 'cancel' },
                         ], onSelect: (value) => {
                             const choice = Array.isArray(value) ? value[0] : value;
-                            analytics.wizardCapture('intro action', {
+                            analytics.wizardCapture('Intro Action', {
                                 action: choice,
                                 integration: session.integration,
                                 detected_framework: session.detectedFrameworkLabel,
@@ -75,7 +75,7 @@ const FrameworkPicker = ({ store, onComplete, }) => {
     }));
     return (_jsx(PickerMenu, { centered: true, columns: 2, message: "Select your framework", options: options, onSelect: (value) => {
             const integration = Array.isArray(value) ? value[0] : value;
-            analytics.wizardCapture('framework manually selected', { integration });
+            analytics.wizardCapture('Framework Manually Selected', { integration });
             void import('../../../lib/registry.js').then(({ FRAMEWORK_REGISTRY }) => {
                 const config = FRAMEWORK_REGISTRY[integration];
                 store.setFrameworkConfig(integration, config);

package/dist/src/ui/tui/screens/McpScreen.js

@@ -17,7 +17,7 @@ import { useSyncExternalStore } from 'react';
 import { McpOutcome, RunPhase } from '../store.js';
 import { ConfirmationInput, PickerMenu } from '../primitives/index.js';
 import { Colors } from '../styles.js';
-import { analytics } from '../../../utils/analytics.js';
+import { analytics, captureWizardError } from '../../../utils/analytics.js';
 var Phase;
 (function (Phase) {
     Phase["Detecting"] = "detecting";
@@ -41,22 +41,25 @@ const markDone = (store, outcome, clients = [], standalone = false, onComplete)
 export const McpScreen = ({ store, installer, mode = 'install', standalone = false, onComplete, }) => {
     useSyncExternalStore((cb) => store.subscribe(cb), () => store.getSnapshot());
     const isRemove = mode === 'remove';
-    const { runPhase, amplitudePreDetected } = store.session;
+    const { runPhase, amplitudePreDetected, amplitudePreDetectedChoicePending } = store.session;
     const dataSetupComplete = runPhase === RunPhase.Completed;
     const [phase, setPhase] = useState(Phase.Detecting);
     const [clients, setClients] = useState([]);
     const [resultClients, setResultClients] = useState([]);
     useEffect(() => {
+        if (amplitudePreDetectedChoicePending) {
+            return;
+        }
         void (async () => {
             try {
                 const detected = await installer.detectClients();
                 if (detected.length === 0) {
-                    analytics.wizardCapture('mcp no clients detected', { mode });
+                    analytics.wizardCapture('MCP No Clients Detected', { mode });
                     setPhase(Phase.None);
                     setTimeout(() => markDone(store, McpOutcome.NoClients, [], standalone, onComplete), 1500);
                 }
                 else {
-                    analytics.wizardCapture('mcp clients detected', {
+                    analytics.wizardCapture('MCP Clients Detected', {
                         mode,
                         clients: detected.map((c) => c.name),
                         count: detected.length,
@@ -66,31 +69,31 @@ export const McpScreen = ({ store, installer, mode = 'install', standalone = fal
                 }
             }
             catch {
-                analytics.wizardCapture('mcp detection failed', { mode });
+                captureWizardError('MCP Client Detection', 'Editor client detection failed', 'McpScreen', { mode });
                 setPhase(Phase.None);
                 setTimeout(() => markDone(store, McpOutcome.Failed, [], standalone, onComplete), 1500);
             }
         })();
-    }, [installer]);
+    }, [installer, amplitudePreDetectedChoicePending]);
     const handleConfirm = () => {
         if (isRemove) {
-            analytics.wizardCapture('mcp remove confirmed');
+            analytics.wizardCapture('MCP Remove Confirmed');
             void doRemove();
         }
         else if (clients.length === 1) {
             const names = clients.map((c) => c.name);
-            analytics.wizardCapture('mcp install confirmed', { clients: names });
+            analytics.wizardCapture('MCP Install Confirmed', { clients: names });
             void doInstall(names);
         }
         else {
-            analytics.wizardCapture('mcp client picker shown', {
+            analytics.wizardCapture('MCP Client Picker Shown', {
                 available_clients: clients.map((c) => c.name),
             });
             setPhase(Phase.Pick);
         }
     };
     const handleSkip = () => {
-        analytics.wizardCapture('mcp skipped', { mode });
+        analytics.wizardCapture('MCP Skipped', { mode });
         markDone(store, McpOutcome.Skipped, [], standalone, onComplete);
     };
     const doInstall = async (names) => {
@@ -104,7 +107,7 @@ export const McpScreen = ({ store, installer, mode = 'install', standalone = fal
             setResultClients([]);
         }
         const failed = names.filter((n) => !result.includes(n));
-        analytics.wizardCapture('mcp install complete', {
+        analytics.wizardCapture('MCP Install Complete', {
             installed: result,
             failed,
             attempted: names,
@@ -123,26 +126,38 @@ export const McpScreen = ({ store, installer, mode = 'install', standalone = fal
         catch {
             setResultClients([]);
         }
-        analytics.wizardCapture('mcp remove complete', { removed: result });
+        analytics.wizardCapture('MCP Remove Complete', { removed: result });
         setPhase(Phase.Done);
         const outcome = result.length > 0 ? McpOutcome.Installed : McpOutcome.Failed;
         setTimeout(() => markDone(store, outcome, result, standalone, onComplete), 2000);
     };
     return (_jsxs(Box, { flexDirection: "column", flexGrow: 1, children: [dataSetupComplete && (_jsx(Box, { marginBottom: 1, children: _jsx(Text, { color: "green", bold: true, children: amplitudePreDetected
                         ? '\u2714 Amplitude is already configured in this project!'
-                        : '\u2714 Data setup complete!' }) })), _jsxs(Text, { bold: true, color: Colors.accent, children: ["MCP Server ", isRemove ? 'Removal' : 'Setup'] }), _jsxs(Box, { marginTop: 1, flexDirection: "column", children: [phase === Phase.Detecting && (_jsx(Text, { color: Colors.muted, children: "Detecting supported editors..." })), phase === Phase.None && (_jsxs(Text, { color: Colors.muted, children: ["No ", isRemove ? 'installed' : 'supported', " MCP clients detected. Skipping..."] })), phase === Phase.Ask && (_jsxs(_Fragment, { children: [_jsxs(Text, { color: Colors.muted, children: ["Detected: ", clients.map((c) => c.name).join(', ')] }), _jsx(Box, { marginTop: 1, children: _jsx(ConfirmationInput, { message: isRemove
-                                        ? 'Remove the Amplitude MCP server from your editor?'
-                                        : 'Install the Amplitude MCP server to your editor?', confirmLabel: isRemove ? 'Remove MCP' : 'Install MCP', cancelLabel: "No thanks", onConfirm: handleConfirm, onCancel: handleSkip }) })] })), phase === Phase.Pick && (_jsx(PickerMenu, { message: "Select editor to install MCP server", options: clients.map((c) => ({
-                            label: c.name,
-                            value: c.name,
-                        })), mode: "multi", onSelect: (selected) => {
-                            const names = Array.isArray(selected) ? selected : [selected];
-                            if (names.length === 0)
-                                return;
-                            analytics.wizardCapture('mcp clients selected', {
-                                selected_clients: names,
-                                available_clients: clients.map((c) => c.name),
-                            });
-                            void doInstall(names);
-                        } })), phase === Phase.Working && (_jsxs(Text, { color: Colors.muted, children: [isRemove ? 'Removing' : 'Installing', " MCP server..."] })), phase === Phase.Done && (_jsx(Box, { flexDirection: "column", children: resultClients.length > 0 ? (_jsxs(_Fragment, { children: [_jsxs(Text, { color: "green", bold: true, children: ['\u2714', " MCP server", ' ', isRemove ? 'removed from' : 'installed for', ":"] }), resultClients.map((name, i) => (_jsxs(Text, { children: [' ', '\u2022', " ", name] }, i)))] })) : (_jsxs(Text, { color: Colors.muted, children: [isRemove ? 'Removal' : 'Installation', " skipped."] })) }))] })] }));
+                        : '\u2714 Data setup complete!' }) })), amplitudePreDetectedChoicePending && !isRemove && (_jsxs(Box, { marginBottom: 1, flexDirection: "column", children: [_jsx(Text, { color: Colors.muted, children: "The installer skipped the automated setup step because Amplitude is already present. You can continue to editor MCP setup, or run the full setup wizard if you want to review or change the integration." }), _jsx(Box, { marginTop: 1, children: _jsx(PickerMenu, { message: "How would you like to proceed?", options: [
+                                { label: 'Continue to MCP setup', value: 'continue' },
+                                {
+                                    label: 'Run setup wizard anyway',
+                                    value: 'wizard',
+                                },
+                            ], onSelect: (value) => {
+                                const runWizard = value === 'wizard';
+                                analytics.wizardCapture('Amplitude Pre-Detected Choice', {
+                                    run_wizard_anyway: runWizard,
+                                });
+                                store.resolvePreDetectedChoice(runWizard);
+                            } }) })] })), !amplitudePreDetectedChoicePending && (_jsxs(_Fragment, { children: [_jsxs(Text, { bold: true, color: Colors.accent, children: ["MCP Server ", isRemove ? 'Removal' : 'Setup'] }), _jsxs(Box, { marginTop: 1, flexDirection: "column", children: [phase === Phase.Detecting && (_jsx(Text, { color: Colors.muted, children: "Detecting supported editors..." })), phase === Phase.None && (_jsxs(Text, { color: Colors.muted, children: ["No ", isRemove ? 'installed' : 'supported', " MCP clients detected. Skipping..."] })), phase === Phase.Ask && (_jsxs(_Fragment, { children: [_jsxs(Text, { color: Colors.muted, children: ["Detected: ", clients.map((c) => c.name).join(', ')] }), _jsx(Box, { marginTop: 1, children: _jsx(ConfirmationInput, { message: isRemove
+                                                ? 'Remove the Amplitude MCP server from your editor?'
+                                                : 'Install the Amplitude MCP server to your editor?', confirmLabel: isRemove ? 'Remove MCP' : 'Install MCP', cancelLabel: "No thanks", onConfirm: handleConfirm, onCancel: handleSkip }) })] })), phase === Phase.Pick && (_jsx(PickerMenu, { message: "Select editor to install MCP server", options: clients.map((c) => ({
+                                    label: c.name,
+                                    value: c.name,
+                                })), mode: "multi", onSelect: (selected) => {
+                                    const names = Array.isArray(selected) ? selected : [selected];
+                                    if (names.length === 0)
+                                        return;
+                                    analytics.wizardCapture('MCP Clients Selected', {
+                                        selected_clients: names,
+                                        available_clients: clients.map((c) => c.name),
+                                    });
+                                    void doInstall(names);
+                                } })), phase === Phase.Working && (_jsxs(Text, { color: Colors.muted, children: [isRemove ? 'Removing' : 'Installing', " MCP server..."] })), phase === Phase.Done && (_jsx(Box, { flexDirection: "column", children: resultClients.length > 0 ? (_jsxs(_Fragment, { children: [_jsxs(Text, { color: "green", bold: true, children: ['\u2714', " MCP server", ' ', isRemove ? 'removed from' : 'installed for', ":"] }), resultClients.map((name, i) => (_jsxs(Text, { children: [' ', '\u2022', " ", name] }, i)))] })) : (_jsxs(Text, { color: Colors.muted, children: [isRemove ? 'Removal' : 'Installation', " skipped."] })) }))] })] }))] }));
 };

package/dist/src/ui/tui/screens/OutroScreen.js

@@ -47,7 +47,7 @@ export const OutroScreen = ({ store }) => {
                         { label: 'Exit', value: 'exit' },
                     ], onSelect: (value) => {
                         const choice = Array.isArray(value) ? value[0] : value;
-                        analytics.wizardCapture('outro action', {
+                        analytics.wizardCapture('Outro Action', {
                             action: choice,
                             outro_kind: outroData.kind,
                         });

package/dist/src/ui/tui/store.d.ts

@@ -72,6 +72,8 @@ export declare class WizardStore {
     private _backupAndFixSettings;
     /** Pending confirmation or choice prompt from the agent. */
     private $pendingPrompt;
+    /** Resolves when the user picks continue vs run wizard after Amplitude pre-detection. */
+    private _preDetectedChoiceResolver;
     constructor(flow?: Flow);
     get session(): WizardSession;
     set session(value: WizardSession);
@@ -94,6 +96,7 @@ export declare class WizardStore {
     completeSetup(): void;
     setRunPhase(phase: RunPhase): void;
     setCredentials(credentials: WizardSession['credentials']): void;
+    setApiKeyNotice(notice: string | null): void;
     setFrameworkConfig(integration: WizardSession['integration'], config: WizardSession['frameworkConfig']): void;
     setDetectionComplete(): void;
     setDetectedFramework(label: string): void;
@@ -188,6 +191,20 @@ export declare class WizardStore {
      */
     enableFeature(feature: AdditionalFeature): void;
     setAmplitudePreDetected(): void;
+    /**
+     * Blocks bin.ts until McpScreen resolves via resolvePreDetectedChoice().
+     */
+    waitForPreDetectedChoice(): Promise<boolean>;
+    /**
+     * Called from McpScreen when the user chooses to skip the agent (continue to
+     * MCP) or run the full setup wizard anyway.
+     */
+    resolvePreDetectedChoice(runWizardAnyway: boolean): void;
+    /**
+     * Undo the pre-detection fast-path so runWizard can run; used when the user
+     * opts into the setup agent after Amplitude was already found in the project.
+     */
+    resetForAgentAfterPreDetected(): void;
     setMcpComplete(outcome?: McpOutcome, installedClients?: string[]): void;
     setSlackComplete(outcome?: SlackOutcome): void;
     setOutroData(data: OutroData): void;

package/dist/src/ui/tui/store.js

@@ -13,7 +13,7 @@ import { atom, map } from 'nanostores';
 import { TaskStatus } from '../wizard-ui.js';
 import { AdditionalFeature, McpOutcome, SlackOutcome, RunPhase, buildSession, } from '../../lib/wizard-session.js';
 import { WizardRouter, Screen, Overlay, Flow, } from './router.js';
-import { analytics, sessionProperties } from '../../utils/analytics.js';
+import { analytics, sessionPropertiesCompact } from '../../utils/analytics.js';
 export { TaskStatus, Screen, Overlay, Flow, RunPhase, McpOutcome, SlackOutcome, };
 export class WizardStore {
     // ── Internal nanostore atoms ─────────────────────────────────────
@@ -51,6 +51,8 @@ export class WizardStore {
     _backupAndFixSettings = null;
     /** Pending confirmation or choice prompt from the agent. */
     $pendingPrompt = atom(null);
+    /** Resolves when the user picks continue vs run wizard after Amplitude pre-detection. */
+    _preDetectedChoiceResolver = null;
     constructor(flow = Flow.Wizard) {
         this.router = new WizardRouter(flow);
     }
@@ -103,7 +105,7 @@ export class WizardStore {
      */
     completeSetup() {
         this.$session.setKey('setupConfirmed', true);
-        analytics.wizardCapture('setup confirmed', sessionProperties(this.session));
+        analytics.wizardCapture('Setup Confirmed', sessionPropertiesCompact(this.session));
         this._resolveSetup();
         this.emitChange();
     }
@@ -116,15 +118,16 @@ export class WizardStore {
         if (credentials?.projectId) {
             analytics.setDistinctId(String(credentials.projectId));
         }
-        analytics.wizardCapture('auth complete', {
-            project_id: credentials?.projectId,
-        });
-        analytics.wizardCapture('credentials updated', {
+        analytics.wizardCapture('Auth Complete', {
             project_id: credentials?.projectId,
             region: this.session.region,
         });
         this.emitChange();
     }
+    setApiKeyNotice(notice) {
+        this.$session.setKey('apiKeyNotice', notice);
+        this.emitChange();
+    }
     setFrameworkConfig(integration, config) {
         this.$session.setKey('integration', integration);
         this.$session.setKey('frameworkConfig', config);
@@ -194,7 +197,7 @@ export class WizardStore {
         const prompt = this.$pendingPrompt.get();
         if (!prompt || prompt.kind === 'event-plan')
             return;
-        analytics.wizardCapture('prompt response', {
+        analytics.wizardCapture('Prompt Response', {
             prompt_kind: prompt.kind,
             response: String(answer),
         });
@@ -219,7 +222,7 @@ export class WizardStore {
         const prompt = this.$pendingPrompt.get();
         if (!prompt || prompt.kind !== 'event-plan')
             return;
-        analytics.wizardCapture('prompt response', {
+        analytics.wizardCapture('Prompt Response', {
             prompt_kind: 'event-plan',
             response: typeof decision === 'object' ? 'feedback' : String(decision),
         });
@@ -303,7 +306,7 @@ export class WizardStore {
     }
     setDataIngestionConfirmed() {
         this.$session.setKey('dataIngestionConfirmed', true);
-        analytics.wizardCapture('data ingestion confirmed', sessionProperties(this.session));
+        analytics.wizardCapture('Data Ingestion Confirmed', sessionPropertiesCompact(this.session));
         this.emitChange();
     }
     setChecklistChartComplete() {
@@ -316,10 +319,10 @@ export class WizardStore {
     }
     setChecklistComplete() {
         this.$session.setKey('checklistComplete', true);
-        analytics.wizardCapture('checklist completed', {
+        analytics.wizardCapture('Checklist Completed', {
             chart_complete: this.session.checklistChartComplete,
             dashboard_complete: this.session.checklistDashboardComplete,
-            ...sessionProperties(this.session),
+            ...sessionPropertiesCompact(this.session),
         });
         this.emitChange();
     }
@@ -411,30 +414,62 @@ export class WizardStore {
         if (feature === AdditionalFeature.LLM) {
             this.session.llmOptIn = true;
         }
-        analytics.wizardCapture('feature enabled', { feature });
+        analytics.wizardCapture('Feature Enabled', { feature });
         this.emitChange();
     }
     setAmplitudePreDetected() {
         this.$session.setKey('amplitudePreDetected', true);
+        this.$session.setKey('amplitudePreDetectedChoicePending', true);
+        this.emitChange();
+    }
+    /**
+     * Blocks bin.ts until McpScreen resolves via resolvePreDetectedChoice().
+     */
+    waitForPreDetectedChoice() {
+        return new Promise((resolve) => {
+            this._preDetectedChoiceResolver = resolve;
+        });
+    }
+    /**
+     * Called from McpScreen when the user chooses to skip the agent (continue to
+     * MCP) or run the full setup wizard anyway.
+     */
+    resolvePreDetectedChoice(runWizardAnyway) {
+        const resolveFn = this._preDetectedChoiceResolver;
+        this._preDetectedChoiceResolver = null;
+        if (!runWizardAnyway) {
+            this.$session.setKey('amplitudePreDetectedChoicePending', false);
+        }
+        this.emitChange();
+        resolveFn?.(runWizardAnyway);
+    }
+    /**
+     * Undo the pre-detection fast-path so runWizard can run; used when the user
+     * opts into the setup agent after Amplitude was already found in the project.
+     */
+    resetForAgentAfterPreDetected() {
+        this.$session.setKey('amplitudePreDetected', false);
+        this.$session.setKey('amplitudePreDetectedChoicePending', false);
+        this.$session.setKey('runPhase', RunPhase.Idle);
         this.emitChange();
     }
     setMcpComplete(outcome = McpOutcome.Skipped, installedClients = []) {
         this.$session.setKey('mcpComplete', true);
         this.$session.setKey('mcpOutcome', outcome);
         this.$session.setKey('mcpInstalledClients', installedClients);
-        analytics.wizardCapture('mcp complete', {
+        analytics.wizardCapture('MCP Complete', {
             mcp_outcome: outcome,
             mcp_installed_clients: installedClients,
-            ...sessionProperties(this.session),
+            ...sessionPropertiesCompact(this.session),
         });
         this.emitChange();
     }
     setSlackComplete(outcome = SlackOutcome.Skipped) {
         this.$session.setKey('slackComplete', true);
         this.$session.setKey('slackOutcome', outcome);
-        analytics.wizardCapture('slack complete', {
+        analytics.wizardCapture('Slack Complete', {
             slack_outcome: outcome,
-            ...sessionProperties(this.session),
+            ...sessionPropertiesCompact(this.session),
         });
         this.emitChange();
     }
@@ -512,9 +547,10 @@ export class WizardStore {
                 for (const fn of hooks)
                     fn();
             }
-            analytics.wizardCapture(`screen ${next}`, {
-                from_screen: prev,
-                ...sessionProperties(this.session),
+            analytics.wizardCapture('Wizard Screen Entered', {
+                screen_name: next,
+                previous_screen: prev,
+                ...sessionPropertiesCompact(this.session),
             });
         }
     }

package/dist/src/utils/analytics.d.ts

@@ -1,17 +1,29 @@
 import type { WizardSession } from '../lib/wizard-session';
+/**
+ * Telemetry project API key. Empty or whitespace-only env value means “no key”
+ * (use default only when the variable is unset).
+ */
+export declare function resolveTelemetryApiKey(): string;
+/** HTTP API URL for `@amplitude/analytics-node` (same shape as manual HTTP ingest). */
+export declare function getAmplitudeNodeServerUrl(): string;
 /**
  * Extract a standard property bag from the current session.
  * Used by store-level analytics and available for ad-hoc captures.
  */
 export declare function sessionProperties(session: WizardSession): Record<string, unknown>;
+/**
+ * Smaller session bag for high-volume wizard events (taxonomy: keep event
+ * properties chart-useful and within a small count).
+ */
+export declare function sessionPropertiesCompact(session: WizardSession): Record<string, unknown>;
 export declare class Analytics {
     private tags;
     private distinctId?;
     private anonymousId;
     private appName;
     private activeFlags;
-    private pendingEvents;
-    private flushTimer;
+    private readonly client;
+    private initPromise;
     constructor();
     setDistinctId(distinctId: string): void;
     setTag(key: string, value: string | boolean | number | null | undefined): void;
@@ -20,9 +32,11 @@ export declare class Analytics {
     /**
      * Capture a wizard-specific event. Automatically prepends "wizard: " to the event name.
      * All new wizard analytics should use this method instead of capture() directly.
+     * Use lowercase with spaces for eventName (e.g. "agent started", "api key submitted")
+     * per Amplitude quickstart taxonomy guidelines.
      */
     wizardCapture(eventName: string, properties?: Record<string, unknown>): void;
-    private flush;
+    private ensureInitStarted;
     getFeatureFlag(flagKey: string): Promise<string | boolean | undefined>;
     /**
      * Evaluate all feature flags for the current user at the start of a run.
@@ -32,4 +46,14 @@ export declare class Analytics {
     getAllFlagsForWizard(): Promise<Record<string, string>>;
     shutdown(status: 'success' | 'error' | 'cancelled'): Promise<void>;
 }
+/**
+ * Full Amplitude `event_type` for CLI/TUI product feedback.
+ * Same string as `wizardCapture('Feedback Submitted', …)`.
+ */
+export declare const WIZARD_FEEDBACK_EVENT_TYPE = "wizard: feedback submitted";
 export declare const analytics: Analytics;
+/**
+ * Unified wizard error telemetry (aligns with starter taxonomy “Error Encountered”).
+ * Emits `wizard: error encountered` with category / message / context.
+ */
+export declare function captureWizardError(errorCategory: string, errorMessage: string, errorContext: string, extra?: Record<string, unknown>): void;

package/dist/src/utils/analytics.js

@@ -1,11 +1,29 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.analytics = exports.Analytics = void 0;
+exports.analytics = exports.WIZARD_FEEDBACK_EVENT_TYPE = exports.Analytics = void 0;
+exports.resolveTelemetryApiKey = resolveTelemetryApiKey;
+exports.getAmplitudeNodeServerUrl = getAmplitudeNodeServerUrl;
 exports.sessionProperties = sessionProperties;
+exports.sessionPropertiesCompact = sessionPropertiesCompact;
+exports.captureWizardError = captureWizardError;
+const analytics_node_1 = require("@amplitude/analytics-node");
 const uuid_1 = require("uuid");
 const debug_1 = require("./debug");
-const AMPLITUDE_API_KEY = process.env.AMPLITUDE_API_KEY ?? 'e5a2c9bdffe949f7da77e6b481e118fa';
-const AMPLITUDE_SERVER_URL = process.env.AMPLITUDE_SERVER_URL ?? 'https://api2.amplitude.com';
+const DEFAULT_TELEMETRY_API_KEY = 'e5a2c9bdffe949f7da77e6b481e118fa';
+/**
+ * Telemetry project API key. Empty or whitespace-only env value means “no key”
+ * (use default only when the variable is unset).
+ */
+function resolveTelemetryApiKey() {
+    const fromEnv = process.env.AMPLITUDE_API_KEY;
+    const raw = fromEnv !== undefined ? fromEnv : DEFAULT_TELEMETRY_API_KEY;
+    return raw.trim();
+}
+/** HTTP API URL for `@amplitude/analytics-node` (same shape as manual HTTP ingest). */
+function getAmplitudeNodeServerUrl() {
+    const base = process.env.AMPLITUDE_SERVER_URL ?? 'https://api2.amplitude.com';
+    return `${base.replace(/\/$/, '')}/2/httpapi`;
+}
 /**
  * Extract a standard property bag from the current session.
  * Used by store-level analytics and available for ad-hoc captures.
@@ -21,18 +39,31 @@ function sessionProperties(session) {
         run_phase: session.runPhase,
     };
 }
+/**
+ * Smaller session bag for high-volume wizard events (taxonomy: keep event
+ * properties chart-useful and within a small count).
+ */
+function sessionPropertiesCompact(session) {
+    return {
+        integration: session.integration,
+        detected_framework: session.detectedFrameworkLabel,
+        run_phase: session.runPhase,
+        project_id: session.credentials?.projectId,
+    };
+}
 class Analytics {
     tags = {};
     distinctId;
     anonymousId;
     appName = 'wizard';
     activeFlags = null;
-    pendingEvents = [];
-    flushTimer = null;
+    client;
+    initPromise = null;
     constructor() {
         this.tags = { $app_name: this.appName };
         this.anonymousId = (0, uuid_1.v4)();
         this.distinctId = undefined;
+        this.client = (0, analytics_node_1.createInstance)();
     }
     setDistinctId(distinctId) {
         this.distinctId = distinctId;
@@ -48,59 +79,45 @@ class Analytics {
         });
     }
     capture(eventName, properties) {
-        if (!AMPLITUDE_API_KEY) {
+        const apiKey = resolveTelemetryApiKey();
+        if (!apiKey) {
             (0, debug_1.debug)('capture (no API key):', eventName, properties);
             return;
         }
-        const event = {
-            event_type: eventName,
+        this.ensureInitStarted();
+        const eventProps = {
+            ...this.tags,
+            ...properties,
+        };
+        const options = {
             device_id: this.anonymousId,
-            time: Date.now(),
-            event_properties: {
-                ...this.tags,
-                ...properties,
-            },
         };
         if (this.distinctId) {
-            event.user_id = this.distinctId;
+            options.user_id = this.distinctId;
         }
-        this.pendingEvents.push(event);
+        this.client.track(eventName, eventProps, options);
         (0, debug_1.debug)('capture:', eventName, properties);
-        // Debounce flush to batch events
-        if (this.flushTimer) {
-            clearTimeout(this.flushTimer);
-        }
-        this.flushTimer = setTimeout(() => {
-            void this.flush();
-        }, 500);
     }
     /**
      * Capture a wizard-specific event. Automatically prepends "wizard: " to the event name.
      * All new wizard analytics should use this method instead of capture() directly.
+     * Use lowercase with spaces for eventName (e.g. "agent started", "api key submitted")
+     * per Amplitude quickstart taxonomy guidelines.
      */
     wizardCapture(eventName, properties) {
         this.capture(`wizard: ${eventName}`, properties);
     }
-    async flush() {
-        if (this.pendingEvents.length === 0)
-            return;
-        if (!AMPLITUDE_API_KEY)
+    ensureInitStarted() {
+        if (this.initPromise !== null) {
             return;
-        const events = [...this.pendingEvents];
-        this.pendingEvents = [];
-        try {
-            const response = await fetch(`${AMPLITUDE_SERVER_URL}/2/httpapi`, {
-                method: 'POST',
-                headers: { 'Content-Type': 'application/json' },
-                body: JSON.stringify({ api_key: AMPLITUDE_API_KEY, events }),
-            });
-            if (!response.ok) {
-                (0, debug_1.debug)('Amplitude upload failed:', response.status, await response.text());
-            }
         }
-        catch (err) {
-            (0, debug_1.debug)('Amplitude upload error:', err);
+        const apiKey = resolveTelemetryApiKey();
+        if (!apiKey) {
+            return;
         }
+        this.initPromise = this.client.init(apiKey, {
+            serverUrl: getAmplitudeNodeServerUrl(),
+        }).promise;
     }
     // eslint-disable-next-line @typescript-eslint/require-await
     async getFeatureFlag(flagKey) {
@@ -121,13 +138,35 @@ class Analytics {
         return this.activeFlags;
     }
     async shutdown(status) {
-        if (this.flushTimer) {
-            clearTimeout(this.flushTimer);
-            this.flushTimer = null;
+        this.wizardCapture('Session Ended', { status });
+        if (this.initPromise === null) {
+            return;
+        }
+        try {
+            await this.initPromise;
+            await this.client.flush().promise;
+        }
+        catch (err) {
+            (0, debug_1.debug)('analytics shutdown flush error:', err);
         }
-        this.capture('wizard: session ended', { status });
-        await this.flush();
     }
 }
 exports.Analytics = Analytics;
+/**
+ * Full Amplitude `event_type` for CLI/TUI product feedback.
+ * Same string as `wizardCapture('Feedback Submitted', …)`.
+ */
+exports.WIZARD_FEEDBACK_EVENT_TYPE = 'wizard: feedback submitted';
 exports.analytics = new Analytics();
+/**
+ * Unified wizard error telemetry (aligns with starter taxonomy “Error Encountered”).
+ * Emits `wizard: error encountered` with category / message / context.
+ */
+function captureWizardError(errorCategory, errorMessage, errorContext, extra) {
+    exports.analytics.wizardCapture('Error Encountered', {
+        error_category: errorCategory,
+        error_message: errorMessage,
+        error_context: errorContext,
+        ...extra,
+    });
+}

package/dist/src/utils/oauth.js

@@ -315,7 +315,7 @@ async function performAmplitudeAuth(options) {
             (0, index_js_1.getUI)().log.info(`${chalk_1.default.yellow('Authorization was cancelled.')}\n\nRe-run the wizard to try again.`);
         }
         else {
-            (0, index_js_1.getUI)().log.error(`${chalk_1.default.red('Authorization failed:')}\n\n${error.message}\n\n${chalk_1.default.dim(`File an issue:\n${constants_js_1.ISSUES_URL}`)}`);
+            (0, index_js_1.getUI)().log.error(`${chalk_1.default.red('Authorization failed:')}\n\n${error.message}\n\n${chalk_1.default.dim(`File an issue:\n${constants_js_1.OUTBOUND_URLS.githubIssues}`)}`);
         }
         analytics_js_1.analytics.captureException(error, { step: 'oauth_flow' });
         await (0, setup_utils_js_1.abort)();