@funnelsgrove/cli 0.1.282 → 0.1.285

package/dist/cli.js

@@ -19,7 +19,7 @@ import { pullEnvFile } from './envSync.js';
 import { executeFastDraftPatchSync, uploadDirectAssetWithFetch } from './draftPatchSync.js';
 import { updateCliInstallations } from './selfUpdate.js';
 import { executeExpensePublish, executeExpensePull } from './expenseCommands.js';
-import { executeEmailPull, executeEmailPush, executeEmailSend, executeEmailUpdateVariables, executeEmailSequenceAddStep, executeEmailSequenceCancel, executeEmailSequenceCreate, executeEmailSequencePublish, executeEmailSequenceSetActive, executeEmailTemplatePublish, executeEmailValidate, parseEmailVariablesJson, } from './emailCommands.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';
 import { GitHubSyncTimeoutError, syncGitHubDraftIfConnected, } from './githubSyncFlow.js';
 import { reskinFunnel } from './reskin.js';
@@ -1800,6 +1800,8 @@ const emailCommand = addExamples(program.command('email').description('Manage pr
     'fgrove email push',
     'fgrove email send --template welcome --to delivered@example.com',
     'fgrove email template publish welcome',
+    'fgrove email library list',
+    'fgrove email library add subscription-receipt --app-name "Lumen" --manage-url https://lumen.example.com/manage',
 ]);
 emailCommand
     .command('send')
@@ -1890,6 +1892,51 @@ addEmailScopeOptions(emailTemplateCommand
     });
     console.log(`Published email template ${slug}.`);
 });
+const emailLibraryCommand = emailCommand.command('library').description('Browse and copy shared email templates');
+addEmailScopeOptions(emailLibraryCommand
+    .command('list')
+    .description('List shared templates, their variables and the project footer defaults'))
+    .option('--json', 'Print the full library response as JSON')
+    .action(async (options) => {
+    const library = await executeEmailLibraryList(await resolveEmailCommandScope(options));
+    if (options.json) {
+        console.log(JSON.stringify(library, null, 2));
+        return;
+    }
+    for (const template of library.templates) {
+        console.log(`${template.slug}\t${template.name}\t${template.summary}`);
+        for (const [name, type] of Object.entries(template.variables)) {
+            console.log(`  ${name} (${type})\t${template.variableDescriptions[name] || ''}`);
+        }
+    }
+    console.log(`defaults\tsupportEmail=${library.defaults.supportEmail || '-'}\ttermsUrl=${library.defaults.termsUrl || '-'}\tprivacyUrl=${library.defaults.privacyUrl || '-'}`);
+});
+addEmailScopeOptions(emailLibraryCommand
+    .command('add <library-slug>')
+    .description('Copy a shared template into the project as a draft and write it locally'))
+    .requiredOption('--app-name <name>', 'App name shown in the email')
+    .requiredOption('--manage-url <url>', 'HTTPS page where customers change or cancel their subscription')
+    .option('--icon-url <url>', 'HTTPS URL of a square app icon (PNG, at least 176x176), ideally hosted on the domain you send email from. Omit to use a generic app icon')
+    .option('--support-email <email>', 'Support email in the footer (defaults to the project support email)')
+    .option('--terms-url <url>', 'Terms of Service URL (defaults to the project setting)')
+    .option('--privacy-url <url>', 'Privacy Policy URL (defaults to the project setting)')
+    .option('--slug <slug>', 'Project template slug (defaults to the library slug)')
+    .action(async (librarySlug, options) => {
+    const template = await executeEmailLibraryAdd({
+        ...await resolveEmailCommandScope(options),
+        librarySlug,
+        slug: options.slug,
+        settings: {
+            appName: options.appName,
+            manageSubscriptionUrl: options.manageUrl,
+            ...(options.iconUrl ? { appIconUrl: options.iconUrl } : {}),
+            ...(options.supportEmail ? { supportEmail: options.supportEmail } : {}),
+            ...(options.termsUrl ? { termsUrl: options.termsUrl } : {}),
+            ...(options.privacyUrl ? { privacyUrl: options.privacyUrl } : {}),
+        },
+    });
+    console.log(`Added email template ${template.slug} as a draft. Review ${path.join(options.dir, 'emails', 'templates', template.slug)}, then run fgrove email template publish ${template.slug}.`);
+});
 const emailSequenceCommand = emailCommand.command('sequence').description('Manage email sequences');
 const parseEmailSequenceDelay = (options) => {
     const hasHours = options.delayHours !== undefined;

package/dist/emailCommands.d.ts

@@ -1,4 +1,4 @@
-import { type EmailFilesResult, type EmailEventType } from './emailFiles.js';
+import { type EmailFilesResult, type EmailEventType, type EmailTemplateFile } from './emailFiles.js';
 export type EmailCallApi = <T>(input: {
     path: string;
     type: 'query' | 'mutation';
@@ -94,6 +94,33 @@ export declare function executeEmailSequenceSetActive(input: EmailCommandScope &
     slug: string;
     active: boolean;
 }): Promise<void>;
+export type EmailLibraryList = {
+    defaults: {
+        supportEmail: string | null;
+        termsUrl: string | null;
+        privacyUrl: string | null;
+    };
+    templates: Array<{
+        slug: string;
+        name: string;
+        summary: string;
+        variables: Record<string, string>;
+        variableDescriptions: Record<string, string>;
+    }>;
+};
+export declare const executeEmailLibraryList: (scope: EmailCommandScope) => Promise<EmailLibraryList>;
+export declare function executeEmailLibraryAdd(input: EmailCommandScope & {
+    librarySlug: string;
+    slug?: string;
+    settings: {
+        appName: string;
+        appIconUrl?: string;
+        manageSubscriptionUrl: string;
+        supportEmail?: string;
+        termsUrl?: string;
+        privacyUrl?: string;
+    };
+}): Promise<EmailTemplateFile>;
 export declare function executeEmailTemplatePublish(scope: EmailCommandScope & {
     slug: string;
 }): Promise<unknown>;

package/dist/emailCommands.js

@@ -199,6 +199,7 @@ const assertRemoteIdentities = async (scope, input) => {
 const canonicalResource = (kind, value) => {
     if (kind === 'template') {
         const variables = isRecord(value.draft.variables) ? value.draft.variables : {};
+        const variableDescriptions = isRecord(value.draft.variableDescriptions) ? value.draft.variableDescriptions : {};
         return JSON.stringify({
             name: value.name,
             subject: value.draft.subject,
@@ -206,6 +207,7 @@ const canonicalResource = (kind, value) => {
             html: value.draft.html,
             text: value.draft.text,
             variables: Object.fromEntries(Object.entries(variables).sort(([left], [right]) => left.localeCompare(right))),
+            variableDescriptions: Object.fromEntries(Object.entries(variableDescriptions).sort(([left], [right]) => left.localeCompare(right))),
         });
     }
     const steps = Array.isArray(value.draft.steps) ? value.draft.steps : [];
@@ -301,7 +303,7 @@ export async function executeEmailPush(scope) {
                     ...projectData(scope),
                     templateId: template.id,
                     name: template.name,
-                    draft: template.draft,
+                    draft: { ...template.draft, variableDescriptions: template.draft.variableDescriptions ?? {} },
                 },
             });
             continue;
@@ -314,7 +316,7 @@ export async function executeEmailPush(scope) {
                 ...projectData(scope),
                 slug: template.slug,
                 name: template.name,
-                draft: template.draft,
+                draft: { ...template.draft, variableDescriptions: template.draft.variableDescriptions ?? {} },
             },
         });
         template.id = assertCreatedId(created, 'email template');
@@ -471,6 +473,39 @@ export async function executeEmailSequenceSetActive(input) {
         },
     });
 }
