@aglyn/plugins-commerce 1.0.0-beta.143

package/src/lib/server/native-checkout.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/commerce/src/lib/server/native-checkout.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\nimport { isServerReleaseFlagOnForOrg } from '@aglyn/tenant-data-admin'\n\n/**\n * The storefront Payment Element (AGL-1944), the half of native payments\n * AGL-1132 said mattered more: a shopper on a merchant's own domain pays\n * without being bounced to `checkout.stripe.com` and back.\n *\n * ## Why a Checkout Session and not a bare PaymentIntent\n *\n * AGL-1132 recommended \"PaymentIntent + `<PaymentElement/>`\" for this surface,\n * and AGL-1944 asked for that to be a conscious re-decision rather than an\n * inherited one. It is: the Payment Element ships, the bare PaymentIntent does\n * not, and the difference is worth stating because it is the whole safety\n * argument.\n *\n * A PaymentIntent-backed flow would have to own totals, tax, shipping and the\n * platform fee itself — which means a SECOND place that computes what a shopper\n * owes. Two paths that price a cart independently is how a storefront starts\n * under-collecting tax without anyone noticing: nothing fails, the number is\n * just quietly wrong on one of them. It also emits `payment_intent.succeeded`\n * rather than `checkout.session.completed`, so every fulfilment branch in\n * `billing-webhook.ts` — orders, inventory, coupons, gift cards, licence keys,\n * subscriptions — would need a parallel implementation reading a different\n * object shape.\n *\n * `ui_mode: 'custom'` is the Payment Element backed by a Checkout Session. The\n * shopper sees `<PaymentElement/>` inside the merchant's own layout — no Stripe\n * chrome, which is the thing AGL-1944 objected to about embedded Checkout — and\n * the server keeps the session builder it already has. So:\n *\n *   - tax, shipping, inventory, coupons, the Connect destination and the fee\n *     ladder are the SAME code, not a parallel implementation. Parity is by\n *     construction rather than by test;\n *   - `checkout.session.completed` still fires, so `billing-webhook.ts` needs\n *     no change at all and stays the only thing that fulfils an order.\n *\n * ## The API version, and why it is pinned per-request\n *\n * Measured against live Stripe in test mode: `ui_mode: 'custom'` is refused at\n * the platform account's default API version with\n *\n *     Invalid Stripe API version: 2020-08-27. In order to use `ui_mode:\n *     custom`, you must upgrade to Stripe API version 2025-03-31.basil.\n *\n * Upgrading the ACCOUNT default would re-version every Stripe call in this\n * repo at once — a change whose blast radius nobody could review in one pass.\n * A `Stripe-Version` header pins one request instead, and the pin is contained\n * in a way worth being explicit about: webhook deliveries are versioned per\n * ENDPOINT, not per request, so the events `billing-webhook.ts` parses keep\n * arriving in exactly the shape it already reads. The only thing read off the\n * pinned response is `client_secret` and `id`, neither of which the version\n * affects.\n *\n * Same probe, same params (line items, a manual tax line,\n * `shipping_address_collection`, a `fixed_amount` shipping option, Connect\n * `transfer_data[destination]` and `application_fee_amount`), hosted vs custom:\n * `amount_total` **6212 in both**. That is the tax-and-shipping parity claim,\n * measured rather than assumed.\n *\n * ## What this module deliberately does NOT do\n *\n * It does not fulfil anything, and it hands the browser nothing it could use to\n * claim an order was paid. The client gets a `clientSecret` — which is an\n * instruction to Stripe, not an assertion about money — and the same\n * `session_id` the redirect flow already put in the return URL. Fulfilment\n * remains `checkout.session.completed` in `billing-webhook.ts`, exactly as with\n * the redirect. An in-page flow makes trusting the browser tempting; the\n * browser is the one participant that can lie about having paid.\n */\n\n/**\n * The API version `ui_mode: 'custom'` needs, pinned on the session-create\n * request only. Stated once so the header and the doc comment cannot drift.\n */\nexport const NATIVE_CHECKOUT_STRIPE_VERSION = '2025-03-31.basil'\n\n/** The flag both halves of native checkout share (AGL-1132, AGL-1944). */\nexport const NATIVE_CHECKOUT_FLAG = 'release_native_checkout' as const\n\nexport interface NativeCheckoutMode {\n  /** True only when the flag is on for this org AND a publishable key exists. */\n  native: boolean\n  /** Empty unless `native` — the client needs it to boot Stripe.js. */\n  publishableKey: string\n}\n\n/**\n * Two conditions, not one — the same pairing the console's route settled on.\n *\n * A `ui_mode` session returns a `client_secret` and NO `url`, so a browser that\n * cannot mount Stripe.js has nothing to navigate to. If the flag alone decided\n * this, flipping it in an environment without\n * `NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY` would replace a working redirect with a\n * dead Buy button on every storefront at once. Requiring the key here means the\n * worst case of a premature flag flip is the redirect we already ship.\n *\n * That is not hypothetical for the storefront. Measured on 2026-08-18 through\n * the Vercel REST API (`vercel env ls` cannot see team-shared vars):\n * `NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY` exists as a project-level var on\n * `aglyn-console` and is set NOWHERE on `aglyn-tenant`, which is the project\n * that serves storefronts. So today this resolves to `native: false` in\n * production however the flag is set, and the shopper keeps the redirect.\n *\n * The org — never the host — is the rollout bucket, per AGL-1656: a hostId and\n * an orgId hash to different buckets, so bucketing on the host could land a\n * merchant's storefront and their console on opposite sides of the same\n * percentage.\n */\nexport async function resolveNativeCheckoutMode(\n  orgId: string | null | undefined,\n): Promise<NativeCheckoutMode> {\n  const publishableKey = String(\n    process.env.NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY ?? '',\n  ).trim()\n  if (!publishableKey) return { native: false, publishableKey: '' }\n  // A flag lookup that throws must not take a sale down with it, and the catch\n  // is a `try` rather than `.catch()` deliberately: Remote Config being\n  // unreachable rejects, but the resolver being absent entirely — an\n  // environment where the module never loaded — throws SYNCHRONOUSLY, before\n  // there is a promise to attach a handler to. Only the block form covers both.\n  // Either way the answer is the same and it is the safe one: the redirect.\n  let on: boolean\n  try {\n    on = await isServerReleaseFlagOnForOrg(NATIVE_CHECKOUT_FLAG, orgId ?? null)\n  } catch {\n    return { native: false, publishableKey: '' }\n  }\n  return on ? { native: true, publishableKey } : { native: false, publishableKey: '' }\n}\n\n/**\n * Rewrite a built session param set for the Payment Element, in place.\n *\n * DELETES `success_url` and `cancel_url` rather than leaving them alongside\n * `return_url`: Stripe rejects the pair outright on a `ui_mode` session, and a\n * 400 here would surface to the shopper as \"Checkout failed\" on a store that\n * was working an hour ago. Everything else in the param set — line items, the\n * tax line, `automatic_tax`, shipping options, the Connect destination, the\n * application fee, every `metadata[…]` key the webhook reads — is left exactly\n * as the caller built it. That is the point: this function must be incapable of\n * changing what the shopper is charged.\n *\n * `returnUrl` is the caller's OWN `success_url` string, `{CHECKOUT_SESSION_ID}`\n * placeholder and all. Stripe substitutes it on a `ui_mode: 'custom'` return\n * exactly as it does on a hosted redirect (measured), so the storefront's\n * post-purchase reporting — which reads `session_id` off the query to name the\n * order it just completed (AGL-1641) — keeps working unchanged.\n */\nexport function applyNativeCheckoutParams(\n  params: URLSearchParams,\n  returnUrl: string,\n): void {\n  params.delete('success_url')\n  params.delete('cancel_url')\n  params.set('ui_mode', 'custom')\n  params.set('return_url', returnUrl)\n}\n\n/**\n * The `Stripe-Version` pin, as headers to spread into the session-create fetch.\n * Empty for the hosted path so its request is byte-identical to today's.\n */\nexport function nativeCheckoutStripeHeaders(\n  mode: NativeCheckoutMode,\n): Record<string, string> {\n  return mode.native\n    ? { 'Stripe-Version': NATIVE_CHECKOUT_STRIPE_VERSION }\n    : {}\n}\n\nexport interface NativeCheckoutPayload {\n  /** Stripe's own instruction to the browser. Not a claim that money moved. */\n  clientSecret: string\n  publishableKey: string\n  /** The order document id, and the `session_id` the return URL carries. */\n  sessionId: string\n}\n\nexport interface HostedCheckoutPayload {\n  url: string\n}\n\n/**\n * Read the created session into the payload the storefront gets back.\n *\n * Returns `null` when the session is unusable, which BOTH callers already treat\n * as \"nothing was sold\" — release the idempotency claim and answer 502. The\n * null case is the whole reason this is a function rather than a ternary: the\n * hosted path's liveness check was `!session.url`, and a `ui_mode` session\n * never has one. Left unchanged, switching a store to native mode would have\n * made every successful session look like a Stripe failure — a 502 to the\n * shopper, a released claim, and a real Checkout Session left open on the\n * account. So the check has to move with the mode, and it does.\n */\nexport function readCheckoutSessionPayload(\n  session: { url?: string; id?: string; client_secret?: string },\n  mode: NativeCheckoutMode,\n): NativeCheckoutPayload | HostedCheckoutPayload | null {\n  if (!mode.native) return session?.url ? { url: session.url } : null\n  if (!session?.client_secret || !session?.id) return null\n  return {\n    clientSecret: String(session.client_secret),\n    publishableKey: mode.publishableKey,\n    sessionId: String(session.id),\n  }\n}\n"],"names":["isServerReleaseFlagOnForOrg","NATIVE_CHECKOUT_STRIPE_VERSION","NATIVE_CHECKOUT_FLAG","resolveNativeCheckoutMode","orgId","process","publishableKey","String","env","NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY","trim","native","on","applyNativeCheckoutParams","params","returnUrl","delete","set","nativeCheckoutStripeHeaders","mode","readCheckoutSessionPayload","session","url","client_secret","id","clientSecret","sessionId"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED,SAASA,2BAA2B,QAAQ,2BAA0B;AAEtE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAkEC,GAED;;;CAGC,GACD,OAAO,MAAMC,iCAAiC,mBAAkB;AAEhE,wEAAwE,GACxE,OAAO,MAAMC,uBAAuB,0BAAkC;AAStE;;;;;;;;;;;;;;;;;;;;;CAqBC,GACD,OAAO,eAAeC,0BACpBC,KAAgC;QAG9BC;IADF,MAAMC,iBAAiBC,QACrBF,kDAAAA,QAAQG,GAAG,CAACC,kCAAkC,YAA9CJ,kDAAkD,IAClDK,IAAI;IACN,IAAI,CAACJ,gBAAgB,OAAO;QAAEK,QAAQ;QAAOL,gBAAgB;IAAG;IAChE,6EAA6E;IAC7E,sEAAsE;IACtE,mEAAmE;IACnE,2EAA2E;IAC3E,8EAA8E;IAC9E,0EAA0E;IAC1E,IAAIM;IACJ,IAAI;QACFA,KAAK,MAAMZ,4BAA4BE,sBAAsBE,gBAAAA,QAAS;IACxE,EAAE,eAAM;QACN,OAAO;YAAEO,QAAQ;YAAOL,gBAAgB;QAAG;IAC7C;IACA,OAAOM,KAAK;QAAED,QAAQ;QAAML;IAAe,IAAI;QAAEK,QAAQ;QAAOL,gBAAgB;IAAG;AACrF;AAEA;;;;;;;;;;;;;;;;;CAiBC,GACD,OAAO,SAASO,0BACdC,MAAuB,EACvBC,SAAiB;IAEjBD,OAAOE,MAAM,CAAC;IACdF,OAAOE,MAAM,CAAC;IACdF,OAAOG,GAAG,CAAC,WAAW;IACtBH,OAAOG,GAAG,CAAC,cAAcF;AAC3B;AAEA;;;CAGC,GACD,OAAO,SAASG,4BACdC,IAAwB;IAExB,OAAOA,KAAKR,MAAM,GACd;QAAE,kBAAkBV;IAA+B,IACnD,CAAC;AACP;AAcA;;;;;;;;;;;CAWC,GACD,OAAO,SAASmB,2BACdC,OAA8D,EAC9DF,IAAwB;IAExB,IAAI,CAACA,KAAKR,MAAM,EAAE,OAAOU,CAAAA,2BAAAA,QAASC,GAAG,IAAG;QAAEA,KAAKD,QAAQC,GAAG;IAAC,IAAI;IAC/D,IAAI,EAACD,2BAAAA,QAASE,aAAa,KAAI,EAACF,2BAAAA,QAASG,EAAE,GAAE,OAAO;IACpD,OAAO;QACLC,cAAclB,OAAOc,QAAQE,aAAa;QAC1CjB,gBAAgBa,KAAKb,cAAc;QACnCoB,WAAWnB,OAAOc,QAAQG,EAAE;IAC9B;AACF"}

package/src/lib/server/newsletter.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @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.
+ */
+import type { PluginApiHandler } from '@aglyn/aglyn/server';
+/**
+ * Newsletter opt-in (AGL-301): footer signups and checkout opt-ins land
+ * in the contacts CRM with an explicit consent timestamp, feeding the
+ * email-campaign audiences.
+ */
+export declare const newsletterHandler: PluginApiHandler;

package/src/lib/server/newsletter.js

@@ -0,0 +1,323 @@
+/**
+ * @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.
+ */ import { _ as _extends } from "@swc/helpers/_/_extends";
+import { hostPublicOrigin } from "@aglyn/aglyn/app-utils/host-naming";
+import { mergeEmailTopics, normalizeEmailTopic, topicRequiresDoubleOptIn, EMAIL_TOPICS_COLLECTION } from "@aglyn/aglyn/app-utils/email-topics";
+import { enrollListMember, firebaseAdmin, hostSendingIdentity, meterHostEmail, consentGroupForSite, orgDataCollectionForHost, recordPendingTopicConfirmation, resolveCampaignTouch, resolveOrgIdForHost, siteRequiresDoubleOptIn } from "@aglyn/tenant-data-admin";
+import { captureHostContact } from "@aglyn/tenant-runtime";
+import { buildConfirmUrl } from "@aglyn/tenant-data-admin/server/email-unsubscribe-link";
+import { sendEmail } from "@aglyn/shared-util-email";
+import { isDocumentId } from "@aglyn/tenant-data-admin/server/document-id";
+const EMAIL_PATTERN = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+/**
+ * The stream a newsletter signup joins.
+ *
+ * The built-in id, not the campaign default: somebody typing their address
+ * into a footer box is asking for the newsletter, and attributing it to
+ * "Promotions and offers" would confirm them for a stream they did not name.
+ */ const NEWSLETTER_TOPIC_ID = 'newsletter';
+/**
+ * Enrolls one address into an org list's members (AGL-2499).
+ *
+ * The document id comes from `enrollListMember`, which is the only writer of
+ * that collection — the workflow `enrollList` step reaches it too, and when
+ * the two derived their own ids the same person subscribing by both routes
+ * became two members of one list.
+ *
+ * Best-effort and silent on any problem: list enrollment rides along with
+ * the newsletter signup, which must still succeed (and still upsert the
+ * contact) even when the list id is stale, was mistyped into the besigner
+ * prop, or belongs to an org this host cannot resolve.
+ */ async function enrollInList(options) {
+    if (!isDocumentId(options.listId)) return;
+    try {
+        var _contactsRef_parent;
+        const contactsRef = await orgDataCollectionForHost(options.hostId, 'contacts');
+        const listRef = (_contactsRef_parent = contactsRef.parent) == null ? void 0 : _contactsRef_parent.collection('lists').doc(options.listId);
+        if (!listRef) return;
+        const listSnapshot = await listRef.get();
+        // A stale/mistyped id must not silently CREATE a list — campaign-send's
+        // `list` audience would then read a list nobody set up.
+        if (!listSnapshot.exists) return;
+        await enrollListMember(_extends({
+            listRef,
+            group: await consentGroupForSite(options.hostId),
+            email: options.email
+        }, options.name ? {
+            name: options.name
+        } : {}, {
+            source: 'newsletter'
+        }, options.marketingConsent ? {
+            marketingConsent: true
+        } : {}));
+    } catch (error) {
+        console.error('list enrollment failed', error);
+    }
+}
+/**
+ * DOUBLE OPT-IN, when this site asks for one
+ * (`docs/specs/email-competitive-gaps.md` P8).
+ *
+ * A footer signup is where a confirmation belongs — ActiveCampaign's shape,
+ * where forms are the thing that default to it — and it is the only capture
+ * path in the product where the person is present, expecting a reply, and has
+ * just typed the address themselves.
+ *
+ * ## The confirmation message is TRANSACTIONAL
+ *
+ * It carries no marketing context, so it passes no frequency cap and adds no
+ * unsubscribe header: somebody who just asked to subscribe is owed the answer
+ * to what they asked, and gating it behind a marketing ceiling would drop
+ * exactly the message that lets them out of the quarantine. The suppression
+ * lists are not consulted here either — `recordPendingTopicConfirmation`
+ * refuses an address that left this stream before any message is composed,
+ * which is the check that matters: a signup form must not become a way to
+ * mail somebody who unsubscribed by asking them again.
+ *
+ * A hard-bounced address is deliberately NOT refused here, and the asymmetry
+ * with the opt-out above is the point. An opt-out is a stated intention; a
+ * bounce is a measurement of a mailbox at a moment, and refusing to send at
+ * submission time would settle it on evidence that cannot be older than the
+ * question being asked. The confirmation goes out, and if it is delivered and
+ * clicked, `confirmTopicSubscription` lifts the platform bounce — the round
+ * trip is what proves the record stale. A complaint or an unsubscribe is
+ * never lifted by that path.
+ *
+ * ## Best-effort, like the enrollment beside it
+ *
+ * A failure to send leaves the address pending and unmailable, which is the
+ * safe direction: they signed up, nothing reaches them, and signing up again
+ * re-sends. The signup itself still succeeds — the contact is captured with
+ * its consent record either way, and losing the capture because a confirmation
+ * bounced would be a worse trade for everybody.
+ *
+ * @returns whether the address was put in the quarantine, so the caller can
+ *          decide whether to enroll them on a list yet.
+ */ async function requestConfirmation(options) {
+    const topic = options.topics.find((candidate)=>candidate.id === NEWSLETTER_TOPIC_ID);
+    const { result } = await recordPendingTopicConfirmation(options.hostId, options.email, NEWSLETTER_TOPIC_ID);
+    if (result !== 'pending') return false;
+    try {
+        var _hostPublicOrigin, _options_host_cname, _options_host_subdomain, _ref;
+        const siteBase = (_hostPublicOrigin = hostPublicOrigin({
+            cname: String((_options_host_cname = options.host.cname) != null ? _options_host_cname : ''),
+            subdomain: String((_options_host_subdomain = options.host.subdomain) != null ? _options_host_subdomain : '')
+        })) != null ? _hostPublicOrigin : '';
+        const url = buildConfirmUrl({
+            siteBase,
+            hostId: options.hostId,
+            email: options.email,
+            topicId: NEWSLETTER_TOPIC_ID
+        });
+        // No origin or no signing secret means no link, and a confirmation
+        // message with nothing to click is worse than none: the person believes
+        // they have subscribed and nothing ever arrives. Said out loud rather
+        // than shipped quietly, exactly as the unsubscribe seam does.
+        if (!url) {
+            console.warn('[newsletter] confirmation not sent — no public origin or no ' + 'EMAIL_UNSUBSCRIBE_SECRET');
+            return true;
+        }
+        const stream = (_ref = topic == null ? void 0 : topic.name) != null ? _ref : 'our newsletter';
+        const result = await sendEmail({
+            to: options.email,
+            subject: `Confirm your subscription`,
+            text: `Please confirm that you want to receive ${stream} at this ` + `address:\n\n${url}\n\nThe link works for three days. If you did ` + 'not sign up, ignore this message — nothing will be sent.',
+            sendingIdentity: await hostSendingIdentity(options.hostId),
+            audience: 'tenant',
+            context: 'newsletter confirmation'
+        });
+        /*
+     * Counted against the site, as TRANSACTIONAL.
+     *
+     * It is a message this site sent, so it costs what a message costs and
+     * the meter has to see it. `'transactional'` is the honest class: the
+     * person just typed their address into a form and is waiting for the
+     * answer, which is why the message carries no marketing context and no
+     * unsubscribe header either. Only a delivery is counted, so a send that
+     * never left is not billed as one.
+     */ if (result.sent) await meterHostEmail(options.hostId);
+    } catch (error) {
+        console.error('confirmation send failed', error);
+    }
+    return true;
+}
+/**
+ * The site's topic catalog, for the one question the signup asks of it.
+ *
+ * Fails soft to the built-ins, like the preference page's read: a site whose
+ * org cannot be resolved still gets the four defaults, so the decision is
+ * made against a catalog rather than against nothing.
+ */ async function loadTopics(hostId) {
+    try {
+        var _ref;
+        const orgId = await resolveOrgIdForHost(hostId);
+        if (!orgId) return mergeEmailTopics(null);
+        const snapshot = await firebaseAdmin.app().firestore().collection('orgs').doc(orgId).collection(EMAIL_TOPICS_COLLECTION).get();
+        return mergeEmailTopics(((_ref = snapshot == null ? void 0 : snapshot.docs) != null ? _ref : []).map((doc)=>normalizeEmailTopic(doc.id, doc.data())).filter((topic)=>!!topic));
+    } catch (error) {
+        console.error('[newsletter] topic catalog read failed', error);
+        return mergeEmailTopics(null);
+    }
+}
+/**
+ * Everything the confirmation decision needs, in one round trip.
+ *
+ * Three reads — the host document, the org lookup and the topic catalog — and
+ * the first is issued IN PARALLEL with the other two rather than after them,
+ * because none of the three depends on another's answer. A signup is a person
+ * waiting for a form to come back, and serialized reads on that path are
+ * latency the person feels for a decision that is usually "no".
+ *
+ * The host document is returned rather than discarded: the confirmation link
+ * needs the site's public origin, which is on that same document, and reading
+ * it twice would be a read per signup to recover something already in hand.
+ *
+ * Fails soft on the site flag, which `siteRequiresDoubleOptIn` already does —
+ * a default a failed read could switch ON would quarantine every new signup
+ * on a site whose owner never asked for confirmations.
+ */ async function loadHostGate(hostId) {
+    const [topics, siteDefault, snapshot] = await Promise.all([
+        loadTopics(hostId),
+        siteRequiresDoubleOptIn(hostId),
+        firebaseAdmin.app().firestore().collection('hosts').doc(hostId).get().catch(()=>null)
+    ]);
+    return {
+        topics,
+        siteDefault,
+        host: {
+            cname: snapshot == null ? void 0 : snapshot.get('cname'),
+            subdomain: snapshot == null ? void 0 : snapshot.get('subdomain')
+        }
+    };
+}
+// Best-effort per-instance flood damper.
+const attemptsByIp = new Map();
+import { NO_CLIENT_ADDRESS_BUCKET, readClientIp } from "@aglyn/aglyn/app-utils/request-ip";
+/**
+ * Newsletter opt-in (AGL-301): footer signups and checkout opt-ins land
+ * in the contacts CRM with an explicit consent timestamp, feeding the
+ * email-campaign audiences.
+ */ export const newsletterHandler = async (req, res)=>{
+    var _req_body, _body_hostId, _body_email, _body_listId, _readClientIp, _attemptsByIp_get;
+    var _req_socket;
+    if (req.method !== 'POST') {
+        return res.status(405).json({
+            error: 'Method not allowed'
+        });
+    }
+    const body = typeof req.body === 'string' ? JSON.parse(req.body) : (_req_body = req.body) != null ? _req_body : {};
+    const hostId = String((_body_hostId = body.hostId) != null ? _body_hostId : '');
+    const email = String((_body_email = body.email) != null ? _body_email : '').trim().toLowerCase();
+    const listId = String((_body_listId = body.listId) != null ? _body_listId : '').trim();
+    if (!hostId || !EMAIL_PATTERN.test(email)) {
+        return res.status(400).json({
+            error: 'Enter a valid email'
+        });
+    }
+    // Keeps counting under the no-address bucket rather than being skipped: an
+    // unauthenticated signup endpoint that stops counting is an open write into
+    // the contacts CRM.
+    const ip = (_readClientIp = readClientIp(req.headers, {
+        remoteAddress: (_req_socket = req.socket) == null ? void 0 : _req_socket.remoteAddress
+    })) != null ? _readClientIp : NO_CLIENT_ADDRESS_BUCKET;
+    const now = Date.now();
+    const attempts = ((_attemptsByIp_get = attemptsByIp.get(ip)) != null ? _attemptsByIp_get : []).filter((at)=>now - at < 60000);
+    attempts.push(now);
+    attemptsByIp.set(ip, attempts);
+    if (attempts.length > 10) {
+        return res.status(429).json({
+            error: 'Too many attempts'
+        });
+    }
+    try {
+        // A newsletter signup is an identify moment: the visitor was anonymous
+        // while they browsed and this request is the first thing that names them.
+        // Both channels are asked once, here, and the later touch is credited.
+        const campaignTouch = await resolveCampaignTouch({
+            hostId,
+            wire: body.campaignTouch,
+            email,
+            atMs: now
+        });
+        await captureHostContact(_extends({
+            hostId,
+            email,
+            source: 'newsletter',
+            // The stage the name is for (AGL-2612): somebody who asked to hear
+            // from the site and nothing more yet.
+            initialLifecycleStage: 'subscriber',
+            marketingConsent: true,
+            interaction: {
+                refId: `newsletter-${now}`,
+                summary: 'Subscribed to the newsletter'
+            }
+        }, campaignTouch ? {
+            campaignTouch
+        } : {}));
+        /*
+     * The confirmation, when this site asks for one.
+     *
+     * AFTER the contact upsert and never instead of it. The person typed
+     * their address and ticked a box, and that consent record is a fact
+     * whether or not they go on to click a link — withholding the capture
+     * until they do would lose the record of what they actually did. What the
+     * confirmation gates is the SEND, on the person's own topic entry, which
+     * is where `filterTopicSendable` reads it.
+     */ const { topics, siteDefault, host } = await loadHostGate(hostId);
+        const confirming = topicRequiresDoubleOptIn(topics.find((topic)=>topic.id === NEWSLETTER_TOPIC_ID), siteDefault) && await requestConfirmation({
+            hostId,
+            email,
+            topics,
+            host
+        });
+        if (listId) {
+            /*
+       * The same basis the contact upsert records, on the membership too.
+       *
+       * A list membership had no consent field at all, so `audience: 'list'`
+       * gave the send-time join nothing to read even for the one audience
+       * whose members literally asked for a newsletter
+       * (`docs/specs/email-overhaul.md` §1d). This is a DECLARED opt-in and
+       * not an inference from an act: the request this handler serves is
+       * "subscribe me", which is the checkbox.
+       */ await enrollInList({
+                hostId,
+                listId,
+                email,
+                marketingConsent: true
+            });
+        }
+        /*
+     * The caller is told which of the two things happened, so the signup form
+     * can say "check your email" rather than "you're subscribed".
+     *
+     * A form that reported success identically either way would be the site
+     * telling somebody they are on the list while the send path refuses them,
+     * and the only way they could find out is by noticing that nothing
+     * arrives.
+     */ return res.status(200).json({
+            ok: true,
+            confirmationRequired: confirming
+        });
+    } catch (error) {
+        console.error(error);
+        return res.status(500).json({
+            error: 'Signup failed'
+        });
+    }
+};
+
+//# sourceMappingURL=newsletter.js.map

package/src/lib/server/newsletter.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/commerce/src/lib/server/newsletter.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\nimport type { PluginApiHandler } from '@aglyn/aglyn/server'\nimport { hostPublicOrigin } from '@aglyn/aglyn/app-utils/host-naming'\nimport {\n  mergeEmailTopics,\n  normalizeEmailTopic,\n  topicRequiresDoubleOptIn,\n  EMAIL_TOPICS_COLLECTION,\n  type EmailTopic,\n} from '@aglyn/aglyn/app-utils/email-topics'\nimport {\n  enrollListMember,\n  firebaseAdmin,\n  hostSendingIdentity,\n  meterHostEmail,\n  consentGroupForSite,\n  orgDataCollectionForHost,\n  recordPendingTopicConfirmation,\n  resolveCampaignTouch,\n  resolveOrgIdForHost,\n  siteRequiresDoubleOptIn,\n} from '@aglyn/tenant-data-admin'\nimport { captureHostContact } from '@aglyn/tenant-runtime'\nimport { buildConfirmUrl } from '@aglyn/tenant-data-admin/server/email-unsubscribe-link'\nimport { sendEmail } from '@aglyn/shared-util-email'\nimport { isDocumentId } from '@aglyn/tenant-data-admin/server/document-id'\n\nconst EMAIL_PATTERN = /^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$/\n\n/**\n * The stream a newsletter signup joins.\n *\n * The built-in id, not the campaign default: somebody typing their address\n * into a footer box is asking for the newsletter, and attributing it to\n * \"Promotions and offers\" would confirm them for a stream they did not name.\n */\nconst NEWSLETTER_TOPIC_ID = 'newsletter'\n\n/**\n * Enrolls one address into an org list's members (AGL-2499).\n *\n * The document id comes from `enrollListMember`, which is the only writer of\n * that collection — the workflow `enrollList` step reaches it too, and when\n * the two derived their own ids the same person subscribing by both routes\n * became two members of one list.\n *\n * Best-effort and silent on any problem: list enrollment rides along with\n * the newsletter signup, which must still succeed (and still upsert the\n * contact) even when the list id is stale, was mistyped into the besigner\n * prop, or belongs to an org this host cannot resolve.\n */\nasync function enrollInList(options: {\n  hostId: string\n  listId: string\n  email: string\n  name?: string\n  /** The opt-in the signup itself carries — see the call site. */\n  marketingConsent?: boolean\n}): Promise<void> {\n  if (!isDocumentId(options.listId)) return\n  try {\n    const contactsRef = await orgDataCollectionForHost(options.hostId, 'contacts')\n    const listRef = contactsRef.parent?.collection('lists').doc(options.listId)\n    if (!listRef) return\n    const listSnapshot = await listRef.get()\n    // A stale/mistyped id must not silently CREATE a list — campaign-send's\n    // `list` audience would then read a list nobody set up.\n    if (!listSnapshot.exists) return\n    await enrollListMember({\n      listRef,\n      group: await consentGroupForSite(options.hostId),\n      email: options.email,\n      ...(options.name ? { name: options.name } : {}),\n      source: 'newsletter',\n      ...(options.marketingConsent ? { marketingConsent: true } : {}),\n    })\n  } catch (error) {\n    console.error('list enrollment failed', error)\n  }\n}\n\n/**\n * DOUBLE OPT-IN, when this site asks for one\n * (`docs/specs/email-competitive-gaps.md` P8).\n *\n * A footer signup is where a confirmation belongs — ActiveCampaign's shape,\n * where forms are the thing that default to it — and it is the only capture\n * path in the product where the person is present, expecting a reply, and has\n * just typed the address themselves.\n *\n * ## The confirmation message is TRANSACTIONAL\n *\n * It carries no marketing context, so it passes no frequency cap and adds no\n * unsubscribe header: somebody who just asked to subscribe is owed the answer\n * to what they asked, and gating it behind a marketing ceiling would drop\n * exactly the message that lets them out of the quarantine. The suppression\n * lists are not consulted here either — `recordPendingTopicConfirmation`\n * refuses an address that left this stream before any message is composed,\n * which is the check that matters: a signup form must not become a way to\n * mail somebody who unsubscribed by asking them again.\n *\n * A hard-bounced address is deliberately NOT refused here, and the asymmetry\n * with the opt-out above is the point. An opt-out is a stated intention; a\n * bounce is a measurement of a mailbox at a moment, and refusing to send at\n * submission time would settle it on evidence that cannot be older than the\n * question being asked. The confirmation goes out, and if it is delivered and\n * clicked, `confirmTopicSubscription` lifts the platform bounce — the round\n * trip is what proves the record stale. A complaint or an unsubscribe is\n * never lifted by that path.\n *\n * ## Best-effort, like the enrollment beside it\n *\n * A failure to send leaves the address pending and unmailable, which is the\n * safe direction: they signed up, nothing reaches them, and signing up again\n * re-sends. The signup itself still succeeds — the contact is captured with\n * its consent record either way, and losing the capture because a confirmation\n * bounced would be a worse trade for everybody.\n *\n * @returns whether the address was put in the quarantine, so the caller can\n *          decide whether to enroll them on a list yet.\n */\nasync function requestConfirmation(options: {\n  hostId: string\n  email: string\n  topics: EmailTopic[]\n  /** The host document the setting was read from — see {@link loadHostGate}. */\n  host: { cname?: unknown; subdomain?: unknown }\n}): Promise<boolean> {\n  const topic = options.topics.find(\n    (candidate) => candidate.id === NEWSLETTER_TOPIC_ID,\n  )\n  const { result } = await recordPendingTopicConfirmation(\n    options.hostId,\n    options.email,\n    NEWSLETTER_TOPIC_ID,\n  )\n  if (result !== 'pending') return false\n  try {\n    const siteBase =\n      hostPublicOrigin({\n        cname: String(options.host.cname ?? ''),\n        subdomain: String(options.host.subdomain ?? ''),\n      }) ?? ''\n    const url = buildConfirmUrl({\n      siteBase,\n      hostId: options.hostId,\n      email: options.email,\n      topicId: NEWSLETTER_TOPIC_ID,\n    })\n    // No origin or no signing secret means no link, and a confirmation\n    // message with nothing to click is worse than none: the person believes\n    // they have subscribed and nothing ever arrives. Said out loud rather\n    // than shipped quietly, exactly as the unsubscribe seam does.\n    if (!url) {\n      console.warn(\n        '[newsletter] confirmation not sent — no public origin or no ' +\n          'EMAIL_UNSUBSCRIBE_SECRET',\n      )\n      return true\n    }\n    const stream = topic?.name ?? 'our newsletter'\n    const result = await sendEmail({\n      to: options.email,\n      subject: `Confirm your subscription`,\n      text:\n        `Please confirm that you want to receive ${stream} at this ` +\n        `address:\\n\\n${url}\\n\\nThe link works for three days. If you did ` +\n        'not sign up, ignore this message — nothing will be sent.',\n      sendingIdentity: await hostSendingIdentity(options.hostId),\n      audience: 'tenant',\n      context: 'newsletter confirmation',\n    })\n    /*\n     * Counted against the site, as TRANSACTIONAL.\n     *\n     * It is a message this site sent, so it costs what a message costs and\n     * the meter has to see it. `'transactional'` is the honest class: the\n     * person just typed their address into a form and is waiting for the\n     * answer, which is why the message carries no marketing context and no\n     * unsubscribe header either. Only a delivery is counted, so a send that\n     * never left is not billed as one.\n     */\n    if (result.sent) await meterHostEmail(options.hostId)\n  } catch (error) {\n    console.error('confirmation send failed', error)\n  }\n  return true\n}\n\n/**\n * The site's topic catalog, for the one question the signup asks of it.\n *\n * Fails soft to the built-ins, like the preference page's read: a site whose\n * org cannot be resolved still gets the four defaults, so the decision is\n * made against a catalog rather than against nothing.\n */\nasync function loadTopics(hostId: string): Promise<EmailTopic[]> {\n  try {\n    const orgId = await resolveOrgIdForHost(hostId)\n    if (!orgId) return mergeEmailTopics(null)\n    const snapshot = await firebaseAdmin\n      .app()\n      .firestore()\n      .collection('orgs')\n      .doc(orgId)\n      .collection(EMAIL_TOPICS_COLLECTION)\n      .get()\n    return mergeEmailTopics(\n      (snapshot?.docs ?? [])\n        .map((doc: any) => normalizeEmailTopic(doc.id, doc.data()))\n        .filter((topic: EmailTopic | null): topic is EmailTopic => !!topic),\n    )\n  } catch (error) {\n    console.error('[newsletter] topic catalog read failed', error)\n    return mergeEmailTopics(null)\n  }\n}\n\n/**\n * Everything the confirmation decision needs, in one round trip.\n *\n * Three reads — the host document, the org lookup and the topic catalog — and\n * the first is issued IN PARALLEL with the other two rather than after them,\n * because none of the three depends on another's answer. A signup is a person\n * waiting for a form to come back, and serialized reads on that path are\n * latency the person feels for a decision that is usually \"no\".\n *\n * The host document is returned rather than discarded: the confirmation link\n * needs the site's public origin, which is on that same document, and reading\n * it twice would be a read per signup to recover something already in hand.\n *\n * Fails soft on the site flag, which `siteRequiresDoubleOptIn` already does —\n * a default a failed read could switch ON would quarantine every new signup\n * on a site whose owner never asked for confirmations.\n */\nasync function loadHostGate(hostId: string): Promise<{\n  topics: EmailTopic[]\n  siteDefault: boolean\n  host: { cname?: unknown; subdomain?: unknown }\n}> {\n  const [topics, siteDefault, snapshot] = await Promise.all([\n    loadTopics(hostId),\n    siteRequiresDoubleOptIn(hostId),\n    firebaseAdmin\n      .app()\n      .firestore()\n      .collection('hosts')\n      .doc(hostId)\n      .get()\n      .catch(() => null),\n  ])\n  return {\n    topics,\n    siteDefault,\n    host: {\n      cname: snapshot?.get('cname'),\n      subdomain: snapshot?.get('subdomain'),\n    },\n  }\n}\n\n// Best-effort per-instance flood damper.\nconst attemptsByIp = new Map<string, number[]>()\nimport {\n  NO_CLIENT_ADDRESS_BUCKET,\n  readClientIp,\n} from '@aglyn/aglyn/app-utils/request-ip'\n\n/**\n * Newsletter opt-in (AGL-301): footer signups and checkout opt-ins land\n * in the contacts CRM with an explicit consent timestamp, feeding the\n * email-campaign audiences.\n */\nexport const newsletterHandler: PluginApiHandler = async (req, res) => {\n  if (req.method !== 'POST') {\n    return res.status(405).json({ error: 'Method not allowed' })\n  }\n  const body =\n    typeof req.body === 'string' ? JSON.parse(req.body) : (req.body ?? {})\n  const hostId = String(body.hostId ?? '')\n  const email = String(body.email ?? '')\n    .trim()\n    .toLowerCase()\n  const listId = String(body.listId ?? '').trim()\n  if (!hostId || !EMAIL_PATTERN.test(email)) {\n    return res.status(400).json({ error: 'Enter a valid email' })\n  }\n  // Keeps counting under the no-address bucket rather than being skipped: an\n  // unauthenticated signup endpoint that stops counting is an open write into\n  // the contacts CRM.\n  const ip =\n    readClientIp(req.headers, { remoteAddress: req.socket?.remoteAddress }) ??\n    NO_CLIENT_ADDRESS_BUCKET\n  const now = Date.now()\n  const attempts = (attemptsByIp.get(ip) ?? []).filter(\n    (at) => now - at < 60_000,\n  )\n  attempts.push(now)\n  attemptsByIp.set(ip, attempts)\n  if (attempts.length > 10) {\n    return res.status(429).json({ error: 'Too many attempts' })\n  }\n  try {\n    // A newsletter signup is an identify moment: the visitor was anonymous\n    // while they browsed and this request is the first thing that names them.\n    // Both channels are asked once, here, and the later touch is credited.\n    const campaignTouch = await resolveCampaignTouch({\n      hostId,\n      wire: body.campaignTouch,\n      email,\n      atMs: now,\n    })\n    await captureHostContact({\n      hostId,\n      email,\n      source: 'newsletter',\n      // The stage the name is for (AGL-2612): somebody who asked to hear\n      // from the site and nothing more yet.\n      initialLifecycleStage: 'subscriber',\n      marketingConsent: true,\n      interaction: {\n        refId: `newsletter-${now}`,\n        summary: 'Subscribed to the newsletter',\n      },\n      ...(campaignTouch ? { campaignTouch } : {}),\n    })\n    /*\n     * The confirmation, when this site asks for one.\n     *\n     * AFTER the contact upsert and never instead of it. The person typed\n     * their address and ticked a box, and that consent record is a fact\n     * whether or not they go on to click a link — withholding the capture\n     * until they do would lose the record of what they actually did. What the\n     * confirmation gates is the SEND, on the person's own topic entry, which\n     * is where `filterTopicSendable` reads it.\n     */\n    const { topics, siteDefault, host } = await loadHostGate(hostId)\n    const confirming =\n      topicRequiresDoubleOptIn(\n        topics.find((topic) => topic.id === NEWSLETTER_TOPIC_ID),\n        siteDefault,\n      ) && (await requestConfirmation({ hostId, email, topics, host }))\n    if (listId) {\n      /*\n       * The same basis the contact upsert records, on the membership too.\n       *\n       * A list membership had no consent field at all, so `audience: 'list'`\n       * gave the send-time join nothing to read even for the one audience\n       * whose members literally asked for a newsletter\n       * (`docs/specs/email-overhaul.md` §1d). This is a DECLARED opt-in and\n       * not an inference from an act: the request this handler serves is\n       * \"subscribe me\", which is the checkbox.\n       */\n      await enrollInList({ hostId, listId, email, marketingConsent: true })\n    }\n    /*\n     * The caller is told which of the two things happened, so the signup form\n     * can say \"check your email\" rather than \"you're subscribed\".\n     *\n     * A form that reported success identically either way would be the site\n     * telling somebody they are on the list while the send path refuses them,\n     * and the only way they could find out is by noticing that nothing\n     * arrives.\n     */\n    return res.status(200).json({ ok: true, confirmationRequired: confirming })\n  } catch (error) {\n    console.error(error)\n    return res.status(500).json({ error: 'Signup failed' })\n  }\n}\n"],"names":["hostPublicOrigin","mergeEmailTopics","normalizeEmailTopic","topicRequiresDoubleOptIn","EMAIL_TOPICS_COLLECTION","enrollListMember","firebaseAdmin","hostSendingIdentity","meterHostEmail","consentGroupForSite","orgDataCollectionForHost","recordPendingTopicConfirmation","resolveCampaignTouch","resolveOrgIdForHost","siteRequiresDoubleOptIn","captureHostContact","buildConfirmUrl","sendEmail","isDocumentId","EMAIL_PATTERN","NEWSLETTER_TOPIC_ID","enrollInList","options","listId","contactsRef","hostId","listRef","parent","collection","doc","listSnapshot","get","exists","group","email","name","source","marketingConsent","error","console","requestConfirmation","topic","topics","find","candidate","id","result","siteBase","cname","String","host","subdomain","url","topicId","warn","stream","to","subject","text","sendingIdentity","audience","context","sent","loadTopics","orgId","snapshot","app","firestore","docs","map","data","filter","loadHostGate","siteDefault","Promise","all","catch","attemptsByIp","Map","NO_CLIENT_ADDRESS_BUCKET","readClientIp","newsletterHandler","req","res","body","method","status","json","JSON","parse","trim","toLowerCase","test","ip","headers","remoteAddress","socket","now","Date","attempts","at","push","set","length","campaignTouch","wire","atMs","initialLifecycleStage","interaction","refId","summary","confirming","ok","confirmationRequired"],"mappings":"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"}

package/src/lib/server/notify-restock.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @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.
+ */
+import type { PluginApiHandler } from '@aglyn/aglyn/server';
+/**
+ * Back-in-stock signup (AGL-326): captures an email for a sold-out
+ * product; the restock cron emails and clears it once stock returns.
+ */
+export declare const notifyRestockHandler: PluginApiHandler;

package/src/lib/server/notify-restock.js

@@ -0,0 +1,84 @@
+/**
+ * @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.
+ */ import { firebaseAdmin } from "@aglyn/tenant-data-admin";
+import { isDocumentId } from "@aglyn/tenant-data-admin/server/document-id";
+const EMAIL_PATTERN = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+/**
+ * Back-in-stock signup (AGL-326): captures an email for a sold-out
+ * product; the restock cron emails and clears it once stock returns.
+ */ export const notifyRestockHandler = async (req, res)=>{
+    var _req_body, _body_hostId, _body_productId, _body_email;
+    if (req.method !== 'POST') {
+        return res.status(405).json({
+            error: 'Method not allowed'
+        });
+    }
+    const body = typeof req.body === 'string' ? JSON.parse(req.body) : (_req_body = req.body) != null ? _req_body : {};
+    const hostId = String((_body_hostId = body.hostId) != null ? _body_hostId : '');
+    const productId = String((_body_productId = body.productId) != null ? _body_productId : '');
+    const email = String((_body_email = body.email) != null ? _body_email : '').trim().toLowerCase();
+    // AGL-1771/AGL-1774: both were checked non-empty and nothing else, on a
+    // handler that needs NO credentials — no session, no member gate, no
+    // signature — and they are not equally dangerous.
+    //
+    // `hostId` is a path component here: `.doc()` appends a SLASH-SEPARATED path
+    // rather than taking one opaque id, so `a/b/c` created the alert under
+    // `hosts/a/b/c/restockAlerts/…`, beneath a document that does not exist and
+    // therefore invisible to every console list, which resolve the host first.
+    //
+    // `productId` is worse precisely because it is NOT a path component here —
+    // it is stored as a FIELD, and `process-restock.ts` makes it a path
+    // component later. An even-component value threw synchronously out of that
+    // cron's `.doc()`, aborting the whole platform-wide run; and because the
+    // alert was never marked `notifiedAtMs` it came back on every later run, so
+    // one anonymous POST stopped back-in-stock email for every merchant,
+    // permanently. A field is not a path until someone makes it one, and the
+    // place to refuse is where it enters (AGL-1774 guards the cron as well, for
+    // the rows written before this).
+    //
+    // Answered separately from the email, following `762621581`: a caller told
+    // only "Enter a valid email" when the ids are the problem goes looking for
+    // the wrong mistake. A shopper never sees this — the storefront widget fills
+    // both ids — so the message is for whoever is driving the endpoint.
+    if (!isDocumentId(hostId) || !isDocumentId(productId)) {
+        return res.status(400).json({
+            error: 'Missing or invalid hostId or productId'
+        });
+    }
+    if (!EMAIL_PATTERN.test(email)) {
+        return res.status(400).json({
+            error: 'Enter a valid email'
+        });
+    }
+    try {
+        await firebaseAdmin.app().firestore().collection('hosts').doc(hostId).collection('restockAlerts').add({
+            productId,
+            email,
+            notifiedAtMs: null,
+            createdAtMs: Date.now()
+        });
+        return res.status(200).json({
+            ok: true
+        });
+    } catch (error) {
+        console.error(error);
+        return res.status(500).json({
+            error: 'Signup failed'
+        });
+    }
+};
+
+//# sourceMappingURL=notify-restock.js.map

package/src/lib/server/notify-restock.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/commerce/src/lib/server/notify-restock.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\nimport type { PluginApiHandler } from '@aglyn/aglyn/server'\nimport { firebaseAdmin } from '@aglyn/tenant-data-admin'\nimport { isDocumentId } from '@aglyn/tenant-data-admin/server/document-id'\n\nconst EMAIL_PATTERN = /^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$/\n\n/**\n * Back-in-stock signup (AGL-326): captures an email for a sold-out\n * product; the restock cron emails and clears it once stock returns.\n */\nexport const notifyRestockHandler: PluginApiHandler = async (req, res) => {\n  if (req.method !== 'POST') {\n    return res.status(405).json({ error: 'Method not allowed' })\n  }\n  const body =\n    typeof req.body === 'string' ? JSON.parse(req.body) : (req.body ?? {})\n  const hostId = String(body.hostId ?? '')\n  const productId = String(body.productId ?? '')\n  const email = String(body.email ?? '').trim().toLowerCase()\n  // AGL-1771/AGL-1774: both were checked non-empty and nothing else, on a\n  // handler that needs NO credentials — no session, no member gate, no\n  // signature — and they are not equally dangerous.\n  //\n  // `hostId` is a path component here: `.doc()` appends a SLASH-SEPARATED path\n  // rather than taking one opaque id, so `a/b/c` created the alert under\n  // `hosts/a/b/c/restockAlerts/…`, beneath a document that does not exist and\n  // therefore invisible to every console list, which resolve the host first.\n  //\n  // `productId` is worse precisely because it is NOT a path component here —\n  // it is stored as a FIELD, and `process-restock.ts` makes it a path\n  // component later. An even-component value threw synchronously out of that\n  // cron's `.doc()`, aborting the whole platform-wide run; and because the\n  // alert was never marked `notifiedAtMs` it came back on every later run, so\n  // one anonymous POST stopped back-in-stock email for every merchant,\n  // permanently. A field is not a path until someone makes it one, and the\n  // place to refuse is where it enters (AGL-1774 guards the cron as well, for\n  // the rows written before this).\n  //\n  // Answered separately from the email, following `762621581`: a caller told\n  // only \"Enter a valid email\" when the ids are the problem goes looking for\n  // the wrong mistake. A shopper never sees this — the storefront widget fills\n  // both ids — so the message is for whoever is driving the endpoint.\n  if (!isDocumentId(hostId) || !isDocumentId(productId)) {\n    return res\n      .status(400)\n      .json({ error: 'Missing or invalid hostId or productId' })\n  }\n  if (!EMAIL_PATTERN.test(email)) {\n    return res.status(400).json({ error: 'Enter a valid email' })\n  }\n  try {\n    await firebaseAdmin\n      .app()\n      .firestore()\n      .collection('hosts')\n      .doc(hostId)\n      .collection('restockAlerts')\n      .add({ productId, email, notifiedAtMs: null, createdAtMs: Date.now() })\n    return res.status(200).json({ ok: true })\n  } catch (error) {\n    console.error(error)\n    return res.status(500).json({ error: 'Signup failed' })\n  }\n}\n"],"names":["firebaseAdmin","isDocumentId","EMAIL_PATTERN","notifyRestockHandler","req","res","body","method","status","json","error","JSON","parse","hostId","String","productId","email","trim","toLowerCase","test","app","firestore","collection","doc","add","notifiedAtMs","createdAtMs","Date","now","ok","console"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAGD,SAASA,aAAa,QAAQ,2BAA0B;AACxD,SAASC,YAAY,QAAQ,8CAA6C;AAE1E,MAAMC,gBAAgB;AAEtB;;;CAGC,GACD,OAAO,MAAMC,uBAAyC,OAAOC,KAAKC;QAKPD,WACnCE,cACGA,iBACJA;IAPrB,IAAIF,IAAIG,MAAM,KAAK,QAAQ;QACzB,OAAOF,IAAIG,MAAM,CAAC,KAAKC,IAAI,CAAC;YAAEC,OAAO;QAAqB;IAC5D;IACA,MAAMJ,OACJ,OAAOF,IAAIE,IAAI,KAAK,WAAWK,KAAKC,KAAK,CAACR,IAAIE,IAAI,KAAKF,YAAAA,IAAIE,IAAI,YAARF,YAAY,CAAC;IACtE,MAAMS,SAASC,QAAOR,eAAAA,KAAKO,MAAM,YAAXP,eAAe;IACrC,MAAMS,YAAYD,QAAOR,kBAAAA,KAAKS,SAAS,YAAdT,kBAAkB;IAC3C,MAAMU,QAAQF,QAAOR,cAAAA,KAAKU,KAAK,YAAVV,cAAc,IAAIW,IAAI,GAAGC,WAAW;IACzD,wEAAwE;IACxE,qEAAqE;IACrE,kDAAkD;IAClD,EAAE;IACF,6EAA6E;IAC7E,uEAAuE;IACvE,4EAA4E;IAC5E,2EAA2E;IAC3E,EAAE;IACF,2EAA2E;IAC3E,oEAAoE;IACpE,2EAA2E;IAC3E,yEAAyE;IACzE,4EAA4E;IAC5E,qEAAqE;IACrE,yEAAyE;IACzE,4EAA4E;IAC5E,iCAAiC;IACjC,EAAE;IACF,2EAA2E;IAC3E,2EAA2E;IAC3E,6EAA6E;IAC7E,oEAAoE;IACpE,IAAI,CAACjB,aAAaY,WAAW,CAACZ,aAAac,YAAY;QACrD,OAAOV,IACJG,MAAM,CAAC,KACPC,IAAI,CAAC;YAAEC,OAAO;QAAyC;IAC5D;IACA,IAAI,CAACR,cAAciB,IAAI,CAACH,QAAQ;QAC9B,OAAOX,IAAIG,MAAM,CAAC,KAAKC,IAAI,CAAC;YAAEC,OAAO;QAAsB;IAC7D;IACA,IAAI;QACF,MAAMV,cACHoB,GAAG,GACHC,SAAS,GACTC,UAAU,CAAC,SACXC,GAAG,CAACV,QACJS,UAAU,CAAC,iBACXE,GAAG,CAAC;YAAET;YAAWC;YAAOS,cAAc;YAAMC,aAAaC,KAAKC,GAAG;QAAG;QACvE,OAAOvB,IAAIG,MAAM,CAAC,KAAKC,IAAI,CAAC;YAAEoB,IAAI;QAAK;IACzC,EAAE,OAAOnB,OAAO;QACdoB,QAAQpB,KAAK,CAACA;QACd,OAAOL,IAAIG,MAAM,CAAC,KAAKC,IAAI,CAAC;YAAEC,OAAO;QAAgB;IACvD;AACF,EAAC"}