@funnelsgrove/cli 0.1.78 → 0.1.86

package/dist/cli.js

@@ -15,7 +15,7 @@ import { buildCommittedSyncManifest, buildDownloadedSyncManifest, buildSourceCan
 import { mergeTextSourceWithGit } from './sourceRebase.js';
 import { executeExperimentCreate, formatExperimentCreateSuccess, recoverExperimentCreateTransaction, } from './experimentCreate.js';
 import { pullEnvFile } from './envSync.js';
-import { executeEmailPull, executeEmailPush, executeEmailSequencePublish, executeEmailTemplatePublish, executeEmailValidate, } from './emailCommands.js';
+import { executeEmailPull, executeEmailPush, executeEmailSend, executeEmailSequenceAddStep, executeEmailSequenceCreate, executeEmailSequencePublish, executeEmailSequenceSetActive, executeEmailTemplatePublish, executeEmailValidate, parseEmailVariablesJson, } from './emailCommands.js';
 import { formatGitHubConnectRows, formatGitHubJobRows, formatGitHubStatusRows, } from './githubOutput.js';
 import { GitHubSyncTimeoutError, syncGitHubDraftIfConnected, } from './githubSyncFlow.js';
 import { reskinFunnel } from './reskin.js';
@@ -1707,8 +1707,41 @@ const emailCommand = addExamples(program.command('email').description('Manage pr
     'fgrove email pull',
     'fgrove email validate',
     'fgrove email push',
+    'fgrove email send --template welcome --to delivered@example.com',
     'fgrove email template publish welcome',
 ]);
+emailCommand
+    .command('send')
+    .description('Send a published email template with a private project token')
+    .requiredOption('--template <slug>', 'Published email template slug')
+    .requiredOption('--to <email>', 'Recipient email address')
+    .option('--variables <json>', 'Template variables as a JSON object', '{}')
+    .option('--idempotency-key <key>', 'Stable key used to deduplicate retries')
+    .option('--api-url <url>', 'Emails SDK API URL', process.env.FUNNELSGROVE_EMAILS_API_URL || 'https://sdk-api.funnelsgrove.com')
+    .option('--private-token <token>', 'Private project token (defaults to FUNNELSGROVE_PRIVATE_TOKEN)', process.env.FUNNELSGROVE_PRIVATE_TOKEN)
+    .option('--no-wait', 'Return after the email is queued')
+    .option('--timeout-seconds <seconds>', 'Maximum time to wait for delivery', '120')
+    .action(async (options) => {
+    const timeoutSeconds = Number(options.timeoutSeconds);
+    if (!Number.isInteger(timeoutSeconds) || timeoutSeconds <= 0) {
+        throw new Error('--timeout-seconds must be a positive integer.');
+    }
+    const result = await executeEmailSend({
+        apiUrl: options.apiUrl,
+        privateToken: options.privateToken || '',
+        template: options.template,
+        to: options.to,
+        variables: parseEmailVariablesJson(options.variables),
+        idempotencyKey: options.idempotencyKey,
+        wait: options.wait,
+        timeoutMs: timeoutSeconds * 1_000,
+        pollIntervalMs: 2_000,
+    });
+    console.log(JSON.stringify(result, null, 2));
+    if (result.status === 'failed' || result.status === 'unknown') {
+        throw new Error(`Email delivery ${result.id} finished with status ${result.status}.`);
+    }
+});
 addEmailScopeOptions(emailCommand
     .command('pull')
     .description('Pull project email drafts into local files'))
@@ -1752,6 +1785,63 @@ addEmailScopeOptions(emailTemplateCommand
     console.log(`Published email template ${slug}.`);
 });
 const emailSequenceCommand = emailCommand.command('sequence').description('Manage email sequences');
+const parseEmailSequenceDelay = (options) => {
+    const hasHours = options.delayHours !== undefined;
+    const hasDays = options.delayDays !== undefined;
+    if (hasHours === hasDays)
+        throw new Error('Provide exactly one of --delay-hours or --delay-days.');
+    const value = Number(hasHours ? options.delayHours : options.delayDays);
+    if (!Number.isInteger(value) || value < 0)
+        throw new Error('Delay must be a non-negative integer.');
+    return value * (hasDays ? 86_400 : 3_600);
+};
+addEmailScopeOptions(emailSequenceCommand
+    .command('create <slug>')
+    .description('Create a local email sequence with its first published-template step')
+    .requiredOption('--name <name>', 'Sequence display name')
+    .requiredOption('--template <slug>', 'Published email template slug')
+    .requiredOption('--key <key>', 'Unique first-step key')
+    .option('--trigger <event>', 'Trigger event: email_captured, purchase_completed, or registration_completed', 'email_captured')
+    .option('--funnel-id <uuid>', 'Limit the sequence to one project funnel')
+    .option('--all-funnels', 'Apply the sequence to every funnel in the project')
+    .option('--delay-hours <hours>', 'First-step delay in hours')
+    .option('--delay-days <days>', 'First-step delay in days'))
+    .action(async (slug, options) => {
+    if (Boolean(options.funnelId) === Boolean(options.allFunnels)) {
+        throw new Error('Provide exactly one of --funnel-id or --all-funnels.');
+    }
+    if (!['email_captured', 'purchase_completed', 'registration_completed'].includes(options.trigger)) {
+        throw new Error('--trigger must be email_captured, purchase_completed, or registration_completed.');
+    }
+    await executeEmailSequenceCreate({
+        ...await resolveEmailCommandScope(options),
+        slug,
+        name: options.name,
+        triggerEventType: options.trigger,
+        funnelId: options.funnelId || null,
+        firstStepKey: options.key,
+        templateSlug: options.template,
+        delaySeconds: parseEmailSequenceDelay(options),
+    });
+    console.log(`Created local email sequence ${slug}.`);
+});
+addEmailScopeOptions(emailSequenceCommand
+    .command('add-step <slug>')
+    .description('Add a published-template step to a local email sequence')
+    .requiredOption('--key <key>', 'Unique step key')
+    .requiredOption('--template <slug>', 'Published email template slug')
+    .option('--delay-hours <hours>', 'Delay after the previous step in hours')
+    .option('--delay-days <days>', 'Delay after the previous step in days'))
+    .action(async (slug, options) => {
+    await executeEmailSequenceAddStep({
+        ...await resolveEmailCommandScope(options),
+        slug,
+        key: options.key,
+        templateSlug: options.template,
+        delaySeconds: parseEmailSequenceDelay(options),
+    });
+    console.log(`Added email sequence step ${options.key} to ${slug}.`);
+});
 addEmailScopeOptions(emailSequenceCommand
     .command('publish <slug>')
     .description('Publish one email sequence explicitly'))
