@amplitude/wizard 1.0.0-beta.0

package/dist/src/lib/constants.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Shared constants for the Amplitude wizard.
+ */
+/**
+ * Detection order matters: put framework-specific integrations BEFORE basic language fallbacks.
+ */
+export declare enum Integration {
+    nextjs = "nextjs",
+    vue = "vue",
+    reactRouter = "react-router",
+    django = "django",
+    flask = "flask",
+    fastapi = "fastapi",
+    swift = "swift",
+    reactNative = "react-native",
+    android = "android",
+    flutter = "flutter",
+    go = "go",
+    java = "java",
+    unreal = "unreal",
+    unity = "unity",
+    javascript_web = "javascript_web",
+    python = "python",
+    javascriptNode = "javascript_node",
+    generic = "generic"
+}
+export interface Args {
+    debug: boolean;
+    integration: Integration;
+}
+export declare const IS_DEV: boolean;
+export declare const DEBUG = false;
+export declare const DEFAULT_URL: string;
+export declare const DEFAULT_HOST_URL: string;
+export declare const ANALYTICS_AMPLITUDE_PUBLIC_PROJECT_WRITE_KEY = "";
+export declare const ANALYTICS_HOST_URL = "";
+export declare const ANALYTICS_TEAM_TAG = "amplitude-wizard";
+/** Matches the port used by the ampli CLI so sessions are interoperable. */
+export declare const OAUTH_PORT = 13222;
+export declare const AMPLITUDE_ZONE_SETTINGS: {
+    readonly us: {
+        readonly oAuthHost: string;
+        readonly oAuthClientId: string;
+        readonly dataApiUrl: "https://data-api.amplitude.com/graphql";
+        /** Thunder GraphQL endpoint — org-scoped. Append the numeric orgId. */
+        readonly appApiUrlBase: "https://amplitude.com/graphql/org/";
+        readonly webUrl: "https://data.amplitude.com";
+    };
+    readonly eu: {
+        readonly oAuthHost: "https://auth.eu.amplitude.com";
+        readonly oAuthClientId: string;
+        readonly dataApiUrl: "https://data-api.eu.amplitude.com/graphql";
+        /** Thunder GraphQL endpoint — org-scoped. Append the numeric orgId. */
+        readonly appApiUrlBase: "https://amplitude.eu/graphql/org/";
+        readonly webUrl: "https://data.eu.amplitude.com";
+    };
+};
+export type AmplitudeZone = keyof typeof AMPLITUDE_ZONE_SETTINGS;
+export declare const DEFAULT_AMPLITUDE_ZONE: AmplitudeZone;
+/**
+ * Every URL the wizard opens in the browser or presents as a link to the user.
+ * Keep this inventory accurate — the Amplitude UI uses it to allowlist outbound
+ * navigation from the wizard.
+ *
+ * Zone-dependent entries are keyed by AmplitudeZone.
+ * Builder functions compose the full URL from the base + runtime data (orgId, orgName).
+ */
+export declare const OUTBOUND_URLS: {
+    /** App base — used for chart/dashboard/checklist deep-links. */
+    app: Record<AmplitudeZone, string>;
+    /** Overview base — used for Outro, Slack settings, and sign-up continuation. */
+    overview: Record<AmplitudeZone, string>;
+    /** OAuth authorization page — opened automatically to start sign-in. */
+    oAuth: (zone: AmplitudeZone) => string;
+    /** New segmentation chart — opened from the Checklist screen. */
+    newChart: (zone: AmplitudeZone, orgId?: string | null) => string;
+    /** New dashboard — opened from the Checklist screen. */
+    newDashboard: (zone: AmplitudeZone, orgId?: string | null) => string;
+    /** Slack integration settings — opened from the Slack screen. */
+    slackSettings: (zone: AmplitudeZone, orgName?: string | null) => string;
+    /** Products page — shown in the Outro for sign-up users. */
+    products: (zone: AmplitudeZone) => string;
+    /** SDK overview — opened from the Activation Options screen. */
+    sdkDocs: string;
+    /** Per-framework SDK docs — referenced in agent prompts and post-run links. */
+    frameworkDocs: {
+        browser: string;
+        python: string;
+        java: string;
+        go: string;
+        android: string;
+        reactNative: string;
+        ios: string;
+        flutter: string;
+        unity: string;
+        unreal: string;
+    };
+    /** Stripe data-source deep-link — shown as a tip in the RunScreen. */
+    stripeDataSource: string;
+    /** Service status pages — shown in the OutageOverlay. */
+    status: {
+        claude: string;
+        amplitude: string;
+    };
+    /** Bug reports and feedback. */
+    githubIssues: string;
+};
+/** @deprecated Use OUTBOUND_URLS.githubIssues */
+export declare const ISSUES_URL: string;
+/** Placeholder embedded in generated code when the user skips key entry. */
+export declare const DUMMY_PROJECT_API_KEY = "_YOUR_AMPLITUDE_API_KEY_";
+export declare const WIZARD_REMARK_EVENT_NAME = "wizard remark";
+/** Feature flag key whose value selects a variant from WIZARD_VARIANTS. */
+export declare const WIZARD_VARIANT_FLAG_KEY = "wizard-variant";
+/** Variant key -> metadata for wizard run (VARIANT flag selects which entry to use). */
+export declare const WIZARD_VARIANTS: Record<string, Record<string, string>>;
+/** User-Agent for wizard HTTP requests and MCP server identification. */
+export declare const WIZARD_USER_AGENT: string;
+/** Header prefix for Amplitude properties. */
+export declare const AMPLITUDE_PROPERTY_HEADER_PREFIX = "X-AMPLITUDE-PROPERTY-";
+/** Header prefix for Amplitude feature flags. */
+export declare const AMPLITUDE_FLAG_HEADER_PREFIX = "X-AMPLITUDE-FLAG-";
+/** Timeout for framework / project detection probes (ms). */
+export declare const DETECTION_TIMEOUT_MS = 10000;

