@funnelsgrove/cli 0.1.281 → 0.1.283

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.281",
+      "repositoryCliVersion": "0.1.283",
       "manifest": {
         "schemaVersion": 1,
-        "bundleVersion": "2.0.274",
+        "bundleVersion": "2.0.276",
         "stepContractVersion": 3,
         "contractHash": "d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf",
         "managedFiles": [
@@ -45,7 +45,7 @@
           },
           {
             "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-            "sha256": "3d6d1dc040dc64ba2b0d99d568d161efb621ddfc8e03b79e5fea72eb407cc086"
+            "sha256": "57e1c0b45e30abe00ae6a1809d8dd4bd2589d4fe74ec21772c186860f13d48ef"
           },
           {
             "path": "docs/funnelsgrove/qa/analytics.md",
@@ -145,16 +145,16 @@
           },
           {
             "path": "funnel-docs.config.json",
-            "sha256": "9f2c2f20da1c0e9cc714a563041e01a3bd80d416a3965be6237c6036a6ab1f4d"
+            "sha256": "32f6697d21d89786ee7ef42d9baa86ddfa7b50fbd8726f781708050e2c2085bc"
           }
         ]
       }
     },
     {
-      "repositoryCliVersion": "0.1.280",
+      "repositoryCliVersion": "0.1.282",
       "manifest": {
         "schemaVersion": 1,
-        "bundleVersion": "2.0.273",
+        "bundleVersion": "2.0.275",
         "stepContractVersion": 3,
         "contractHash": "d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf",
         "managedFiles": [
@@ -192,7 +192,7 @@
           },
           {
             "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-            "sha256": "0d5fc0fbb91286906cdfe5edd317ce970cd20b9210cea694d6b5ed630b2f8a3e"
+            "sha256": "291485278a2071a4e73422412e8f81e6ef64bc8b5aa3837b5a9e6dec54501607"
           },
           {
             "path": "docs/funnelsgrove/qa/analytics.md",
@@ -292,16 +292,16 @@
           },
           {
             "path": "funnel-docs.config.json",
-            "sha256": "ca45c7be882af24d09999ab0ee7130645f9bfe4fb56addd2f7966bb31807e610"
+            "sha256": "b1ed6276f1565a432a9f48036669b15ed4edfb7c955bf74b312a2b5502f128eb"
           }
         ]
       }
     },
     {
-      "repositoryCliVersion": "0.1.279",
+      "repositoryCliVersion": "0.1.281",
       "manifest": {
         "schemaVersion": 1,
-        "bundleVersion": "2.0.272",
+        "bundleVersion": "2.0.274",
         "stepContractVersion": 3,
         "contractHash": "d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf",
         "managedFiles": [
@@ -339,7 +339,7 @@
           },
           {
             "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-            "sha256": "038a83e26aa4d24ad4ad6ec78a548cc7a2f2bc84d67adde6e9cc03bc11795a09"
+            "sha256": "3d6d1dc040dc64ba2b0d99d568d161efb621ddfc8e03b79e5fea72eb407cc086"
           },
           {
             "path": "docs/funnelsgrove/qa/analytics.md",
@@ -439,22 +439,22 @@
           },
           {
             "path": "funnel-docs.config.json",
-            "sha256": "3eacc262001aadac7bdc68e58d69fa8a102ef919cbdd09178f5be90812468747"
+            "sha256": "9f2c2f20da1c0e9cc714a563041e01a3bd80d416a3965be6237c6036a6ab1f4d"
           }
         ]
       }
     },
     {
-      "repositoryCliVersion": "0.1.278",
+      "repositoryCliVersion": "0.1.280",
       "manifest": {
         "schemaVersion": 1,
-        "bundleVersion": "2.0.271",
+        "bundleVersion": "2.0.273",
         "stepContractVersion": 3,
         "contractHash": "d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf",
         "managedFiles": [
           {
             "path": "AGENTS.md",
-            "sha256": "3860d21f4a3f9b0c25ca54f7a87762d801f14b82a181b4c0b941c57187908f99"
+            "sha256": "b7dc496d1dcfea176fb5a57e6d17f64abdcff77afeccfcecbbe1790d11da7386"
           },
           {
             "path": "CLAUDE.md",
@@ -462,7 +462,7 @@
           },
           {
             "path": "docs/funnelsgrove/START-HERE.md",
-            "sha256": "ef7525739aa0cd5ea42906fca2ae6ca0327465e6939956f9567e3029148a0bd5"
+            "sha256": "5442274f8ca7ddded834147a693677e203a9c223e1db4260e56bf498ec06a362"
           },
           {
             "path": "docs/funnelsgrove/contracts/analytics-events.md",
@@ -470,7 +470,7 @@
           },
           {
             "path": "docs/funnelsgrove/contracts/content-answers.md",
-            "sha256": "38cd477fa65cb00718c6609ede520bc5b7538f331072c888a6cc32e8d0130d27"
+            "sha256": "efd912eb405e4c64b33becb1cf9a397ba5fe9afc2d4e2aea115a0f5e0703ca87"
           },
           {
             "path": "docs/funnelsgrove/contracts/flow-routing.md",
@@ -486,7 +486,7 @@
           },
           {
             "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-            "sha256": "012ef8788fdb0b5f7b8acc283ee9d0c3c9e23f68d944327ed8c2d9378de94585"
+            "sha256": "0d5fc0fbb91286906cdfe5edd317ce970cd20b9210cea694d6b5ed630b2f8a3e"
           },
           {
             "path": "docs/funnelsgrove/qa/analytics.md",
@@ -586,22 +586,22 @@
           },
           {
             "path": "funnel-docs.config.json",
-            "sha256": "580a792c8650972c8016c0052bec88f7a5331445a8a039bb35912c2da4c645a0"
+            "sha256": "ca45c7be882af24d09999ab0ee7130645f9bfe4fb56addd2f7966bb31807e610"
           }
         ]
       }
     },
     {
-      "repositoryCliVersion": "0.1.277",
+      "repositoryCliVersion": "0.1.279",
       "manifest": {
         "schemaVersion": 1,
-        "bundleVersion": "2.0.270",
+        "bundleVersion": "2.0.272",
         "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": "b15776c8ec0ecbc1f9369ccd56daee4160c533f7b34285cd1c5013db38fd411f"
+            "sha256": "038a83e26aa4d24ad4ad6ec78a548cc7a2f2bc84d67adde6e9cc03bc11795a09"
           },
           {
             "path": "docs/funnelsgrove/qa/analytics.md",
@@ -733,16 +733,16 @@
           },
           {
             "path": "funnel-docs.config.json",
-            "sha256": "bdc9354312747f58fa96e201ec2b69b289dfbb21452f33866b3b7d2628490cd6"
+            "sha256": "3eacc262001aadac7bdc68e58d69fa8a102ef919cbdd09178f5be90812468747"
           }
         ]
       }
     },
     {
-      "repositoryCliVersion": "0.1.276",
+      "repositoryCliVersion": "0.1.278",
       "manifest": {
         "schemaVersion": 1,
-        "bundleVersion": "2.0.269",
+        "bundleVersion": "2.0.271",
         "stepContractVersion": 3,
         "contractHash": "d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf",
         "managedFiles": [
@@ -780,7 +780,7 @@
           },
           {
             "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-            "sha256": "fbff72ea55bddc1e2e58a66bfbf15677574868bfed25538507d169fd820f0202"
+            "sha256": "012ef8788fdb0b5f7b8acc283ee9d0c3c9e23f68d944327ed8c2d9378de94585"
           },
           {
             "path": "docs/funnelsgrove/qa/analytics.md",
@@ -880,16 +880,16 @@
           },
           {
             "path": "funnel-docs.config.json",
-            "sha256": "2415311f4118e042c33855343708800e74c9f2433443f61ec4a44325f9a4dbc2"
+            "sha256": "580a792c8650972c8016c0052bec88f7a5331445a8a039bb35912c2da4c645a0"
           }
         ]
       }
     },
     {
-      "repositoryCliVersion": "0.1.275",
+      "repositoryCliVersion": "0.1.277",
       "manifest": {
         "schemaVersion": 1,
-        "bundleVersion": "2.0.268",
+        "bundleVersion": "2.0.270",
         "stepContractVersion": 3,
         "contractHash": "d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf",
         "managedFiles": [
@@ -927,7 +927,7 @@
           },
           {
             "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-            "sha256": "63b9bffafc0e408b769ce39764c84a45f55218e890782496f6b6aceed18e1569"
+            "sha256": "b15776c8ec0ecbc1f9369ccd56daee4160c533f7b34285cd1c5013db38fd411f"
           },
           {
             "path": "docs/funnelsgrove/qa/analytics.md",
@@ -1027,7 +1027,7 @@
           },
           {
             "path": "funnel-docs.config.json",
-            "sha256": "1fcfbd34138904d3ef4213e7950e2c1b124289d1a95fb42c29075ca7512db676"
+            "sha256": "bdc9354312747f58fa96e201ec2b69b289dfbb21452f33866b3b7d2628490cd6"
           }
         ]
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@funnelsgrove/cli",
-  "version": "0.1.281",
+  "version": "0.1.283",
   "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.274",
+  "bundleVersion": "2.0.276",
   "stepContractVersion": 3,
   "contractHash": "d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf",
   "managedFiles": [
@@ -38,7 +38,7 @@
     },
     {
       "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-      "sha256": "3d6d1dc040dc64ba2b0d99d568d161efb621ddfc8e03b79e5fea72eb407cc086"
+      "sha256": "57e1c0b45e30abe00ae6a1809d8dd4bd2589d4fe74ec21772c186860f13d48ef"
     },
     {
       "path": "docs/funnelsgrove/qa/analytics.md",
@@ -138,7 +138,7 @@
     },
     {
       "path": "funnel-docs.config.json",
-      "sha256": "9f2c2f20da1c0e9cc714a563041e01a3bd80d416a3965be6237c6036a6ab1f4d"
+      "sha256": "32f6697d21d89786ee7ef42d9baa86ddfa7b50fbd8726f781708050e2c2085bc"
     }
   ]
 }

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.281`, 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.37.0`. The production deploy verifies the zero-traffic API candidate, publishes and verifies `@funnelsgrove/cli` `0.1.283`, 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.274",
+  "bundleVersion": "2.0.276",
   "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.274",
