@funnelsgrove/cli 0.1.10 → 0.1.11

package/README.md

@@ -39,6 +39,23 @@ fgrove publish --funnel claimbee-general --env preview
 
 The GitHub commands use the FunnelsGrove API only. When GitHub is connected, `fgrove sync up` pushes the resulting draft to GitHub before returning, and `fgrove publish` waits for the current draft to reach GitHub before publishing. Local `.env*` files remain CLI-local runtime material from `sync down`; they are not sent to GitHub sync.
 
+Analytics workflow:
+
+```bash
+fgrove analytics conversions --project claimbee --funnel claimbee-ios --date 2026-06-11
+fgrove analytics funnel-path --project claimbee --funnel claimbee-ios --date 2026-06-11
+fgrove analytics transitions --project claimbee --funnel claimbee-ios --date 2026-06-11
+fgrove analytics cohort --project claimbee --date 2026-06-11
+```
+
+Each analytics command accepts `--format table|json`, `--out <path>`, `--workspace`, and `--timezone`. Use JSON for agents and automations:
+
+```bash
+fgrove analytics conversions --project claimbee --funnel claimbee-ios --date 2026-06-11 --format json --out conversions.json
+```
+
+`conversions` downloads the one-day conversion totals, primary conversion metrics, full funnel path rows, and step transitions. `funnel-path` focuses on the ordered path report. `transitions` focuses on step-by-step advanced/drop-off counts. `cohort` downloads synced marketing cohort economics for the day. If the requested day has no synced data, or cohort source data is incomplete, the CLI exits non-zero with a human-readable explanation.
+
 The package also keeps the longer `funnelsgrove` command as a compatibility alias.
 Use `--api-url` or `FUNNELSGROVE_API_URL` for non-production APIs.
 Use `--config` or `FUNNELSGROVE_CONFIG` to keep test credentials separate from the default `~/.funnelsgrove/config.json`.

package/dist/analyticsOutput.d.ts

