@funnelsgrove/cli 0.1.308 → 0.1.309

package/README.md

@@ -243,6 +243,28 @@ by Merchanto; the cost lines cover FunnelsGrove alerts for the whole project.
 The output never includes customer emails, names, phone numbers, IP addresses,
 card digits, network references or Stripe identifiers.
 
+Support a customer (workspace admins only): look them up by email or funnel
+user ID, refund chosen payments and cancel their subscription:
+
+```bash
+fgrove customers lookup --project claimbee --email buyer@example.com --json   # users, live subscriptions, payments with refund eligibility
+fgrove customers refund --project claimbee --email buyer@example.com --payment ch_123 --payment pay_456 --dry-run
+fgrove customers refund --project claimbee --email buyer@example.com --payment ch_123 --payment pay_456
+fgrove customers cancel --project claimbee --user-id 8f1c2d   # at period end; --now cancels immediately without refunding the remainder
+```
+
+Pass exactly one of `--email` or `--user-id`; `--env test` reads test-mode
+customers. Stripe charges and subscriptions come live from Stripe; Solidgate
+payments come from the FunnelsGrove ledger with refunded amounts read live from
+Solidgate. Refunds are full refunds of each payment's remaining amount, using
+the payment IDs printed by `lookup`. Each payment is refunded at most once,
+including against Chargeback Prevention refunds of the same payment. A
+Solidgate refund that is still processing is reported as `processing`; run
+`lookup` later to confirm it. The command exits 1 if any payment failed. `cancel` refuses to guess when several
+subscriptions are still billing; pass `--subscription`. When `lookup` reports a
+provider that did not answer, missing data does not mean there is no
+subscription.
+
 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/cli.js

@@ -20,6 +20,7 @@ import { executeFastDraftPatchSync, uploadDirectAssetWithFetch } from './draftPa
 import { updateCliInstallations } from './selfUpdate.js';
 import { executeExpensePublish, executeExpensePull } from './expenseCommands.js';
 import { buildAlertStatisticsReport, fetchAlertStatistics, fetchPreventSummary, formatAlertRows, formatAlertStatistics, formatPreventRows, formatPreventSummary, listAlerts, listPreventSearches, parseAlertMonth, toAlertJsonRow, } from './alertCommands.js';
+import { cancelCustomerSubscription, formatCustomerCancellation, formatCustomerLookup, formatCustomerRefunds, formatRefundPreview, lookupCustomer, parseCustomerSelector, previewRefund, refundCustomerPayments, } from './customerCommands.js';
 import { executeOfferSetPrices, executeOfferSetPublish, executeOfferSetPull, formatOfferSetPriceCatalogs, } from './offerSetCommands.js';
 import { executeEmailPull, executeEmailPush, executeEmailSend, executeEmailUpdateVariables, executeEmailSequenceAddStep, executeEmailSequenceCancel, executeEmailSequenceCreate, executeEmailSequencePublish, executeEmailSequenceSetActive, executeEmailLibraryAdd, executeEmailLibraryList, executeEmailTemplatePublish, executeEmailValidate, parseEmailVariablesJson, } from './emailCommands.js';
 import { formatGitHubConnectRows, formatGitHubJobRows, formatGitHubStatusRows, } from './githubOutput.js';
@@ -2278,6 +2279,72 @@ addAlertScopeOptions(preventCommand
     }
     printValueRows(formatPreventSummary(month, summary).map((line) => [line]));
 });