+  "bundleVersion": "2.0.276",
   "stepContractVersion": 3,
   "contractHash": "d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf",
   "managedFiles": [
@@ -38,7 +38,7 @@
     },
     {
       "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-      "sha256": "3d6d1dc040dc64ba2b0d99d568d161efb621ddfc8e03b79e5fea72eb407cc086"
+      "sha256": "57e1c0b45e30abe00ae6a1809d8dd4bd2589d4fe74ec21772c186860f13d48ef"
     },
     {
       "path": "docs/funnelsgrove/qa/analytics.md",
@@ -138,7 +138,7 @@
     },
     {
       "path": "funnel-docs.config.json",
-      "sha256": "9f2c2f20da1c0e9cc714a563041e01a3bd80d416a3965be6237c6036a6ab1f4d"
+      "sha256": "32f6697d21d89786ee7ef42d9baa86ddfa7b50fbd8726f781708050e2c2085bc"
     }
   ]
 }

package/template_scaffold/.funnelsgrove-scaffold.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
-  "sourceTreeHash": "bae1fcbf1c3de232b11630821c7d06db629c3b58b850657746029e69b8b66bf7",
+  "sourceTreeHash": "f1a57f68ef0db46b56cab67f945cbff7056769e722cfc4a0f322ddfe03d434d2",
   "stepContractVersion": 3,
