feat: carry the landing page and HubSpot visitor cookie from embedded forms

[josue-commits]

Closes #199.

Stacked on #203 (spam protection). Do not merge before #203. This PR targets feat/spam-protection-captcha, so the diff shows only this work. Once #203 is in develop, retarget this PR to develop. It owns DB migration 0023.

An embedded form reached HubSpot without the visitor's tracking cookie (hubspotutk) and without the landing URL, so the contact lost its original source, page views and campaign. Embedded forms also lost the landing's UTMs, because the iframe only sees its own src. Only the host page can read those values, so embed.js now answers a small handshake from the form.

What it adds

• Handshake. At mount, and on every partial and complete submit, the form asks its parent for the visit with dapta-forms:context-request and a nonce. embed.js answers with the values read at that moment: pageUri, pageName, pageId (HubSpot CMS pages) and hutk.
  • Who gets an answer: only frames marked data-dapta-forms, and only when the message origin matches the frame's src origin and the origin embed.js was loaded from. The reply goes to that exact targetOrigin. The frame accepts an answer only from its parent, carrying its own nonce.
  • Opting out: the HubSpot opt-outs (__hs_opt_out, __hs_do_not_track) drop the cookie. data-dapta-forms-context="off" on the iframe turns the whole handshake off. Nothing writes cookies.
  • Cost: the form waits at most 500 ms when the host has answered before, and 150 ms otherwise, for example with a bare iframe. The visit is resolved once, in parallel with the spam check, so the submit is still sent once. A late answer is cached for the next submit. Without an answer, pageUri falls back to the referrer.
• Storage. A new nullable column, submission.visit (jsonb in Postgres, text in SQLite), with an additive migration 0023 in both dialects.
  • Upserts use COALESCE, so a write without a visit never erases one.
  • Parsing is tolerant: a malformed field is dropped, never refused.
    • hutk: 32 hex characters.
    • pageUri: absolute http(s), printable ASCII, at most 2048 characters.
    • pageId: digits only.
    • Characters Postgres refuses (\u0000, lone surrogates) never reach it: a page URL carrying one is dropped, a title or UTM value is cleaned, and a UTM key carrying one is skipped.
• Landing UTMs merge into data.utm, all or nothing. UTMs already on the iframe src win.
• HubSpot.
  • The mirror form submission ("Record a form submission in HubSpot" on) now sends context: { hutk, pageUri, pageName, pageId }, leaving out empty keys.
  • On a 400 it retries once with the old { pageName }. Nothing is retried after a successful post.
  • The contact note gets a "Page" line.
  • A cookie from another portal logs a warning.
• Webhooks get a top-level visit: { pageUri, pageName, embedded, hutk? }. It is additive, and the ping example includes it.
• Dashboard.
  • The response panel shows a "Page" row, with the title and the host. It is a link only for http(s) URLs.
  • A "HubSpot cookie received" chip shows when the cookie arrived.
  • CSV export adds a "Page URL" column at the end.
  • The admin API returns visit without the cookie, with a hubspotCookie boolean instead.
  • The cookie is never shown or logged. The webhook delivery history masks it, including inside what a receiver answers.
• Minimization. The cookie is stored only when a destination can use it. It is snapshotted per destination and phase: the HubSpot mirror only posts on complete.
• Direct links. When the form has its own HubSpot tracking ID, it reads its own hubspotutk. pageUri is the form URL without non-UTM params, because the rest are prefilled answers.
• With spam protection on, partials still store the visit but are not delivered. The verified complete carries the merged visit.

Deploy notes

• Migration 0023 is additive and runs on deploy.
• Snippets already pasted pick this up on their next page load, because embed.js is served without cache. Bare iframes (no embed.js) send only the referrer origin.
• Outbox rows queued before the deploy deliver exactly as before.
• embed.js answers the handshake only for frames on the host it was loaded from, which is always the case with the editor snippet. A copy of the script served from another host keeps resizing and redirecting, but sends no visit.
• For attribution in HubSpot, a customer needs three things:
  • the HubSpot connection with the forms and form-submissions-write scopes, and "Record a form submission in HubSpot" on;
  • the same portal in the connection and in the landing's tracking code;
  • the full snippet: the iframe plus embed.js.

Before production

• Verify with a HubSpot test portal on a page that runs the tracking code (steps in feat(embed): pass the HubSpot visit (hutk, page URL, landing UTMs) from embedded forms #199).
  • Check the page views on the contact.
  • Check that the original source does not stay "Offline sources" when the contact is created milliseconds before the mirror submission. If it does, the mirror has to go first, which touches the retry rules.
• Public docs (embed, tracking and privacy, HubSpot, webhook payload) are a follow-up in the docs repo.

Notes for review

• COALESCE works on the whole object, as the issue specifies. A poorer visit, such as a referrer-only one after an iframe reload, can therefore replace a richer one. It can be a follow-up if it matters.
• The issue's Legacy and Protocol sections disagree about a stale embed.js. The code follows Protocol, which falls back to the referrer.
• Found on the base and not changed here: in Playwright WebKit, the builder live preview never leaves "waiting" (on develop too), so one v17 test fails in WebKit.

Testing

• pnpm typecheck and pnpm lint pass. pnpm test: 2,680 passed.
• @quill/db on Postgres: 340/340.
• e2e v18-embed-hubspot-context: 16/16 in Chromium and WebKit. It covers:
  • a landing on another origin, with a fake hubspotutk and UTMs;
  • a bare iframe, off and opt-out;
  • spam protection on.
• Unit specs cover:
  • host-visit, and embed.js in a vm;
  • the UTM merge;
  • tolerant parsing, including values Postgres refuses;
  • the HubSpot mirror context and its 400 retry;
  • the webhook envelope and signature, including a receiver that echoes the request;
  • COALESCE on both dialects;
  • the outbox snapshot, booking sync, CSV and the panel.
• Publish gate passed, no dashes added, DCO and commitlint clean. No test reaches HubSpot or Cloudflare.

🤖 Generated with Claude Code