@aglyn/shared-util-email 1.0.0-beta.234 → 1.0.0-beta.235

package/src/lib/retention-emails.js

@@ -0,0 +1,375 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ /**
+ * THE GETTING-STARTED EMAILS (AGL-3692).
+ *
+ * Until these, the platform said one thing to a new account, the welcome
+ * email, and then nothing, whether the person built a site, stalled on
+ * verification or stopped coming back. Each email here is sent once per
+ * crossing of an activation stage by the hourly retention sweep, and is in
+ * the system-email catalog so staff can also send it by hand from an
+ * account's staff page (AGL-3691).
+ *
+ * ## Which preference governs them
+ *
+ * The verification reminder is ACCOUNT mail: it finishes something the
+ * person started, so it follows only the suppression list, like the
+ * verification email itself.
+ *
+ * Every other email here is a product tip and belongs to the account's
+ * PRODUCT EMAIL answer (`marketingConsent` on `users/{uid}`, the switch under
+ * Manage account → Emails). A person who said No there, or left the product
+ * updates list from a marketing email (mirrored onto the same answer,
+ * AGL-3305), is never sent one. Each carries a link to that switch in its
+ * body and in `List-Unsubscribe`.
+ *
+ * ## Copy rules
+ *
+ * The heading states the topic, so a reader who skipped the subject still
+ * knows what the email is about (AGL-3432). Customer copy says "pages",
+ * never "screens". No prices. The product is named by token, so a renamed
+ * deployment reads as itself.
+ *
+ * ## Same design as every other system email
+ *
+ * Each is a catalog entry like `welcome` or `email-verification`, so it
+ * renders through `renderSystemEmail`: the staff design when one is published
+ * under Staff → Emails, else these blocks, inside the same header, footer,
+ * palette and button. Like the rest, an email carries ONE button; anything
+ * else it points at is a caption line with a bare link, the house shape of
+ * the opt-out caption `notification` and the digests carry.
+ *
+ * ## Docs links
+ *
+ * Each email points at the docs page that walks through its one task. The
+ * paths live in {@link RETENTION_DOCS_PATHS}, the merge values are built from
+ * the deployment's docs origin by {@link retentionDocsMergeValues} at send
+ * time, so the copy names a token and never a host, and a spec holds every
+ * path to a real page under `apps/docs`.
+ */ export const RETENTION_VERIFY_REMINDER_EMAIL = 'retention-verify-reminder';
+export const RETENTION_BUILD_SITE_EMAIL = 'retention-build-site';
+export const RETENTION_PUBLISH_REMINDER_EMAIL = 'retention-publish-reminder';
+export const RETENTION_IDLE_EMAIL = 'retention-idle';
+export const RETENTION_NEXT_STEPS_EMAIL = 'retention-next-steps';
+/**
+ * The docs pages the getting-started emails link to, by merge token: a path
+ * on the docs site, with a heading anchor where the page covers more than
+ * the one task. Each is a page under `apps/docs/docs` (the docs site serves
+ * it at its root), which `retention-emails.spec.ts` checks.
+ */ export const RETENTION_DOCS_PATHS = {
+    'docs.verifyEmailUrl': '/workspace-and-billing/signing-in-and-sessions#verifying-your-email',
+    'docs.generateSiteUrl': '/ai/generate-a-site',
+    'docs.publishUrl': '/getting-started/publish-your-first-screen',
+    'docs.connectDomainUrl': '/building-sites/custom-domains/connect-a-domain',
+    'docs.formsUrl': '/content-and-data/forms/overview',
+    'docs.generateSectionUrl': '/ai/generate-section',
+    'docs.copyAssistUrl': '/ai/copy-assist'
+};
+/**
+ * Every docs link as a merge value, on the given docs origin. The console
+ * passes its own docs origin (`DOCS_BASE_URL`), so a self-hosted deployment
+ * links its own docs build.
+ */ export function retentionDocsMergeValues(docsOrigin) {
+    const origin = docsOrigin.trim().replace(/\/+$/, '');
+    return Object.fromEntries(Object.entries(RETENTION_DOCS_PATHS).map(([token, path])=>[
+            token,
+            `${origin}${path}`
+        ]));
+}
+/**
+ * The retention emails that are product tips, governed by the account's
+ * product email answer. The verification reminder is not one of them.
+ */ export const PRODUCT_TIP_RETENTION_EMAILS = new Set([
+    RETENTION_BUILD_SITE_EMAIL,
+    RETENTION_PUBLISH_REMINDER_EMAIL,
+    RETENTION_IDLE_EMAIL,
+    RETENTION_NEXT_STEPS_EMAIL
+]);
+/**
+ * The getting-started entries, built on the catalog's sample console origin.
+ *
+ * A function rather than a constant so that origin is the catalog's own
+ * `SAMPLE_CONSOLE_ORIGIN`, one reading of `NEXT_PUBLIC_CONSOLE_URL` for every
+ * preview sample, rather than a second spelled-out default here.
+ */ export function retentionSystemEmailTemplates(SAMPLE_CONSOLE_ORIGIN, SAMPLE_DOCS_ORIGIN) {
+    const docsSamples = retentionDocsMergeValues(SAMPLE_DOCS_ORIGIN);
+    const DOCS_TOKEN = (name, description)=>({
+            name,
+            description,
+            sample: docsSamples[name]
+        });
+    const NAME_TOKEN = {
+        name: 'name',
+        description: "The account holder's first name, or “there”",
+        sample: 'Alex'
+    };
+    const SITE_NAME_TOKEN = {
+        name: 'site.name',
+        description: 'The name of their site',
+        sample: 'Test Site'
+    };
+    const CTA_TOKEN = {
+        name: 'ctaUrl',
+        description: 'Where the button opens in the console',
+        sample: `${SAMPLE_CONSOLE_ORIGIN}/test-org/hosts/test-site`
+    };
+    const PREFERENCES_TOKEN = {
+        name: 'preferencesUrl',
+        description: 'The product email switch in account settings',
+        sample: `${SAMPLE_CONSOLE_ORIGIN}/manage/user/emails`
+    };
+    // The house opt-out line, as `notification` and the digests word it.
+    const PREFERENCES_CAPTION = {
+        block: 'text',
+        text: 'Change what you are emailed about: {{preferencesUrl}}',
+        variant: 'caption'
+    };
+    return [
+        {
+            key: RETENTION_VERIFY_REMINDER_EMAIL,
+            name: 'Getting started: confirm your email',
+            description: 'Sent about an hour, and again a day, after sign-up to an account ' + 'that has not confirmed its email address. Carries a fresh link.',
+            deliveredBy: 'resend',
+            defaultSubject: 'Confirm your email to open your {{brand.productName}} workspace',
+            mergeTokens: [
+                NAME_TOKEN,
+                {
+                    name: 'verifyUrl',
+                    description: 'One-time link that confirms the address',
+                    sample: `${SAMPLE_CONSOLE_ORIGIN}/verify-email?oobCode=…`
+                },
+                DOCS_TOKEN('docs.verifyEmailUrl', 'Docs: verifying your email, under Signing in & sessions')
+            ],
+            defaultBody: [
+                {
+                    block: 'text',
+                    text: 'Confirm your email to finish signing up',
+                    variant: 'heading'
+                },
+                {
+                    block: 'text',
+                    text: 'Hi {{name}}, you started a {{brand.productName}} account but your ' + 'email address is not confirmed yet. Confirm it and your ' + 'workspace opens, ready for your website.',
+                    variant: 'body'
+                },
+                {
+                    block: 'button',
+                    label: 'Confirm my email',
+                    href: '{{verifyUrl}}'
+                },
+                {
+                    block: 'text',
+                    text: 'The link works once and expires soon. If you did not sign up, ' + 'ignore this email and nothing happens.',
+                    variant: 'caption'
+                },
+                {
+                    block: 'text',
+                    text: 'Link expired or not arriving? See verifying your email: {{docs.verifyEmailUrl}}',
+                    variant: 'caption'
+                }
+            ],
+            footerReason: 'You’re receiving this because this address was used to sign up ' + 'for {{brand.productName}} and has not been confirmed.',
+            source: 'apps/console/app/api/admin/retention-emails/route.ts'
+        },
+        {
+            key: RETENTION_BUILD_SITE_EMAIL,
+            name: 'Getting started: build your site',
+            description: 'Sent a day, and again three days, after sign-up to a confirmed ' + 'account with no page of its own yet: no workspace, no site, or ' + 'only the starter pages.',
+            deliveredBy: 'resend',
+            defaultSubject: 'Your website is a few minutes away',
+            mergeTokens: [
+                NAME_TOKEN,
+                CTA_TOKEN,
+                DOCS_TOKEN('docs.generateSiteUrl', 'Docs: generate a website from a prompt'),
+                PREFERENCES_TOKEN
+            ],
+            defaultBody: [
+                {
+                    block: 'text',
+                    text: 'Build your website with {{brand.productName}} AI',
+                    variant: 'heading'
+                },
+                {
+                    block: 'text',
+                    text: 'Hi {{name}}, your account is ready, but your site has no pages ' + 'of your own yet. Describe your business in a sentence and ' + '{{brand.productName}} AI builds a full website for you, with ' + 'pages, photos and copy you can edit. Your first AI site is ' + 'included on the Free plan, and you can start right now.',
+                    variant: 'body'
+                },
+                {
+                    block: 'text',
+                    text: 'Prefer to start by hand? Add a page from your dashboard and pick a layout.',
+                    variant: 'body'
+                },
+                {
+                    block: 'button',
+                    label: 'Build my site',
+                    href: '{{ctaUrl}}'
+                },
+                {
+                    block: 'text',
+                    text: 'How a site is built from your description, step by step: {{docs.generateSiteUrl}}',
+                    variant: 'caption'
+                },
+                PREFERENCES_CAPTION
+            ],
+            footerReason: 'You’re receiving this because you signed up for ' + '{{brand.productName}} and have not added a page yet.',
+            source: 'apps/console/app/api/admin/retention-emails/route.ts'
+        },
+        {
+            key: RETENTION_PUBLISH_REMINDER_EMAIL,
+            name: 'Getting started: publish your changes',
+            description: 'Sent once to an account that edited pages a day or more ago and ' + 'has published none of its own work.',
+            deliveredBy: 'resend',
+            defaultSubject: 'Your changes on {{site.name}} are not live yet',
+            mergeTokens: [
+                NAME_TOKEN,
+                SITE_NAME_TOKEN,
+                CTA_TOKEN,
+                DOCS_TOKEN('docs.publishUrl', 'Docs: publish your first page'),
+                PREFERENCES_TOKEN
+            ],
+            defaultBody: [
+                {
+                    block: 'text',
+                    text: 'Your edits are saved, not published',
+                    variant: 'heading'
+                },
+                {
+                    block: 'text',
+                    text: 'Hi {{name}}, you edited pages on {{site.name}}, and those ' + 'changes are saved. Visitors will not see them until you ' + 'publish.',
+                    variant: 'body'
+                },
+                {
+                    block: 'button',
+                    label: 'Review and publish',
+                    href: '{{ctaUrl}}'
+                },
+                {
+                    block: 'text',
+                    text: 'How previewing and publishing a page works: {{docs.publishUrl}}',
+                    variant: 'caption'
+                },
+                PREFERENCES_CAPTION
+            ],
+            footerReason: 'You’re receiving this because you have unpublished changes on a ' + '{{brand.productName}} site.',
+            source: 'apps/console/app/api/admin/retention-emails/route.ts'
+        },
+        {
+            key: RETENTION_IDLE_EMAIL,
+            name: 'Getting started: pick up where you left off',
+            description: 'Sent 7 days, and again 14 days, after the last sign-in of an ' + 'account that has worked on its site. Once per quiet spell; coming ' + 'back resets it.',
+            deliveredBy: 'resend',
+            defaultSubject: 'Pick up where you left off on {{site.name}}',
+            mergeTokens: [
+                NAME_TOKEN,
+                SITE_NAME_TOKEN,
+                CTA_TOKEN,
+                DOCS_TOKEN('docs.generateSectionUrl', 'Docs: generate a section on the canvas'),
+                DOCS_TOKEN('docs.copyAssistUrl', 'Docs: rewrite and write copy with AI'),
+                PREFERENCES_TOKEN
+            ],
+            defaultBody: [
+                {
+                    block: 'text',
+                    text: 'Pick up where you left off on {{site.name}}',
+                    variant: 'heading'
+                },
+                {
+                    block: 'text',
+                    text: 'Hi {{name}}, it has been a little while since you worked on ' + '{{site.name}}. Your pages are where you left them. A new ' + 'section, a fresh photo or an updated page keeps the site ' + 'current for the people who find it.',
+                    variant: 'body'
+                },
+                {
+                    block: 'text',
+                    text: 'Short on time? {{brand.productName}} AI can build a new section ' + 'or rewrite the words on a page from one sentence.',
+                    variant: 'body'
+                },
+                {
+                    block: 'button',
+                    label: 'Open my site',
+                    href: '{{ctaUrl}}'
+                },
+                {
+                    block: 'text',
+                    text: 'Build a section with AI: {{docs.generateSectionUrl}}\n' + 'Rewrite your copy with AI: {{docs.copyAssistUrl}}',
+                    variant: 'caption'
+                },
+                PREFERENCES_CAPTION
+            ],
+            footerReason: 'You’re receiving this because you have a site on ' + '{{brand.productName}} and have not signed in for a while.',
+            source: 'apps/console/app/api/admin/retention-emails/route.ts'
+        },
+        {
+            key: RETENTION_NEXT_STEPS_EMAIL,
+            name: 'Getting started: your site is live',
+            description: 'Sent once, after an account first publishes pages of its own: ' + 'what to do next, a custom domain and a contact form.',
+            deliveredBy: 'resend',
+            defaultSubject: '{{site.name}} is live: what to do next',
+            mergeTokens: [
+                NAME_TOKEN,
+                SITE_NAME_TOKEN,
+                {
+                    name: 'siteUrl',
+                    description: 'The published site',
+                    sample: 'https://www.example.com'
+                },
+                {
+                    name: 'domainUrl',
+                    description: 'The site’s domain settings in the console',
+                    sample: `${SAMPLE_CONSOLE_ORIGIN}/test-org/hosts/test-site/admin/domain`
+                },
+                {
+                    name: 'formsUrl',
+                    description: 'The site’s forms in the console',
+                    sample: `${SAMPLE_CONSOLE_ORIGIN}/test-org/hosts/test-site/forms`
+                },
+                DOCS_TOKEN('docs.connectDomainUrl', 'Docs: connect a domain'),
+                DOCS_TOKEN('docs.formsUrl', 'Docs: forms and lead capture'),
+                PREFERENCES_TOKEN
+            ],
+            defaultBody: [
+                {
+                    block: 'text',
+                    text: '{{site.name}} is live',
+                    variant: 'heading'
+                },
+                {
+                    block: 'text',
+                    text: 'Hi {{name}}, your pages are published and anyone with the link ' + 'can see them: {{siteUrl}}',
+                    variant: 'body'
+                },
+                {
+                    block: 'text',
+                    text: 'Three things that help people find and reach you:\n' + '1. Connect your own domain, so the address is yours.\n' + '2. Add a contact form, so visitors can reach you from any ' + 'page: {{formsUrl}}\n' + '3. Share the link where your customers already are.',
+                    variant: 'body'
+                },
+                {
+                    block: 'button',
+                    label: 'Connect a domain',
+                    href: '{{domainUrl}}'
+                },
+                {
+                    block: 'text',
+                    text: 'Connect a domain, step by step: {{docs.connectDomainUrl}}\n' + 'Add a form and read its submissions: {{docs.formsUrl}}',
+                    variant: 'caption'
+                },
+                PREFERENCES_CAPTION
+            ],
+            footerReason: 'You’re receiving this because you published a site on ' + '{{brand.productName}}.',
+            source: 'apps/console/app/api/admin/retention-emails/route.ts'
+        }
+    ];
+}
+
+//# sourceMappingURL=retention-emails.js.map