+const addCustomerOptions = (command) => command
+    .option('--workspace <id-or-slug-or-name>', 'Workspace id, slug, or name')
+    .option('--project <id-or-slug-or-name>', 'Project id, slug, or name')
+    .option('--email <email>', 'Customer email (exact match, case-insensitive)')
+    .option('--user-id <id>', 'Funnel user ID (the SDK user ID)')
+    .option('--env <environment>', 'test or live', 'live')
+    .option('--json', 'Print machine-readable JSON');
+const resolveCustomerCommandScope = async (options) => {
+    const selector = parseCustomerSelector(options);
+    return { scope: await resolveProjectCommandScope(options), selector };
+};
+const customersCommand = addExamples(program.command('customers').description('Look up a customer\'s subscriptions and payments, refund payments and cancel subscriptions (workspace admins)'), [
+    'fgrove customers lookup --project claimbee --email buyer@example.com',
+    'fgrove customers refund --project claimbee --email buyer@example.com --payment ch_123 --payment pay_456',
+    'fgrove customers cancel --project claimbee --user-id 8f1c... --now',
+]);
+addCustomerOptions(customersCommand
+    .command('lookup')
+    .description('List the customer\'s funnel users, live provider subscriptions and payments with refund eligibility'))
+    .action(async (options) => {
+    const { scope, selector } = await resolveCustomerCommandScope(options);
+    const lookup = await lookupCustomer(scope, selector);
+    if (options.json) {
+        console.log(JSON.stringify(lookup, null, 2));
+        return;
+    }
+    printValueRows(formatCustomerLookup(lookup).map((line) => [line]));
+});
+addCustomerOptions(customersCommand
+    .command('refund')
+    .description('Fully refund the remaining amount of each chosen payment (payment IDs from customers lookup)')
+    .requiredOption('--payment <id>', 'Payment ID from customers lookup; repeat for several', (value, previous = []) => [...previous, value])
+    .option('--dry-run', 'Show what would be refunded without refunding'))
+    .action(async (options) => {
+    const { scope, selector } = await resolveCustomerCommandScope(options);
+    if (options.dryRun) {
+        const preview = previewRefund(await lookupCustomer(scope, selector), options.payment);
+        console.log(options.json ? JSON.stringify({ dryRun: true, refunds: preview }, null, 2)
+            : formatRefundPreview(preview).join('\n'));
+        return;
+    }
+    const { refunds } = await refundCustomerPayments(scope, selector, options.payment);
+    if (refunds.some((refund) => refund.outcome === 'failed'))
+        process.exitCode = 1;
+    if (options.json) {
+        console.log(JSON.stringify({ refunds }, null, 2));
+        return;
+    }
+    printValueRows(formatCustomerRefunds(refunds).map((line) => [line]));
+});
+addCustomerOptions(customersCommand
+    .command('cancel')
+    .description('Cancel the customer\'s billing subscription at period end, or immediately with --now')
+    .option('--subscription <id>', 'Subscription ID; required when several subscriptions are still billing')
+    .option('--now', 'Cancel immediately; the paid remainder is forfeited without a refund'))
+    .action(async (options) => {
+    const { scope, selector } = await resolveCustomerCommandScope(options);
+    if (options.now)
+        console.error('Cancelling immediately: access ends now and the paid remainder is not refunded.');
+    const result = await cancelCustomerSubscription(scope, selector, { subscriptionId: options.subscription, now: options.now });
+    if (options.json) {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+    }
+    printValueRows(formatCustomerCancellation(result).map((line) => [line]));
+});
 const funnelsCommand = addExamples(program.command('funnels').description('Manage funnels'), [
     'fgrove funnels list',
     'fgrove funnels clone --funnel claimbee --name claimbee-ios',

package/dist/customerCommands.d.ts

@@ -0,0 +1,120 @@
+type CallApi = <T>(input: {
+    path: string;
+    type: 'query' | 'mutation';
+    data?: unknown;
+    token?: string | null;
+}) => Promise<T>;
+export type CustomerCommandScope = {
+    callApi: CallApi;
+    token: string;
+    workspaceId: string;
+    projectId: string;
+};
+export type CustomerSelector = {
+    environment: 'test' | 'live';
+    email?: string;
+    userId?: string;
+};
+type Provider = 'stripe' | 'solidgate';
+export type CustomerSubscription = {
+    provider: Provider;
+    paymentProfileId: string;
+    subscriptionId: string;
+    customerId: string | null;
+    status: string;
+    cancelAtPeriodEnd: boolean;
+    currentPeriodStart: string | null;
+    currentPeriodEnd: string | null;
+    createdAt: string | null;
+    amountMinor: number | null;
+    currency: string | null;
+    interval: string | null;
+    billing: boolean;
+};
+export type CustomerPayment = {
+    provider: Provider;
+    paymentProfileId: string;
+    paymentId: string | null;
+    subscriptionId: string | null;
+    createdAt: string;
+    status: string;
+    amountMinor: number;
+    refundedMinor: number;
+    currency: string;
+    description: string | null;
+    refundable: boolean;
+    notRefundableReason: string | null;
+};
+export type CustomerLookup = {
+    environment: 'test' | 'live';
+    users: Array<{
+        funnelUserId: string;
+        userId: string | null;
+        email: string | null;
+        funnelId: string | null;
+        createdAt: string;
+    }>;
+    subscriptions: CustomerSubscription[];
+    payments: CustomerPayment[];
+    sources: Array<{
+        provider: string;
+        paymentProfileId: string | null;
+        status: 'answered' | 'failed' | 'not-supported';
+        detail?: string;
+    }>;
+};
+export type CustomerRefund = {
+    paymentId: string;
+    provider: Provider | null;
+    outcome: 'refunded' | 'already_refunded' | 'processing' | 'failed';
+    amountMinor: number;
+    currency: string | null;
+    refundIds: string[];
+    error?: string;
+};
+export type CustomerCancellation = {
+    provider: Provider;
+    paymentProfileId: string;
+    subscriptionId: string;
+    mode: 'period_end' | 'immediate';
+    status: string;
+    cancelAtPeriodEnd: boolean;
+    accessUntilBefore: string | null;
+    accessUntil: string | null;
+    paidDaysForfeited: number;
+};
+/** Exactly one of email or user ID; emails are matched trimmed and lowercased. */
+export declare const parseCustomerSelector: (options: {
+    email?: string;
+    userId?: string;
+    env?: string;
+}) => CustomerSelector;
+export declare const lookupCustomer: (scope: CustomerCommandScope, selector: CustomerSelector) => Promise<CustomerLookup>;
+export declare const refundCustomerPayments: (scope: CustomerCommandScope, selector: CustomerSelector, paymentIds: string[]) => Promise<{
+    refunds: CustomerRefund[];
+}>;
+export declare const cancelCustomerSubscription: (scope: CustomerCommandScope, selector: CustomerSelector, input: {
+    subscriptionId?: string;
+    now?: boolean;
+}) => Promise<CustomerCancellation>;
+/** Payments the refund would touch, in the order requested; unknown IDs are reported, not dropped. */
+export declare const previewRefund: (lookup: CustomerLookup, paymentIds: string[]) => ({
+    paymentId: string;
+    provider: Provider;
+    amountMinor: number;
+    currency: string;
+    refundable: boolean;
+    reason: string | null;
+} | {
+    paymentId: string;
+    provider: null;
+    amountMinor: number;
+    currency: null;
+    refundable: boolean;
+    reason: string;
+})[];
+export declare const formatRefundPreview: (preview: ReturnType<typeof previewRefund>) => string[];
+export declare const formatCustomerLookup: (lookup: CustomerLookup) => string[];
+export declare const formatCustomerRefunds: (refunds: CustomerRefund[]) => string[];
+export declare const formatCustomerCancellation: (result: CustomerCancellation) => string[];
+export {};

package/dist/customerCommands.js

@@ -0,0 +1,71 @@
+import { formatMinor } from './alertCommands.js';
+/** Exactly one of email or user ID; emails are matched trimmed and lowercased. */
+export const parseCustomerSelector = (options) => {
+    const email = options.email?.trim().toLowerCase();
+    const userId = options.userId?.trim();
+    if (Boolean(email) === Boolean(userId))
+        throw new Error('Pass exactly one of --email or --user-id.');
+    if (options.env && options.env !== 'test' && options.env !== 'live')
+        throw new Error('--env must be test or live.');
+    return { environment: options.env ?? 'live', ...(email ? { email } : { userId }) };
+};
+const request = (scope, selector) => ({
+    workspaceId: scope.workspaceId, projectId: scope.projectId, ...selector,
+});
+export const lookupCustomer = (scope, selector) => scope.callApi({
+    path: 'customers.lookup', type: 'query', token: scope.token, data: request(scope, selector),
+});
+export const refundCustomerPayments = (scope, selector, paymentIds) => (scope.callApi({
+    path: 'customers.refund', type: 'mutation', token: scope.token, data: { ...request(scope, selector), paymentIds },
+}));
+export const cancelCustomerSubscription = (scope, selector, input) => scope.callApi({
+    path: 'customers.cancel',
+    type: 'mutation',
+    token: scope.token,
+    data: { ...request(scope, selector), ...(input.subscriptionId ? { subscriptionId: input.subscriptionId } : {}), mode: input.now ? 'immediate' : 'period_end' },
+});
+/** Payments the refund would touch, in the order requested; unknown IDs are reported, not dropped. */
+export const previewRefund = (lookup, paymentIds) => paymentIds.map((paymentId) => {
+    const payment = lookup.payments.find((candidate) => candidate.paymentId === paymentId);
+    return payment
+        ? { paymentId, provider: payment.provider, amountMinor: payment.amountMinor - payment.refundedMinor, currency: payment.currency, refundable: payment.refundable, reason: payment.notRefundableReason }
+        : { paymentId, provider: null, amountMinor: 0, currency: null, refundable: false, reason: 'Not found in customers lookup' };
+});
+export const formatRefundPreview = (preview) => preview.map((row) => [
+    row.paymentId, row.refundable ? `would refund ${formatMinor(row.amountMinor, row.currency)}` : `skip: ${row.reason}`,
+].join('\t'));
+const day = (value) => value?.slice(0, 10) ?? '';
+export const formatCustomerLookup = (lookup) => {
+    const lines = [`Environment\t${lookup.environment}`];
+    for (const user of lookup.users)
+        lines.push(`User\t${user.userId ?? ''}\t${user.email ?? ''}\tfunnel user ${user.funnelUserId}\tcreated ${day(user.createdAt)}`);
+    lines.push('', ['subscription', 'provider', 'status', 'billing', 'price', 'period_end', 'cancel_at_period_end'].join('\t'));
+    for (const subscription of lookup.subscriptions) {
+        lines.push([subscription.subscriptionId, subscription.provider, subscription.status, subscription.billing ? 'yes' : 'no',
+            subscription.amountMinor === null ? '' : `${formatMinor(subscription.amountMinor, subscription.currency)}${subscription.interval ? `/${subscription.interval}` : ''}`,
+            day(subscription.currentPeriodEnd), subscription.cancelAtPeriodEnd ? 'yes' : 'no'].join('\t'));
+    }
+    lines.push('', ['created_at', 'payment', 'provider', 'status', 'amount', 'refunded', 'refundable', 'subscription', 'description'].join('\t'));
+    for (const payment of lookup.payments) {
+        lines.push([payment.createdAt, payment.paymentId ?? '(unknown)', payment.provider, payment.status, formatMinor(payment.amountMinor, payment.currency),
+            payment.refundedMinor ? formatMinor(payment.refundedMinor, payment.currency) : '', payment.refundable ? 'yes' : `no: ${payment.notRefundableReason}`,
+            payment.subscriptionId ?? '', payment.description ?? ''].join('\t'));
+    }
+    const gaps = lookup.sources.filter((source) => source.status !== 'answered');
+    if (gaps.length) {
+        lines.push('', 'Incomplete: some provider accounts did not answer; missing data does not mean there is no subscription.');
+        for (const source of gaps)
+            lines.push(`  ${source.provider}\t${source.paymentProfileId ?? ''}\t${source.status}\t${source.detail ?? ''}`);
+    }
+    return lines;
+};
+export const formatCustomerRefunds = (refunds) => refunds.map((refund) => [
+    refund.paymentId, refund.outcome.replace('_', ' '),
+    refund.error ?? formatMinor(refund.amountMinor, refund.currency), refund.refundIds.join(','),
+].join('\t'));
+export const formatCustomerCancellation = (result) => [
+    `Subscription\t${result.subscriptionId} (${result.provider})`,
+    `Status\t${result.status}${result.cancelAtPeriodEnd ? ', cancels at period end' : ''}`,
+    `Access until\t${result.accessUntil ?? ''} (was ${result.accessUntilBefore ?? 'unknown'})`,
+    ...(result.paidDaysForfeited ? [`Paid days forfeited without refund\t${result.paidDaysForfeited}`] : []),
+];

package/funnel-contract-compatibility.json

@@ -4,10 +4,10 @@
   "minimumCliVersion": "0.1.20",
   "entries": [
     {
-      "repositoryCliVersion": "0.1.308",
+      "repositoryCliVersion": "0.1.309",
       "manifest": {
         "schemaVersion": 1,
-        "bundleVersion": "2.0.301",
+        "bundleVersion": "2.0.302",
         "stepContractVersion": 3,
         "contractHash": "d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf",
         "managedFiles": [
@@ -45,7 +45,7 @@
           },
           {
             "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-            "sha256": "2c7f7e4ee64cb6fdf5f69c4c35b53bdbf63659494323cd4a93826374e1560f8a"
+            "sha256": "72d337fa007993d18455f281b9a784e2e15fb46e43038a2934ddfcc82d8c1d28"
           },
           {
             "path": "docs/funnelsgrove/qa/analytics.md",
@@ -145,16 +145,16 @@
           },
           {
             "path": "funnel-docs.config.json",
-            "sha256": "6c5486fea9dae1e582bd9c1fece156d174919c75008a1555bc3876c5ddc01b91"
+            "sha256": "e381723d48a0772419a5f8d757de1bb8fc9d7b3fd7838ad6fcde8ce0031d77c3"
           }
         ]
       }
     },
     {
-      "repositoryCliVersion": "0.1.307",
+      "repositoryCliVersion": "0.1.308",
       "manifest": {
         "schemaVersion": 1,
-        "bundleVersion": "2.0.300",
+        "bundleVersion": "2.0.301",
         "stepContractVersion": 3,
         "contractHash": "d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf",
         "managedFiles": [
@@ -192,7 +192,7 @@
           },
           {
             "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-            "sha256": "5c85ab989a7c1675ef36fda22779d50977a926b6cc417880ae1e08bd35380135"
+            "sha256": "2c7f7e4ee64cb6fdf5f69c4c35b53bdbf63659494323cd4a93826374e1560f8a"
           },
           {
             "path": "docs/funnelsgrove/qa/analytics.md",
@@ -292,16 +292,16 @@
           },
           {
             "path": "funnel-docs.config.json",
-            "sha256": "451b21e025b31e38404784ba88d0a409958e8ed2cf25da163b0a7dd291bb471c"
+            "sha256": "6c5486fea9dae1e582bd9c1fece156d174919c75008a1555bc3876c5ddc01b91"
           }
         ]
       }
     },
     {
-      "repositoryCliVersion": "0.1.306",
+      "repositoryCliVersion": "0.1.307",
       "manifest": {
         "schemaVersion": 1,
-        "bundleVersion": "2.0.299",
+        "bundleVersion": "2.0.300",
         "stepContractVersion": 3,
         "contractHash": "d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf",
         "managedFiles": [
@@ -339,7 +339,7 @@
           },
           {
             "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-            "sha256": "e28376a9ab3d97ba9da5380d8c424dd4ace9f8bd7f83b21c1e87de55c14636b4"
+            "sha256": "5c85ab989a7c1675ef36fda22779d50977a926b6cc417880ae1e08bd35380135"
           },
           {
             "path": "docs/funnelsgrove/qa/analytics.md",
@@ -439,16 +439,16 @@
           },
           {
             "path": "funnel-docs.config.json",
-            "sha256": "3bcbc5df69c1d4ef7e25430a5d48fb0af48919a6b5844f73d77b14478df7e6af"
+            "sha256": "451b21e025b31e38404784ba88d0a409958e8ed2cf25da163b0a7dd291bb471c"
           }
         ]
       }
     },
     {
-      "repositoryCliVersion": "0.1.305",
+      "repositoryCliVersion": "0.1.306",
       "manifest": {
         "schemaVersion": 1,
-        "bundleVersion": "2.0.298",
+        "bundleVersion": "2.0.299",
         "stepContractVersion": 3,
         "contractHash": "d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf",
         "managedFiles": [
@@ -474,7 +474,7 @@
           },
           {
             "path": "docs/funnelsgrove/contracts/flow-routing.md",
-            "sha256": "fd81ec6c973f4c3a9c26db813bf44c6cfce3c8bbe17287cdaec330fa566ee78c"
+            "sha256": "050564846bf7d44afb267e1321d6fe277f032fe7b6237441741570c723543d0e"
           },
           {
             "path": "docs/funnelsgrove/contracts/payments.md",
@@ -486,7 +486,7 @@
           },
           {
             "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-            "sha256": "6a7df14c1aad5de56a90931928a2ed3f0ac08cf1e04c34f9a4da77ad65cec8b3"
+            "sha256": "e28376a9ab3d97ba9da5380d8c424dd4ace9f8bd7f83b21c1e87de55c14636b4"
           },
           {
             "path": "docs/funnelsgrove/qa/analytics.md",
@@ -586,16 +586,16 @@
           },
           {
             "path": "funnel-docs.config.json",
-            "sha256": "0009f06c828f9441ff7a9a8a36ca4fe799fc70236b0338506a2e8fb9325092ca"
+            "sha256": "3bcbc5df69c1d4ef7e25430a5d48fb0af48919a6b5844f73d77b14478df7e6af"
           }
         ]
       }
     },
     {
-      "repositoryCliVersion": "0.1.304",
+      "repositoryCliVersion": "0.1.305",
       "manifest": {
         "schemaVersion": 1,
-        "bundleVersion": "2.0.297",
+        "bundleVersion": "2.0.298",
         "stepContractVersion": 3,
         "contractHash": "d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf",
         "managedFiles": [
@@ -621,7 +621,7 @@
           },
           {
             "path": "docs/funnelsgrove/contracts/flow-routing.md",
-            "sha256": "050564846bf7d44afb267e1321d6fe277f032fe7b6237441741570c723543d0e"
+            "sha256": "fd81ec6c973f4c3a9c26db813bf44c6cfce3c8bbe17287cdaec330fa566ee78c"
           },
           {
             "path": "docs/funnelsgrove/contracts/payments.md",
@@ -633,7 +633,7 @@
           },
           {
             "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-            "sha256": "6b5546c6bfabf6c03b3d576bf945de4350a0d8f465a4159a3fb7cae40ba6142a"
+            "sha256": "6a7df14c1aad5de56a90931928a2ed3f0ac08cf1e04c34f9a4da77ad65cec8b3"
           },
           {
             "path": "docs/funnelsgrove/qa/analytics.md",
@@ -733,16 +733,16 @@
           },
           {
             "path": "funnel-docs.config.json",
-            "sha256": "ba7cf49d4b85969994262ae8ca59989cc5ef6a7db7272820556a99887bc5c408"
+            "sha256": "0009f06c828f9441ff7a9a8a36ca4fe799fc70236b0338506a2e8fb9325092ca"
           }
         ]
       }
     },
     {
-      "repositoryCliVersion": "0.1.303",
+      "repositoryCliVersion": "0.1.304",
       "manifest": {
         "schemaVersion": 1,
-        "bundleVersion": "2.0.296",
+        "bundleVersion": "2.0.297",
         "stepContractVersion": 3,
         "contractHash": "d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf",
         "managedFiles": [
@@ -780,7 +780,7 @@
           },
           {
             "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-            "sha256": "b54e093d99f163b399ca52788beabc94530accea7b3c7d60caaf9f067a5aeb04"
+            "sha256": "6b5546c6bfabf6c03b3d576bf945de4350a0d8f465a4159a3fb7cae40ba6142a"
           },
           {
             "path": "docs/funnelsgrove/qa/analytics.md",
@@ -880,16 +880,16 @@
           },
           {
             "path": "funnel-docs.config.json",
-            "sha256": "51ad1bfe95afe002bc2fabefe00655881cc41ab34cfb1d13a0dbf92b31ab0c7e"
+            "sha256": "ba7cf49d4b85969994262ae8ca59989cc5ef6a7db7272820556a99887bc5c408"
           }
         ]
       }
     },
     {
-      "repositoryCliVersion": "0.1.302",
+      "repositoryCliVersion": "0.1.303",
       "manifest": {
         "schemaVersion": 1,
-        "bundleVersion": "2.0.295",
+        "bundleVersion": "2.0.296",
         "stepContractVersion": 3,
         "contractHash": "d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf",
         "managedFiles": [
@@ -907,7 +907,7 @@
           },
           {
             "path": "docs/funnelsgrove/contracts/analytics-events.md",
-            "sha256": "482b159a6b88a86009b9d2bec643d3e6dc4389c7693e1ab26c8df60b1eeb1f19"
+            "sha256": "11c79bd21570374ae591f21594c7235cc2bb015067ad901eddc1420a9998cd25"
           },
           {
             "path": "docs/funnelsgrove/contracts/content-answers.md",
@@ -927,7 +927,7 @@
           },
           {
             "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-            "sha256": "373b181e673ad2fffcbcb68a11fa43186a57cac67493a746aafec03bd0a0ab94"
+            "sha256": "b54e093d99f163b399ca52788beabc94530accea7b3c7d60caaf9f067a5aeb04"
           },
           {
             "path": "docs/funnelsgrove/qa/analytics.md",
@@ -1027,7 +1027,7 @@
           },
           {
             "path": "funnel-docs.config.json",
-            "sha256": "df1b6615d35d8d2385038e26580604bae5921075126dd01159bf7300ba675bf9"
+            "sha256": "51ad1bfe95afe002bc2fabefe00655881cc41ab34cfb1d13a0dbf92b31ab0c7e"
           }
         ]
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@funnelsgrove/cli",
-  "version": "0.1.308",
+  "version": "0.1.309",
   "description": "FunnelsGrove command-line tools for editing, syncing, and publishing funnels",
   "repository": {
     "type": "git",

package/template_docs/.funnelsgrove-docs.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "bundleVersion": "2.0.301",
+  "bundleVersion": "2.0.302",
   "stepContractVersion": 3,
   "contractHash": "d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf",
   "managedFiles": [
@@ -38,7 +38,7 @@
     },
     {
       "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-      "sha256": "2c7f7e4ee64cb6fdf5f69c4c35b53bdbf63659494323cd4a93826374e1560f8a"
+      "sha256": "72d337fa007993d18455f281b9a784e2e15fb46e43038a2934ddfcc82d8c1d28"
     },
     {
       "path": "docs/funnelsgrove/qa/analytics.md",
@@ -138,7 +138,7 @@
     },
     {
       "path": "funnel-docs.config.json",
-      "sha256": "6c5486fea9dae1e582bd9c1fece156d174919c75008a1555bc3876c5ddc01b91"
+      "sha256": "e381723d48a0772419a5f8d757de1bb8fc9d7b3fd7838ad6fcde8ce0031d77c3"
     }
   ]
 }