@@ -1762,6 +1852,20 @@ addEmailScopeOptions(emailSequenceCommand
     });
     console.log(`Published email sequence ${slug}.`);
 });
+for (const active of [true, false]) {
+    const action = active ? 'enable' : 'disable';
+    addEmailScopeOptions(emailSequenceCommand
+        .command(`${action} <slug>`)
+        .description(`${active ? 'Enable' : 'Disable'} one published email sequence`))
+        .action(async (slug, options) => {
+        await executeEmailSequenceSetActive({
+            ...await resolveEmailCommandScope(options),
+            slug,
+            active,
+        });
+        console.log(`${active ? 'Enabled' : 'Disabled'} email sequence ${slug}.`);
+    });
+}
 const projectsCommand = addExamples(program.command('projects').description('Manage projects'), [
     'fgrove projects list',
     'fgrove projects list --workspace acme',

package/dist/emailCommands.d.ts

@@ -1,4 +1,4 @@
-import { type EmailFilesResult } from './emailFiles.js';
+import { type EmailFilesResult, type EmailEventType } from './emailFiles.js';
 export type EmailCallApi = <T>(input: {
     path: string;
     type: 'query' | 'mutation';
@@ -12,6 +12,32 @@ type EmailCommandScope = {
     projectId: string;
     sourceDir: string;
 };
+export type EmailSendStatus = {
+    id: string;
+    status: 'queued' | 'sent' | 'failed' | 'unknown';
+    terminalReason?: string | null;
+    createdAt?: string;
+    updatedAt?: string;
+    sentAt?: string | null;
+    failedAt?: string | null;
+};
+type EmailSendFetch = typeof globalThis.fetch;
+export declare const parseEmailVariablesJson: (value: string) => Record<string, string | number | boolean>;
+export declare function executeEmailSend(input: {
+    apiUrl: string;
+    privateToken: string;
+    template: string;
+    to: string;
+    variables: Record<string, string | number | boolean>;
+    idempotencyKey?: string;
+    wait: boolean;
+    timeoutMs: number;
+    pollIntervalMs: number;
+}, dependencies?: {
+    fetchImpl?: EmailSendFetch;
+    sleep?: (durationMs: number) => Promise<void>;
+    now?: () => number;
+}): Promise<EmailSendStatus>;
 export declare function executeEmailPull(scope: EmailCommandScope): Promise<{
     templates: number;
     sequences: number;
@@ -23,6 +49,25 @@ export declare function executeEmailPush(scope: EmailCommandScope): Promise<{
     templates: number;
     sequences: number;
 }>;
+export declare function executeEmailSequenceAddStep(input: EmailCommandScope & {
+    slug: string;
+    key: string;
+    templateSlug: string;
+    delaySeconds: number;
+}): Promise<void>;
+export declare function executeEmailSequenceCreate(input: EmailCommandScope & {
+    slug: string;
+    name: string;
+    triggerEventType: EmailEventType;
+    funnelId: string | null;
+    firstStepKey: string;
+    templateSlug: string;
+    delaySeconds: number;
+}): Promise<void>;
+export declare function executeEmailSequenceSetActive(input: EmailCommandScope & {
+    slug: string;
+    active: boolean;
+}): Promise<void>;
 export declare function executeEmailTemplatePublish(scope: EmailCommandScope & {
     slug: string;
 }): Promise<unknown>;

package/dist/emailCommands.js

@@ -1,6 +1,89 @@
+import { randomUUID } from 'node:crypto';
 import { readEmailFiles, replaceEmailFiles, writeEmailFiles, writeEmailSequenceFile, writeEmailTemplateFile, } from './emailFiles.js';
 const isRecord = (value) => (typeof value === 'object' && value !== null && !Array.isArray(value));
 const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const STEP_KEY = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const TERMINAL_EMAIL_STATUSES = new Set(['sent', 'failed', 'unknown']);
+export const parseEmailVariablesJson = (value) => {
+    let parsed;
+    try {
+        parsed = JSON.parse(value);
+    }
+    catch {
+        throw new Error('--variables must be a JSON object.');
+    }
+    if (!isRecord(parsed))
+        throw new Error('--variables must be a JSON object.');
+    if (Object.values(parsed).some((item) => (typeof item !== 'string'
+        && typeof item !== 'number'
+        && typeof item !== 'boolean'))) {
+        throw new Error('--variables must contain only string, number, or boolean values.');
+    }
+    return parsed;
+};
+const emailApiRequest = async (input) => {
+    const response = await input.fetchImpl(`${input.apiUrl.replace(/\/+$/, '')}${input.path}`, {
+        method: input.method || 'GET',
+        headers: {
+            authorization: `Bearer ${input.privateToken}`,
+            accept: 'application/json',
+            ...(input.body ? { 'content-type': 'application/json' } : {}),
+            ...(input.idempotencyKey ? { 'idempotency-key': input.idempotencyKey } : {}),
+        },
+        ...(input.body ? { body: JSON.stringify(input.body) } : {}),
+    });
+    const body = await response.json().catch(() => ({}));
+    if (!response.ok) {
+        const message = isRecord(body) && typeof body.error === 'string'
+            ? body.error
+            : 'Email API request failed';
+        throw new Error(`${message} (HTTP ${response.status})`);
+    }
+    if (!isRecord(body))
+        throw new Error('Email API returned an invalid response.');
+    return body;
+};
+const parseEmailSendStatus = (value) => {
+    if (typeof value.id !== 'string'
+        || !UUID.test(value.id)
+        || !['queued', 'sent', 'failed', 'unknown'].includes(String(value.status))) {
+        throw new Error('Email API returned an invalid delivery status.');
+    }
+    return value;
+};
+export async function executeEmailSend(input, dependencies = {}) {
+    if (!input.privateToken.trim())
+        throw new Error('A private project token is required.');
+    const fetchImpl = dependencies.fetchImpl || fetch;
+    const sleep = dependencies.sleep || ((durationMs) => new Promise((resolve) => {
+        setTimeout(resolve, durationMs);
+    }));
+    const now = dependencies.now || Date.now;
+    const receipt = parseEmailSendStatus(await emailApiRequest({
+        apiUrl: input.apiUrl,
+        privateToken: input.privateToken,
+        path: '/sdk/private/emails/send',
+        method: 'POST',
+        idempotencyKey: input.idempotencyKey || `email-cli:${randomUUID()}`,
+        body: { template: input.template, to: input.to, variables: input.variables },
+        fetchImpl,
+    }));
+    if (!input.wait || TERMINAL_EMAIL_STATUSES.has(receipt.status))
+        return receipt;
+    const deadline = now() + input.timeoutMs;
+    while (now() < deadline) {
+        await sleep(Math.min(input.pollIntervalMs, Math.max(0, deadline - now())));
+        const status = parseEmailSendStatus(await emailApiRequest({
+            apiUrl: input.apiUrl,
+            privateToken: input.privateToken,
+            path: `/sdk/private/emails/${encodeURIComponent(receipt.id)}`,
+            fetchImpl,
+        }));
+        if (TERMINAL_EMAIL_STATUSES.has(status.status))
+            return status;
+    }
+    throw new Error(`Timed out waiting for email delivery ${receipt.id}.`);
+}
 const hasDraft = (value) => (isRecord(value) && isRecord(value.draft));
 const assertRemoteResource = (value, resource) => {
     if (!isRecord(value)
@@ -211,6 +294,95 @@ export async function executeEmailPush(scope) {
     });
     return { templates: files.templates.length, sequences: files.sequences.length };
 }
+export async function executeEmailSequenceAddStep(input) {
+    const files = await readEmailFiles(input.sourceDir);
+    assertValidFiles(files);
+    const sequence = files.sequences.find((item) => item.slug === input.slug);
+    if (!sequence)
+        throw new Error(`Email sequence "${input.slug}" was not found locally.`);
+    if (sequence.draft.steps.some((step) => step.key === input.key)) {
+        throw new Error(`Email sequence step "${input.key}" already exists.`);
+    }
+    const templateVersionId = await resolvePublishedTemplateVersionId(input, input.templateSlug);
+    sequence.draft.steps.push({
+        key: input.key,
+        delaySeconds: input.delaySeconds,
+        templateVersionId,
+    });
+    await writeEmailSequenceFile(input.sourceDir, sequence);
+}
+const resolvePublishedTemplateVersionId = async (scope, templateSlug) => {
+    const templates = await scope.callApi({
+        path: 'emailTemplates.list',
+        type: 'query',
+        token: scope.token,
+        data: projectData(scope),
+    });
+    const template = templates.find((item) => item.slug === templateSlug);
+    if (!template?.currentPublishedVersionId) {
+        throw new Error(`Published email template "${templateSlug}" was not found.`);
+    }
+    return template.currentPublishedVersionId;
+};
+export async function executeEmailSequenceCreate(input) {
+    const files = await readEmailFiles(input.sourceDir);
+    assertValidFiles(files);
+    if (files.sequences.some((item) => item.slug === input.slug)) {
+        throw new Error(`Email sequence "${input.slug}" already exists locally.`);
+    }
+    const name = input.name.trim();
+    if (!name || name.length > 120)
+        throw new Error('Sequence name must be 1 to 120 characters.');
+    if (!STEP_KEY.test(input.firstStepKey) || input.firstStepKey.length > 64) {
+        throw new Error('Sequence step key must be lowercase kebab-case up to 64 characters.');
+    }
+    if (!Number.isInteger(input.delaySeconds) || input.delaySeconds < 0 || input.delaySeconds > 7_776_000) {
+        throw new Error('Sequence delay must be an integer from 0 to 7776000 seconds.');
+    }
+    if (input.funnelId !== null && !UUID.test(input.funnelId)) {
+        throw new Error('--funnel-id must be a UUID.');
+    }
+    const templateVersionId = await resolvePublishedTemplateVersionId(input, input.templateSlug);
+    await writeEmailSequenceFile(input.sourceDir, {
+        id: null,
+        slug: input.slug,
+        name,
+        draft: {
+            triggerEventType: input.triggerEventType,
+            funnelIds: input.funnelId === null ? [] : [input.funnelId],
+            steps: [{
+                    key: input.firstStepKey,
+                    delaySeconds: input.delaySeconds,
+                    templateVersionId,
+                }],
+            exitEventTypes: input.triggerEventType === 'purchase_completed'
+                ? []
+                : ['purchase_completed'],
+        },
+    });
+}
+export async function executeEmailSequenceSetActive(input) {
+    const files = await readEmailFiles(input.sourceDir);
+    assertValidFiles(files);
+    const sequence = files.sequences.find((item) => item.slug === input.slug);
+    if (!sequence)
+        throw new Error(`Email sequence "${input.slug}" was not found locally.`);
+    if (!sequence.id)
+        throw new Error(`Push email sequence "${input.slug}" before changing activation.`);
+    await assertRemoteIdentities(input, {
+        resource: 'emailSequences',
+        local: [{ id: sequence.id, slug: sequence.slug }],
+    });
+    await input.callApi({
+        path: `emailSequences.${input.active ? 'enable' : 'disable'}`,
+        type: 'mutation',
+        token: input.token,
+        data: {
+            ...projectData(input),
+            sequenceId: sequence.id,
+        },
+    });
+}
 export async function executeEmailTemplatePublish(scope) {
     return executeEmailPublish(scope, {
         kind: 'template',

package/dist/emailFiles.js

@@ -226,8 +226,8 @@ const validateSequence = (value, pathSlug, file, diagnostics) => {
     if (!EMAIL_EVENTS.has(value.triggerEventType)) {
         diagnostics.push(schemaDiagnostic(file, 'triggerEventType', [...EMAIL_EVENTS], value.triggerEventType));
     }
-    if (!Array.isArray(value.funnelIds) || value.funnelIds.length < 1 || value.funnelIds.length > 50) {
-        diagnostics.push(schemaDiagnostic(file, 'funnelIds', '1 to 50 UUIDs', value.funnelIds));
+    if (!Array.isArray(value.funnelIds) || value.funnelIds.length > 50) {
+        diagnostics.push(schemaDiagnostic(file, 'funnelIds', '0 to 50 UUIDs; empty means all funnels', value.funnelIds));
     }
     else {
         value.funnelIds.forEach((id, index) => {

package/funnel-contract-compatibility.json

@@ -4,10 +4,10 @@
   "minimumCliVersion": "0.1.20",
   "entries": [
     {
-      "repositoryCliVersion": "0.1.78",
+      "repositoryCliVersion": "0.1.86",
       "manifest": {
         "schemaVersion": 1,
-        "bundleVersion": "2.0.67",
+        "bundleVersion": "2.0.75",
         "stepContractVersion": 3,
         "contractHash": "d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf",
         "managedFiles": [
@@ -45,7 +45,7 @@
           },
           {
             "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-            "sha256": "4f588258cea6bffac880bde94e7861d26f0a62f50622ed1387828c3192a585ca"
+            "sha256": "a50e601c2ed9351b5322fc71cdb5a8e58dc2826d0a17cf0a5763c6c80ccfb28b"
           },
           {
             "path": "docs/funnelsgrove/qa/analytics.md",
@@ -145,16 +145,16 @@
           },
           {
             "path": "funnel-docs.config.json",
-            "sha256": "1ac549608dffb179c9029914dc56e8f02d6fa9be92d798a85945b68b0ce750fd"
+            "sha256": "2979bb06b0823bf925e99fc2ec5f4bb52ec5dfca103c57d391e4e82521d64feb"
           }
         ]
       }
     },
     {
-      "repositoryCliVersion": "0.1.77",
+      "repositoryCliVersion": "0.1.85",
       "manifest": {
         "schemaVersion": 1,
-        "bundleVersion": "2.0.66",
+        "bundleVersion": "2.0.74",
         "stepContractVersion": 3,
         "contractHash": "d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf",
         "managedFiles": [
@@ -192,7 +192,7 @@
           },
           {
             "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-            "sha256": "0a76f7f6a26bfbce6a0ae2b9ccbb20f58b99783963e3a3d619b98b1c96868106"
+            "sha256": "5bc3de862b0824a2bbeb324d5aa0a097f2b93c9d8a250b292e1002e1f10f127a"
           },
           {
             "path": "docs/funnelsgrove/qa/analytics.md",
@@ -292,16 +292,16 @@
           },
           {
             "path": "funnel-docs.config.json",
-            "sha256": "2c5bd7e557878d1cc1ab724c14246c2c762eeb4be07c834108c5a4ec7e5d75d2"
+            "sha256": "7d9ebfea22bb7e47c3233f1229c8924da048c27253755ec4ce2cdc280f576400"
           }
         ]
       }
     },
     {
-      "repositoryCliVersion": "0.1.76",
+      "repositoryCliVersion": "0.1.84",
       "manifest": {
         "schemaVersion": 1,
-        "bundleVersion": "2.0.65",
+        "bundleVersion": "2.0.73",
         "stepContractVersion": 3,
         "contractHash": "d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf",
         "managedFiles": [
@@ -339,7 +339,7 @@
           },
           {
             "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-            "sha256": "753d4bd01a3f05d3165cbe19510564b44a80d0f8392b72582222b771bc7045e0"
+            "sha256": "0dfaf22828481cb206164304c15d06f5900ca47cf37d38a4e650facd0ad84ec8"
           },
           {
             "path": "docs/funnelsgrove/qa/analytics.md",
@@ -439,16 +439,16 @@
           },
           {
             "path": "funnel-docs.config.json",
-            "sha256": "d085f9a552809b085d6b6cd1a5237ad5fcc0d88a8d4384d185638bc3bc99c90f"
+            "sha256": "79d08c93ffa111b31c8b5ed95b022ea5ce800d1e31b1ee1b7c957bffc18dc336"
           }
         ]
       }
     },
     {
-      "repositoryCliVersion": "0.1.75",
+      "repositoryCliVersion": "0.1.83",
       "manifest": {
         "schemaVersion": 1,
-        "bundleVersion": "2.0.64",
+        "bundleVersion": "2.0.72",
         "stepContractVersion": 3,
         "contractHash": "d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf",
         "managedFiles": [
@@ -486,7 +486,7 @@
           },
           {
             "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-            "sha256": "e73eba7d01d41d4d87be8a6170835c84b7c4f64792bbafb59201130a380250ec"
+            "sha256": "ff879b9479fa097459e9527a99b1d267e0a35b6cc056dace34a3b1ed640bdc5e"
           },
           {
             "path": "docs/funnelsgrove/qa/analytics.md",
@@ -586,16 +586,16 @@
           },
           {
             "path": "funnel-docs.config.json",
-            "sha256": "fd64ef085f6037e92d596ef958d4118e671285dd3561e22881eed0d7da1bba82"
+            "sha256": "1011fadb554a1bbc28110119ee43417c5e75d8b6c71482e21ca6014a9a66716a"
           }
         ]
       }
     },
     {
-      "repositoryCliVersion": "0.1.74",
+      "repositoryCliVersion": "0.1.81",
       "manifest": {
         "schemaVersion": 1,
-        "bundleVersion": "2.0.63",
+        "bundleVersion": "2.0.70",
         "stepContractVersion": 3,
         "contractHash": "d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf",
         "managedFiles": [
@@ -633,7 +633,7 @@
           },
           {
             "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-            "sha256": "f025610f7c1d91188a67f50e7511a47642b3606170700e11cef0e7a49c8cd997"
+            "sha256": "9da61fe189a9b34001c3c73a0abb217d3db109f512fc0a80187123c2c07b356c"
           },
           {
             "path": "docs/funnelsgrove/qa/analytics.md",
@@ -733,16 +733,16 @@
           },
           {
             "path": "funnel-docs.config.json",
-            "sha256": "7852876ec227cb893db0315a00627cd609afe14ac5ffac5fdba0fe585a56fbbf"
+            "sha256": "3bff17f060f71f221c36703b668b601d1f80fac5ff43c55b99cdb5a1d6136962"
           }
         ]
       }
     },
     {
-      "repositoryCliVersion": "0.1.73",
+      "repositoryCliVersion": "0.1.80",
       "manifest": {
         "schemaVersion": 1,
-        "bundleVersion": "2.0.62",
+        "bundleVersion": "2.0.69",
         "stepContractVersion": 3,
         "contractHash": "d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf",
         "managedFiles": [
@@ -780,7 +780,7 @@
           },
           {
             "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-            "sha256": "54e982ca3f199113646be0d6de1f8e2b8dde87744df82d6d7452d8e33b2b5258"
+            "sha256": "00b0089ec0997a0ef095e1216a4b2322d4e4e00816e0fa7eea6bfc1238e9e459"
           },
           {
             "path": "docs/funnelsgrove/qa/analytics.md",
@@ -880,16 +880,16 @@
           },
           {
             "path": "funnel-docs.config.json",
-            "sha256": "7f343fd806a932abcb3cac6463ae84a7532b7c9f583540e6fa06fd7ff7721ddf"
+            "sha256": "f66d2e8d39c457cbc30a9fe120b72df3a15f31259f1ac03afb829d87c7679e40"
           }
         ]
       }
     },
     {
-      "repositoryCliVersion": "0.1.72",
+      "repositoryCliVersion": "0.1.79",
       "manifest": {
         "schemaVersion": 1,
-        "bundleVersion": "2.0.61",
+        "bundleVersion": "2.0.68",
         "stepContractVersion": 3,
         "contractHash": "d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf",
         "managedFiles": [
@@ -927,7 +927,7 @@
           },
           {
             "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-            "sha256": "217b719ef163d485c7a740906b3a1d551f5af37faf9fb721fc61d1fecf5fa9e6"
+            "sha256": "cb4bbcd69c41a211407165ee69f6b8c882ea4f85fe7dc10e6e02f0456dd04213"
           },
           {
             "path": "docs/funnelsgrove/qa/analytics.md",
@@ -1027,7 +1027,7 @@
           },
           {
             "path": "funnel-docs.config.json",
-            "sha256": "f9be1a58ba8548ecbf51b2676479964dca89a04a63c9de53f6f805a6ed090fd0"
+            "sha256": "a8e43e7908bdf3be2634ee7fb64b429e1aeb11e51dc5f1eb72b51d126bb477f2"
           }
         ]
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@funnelsgrove/cli",
-  "version": "0.1.78",
+  "version": "0.1.86",
   "description": "FunnelsGrove command-line tools for editing, syncing, and publishing funnels",
   "repository": {
     "type": "git",
@@ -34,12 +34,12 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@funnelsgrove/runtime": "0.7.6",
+    "@funnelsgrove/runtime": "0.7.9",
     "commander": "^12.0.0",
     "typescript": "^5.8.3"
   },
   "devDependencies": {
-    "@funnelsgrove/analytics": "0.1.55",
+    "@funnelsgrove/analytics": "0.1.58",
     "@funnelsgrove/payments": "0.7.3",
     "vitest": "^3.0.0"
   }

package/template_docs/.funnelsgrove-docs.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "bundleVersion": "2.0.67",
+  "bundleVersion": "2.0.75",
   "stepContractVersion": 3,
   "contractHash": "d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf",
   "managedFiles": [
@@ -38,7 +38,7 @@
     },
     {
       "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-      "sha256": "4f588258cea6bffac880bde94e7861d26f0a62f50622ed1387828c3192a585ca"
+      "sha256": "a50e601c2ed9351b5322fc71cdb5a8e58dc2826d0a17cf0a5763c6c80ccfb28b"
     },
     {
       "path": "docs/funnelsgrove/qa/analytics.md",
@@ -138,7 +138,7 @@
     },
     {
       "path": "funnel-docs.config.json",
-      "sha256": "1ac549608dffb179c9029914dc56e8f02d6fa9be92d798a85945b68b0ce750fd"
+      "sha256": "2979bb06b0823bf925e99fc2ec5f4bb52ec5dfca103c57d391e4e82521d64feb"
     }
   ]
 }

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/runtime` `0.7.6` first, then `@funnelsgrove/analytics` `0.1.55`, then `@funnelsgrove/payments` `0.7.3`. Deploy the API and funnel template, then confirm production `/health` reports the new docs identity. Only then publish `@funnelsgrove/cli` `0.1.78`. Publishing packages and deploying production remain separately approved operational actions.
+Release `@funnelsgrove/runtime` `0.7.9` first, then `@funnelsgrove/analytics` `0.1.58`, then `@funnelsgrove/payments` `0.7.3`. Deploy the API and funnel template, then confirm production `/health` reports the new docs identity. Only then publish `@funnelsgrove/cli` `0.1.86`. 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.67",
+  "bundleVersion": "2.0.75",
   "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.67",
+  "bundleVersion": "2.0.75",
   "stepContractVersion": 3,
   "contractHash": "d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf",
   "managedFiles": [
@@ -38,7 +38,7 @@
     },
     {
       "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-      "sha256": "4f588258cea6bffac880bde94e7861d26f0a62f50622ed1387828c3192a585ca"
+      "sha256": "a50e601c2ed9351b5322fc71cdb5a8e58dc2826d0a17cf0a5763c6c80ccfb28b"
     },
     {
       "path": "docs/funnelsgrove/qa/analytics.md",
@@ -138,7 +138,7 @@
     },
     {
       "path": "funnel-docs.config.json",
-      "sha256": "1ac549608dffb179c9029914dc56e8f02d6fa9be92d798a85945b68b0ce750fd"
+      "sha256": "2979bb06b0823bf925e99fc2ec5f4bb52ec5dfca103c57d391e4e82521d64feb"
     }
   ]
 }

package/template_scaffold/.funnelsgrove-scaffold.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
-  "sourceTreeHash": "e87926c04ef311b0dd8e18ace4874ef42ae792af88f0ded13309f10929034674",
+  "sourceTreeHash": "ada91ddf280aa113c83e0ce869a657fcff6ee1e48d8fbc50d9afca3e2bc630bf",
   "stepContractVersion": 3,
-  "docsBundleVersion": "2.0.67",
+  "docsBundleVersion": "2.0.75",
   "files": [
     {
       "path": ".env.example",
@@ -16,7 +16,7 @@
     },
     {
       "path": ".funnelsgrove-docs.json",
-      "sha256": "b1ea1636455086e8b3ff78a2f61819ff4b46ea70aad1e1c29bc4c5f6a17f3b0b",
+      "sha256": "cd1687669bbad96d04bbeeb5747beb4535e821112fff66de531e76f7c2e95ccb",
       "mode": "100644"
     },
     {
@@ -101,7 +101,7 @@
     },
     {
       "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-      "sha256": "4f588258cea6bffac880bde94e7861d26f0a62f50622ed1387828c3192a585ca",
+      "sha256": "a50e601c2ed9351b5322fc71cdb5a8e58dc2826d0a17cf0a5763c6c80ccfb28b",
       "mode": "100644"
     },
     {
@@ -236,7 +236,7 @@
     },
     {
       "path": "funnel-docs.config.json",
-      "sha256": "1ac549608dffb179c9029914dc56e8f02d6fa9be92d798a85945b68b0ce750fd",
+      "sha256": "2979bb06b0823bf925e99fc2ec5f4bb52ec5dfca103c57d391e4e82521d64feb",
       "mode": "100644"
     },
     {
@@ -261,12 +261,12 @@
     },
     {
       "path": "package-lock.json",
-      "sha256": "7aba9c8a0e5919b31b70f7eaeb684b718708b2c2afdb8d919476edbe6a09e588",
+      "sha256": "6310cad764c6569cfdbb91e7472bfc5817a725588190d61d167bbb3c297dbc86",
       "mode": "100644"
     },
     {
       "path": "package.json",
-      "sha256": "15cf7b7514c3837d3740f825adbf1b76a1d275c1cceda073cadcb690ef8351b7",
+      "sha256": "f82ef00e2cb053b2bd4c3d3e07e905676f384aee6b1c5a0266acb1295c79fd5e",
       "mode": "100644"
     },
     {
@@ -736,7 +736,7 @@
     },
     {
       "path": "src/steps/content/subscription-started.content.ts",
-      "sha256": "1b50bdd85c3f5999891b43ba604adf4135129c1e9ef82ce42433e4a6c2969e1d",
+      "sha256": "7abd10868249d4da2281678c57a11a1cf92a804398bc7f02d615c1aae62cec18",
       "mode": "100644"
     },
     {
@@ -851,7 +851,7 @@
     },
     {
       "path": "src/steps/step-33-subscription-started.tsx",
-      "sha256": "a9c9a58b9a2cb03ea5e7b1110557819ddeb83ceada956448215b759b68c167a2",
+      "sha256": "c5120ebc8bc7ea04443d85b3c1c3014535c3c7380ee855ceed2b3a7b78dc9cd4",
       "mode": "100644"
     },
     {
@@ -916,7 +916,7 @@
     },
     {
       "path": "tests/funnel-agent-docs.test.ts",
-      "sha256": "fb520e7197704b22be56f77c36600f3557edcec9e4698393a1245b708215fa2a",
+      "sha256": "0dfc60cd22732d6d7642aa2681f1002f471def2a3633ec45933250538c67eb2f",
       "mode": "100644"
     },
     {
@@ -1036,7 +1036,7 @@
     },
     {
       "path": "tests/src/steps/step-33-subscription-started.test.ts",
-      "sha256": "64795d72a03b0ede1a6d42f9fcf575eadb88eb170266f1aa418ce966d0dc57b7",
+      "sha256": "a3547ccca96132eff97c4c1c0b082fbd7e071d6ad59c8df86e9d26bae224d607",
       "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/runtime` `0.7.6` first, then `@funnelsgrove/analytics` `0.1.55`, then `@funnelsgrove/payments` `0.7.3`. Deploy the API and funnel template, then confirm production `/health` reports the new docs identity. Only then publish `@funnelsgrove/cli` `0.1.78`. Publishing packages and deploying production remain separately approved operational actions.
+Release `@funnelsgrove/runtime` `0.7.9` first, then `@funnelsgrove/analytics` `0.1.58`, then `@funnelsgrove/payments` `0.7.3`. Deploy the API and funnel template, then confirm production `/health` reports the new docs identity. Only then publish `@funnelsgrove/cli` `0.1.86`. 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.67",
+  "bundleVersion": "2.0.75",
   "contractSource": "funnelsgrove-repository://apps/funnel-runtime/contracts/step-contract-v2.json",
   "fullyGenerated": [
     ".funnelsgrove-docs.json",

package/template_scaffold/package-lock.json

@@ -8,9 +8,9 @@
       "name": "funnel-template",
       "version": "0.1.0",
       "dependencies": {
-        "@funnelsgrove/analytics": "^0.1.55",
+        "@funnelsgrove/analytics": "^0.1.58",
         "@funnelsgrove/payments": "^0.7.3",
-        "@funnelsgrove/runtime": "^0.7.6",
+        "@funnelsgrove/runtime": "^0.7.9",
         "@stripe/react-stripe-js": "^5.6.0",
         "@stripe/stripe-js": "^8.7.0",
         "lucide-react": "^0.553.0",
@@ -891,11 +891,11 @@
       }
     },
     "node_modules/@funnelsgrove/analytics": {
-      "version": "0.1.55",
-      "resolved": "https://registry.npmjs.org/@funnelsgrove/analytics/-/analytics-0.1.55.tgz",
-      "integrity": "sha512-+JlX1OWL81XcSAGd3clUENKiloPPMFUNSfLnfnOIs+iXJbXPX5MlEbVmkLAuQUOMRT4yMZzGDQe9OIpxO++2Yg==",
+      "version": "0.1.58",
+      "resolved": "https://registry.npmjs.org/@funnelsgrove/analytics/-/analytics-0.1.58.tgz",
+      "integrity": "sha512-bTSq7SO7CuicexEXUKIc3WMW7RQV1VI9pQfCOn79E6ygHa/1shoY7GZyzB/9n5Pn2pAOdZzNIy+erPPHaQROQQ==",
       "dependencies": {
-        "@funnelsgrove/runtime": "0.7.6"
+        "@funnelsgrove/runtime": "0.7.9"
       }
     },
     "node_modules/@funnelsgrove/payments": {
@@ -913,9 +913,9 @@
       }
     },
     "node_modules/@funnelsgrove/runtime": {
-      "version": "0.7.6",
-      "resolved": "https://registry.npmjs.org/@funnelsgrove/runtime/-/runtime-0.7.6.tgz",
-      "integrity": "sha512-olumRPhnx5VcSb+SG/LqxbiKkJoQIIcMm4DFYlPe7QVD4g18sModuHAEfR3qeFtuZfV4Na5hA9hUPicD0M45kg==",
+      "version": "0.7.9",
+      "resolved": "https://registry.npmjs.org/@funnelsgrove/runtime/-/runtime-0.7.9.tgz",
+      "integrity": "sha512-j6T7n2YZ5CaQc1IPc+2HX/gBq7U/rtNKKrBEttMMNtrC/ip1PcLdoj7qBgsyh6dgjpg+eYi6lExr8I1g5gA/ew==",
       "dependencies": {
         "posthog-js": "^1.369.2",
         "react": "19.2.3",

package/template_scaffold/package.json

@@ -12,9 +12,9 @@
     "validate:funnel": "vite-node --config src/contract/funnel-validator.vite.config.ts src/contract/validate-funnel.cli.ts"
   },
   "dependencies": {
-    "@funnelsgrove/analytics": "^0.1.55",
+    "@funnelsgrove/analytics": "^0.1.58",
     "@funnelsgrove/payments": "^0.7.3",
-    "@funnelsgrove/runtime": "^0.7.6",
+    "@funnelsgrove/runtime": "^0.7.9",
     "@stripe/react-stripe-js": "^5.6.0",
     "@stripe/stripe-js": "^8.7.0",
     "lucide-react": "^0.553.0",

package/template_scaffold/src/steps/content/subscription-started.content.ts

@@ -66,3 +66,19 @@ export const subscriptionStartedContent = {
     },
   },
 } as const satisfies LocalizedStepContent<SubscriptionStartedLocaleContent>;
+
+export const returningSubscriberContent = {
+  defaultLocale: 'en',
+  locales: {
+    en: {
+      ...subscriptionStartedContent.locales.en,
+      kicker: 'Welcome back',
+      title: 'You already have access.',
+      copyWithQr:
+        'Your subscription is active. Open the app and sign in with this email to continue.',
+      copyWithoutQr:
+        'Your subscription is active. Open the app and sign in with this email to continue.',
+      note: 'We’ll send you a verification code when you sign in.',
+    },
+  },
+} as const satisfies LocalizedStepContent<SubscriptionStartedLocaleContent>;

package/template_scaffold/src/steps/step-33-subscription-started.tsx

@@ -8,7 +8,11 @@ import {
   type FunnelStepMeta,
 } from '@funnelsgrove/runtime';
 import { getStepContentLocale } from '@/runtime/step-content-context';
-import { subscriptionStartedContent } from '@/steps/content/subscription-started.content';
+import {
+  returningSubscriberContent,
+  subscriptionStartedContent,
+  type SubscriptionStartedLocaleContent,
+} from '@/steps/content/subscription-started.content';
 
 export const stepSubscriptionStartedId = 'subscription-started';
 
@@ -26,10 +30,10 @@ export const stepSubscriptionStarted: FunnelStepMeta = {
 };
 
 export function StepSubscriptionStarted() {
-  const { attributes } = useFunnel();
-  const content = usePreviewStepLocalizedContent(
+  const { attributes, isReturningSubscriber } = useFunnel();
+  const content = usePreviewStepLocalizedContent<SubscriptionStartedLocaleContent>(
     stepSubscriptionStartedId,
-    subscriptionStartedContent,
+    isReturningSubscriber ? returningSubscriberContent : subscriptionStartedContent,
     getStepContentLocale(attributes),
   );
 

package/template_scaffold/tests/funnel-agent-docs.test.ts

@@ -363,7 +363,7 @@ describe('funnel agent documentation supply', () => {
 
     expect(manifest).toMatchObject({
       schemaVersion: 1,
-      bundleVersion: '2.0.67',
+      bundleVersion: '2.0.75',
       stepContractVersion: contract.stepContractVersion,
       contractHash: contract.contractHash,
     });

package/template_scaffold/tests/src/steps/step-33-subscription-started.test.ts

@@ -10,6 +10,9 @@ describe('template subscription-started source', () => {
     );
 
     expect(stepSource).toContain('SubscriptionHandoffScreen');
+    expect(stepSource.match(/<SubscriptionHandoffScreen/g)).toHaveLength(1);
+    expect(stepSource).toContain('isReturningSubscriber');
+    expect(stepSource).toContain('returningSubscriberContent');
     expect(stepSource).toContain("completionMode='funnel'");
     expect(stepSource).toContain("type: 'purchase_completed'");
     expect(stepSource).not.toContain('@funnelsgrove/analytics');
@@ -22,4 +25,20 @@ describe('template subscription-started source', () => {
     expect(stepSource).not.toContain('api.qrserver.com');
     expect(stepSource).not.toContain('NEXT_PUBLIC_IOS_APP_STORE_URL');
   });
+
+  it('defines the approved returning-subscriber copy', () => {
+    const contentSource = readFileSync(
+      path.resolve(__dirname, '../../../src/steps/content/subscription-started.content.ts'),
+      'utf8',
+    );
+
+    expect(contentSource).toContain("kicker: 'Welcome back'");
+    expect(contentSource).toContain("title: 'You already have access.'");
+    expect(contentSource).toContain(
+      "'Your subscription is active. Open the app and sign in with this email to continue.'",
+    );
+    expect(contentSource).toContain(
+      "'We’ll send you a verification code when you sign in.'",
+    );
+  });
 });