+export const executeEmailLibraryList = (scope) => (scope.callApi({
+    path: 'emailTemplates.library',
+    type: 'query',
+    token: scope.token,
+    data: projectData(scope),
+}));
+export async function executeEmailLibraryAdd(input) {
+    const files = await readEmailFiles(input.sourceDir);
+    assertValidFiles(files);
+    const slug = input.slug || input.librarySlug;
+    if (files.templates.some((item) => item.slug === slug)) {
+        throw new Error(`Email template "${slug}" already exists locally.`);
+    }
+    const created = await input.callApi({
+        path: 'emailTemplates.copyFromLibrary',
+        type: 'mutation',
+        token: input.token,
+        data: {
+            ...projectData(input),
+            librarySlug: input.librarySlug,
+            ...(input.slug ? { slug: input.slug } : {}),
+            settings: input.settings,
+        },
+    });
+    const template = {
+        id: assertCreatedId(created, 'email template'),
+        slug: created.slug,
+        name: created.name,
+        draft: created.draft,
+    };
+    await writeEmailTemplateFile(input.sourceDir, template);
+    return template;
+}
 export async function executeEmailTemplatePublish(scope) {
     return executeEmailPublish(scope, {
         kind: 'template',

package/dist/emailFiles.d.ts

@@ -8,6 +8,7 @@ export type EmailTemplateDraft = {
     html: string;
     text: string;
     variables: Record<string, EmailTemplateVariableType>;
+    variableDescriptions?: Record<string, string>;
 };
 export type EmailTemplateFile = {
     id: string | null;

package/dist/emailFiles.js

@@ -24,6 +24,7 @@ const TEMPLATE_METADATA_KEYS = new Set([
     'subject',
     'previewText',
     'variables',
+    'variableDescriptions',
 ]);
 const SEQUENCE_KEYS = new Set([
     'id',
@@ -219,9 +220,37 @@ const validateTemplateMetadata = (value, pathSlug, file, diagnostics) => {
             }
         }
     }
+    const variableDescriptions = {};
+    if (value.variableDescriptions !== undefined) {
+        if (!isRecord(value.variableDescriptions) || Object.getPrototypeOf(value.variableDescriptions) !== Object.prototype) {
+            diagnostics.push(schemaDiagnostic(file, 'variableDescriptions', 'object', value.variableDescriptions));
+        }
+        else {
+            for (const [name, description] of Object.entries(value.variableDescriptions)) {
+                if (!isRecord(value.variables) || !Object.hasOwn(value.variables, name)) {
+                    diagnostics.push(schemaDiagnostic(file, `variableDescriptions.${name}`, 'declared variable name', name));
+                }
+                else if (typeof description !== 'string'
+                    || !description.trim()
+                    || Buffer.byteLength(description.trim(), 'utf8') > 500
+                    || [...description].some((character) => {
+                        const code = character.codePointAt(0);
+                        return code <= 0x1f || (code >= 0x7f && code <= 0x9f);
+                    })) {
+                    diagnostics.push(schemaDiagnostic(file, `variableDescriptions.${name}`, 'non-empty string up to 500 UTF-8 bytes without control characters', description));
+                }
+                else {
+                    variableDescriptions[name] = description.trim();
+                }
+            }
+        }
+    }
     if (diagnostics.length !== initialCount)
         return null;
-    return value;
+    return {
+        ...value,
+        ...(value.variableDescriptions === undefined ? {} : { variableDescriptions }),
+    };
 };
 const validateSequence = (value, pathSlug, file, diagnostics) => {
     if (!isRecord(value)) {
@@ -442,6 +471,7 @@ export async function readEmailFiles(sourceDir) {
                         html,
                         text,
                         variables: metadata.variables,
+                        ...(metadata.variableDescriptions === undefined ? {} : { variableDescriptions: metadata.variableDescriptions }),
                     },
                 });
             }
@@ -486,6 +516,9 @@ export async function writeEmailTemplateFile(sourceDir, template) {
         subject: template.draft.subject,
         previewText: template.draft.previewText,
         variables: sortedVariables(template.draft.variables),
+        ...(Object.keys(template.draft.variableDescriptions ?? {}).length === 0 ? {} : {
+            variableDescriptions: sortedVariables(template.draft.variableDescriptions),
+        }),
     };
     await writeAtomic(path.join(directory, 'template.json'), `${JSON.stringify(metadata, null, 2)}\n`);
     await Promise.all([

package/funnel-contract-compatibility.json

@@ -4,10 +4,10 @@
   "minimumCliVersion": "0.1.20",
   "entries": [
     {
-      "repositoryCliVersion": "0.1.282",
+      "repositoryCliVersion": "0.1.285",
       "manifest": {
         "schemaVersion": 1,
-        "bundleVersion": "2.0.275",
+        "bundleVersion": "2.0.278",
         "stepContractVersion": 3,
         "contractHash": "d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf",
         "managedFiles": [
@@ -37,7 +37,7 @@
           },
           {
             "path": "docs/funnelsgrove/contracts/payments.md",
-            "sha256": "67b8a8bbe575019cf8708c1e03f76c6661ce96ca1dc658cafe486256945f6826"
+            "sha256": "993f4bb468db7eb874c81c23464b76260a51c0f9491b563fea6ab9d59dad59ef"
           },
           {
             "path": "docs/funnelsgrove/contracts/step-metadata.md",
@@ -45,7 +45,7 @@
           },
           {
             "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-            "sha256": "291485278a2071a4e73422412e8f81e6ef64bc8b5aa3837b5a9e6dec54501607"
+            "sha256": "ce93e7385a991ba5fd0c5b2d00499f0efc8bc6aabdf67f5288aa0b06648d987b"
           },
           {
             "path": "docs/funnelsgrove/qa/analytics.md",
@@ -145,16 +145,16 @@
           },
           {
             "path": "funnel-docs.config.json",
-            "sha256": "b1ed6276f1565a432a9f48036669b15ed4edfb7c955bf74b312a2b5502f128eb"
+            "sha256": "a8e381a1f92df52dbc9d20bb08b5012991132996848fdf41cc6e14ca12f4d9d1"
           }
         ]
       }
     },
     {
-      "repositoryCliVersion": "0.1.281",
+      "repositoryCliVersion": "0.1.284",
       "manifest": {
         "schemaVersion": 1,
-        "bundleVersion": "2.0.274",
+        "bundleVersion": "2.0.277",
         "stepContractVersion": 3,
         "contractHash": "d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf",
         "managedFiles": [
@@ -184,7 +184,7 @@
           },
           {
             "path": "docs/funnelsgrove/contracts/payments.md",
-            "sha256": "67b8a8bbe575019cf8708c1e03f76c6661ce96ca1dc658cafe486256945f6826"
+            "sha256": "993f4bb468db7eb874c81c23464b76260a51c0f9491b563fea6ab9d59dad59ef"
           },
           {
             "path": "docs/funnelsgrove/contracts/step-metadata.md",
@@ -192,7 +192,7 @@
           },
           {
             "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-            "sha256": "3d6d1dc040dc64ba2b0d99d568d161efb621ddfc8e03b79e5fea72eb407cc086"
+            "sha256": "876896d34bd8dcca2b9d5abffe84895f307d5795b093b55502085b45549c95dc"
           },
           {
             "path": "docs/funnelsgrove/qa/analytics.md",
@@ -292,16 +292,16 @@
           },
           {
             "path": "funnel-docs.config.json",
-            "sha256": "9f2c2f20da1c0e9cc714a563041e01a3bd80d416a3965be6237c6036a6ab1f4d"
+            "sha256": "d2e0907e2f3fbe1dc37396d51a3b75653fe141961788b0442615fcce97d70aa9"
           }
         ]
       }
     },
     {
-      "repositoryCliVersion": "0.1.280",
+      "repositoryCliVersion": "0.1.283",
       "manifest": {
         "schemaVersion": 1,
-        "bundleVersion": "2.0.273",
+        "bundleVersion": "2.0.276",
         "stepContractVersion": 3,
         "contractHash": "d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf",
         "managedFiles": [
@@ -339,7 +339,7 @@
           },
           {
             "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-            "sha256": "0d5fc0fbb91286906cdfe5edd317ce970cd20b9210cea694d6b5ed630b2f8a3e"
+            "sha256": "57e1c0b45e30abe00ae6a1809d8dd4bd2589d4fe74ec21772c186860f13d48ef"
           },
           {
             "path": "docs/funnelsgrove/qa/analytics.md",
@@ -439,16 +439,16 @@
           },
           {
             "path": "funnel-docs.config.json",
-            "sha256": "ca45c7be882af24d09999ab0ee7130645f9bfe4fb56addd2f7966bb31807e610"
+            "sha256": "32f6697d21d89786ee7ef42d9baa86ddfa7b50fbd8726f781708050e2c2085bc"
           }
         ]
       }
     },
     {
-      "repositoryCliVersion": "0.1.279",
+      "repositoryCliVersion": "0.1.282",
       "manifest": {
         "schemaVersion": 1,
-        "bundleVersion": "2.0.272",
+        "bundleVersion": "2.0.275",
         "stepContractVersion": 3,
         "contractHash": "d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf",
         "managedFiles": [
@@ -486,7 +486,7 @@
           },
           {
             "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-            "sha256": "038a83e26aa4d24ad4ad6ec78a548cc7a2f2bc84d67adde6e9cc03bc11795a09"
+            "sha256": "291485278a2071a4e73422412e8f81e6ef64bc8b5aa3837b5a9e6dec54501607"
           },
           {
             "path": "docs/funnelsgrove/qa/analytics.md",
@@ -586,22 +586,22 @@
           },
           {
             "path": "funnel-docs.config.json",
-            "sha256": "3eacc262001aadac7bdc68e58d69fa8a102ef919cbdd09178f5be90812468747"
+            "sha256": "b1ed6276f1565a432a9f48036669b15ed4edfb7c955bf74b312a2b5502f128eb"
           }
         ]
       }
     },
     {
-      "repositoryCliVersion": "0.1.278",
+      "repositoryCliVersion": "0.1.281",
       "manifest": {
         "schemaVersion": 1,
-        "bundleVersion": "2.0.271",
+        "bundleVersion": "2.0.274",
         "stepContractVersion": 3,
         "contractHash": "d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf",
         "managedFiles": [
           {
             "path": "AGENTS.md",
-            "sha256": "3860d21f4a3f9b0c25ca54f7a87762d801f14b82a181b4c0b941c57187908f99"
+            "sha256": "b7dc496d1dcfea176fb5a57e6d17f64abdcff77afeccfcecbbe1790d11da7386"
           },
           {
             "path": "CLAUDE.md",
@@ -609,7 +609,7 @@
           },
           {
             "path": "docs/funnelsgrove/START-HERE.md",
-            "sha256": "ef7525739aa0cd5ea42906fca2ae6ca0327465e6939956f9567e3029148a0bd5"
+            "sha256": "5442274f8ca7ddded834147a693677e203a9c223e1db4260e56bf498ec06a362"
           },
           {
             "path": "docs/funnelsgrove/contracts/analytics-events.md",
@@ -617,7 +617,7 @@
           },
           {
             "path": "docs/funnelsgrove/contracts/content-answers.md",
-            "sha256": "38cd477fa65cb00718c6609ede520bc5b7538f331072c888a6cc32e8d0130d27"
+            "sha256": "efd912eb405e4c64b33becb1cf9a397ba5fe9afc2d4e2aea115a0f5e0703ca87"
           },
           {
             "path": "docs/funnelsgrove/contracts/flow-routing.md",
@@ -633,7 +633,7 @@
           },
           {
             "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-            "sha256": "012ef8788fdb0b5f7b8acc283ee9d0c3c9e23f68d944327ed8c2d9378de94585"
+            "sha256": "3d6d1dc040dc64ba2b0d99d568d161efb621ddfc8e03b79e5fea72eb407cc086"
           },
           {
             "path": "docs/funnelsgrove/qa/analytics.md",
@@ -733,22 +733,22 @@
           },
           {
             "path": "funnel-docs.config.json",
-            "sha256": "580a792c8650972c8016c0052bec88f7a5331445a8a039bb35912c2da4c645a0"
+            "sha256": "9f2c2f20da1c0e9cc714a563041e01a3bd80d416a3965be6237c6036a6ab1f4d"
           }
         ]
       }
     },
     {
-      "repositoryCliVersion": "0.1.277",
+      "repositoryCliVersion": "0.1.280",
       "manifest": {
         "schemaVersion": 1,
-        "bundleVersion": "2.0.270",
+        "bundleVersion": "2.0.273",
         "stepContractVersion": 3,
         "contractHash": "d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf",
         "managedFiles": [
           {
             "path": "AGENTS.md",
-            "sha256": "3860d21f4a3f9b0c25ca54f7a87762d801f14b82a181b4c0b941c57187908f99"
+            "sha256": "b7dc496d1dcfea176fb5a57e6d17f64abdcff77afeccfcecbbe1790d11da7386"
           },
           {
             "path": "CLAUDE.md",
@@ -756,7 +756,7 @@
           },
           {
             "path": "docs/funnelsgrove/START-HERE.md",
-            "sha256": "ef7525739aa0cd5ea42906fca2ae6ca0327465e6939956f9567e3029148a0bd5"
+            "sha256": "5442274f8ca7ddded834147a693677e203a9c223e1db4260e56bf498ec06a362"
           },
           {
             "path": "docs/funnelsgrove/contracts/analytics-events.md",
@@ -764,7 +764,7 @@
           },
           {
             "path": "docs/funnelsgrove/contracts/content-answers.md",
-            "sha256": "38cd477fa65cb00718c6609ede520bc5b7538f331072c888a6cc32e8d0130d27"
+            "sha256": "efd912eb405e4c64b33becb1cf9a397ba5fe9afc2d4e2aea115a0f5e0703ca87"
           },
           {
             "path": "docs/funnelsgrove/contracts/flow-routing.md",
@@ -780,7 +780,7 @@
           },
           {
             "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-            "sha256": "b15776c8ec0ecbc1f9369ccd56daee4160c533f7b34285cd1c5013db38fd411f"
+            "sha256": "0d5fc0fbb91286906cdfe5edd317ce970cd20b9210cea694d6b5ed630b2f8a3e"
           },
           {
             "path": "docs/funnelsgrove/qa/analytics.md",
@@ -880,22 +880,22 @@
           },
           {
             "path": "funnel-docs.config.json",
-            "sha256": "bdc9354312747f58fa96e201ec2b69b289dfbb21452f33866b3b7d2628490cd6"
+            "sha256": "ca45c7be882af24d09999ab0ee7130645f9bfe4fb56addd2f7966bb31807e610"
           }
         ]
       }
     },
     {
-      "repositoryCliVersion": "0.1.276",
+      "repositoryCliVersion": "0.1.279",
       "manifest": {
         "schemaVersion": 1,
-        "bundleVersion": "2.0.269",
+        "bundleVersion": "2.0.272",
         "stepContractVersion": 3,
         "contractHash": "d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf",
         "managedFiles": [
           {
             "path": "AGENTS.md",
-            "sha256": "3860d21f4a3f9b0c25ca54f7a87762d801f14b82a181b4c0b941c57187908f99"
+            "sha256": "b7dc496d1dcfea176fb5a57e6d17f64abdcff77afeccfcecbbe1790d11da7386"
           },
           {
             "path": "CLAUDE.md",
@@ -903,7 +903,7 @@
           },
           {
             "path": "docs/funnelsgrove/START-HERE.md",
-            "sha256": "ef7525739aa0cd5ea42906fca2ae6ca0327465e6939956f9567e3029148a0bd5"
+            "sha256": "5442274f8ca7ddded834147a693677e203a9c223e1db4260e56bf498ec06a362"
           },
           {
             "path": "docs/funnelsgrove/contracts/analytics-events.md",
@@ -911,7 +911,7 @@
           },
           {
             "path": "docs/funnelsgrove/contracts/content-answers.md",
-            "sha256": "38cd477fa65cb00718c6609ede520bc5b7538f331072c888a6cc32e8d0130d27"
+            "sha256": "efd912eb405e4c64b33becb1cf9a397ba5fe9afc2d4e2aea115a0f5e0703ca87"
           },
           {
             "path": "docs/funnelsgrove/contracts/flow-routing.md",
@@ -927,7 +927,7 @@
           },
           {
             "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-            "sha256": "fbff72ea55bddc1e2e58a66bfbf15677574868bfed25538507d169fd820f0202"
+            "sha256": "038a83e26aa4d24ad4ad6ec78a548cc7a2f2bc84d67adde6e9cc03bc11795a09"
           },
           {
             "path": "docs/funnelsgrove/qa/analytics.md",
@@ -1027,7 +1027,7 @@
           },
           {
             "path": "funnel-docs.config.json",
-            "sha256": "2415311f4118e042c33855343708800e74c9f2433443f61ec4a44325f9a4dbc2"
+            "sha256": "3eacc262001aadac7bdc68e58d69fa8a102ef919cbdd09178f5be90812468747"
           }
         ]
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@funnelsgrove/cli",
-  "version": "0.1.282",
+  "version": "0.1.285",
   "description": "FunnelsGrove command-line tools for editing, syncing, and publishing funnels",
   "repository": {
     "type": "git",
@@ -41,7 +41,7 @@
   },
   "devDependencies": {
     "@funnelsgrove/analytics": "0.12.0",
-    "@funnelsgrove/payments": "0.37.0",
+    "@funnelsgrove/payments": "0.38.0",
     "vitest": "^3.0.0"
   }
 }

package/template_docs/.funnelsgrove-docs.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "bundleVersion": "2.0.275",
+  "bundleVersion": "2.0.278",
   "stepContractVersion": 3,
   "contractHash": "d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf",
   "managedFiles": [
@@ -30,7 +30,7 @@
     },
     {
       "path": "docs/funnelsgrove/contracts/payments.md",
-      "sha256": "67b8a8bbe575019cf8708c1e03f76c6661ce96ca1dc658cafe486256945f6826"
+      "sha256": "993f4bb468db7eb874c81c23464b76260a51c0f9491b563fea6ab9d59dad59ef"
     },
     {
       "path": "docs/funnelsgrove/contracts/step-metadata.md",
@@ -38,7 +38,7 @@
     },
     {
       "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-      "sha256": "291485278a2071a4e73422412e8f81e6ef64bc8b5aa3837b5a9e6dec54501607"
+      "sha256": "ce93e7385a991ba5fd0c5b2d00499f0efc8bc6aabdf67f5288aa0b06648d987b"
     },
     {
       "path": "docs/funnelsgrove/qa/analytics.md",
@@ -138,7 +138,7 @@
     },
     {
       "path": "funnel-docs.config.json",
-      "sha256": "b1ed6276f1565a432a9f48036669b15ed4edfb7c955bf74b312a2b5502f128eb"
+      "sha256": "a8e381a1f92df52dbc9d20bb08b5012991132996848fdf41cc6e14ca12f4d9d1"
     }
   ]
 }