package/template_docs/docs/funnelsgrove/migrations/step-contract-v3.md

@@ -17,7 +17,7 @@ Supported read versions: `1`, `2`, `3`. Authoring and publish target version `3`
 
 ### Package release order
 
-Release `@funnelsgrove/sdk` `0.4.0` first, then `@funnelsgrove/runtime` `0.38.0`, then `@funnelsgrove/analytics` `0.20.0`, then `@funnelsgrove/payments` `0.51.0`. The production deploy verifies the zero-traffic API candidate, publishes and verifies `@funnelsgrove/cli` `0.1.308`, and only then promotes the candidate to production traffic. The serving API must never advertise an unpublished preferred CLI. Publishing packages and deploying production remain separately approved operational actions.
+Release `@funnelsgrove/sdk` `0.4.0` first, then `@funnelsgrove/runtime` `0.39.0`, then `@funnelsgrove/analytics` `0.21.0`, then `@funnelsgrove/payments` `0.52.0`. The production deploy verifies the zero-traffic API candidate, publishes and verifies `@funnelsgrove/cli` `0.1.309`, and only then promotes the candidate to production traffic. The serving API must never advertise an unpublished preferred CLI. Publishing packages and deploying production remain separately approved operational actions.
 <!-- funnelsgrove:generated:end contract-v3/migration/step-contract-v3 -->
 
 ## Version-last policy