package/dist/src/lib/constants.js

@@ -0,0 +1,170 @@
+"use strict";
+/**
+ * Shared constants for the Amplitude wizard.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DETECTION_TIMEOUT_MS = exports.AMPLITUDE_FLAG_HEADER_PREFIX = exports.AMPLITUDE_PROPERTY_HEADER_PREFIX = exports.WIZARD_USER_AGENT = exports.WIZARD_VARIANTS = exports.WIZARD_VARIANT_FLAG_KEY = exports.WIZARD_REMARK_EVENT_NAME = exports.DUMMY_PROJECT_API_KEY = exports.ISSUES_URL = exports.OUTBOUND_URLS = exports.DEFAULT_AMPLITUDE_ZONE = exports.AMPLITUDE_ZONE_SETTINGS = exports.OAUTH_PORT = exports.ANALYTICS_TEAM_TAG = exports.ANALYTICS_HOST_URL = exports.ANALYTICS_AMPLITUDE_PUBLIC_PROJECT_WRITE_KEY = exports.DEFAULT_HOST_URL = exports.DEFAULT_URL = exports.DEBUG = exports.IS_DEV = exports.Integration = void 0;
+const package_json_1 = require("../../package.json");
+// ── Integration / CLI ───────────────────────────────────────────────
+/**
+ * Detection order matters: put framework-specific integrations BEFORE basic language fallbacks.
+ */
+var Integration;
+(function (Integration) {
+    // Frameworks
+    Integration["nextjs"] = "nextjs";
+    Integration["vue"] = "vue";
+    Integration["reactRouter"] = "react-router";
+    Integration["django"] = "django";
+    Integration["flask"] = "flask";
+    Integration["fastapi"] = "fastapi";
+    Integration["swift"] = "swift";
+    Integration["reactNative"] = "react-native";
+    Integration["android"] = "android";
+    Integration["flutter"] = "flutter";
+    Integration["go"] = "go";
+    Integration["java"] = "java";
+    Integration["unreal"] = "unreal";
+    Integration["unity"] = "unity";
+    // Language fallbacks
+    Integration["javascript_web"] = "javascript_web";
+    Integration["python"] = "python";
+    Integration["javascriptNode"] = "javascript_node";
+    // Unknown / fallback (framework not detected)
+    Integration["generic"] = "generic";
+})(Integration || (exports.Integration = Integration = {}));
+// ── Environment ──────────────────────────────────────────────────────
+exports.IS_DEV = ['test', 'development'].includes(process.env.NODE_ENV ?? '');
+exports.DEBUG = false;
+// ── URLs ─────────────────────────────────────────────────────────────
+exports.DEFAULT_URL = exports.IS_DEV
+    ? 'http://localhost:8010'
+    : 'https://amplitude.com';
+exports.DEFAULT_HOST_URL = exports.IS_DEV
+    ? 'http://localhost:8010'
+    : 'https://api2.amplitude.com';
+// ── Analytics (internal) ──────────────────────────────────────────────
+// TODO: Replace with Amplitude analytics keys
+exports.ANALYTICS_AMPLITUDE_PUBLIC_PROJECT_WRITE_KEY = '';
+exports.ANALYTICS_HOST_URL = '';
+exports.ANALYTICS_TEAM_TAG = 'amplitude-wizard';
+// ── OAuth / Auth ────────────────────────────────────────────────────
+/** Matches the port used by the ampli CLI so sessions are interoperable. */
+exports.OAUTH_PORT = 13222;
+exports.AMPLITUDE_ZONE_SETTINGS = {
+    us: {
+        oAuthHost: process.env.OAUTH_HOST ?? 'https://auth.amplitude.com',
+        oAuthClientId: process.env.OAUTH_CLIENT_ID ?? '0ac84169-c41c-4222-885b-31469c761cb0',
+        dataApiUrl: 'https://data-api.amplitude.com/graphql',
+        /** Thunder GraphQL endpoint — org-scoped. Append the numeric orgId. */
+        appApiUrlBase: 'https://amplitude.com/graphql/org/',
+        webUrl: 'https://data.amplitude.com',
+    },
+    eu: {
+        oAuthHost: 'https://auth.eu.amplitude.com',
+        oAuthClientId: process.env.OAUTH_CLIENT_ID ?? '110d04a1-8e60-4157-9c43-fcbe4e014a85',
+        dataApiUrl: 'https://data-api.eu.amplitude.com/graphql',
+        /** Thunder GraphQL endpoint — org-scoped. Append the numeric orgId. */
+        appApiUrlBase: 'https://amplitude.eu/graphql/org/',
+        webUrl: 'https://data.eu.amplitude.com',
+    },
+};
+exports.DEFAULT_AMPLITUDE_ZONE = 'us';
+/**
+ * Every URL the wizard opens in the browser or presents as a link to the user.
+ * Keep this inventory accurate — the Amplitude UI uses it to allowlist outbound
+ * navigation from the wizard.
+ *
+ * Zone-dependent entries are keyed by AmplitudeZone.
+ * Builder functions compose the full URL from the base + runtime data (orgId, orgName).
+ */
+exports.OUTBOUND_URLS = {
+    // ── Amplitude app base URLs ──────────────────────────────────────────────
+    // Deep-links into the chart/dashboard editor use app.eu.amplitude.com for EU.
+    // Overview and Slack settings use eu.amplitude.com (no "app." prefix) for EU.
+    /** App base — used for chart/dashboard/checklist deep-links. */
+    app: {
+        us: 'https://app.amplitude.com',
+        eu: 'https://app.eu.amplitude.com',
+    },
+    /** Overview base — used for Outro, Slack settings, and sign-up continuation. */
+    overview: {
+        us: 'https://app.amplitude.com',
+        eu: 'https://eu.amplitude.com',
+    },
+    // ── Auth ─────────────────────────────────────────────────────────────────
+    /** OAuth authorization page — opened automatically to start sign-in. */
+    oAuth: (zone) => `${exports.AMPLITUDE_ZONE_SETTINGS[zone].oAuthHost}/oauth2/auth`,
+    // ── Checklist deep-links ─────────────────────────────────────────────────
+    /** New segmentation chart — opened from the Checklist screen. */
+    newChart: (zone, orgId) => {
+        const base = exports.OUTBOUND_URLS.app[zone];
+        return orgId ? `${base}/${orgId}/chart/new` : `${base}/chart/new`;
+    },
+    /** New dashboard — opened from the Checklist screen. */
+    newDashboard: (zone, orgId) => {
+        const base = exports.OUTBOUND_URLS.app[zone];
+        return orgId ? `${base}/${orgId}/dashboard/new` : `${base}/dashboard/new`;
+    },
+    // ── Post-setup ────────────────────────────────────────────────────────────
+    /** Slack integration settings — opened from the Slack screen. */
+    slackSettings: (zone, orgName) => {
+        const base = exports.OUTBOUND_URLS.overview[zone];
+        return orgName
+            ? `${base}/analytics/${encodeURIComponent(orgName)}/settings/profile`
+            : `${base}/settings/profile`;
+    },
+    /** Products page — shown in the Outro for sign-up users. */
+    products: (zone) => `${exports.OUTBOUND_URLS.overview[zone]}/products?source=wizard`,
+    // ── Docs ─────────────────────────────────────────────────────────────────
+    /** SDK overview — opened from the Activation Options screen. */
+    sdkDocs: 'https://amplitude.com/docs/sdks',
+    /** Per-framework SDK docs — referenced in agent prompts and post-run links. */
+    frameworkDocs: {
+        browser: 'https://amplitude.com/docs/sdks/analytics/browser/browser-sdk-2',
+        python: 'https://amplitude.com/docs/sdks/analytics/python',
+        java: 'https://amplitude.com/docs/sdks/analytics/java/jre-java-sdk',
+        go: 'https://amplitude.com/docs/sdks/analytics/go/go-sdk',
+        android: 'https://amplitude.com/docs/sdks/analytics/android/android-kotlin-sdk',
+        reactNative: 'https://amplitude.com/docs/sdks/analytics/react-native/react-native-sdk',
+        ios: 'https://amplitude.com/docs/sdks/analytics/ios/unified-sdk',
+        flutter: 'https://amplitude.com/docs/sdks/analytics/flutter/flutter-sdk-4',
+        unity: 'https://amplitude.com/docs/sdks/analytics/unity/unity-sdk',
+        unreal: 'https://amplitude.com/docs/sdks/analytics/unreal/unreal-sdk',
+    },
+    // ── Tips ──────────────────────────────────────────────────────────────────
+    /** Stripe data-source deep-link — shown as a tip in the RunScreen. */
+    stripeDataSource: 'https://app.amplitude.com/project/data-warehouse/new-source?kind=Stripe',
+    // ── Status ────────────────────────────────────────────────────────────────
+    /** Service status pages — shown in the OutageOverlay. */
+    status: {
+        claude: 'https://status.claude.com',
+        amplitude: 'https://www.amplitudestatus.com',
+    },
+    // ── Support ───────────────────────────────────────────────────────────────
+    /** Bug reports and feedback. */
+    githubIssues: 'https://github.com/amplitude/wizard/issues',
+};
+/** @deprecated Use OUTBOUND_URLS.githubIssues */
+exports.ISSUES_URL = exports.OUTBOUND_URLS.githubIssues;
+/** Placeholder embedded in generated code when the user skips key entry. */
+exports.DUMMY_PROJECT_API_KEY = '_YOUR_AMPLITUDE_API_KEY_';
+// ── Wizard run / variants ───────────────────────────────────────────
+exports.WIZARD_REMARK_EVENT_NAME = 'wizard remark';
+/** Feature flag key whose value selects a variant from WIZARD_VARIANTS. */
+exports.WIZARD_VARIANT_FLAG_KEY = 'wizard-variant';
+/** Variant key -> metadata for wizard run (VARIANT flag selects which entry to use). */
+exports.WIZARD_VARIANTS = {
+    base: { VARIANT: 'base' },
+    subagents: { VARIANT: 'subagents' },
+};
+/** User-Agent for wizard HTTP requests and MCP server identification. */
+exports.WIZARD_USER_AGENT = `amplitude/wizard; version: ${package_json_1.version}`;
+// ── HTTP headers ─────────────────────────────────────────────────────
+/** Header prefix for Amplitude properties. */
+exports.AMPLITUDE_PROPERTY_HEADER_PREFIX = 'X-AMPLITUDE-PROPERTY-';
+/** Header prefix for Amplitude feature flags. */
+exports.AMPLITUDE_FLAG_HEADER_PREFIX = 'X-AMPLITUDE-FLAG-';
+// ── Timeouts ─────────────────────────────────────────────────────────
+/** Timeout for framework / project detection probes (ms). */
+exports.DETECTION_TIMEOUT_MS = 10_000;

