@funnelsgrove/cli 0.1.20 → 0.1.24

package/README.md

@@ -41,6 +41,22 @@ for the same local diff.
 
 Use `fgrove env pull` from a synced folder to refresh only the ignored local `.env` file after project settings change, without replacing source files.
 
+Create an experiment draft from a strict JSON spec:
+
+```bash
+fgrove experiments create --spec experiment.json --dir .
+fgrove experiments create --spec experiment.json --dir . --json
+fgrove validate
+```
+
+The spec uses a stable `id` and `type: "step"`, `"paywall"`, or `"pricing"` with two to five variants, exactly one control, unique metrics and variant keys, and integer traffic totaling 100. Pricing variants also require `offerSetKey` and must route to the top-level `stepId`. See `docs/funnelsgrove/recipes/add-experiment.md` in a synced funnel for complete valid JSON examples and remediation guidance.
+
+Creation is draft-only: it creates no PostHog flag and activates no traffic. The experiment becomes visible in the UI after the API commits its hosted generated snapshot, and the CLI installs those exact generated bytes locally through recoverable staging. `.funnelsgrove-sync.json` stays local and ignored.
+
+With `--json`, success output contains only `experimentId`, `experimentKey`, `draftVersionId`, and `writtenPaths`, with generated paths in canonical order.
+
+For a non-GitHub funnel, deliver the local source with `fgrove sync up`. For a GitHub-connected funnel, commit and push the generated source with the rest of the change, then run `fgrove github pull`; do not commit `.funnelsgrove-sync.json` or use `fgrove sync up` for that diff.
+
 GitHub sync workflow:
 
 ```bash

package/dist/analyticsOutput.d.ts

@@ -108,8 +108,9 @@ export type MarketingCohortPerformanceRow = {
     revenueDay3: number;
     revenueDay90: number;
     revenueDay180: number;
+    pLtvCurrency: string | null;
     pLtv: number | null;
-    pLtvPredictedNetRevenueDay365Minor: number;
+    pLtvPredictedNetRevenueDay365Minor: number | null;
     pLtvPredictedCustomerCount: number;
     campaign: string;
     channel: string;

package/dist/analyticsOutput.js

@@ -78,8 +78,8 @@ const formatPercent = (value) => (typeof value === 'number' && Number.isFinite(v
 const formatPercentPoints = (value) => (typeof value === 'number' && Number.isFinite(value)
     ? `${value.toFixed(2)}%`
     : '');
-const formatCurrency = (value) => new Intl.NumberFormat('en-US', {
-    currency: 'USD',
+const formatCurrency = (value, currency = 'USD') => new Intl.NumberFormat('en-US', {
+    currency,
     maximumFractionDigits: 2,
     style: 'currency',
 }).format(value);
@@ -225,11 +225,25 @@ export const formatConversionsTable = (input) => {
     return `${lines.join('\n')}\n`;
 };
 const flattenCohortRows = (rows) => rows.flatMap((row) => [row, ...(row.segments || []), ...(row.children || [])]);
+const normalizeCurrency = (value) => {
+    const currency = value?.trim().toUpperCase() || '';
+    return /^[A-Z]{3}$/.test(currency) ? currency : null;
+};
 const predictedAverageLtv = (row) => {
+    if (!normalizeCurrency(row.pLtvCurrency)) {
+        return null;
+    }
     if (row.pLtvPredictedCustomerCount > 0) {
-        return row.pLtvPredictedNetRevenueDay365Minor / row.pLtvPredictedCustomerCount / 100;
+        return typeof row.pLtvPredictedNetRevenueDay365Minor === 'number'
+            && Number.isFinite(row.pLtvPredictedNetRevenueDay365Minor)
+            ? row.pLtvPredictedNetRevenueDay365Minor
+                / row.pLtvPredictedCustomerCount
+                / 100
+            : null;
     }
-    return Number(row.pLtv) || 0;
+    return typeof row.pLtv === 'number' && Number.isFinite(row.pLtv)
+        ? row.pLtv
+        : null;
 };
 const ratioToSpend = (value, spend) => (Number.isFinite(value) && Number.isFinite(spend) && spend !== 0 ? value / spend : null);
 const formatRoi = (profit, spend) => {
@@ -243,12 +257,18 @@ const formatRoas = (revenue, spend) => {
 export const formatCohortTable = (input) => {
     const lines = [
         `Cohort\t${input.date}`,
-        'cohort\tmediaSource\tfunnelUrl\tspend\tsubscribers\taliveRate\trevenue\tpLtv\tcpa\tpredictedProfit\tpROI\tROAS\tROAS d3\tROAS d90\tROAS d180',
+        'cohort\tmediaSource\tfunnelUrl\tspend\tsubscribers\taliveRate\trevenue\tpLtv\tpLtvCurrency\tcpa\tpredictedProfit\tpROI\tROAS\tROAS d3\tROAS d90\tROAS d180',
     ];
     for (const row of flattenCohortRows(input.cohort.rows)) {
         const cpa = row.subscribers > 0 ? row.spend / row.subscribers : 0;
-        const predictedRevenue = predictedAverageLtv(row) * row.subscribers;
-        const predictedProfit = predictedRevenue - row.spend;
+        const averageLtv = predictedAverageLtv(row);
+        const predictedRevenue = averageLtv === null
+            ? null
+            : averageLtv * row.subscribers;
+        const predictedProfit = predictedRevenue === null
+            ? null
+            : predictedRevenue - row.spend;
+        const pLtvCurrency = normalizeCurrency(row.pLtvCurrency);
         lines.push([
             row.cohortDate,
             row.mediaSource,
@@ -257,10 +277,15 @@ export const formatCohortTable = (input) => {
             formatNumber(row.subscribers),
             formatPercentPoints(row.subscribersAlivePercent),
             formatCurrency(row.revenue),
-            row.pLtv === null ? '' : formatCurrency(row.pLtv),
+            row.pLtv === null || pLtvCurrency === null
+                ? ''
+                : formatCurrency(row.pLtv, pLtvCurrency),
+            pLtvCurrency || '',
             row.subscribers > 0 ? formatCurrency(cpa) : '',
-            formatCurrency(predictedProfit),
-            formatRoi(predictedProfit, row.spend),
+            predictedProfit === null
+                ? ''
+                : formatCurrency(predictedProfit, pLtvCurrency || 'USD'),
+            predictedProfit === null ? '' : formatRoi(predictedProfit, row.spend),
             formatRoas(row.revenue, row.spend),
             formatRoas(row.revenueDay3, row.spend),
             formatRoas(row.revenueDay90, row.spend),

package/dist/apiClient.d.ts

@@ -1,5 +1,6 @@
 import { type FunnelContractDiagnosticCode } from '@funnelsgrove/runtime';
 import type { SourceCandidateOperation } from './localSync.js';
+import type { AgentExperimentSpec, ExperimentCreateResponse } from './experimentCreate.js';
 type FetchFn = typeof fetch;
 type TrpcProcedureType = 'query' | 'mutation';
 export type TrpcCallInput = {
@@ -17,6 +18,12 @@ export type FunnelSourceCandidateApiContext = {
     fetchFn?: FetchFn;
     signal?: AbortSignal;
 };
+export type CreateFunnelExperimentFromSpecInput = {
+    workspaceId: string;
+    funnelId: string;
+    expectedDraftVersionId: string;
+    spec: AgentExperimentSpec;
+};
 export type FunnelSourceCandidateStatus = 'staging' | 'validating' | 'committed' | 'aborted' | 'expired' | 'failed';
 export type BeginFunnelSourceCandidateInput = {
     workspaceId: string;
@@ -64,7 +71,7 @@ export type FinalizeFunnelSourceCandidateResult = {
     idempotent: boolean;
     diagnostics: readonly FunnelContractApiDiagnostic[];
 };
-export declare const FUNNEL_CONTRACT_API_INGRESSES: readonly ["agent-transaction", "cli-sync", "github-sync", "builder-authoring", "preview-publish", "production-publish", "published-artifact-serving"];
+export declare const FUNNEL_CONTRACT_API_INGRESSES: readonly ["cli-sync", "github-sync", "builder-authoring", "preview-publish", "production-publish", "published-artifact-serving"];
 export type FunnelContractApiIngress = (typeof FUNNEL_CONTRACT_API_INGRESSES)[number];
 export type FunnelContractApiDiagnostic = {
     code: FunnelContractDiagnosticCode;
@@ -95,4 +102,5 @@ export declare const beginFunnelSourceCandidate: (context: FunnelSourceCandidate
 export declare const stageFunnelSourceCandidate: (context: FunnelSourceCandidateApiContext, input: StageFunnelSourceCandidateInput) => Promise<StageFunnelSourceCandidateResult>;
 export declare const finalizeFunnelSourceCandidate: (context: FunnelSourceCandidateApiContext, input: FinalizeFunnelSourceCandidateInput) => Promise<FinalizeFunnelSourceCandidateResult>;
 export declare const abortFunnelSourceCandidate: (context: FunnelSourceCandidateApiContext, input: FinishFunnelSourceCandidateInput) => Promise<FunnelSourceCandidateSummary>;
+export declare const createFunnelExperimentFromSpec: (context: FunnelSourceCandidateApiContext, input: CreateFunnelExperimentFromSpecInput) => Promise<ExperimentCreateResponse>;
 export {};

package/dist/apiClient.js

@@ -1,6 +1,5 @@
 import { CURRENT_STEP_CONTRACT_VERSION, FUNNEL_CONTRACT_DIAGNOSTIC_CODES, } from '@funnelsgrove/runtime';
 export const FUNNEL_CONTRACT_API_INGRESSES = Object.freeze([
-    'agent-transaction',
     'cli-sync',
     'github-sync',
     'builder-authoring',
@@ -276,3 +275,9 @@ export const beginFunnelSourceCandidate = (context, input) => callFunnelSourceCa
 export const stageFunnelSourceCandidate = (context, input) => callFunnelSourceCandidateMutation(context, 'funnels.stageSourceCandidate', input);
 export const finalizeFunnelSourceCandidate = (context, input) => callFunnelSourceCandidateMutation(context, 'funnels.finalizeSourceCandidate', input);
 export const abortFunnelSourceCandidate = (context, input) => callFunnelSourceCandidateMutation(context, 'funnels.abortSourceCandidate', input);
+export const createFunnelExperimentFromSpec = (context, input) => callTrpcProcedure({
+    ...context,
+    path: 'funnelExperiments.createFromSpec',
+    type: 'mutation',
+    input,
+});

package/dist/cli.d.ts

@@ -144,6 +144,7 @@ type SyncTargetIdInput = {
 };
 type GeneratedConfigKind = 'offerSets' | 'experiments';
 export declare const SYNC_DOWN_GENERATED_CONFIG_KINDS: GeneratedConfigKind[];
+export declare const EXPERIMENT_TRANSACTION_RECOVERY_COMMANDS: readonly ["sync down", "sync up", "experiments sync", "offer-sets sync"];
 export declare function resolveSyncTargetIds(input: SyncTargetIdInput): {
     workspaceId: string;
     funnelId?: string;

package/dist/cli.js

@@ -8,9 +8,10 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { Command } from 'commander';
 import { CURRENT_STEP_CONTRACT_VERSION, FUNNEL_CONTRACT_DIAGNOSTIC_CODES, PREVIOUS_STEP_CONTRACT_VERSION, createFunnelContractDiagnostic, } from '@funnelsgrove/runtime';
-import { abortFunnelSourceCandidate, beginFunnelSourceCandidate, callTrpcProcedure, finalizeFunnelSourceCandidate, stageFunnelSourceCandidate, } from './apiClient.js';
+import { abortFunnelSourceCandidate, beginFunnelSourceCandidate, callTrpcProcedure, createFunnelExperimentFromSpec, finalizeFunnelSourceCandidate, stageFunnelSourceCandidate, } from './apiClient.js';
 import { clearActiveContext, getDefaultAuthConfigPath, loadActiveContext, loadAuthToken, saveActiveContext, saveAuthToken, } from './authStore.js';
 import { buildSyncManifest, buildCommittedSyncManifest, buildSourceCandidateOperations, collectChangedSourceFiles, collectSourceSnapshot, ensureGitignore, formatSyncUploadSummary, hasLocalSourceChanges, readSyncManifest, runSyncDownLocalLifecycle, runSourceCandidateSync, writeLocalEnvFile, writeSourceFiles, writeSyncManifest, } from './localSync.js';
+import { executeExperimentCreate, formatExperimentCreateSuccess, recoverExperimentCreateTransaction, } from './experimentCreate.js';
 import { pullEnvFile } from './envSync.js';
 import { formatGitHubConnectRows, formatGitHubJobRows, formatGitHubStatusRows, } from './githubOutput.js';
 import { syncGitHubDraftIfConnected } from './githubSyncFlow.js';
@@ -1059,6 +1060,13 @@ const GENERATED_CONFIG_PATH_BY_KIND = {
     experiments: 'src/config/experiments.generated.ts',
 };
 export const SYNC_DOWN_GENERATED_CONFIG_KINDS = ['offerSets', 'experiments'];
+export const EXPERIMENT_TRANSACTION_RECOVERY_COMMANDS = [
+    'sync down',
+    'sync up',
+    'experiments sync',
+    'offer-sets sync',
+];
+const experimentTransactionRecoveryCommands = new Set(EXPERIMENT_TRANSACTION_RECOVERY_COMMANDS);
 export function resolveSyncTargetIds(input) {
     const workspaceId = input.explicitWorkspaceId ||
         input.manifest?.workspaceId ||
@@ -1432,6 +1440,13 @@ const syncGeneratedConfigFilesForCli = async (input) => {
 };
 const addExamples = (command, examples) => command.addHelpText('after', `\nExamples:\n${examples.map((example) => `  $ ${example}`).join('\n')}`);
 export const program = new Command();
+program.hook('preAction', async (_command, actionCommand) => {
+    const commandPath = `${actionCommand.parent?.name() || ''} ${actionCommand.name()}`.trim();
+    if (!experimentTransactionRecoveryCommands.has(commandPath))
+        return;
+    const options = actionCommand.opts();
+    await recoverExperimentCreateTransaction(path.resolve(process.cwd(), options.dir || '.'));
+});
 program
     .name('fgrove')
     .description('FunnelsGrove CLI for editing, syncing, and publishing funnels')
@@ -1654,9 +1669,30 @@ addExamples(offerSetsCommand
     console.log(`Wrote ${formatGeneratedFileCount(generatedFiles.length)}`);
 });
 const experimentsCommand = addExamples(program.command('experiments').description('Manage funnel experiments'), [
+    'fgrove experiments create --spec experiment.json --dir .',
     'fgrove experiments sync',
     'fgrove experiments sync --funnel claimbee-ios',
 ]);
+addExamples(experimentsCommand
+    .command('create')
+    .description('Create a draft experiment from a JSON spec')
+    .requiredOption('--spec <path>', 'Experiment JSON spec')
+    .option('--dir <path>', 'Synced local funnel directory', '.')
+    .option('--json', 'Emit one machine-readable success object'), [
+    'fgrove experiments create --spec experiment.json --dir .',
+    'fgrove experiments create --spec experiment.json --dir ./claimbee-ios --json',
+])
+    .action(async (options) => {
+    const result = await executeExperimentCreate({
+        sourceDir: path.resolve(process.cwd(), options.dir),
+        specPath: path.resolve(process.cwd(), options.spec),
+        createFromSpec: async (input) => createFunnelExperimentFromSpec({
+            apiUrl: getApiUrl(),
+            token: await readAuthToken(),
+        }, input),
+    });
+    process.stdout.write(formatExperimentCreateSuccess(result, options.json === true));
+});
 addExamples(experimentsCommand
     .command('sync')
     .description('Write generated experiment config for a funnel')

package/dist/experimentCreate.d.ts

@@ -0,0 +1,100 @@
+import { readSyncManifest, type SyncManifest } from './localSync.js';
+export declare const EXPERIMENT_GENERATED_PATHS: readonly ["src/config/experiments.generated.ts", "src/config/experiments.ts"];
+declare const EXPERIMENT_GENERATED_CONTENT_TYPE = "text/typescript";
+declare const EXPERIMENT_METRICS: readonly ["step_completion", "next_step_reached", "checkout_opened", "funnel_completed", "paying_customer"];
+export type ExperimentMetric = (typeof EXPERIMENT_METRICS)[number];
+export type AgentExperimentVariant = {
+    variantKey: string;
+    label: string;
+    routeToStepId: string;
+    trafficPercent: number;
+    isControl: boolean;
+};
+export type AgentPricingExperimentVariant = AgentExperimentVariant & {
+    offerSetKey: string;
+};
+type SharedAgentExperimentSpec = {
+    id: string;
+    name: string;
+    stepId: string;
+    primaryMetric: ExperimentMetric;
+    trackedMetrics: ExperimentMetric[];
+};
+export type AgentExperimentSpec = SharedAgentExperimentSpec & ({
+    type: 'step' | 'paywall';
+    variants: AgentExperimentVariant[];
+} | {
+    type: 'pricing';
+    variants: AgentPricingExperimentVariant[];
+});
+export type GeneratedExperimentFile = {
+    path: (typeof EXPERIMENT_GENERATED_PATHS)[number];
+    content: string;
+    contentType: typeof EXPERIMENT_GENERATED_CONTENT_TYPE;
+};
+export type ExperimentCreateResponse = {
+    experiment: Record<string, unknown> & {
+        id: string;
+        posthog_flag_key: string;
+    };
+    variants: Array<Record<string, unknown> & {
+        id: string;
+        experiment_id: string;
+        variant_key: string;
+        label: string;
+        route_to_step_id: string;
+        traffic_percent: number;
+        is_control: boolean;
+    }>;
+    draftVersionId: string;
+    generatedFiles: [GeneratedExperimentFile, GeneratedExperimentFile];
+    githubConnected: boolean;
+};
+export declare class ExperimentCreateContractError extends Error {
+    constructor(fieldPath: string, reason: string);
+}
+export declare function parseAgentExperimentSpec(value: unknown): AgentExperimentSpec;
+export declare function readAgentExperimentSpec(filePath: string): Promise<AgentExperimentSpec>;
+export declare function parseExperimentCreateResponse(value: unknown, requestedSpec: AgentExperimentSpec, expectedFunnelIdValue: string): ExperimentCreateResponse;
+export declare function assertGeneratedExperimentFilesUnchanged(root: string, manifestValue: SyncManifest): Promise<void>;
+export declare function buildExperimentCreateManifest(manifestValue: SyncManifest, draftVersionIdValue: string, filesValue: unknown): SyncManifest;
+export type ExperimentCreateInstallPhase = 'prepared' | 'ready' | `generated:${GeneratedExperimentFile['path']}` | 'before-manifest' | 'manifest';
+type ExperimentCreateInstallHooks = {
+    afterPhase?: (phase: ExperimentCreateInstallPhase) => void | Promise<void>;
+};
+export declare function recoverExperimentCreateTransaction(root: string): Promise<boolean>;
+export declare function installExperimentCreateTransaction(root: string, input: {
+    generatedFiles: unknown;
+    manifest: SyncManifest;
+}, hooks?: ExperimentCreateInstallHooks): Promise<void>;
+export type ExecuteExperimentCreateInput = {
+    sourceDir: string;
+    specPath: string;
+    createFromSpec: (input: {
+        workspaceId: string;
+        funnelId: string;
+        expectedDraftVersionId: string;
+        spec: AgentExperimentSpec;
+    }) => Promise<unknown>;
+};
+export type ExperimentCreateSuccess = {
+    experimentId: string;
+    experimentKey: string;
+    draftVersionId: string;
+    writtenPaths: [...typeof EXPERIMENT_GENERATED_PATHS];
+    githubConnected: boolean;
+};
+type ExecuteExperimentCreateDependencies = {
+    recover: typeof recoverExperimentCreateTransaction;
+    readManifest: typeof readSyncManifest;
+    readSpec: typeof readAgentExperimentSpec;
+    assertGeneratedFilesUnchanged: typeof assertGeneratedExperimentFilesUnchanged;
+    parseResponse: typeof parseExperimentCreateResponse;
+    install: (sourceDir: string, input: {
+        generatedFiles: unknown;
+        manifest: SyncManifest;
+    }) => Promise<void>;
+};
+export declare function executeExperimentCreate(input: ExecuteExperimentCreateInput, dependencyOverrides?: Partial<ExecuteExperimentCreateDependencies>): Promise<ExperimentCreateSuccess>;
+export declare function formatExperimentCreateSuccess(result: ExperimentCreateSuccess, json: boolean): string;
+export {};