package/src/lib/retention-emails.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/shared/util/email/src/lib/retention-emails.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * THE GETTING-STARTED EMAILS (AGL-3692).\n *\n * Until these, the platform said one thing to a new account, the welcome\n * email, and then nothing, whether the person built a site, stalled on\n * verification or stopped coming back. Each email here is sent once per\n * crossing of an activation stage by the hourly retention sweep, and is in\n * the system-email catalog so staff can also send it by hand from an\n * account's staff page (AGL-3691).\n *\n * ## Which preference governs them\n *\n * The verification reminder is ACCOUNT mail: it finishes something the\n * person started, so it follows only the suppression list, like the\n * verification email itself.\n *\n * Every other email here is a product tip and belongs to the account's\n * PRODUCT EMAIL answer (`marketingConsent` on `users/{uid}`, the switch under\n * Manage account → Emails). A person who said No there, or left the product\n * updates list from a marketing email (mirrored onto the same answer,\n * AGL-3305), is never sent one. Each carries a link to that switch in its\n * body and in `List-Unsubscribe`.\n *\n * ## Copy rules\n *\n * The heading states the topic, so a reader who skipped the subject still\n * knows what the email is about (AGL-3432). Customer copy says \"pages\",\n * never \"screens\". No prices. The product is named by token, so a renamed\n * deployment reads as itself.\n *\n * ## Same design as every other system email\n *\n * Each is a catalog entry like `welcome` or `email-verification`, so it\n * renders through `renderSystemEmail`: the staff design when one is published\n * under Staff → Emails, else these blocks, inside the same header, footer,\n * palette and button. Like the rest, an email carries ONE button; anything\n * else it points at is a caption line with a bare link, the house shape of\n * the opt-out caption `notification` and the digests carry.\n *\n * ## Docs links\n *\n * Each email points at the docs page that walks through its one task. The\n * paths live in {@link RETENTION_DOCS_PATHS}, the merge values are built from\n * the deployment's docs origin by {@link retentionDocsMergeValues} at send\n * time, so the copy names a token and never a host, and a spec holds every\n * path to a real page under `apps/docs`.\n */\n\nimport type {\n  SystemEmailDefaultBlock,\n  SystemEmailMergeToken,\n  SystemEmailTemplateDefinition,\n} from './system-email-catalog'\n\nexport const RETENTION_VERIFY_REMINDER_EMAIL = 'retention-verify-reminder'\nexport const RETENTION_BUILD_SITE_EMAIL = 'retention-build-site'\nexport const RETENTION_PUBLISH_REMINDER_EMAIL = 'retention-publish-reminder'\nexport const RETENTION_IDLE_EMAIL = 'retention-idle'\nexport const RETENTION_NEXT_STEPS_EMAIL = 'retention-next-steps'\n\n/**\n * The docs pages the getting-started emails link to, by merge token: a path\n * on the docs site, with a heading anchor where the page covers more than\n * the one task. Each is a page under `apps/docs/docs` (the docs site serves\n * it at its root), which `retention-emails.spec.ts` checks.\n */\nexport const RETENTION_DOCS_PATHS = {\n  'docs.verifyEmailUrl':\n    '/workspace-and-billing/signing-in-and-sessions#verifying-your-email',\n  'docs.generateSiteUrl': '/ai/generate-a-site',\n  'docs.publishUrl': '/getting-started/publish-your-first-screen',\n  'docs.connectDomainUrl': '/building-sites/custom-domains/connect-a-domain',\n  'docs.formsUrl': '/content-and-data/forms/overview',\n  'docs.generateSectionUrl': '/ai/generate-section',\n  'docs.copyAssistUrl': '/ai/copy-assist',\n} as const\n\nexport type RetentionDocsToken = keyof typeof RETENTION_DOCS_PATHS\n\n/**\n * Every docs link as a merge value, on the given docs origin. The console\n * passes its own docs origin (`DOCS_BASE_URL`), so a self-hosted deployment\n * links its own docs build.\n */\nexport function retentionDocsMergeValues(\n  docsOrigin: string,\n): Record<RetentionDocsToken, string> {\n  const origin = docsOrigin.trim().replace(/\\/+$/, '')\n  return Object.fromEntries(\n    Object.entries(RETENTION_DOCS_PATHS).map(([token, path]) => [\n      token,\n      `${origin}${path}`,\n    ]),\n  ) as Record<RetentionDocsToken, string>\n}\n\n/**\n * The retention emails that are product tips, governed by the account's\n * product email answer. The verification reminder is not one of them.\n */\nexport const PRODUCT_TIP_RETENTION_EMAILS: ReadonlySet<string> = new Set([\n  RETENTION_BUILD_SITE_EMAIL,\n  RETENTION_PUBLISH_REMINDER_EMAIL,\n  RETENTION_IDLE_EMAIL,\n  RETENTION_NEXT_STEPS_EMAIL,\n])\n\n/**\n * The getting-started entries, built on the catalog's sample console origin.\n *\n * A function rather than a constant so that origin is the catalog's own\n * `SAMPLE_CONSOLE_ORIGIN`, one reading of `NEXT_PUBLIC_CONSOLE_URL` for every\n * preview sample, rather than a second spelled-out default here.\n */\nexport function retentionSystemEmailTemplates(\n  SAMPLE_CONSOLE_ORIGIN: string,\n  SAMPLE_DOCS_ORIGIN: string,\n): readonly SystemEmailTemplateDefinition[] {\n  const docsSamples = retentionDocsMergeValues(SAMPLE_DOCS_ORIGIN)\n  const DOCS_TOKEN = (\n    name: RetentionDocsToken,\n    description: string,\n  ): SystemEmailMergeToken => ({ name, description, sample: docsSamples[name] })\n\n  const NAME_TOKEN: SystemEmailMergeToken = {\n    name: 'name',\n    description: \"The account holder's first name, or “there”\",\n    sample: 'Alex',\n  }\n\n  const SITE_NAME_TOKEN: SystemEmailMergeToken = {\n    name: 'site.name',\n    description: 'The name of their site',\n    sample: 'Test Site',\n  }\n\n  const CTA_TOKEN: SystemEmailMergeToken = {\n    name: 'ctaUrl',\n    description: 'Where the button opens in the console',\n    sample: `${SAMPLE_CONSOLE_ORIGIN}/test-org/hosts/test-site`,\n  }\n\n  const PREFERENCES_TOKEN: SystemEmailMergeToken = {\n    name: 'preferencesUrl',\n    description: 'The product email switch in account settings',\n    sample: `${SAMPLE_CONSOLE_ORIGIN}/manage/user/emails`,\n  }\n\n  // The house opt-out line, as `notification` and the digests word it.\n  const PREFERENCES_CAPTION: SystemEmailDefaultBlock = {\n    block: 'text',\n    text: 'Change what you are emailed about: {{preferencesUrl}}',\n    variant: 'caption',\n  }\n\n  return [\n    {\n      key: RETENTION_VERIFY_REMINDER_EMAIL,\n      name: 'Getting started: confirm your email',\n      description:\n        'Sent about an hour, and again a day, after sign-up to an account ' +\n        'that has not confirmed its email address. Carries a fresh link.',\n      deliveredBy: 'resend',\n      defaultSubject:\n        'Confirm your email to open your {{brand.productName}} workspace',\n      mergeTokens: [\n        NAME_TOKEN,\n        {\n          name: 'verifyUrl',\n          description: 'One-time link that confirms the address',\n          sample: `${SAMPLE_CONSOLE_ORIGIN}/verify-email?oobCode=…`,\n        },\n        DOCS_TOKEN(\n          'docs.verifyEmailUrl',\n          'Docs: verifying your email, under Signing in & sessions',\n        ),\n      ],\n      defaultBody: [\n        {\n          block: 'text',\n          text: 'Confirm your email to finish signing up',\n          variant: 'heading',\n        },\n        {\n          block: 'text',\n          text:\n            'Hi {{name}}, you started a {{brand.productName}} account but your ' +\n            'email address is not confirmed yet. Confirm it and your ' +\n            'workspace opens, ready for your website.',\n          variant: 'body',\n        },\n        { block: 'button', label: 'Confirm my email', href: '{{verifyUrl}}' },\n        {\n          block: 'text',\n          text:\n            'The link works once and expires soon. If you did not sign up, ' +\n            'ignore this email and nothing happens.',\n          variant: 'caption',\n        },\n        {\n          block: 'text',\n          text: 'Link expired or not arriving? See verifying your email: {{docs.verifyEmailUrl}}',\n          variant: 'caption',\n        },\n      ],\n      footerReason:\n        'You’re receiving this because this address was used to sign up ' +\n        'for {{brand.productName}} and has not been confirmed.',\n      source: 'apps/console/app/api/admin/retention-emails/route.ts',\n    },\n    {\n      key: RETENTION_BUILD_SITE_EMAIL,\n      name: 'Getting started: build your site',\n      description:\n        'Sent a day, and again three days, after sign-up to a confirmed ' +\n        'account with no page of its own yet: no workspace, no site, or ' +\n        'only the starter pages.',\n      deliveredBy: 'resend',\n      defaultSubject: 'Your website is a few minutes away',\n      mergeTokens: [\n        NAME_TOKEN,\n        CTA_TOKEN,\n        DOCS_TOKEN('docs.generateSiteUrl', 'Docs: generate a website from a prompt'),\n        PREFERENCES_TOKEN,\n      ],\n      defaultBody: [\n        {\n          block: 'text',\n          text: 'Build your website with {{brand.productName}} AI',\n          variant: 'heading',\n        },\n        {\n          block: 'text',\n          text:\n            'Hi {{name}}, your account is ready, but your site has no pages ' +\n            'of your own yet. Describe your business in a sentence and ' +\n            '{{brand.productName}} AI builds a full website for you, with ' +\n            'pages, photos and copy you can edit. Your first AI site is ' +\n            'included on the Free plan, and you can start right now.',\n          variant: 'body',\n        },\n        {\n          block: 'text',\n          text: 'Prefer to start by hand? Add a page from your dashboard and pick a layout.',\n          variant: 'body',\n        },\n        { block: 'button', label: 'Build my site', href: '{{ctaUrl}}' },\n        {\n          block: 'text',\n          text: 'How a site is built from your description, step by step: {{docs.generateSiteUrl}}',\n          variant: 'caption',\n        },\n        PREFERENCES_CAPTION,\n      ],\n      footerReason:\n        'You’re receiving this because you signed up for ' +\n        '{{brand.productName}} and have not added a page yet.',\n      source: 'apps/console/app/api/admin/retention-emails/route.ts',\n    },\n    {\n      key: RETENTION_PUBLISH_REMINDER_EMAIL,\n      name: 'Getting started: publish your changes',\n      description:\n        'Sent once to an account that edited pages a day or more ago and ' +\n        'has published none of its own work.',\n      deliveredBy: 'resend',\n      defaultSubject: 'Your changes on {{site.name}} are not live yet',\n      mergeTokens: [\n        NAME_TOKEN,\n        SITE_NAME_TOKEN,\n        CTA_TOKEN,\n        DOCS_TOKEN('docs.publishUrl', 'Docs: publish your first page'),\n        PREFERENCES_TOKEN,\n      ],\n      defaultBody: [\n        {\n          block: 'text',\n          text: 'Your edits are saved, not published',\n          variant: 'heading',\n        },\n        {\n          block: 'text',\n          text:\n            'Hi {{name}}, you edited pages on {{site.name}}, and those ' +\n            'changes are saved. Visitors will not see them until you ' +\n            'publish.',\n          variant: 'body',\n        },\n        { block: 'button', label: 'Review and publish', href: '{{ctaUrl}}' },\n        {\n          block: 'text',\n          text: 'How previewing and publishing a page works: {{docs.publishUrl}}',\n          variant: 'caption',\n        },\n        PREFERENCES_CAPTION,\n      ],\n      footerReason:\n        'You’re receiving this because you have unpublished changes on a ' +\n        '{{brand.productName}} site.',\n      source: 'apps/console/app/api/admin/retention-emails/route.ts',\n    },\n    {\n      key: RETENTION_IDLE_EMAIL,\n      name: 'Getting started: pick up where you left off',\n      description:\n        'Sent 7 days, and again 14 days, after the last sign-in of an ' +\n        'account that has worked on its site. Once per quiet spell; coming ' +\n        'back resets it.',\n      deliveredBy: 'resend',\n      defaultSubject: 'Pick up where you left off on {{site.name}}',\n      mergeTokens: [\n        NAME_TOKEN,\n        SITE_NAME_TOKEN,\n        CTA_TOKEN,\n        DOCS_TOKEN('docs.generateSectionUrl', 'Docs: generate a section on the canvas'),\n        DOCS_TOKEN('docs.copyAssistUrl', 'Docs: rewrite and write copy with AI'),\n        PREFERENCES_TOKEN,\n      ],\n      defaultBody: [\n        {\n          block: 'text',\n          text: 'Pick up where you left off on {{site.name}}',\n          variant: 'heading',\n        },\n        {\n          block: 'text',\n          text:\n            'Hi {{name}}, it has been a little while since you worked on ' +\n            '{{site.name}}. Your pages are where you left them. A new ' +\n            'section, a fresh photo or an updated page keeps the site ' +\n            'current for the people who find it.',\n          variant: 'body',\n        },\n        {\n          block: 'text',\n          text:\n            'Short on time? {{brand.productName}} AI can build a new section ' +\n            'or rewrite the words on a page from one sentence.',\n          variant: 'body',\n        },\n        { block: 'button', label: 'Open my site', href: '{{ctaUrl}}' },\n        {\n          block: 'text',\n          text:\n            'Build a section with AI: {{docs.generateSectionUrl}}\\n' +\n            'Rewrite your copy with AI: {{docs.copyAssistUrl}}',\n          variant: 'caption',\n        },\n        PREFERENCES_CAPTION,\n      ],\n      footerReason:\n        'You’re receiving this because you have a site on ' +\n        '{{brand.productName}} and have not signed in for a while.',\n      source: 'apps/console/app/api/admin/retention-emails/route.ts',\n    },\n    {\n      key: RETENTION_NEXT_STEPS_EMAIL,\n      name: 'Getting started: your site is live',\n      description:\n        'Sent once, after an account first publishes pages of its own: ' +\n        'what to do next, a custom domain and a contact form.',\n      deliveredBy: 'resend',\n      defaultSubject: '{{site.name}} is live: what to do next',\n      mergeTokens: [\n        NAME_TOKEN,\n        SITE_NAME_TOKEN,\n        {\n          name: 'siteUrl',\n          description: 'The published site',\n          sample: 'https://www.example.com',\n        },\n        {\n          name: 'domainUrl',\n          description: 'The site’s domain settings in the console',\n          sample: `${SAMPLE_CONSOLE_ORIGIN}/test-org/hosts/test-site/admin/domain`,\n        },\n        {\n          name: 'formsUrl',\n          description: 'The site’s forms in the console',\n          sample: `${SAMPLE_CONSOLE_ORIGIN}/test-org/hosts/test-site/forms`,\n        },\n        DOCS_TOKEN('docs.connectDomainUrl', 'Docs: connect a domain'),\n        DOCS_TOKEN('docs.formsUrl', 'Docs: forms and lead capture'),\n        PREFERENCES_TOKEN,\n      ],\n      defaultBody: [\n        { block: 'text', text: '{{site.name}} is live', variant: 'heading' },\n        {\n          block: 'text',\n          text:\n            'Hi {{name}}, your pages are published and anyone with the link ' +\n            'can see them: {{siteUrl}}',\n          variant: 'body',\n        },\n        {\n          block: 'text',\n          text:\n            'Three things that help people find and reach you:\\n' +\n            '1. Connect your own domain, so the address is yours.\\n' +\n            '2. Add a contact form, so visitors can reach you from any ' +\n            'page: {{formsUrl}}\\n' +\n            '3. Share the link where your customers already are.',\n          variant: 'body',\n        },\n        { block: 'button', label: 'Connect a domain', href: '{{domainUrl}}' },\n        {\n          block: 'text',\n          text:\n            'Connect a domain, step by step: {{docs.connectDomainUrl}}\\n' +\n            'Add a form and read its submissions: {{docs.formsUrl}}',\n          variant: 'caption',\n        },\n        PREFERENCES_CAPTION,\n      ],\n      footerReason:\n        'You’re receiving this because you published a site on ' +\n        '{{brand.productName}}.',\n      source: 'apps/console/app/api/admin/retention-emails/route.ts',\n    },\n  ]\n}\n"],"names":["RETENTION_VERIFY_REMINDER_EMAIL","RETENTION_BUILD_SITE_EMAIL","RETENTION_PUBLISH_REMINDER_EMAIL","RETENTION_IDLE_EMAIL","RETENTION_NEXT_STEPS_EMAIL","RETENTION_DOCS_PATHS","retentionDocsMergeValues","docsOrigin","origin","trim","replace","Object","fromEntries","entries","map","token","path","PRODUCT_TIP_RETENTION_EMAILS","Set","retentionSystemEmailTemplates","SAMPLE_CONSOLE_ORIGIN","SAMPLE_DOCS_ORIGIN","docsSamples","DOCS_TOKEN","name","description","sample","NAME_TOKEN","SITE_NAME_TOKEN","CTA_TOKEN","PREFERENCES_TOKEN","PREFERENCES_CAPTION","block","text","variant","key","deliveredBy","defaultSubject","mergeTokens","defaultBody","label","href","footerReason","source"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8CC,GAQD,OAAO,MAAMA,kCAAkC,4BAA2B;AAC1E,OAAO,MAAMC,6BAA6B,uBAAsB;AAChE,OAAO,MAAMC,mCAAmC,6BAA4B;AAC5E,OAAO,MAAMC,uBAAuB,iBAAgB;AACpD,OAAO,MAAMC,6BAA6B,uBAAsB;AAEhE;;;;;CAKC,GACD,OAAO,MAAMC,uBAAuB;IAClC,uBACE;IACF,wBAAwB;IACxB,mBAAmB;IACnB,yBAAyB;IACzB,iBAAiB;IACjB,2BAA2B;IAC3B,sBAAsB;AACxB,EAAU;AAIV;;;;CAIC,GACD,OAAO,SAASC,yBACdC,UAAkB;IAElB,MAAMC,SAASD,WAAWE,IAAI,GAAGC,OAAO,CAAC,QAAQ;IACjD,OAAOC,OAAOC,WAAW,CACvBD,OAAOE,OAAO,CAACR,sBAAsBS,GAAG,CAAC,CAAC,CAACC,OAAOC,KAAK,GAAK;YAC1DD;YACA,GAAGP,SAASQ,MAAM;SACnB;AAEL;AAEA;;;CAGC,GACD,OAAO,MAAMC,+BAAoD,IAAIC,IAAI;IACvEjB;IACAC;IACAC;IACAC;CACD,EAAC;AAEF;;;;;;CAMC,GACD,OAAO,SAASe,8BACdC,qBAA6B,EAC7BC,kBAA0B;IAE1B,MAAMC,cAAchB,yBAAyBe;IAC7C,MAAME,aAAa,CACjBC,MACAC,cAC2B,CAAA;YAAED;YAAMC;YAAaC,QAAQJ,WAAW,CAACE,KAAK;QAAC,CAAA;IAE5E,MAAMG,aAAoC;QACxCH,MAAM;QACNC,aAAa;QACbC,QAAQ;IACV;IAEA,MAAME,kBAAyC;QAC7CJ,MAAM;QACNC,aAAa;QACbC,QAAQ;IACV;IAEA,MAAMG,YAAmC;QACvCL,MAAM;QACNC,aAAa;QACbC,QAAQ,GAAGN,sBAAsB,yBAAyB,CAAC;IAC7D;IAEA,MAAMU,oBAA2C;QAC/CN,MAAM;QACNC,aAAa;QACbC,QAAQ,GAAGN,sBAAsB,mBAAmB,CAAC;IACvD;IAEA,qEAAqE;IACrE,MAAMW,sBAA+C;QACnDC,OAAO;QACPC,MAAM;QACNC,SAAS;IACX;IAEA,OAAO;QACL;YACEC,KAAKnC;YACLwB,MAAM;YACNC,aACE,sEACA;YACFW,aAAa;YACbC,gBACE;YACFC,aAAa;gBACXX;gBACA;oBACEH,MAAM;oBACNC,aAAa;oBACbC,QAAQ,GAAGN,sBAAsB,uBAAuB,CAAC;gBAC3D;gBACAG,WACE,uBACA;aAEH;YACDgB,aAAa;gBACX;oBACEP,OAAO;oBACPC,MAAM;oBACNC,SAAS;gBACX;gBACA;oBACEF,OAAO;oBACPC,MACE,uEACA,6DACA;oBACFC,SAAS;gBACX;gBACA;oBAAEF,OAAO;oBAAUQ,OAAO;oBAAoBC,MAAM;gBAAgB;gBACpE;oBACET,OAAO;oBACPC,MACE,mEACA;oBACFC,SAAS;gBACX;gBACA;oBACEF,OAAO;oBACPC,MAAM;oBACNC,SAAS;gBACX;aACD;YACDQ,cACE,oEACA;YACFC,QAAQ;QACV;QACA;YACER,KAAKlC;YACLuB,MAAM;YACNC,aACE,oEACA,oEACA;YACFW,aAAa;YACbC,gBAAgB;YAChBC,aAAa;gBACXX;gBACAE;gBACAN,WAAW,wBAAwB;gBACnCO;aACD;YACDS,aAAa;gBACX;oBACEP,OAAO;oBACPC,MAAM;oBACNC,SAAS;gBACX;gBACA;oBACEF,OAAO;oBACPC,MACE,oEACA,+DACA,kEACA,gEACA;oBACFC,SAAS;gBACX;gBACA;oBACEF,OAAO;oBACPC,MAAM;oBACNC,SAAS;gBACX;gBACA;oBAAEF,OAAO;oBAAUQ,OAAO;oBAAiBC,MAAM;gBAAa;gBAC9D;oBACET,OAAO;oBACPC,MAAM;oBACNC,SAAS;gBACX;gBACAH;aACD;YACDW,cACE,qDACA;YACFC,QAAQ;QACV;QACA;YACER,KAAKjC;YACLsB,MAAM;YACNC,aACE,qEACA;YACFW,aAAa;YACbC,gBAAgB;YAChBC,aAAa;gBACXX;gBACAC;gBACAC;gBACAN,WAAW,mBAAmB;gBAC9BO;aACD;YACDS,aAAa;gBACX;oBACEP,OAAO;oBACPC,MAAM;oBACNC,SAAS;gBACX;gBACA;oBACEF,OAAO;oBACPC,MACE,+DACA,6DACA;oBACFC,SAAS;gBACX;gBACA;oBAAEF,OAAO;oBAAUQ,OAAO;oBAAsBC,MAAM;gBAAa;gBACnE;oBACET,OAAO;oBACPC,MAAM;oBACNC,SAAS;gBACX;gBACAH;aACD;YACDW,cACE,qEACA;YACFC,QAAQ;QACV;QACA;YACER,KAAKhC;YACLqB,MAAM;YACNC,aACE,kEACA,uEACA;YACFW,aAAa;YACbC,gBAAgB;YAChBC,aAAa;gBACXX;gBACAC;gBACAC;gBACAN,WAAW,2BAA2B;gBACtCA,WAAW,sBAAsB;gBACjCO;aACD;YACDS,aAAa;gBACX;oBACEP,OAAO;oBACPC,MAAM;oBACNC,SAAS;gBACX;gBACA;oBACEF,OAAO;oBACPC,MACE,iEACA,8DACA,8DACA;oBACFC,SAAS;gBACX;gBACA;oBACEF,OAAO;oBACPC,MACE,qEACA;oBACFC,SAAS;gBACX;gBACA;oBAAEF,OAAO;oBAAUQ,OAAO;oBAAgBC,MAAM;gBAAa;gBAC7D;oBACET,OAAO;oBACPC,MACE,2DACA;oBACFC,SAAS;gBACX;gBACAH;aACD;YACDW,cACE,sDACA;YACFC,QAAQ;QACV;QACA;YACER,KAAK/B;YACLoB,MAAM;YACNC,aACE,mEACA;YACFW,aAAa;YACbC,gBAAgB;YAChBC,aAAa;gBACXX;gBACAC;gBACA;oBACEJ,MAAM;oBACNC,aAAa;oBACbC,QAAQ;gBACV;gBACA;oBACEF,MAAM;oBACNC,aAAa;oBACbC,QAAQ,GAAGN,sBAAsB,sCAAsC,CAAC;gBAC1E;gBACA;oBACEI,MAAM;oBACNC,aAAa;oBACbC,QAAQ,GAAGN,sBAAsB,+BAA+B,CAAC;gBACnE;gBACAG,WAAW,yBAAyB;gBACpCA,WAAW,iBAAiB;gBAC5BO;aACD;YACDS,aAAa;gBACX;oBAAEP,OAAO;oBAAQC,MAAM;oBAAyBC,SAAS;gBAAU;gBACnE;oBACEF,OAAO;oBACPC,MACE,oEACA;oBACFC,SAAS;gBACX;gBACA;oBACEF,OAAO;oBACPC,MACE,wDACA,2DACA,+DACA,yBACA;oBACFC,SAAS;gBACX;gBACA;oBAAEF,OAAO;oBAAUQ,OAAO;oBAAoBC,MAAM;gBAAgB;gBACpE;oBACET,OAAO;oBACPC,MACE,gEACA;oBACFC,SAAS;gBACX;gBACAH;aACD;YACDW,cACE,2DACA;YACFC,QAAQ;QACV;KACD;AACH"}