package/dist/src/lib/detect-amplitude.d.ts

@@ -0,0 +1,31 @@
+/**
+ * detect-amplitude — Static heuristics to check if Amplitude is already
+ * installed in the project directory, without calling any APIs or AI.
+ *
+ * Checks (in order of confidence):
+ *   1. package.json — Amplitude npm packages in dependencies
+ *   2. Python requirements files — amplitude-analytics
+ *   3. Swift — Podfile or Package.resolved
+ *   4. Android / Java — build.gradle / build.gradle.kts
+ *   5. Flutter — pubspec.yaml
+ *   6. Go — go.mod
+ *   7. Unreal Engine — Config/DefaultEngine.ini or Plugins/AmplitudeUnreal/
+ *   8. Unity — Packages/manifest.json
+ *   9. Source code imports — grep for amplitude import statements
+ *
+ * Returns a confidence level so callers can decide how to act:
+ *   'high'   — package file explicitly lists an Amplitude SDK
+ *   'low'    — import found in source but no package file entry
+ *   'none'   — no evidence found
+ */
+export type AmplitudeDetectionConfidence = 'high' | 'low' | 'none';
+export interface AmplitudeDetectionResult {
+    confidence: AmplitudeDetectionConfidence;
+    /** Human-readable reason for the confidence level */
+    reason: string | null;
+}
+/**
+ * Run all static checks in priority order.
+ * Returns the first non-'none' result, or 'none' if nothing found.
+ */
+export declare function detectAmplitudeInProject(installDir: string): AmplitudeDetectionResult;