package/template_docs/funnel-docs.config.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "bundleVersion": "2.0.301",
+  "bundleVersion": "2.0.302",
   "contractSource": "funnelsgrove-repository://apps/funnel-runtime/contracts/step-contract-v2.json",
   "fullyGenerated": [
     ".funnelsgrove-docs.json",

package/template_scaffold/.funnelsgrove-docs.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "bundleVersion": "2.0.301",
+  "bundleVersion": "2.0.302",
   "stepContractVersion": 3,
   "contractHash": "d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf",
   "managedFiles": [
@@ -38,7 +38,7 @@
     },
     {
       "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-      "sha256": "2c7f7e4ee64cb6fdf5f69c4c35b53bdbf63659494323cd4a93826374e1560f8a"
+      "sha256": "72d337fa007993d18455f281b9a784e2e15fb46e43038a2934ddfcc82d8c1d28"
     },
     {
       "path": "docs/funnelsgrove/qa/analytics.md",
@@ -138,7 +138,7 @@
     },
     {
       "path": "funnel-docs.config.json",
-      "sha256": "6c5486fea9dae1e582bd9c1fece156d174919c75008a1555bc3876c5ddc01b91"
+      "sha256": "e381723d48a0772419a5f8d757de1bb8fc9d7b3fd7838ad6fcde8ce0031d77c3"
     }
   ]
 }