@@ -0,0 +1,276 @@
+export type AnalyticsOutputFormat = 'table' | 'json';
+export type AnalyticsProjectSummary = {
+    id: string;
+    name?: string | null;
+    slug?: string | null;
+};
+export type AnalyticsFunnelSummary = {
+    id: string;
+    name?: string | null;
+    slug?: string | null;
+};
+export type AnalyticsOverviewResponse = {
+    generatedAt: string;
+    from: string | null;
+    to: string | null;
+    currency: string | null;
+    funnels: AnalyticsFunnelSummary[];
+    totals: Record<string, number>;
+    byDay: Array<{
+        date: string;
+        visitors: number;
+        subscriptions: number;
+        chargedRevenueMinor: number;
+    }>;
+};
+export type AnalyticsStepDropoffResponse = {
+    generatedAt: string;
+    from: string | null;
+    to: string | null;
+    funnel: {
+        id: string;
+        name: string;
+        slug: string;
+    };
+    version: {
+        selected: {
+            id: string;
+            seq: number;
+            message: string | null;
+            publishedAt: string | null;
+            isCurrent: boolean;
+        } | null;
+        options: Array<{
+            id: string;
+            seq: number;
+            message: string | null;
+            publishedAt: string | null;
+            isCurrent: boolean;
+        }>;
+    };
+    totals: Record<string, number>;
+    metrics: Array<{
+        id: string;
+        label: string;
+        numerator: number;
+        denominator: number;
+        rate: number;
+        numeratorLabel: string;
+        denominatorLabel: string;
+        description: string;
+        chartPoints: unknown[];
+    }>;
+    steps: AnalyticsStepTransition[];
+    flow: {
+        steps: Array<{
+            stepId: string;
+            stepName: string | null;
+            stepPath: string | null;
+            stepTitle: string | null;
+            stepType: string | null;
+            stepKind: string | null;
+            stepOrder: number;
+        }>;
+        experiments: unknown[];
+        branches: unknown[];
+    } | null;
+};
+export type AnalyticsStepTransition = {
+    stepId: string;
+    stepName: string | null;
+    stepOrder: number;
+    entrants: number;
+    completions: number;
+    advancedToNextStep: number;
+    dropoffs: number;
+    dropoffRate: number;
+    nextStepId: string | null;
+    nextStepName: string | null;
+};
+export type MarketingCohortPerformanceRow = {
+    id: string;
+    cohortDate: string;
+    funnelUrl: string;
+    mediaSource: string;
+    spend: number;
+    subscribers: number;
+    subscribersAlive: number;
+    subscribersAlivePercent: number | null;
+    revenue: number;
+    pLtv: number | null;
+    pLtvPredictedNetRevenueDay365Minor: number;
+    pLtvPredictedCustomerCount: number;
+    campaign: string;
+    channel: string;
+    country: string;
+    children?: MarketingCohortPerformanceRow[];
+    segments?: MarketingCohortPerformanceRow[];
+};
+export type MarketingCohortPerformanceReport = {
+    generatedAt: string;
+    from: string | null;
+    to: string | null;
+    rows: MarketingCohortPerformanceRow[];
+    sourceHealth?: {
+        complete: boolean;
+        warnings: string[];
+    };
+};
+export type ParsedAnalyticsDate = {
+    date: string;
+    fromIso: string;
+    toIso: string;
+};
+type ReportContext = {
+    date: string;
+    workspaceId: string;
+    project: AnalyticsProjectSummary;
+};
+export declare const parseAnalyticsDate: (value: string) => ParsedAnalyticsDate;
+export declare const normalizeAnalyticsOutputFormat: (value: string | undefined) => AnalyticsOutputFormat;
+export declare const assertHasConversionData: (date: string, overview: AnalyticsOverviewResponse, stepDropoff: AnalyticsStepDropoffResponse) => void;
+export declare const assertHasTransitionData: (date: string, stepDropoff: AnalyticsStepDropoffResponse) => void;
+export declare const assertHasFunnelPathData: (date: string, stepDropoff: AnalyticsStepDropoffResponse) => void;
+export declare const assertHasCohortData: (date: string, report: MarketingCohortPerformanceReport) => void;
+export declare const buildTransitionRows: (stepDropoff: AnalyticsStepDropoffResponse) => {
+    stepId: string;
+    step: string;
+    nextStep: string;
+    entrants: number;
+    advancedToNextStep: number;
+    dropoffs: number;
+    dropoffRate: number;
+}[];
+export declare const buildFunnelPathRows: (stepDropoff: AnalyticsStepDropoffResponse) => {
+    stepId: string;
+    path: string;
+    label: string;
+    users: number;
+    advancedToNextStep: number;
+    conversionToNextStep: number;
+    dropoffs: number;
+    dropoffRate: number;
+}[];
+export declare const buildConversionReportPayload: (input: ReportContext & {
+    overview: AnalyticsOverviewResponse;
+    stepDropoff: AnalyticsStepDropoffResponse;
+}) => {
+    generatedAt: string;
+    date: string;
+    workspaceId: string;
+    project: AnalyticsProjectSummary;
+    funnel: {
+        id: string;
+        name: string;
+        slug: string;
+    };
+    overview: AnalyticsOverviewResponse;
+    totals: Record<string, number>;
+    metrics: {
+        id: string;
+        label: string;
+        numerator: number;
+        denominator: number;
+        rate: number;
+        numeratorLabel: string;
+        denominatorLabel: string;
+        description: string;
+        chartPoints: unknown[];
+    }[];
+    funnelPath: {
+        stepId: string;
+        path: string;
+        label: string;
+        users: number;
+        advancedToNextStep: number;
+        conversionToNextStep: number;
+        dropoffs: number;
+        dropoffRate: number;
+    }[];
+    transitions: {
+        stepId: string;
+        step: string;
+        nextStep: string;
+        entrants: number;
+        advancedToNextStep: number;
+        dropoffs: number;
+        dropoffRate: number;
+    }[];
+};
+export declare const buildFunnelPathReportPayload: (input: ReportContext & {
+    stepDropoff: AnalyticsStepDropoffResponse;
+}) => {
+    generatedAt: string;
+    date: string;
+    workspaceId: string;
+    project: AnalyticsProjectSummary;
+    funnel: {
+        id: string;
+        name: string;
+        slug: string;
+    };
+    funnelPath: {
+        stepId: string;
+        path: string;
+        label: string;
+        users: number;
+        advancedToNextStep: number;
+        conversionToNextStep: number;
+        dropoffs: number;
+        dropoffRate: number;
+    }[];
+};
+export declare const buildTransitionReportPayload: (input: ReportContext & {
+    stepDropoff: AnalyticsStepDropoffResponse;
+}) => {
+    generatedAt: string;
+    date: string;
+    workspaceId: string;
+    project: AnalyticsProjectSummary;
+    funnel: {
+        id: string;
+        name: string;
+        slug: string;
+    };
+    transitions: {
+        stepId: string;
+        step: string;
+        nextStep: string;
+        entrants: number;
+        advancedToNextStep: number;
+        dropoffs: number;
+        dropoffRate: number;
+    }[];
+};
+export declare const buildCohortReportPayload: (input: ReportContext & {
+    cohort: MarketingCohortPerformanceReport;
+}) => {
+    generatedAt: string;
+    date: string;
+    workspaceId: string;
+    project: AnalyticsProjectSummary;
+    cohort: MarketingCohortPerformanceReport;
+    sourceHealth: {
+        complete: boolean;
+        warnings: string[];
+    } | null;
+};
+export declare const formatAnalyticsJson: (payload: unknown) => string;
+export declare const formatTransitionsTable: (input: {
+    date: string;
+    stepDropoff: AnalyticsStepDropoffResponse;
+}) => string;
+export declare const formatFunnelPathTable: (input: {
+    date: string;
+    stepDropoff: AnalyticsStepDropoffResponse;
+}) => string;
+export declare const formatConversionsTable: (input: {
+    date: string;
+    overview: AnalyticsOverviewResponse;
+    stepDropoff: AnalyticsStepDropoffResponse;
+}) => string;
+export declare const formatCohortTable: (input: {
+    date: string;
+    cohort: MarketingCohortPerformanceReport;
+}) => string;
+export {};