-  "docsBundleVersion": "2.0.274",
+  "docsBundleVersion": "2.0.276",
   "files": [
     {
       "path": ".env.example",
@@ -16,7 +16,7 @@
     },
     {
       "path": ".funnelsgrove-docs.json",
-      "sha256": "77a5ba3f7f89c781d812a8cecbd0e3142b9d5ba8c57fa5bb2017a1578e8ae865",
+      "sha256": "f2893f6ea08ac5831b616e0f1f6a11fb56d17c9c23984be827175ebd7e2ee862",
       "mode": "100644"
     },
     {
@@ -76,7 +76,7 @@
     },
     {
       "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-      "sha256": "3d6d1dc040dc64ba2b0d99d568d161efb621ddfc8e03b79e5fea72eb407cc086",
+      "sha256": "57e1c0b45e30abe00ae6a1809d8dd4bd2589d4fe74ec21772c186860f13d48ef",
       "mode": "100644"
     },
     {
@@ -206,7 +206,7 @@
     },
     {
       "path": "funnel-docs.config.json",
-      "sha256": "9f2c2f20da1c0e9cc714a563041e01a3bd80d416a3965be6237c6036a6ab1f4d",
+      "sha256": "32f6697d21d89786ee7ef42d9baa86ddfa7b50fbd8726f781708050e2c2085bc",
       "mode": "100644"
     },
     {
@@ -216,7 +216,7 @@
     },
     {
       "path": "funnel.runtime-capabilities.json",
-      "sha256": "3d74683170fced7afa9badfdf837706aac9c3d554690708b3ba31b009028a069",
+      "sha256": "50024a9d997506468094a938db5b34ed8d4c6d27e44de76b3417363c51b2c042",
       "mode": "100644"
     },
     {
@@ -551,7 +551,7 @@
     },
     {
       "path": "src/steps/step-32-paywall.tsx",
-      "sha256": "43789583e91269b5427dbe5a054aafbe7cafac2a40d9a26f1c9414f1ae458b5c",
+      "sha256": "8a2903926e6476eef4901b240f7b6d054eb782292d72e84b1a11dcda65b200c4",
       "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.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.281`, 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.37.0`. The production deploy verifies the zero-traffic API candidate, publishes and verifies `@funnelsgrove/cli` `0.1.283`, 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.274",
+  "bundleVersion": "2.0.276",
   "contractSource": "funnelsgrove-repository://apps/funnel-runtime/contracts/step-contract-v2.json",
   "fullyGenerated": [
     ".funnelsgrove-docs.json",

package/template_scaffold/funnel.runtime-capabilities.json

@@ -1,4 +1,5 @@
 {
   "moneyContractVersion": 1,
-  "localeContractVersion": 1
+  "localeContractVersion": 1,
+  "paypalCheckoutVersion": 1
 }

package/template_scaffold/src/steps/step-32-paywall.tsx

@@ -33,6 +33,9 @@ import { getPathForStep } from '@/runtime/funnel-runtime';
 import {
   SharedCheckoutSpecialOfferDialog,
   SolidgateCheckoutDialog,
+  PayPalCheckout,
+  PayPalCheckoutDialog,
+  readPendingPayPalCheckout,
   SharedStripeCheckoutV2Dialog,
   StripeSubscriptionWalletSurface,
   activateSecondPaywallDiscount,
@@ -140,7 +143,7 @@ function StepPaywallRuntime({
 }: StepPaywallProps = {}) {
   const [runtimeMode] = useRuntimeMode();
   const checkoutMode = runtimeMode;
-  const { user, setUser, attributes, featureFlags, completeStep, userBootstrapped } = useFunnel();
+  const { user, setUser, attributes, featureFlags, completeStep, goNext, userBootstrapped } = useFunnel();
   const publishedRuntime = useFunnelRuntimeConfig();
   const browserLocale = useBrowserOfferLocale();
   const content = usePreviewStepLocalizedContent(
@@ -179,7 +182,7 @@ function StepPaywallRuntime({
     activeBillingRuntime.sourceVersionId,
   ]);
   const activeBillingDiscounts = useMemo(
-    () => activeBillingRuntime.discounts ?? (
+    () => activeBillingRuntime.provider === 'paypal' ? inactiveBillingDiscounts : activeBillingRuntime.discounts ?? (
       activeBillingRuntime.provider === 'stripe'
         ? buildBillingDiscountCatalog(billingDiscountList)
         : inactiveBillingDiscounts
@@ -217,10 +220,16 @@ function StepPaywallRuntime({
       null,
     [activeBillingRuntime.defaultPlanKey, availablePlans],
   );
-  const [selectedPlanId, setSelectedPlanId] = useState<string | null>(
+  const [requestedPlanId, setSelectedPlanId] = useState<string | null>(
     initialPlanId,
   );
-  const [checkoutDialogOpen, setCheckoutDialogOpen] = useState(false);
+  const pendingPayPal = readPendingPayPalCheckout({ environment: checkoutMode, funnelEndUserId: user.id, runtimeConfig: activeCheckoutRuntimeConfig });
+  const hasPendingPayPal = Boolean(pendingPayPal);
+  const selectedPlanId = pendingPayPal
+    ? availablePlans.find(plan => plan.funnelPlanKey === pendingPayPal.funnelPlanKey)?.id ?? null
+    : requestedPlanId;
+  const [checkoutDialogOpen, setCheckoutDialogOpen] = useState(Boolean(pendingPayPal));
+  const [paypalPending, setPayPalPending] = useState(false);
   const [solidgateAttemptKey, setSolidgateAttemptKey] = useState<string | null>(null);
   const [specialOfferDialogOpen, setSpecialOfferDialogOpen] = useState(() => {
     if (typeof window === 'undefined') {
@@ -287,6 +296,7 @@ function StepPaywallRuntime({
   const checkoutSummaryLabel =
     selectedDisplayPlan?.checkoutSummaryLabel?.trim() || selectedDisplayPlan?.title || content.selectedPlanLabel;
   const checkoutProvider = activeBillingRuntime.provider;
+  const paypalOption = pendingPayPal?.option || (selectedPlan?.funnelPlanKey ? activeBillingRuntime.paypalOptionsByPlanKey?.[selectedPlan.funnelPlanKey] : null);
   const storyOptions = useMemo<readonly StoryOption[]>(
     () =>
       content.stories.items.map((item, index) => ({
@@ -390,7 +400,7 @@ function StepPaywallRuntime({
     }
     successUrl.searchParams.set(
       'source',
-      checkoutProvider === 'solidgate' ? 'solidgate' : 'stripe-elements',
+      checkoutProvider === 'stripe' ? 'stripe-elements' : checkoutProvider,
     );
 
     return successUrl.toString();
@@ -483,10 +493,10 @@ function StepPaywallRuntime({
     && activeBillingRuntime.offerSetId.trim()
     && selectedPlan?.funnelPlanKey?.trim(),
   );
-  const checkoutDisabled = !checkoutSelectionReady || !userBootstrapped || !selectedPlan || !selectedDisplayPlan || (
+  const checkoutDisabled = Boolean(pendingPayPal) || paypalPending || !checkoutSelectionReady || !userBootstrapped || !selectedPlan || !selectedDisplayPlan || (
     checkoutProvider === 'solidgate'
       ? !solidgateCheckoutConfigured
-      : !checkoutSession.configured
+      : checkoutProvider === 'paypal' ? !paypalOption : !checkoutSession.configured
   );
   const checkoutDialogReady =
     checkoutProvider === 'stripe' &&
@@ -539,10 +549,10 @@ function StepPaywallRuntime({
   }, [user.email]);
 
   useEffect(() => {
-    setCheckoutDialogOpen(false);
+    setCheckoutDialogOpen(hasPendingPayPal);
     setSolidgateAttemptKey(null);
     setError(null);
-  }, [selectedPlanId]);
+  }, [selectedPlanId, hasPendingPayPal]);
 
   useEffect(() => {
     if (
@@ -633,6 +643,7 @@ function StepPaywallRuntime({
     paywallWalletMethodWrapperClassNames[method];
 
   const startCheckout = async () => {
+    if (pendingPayPal || paypalPending) { setCheckoutDialogOpen(true); return; }
     if (checkoutDisabled) {
       return;
     }
@@ -642,6 +653,8 @@ function StepPaywallRuntime({
       return;
     }
 
+    if (checkoutProvider === 'paypal') { setCheckoutDialogOpen(true); return; }
+
     if (checkoutProvider === 'solidgate') {
       setSolidgateAttemptKey(crypto.randomUUID());
       setCheckoutDialogOpen(true);
@@ -684,6 +697,7 @@ function StepPaywallRuntime({
   };
 
   const openCardCheckoutFromUnavailableWallet = async () => {
+    if (pendingPayPal || paypalPending) { setCheckoutDialogOpen(true); return; }
     if (checkoutDisabled) {
       return;
     }
@@ -754,6 +768,27 @@ function StepPaywallRuntime({
     setCheckoutEmailPromptError(null);
   };
 
+  const paypalCheckout = (checkoutSelectionReady || pendingPayPal) && userBootstrapped && paypalOption && (selectedPlan?.funnelPlanKey || pendingPayPal) ? (
+    <PayPalCheckout
+      key={`${paypalOption.paymentProfileId}:${paypalOption.providerPlanId}:${checkoutMode}:${pendingPayPal?.funnelPlanKey || selectedPlan?.funnelPlanKey}`}
+      option={paypalOption}
+      environment={checkoutMode}
+      funnelEndUserId={user.id}
+      offerSetId={pendingPayPal?.offerSetId || activeBillingRuntime.offerSetId}
+      funnelPlanKey={pendingPayPal?.funnelPlanKey || selectedPlan?.funnelPlanKey || ''}
+      runtimeConfig={activeCheckoutRuntimeConfig}
+      onPreparationStart={billingSelection.pin}
+      onPendingChange={pending => {
+        setPayPalPending(pending);
+        if (!pending) billingSelection.reset();
+      }}
+      onSuccess={() => {
+        completeStep(analyticsStepId, { planId: selectedDisplayPlan?.id ?? pendingPayPal?.funnelPlanKey });
+        goNext();
+      }}
+    />
+  ) : undefined;
+
   const closeCheckoutDialog = () => {
     if (checkoutProvider === 'stripe') checkoutSession.reset();
     else billingSelection.reset();
@@ -903,6 +938,11 @@ function StepPaywallRuntime({
         />
       ) : null}
 
+      {checkoutDialogOpen && paypalCheckout && (checkoutProvider === 'paypal' || !checkoutSession.activeClientSecret) ? (
+        <PayPalCheckoutDialog title={content.checkout.title} closeAriaLabel={content.checkout.closeAriaLabel}
+          onClose={() => setCheckoutDialogOpen(false)}>{paypalCheckout}</PayPalCheckoutDialog>
+      ) : null}
+
       {checkoutDialogOpen &&
       checkoutProvider === 'stripe' &&
       checkoutSession.activeClientSecret &&
@@ -933,6 +973,8 @@ function StepPaywallRuntime({
           onError={checkoutSession.setError}
           onSuccess={handleCheckoutCompleted}
           paymentMethodLabels={content.checkout.paymentMethodLabels}
+          paypalCheckout={paypalCheckout}
+          paypalPending={paypalPending || Boolean(pendingPayPal)}
           paypalButtonLabel={content.checkout.paypalButtonLabel}
           paypalLabel={content.checkout.paypalLabel}
           promoActive={checkoutPromoActive}
@@ -1099,6 +1141,7 @@ function StepPaywallRuntime({
               ]
                 .filter(Boolean)
                 .join(' ')}
+              disabled={paypalPending || Boolean(pendingPayPal)}
               onClick={() => setSelectedPlanId(plan.id)}
             >
               {plan.featuredTag ? <span className='paywall-v2-plan-tag'>{plan.featuredTag}</span> : null}
@@ -1169,12 +1212,17 @@ function StepPaywallRuntime({
             type='button'
             className='paywall-v2-card-button paywall-v2-vibe-cta'
             onClick={() => void startCheckout()}
-            disabled={checkoutDisabled}
+            disabled={checkoutDisabled && !pendingPayPal && !paypalPending}
           >
             {content.plans.cardButtonLabel}
           </button>
-          <p className='paywall-v2-alt-meta'>{content.plans.metaLabels.join(' · ')}</p>
+          {checkoutProvider !== 'paypal' && !pendingPayPal ? (
+            <div aria-label='Card and wallet billing terms'>
+              {paypalOption ? <p className='paywall-v2-alt-meta'>Card and wallet terms</p> : null}
           <PaywallRenewalDisclaimer plan={selectedPlan} hasActiveDiscount={Boolean(activeCouponId)} copy={content.checkout} catalogLabels={content.catalogLabels} />
+            </div>
+          ) : null}
+          <p className='paywall-v2-alt-meta'>{content.plans.metaLabels.join(' · ')}</p>
           <p className='paywall-v2-support'>
             {content.checkout.supportText}{' '}
             <a href={`mailto:${supportEmail}`}>{supportEmail}</a>