package/template_docs/docs/funnelsgrove/contracts/payments.md

@@ -31,7 +31,8 @@ A paywall presents purchasable plans. A reveal, loading state, calculation, or
 
 - Resolve plans, prices, discounts, currencies, provider IDs, and payment mode from shared configuration.
 - Use `SharedStripeCheckoutV2Dialog` for card checkout. Render one `StripeSubscriptionWalletSurface` per simultaneously visible subscription wallet placement and one `StripeOneTimeWalletSurface` per one-time placement. Never share a checkout hook result between card and wallet surfaces or between two visible wallet placements.
-- Pass `checkoutAnalytics` to every shared dialog and wallet surface. The payments package owns `checkout_started`, `add_payment_info`, and verified `checkout_completed`; do not call the corresponding `publicAnalyticsSdk` methods in funnel components.
+- For an inline paywall form where the device wallet comes first and card second, render one `StripeWalletFirstCheckout` with the card hook's `clientSecret`, `checkoutSessionId` and `stripePromise`. Pass `clientSecret={null}` while the session is being created; the layout stays in place and shows progress. The funnel owns `copy` in its content files.
+- Pass `checkoutAnalytics` to every shared dialog, wallet surface and `StripeWalletFirstCheckout`. The payments package owns `checkout_started`, `add_payment_info`, and verified `checkout_completed`; do not call the corresponding `publicAnalyticsSdk` methods in funnel components.
 - Treat `onSuccess` as the first valid place to call `completeStep` for a purchase flow. Payment-info submission, dialog open, session creation, browser return, and provider-pending state are not lifecycle completion.
 - Use `completeStripeOneClickPayment` for one-click upsells. Do not duplicate the public one-click endpoint, Stripe loader, or `confirmPayment` inside a funnel.
 - Reuse the same event ID when retrying the same logical conversion.

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.30.0`, then `@funnelsgrove/analytics` `0.12.0`, then `@funnelsgrove/payments` `0.37.0`. The production deploy verifies the zero-traffic API candidate, publishes and verifies `@funnelsgrove/cli` `0.1.282`, 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.30.0`, then `@funnelsgrove/analytics` `0.12.0`, then `@funnelsgrove/payments` `0.38.0`. The production deploy verifies the zero-traffic API candidate, publishes and verifies `@funnelsgrove/cli` `0.1.285`, 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.275",
+  "bundleVersion": "2.0.278",
   "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.275",