package/template_scaffold/.funnelsgrove-scaffold.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
-  "sourceTreeHash": "08faba0e5942271e944866ec1c9bb7fdc652e853d881078bb5e261a479ff3a23",
+  "sourceTreeHash": "dcd370b7855a36f8157ecd731e4bf3d3cc10b0c360c769be3314cae460cd8099",
   "stepContractVersion": 3,
-  "docsBundleVersion": "2.0.301",
+  "docsBundleVersion": "2.0.302",
   "files": [
     {
       "path": ".env.example",
@@ -16,7 +16,7 @@
     },
     {
       "path": ".funnelsgrove-docs.json",
-      "sha256": "507b6fb6eb31373c60da9315ae32880f4bd9094de87dae2a17bc8810e3b45c9d",
+      "sha256": "7316f1d05693f4d9ca4311c5c279744de86198da046c392905c8939b940c6fe9",
       "mode": "100644"
     },
     {
@@ -76,7 +76,7 @@
     },
     {
       "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-      "sha256": "2c7f7e4ee64cb6fdf5f69c4c35b53bdbf63659494323cd4a93826374e1560f8a",
+      "sha256": "72d337fa007993d18455f281b9a784e2e15fb46e43038a2934ddfcc82d8c1d28",
       "mode": "100644"
     },
     {
@@ -206,7 +206,7 @@
     },
     {
       "path": "funnel-docs.config.json",
-      "sha256": "6c5486fea9dae1e582bd9c1fece156d174919c75008a1555bc3876c5ddc01b91",
+      "sha256": "e381723d48a0772419a5f8d757de1bb8fc9d7b3fd7838ad6fcde8ce0031d77c3",
       "mode": "100644"
     },
     {

package/template_scaffold/docs/funnelsgrove/migrations/step-contract-v3.md

@@ -17,7 +17,7 @@ Supported read versions: `1`, `2`, `3`. Authoring and publish target version `3`
 
 ### Package release order
 
-Release `@funnelsgrove/sdk` `0.4.0` first, then `@funnelsgrove/runtime` `0.38.0`, then `@funnelsgrove/analytics` `0.20.0`, then `@funnelsgrove/payments` `0.51.0`. The production deploy verifies the zero-traffic API candidate, publishes and verifies `@funnelsgrove/cli` `0.1.308`, and only then promotes the candidate to production traffic. The serving API must never advertise an unpublished preferred CLI. Publishing packages and deploying production remain separately approved operational actions.
+Release `@funnelsgrove/sdk` `0.4.0` first, then `@funnelsgrove/runtime` `0.39.0`, then `@funnelsgrove/analytics` `0.21.0`, then `@funnelsgrove/payments` `0.52.0`. The production deploy verifies the zero-traffic API candidate, publishes and verifies `@funnelsgrove/cli` `0.1.309`, and only then promotes the candidate to production traffic. The serving API must never advertise an unpublished preferred CLI. Publishing packages and deploying production remain separately approved operational actions.
 <!-- funnelsgrove:generated:end contract-v3/migration/step-contract-v3 -->
 
 ## Version-last policy

package/template_scaffold/funnel-docs.config.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "bundleVersion": "2.0.301",
+  "bundleVersion": "2.0.302",
   "contractSource": "funnelsgrove-repository://apps/funnel-runtime/contracts/step-contract-v2.json",
   "fullyGenerated": [
     ".funnelsgrove-docs.json",