@amplitude/wizard 1.0.0-beta.0

package/dist/src/lib/ampli-config.js

@@ -0,0 +1,178 @@
+"use strict";
+/**
+ * Types and logic for the project-level ~/.ampli.json configuration file.
+ *
+ * The ampli CLI reads and writes this file (named "ampli.json") in the project
+ * directory to track which Amplitude workspace, source, and branch a project is
+ * connected to. The wizard creates or updates this file during setup.
+ *
+ * Types are modelled after the ampli CLI's Settings class
+ * (ampli/src/settings/index.ts) and are intentionally kept compatible.
+ *
+ * UNIT-TESTABLE SURFACE (pure, no I/O):
+ *   parseAmpliConfig, validateAmpliConfig, mergeAmpliConfig,
+ *   isConfigured, isMinimllyConfigured
+ *
+ * I/O SURFACE (not unit-testable in isolation):
+ *   readAmpliConfig, writeAmpliConfig, ampliConfigExists
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AMPLI_CONFIG_FILENAME = void 0;
+exports.parseAmpliConfig = parseAmpliConfig;
+exports.isMinimallyConfigured = isMinimallyConfigured;
+exports.isConfigured = isConfigured;
+exports.mergeAmpliConfig = mergeAmpliConfig;
+exports.hasMergeConflicts = hasMergeConflicts;
+exports.ampliConfigPath = ampliConfigPath;
+exports.ampliConfigExists = ampliConfigExists;
+exports.readAmpliConfig = readAmpliConfig;
+exports.writeAmpliConfig = writeAmpliConfig;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const zod_1 = require("zod");
+exports.AMPLI_CONFIG_FILENAME = 'ampli.json';
+// ── Pure logic (unit-testable) ────────────────────────────────────────────────
+const AmpliConfigSchema = zod_1.z
+    .object({
+    OrgId: zod_1.z.string().optional(),
+    WorkspaceId: zod_1.z.string().optional(),
+    SourceId: zod_1.z.string().optional(),
+    Branch: zod_1.z.string().optional(),
+    Path: zod_1.z.string().optional(),
+    Version: zod_1.z.string().optional(),
+    VersionId: zod_1.z.string().optional(),
+    Zone: zod_1.z.string().optional(),
+    Runtime: zod_1.z.string().optional(),
+    Platform: zod_1.z.string().optional(),
+    Language: zod_1.z.string().optional(),
+    SDK: zod_1.z.string().optional(),
+    OmitApiKeys: zod_1.z.boolean().optional(),
+    SourceDirs: zod_1.z.array(zod_1.z.string()).optional(),
+    InstanceNames: zod_1.z.array(zod_1.z.string()).optional(),
+})
+    .passthrough();
+/**
+ * Parse a raw JSON string into an AmpliConfig.
+ * Returns a typed result rather than throwing.
+ */
+function parseAmpliConfig(raw) {
+    if (hasMergeConflicts(raw)) {
+        return { ok: false, error: 'merge_conflicts' };
+    }
+    try {
+        const result = AmpliConfigSchema.safeParse(JSON.parse(raw));
+        if (!result.success) {
+            return { ok: false, error: 'invalid_json' };
+        }
+        return { ok: true, config: result.data };
+    }
+    catch {
+        return { ok: false, error: 'invalid_json' };
+    }
+}
+/**
+ * Returns true when the config contains the fields required to query Amplitude
+ * for event data (i.e. the project has been linked to an Amplitude source).
+ */
+function isMinimallyConfigured(config) {
+    return Boolean(config.SourceId);
+}
+/**
+ * Returns true when the config is considered fully configured: it has an org,
+ * a workspace, and a source linked.
+ */
+function isConfigured(config) {
+    return Boolean(config.OrgId && config.WorkspaceId && config.SourceId);
+}
+/**
+ * Shallow-merge an update into an existing config. Undefined update values are
+ * ignored so callers can safely spread partial objects.
+ */
+function mergeAmpliConfig(existing, updates) {
+    const result = { ...existing };
+    for (const [key, value] of Object.entries(updates)) {
+        if (value !== undefined) {
+            // @ts-expect-error – dynamic key assignment
+            result[key] = value;
+        }
+    }
+    return result;
+}
+/**
+ * Detect git merge conflict markers in a file's content.
+ * Mirrors the check in the ampli CLI (ampli/src/util/git/mergeConflicts.ts).
+ */
+function hasMergeConflicts(text) {
+    return (text.includes('<<<<<<<') &&
+        text.includes('=======') &&
+        text.includes('>>>>>>>'));
+}
+// ── I/O (not unit-testable in isolation) ────────────────────────────────────
+/**
+ * Returns the full path to ampli.json in the given directory.
+ */
+function ampliConfigPath(dir) {
+    return path.join(dir, exports.AMPLI_CONFIG_FILENAME);
+}
+/**
+ * Returns true if ampli.json exists in the given directory.
+ */
+function ampliConfigExists(dir) {
+    return fs.existsSync(ampliConfigPath(dir));
+}
+/**
+ * Read and parse ampli.json from the given directory.
+ * Returns a typed result; never throws.
+ */
+function readAmpliConfig(dir) {
+    const filePath = ampliConfigPath(dir);
+    let raw;
+    try {
+        raw = fs.readFileSync(filePath, 'utf-8');
+    }
+    catch {
+        return { ok: false, error: 'not_found' };
+    }
+    return parseAmpliConfig(raw);
+}
+/**
+ * Write an AmpliConfig object to ampli.json in the given directory.
+ * Creates the directory if it does not exist.
+ */
+function writeAmpliConfig(dir, config) {
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(ampliConfigPath(dir), JSON.stringify(config, null, 2), 'utf-8');
+}

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