+  "bundleVersion": "2.0.278",
   "stepContractVersion": 3,
   "contractHash": "d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf",
   "managedFiles": [
@@ -30,7 +30,7 @@
     },
     {
       "path": "docs/funnelsgrove/contracts/payments.md",
-      "sha256": "67b8a8bbe575019cf8708c1e03f76c6661ce96ca1dc658cafe486256945f6826"
+      "sha256": "993f4bb468db7eb874c81c23464b76260a51c0f9491b563fea6ab9d59dad59ef"
     },
     {
       "path": "docs/funnelsgrove/contracts/step-metadata.md",
@@ -38,7 +38,7 @@
     },
     {
       "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-      "sha256": "291485278a2071a4e73422412e8f81e6ef64bc8b5aa3837b5a9e6dec54501607"
+      "sha256": "ce93e7385a991ba5fd0c5b2d00499f0efc8bc6aabdf67f5288aa0b06648d987b"
     },
     {
       "path": "docs/funnelsgrove/qa/analytics.md",
@@ -138,7 +138,7 @@
     },
     {
       "path": "funnel-docs.config.json",
-      "sha256": "b1ed6276f1565a432a9f48036669b15ed4edfb7c955bf74b312a2b5502f128eb"
+      "sha256": "a8e381a1f92df52dbc9d20bb08b5012991132996848fdf41cc6e14ca12f4d9d1"
     }
   ]
 }