package/src/lib/send-email.d.ts

@@ -56,6 +56,14 @@ export interface SendEmailOptions {
     /** Delivery tags for the opens/clicks webhook. */
     tags?: EmailTag[];
     replyTo?: string | string[];
+    /**
+     * Blind copies (AGL-3699): addresses that receive the same message without
+     * appearing on it — a review platform's invitation inbox copied on an order
+     * email, for one. Never a second customer: a blind copy is not screened by
+     * the deliverability preflight or the marketing gate, which ask about the
+     * `to` recipients, so a marketing send refuses any.
+     */
+    bcc?: string | string[];
     /**
      * White-label display name for the sender (White-Label Phase 1). Replaces
      * only the display name in front of the verified address — the address

package/src/lib/send-email.js

@@ -280,7 +280,7 @@ function normalizeRecipients(to) {
  * `{ sent: false, reason: 'unconfigured' }` rather than failing, so local and
  * preview environments keep working without a mail provider.
  */ export async function sendEmail(options) {
-    var _ref, _ref1, _ref2, _ref3, _ref4, _options_text;
+    var _ref, _ref1, _ref2, _ref3, _ref4, _options_bcc, _options_text;
     var _options_sendingIdentity, _options_sendingIdentity1, _options_marketing, _preflight_refused, _preflight_held, _options_marketing1, _options_marketing2, _options_headers;
     const provider = mailProvider();
     const configuredFrom = process.env.USAGE_EMAIL_FROM || undefined;
@@ -467,6 +467,16 @@ function normalizeRecipients(to) {
    */ let unsubscribeUrl = (_ref3 = (_options_marketing1 = options.marketing) == null ? void 0 : _options_marketing1.unsubscribeUrl) != null ? _ref3 : '';
     let oneClickUrl = (_ref4 = (_options_marketing2 = options.marketing) == null ? void 0 : _options_marketing2.oneClickUrl) != null ? _ref4 : '';
     if (options.marketing) {
+        var _options_bcc1;
+        if (normalizeRecipients((_options_bcc1 = options.bcc) != null ? _options_bcc1 : []).length) {
+            // A blind copy of a marketing send is mail the gate never asked about.
+            console.error(`${label} refused — a marketing send carries no blind copies`);
+            return {
+                sent: false,
+                reason: 'no-recipient',
+                detail: 'A marketing send carries no blind copies.'
+            };
+        }
         if (to.length !== 1) {
             // Not a delivery outcome — a caller error, and one that would put the
             // first recipient's signed unsubscribe link in everybody else's copy.
@@ -590,14 +600,20 @@ function normalizeRecipients(to) {
    *     into an outage on the product is a worse bug than the burst it was
    *     guarding. The same posture `sendEmail` takes everywhere else: it
    *     never throws, and neither does this.
-   */ const priority = resolveSendPriority(options.context, options.priority);
+   */ // Blind copies, de-duplicated against the visible recipients: an address
+    // on both would receive the message twice.
+    const visible = new Set(to.map((address)=>address.toLowerCase()));
+    const bcc = [
+        ...new Set(normalizeRecipients((_options_bcc = options.bcc) != null ? _options_bcc : []).filter((address)=>!visible.has(address.toLowerCase())))
+    ];
+    const priority = resolveSendPriority(options.context, options.priority);
     const governor = getEmailSendGovernor();
     if (governor) {
         let verdict;
         try {
             verdict = await governor({
                 priority,
-                count: to.length,
+                count: to.length + bcc.length,
                 context: options.context
             });
         } catch (error) {
@@ -667,6 +683,8 @@ function normalizeRecipients(to) {
             tags
         } : {}, options.replyTo ? {
             replyTo: options.replyTo
+        } : {}, bcc.length ? {
+            bcc
         } : {}), options.context);
         if (!outcome.accepted) {
             var _refusal_detail;