package/dist/analyticsOutput.js

@@ -0,0 +1,254 @@
+export const parseAnalyticsDate = (value) => {
+    const trimmed = value.trim();
+    const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(trimmed);
+    if (!match) {
+        throw new Error('Expected --date in YYYY-MM-DD format.');
+    }
+    const year = Number(match[1]);
+    const month = Number(match[2]);
+    const day = Number(match[3]);
+    const timestamp = Date.UTC(year, month - 1, day);
+    const parsed = new Date(timestamp);
+    const isRealDate = parsed.getUTCFullYear() === year &&
+        parsed.getUTCMonth() + 1 === month &&
+        parsed.getUTCDate() === day;
+    if (!isRealDate) {
+        throw new Error('Expected --date to be a real calendar date.');
+    }
+    return {
+        date: trimmed,
+        fromIso: `${trimmed}T00:00:00.000Z`,
+        toIso: `${trimmed}T23:59:59.999Z`,
+    };
+};
+export const normalizeAnalyticsOutputFormat = (value) => {
+    const normalized = (value || 'table').trim().toLowerCase();
+    if (normalized === 'table' || normalized === 'json') {
+        return normalized;
+    }
+    throw new Error('--format must be table or json.');
+};
+const hasPositiveNumber = (value) => {
+    if (typeof value === 'number') {
+        return Number.isFinite(value) && value > 0;
+    }
+    if (Array.isArray(value)) {
+        return value.some(hasPositiveNumber);
+    }
+    if (value && typeof value === 'object') {
+        return Object.values(value).some(hasPositiveNumber);
+    }
+    return false;
+};
+export const assertHasConversionData = (date, overview, stepDropoff) => {
+    if (hasPositiveNumber(overview.totals) ||
+        hasPositiveNumber(overview.byDay) ||
+        hasPositiveNumber(stepDropoff.totals) ||
+        hasPositiveNumber(stepDropoff.steps)) {
+        return;
+    }
+    throw new Error(`No synced conversion data found for ${date}. Analytics may not have synced yet, or the funnel had no tracked traffic that day.`);
+};
+export const assertHasTransitionData = (date, stepDropoff) => {
+    if (stepDropoff.steps.length > 0 && hasPositiveNumber(stepDropoff.steps)) {
+        return;
+    }
+    throw new Error(`No synced step transition data found for ${date}. Analytics may not have synced yet, or the funnel had no tracked step traffic that day.`);
+};
+export const assertHasFunnelPathData = (date, stepDropoff) => {
+    if (buildFunnelPathRows(stepDropoff).length > 0 && hasPositiveNumber(stepDropoff.steps)) {
+        return;
+    }
+    throw new Error(`No synced full funnel path data found for ${date}. Analytics may not have synced yet, or the funnel had no tracked path traffic that day.`);
+};
+export const assertHasCohortData = (date, report) => {
+    if (report.sourceHealth && !report.sourceHealth.complete) {
+        const warnings = report.sourceHealth.warnings.join(' ').trim();
+        throw new Error(`Cohort source data for ${date} is not fully synced. ${warnings || 'Required marketing sources have not finished syncing.'}`);
+    }
+    if (report.rows.length > 0) {
+        return;
+    }
+    throw new Error(`No synced cohort data found for ${date}. Marketing cohort data may not have synced yet, or there were no subscribers for that day.`);
+};
+const formatNumber = (value) => Math.round(value).toLocaleString('en-US');
+const formatPercent = (value) => (typeof value === 'number' && Number.isFinite(value)
+    ? `${(value * 100).toFixed(2)}%`
+    : '');
+const formatPercentPoints = (value) => (typeof value === 'number' && Number.isFinite(value)
+    ? `${value.toFixed(2)}%`
+    : '');
+const formatCurrency = (value) => new Intl.NumberFormat('en-US', {
+    currency: 'USD',
+    maximumFractionDigits: 2,
+    style: 'currency',
+}).format(value);
+const formatMinorCurrency = (value) => formatCurrency((Number(value) || 0) / 100);
+const stepDisplayName = (step) => step.stepName || step.stepId;
+const flowStepDisplay = (stepDropoff, step) => {
+    const flowStep = stepDropoff.flow?.steps.find((candidate) => candidate.stepId === step.stepId);
+    return {
+        label: flowStep?.stepTitle || step.stepName || flowStep?.stepName || step.stepId,
+        path: flowStep?.stepPath || step.stepId,
+    };
+};
+export const buildTransitionRows = (stepDropoff) => [...stepDropoff.steps]
+    .sort((left, right) => left.stepOrder - right.stepOrder || left.stepId.localeCompare(right.stepId))
+    .map((step) => ({
+    stepId: step.stepId,
+    step: stepDisplayName(step),
+    nextStep: step.nextStepId || '',
+    entrants: step.entrants,
+    advancedToNextStep: step.advancedToNextStep,
+    dropoffs: step.dropoffs,
+    dropoffRate: step.dropoffRate,
+}));
+export const buildFunnelPathRows = (stepDropoff) => buildTransitionRows(stepDropoff).map((row) => {
+    const step = stepDropoff.steps.find((candidate) => candidate.stepId === row.stepId);
+    const display = flowStepDisplay(stepDropoff, step);
+    return {
+        stepId: row.stepId,
+        path: display.path,
+        label: display.label,
+        users: row.entrants,
+        advancedToNextStep: row.advancedToNextStep,
+        conversionToNextStep: row.entrants > 0 ? row.advancedToNextStep / row.entrants : 0,
+        dropoffs: row.dropoffs,
+        dropoffRate: row.dropoffRate,
+    };
+});
+export const buildConversionReportPayload = (input) => ({
+    generatedAt: new Date().toISOString(),
+    date: input.date,
+    workspaceId: input.workspaceId,
+    project: input.project,
+    funnel: input.stepDropoff.funnel,
+    overview: input.overview,
+    totals: input.stepDropoff.totals,
+    metrics: input.stepDropoff.metrics,
+    funnelPath: buildFunnelPathRows(input.stepDropoff),
+    transitions: buildTransitionRows(input.stepDropoff),
+});
+export const buildFunnelPathReportPayload = (input) => ({
+    generatedAt: new Date().toISOString(),
+    date: input.date,
+    workspaceId: input.workspaceId,
+    project: input.project,
+    funnel: input.stepDropoff.funnel,
+    funnelPath: buildFunnelPathRows(input.stepDropoff),
+});
+export const buildTransitionReportPayload = (input) => ({
+    generatedAt: new Date().toISOString(),
+    date: input.date,
+    workspaceId: input.workspaceId,
+    project: input.project,
+    funnel: input.stepDropoff.funnel,
+    transitions: buildTransitionRows(input.stepDropoff),
+});
+export const buildCohortReportPayload = (input) => ({
+    generatedAt: new Date().toISOString(),
+    date: input.date,
+    workspaceId: input.workspaceId,
+    project: input.project,
+    cohort: input.cohort,
+    sourceHealth: input.cohort.sourceHealth || null,
+});
+export const formatAnalyticsJson = (payload) => `${JSON.stringify(payload, null, 2)}\n`;
+export const formatTransitionsTable = (input) => {
+    const lines = [
+        `Step transitions\t${input.date}\t${input.stepDropoff.funnel.name}`,
+        'step\tnextStep\tentrants\tadvanced\tdropoffs\tdropoffRate',
+    ];
+    for (const row of buildTransitionRows(input.stepDropoff)) {
+        lines.push([
+            row.step,
+            row.nextStep,
+            formatNumber(row.entrants),
+            formatNumber(row.advancedToNextStep),
+            formatNumber(row.dropoffs),
+            formatPercent(row.dropoffRate),
+        ].join('\t'));
+    }
+    return `${lines.join('\n')}\n`;
+};
+export const formatFunnelPathTable = (input) => {
+    const lines = [
+        `Full funnel path\t${input.date}\t${input.stepDropoff.funnel.name}`,
+        'step\tpath\tusers\tadvanced\tconversionToNext\tdropoffs\tdropoffRate',
+    ];
+    for (const row of buildFunnelPathRows(input.stepDropoff)) {
+        lines.push([
+            row.label,
+            row.path,
+            formatNumber(row.users),
+            formatNumber(row.advancedToNextStep),
+            formatPercent(row.conversionToNextStep),
+            formatNumber(row.dropoffs),
+            formatPercent(row.dropoffRate),
+        ].join('\t'));
+    }
+    return `${lines.join('\n')}\n`;
+};
+export const formatConversionsTable = (input) => {
+    const totals = input.stepDropoff.totals;
+    const overviewTotals = input.overview.totals;
+    const lines = [
+        `Conversions\t${input.date}\t${input.stepDropoff.funnel.name}`,
+        'metric\tvalue',
+        ['visitors', formatNumber(totals.visitors ?? overviewTotals.visitors ?? 0)].join('\t'),
+        ['quizEntries', formatNumber(totals.quizEntries ?? 0)].join('\t'),
+        ['quizStarts', formatNumber(totals.quizStarts ?? overviewTotals.quizStarts ?? 0)].join('\t'),
+        ['finishedQuiz', formatNumber(totals.finishedQuiz ?? overviewTotals.finishedQuiz ?? 0)].join('\t'),
+        ['emailAdds', formatNumber(totals.emailAdds ?? overviewTotals.emailAdds ?? 0)].join('\t'),
+        ['paywallViews', formatNumber(totals.paywallViews ?? 0)].join('\t'),
+        ['checkoutStarts', formatNumber(totals.checkoutStarts ?? overviewTotals.checkoutStarts ?? 0)].join('\t'),
+        ['subscriptions', formatNumber(totals.subscriptions ?? overviewTotals.subscriptionsStarted ?? 0)].join('\t'),
+        ['completedRegistrations', formatNumber(totals.completedRegistrations ?? overviewTotals.completedRegistrations ?? 0)].join('\t'),
+        ['netRevenue', formatMinorCurrency(overviewTotals.netRevenueMinor)].join('\t'),
+        '',
+        'conversionMetric\tnumerator\tdenominator\trate',
+    ];
+    for (const metric of input.stepDropoff.metrics) {
+        lines.push([
+            metric.label,
+            formatNumber(metric.numerator),
+            formatNumber(metric.denominator),
+            formatPercent(metric.rate),
+        ].join('\t'));
+    }
+    lines.push('', formatFunnelPathTable({
+        date: input.date,
+        stepDropoff: input.stepDropoff,
+    }).trimEnd());
+    return `${lines.join('\n')}\n`;
+};
+const flattenCohortRows = (rows) => rows.flatMap((row) => [row, ...(row.segments || []), ...(row.children || [])]);
+const predictedAverageLtv = (row) => {
+    if (row.pLtvPredictedCustomerCount > 0) {
+        return row.pLtvPredictedNetRevenueDay365Minor / row.pLtvPredictedCustomerCount / 100;
+    }
+    return Number(row.pLtv) || 0;
+};
+export const formatCohortTable = (input) => {
+    const lines = [
+        `Cohort\t${input.date}`,
+        'cohort\tmediaSource\tfunnelUrl\tspend\tsubscribers\taliveRate\trevenue\tpLtv\tcpa\tpredictedProfit',
+    ];
+    for (const row of flattenCohortRows(input.cohort.rows)) {
+        const cpa = row.subscribers > 0 ? row.spend / row.subscribers : 0;
+        const predictedRevenue = predictedAverageLtv(row) * row.subscribers;
+        lines.push([
+            row.cohortDate,
+            row.mediaSource,
+            row.funnelUrl,
+            formatCurrency(row.spend),
+            formatNumber(row.subscribers),
+            formatPercentPoints(row.subscribersAlivePercent),
+            formatCurrency(row.revenue),
+            row.pLtv === null ? '' : formatCurrency(row.pLtv),
+            row.subscribers > 0 ? formatCurrency(cpa) : '',
+            formatCurrency(predictedRevenue - row.spend),
+        ].join('\t'));
+    }
+    return `${lines.join('\n')}\n`;
+};

package/dist/cli.d.ts

@@ -1,6 +1,14 @@
 #!/usr/bin/env node
 import { type ActiveContext } from './authStore.js';
 import { type SyncManifest } from './localSync.js';
+import { type AnalyticsOutputFormat } from './analyticsOutput.js';
+type AnalyticsCommandInput = {
+    date: string;
+    from: string;
+    to: string;
+    format: AnalyticsOutputFormat;
+    timezone?: string;
+};
 type SyncTargetIdInput = {
     explicitWorkspaceId?: string;
     explicitFunnelId?: string;
@@ -13,4 +21,9 @@ export declare function resolveSyncTargetIds(input: SyncTargetIdInput): {
     funnelId?: string;
 };
 export declare function isCliEntrypoint(invokedPath: string | undefined, modulePath: string, realpath?: (filePath: string) => string): boolean;
+export declare function buildAnalyticsCommandInput(options: {
+    date: string;
+    format?: string;
+    timezone?: string;
+}): AnalyticsCommandInput;
 export {};