@@ -0,0 +1,107 @@
+import { z } from 'zod';
+import { type AmplitudeZone } from './constants.js';
+export type AmplitudeOrg = {
+    id: string;
+    name: string;
+    workspaces: Array<{
+        id: string;
+        name: string;
+        environments?: Array<{
+            name: string;
+            rank: number;
+            app: {
+                id: string;
+                apiKey?: string | null;
+            } | null;
+        }> | null;
+    }>;
+};
+export type AmplitudeUserInfo = {
+    id: string;
+    firstName: string;
+    lastName: string;
+    email: string;
+    orgs: AmplitudeOrg[];
+};
+/**
+ * Fetches the authenticated user's org/workspace info from Amplitude's Data API.
+ * Uses the OAuth id_token as the Authorization header (same as ampli CLI).
+ */
+export declare function fetchAmplitudeUser(idToken: string, zone: AmplitudeZone): Promise<AmplitudeUserInfo>;
+export type AmplitudeBranch = {
+    id: string;
+    name: string;
+    default: boolean;
+    currentVersionId: string;
+};
+/** Fetches branches for a workspace. */
+export declare function fetchBranches(idToken: string, zone: AmplitudeZone, orgId: string, workspaceId: string): Promise<AmplitudeBranch[]>;
+/**
+ * Fetches the event type names cataloged in the default branch of a workspace.
+ * Returns an empty array if the workspace has no events or the query fails.
+ */
+export declare function fetchWorkspaceEventTypes(idToken: string, zone: AmplitudeZone, orgId: string, workspaceId: string): Promise<string[]>;
+/**
+ * Checks whether the authenticated user has any charts or dashboards in their org.
+ * Uses the Thunder org-scoped GraphQL endpoint.
+ *
+ * Detection is org-scoped — Thunder has no project-level chart/dashboard listing
+ * API. For a typical new-project user this is equivalent to project-scoped.
+ *
+ * Returns { hasCharts: false, hasDashboards: false } on any error so the
+ * checklist falls back to the default empty state rather than crashing.
+ */
+export declare function fetchOwnedDashboards(idToken: string, zone: AmplitudeZone, orgId: string): Promise<{
+    hasCharts: boolean;
+    hasDashboards: boolean;
+}>;
+export type AmplitudeSource = {
+    id: string;
+    name: string;
+    runtime: {
+        id: string;
+        platformId: string;
+        platformName: string;
+        languageId: string;
+        languageName: string;
+    } | null;
+    destinations: Array<{
+        name: string;
+        serviceId: string;
+    }>;
+};
+/** Fetches sources for a specific branch version. */
+export declare function fetchSources(idToken: string, zone: AmplitudeZone, orgId: string, workspaceId: string, branchId: string, versionId: string): Promise<AmplitudeSource[]>;
+export type ProjectActivationStatus = {
+    /** SDK/snippet has been installed (default event tracking source detected) */
+    hasDetSource: boolean;
+    hasPageViewedEvent: boolean;
+    hasSessionStartEvent: boolean;
+    hasSessionEndEvent: boolean;
+    /** True if at least one event type has been ingested */
+    hasAnyEvents: boolean;
+};
+/**
+ * Checks whether an Amplitude project has ingested any events and whether
+ * the SDK snippet is configured.
+ *
+ * The query lives in Thunder (the main Amplitude app GraphQL server), served
+ * at /graphql/org/:orgId.  orgId is required to construct the endpoint URL.
+ */
+export declare function fetchProjectActivationStatus(idToken: string, zone: AmplitudeZone, appId: number | string, orgId?: string | null): Promise<ProjectActivationStatus>;
+export declare const ApiUserSchema: z.ZodObject<{
+    distinct_id: z.ZodString;
+}, z.core.$strip>;
+export declare const ApiProjectSchema: z.ZodObject<{
+    id: z.ZodNumber;
+    uuid: z.ZodString;
+    organization: z.ZodString;
+    api_token: z.ZodString;
+    name: z.ZodString;
+}, z.core.$strip>;
+export type ApiUser = z.infer<typeof ApiUserSchema>;
+export type ApiProject = z.infer<typeof ApiProjectSchema>;
+/** @deprecated Amplitude stub. Use fetchAmplitudeUser instead. */
+export declare function fetchUserData(_accessToken: string, _baseUrl: string): Promise<ApiUser>;
+/** @deprecated Amplitude stub. Use fetchAmplitudeUser instead. */
+export declare function fetchProjectData(_accessToken: string, _projectId: number, _baseUrl: string): Promise<ApiProject>;