package/template_scaffold/.funnelsgrove-scaffold.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
-  "sourceTreeHash": "b695f9d05e91e191e2053228b64bfc7b4d2c1e23b366b4fc9fa5a684ffcbf4a3",
+  "sourceTreeHash": "293874f6b62857411de69514c373e5da0384282ee40dc848260eef605e6db85a",
   "stepContractVersion": 3,
-  "docsBundleVersion": "2.0.275",
+  "docsBundleVersion": "2.0.278",
   "files": [
     {
       "path": ".env.example",
@@ -16,7 +16,7 @@
     },
     {
       "path": ".funnelsgrove-docs.json",
-      "sha256": "3a05839c27f66c2733c0a43d3b9d84ef202ec0c6a6b1dbe7815e69dd02abdcbc",
+      "sha256": "29a119d3014940eafcbefe708be1a03024cf6966c45c68b5760b920a1fdd4a1c",
       "mode": "100644"
     },
     {
@@ -66,7 +66,7 @@
     },
     {
       "path": "docs/funnelsgrove/contracts/payments.md",
-      "sha256": "67b8a8bbe575019cf8708c1e03f76c6661ce96ca1dc658cafe486256945f6826",
+      "sha256": "993f4bb468db7eb874c81c23464b76260a51c0f9491b563fea6ab9d59dad59ef",
       "mode": "100644"
     },
     {
@@ -76,7 +76,7 @@
     },
     {
       "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-      "sha256": "291485278a2071a4e73422412e8f81e6ef64bc8b5aa3837b5a9e6dec54501607",
+      "sha256": "ce93e7385a991ba5fd0c5b2d00499f0efc8bc6aabdf67f5288aa0b06648d987b",
       "mode": "100644"
     },
     {
@@ -206,7 +206,7 @@
     },
     {
       "path": "funnel-docs.config.json",
-      "sha256": "b1ed6276f1565a432a9f48036669b15ed4edfb7c955bf74b312a2b5502f128eb",
+      "sha256": "a8e381a1f92df52dbc9d20bb08b5012991132996848fdf41cc6e14ca12f4d9d1",
       "mode": "100644"
     },
     {
@@ -236,12 +236,12 @@
     },
     {
       "path": "package-lock.json",
-      "sha256": "5d7d31d0f2fde5fdfed166440191ab8891d13460e01c56afa0c8362f35cab7c8",
+      "sha256": "9c7e50ac2812c7c8e4f90aba15daa9c2a4ab35202e174a8a4479df5053de3781",
       "mode": "100644"
     },
     {
       "path": "package.json",
-      "sha256": "f6e66b75994b00ec61a0a9f48825c4c2197d0c0177504397f6faf88fc1a9eb95",
+      "sha256": "2e91d63ef2f5b813e0f59ec31961a8b871c86af3c1576a3fa7267b7a920da198",
       "mode": "100644"
     },
     {

package/template_scaffold/docs/funnelsgrove/contracts/payments.md

@@ -31,7 +31,8 @@ A paywall presents purchasable plans. A reveal, loading state, calculation, or
 
 - Resolve plans, prices, discounts, currencies, provider IDs, and payment mode from shared configuration.
 - Use `SharedStripeCheckoutV2Dialog` for card checkout. Render one `StripeSubscriptionWalletSurface` per simultaneously visible subscription wallet placement and one `StripeOneTimeWalletSurface` per one-time placement. Never share a checkout hook result between card and wallet surfaces or between two visible wallet placements.
-- Pass `checkoutAnalytics` to every shared dialog and wallet surface. The payments package owns `checkout_started`, `add_payment_info`, and verified `checkout_completed`; do not call the corresponding `publicAnalyticsSdk` methods in funnel components.
+- For an inline paywall form where the device wallet comes first and card second, render one `StripeWalletFirstCheckout` with the card hook's `clientSecret`, `checkoutSessionId` and `stripePromise`. Pass `clientSecret={null}` while the session is being created; the layout stays in place and shows progress. The funnel owns `copy` in its content files.
+- Pass `checkoutAnalytics` to every shared dialog, wallet surface and `StripeWalletFirstCheckout`. The payments package owns `checkout_started`, `add_payment_info`, and verified `checkout_completed`; do not call the corresponding `publicAnalyticsSdk` methods in funnel components.
 - Treat `onSuccess` as the first valid place to call `completeStep` for a purchase flow. Payment-info submission, dialog open, session creation, browser return, and provider-pending state are not lifecycle completion.
 - Use `completeStripeOneClickPayment` for one-click upsells. Do not duplicate the public one-click endpoint, Stripe loader, or `confirmPayment` inside a funnel.
 - Reuse the same event ID when retrying the same logical conversion.

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.30.0`, then `@funnelsgrove/analytics` `0.12.0`, then `@funnelsgrove/payments` `0.37.0`. The production deploy verifies the zero-traffic API candidate, publishes and verifies `@funnelsgrove/cli` `0.1.282`, 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.30.0`, then `@funnelsgrove/analytics` `0.12.0`, then `@funnelsgrove/payments` `0.38.0`. The production deploy verifies the zero-traffic API candidate, publishes and verifies `@funnelsgrove/cli` `0.1.285`, 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.275",
+  "bundleVersion": "2.0.278",
   "contractSource": "funnelsgrove-repository://apps/funnel-runtime/contracts/step-contract-v2.json",
   "fullyGenerated": [
     ".funnelsgrove-docs.json",

package/template_scaffold/package-lock.json

@@ -9,7 +9,7 @@
       "version": "0.1.0",
       "dependencies": {
         "@funnelsgrove/analytics": "^0.12.0",
-        "@funnelsgrove/payments": "^0.37.0",
+        "@funnelsgrove/payments": "^0.38.0",
         "@funnelsgrove/runtime": "^0.30.0",
         "@stripe/react-stripe-js": "^5.6.0",
         "@stripe/stripe-js": "^8.7.0",
@@ -948,9 +948,9 @@
       }
     },
     "node_modules/@funnelsgrove/payments": {
-      "version": "0.37.0",
-      "resolved": "https://registry.npmjs.org/@funnelsgrove/payments/-/payments-0.37.0.tgz",
-      "integrity": "sha512-JPVeFQ3ewh0E2I8yl0CgTpZ02xKLKPLBRJabAmJYtvp6EO1zBDhnVbxqNvMlFou26DoU2e5ZqsCBhvgUcV4JjA==",
+      "version": "0.38.0",
+      "resolved": "https://registry.npmjs.org/@funnelsgrove/payments/-/payments-0.38.0.tgz",
+      "integrity": "sha512-zZCNNC5kbsXcOSwko/C8q4nYy0SE8NZ2RWZUAJyXHiOdXUC3urCpMtvG+m2RDPhrmaCZofxgcPfmgAHBDF69Qw==",
       "dependencies": {
         "@solidgate/react-sdk": "1.34.0",
         "@stripe/react-stripe-js": "^5.6.0",

package/template_scaffold/package.json

@@ -13,7 +13,7 @@
   },
   "dependencies": {
     "@funnelsgrove/analytics": "^0.12.0",
-    "@funnelsgrove/payments": "^0.37.0",
+    "@funnelsgrove/payments": "^0.38.0",
     "@funnelsgrove/runtime": "^0.30.0",
     "@stripe/react-stripe-js": "^5.6.0",
     "@stripe/stripe-js": "^8.7.0",