@aglyn/plugins-forms 1.0.0-beta.221 → 1.0.0-beta.223

package/src/lib/server/form-submit.js

@@ -0,0 +1,850 @@
+import { _ as _extends } from "@swc/helpers/_/_extends";
+/**
+ * @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 Aglyn from "@aglyn/aglyn/server";
+import { extractEmailFromFields } from "@aglyn/aglyn/server";
+import { consumeRateLimit, firebaseAdmin, getOrgForHost, notifyHostManagers, visitorWriteRefusal } from "@aglyn/tenant-data-admin";
+import { emitHostEvent } from "@aglyn/tenant-runtime";
+import recordCapturedContact from "@aglyn/aglyn/plugin-manager/record-captured-contact";
+// By path: the server-only contract a door credits its outcome through.
+import { CONVERSION_TOUCH_DETAIL, conversionDescriptionSentences, creditConversion, describeConversion, resolveConversionTouch } from "@aglyn/aglyn/plugin-manager/plugin-conversion-credit";
+import { normalizeContainerIds } from "@aglyn/aglyn/app-utils/container-membership";
+import { findScreenIdByRoutePath, screenRoutePathFromUrl } from "@aglyn/aglyn/app-utils/screen-route";
+// The leaf: the Inbox list's search keys, the same function its backfill
+// restates and its query's normalizers read (AGL-3321).
+import { messageSearchFields } from "@aglyn/aglyn/app-utils/message-search";
+// By path: the server-only contract a submission is filed as a record through.
+import { writeFormRecordTarget } from "@aglyn/aglyn/plugin-manager/submission-record-target";
+// By path: where a manager reads submissions, declared by the plugin whose
+// page shows them, for the notifications below (AGL-3080).
+import { pluginRecordPageLink } from "@aglyn/aglyn/plugin-manager/plugin-record-pages";
+import { FieldValue } from "firebase-admin/firestore";
+import { isCredentialFieldName } from "@aglyn/shared-util-email/hosted-page-screen";
+import { FORMS_OFF_FOR_SITE_REFUSAL, formSubmissionDoorPlugin } from "../model/form-door.js";
+import { FORM_ABUSE_CEILING_CODE } from "../model/form-unavailable.js";
+import { incrementFormStats } from "./increment-form-stats.js";
+import { NO_CLIENT_ADDRESS_BUCKET, readClientIp } from "@aglyn/aglyn/app-utils/request-ip";
+const MAX_FIELDS = 20;
+const MAX_PAYLOAD_CHARS = 10000;
+// Per-IP submission limit (AGL-794). Previously a per-instance Map, which on
+// serverless resets each cold start and is held per concurrent instance — so
+// a spammer got roughly RATE_MAX × instances and could widen it by going
+// wider. The monthly plan quota was never the right thing to be defended BY:
+// burning a site's whole allowance is the damage, not the protection — and
+// since AGL-1280 it is not even a wall on a paid plan, it meters. This
+// counter is global, keyed per (site, IP).
+//
+// It is the SHAPE of abuse control, not the whole of it (AGL-1655): 10/60s
+// per address is 14,400/day from one IP and multiplies by the number of
+// addresses, so per-IP alone leaves the site's total unbounded. The per-site
+// monthly ceiling below is what bounds the total.
+const RATE_WINDOW_MS = 60000;
+const RATE_MAX = 10;
+const json = (body, status = 200)=>Response.json(body, {
+        status
+    });
+/**
+ * The ceiling is a per-MONTH count, so the honest retry hint is the month
+ * boundary rather than a made-up interval. UTC, matching `monthKey`.
+ */ const secondsUntilNextMonth = (now = new Date())=>{
+    const next = Date.UTC(now.getUTCFullYear(), now.getUTCMonth() + 1, 1);
+    return Math.max(1, Math.ceil((next - now.getTime()) / 1000));
+};
+/**
+ * The one useful thing a refused visitor can be given (AGL-1666): the site's
+ * OWN published support address, so a lost lead has somewhere else to go.
+ *
+ * Read through the host-token registry rather than reaching into the
+ * document, because that registry is what defines this field as the address
+ * a site publishes to visitors — its description is literally "where
+ * visitors should write for help". Anything else on the host document is
+ * account data and must not leave the console.
+ *
+ * Free: the host snapshot is already loaded for the existence check.
+ */ const publishedContactEmail = (host)=>{
+    var _Aglyn_HOST_TOKENS_supportEmail;
+    return host ? (_Aglyn_HOST_TOKENS_supportEmail = Aglyn.HOST_TOKENS['supportEmail']) == null ? void 0 : _Aglyn_HOST_TOKENS_supportEmail.resolve(host) : undefined;
+};
+/**
+ * Make a tripped ceiling OBSERVABLE (AGL-1655) rather than a silent drop.
+ *
+ * Two audiences, one write. Staff get a durable per-month refusal count at
+ * `hosts/{id}/counters/formSubmissionsRefused` — the same counters-document
+ * shape `contactsDropped` already uses for free-tier contact drops, and
+ * client-unwritable for the same reason (AGL-1367). The site's managers get
+ * one in-app notification, on the FIRST refusal of the month only: a
+ * notification per refused bot request would be the flood again, delivered.
+ *
+ * Best-effort throughout. A bookkeeping failure must not turn a contained
+ * refusal into a 500, because a 500 is a retry invitation.
+ */ async function recordAbuseCeilingTrip(hostRef, hostId, monthKey, ceiling) {
+    try {
+        var _refusedSnapshot_get;
+        const refusedRef = hostRef.collection('counters').doc('formSubmissionsRefused');
+        const refusedSnapshot = await refusedRef.get();
+        const alreadyRefused = Number((_refusedSnapshot_get = refusedSnapshot.get(monthKey)) != null ? _refusedSnapshot_get : 0);
+        await refusedRef.set({
+            [monthKey]: FieldValue.increment(1),
+            // Explicit values only — Firestore rejects `undefined`.
+            ceiling,
+            lastRefusedAtMs: Date.now()
+        }, {
+            merge: true
+        });
+        if (alreadyRefused === 0) {
+            // Every fact here is the route's own (AGL-3432): the refusal sits before
+            // every write, so a refused submission is neither stored nor counted
+            // toward the bill, and the counter is month-keyed, so forms accept
+            // again at the UTC month boundary — the same date the inbox notice
+            // prints. `{site}` is the site's name, filled by `notifyHostManagers`.
+            const reopens = Aglyn.nextUtcMonthStart().toLocaleDateString('en-US', {
+                month: 'long',
+                day: 'numeric',
+                timeZone: 'UTC'
+            });
+            await notifyHostManagers(hostId, _extends({
+                type: 'system.formSubmissionsPaused',
+                title: 'Form submissions paused on {site} — unusual volume',
+                body: `Forms on {site} stopped accepting submissions: the site reached ` + `${ceiling.toLocaleString()} this month, the safety limit for ` + 'unusual volume. Submissions sent now are refused and not saved, ' + `and none of them are billed. Forms accept submissions again on ` + `${reopens}. Contact support if this is real traffic.`
+            }, submissionsLink(hostId)));
+        }
+    } catch (error) {
+        console.error('form abuse ceiling bookkeeping failed', error);
+    }
+}
+/**
+ * A notification's link to where the site's managers read submissions — the
+ * page the plugin that shows `formSubmission` records declares, opened on one
+ * submission when `submissionId` is given and that page can open one — and no
+ * link where no plugin in this build shows them. A key left out rather than
+ * set to `undefined`, which Firestore rejects.
+ */ function submissionsLink(hostId, submissionId) {
+    const link = pluginRecordPageLink('formSubmission', hostId, submissionId);
+    return link ? {
+        link
+    } : {};
+}
+/**
+ * Count a honeypot hit so the bot rate is a NUMBER, not a guess (AGL-1664).
+ *
+ * The attestation decision (App Check / CAPTCHA / neither) asked to be made
+ * on a measured per-host bot rate, and the honeypot was the instrument named
+ * for it — but a hit used to return fake success and record nothing, so the
+ * number it was supposed to produce did not exist. This writes the same
+ * counters-document shape `formSubmissionsRefused` uses (per-month key,
+ * client-unwritable, AGL-1367), keyed per host because "which site is the
+ * bot filling in" is the decision input.
+ *
+ * The host-existence read is the orphan guard: this path runs BEFORE the
+ * route's shape validation, and an attacker spraying invented host ids must
+ * not mint counter documents under hosts that do not exist. Cost per hit is
+ * one read + one write — the same order the legitimate path already pays the
+ * rate limiter — where the old path cost nothing; that is the price of the
+ * measurement, paid only on requests that self-identified as bots.
+ *
+ * No notification, ever: honeypot hits are routine background noise, and a
+ * flood of them delivered as alerts would be the flood again (the
+ * `formSubmissionsPaused` lesson). Best-effort for the same reason the
+ * refusal bookkeeping is — a bookkeeping failure must not turn a dropped bot
+ * request into a 500 retry invitation.
+ */ async function recordHoneypotHit(hostId) {
+    try {
+        if (typeof hostId !== 'string' || !hostId || hostId.length > 128) return;
+        const hostRef = firebaseAdmin.app().firestore().collection('hosts').doc(hostId);
+        if (!(await hostRef.get()).exists) return;
+        await hostRef.collection('counters').doc('formSubmissionsSpam').set({
+            [Aglyn.utcMonthKey()]: FieldValue.increment(1),
+            lastSpamAtMs: Date.now()
+        }, {
+            merge: true
+        });
+    } catch (error) {
+        console.error('honeypot bookkeeping failed', error);
+    }
+}
+/**
+ * The opt-in a form CARRIES, or `false`.
+ *
+ * `upsertHostContact` has accepted `marketingConsent` since AGL-301 and would
+ * stamp `marketingConsentAtMs` from it, and this route passed it zero times —
+ * so a subscribe checkbox a merchant put on their form was collected, stored
+ * as a submission field, and then dropped on the way to the contact. That is
+ * the missing INPUT for the send-time consent join
+ * (`docs/specs/email-overhaul.md` §1d): the join can only ever be as good as
+ * what the capture surfaces record.
+ *
+ * ⛔ THE FACT OF SUBMISSION IS NOT AN OPT-IN. Only a field whose VALUE is a
+ * tick counts, and only under a name that means marketing consent. A form is
+ * submitted to ask a question, book a table or claim a refund, and treating
+ * any of those as a subscription is exactly the inference the consent arc
+ * refused to make.
+ *
+ * What a tick is comes from `isConsentCheckboxTicked`. A box with no text of
+ * its own posts an affirmative value on any form. A Checkboxes field posts
+ * the text of its option, which is a tick only where a BOUND form's stored
+ * `declarations` show that field is a checkbox with exactly one option: an
+ * unbound form has no declaration, and the request never supplies one.
+ *
+ * The name list is `MARKETING_CONSENT_FIELD_NAMES`, closed rather than a
+ * substring match on "consent" (a clinic intake form's `consentToTreatment`
+ * is a different instrument), and shared with the publish check: a design
+ * `checkFormContract` accepts as recording consent is one this route reads
+ * an opt-in from.
+ */ function readDeclaredMarketingConsent(payload, fields, declarations) {
+    // A first-class body field, for a caller that models the checkbox
+    // explicitly rather than as one more form field.
+    if (payload['marketingConsent'] === true) return true;
+    for (const [key, value] of Object.entries(fields)){
+        if (!Aglyn.isMarketingConsentFieldName(key)) continue;
+        const declaration = declarations.find((entry)=>(entry == null ? void 0 : entry.fieldName) === key);
+        if (Aglyn.isConsentCheckboxTicked(value, declaration)) return true;
+    }
+    return false;
+}
+/**
+ * `POST /api/forms/submit` — every form's door, and a Marketing popup's
+ * (AGL-76, AGL-3080).
+ *
+ * This plugin's route, served by the tenant's plugin API dispatcher at the
+ * address it has always had, and registered as a route that KEEPS ITS OWN
+ * VISITOR GATES (`ownVisitorGates`): the dispatcher hands it the request
+ * untouched, because every gate below is a published answer — which plugin's
+ * switch decides a submission (the door it came through, not this route's
+ * owner), the "not accepting" notice a site with Forms off gives, the
+ * per-(site, address) limit and the monthly ceiling, and where lockdown sits
+ * among them. The dispatcher's own versions of those would answer first and
+ * differently.
+ *
+ * Lead-capture submissions endpoint (AGL-76): validates the target host,
+ * drops honeypot hits silently, applies the plan's monthly submission quota
+ * via a per-month counter — a hard wall on free, a meter on plans that carry
+ * the infra pass-through (AGL-1280) — refuses above the per-site abuse
+ * ceiling (AGL-1655), and stores the submission for the console inbox. Writes
+ * go through the admin SDK, so client rules never allow arbitrary submission
+ * writes.
+ *
+ * The two 429s are different answers and must stay distinguishable: the plan
+ * wall means the customer's allowance is spent, the ceiling means the site is
+ * being flooded. Only the ceiling refusal carries `code`.
+ */ export async function POST(request) {
+    var _readClientIp;
+    // The dispatcher serves every method at its catch-all; this door takes a
+    // POST alone, as the route it replaced did.
+    if (request.method !== 'POST') {
+        return new Response(null, {
+            status: 405,
+            headers: {
+                Allow: 'POST'
+            }
+        });
+    }
+    const payload = await request.json().catch(()=>({}));
+    // `datasetId`, `dataset` and `fieldMap` are deliberately not read: the
+    // dataset a record lands in comes from the page's signed binding (below).
+    const { hostId, formId, formName, path, fields, website } = payload;
+    // Honeypot filled → pretend success so bots learn nothing, counted so the
+    // owner of the attestation decision learns something (AGL-1664).
+    if (typeof website === 'string' && website.trim()) {
+        await recordHoneypotHit(hostId);
+        return json({
+            received: true
+        });
+    }
+    if (typeof hostId !== 'string' || !hostId || typeof fields !== 'object' || fields === null || Array.isArray(fields) || Object.keys(fields).length === 0 || Object.keys(fields).length > MAX_FIELDS || JSON.stringify(fields).length > MAX_PAYLOAD_CHARS) {
+        return json({
+            error: 'Invalid submission'
+        }, 400);
+    }
+    // Keeps counting under the no-address bucket rather than being skipped: a
+    // public form endpoint that stops counting is an open write, and the key
+    // already carries the site, so an unreadable address shares one budget per
+    // SITE rather than one across the deployment.
+    const ip = (_readClientIp = readClientIp(request.headers)) != null ? _readClientIp : NO_CLIENT_ADDRESS_BUCKET;
+    const rate = await consumeRateLimit(`form:${hostId}:${ip}`, {
+        limit: RATE_MAX,
+        windowMs: RATE_WINDOW_MS
+    });
+    if (!rate.allowed) {
+        // Note this is NOT told to the caller, degraded or not. The body and the
+        // status are identical either way: "the global limiter is currently a
+        // per-instance one" is exactly the sentence an abuser would spend the
+        // window on, and this endpoint is public and unauthenticated.
+        return Response.json({
+            error: 'Too many submissions'
+        }, {
+            status: 429,
+            headers: {
+                'Retry-After': String(Math.max(1, Math.ceil((rate.resetMs - Date.now()) / 1000)))
+            }
+        });
+    }
+    try {
+        var _ref, _form_get, _ref1;
+        const firestore = firebaseAdmin.app().firestore();
+        const hostRef = firestore.collection('hosts').doc(hostId);
+        const hostSnapshot = await hostRef.get();
+        if (!hostSnapshot.exists) {
+            return json({
+                error: 'Unknown site'
+            }, 404);
+        }
+        // Lockdown (AGL-1511). Placed after the host exists and BEFORE the quota
+        // read and every write: a paused submission must not consume the
+        // customer's monthly allowance, and it must not be half-recorded.
+        // Refused with the visitor pause copy — the site around this form is
+        // still serving, so an outage page here would be both a lie and a lost
+        // lead. The `/api` surface is outside the middleware matcher, so this is
+        // the only lockdown enforcement a form POST ever meets, full or
+        // read-only.
+        const paused = await visitorWriteRefusal({
+            hostId,
+            request,
+            surface: 'form'
+        });
+        if (paused) return paused;
+        // Monthly quota by the owning org's plan (dark-launch: orgs
+        // without a plan are uncapped, matching every other gate).
+        // Plan/quota gates ride the owning org's doc (AGL-238).
+        const owningOrg = await getOrgForHost(hostId);
+        const orgBilling = owningOrg == null ? void 0 : owningOrg.org;
+        /*
+     * A site that switched Forms off accepts no form submission (AGL-3029).
+     *
+     * Asked of the site's own plugin set — the org's resolved set minus this
+     * host's deny-list, the same answer the tenant draws the page from — and
+     * about the plugin whose door the submission came through: a Marketing
+     * popup's capture belongs to Marketing, and keeps working on a site that
+     * still shows the popup. Core imports no plugin, so both are ids.
+     *
+     * Placed after the site is known to exist and before the quota read and
+     * every write: a refused submission is not counted, not billed and not
+     * stored. 404, the answer the route already gives a retired form, because
+     * the honest reply to the visitor is the same — this site takes no form
+     * here — and the sentence names no setting a stranger has no use for.
+     */ if (!Aglyn.isHostPluginEnabled(orgBilling, hostSnapshot.data(), formSubmissionDoorPlugin(payload))) {
+            return json({
+                error: FORMS_OFF_FOR_SITE_REFUSAL
+            }, 404);
+        }
+        // Shared with the console surface that reads these counters back
+        // (AGL-1666) — a differently-derived key there would read 0 refusals on
+        // exactly the sites being refused.
+        const monthKey = Aglyn.utcMonthKey();
+        const counterRef = hostRef.collection('counters').doc('formSubmissions');
+        {
+            var _counterSnapshot_get;
+            // Plan-less orgs resolve as free (AGL-247) — the cap always runs.
+            const counterSnapshot = await counterRef.get();
+            const used = Number((_counterSnapshot_get = counterSnapshot.get(monthKey)) != null ? _counterSnapshot_get : 0);
+            // AGL-1280: a plan with the metered infra pass-through is never cut
+            // off — submissions past the included count bill at cost × 1.3 like
+            // storage, API requests and contacts already do. Free keeps the hard
+            // wall, because there is no subscription to meter onto. A dropped
+            // submission is a lost lead, so this is the meter where being wrong
+            // in the "cut them off" direction costs the customer the most.
+            if (!Aglyn.checkFormSubmissionQuota(orgBilling, used).allowed) {
+                return json({
+                    error: 'Submission limit reached'
+                }, 429);
+            }
+            // Abuse ceiling (AGL-1655). The plan gate above cannot refuse a
+            // metered plan by design, so on every paying customer it was the only
+            // thing between a bot flood and an unbounded invoice — and it always
+            // said yes. The per-IP limiter is 10/60s, which one address turns into
+            // 14,400/day and any number of addresses multiplies.
+            //
+            // This is the ceiling that can say no. It reuses the count already
+            // read above (no extra Firestore read on the happy path) and sits
+            // BEFORE every write, so a refused submission never touches
+            // `counters/formSubmissions` — the document /api/billing/report-usage
+            // invoices from. Refusing and still billing would have been the same
+            // bug with a smaller number.
+            const ceiling = Aglyn.checkFormSubmissionAbuseCeiling(orgBilling, used);
+            if (ceiling.exceeded) {
+                await recordAbuseCeilingTrip(hostRef, hostId, monthKey, ceiling.ceiling);
+                const contact = publishedContactEmail(hostSnapshot.data());
+                return Response.json(_extends({
+                    error: 'Submissions are paused for this site',
+                    // Machine-readable so a client can tell containment apart from
+                    // the plan wall it shares a status with.
+                    code: FORM_ABUSE_CEILING_CODE
+                }, contact ? {
+                    contact
+                } : {}), {
+                    status: 429,
+                    headers: {
+                        'Retry-After': String(secondsUntilNextMonth())
+                    }
+                });
+            }
+        }
+        /*
+     * NO CREDENTIALS, whatever the page asked for (AGL-3356).
+     *
+     * A published page that asks for a password, a card number or a
+     * one-time code in a field of its own is held by the page review before
+     * a visitor sees it. This endpoint is the one path that does not pass a
+     * publish: it takes whatever names a request carries, so a page the
+     * review never read — a marketplace plugin's frame, a hand-built request
+     * — could still post one here. Such a field is dropped, never stored,
+     * never forwarded to a workflow or a contact.
+     */ const sanitizedFields = {};
+        for (const [key, value] of Object.entries(fields)){
+            if (isCredentialFieldName(String(key))) continue;
+            sanitizedFields[String(key).slice(0, 64)] = String(value).slice(0, 2000);
+        }
+        if (!Object.keys(sanitizedFields).length) {
+            return json({
+                error: 'Invalid submission'
+            }, 400);
+        }
+        /*
+     * The bound form entity (`docs/specs/reusable-forms.md` §2c).
+     *
+     * READ AND VERIFIED, never trusted. `formId` arrives in a public,
+     * unauthenticated body, so stamping it unchecked would let anyone file
+     * rows into any form's list on any site — the per-form list is the
+     * surface this id exists to make correct, and an unverified id would make
+     * it wrong in a way that looks right.
+     *
+     * One extra document read, and only when a form is bound. A form with no
+     * `formId` pays nothing, which is the same shape the dataset binding and
+     * `rateDegraded` already take.
+     */ const boundFormId = String(formId != null ? formId : '').trim().slice(0, 128);
+        const formSnapshot = boundFormId ? await hostRef.collection('forms').doc(boundFormId).get() : null;
+        const form = (formSnapshot == null ? void 0 : formSnapshot.exists) ? formSnapshot : null;
+        /*
+     * A RETIRED form collects nothing (AGL-2671).
+     *
+     * Retirement is what a merchant does with a form they have finished with
+     * but must keep — the submissions, the leads and the contact timeline
+     * those built are filed under it. Leaving it able to collect would make
+     * the retirement a UI illusion: the row would be gone from the list and
+     * out of the funnel's grading while a form still placed on a published
+     * page kept filing leads nobody was looking at, which is the quiet half
+     * of a lost lead rather than a retirement.
+     *
+     * Refused HERE, on the verified entity, rather than by unpublishing the
+     * page: a form is placed by whoever placed it, on any number of pages, and
+     * the document is the one place that knows it is retired.
+     *
+     * 404 rather than a 4xx that explains: the visitor's honest answer is that
+     * this form is not here any more, and the shape matches `Unknown site`
+     * above. Only ever for a BOUND form — a submission carrying no `formId`
+     * has no entity to be retired and is untouched.
+     */ if (Aglyn.isFormArchived(form == null ? void 0 : form.data())) {
+            return json({
+                error: 'This form is no longer accepting submissions'
+            }, 404);
+        }
+        /*
+     * The caption follows the entity once one is bound.
+     *
+     * `formName` stays written either way: it is what the pre-entity `?form=`
+     * filter reads, and no phase of this work removes it. Resolving it from
+     * the form's own `displayName` keeps the Inbox's label from going stale
+     * the moment somebody renames a form.
+     *
+     * ⚠️ This does NOT make the legacy filter rename-safe, and it is not
+     * meant to — renaming still splits what `?form=` returns, exactly as it
+     * always did. `formId` is the filter that survives a rename; that is the
+     * whole reason it exists.
+     */ const resolvedFormName = form ? String((_ref = (_form_get = form.get('displayName')) != null ? _form_get : formName) != null ? _ref : 'Form').slice(0, 100) : String(formName != null ? formName : 'Form').slice(0, 100);
+        /*
+     * Consent, from the field the FORM declares.
+     *
+     * ⛔ Still never inferred from the fact of submission. What the entity
+     * adds is a declared place to look: `consentFieldName` names the one
+     * field that IS the opt-in, so a merchant's checkbox called anything at
+     * all is readable, and a clinic intake form's `consentToTreatment` stays
+     * the different instrument it is.
+     *
+     * A bound form that declares NO consent field falls through to the closed
+     * name list below rather than recording nothing. Adoption must not be the
+     * moment a form that was capturing opt-ins stops — consent is carried
+     * forward, never dropped as a side effect of a migration.
+     *
+     * Both readers are handed the form's STORED declaration: a Checkboxes
+     * field posts the text of the option that was ticked, and only the
+     * declaration says a consent field has exactly one option, whose text is
+     * then the tick. An unbound form has none, so its boxes count only by an
+     * affirmative value.
+     */ const formFieldDecls = Array.isArray(form == null ? void 0 : form.get('fields')) ? form == null ? void 0 : form.get('fields') : [];
+        const declaredMarketingConsent = (form == null ? void 0 : form.get('consentFieldName')) ? Aglyn.readFormDeclaredConsent({
+            consentFieldName: String(form.get('consentFieldName')),
+            fields: formFieldDecls
+        }, sanitizedFields) : readDeclaredMarketingConsent(payload, fields, formFieldDecls);
+        /*
+     * THE DISCLOSURE THE FORM SHOWED beside that opt-in (AGL-3320).
+     *
+     * The Form block renders the site's consent-group sentence under its
+     * consent field and posts back the key of what it rendered
+     * (`/api/consent/disclosure`). Passed to the record system as it arrived:
+     * the writer pools the opt-in across the group only when this is the
+     * group's CURRENT key, so a page rendered before a rename or before a
+     * site joined records the one site the visitor was on. Trusting it costs
+     * nothing — it can only ever narrow what the checkbox above already
+     * claims, never widen it past the declaration.
+     */ const disclosedConsentGroup = typeof payload['__consentGroup'] === 'string' ? payload['__consentGroup'].trim().slice(0, 64) : '';
+        /*
+     * THE CAMPAIGNS THE FORM IS FILED UNDER.
+     *
+     * Off the form document this route has already read, so it costs nothing,
+     * and off the VERIFIED form for the same reason the id is: a membership
+     * taken from the request body would let anyone file people into any
+     * campaign on any site.
+     *
+     * ⚠️ NOT the campaign touch resolved below, and the two never write each
+     * other's field. The touch is where this visitor came FROM and is
+     * browser-supplied; this is which campaigns the merchant put the form in,
+     * and it is true of every person who fills that form in — including the
+     * one who arrived by typing the address. Recording only the touch is what
+     * left three forms assigned to a campaign producing contacts that belonged
+     * to none.
+     */ const formCampaignIds = form ? Aglyn.readContainerIds(form.data(), 'campaign') : [];
+        /*
+     * THE CAMPAIGNS THE PAGE IS FILED UNDER (AGL-3461), stamped beside the
+     * form's for the same reason and with the same caveat: where the merchant
+     * filed the page, true of everyone who submits on it, and never a credit.
+     *
+     * The screen is found in the routing map on the host snapshot this route
+     * already holds, from the path the browser sent, so a path naming no page
+     * this site serves names no screen and costs nothing. Its campaigns are
+     * read off the screen document — one read, only when the path resolves.
+     * A failed read stamps nothing rather than failing the submission.
+     */ const pageRoutePath = screenRoutePathFromUrl(typeof path === 'string' ? path : '');
+        const pageScreenId = pageRoutePath ? findScreenIdByRoutePath(hostSnapshot.get('screens'), pageRoutePath) : undefined;
+        const pageCampaignIds = pageScreenId ? await hostRef.collection('screens').doc(pageScreenId).get().then((screen)=>screen.exists ? Aglyn.readContainerIds(screen.data(), 'campaign') : []).catch((error)=>{
+            console.error('form submission page campaigns read failed', error);
+            return [];
+        }) : [];
+        /*
+     * THE CUSTOM CONTACT FIELDS THIS FORM SAVES TO (AGL-2601).
+     *
+     * Off the VERIFIED form's declaration, like the campaigns above and for
+     * the same reason: a mapping taken from the request body would let anyone
+     * write any value under any field of any contact on any site. The
+     * definitions are read from the owning org — one bounded read of a small
+     * collection — and only when the declaration maps at least one field, so
+     * a form that saves nowhere pays nothing.
+     *
+     * Coerced by the definition's TYPE before it goes anywhere near the
+     * contact: `collectMappedContactCustom` is the same rule the API applies
+     * to a `custom` body, so a number typed into a form and a number sent
+     * over the API are stored as the same thing. A blank field contributes no
+     * key at all, so a submission never clears a value the merchant set.
+     */ const mappedContactCustom = form && (owningOrg == null ? void 0 : owningOrg.orgId) && formFieldDecls.some((decl)=>decl == null ? void 0 : decl.contactFieldKey) ? Aglyn.collectMappedContactCustom({
+            fields: sanitizedFields,
+            decls: formFieldDecls,
+            definitions: (await firestore.collection('orgs').doc(owningOrg.orgId).collection(Aglyn.CRM_COLLECTIONS.contactFields).limit(Aglyn.CONTACT_FIELDS_MAX_PER_ORG).get()).docs.map((snapshot)=>snapshot.data())
+        }) : {};
+        // One instant for the whole submission. The attribution window is
+        // measured against it in three places below, and three calls to
+        // `Date.now()` would let a slow write decide whether a touch was inside
+        // the window for the contact and outside it for the lead.
+        const submittedAtMs = Date.now();
+        /*
+     * The organization this site belongs to, off the two documents this
+     * route has already read — the host, whose `orgId` only the org APIs
+     * write, and the `hostIndex` mirror the plan gate resolved through.
+     */ const hostOrgId = hostSnapshot.get('orgId');
+        const submissionOrgId = typeof hostOrgId === 'string' && hostOrgId ? hostOrgId : owningOrg == null ? void 0 : owningOrg.orgId;
+        const submissionRef = await hostRef.collection('formSubmissions').add(_extends({}, submissionOrgId ? {
+            orgId: submissionOrgId
+        } : {}, {
+            hostId
+        }, form ? {
+            formId: form.id
+        } : {}, formCampaignIds.length ? {
+            campaignIds: formCampaignIds
+        } : {}, pageCampaignIds.length ? {
+            pageCampaignIds
+        } : {}, {
+            formName: resolvedFormName,
+            path: String(path != null ? path : '').slice(0, 500),
+            fields: sanitizedFields
+        }, messageSearchFields(sanitizedFields), {
+            read: false,
+            createdAt: FieldValue.serverTimestamp()
+        }, rate.degraded ? {
+            rateDegraded: true
+        } : {}));
+        // Contacts ingestion (AGL-197): forms don't guarantee an email field —
+        // best-effort extraction; never blocks the submission.
+        const contactEmail = extractEmailFromFields(sanitizedFields);
+        /*
+     * Whether this submission was filed to the site's Leads.
+     *
+     * The form counts PEOPLE (AGL-3330). The lead silo keys one person to one
+     * document, so a returning visitor's second submission updates the lead
+     * it created the first time; the form's lead count moves only when the
+     * capture puts this form's source on a lead for the first time
+     * (`leadCounted`), which is exactly what a recount of the leads'
+     * `sources` finds — so the increment and the recount agree, and a lead
+     * erased later can be taken back off. A routed submission by somebody
+     * the workspace already holds as a contact lands on the contact and files
+     * no lead (AGL-3232), and is not counted.
+     */ let leadStored = false;
+        /** Whether that lead is one more person on this form's lead count. */ let leadCounted = false;
+        /**
+     * The lead or contact the person was filed as, for the Inbox to link to
+     * (AGL-3461) — by the id the record system answered with, which is the
+     * id its own record route addresses.
+     */ let capturedRecord = null;
+        /*
+     * WHERE THE VISITOR ARRIVED FROM, RESOLVED ONCE FOR THE WHOLE SUBMISSION.
+     *
+     * One visitor action lands in three collections here — the submission,
+     * the contact and (when the form declares itself a lead surface) the
+     * lead — and all three are the same person arriving from the same place.
+     * Resolving here and handing the result down is what keeps the lookup at
+     * one per submission instead of three, and it is also what guarantees the
+     * three records cannot disagree about what to credit.
+     *
+     * The answer is the crediting plugin's (`plugin-conversion-credit.ts`),
+     * asked with what the visitor's browser sent under `campaignTouch` —
+     * untrusted, so the creditor re-parses and window-checks it before it
+     * can name anything. A submission carrying none — direct traffic, or a
+     * visitor whose consent posture never let a touch be remembered — and a
+     * workspace whose plugins credit nothing both resolve to null and write
+     * no credit at all.
+     */ const arrival = await resolveConversionTouch({
+            hostId,
+            wire: payload['campaignTouch'],
+            email: contactEmail,
+            atMs: submittedAtMs
+        });
+        // The submission itself is an outcome whether or not it named anybody:
+        // an anonymous enquiry from a campaign link is a conversion that campaign
+        // caused, and refusing to count it because no email field was filled in
+        // would under-report exactly the forms that ask for the least.
+        void creditConversion({
+            hostId,
+            kind: 'form',
+            refId: submissionRef.id,
+            touch: arrival,
+            convertedAtMs: submittedAtMs
+        });
+        /*
+     * THE CAMPAIGNS IN WORDS, for the managers' alert below (AGL-3461): the
+     * one the visitor arrived through and the ones the form and page are
+     * filed under, named by the plugin that keeps campaigns. Started here so
+     * its reads overlap the capture and the counters; asked only when there
+     * is something to name, and it never throws.
+     */ const filedUnder = normalizeContainerIds([
+            ...formCampaignIds,
+            ...pageCampaignIds
+        ]);
+        const describing = arrival || filedUnder.length ? describeConversion({
+            hostId,
+            touch: arrival,
+            containerIds: filedUnder
+        }) : Promise.resolve(null);
+        if (contactEmail) {
+            var _ref2, _sanitizedFields_name, _captured_sourceAdded;
+            var _form_get1;
+            /*
+       * WHICH RECORD THE PERSON LANDS ON is the record system's decision
+       * (AGL-3232), and the form says only what kind of surface it is: a
+       * lead surface when its author switched lead routing on
+       * (`docs/specs/reusable-forms.md` §4a), a touch otherwise. The writer
+       * files a lead — through `addHostLead`, keyed on the person and
+       * counted against the ceiling — unless the workspace already holds the
+       * address as a contact, and answers which record it wrote.
+       *
+       * AWAITED, unlike the capture of every other door, and only because
+       * the answer is counted: the form's `stats.leads` rides the same
+       * `update` the submission counters ride below, and a `void` call with
+       * the counter chained onto its `then` would put the one figure on this
+       * page that is about routing on a promise the runtime is free to
+       * abandon once the response is sent. The posture is unchanged —
+       * `recordCapturedContact` never throws — so awaiting it cannot fail the
+       * submission any more than voiding it could.
+       */ const routed = (form == null ? void 0 : (_form_get1 = form.get('routing')) == null ? void 0 : _form_get1.lead) === true;
+            const captured = await recordCapturedContact(_extends({
+                /*
+         * Not gated on the org resolving. The record system keys a person on
+         * the SITE they were met on, so an org lookup that came back empty
+         * costs the capture nothing — and refusing to record the person over
+         * it would turn a lookup failure into a lost contact, silently, which
+         * is the failure this whole seam is arranged to avoid.
+         */ orgId: (_ref2 = owningOrg == null ? void 0 : owningOrg.orgId) != null ? _ref2 : '',
+                hostId,
+                identity: {
+                    email: contactEmail,
+                    name: (_sanitizedFields_name = sanitizedFields['name']) != null ? _sanitizedFields_name : sanitizedFields['fullName']
+                },
+                interaction: {
+                    source: 'form',
+                    refId: submissionRef.id,
+                    summary: `Submitted "${resolvedFormName.slice(0, 60)}"`
+                },
+                surface: routed ? 'lead' : 'touch'
+            }, declaredMarketingConsent ? {
+                marketingConsent: true
+            } : {}, declaredMarketingConsent && disclosedConsentGroup ? {
+                disclosedConsentGroup
+            } : {}, formCampaignIds.length ? {
+                containers: {
+                    campaign: formCampaignIds
+                }
+            } : {}, Object.keys(mappedContactCustom).length ? {
+                profile: {
+                    custom: mappedContactCustom
+                }
+            } : {}, {
+                detail: _extends({}, form ? {
+                    formId: form.id
+                } : {}, typeof path === 'string' && path ? {
+                    path
+                } : {}, arrival ? {
+                    [CONVERSION_TOUCH_DETAIL]: arrival
+                } : {})
+            }));
+            leadStored = (captured == null ? void 0 : captured.ok) === true && captured.record === 'lead';
+            /*
+       * A form counts the PEOPLE it filed (AGL-3330): the capture says
+       * whether this one was new to the form, and a writer that does not
+       * say is read as whether the lead itself was new.
+       */ leadCounted = leadStored && (captured == null ? void 0 : captured.ok) === true && captured.record === 'lead' && ((_captured_sourceAdded = captured.sourceAdded) != null ? _captured_sourceAdded : captured.created) === true;
+            if ((captured == null ? void 0 : captured.ok) === true) {
+                const id = captured.record === 'lead' ? captured.leadId : captured.contactId;
+                if (id) capturedRecord = {
+                    kind: captured.record,
+                    id
+                };
+            }
+        }
+        /*
+     * WHERE ELSE THE SUBMISSION IS FILED (AGL-3080): a record in whatever
+     * plugin keeps the records a form may write into — a dataset row, today.
+     *
+     * Asked AFTER the submission is stored, through the platform's contract
+     * (`plugin-manager/submission-record-target.ts`), and the target decides from
+     * what the page's compose stamped onto this form, never from the body
+     * alone: the route is public. It answers the submission's `routing`,
+     * which the Inbox reads to say where it went or why it did not. The Inbox
+     * copy above is canonical either way, and nothing here can fail the
+     * submission.
+     */ const filed = await writeFormRecordTarget({
+            hostId,
+            orgId: (_ref1 = owningOrg == null ? void 0 : owningOrg.orgId) != null ? _ref1 : null,
+            orgBilling,
+            body: payload,
+            fields: sanitizedFields
+        });
+        /*
+     * What the submission led to, on the row in ONE update: where else it
+     * was filed, and the lead or contact it filed (AGL-3461). Written only
+     * when there is either, so the ordinary anonymous enquiry pays nothing.
+     */ const outcomeNotes = _extends({}, filed.routing ? {
+            routing: filed.routing
+        } : {}, capturedRecord ? {
+            capturedRecord
+        } : {});
+        if (Object.keys(outcomeNotes).length) {
+            try {
+                await submissionRef.update(outcomeNotes);
+            } catch (error) {
+                console.error('form submission routing note failed', error);
+            }
+        }
+        await counterRef.set({
+            [monthKey]: FieldValue.increment(1)
+        }, {
+            merge: true
+        });
+        /*
+     * Per-form counters (`docs/specs/reusable-forms.md` §5a), through the
+     * one writer that retries and REPORTS a failure rather than swallowing
+     * it (AGL-3330) — see `incrementFormStats`.
+     *
+     * `stats.leads` is here rather than beside the lead writer for the same
+     * reason the submission counters are: a second write to say a lead was
+     * filed would be a second write per submission on the collection the
+     * customer is billed against.
+     */ if (form) {
+            await incrementFormStats({
+                formRef: form.ref,
+                hostId,
+                monthKey,
+                submittedAtMs,
+                leadCounted
+            });
+        }
+        // Event trigger (AGL-128/148): field values join the automation
+        // scope; action-produced site alerts ride back to the visitor.
+        // In-app notification to the site's managers (AGL-259).
+        /*
+     * The body names the form and the site on its own (AGL-3432): a manager
+     * of several sites reads the email body, not always the subject, and
+     * "Page: /contact" said neither. `{site}` is filled by
+     * `notifyHostManagers` from the host doc it already reads.
+     *
+     * Then the campaigns (AGL-3461): the one the visitor was credited to and
+     * how, and what the form and page are filed under, as the crediting
+     * plugin names them.
+     *
+     * It opens THIS submission, not the list: the address the plugin that
+     * shows submissions declares for one record (`submissionsLink`), stored
+     * in the host-link shape every host notification uses and rewritten onto
+     * the site's address when it is followed, in the console and in the email
+     * alike. A notification holds one link, so the lead and the campaign are
+     * links inside the reader.
+     */ const alertPath = typeof path === 'string' ? path.slice(0, 500) : '';
+        void notifyHostManagers(hostId, _extends({
+            type: 'content.formSubmission',
+            title: `New form submission — ${resolvedFormName}`,
+            body: [
+                `Someone submitted “${resolvedFormName}” on {site}` + (alertPath ? ` (page ${alertPath}).` : '.'),
+                ...conversionDescriptionSentences(await describing)
+            ].join(' ')
+        }, submissionsLink(hostId, submissionRef.id)));
+        const submittedEmail = typeof sanitizedFields['email'] === 'string' ? sanitizedFields['email'] : '';
+        /*
+     * `formId` is the VERIFIED form's id (AGL-3458), the way `contactCreated`
+     * carries it: a condition keyed on it survives the form being renamed,
+     * where one on `formName` silently stops matching. It is written last
+     * and only from the form this route read, so a submitted field that
+     * calls itself `formId` can neither claim another form's automations
+     * nor stand in for a form the site does not have.
+     */ const submittedFields = Object.fromEntries(Object.entries(sanitizedFields).filter(([key])=>key !== 'formId'));
+        const { alerts } = await emitHostEvent(hostId, 'formSubmission', _extends({
+            formName: resolvedFormName,
+            path: String(path != null ? path : '').slice(0, 500)
+        }, submittedFields, form ? {
+            formId: form.id
+        } : {}), // The visitor who submitted, by the address they typed if any (AGL-3376).
+        {
+            actor: _extends({
+                kind: 'visitor'
+            }, submittedEmail ? {
+                email: submittedEmail
+            } : {})
+        });
+        return json({
+            received: true,
+            alerts
+        });
+    } catch (error) {
+        console.error(error);
+        return json({
+            error: 'Submission failed'
+        }, 500);
+    }
+}
+
+//# sourceMappingURL=form-submit.js.map