@alvera-ai/platform-sdk 0.19.2 → 0.20.0-next.gaafd87a

package/.agent/cookbook/organic-marketing.md

@@ -1,6 +1,6 @@
 ---
 title: "Organic marketing: score, greet, campaign — on one raw lake"
-summary: The whole organic-marketing surface in one walk. Stand up a tenant and a raw datalake, then run the scenarios end to end — an LLM agent banding inbound leads into a four-way SMS fan-out, a pure-Liquid birthday trigger that schedules a greeting a year out and closes the reply loop through a connected app, and an A/B campaign that gates on suppression, splits inside the workflow and dispatches on SMS and email in one run. Ends with delivery reconciliation and a natural-language read of the lake.
+summary: The whole organic-marketing surface in one walk. Stand up a tenant and a raw datalake, then run the scenarios end to end — an LLM agent banding inbound leads into a four-way SMS fan-out, a pure-Liquid birthday trigger that schedules a greeting a year out and closes the loop through its authenticated link, and an A/B campaign that gates on suppression, splits inside the workflow and dispatches on SMS and email in one run. Ends with delivery reconciliation and a natural-language read of the lake.
 use_case: organic-marketing
 slug: organic-marketing
 vitest_source:
@@ -40,7 +40,7 @@ is one call away from here.
 | Score Lead AI agent                 | Bands inbound leads                          |
 | Three generic tables                | Leads, the roster, and the audience          |
 | Three workflows                     | Band fan-out, birthday greeting, campaign    |
-| Connected app                       | The reply loop, twice                        |
+| Authenticated links                 | The greeting's link and the campaign's link  |
 | Action status updater               | Delivery outcomes, reconciled on a cron      |
 
 # Walkthrough
@@ -651,8 +651,8 @@ ctx.agentSlug = agent.slug!
 
 ## 012 — the Score Lead workflow
 
-Standard shape — filter, decision, actions — with two things worth reading
-closely.
+Standard shape — filter, decision, actions — with three things worth
+reading closely.
 
 The agent is **nested in the create body** (`workflow_ai_agents`, a
 `cast_assoc` rather than a separate attach call), which binds it into the
@@ -669,6 +669,13 @@ action and leaves the other three `:skipped`.
 hyphens, and Liquid's dot parser would read `additional_context.score-lead`
 as a subtraction.
 
+**`link_prefix` is required on every SMS call, this one included.** These
+bodies carry no link of the walk's own, but each echoes the lead's message,
+and a URL a lead typed into the form goes out as `<link_prefix>/<token>`
+like any other. A body with no URL in it is sent unchanged. Leave the
+prefix off and the workflow is refused at create with a 422 on
+`/actions/<n>/tool_call/link_prefix`.
+
 ```typescript
 const BANDS = ['hot', 'warm', 'cold', 'spam'] as const
 
@@ -713,6 +720,7 @@ const scoreWorkflow = await ctx.ensure(
           to: { type: 'custom', body: '+15551234567' },
           body: { type: 'custom', body: `Lead band [${band}]: {{ event_dataset.message }}` },
           sms_type: 'transactional',
+          link_prefix: 'https://go.leads.example.local/l',
         },
       })),
       workflow_ai_agents: [
@@ -956,33 +964,25 @@ if (!bandBody.includes('[hot]')) {
 }
 ```
 
-## 019 — the Birthday Greeting connected app
+## 019 — where the greeting's link lands
+
+The greeting carries a link so the recipient can do something with it —
+upload a photo, RSVP, whatever the operator builds. Two addresses are in
+play, and neither is registered with the platform.
+
+The **page** is the URL you write into the SMS body, exactly as a person
+should end up seeing it. The **link prefix** is the host you run in front
+of it: at send the platform swaps every URL in the body for
+`<link_prefix>/<token>`, a link minted for this one message, and a tap on
+it reaches that host first. The host asks the platform what the link is,
+then sends the person on to the page — §030 does exactly that.
 
-The greeting carries a deep link so the recipient can do something with it
-— upload a photo, RSVP, whatever the operator wires up. A connected app is
-a thin registration of that page's URL and mode; the page itself is hosted
-outside the platform (`mode: 'self_hosted'`). Capture the server-derived
-`slug` — §030 resolves a token against it.
+A path is allowed in the prefix; a query, a fragment or a trailing slash is
+not, because the platform appends `/<token>` itself.
 
 ```typescript
-const birthdayApp = await ctx.ensure(
-  'Birthday Greeting connected app',
-  async () => {
-    const { data } = await api.connectedApps.list(tenantSlug, datalakeSlug)
-    return (data.data ?? []).find((a: { name?: string }) => a.name === 'Cookbook Birthday Greeting Form')
-  },
-  async () => {
-    const { data } = await api.connectedApps.create(tenantSlug, datalakeSlug, {
-      name: 'Cookbook Birthday Greeting Form',
-      description: 'Birthday-greeting form linked from the outbound SMS.',
-      mode: 'self_hosted',
-      urls: [{ url: 'https://birthday.example.local', is_primary: true, label: 'production' }],
-    })
-    return data
-  },
-)
-connectedAppId = birthdayApp.id!
-ctx.birthdayAppSlug = birthdayApp.slug!
+ctx.birthdayFormUrl = 'https://birthday.example.local/forms/birthday-greeting'
+ctx.birthdayLinkPrefix = 'https://go.birthday.example.local/l'
 ```
 
 ## 020 — the Happy Birthday workflow, and the year-roll trigger
@@ -999,10 +999,12 @@ correct instead of nearly correct.
 Two things that look optional and are not. The filter reads
 `mdm_output.legal_entity.date_of_birth`, which requires
 `skip_mdm_resolution: false` — the resolution is what puts the subject in
-scope for the filter at all. And the SMS body must reference
-`{{ connected_app_form_url }}`: the platform mints the page token at action
-time and injects that variable, so a body that never mentions it gets a
-token minted and thrown away, and §031 has no link to resolve.
+scope for the filter at all — and it is what fills the link's
+`legal_entity_id`, so a tap on it says who tapped. And the SMS call must
+carry `link_prefix`: it is required on every SMS, MMS and email call, and
+it is what turns the page URL in the body into a link §029 can find.
+`metadata_template` renders once per send and rides on the message, so the
+host behind the prefix gets it back with the link.
 
 ```typescript
 const DECISION_KEY = 'send_happy_birthday_sms'
@@ -1041,17 +1043,16 @@ const birthdayWorkflow = await ctx.ensure(
           position: 0,
           trigger_template: TRIGGER_TEMPLATE,
           idempotency_template: '{{ legal_entity.id }}-birthday-greeting',
-          connected_app_id: connectedAppId,
-          connected_app_route: '/forms/birthday-greeting',
-          connected_app_metadata_template: '{"legal_entity_id":"{{ legal_entity.id }}"}',
+          metadata_template: '{"legal_entity_id":"{{ legal_entity.id }}"}',
           tool_call: {
             tool_call_type: 'sms_request',
             to: { type: 'custom', body: '{{ mdm_output.legal_entity.phone_numbers | first | map: "phone_number" }}' },
             body: {
               type: 'custom',
-              body: 'Happy birthday {{ mdm_output.legal_entity.first_name }}! \u{1F382} Share a photo: {{ connected_app_form_url }}',
+              body: `Happy birthday {{ mdm_output.legal_entity.first_name }}! \u{1F382} Share a photo: ${ctx.birthdayFormUrl}`,
             },
             sms_type: 'transactional',
+            link_prefix: ctx.birthdayLinkPrefix,
           },
         },
       ],
@@ -1376,12 +1377,13 @@ if (forcedStatus !== 'completed') {
 }
 ```
 
-## 029 — the greeting exists, and it carries a deep link
+## 029 — the greeting exists, and it carries an authenticated link
 
-The end state: a birthday greeting exists for this contact, with a
-`/t/<token>` link in its body. True on the first run because the action
-just dispatched, and true on every run after because it dispatched once and
-the idempotency key has protected it since.
+The end state: a birthday greeting exists for this contact, and the page
+URL §019 wrote into its body went out as `<link_prefix>/<token>` — a link
+minted for this one message. True on the first run because the action just
+dispatched, and true on every run after because it dispatched once and the
+idempotency key has protected it since.
 
 **Read the durable record, not the run you just made.** The obvious move is
 to pull the rendered body off the execution log from §028 — and that works
@@ -1393,6 +1395,11 @@ asking. In local dev the publish itself lands in LocalStack's SNS records
 at `/_aws/sns/sms-messages`, keyed by phone number — useful to eyeball, too
 volatile to assert on.
 
+**The stored body is the body as sent**, so the page URL is not in it: in
+its place stand the link prefix and a fifteen-character token. Finding the
+page URL itself in the stored body would mean no link was minted, and the
+recipient was sent straight to the page with nothing to say who tapped.
+
 ```typescript
 const { data: bdMsgSearch } = await api.datasets.createUserSearch(tenantSlug, datalakeSlug, 'message', {
   search_query: `m.idempotency_key LIKE '${ctx.birthdayLegalEntityId}-%'`,
@@ -1420,40 +1427,85 @@ if (bdMessages.length === 0) {
 
 const greeting = bdMessages
   .map((m) => String(m.body ?? ''))
-  .find((b) => b.includes('Happy birthday') && b.includes('/t/'))
+  .find((b) => b.includes('Happy birthday'))
 if (!greeting) {
-  throw new Error(`no greeting body with a /t/ link — bodies: ${JSON.stringify(bdMessages.map((m) => m.body))}`)
+  throw new Error(`no greeting body — bodies: ${JSON.stringify(bdMessages.map((m) => m.body))}`)
+}
+if (greeting.includes(ctx.birthdayFormUrl)) {
+  throw new Error(`the page URL went out as written, so no link was minted: ${greeting}`)
 }
-const bdToken = greeting.match(/\/t\/([A-Za-z0-9_-]+)/)
-if (!bdToken) throw new Error(`no /t/<token> in the rendered greeting: ${greeting}`)
-ctx.birthdayShortPath = bdToken[1]!
+const bdLinkStart = `${ctx.birthdayLinkPrefix}/`
+const bdToken = greeting.split(bdLinkStart)[1]?.match(/^[A-Za-z0-9_-]{15}/)?.[0]
+if (!bdToken) throw new Error(`no ${bdLinkStart}<token> in the greeting: ${greeting}`)
+ctx.birthdayLinkToken = bdToken
 ```
 
-## 030 — resolve the link, and close the loop
+## 030 — the tap, the page, and the form
+
+This step plays the host behind the link prefix. A tap on the link reaches
+it with the token in the path; the host hands that token to
+`authenticatedLinks.exchange` together with what the tap's request said
+about itself, and gets back where to send the person and whom the link was
+for. Both calls here need only the tenant's publishable key — the host is
+not a signed-in user.
+
+**Forward the tap's own details, not your server's.** The platform judges
+from them whether a person tapped: a `HEAD`, a prefetch header, an empty
+user agent or one naming a bot or a link preview is recorded and moves
+nothing. A person's first tap stamps the link's `link_clicked_at` and the
+message's `clicked_at`; later taps keep both. That is why the user agent
+below is a phone's browser — the one the person actually used.
+
+The answer carries `metadata_template`'s output on the **message**, as
+`message.metadata` — the link itself has no metadata field.
 
-The shortlink resolves through `connectedApps.resolvePage`, and the
-`route_path` that comes back must match the action's `connected_app_route`.
-Posting `opened_at` and `form_submitted_at` then mirrors exactly what the
-form's frontend does when the recipient opens it — which closes the loop
-from a scheduled greeting to a tracked reply.
+Then the page reports what the person did, with the same token. **The
+message status only moves forward**, and `opened` ranks *below* `clicked`:
+reporting `opened` after the tap leaves the status at `clicked`, while
+`opened_at` still lands. `form_submitted` ranks above both, so the message
+ends there.
 
 ```typescript
-const { data: bdResolved } = await api.connectedApps.resolvePage(
-  tenantSlug, datalakeSlug, ctx.birthdayAppSlug,
-  { short_path: ctx.birthdayShortPath, user_agent: 'cookbook-doctest/birthday-greeting' },
-)
-if (bdResolved.route_path !== '/forms/birthday-greeting') {
-  throw new Error(`resolvePage route_path mismatch: ${bdResolved.route_path}`)
+ctx.personOnAPhone =
+  'Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) AppleWebKit/605.1.15 ' +
+  '(KHTML, like Gecko) Version/17.0 Mobile/15E148 Safari/604.1'
+
+const { data: bdTap } = await api.authenticatedLinks.exchange(tenantSlug, datalakeSlug, {
+  token: ctx.birthdayLinkToken,
+  method: 'GET',
+  user_agent: ctx.personOnAPhone,
+  headers: { 'accept-language': 'en-US' },
+})
+if (bdTap.destination_url !== ctx.birthdayFormUrl) {
+  throw new Error(`the link should lead to ${ctx.birthdayFormUrl}, got ${bdTap.destination_url}`)
+}
+if (bdTap.legal_entity_id !== ctx.birthdayLegalEntityId) {
+  throw new Error(`the link should name contact ${ctx.birthdayLegalEntityId}, got ${bdTap.legal_entity_id}`)
+}
+if (bdTap.message.metadata?.legal_entity_id !== ctx.birthdayLegalEntityId) {
+  throw new Error(`metadata_template did not reach the message: ${JSON.stringify(bdTap.message.metadata)}`)
+}
+if (!bdTap.link_clicked_at || !bdTap.message.clicked_at) {
+  throw new Error("a person's tap should stamp link_clicked_at and the message's clicked_at")
 }
 
 const bdNow = new Date().toISOString()
-const { data: bdTracked } = await api.connectedApps.updateMessageTracking(
-  tenantSlug, datalakeSlug, ctx.birthdayAppSlug,
-  { short_path: ctx.birthdayShortPath, opened_at: bdNow, form_submitted_at: bdNow },
-)
-if (!bdTracked.message?.opened_at || !bdTracked.message?.form_submitted_at) {
+await api.authenticatedLinks.updateMessageTracking(tenantSlug, datalakeSlug, {
+  token: ctx.birthdayLinkToken,
+  status: 'opened',
+  opened_at: bdNow,
+})
+const { data: bdTracked } = await api.authenticatedLinks.updateMessageTracking(tenantSlug, datalakeSlug, {
+  token: ctx.birthdayLinkToken,
+  status: 'form_submitted',
+  form_submitted_at: bdNow,
+})
+if (!bdTracked.message.opened_at || !bdTracked.message.form_submitted_at) {
   throw new Error('message tracking did not persist opened_at + form_submitted_at')
 }
+if (bdTracked.message.status !== 'form_submitted') {
+  throw new Error(`the message should end at form_submitted, got ${bdTracked.message.status}`)
+}
 ```
 
 ## 031 — the roster and the audience, as two tables
@@ -1701,8 +1753,9 @@ Same shape, two differences that carry the campaign.
 
 Each recipient resolves to an **individual** legal entity keyed on their
 contact handle — phone when there is one, email otherwise. That subject is
-what the per-recipient short link in §039 is minted against, which is what
-makes a click attributable to one person rather than to the campaign.
+what every campaign message §039 sends — and every link minted with it —
+names as its `legal_entity_id`, which is what makes a tap attributable to
+one person rather than to the campaign.
 
 And the generic-table contract assigns the **bucket**, derived from the last
 two digits of the vendor's own id rather than from a random draw. Re-ingest
@@ -1914,8 +1967,7 @@ await ctx.waitForBatches(ctx.audienceDataDacSlug, audienceDataBatches)
 
 Read the four rows back. Every one carries a `legal_entity_id`, and the four
 are **distinct** — four recipients, four subjects. A shared subject would
-mean two people collapsed into one, and a short link pointing at the wrong
-customer.
+mean two people collapsed into one, and a link naming the wrong customer.
 
 The buckets are checked here too, because a wrong bucket is the kind of
 thing that stays invisible until someone asks why variant A outperformed B
@@ -1956,7 +2008,7 @@ if (subjects.size !== 4) {
 ctx.adaSubjectId = String(byCustomerId.get(ctx.adaId)!.legal_entity_id)
 ```
 
-## 037 — two sender tools, and the booking form
+## 037 — two sender tools, and the booking page
 
 **Two sender tools, not one.** An SMS number and an email identity are
 different assets, provisioned and billed separately, so §038 binds each
@@ -1969,7 +2021,16 @@ against any server without asking the deployment to be in "test mode", and
 swapping `mock` for a real provider sends real email through the same
 workflow.
 
+**The booking page is two addresses, as in §019**, and neither is a
+resource: the page the campaign points people at, and the host in front of
+it that answers the taps. Nothing is registered with the platform, so there
+is nothing to look up or create — the addresses are just values the
+workflow's actions carry.
+
 ```typescript
+ctx.bookingPageUrl = 'https://campaign.example.com/forms/campaign'
+ctx.campaignLinkPrefix = 'https://go.campaign.example.com/l'
+
 const campaignSms = await ctx.ensure(
   'campaign SMS sender',
   async () => {
@@ -2022,25 +2083,6 @@ const campaignEmail = await ctx.ensure(
   },
 )
 ctx.campaignEmailToolId = campaignEmail.id!
-
-const bookingApp = await ctx.ensure(
-  'campaign booking form',
-  async () => {
-    const { data } = await api.connectedApps.list(tenantSlug, datalakeSlug)
-    return (data.data ?? []).find((a: { name?: string }) => a.name === 'Cookbook Campaign Booking Form')
-  },
-  async () => {
-    const { data } = await api.connectedApps.create(tenantSlug, datalakeSlug, {
-      name: 'Cookbook Campaign Booking Form',
-      description: 'The booking form the campaign links to.',
-      mode: 'self_hosted',
-      urls: [{ url: 'https://campaign.example.com', is_primary: true, label: 'production' }],
-    })
-    return data
-  },
-)
-ctx.bookingAppId = bookingApp.id!
-ctx.bookingAppSlug = bookingApp.slug!
 ```
 
 ## 038 — the campaign workflow: the gates, the split, both channels
@@ -2062,11 +2104,24 @@ than two workflows kept in step by hand.
 
 **`skip_mdm_resolution: false` is set explicitly, and must be.** A
 generic-table row is never its own subject; the subject is the one §034
-stamped onto it. With resolution on, the platform loads that subject and
-mints a page token against it, which is what makes
-`{{ connected_app_form_url }}` a *per-recipient* link. Skip it and the
-subject is nil, no token is minted, and the link renders empty — with
-nothing anywhere reporting a problem.
+stamped onto it. With resolution on, the platform loads that subject, and
+the message — and every link minted with it — names that person as its
+`legal_entity_id`. Skip it and the subject is nil: the links still go out
+and still resolve, but none of them can say who tapped, and nothing
+anywhere reports a problem.
+
+**Every message gets its own links.** The booking page's URL is written
+straight into the body, the same for everyone; the platform swaps it at
+send for `<link_prefix>/<token>`, with a token minted for that one message.
+The SMS body is plain text, so its bare URL is swapped. **The email body is
+HTML, and only an `href` is swapped** — a bare URL in an email's text goes
+out exactly as written, and a mail client that turns it into a link sends
+the person straight to the page, past the host and with nothing recorded.
+So the email variants carry their link as an `<a href>`.
+
+`link_prefix` is required on every SMS and email call — the same host
+answers both channels' links. `metadata_template` gives that host what it
+needs about the recipient beyond who they are.
 
 `output_schema` is a JSON-Schema **object**. The string form is refused 422.
 
@@ -2079,15 +2134,19 @@ const CAMPAIGN_FILTER =
 const AB_DECISION =
   '{% if event_dataset.bucket < 50 %}["sms_variant_a","email_variant_a"]' +
   '{% else %}["sms_variant_b","email_variant_b"]{% endif %}'
-const VARIANT_A = 'Hi {{ event_dataset.name }} — 20% off your next visit this week only. Book: {{ connected_app_form_url }}'
-const VARIANT_B = 'Hi {{ event_dataset.name }} — your loyalty reward is waiting. Claim: {{ connected_app_form_url }}'
+const SMS_VARIANT_A = `Hi {{ event_dataset.name }} — 20% off your next visit this week only. Book: ${ctx.bookingPageUrl}`
+const SMS_VARIANT_B = `Hi {{ event_dataset.name }} — your loyalty reward is waiting. Claim: ${ctx.bookingPageUrl}`
+const EMAIL_VARIANT_A =
+  `<p>Hi {{ event_dataset.name }} — 20% off your next visit this week only.</p>` +
+  `<p><a href="${ctx.bookingPageUrl}">Book your visit</a></p>`
+const EMAIL_VARIANT_B =
+  `<p>Hi {{ event_dataset.name }} — your loyalty reward is waiting.</p>` +
+  `<p><a href="${ctx.bookingPageUrl}">Claim your reward</a></p>`
 
 const linkage = {
   trigger_template: 'now',
   idempotency_template: '{{ event_dataset.end_customer_id }}/{{ action_id }}',
-  connected_app_id: ctx.bookingAppId,
-  connected_app_route: '/forms/campaign',
-  connected_app_metadata_template:
+  metadata_template:
     '{"end_customer_id":"{{ event_dataset.end_customer_id }}","name":"{{ event_dataset.name }}"}',
 }
 
@@ -2119,8 +2178,9 @@ const campaign = await ctx.ensure(
           tool_call: {
             tool_call_type: 'sms_request',
             to: { type: 'custom', body: '{{ event_dataset.phone }}' },
-            body: { type: 'custom', body: VARIANT_A },
+            body: { type: 'custom', body: SMS_VARIANT_A },
             sms_type: 'transactional',
+            link_prefix: ctx.campaignLinkPrefix,
           },
         },
         {
@@ -2129,8 +2189,9 @@ const campaign = await ctx.ensure(
           tool_call: {
             tool_call_type: 'sms_request',
             to: { type: 'custom', body: '{{ event_dataset.phone }}' },
-            body: { type: 'custom', body: VARIANT_B },
+            body: { type: 'custom', body: SMS_VARIANT_B },
             sms_type: 'transactional',
+            link_prefix: ctx.campaignLinkPrefix,
           },
         },
         {
@@ -2140,7 +2201,8 @@ const campaign = await ctx.ensure(
             tool_call_type: 'email_request',
             to: { type: 'custom', body: '{{ event_dataset.email }}' },
             subject: { type: 'custom', body: 'Your 20% off is here' },
-            body: { type: 'custom', body: VARIANT_A },
+            body: { type: 'custom', body: EMAIL_VARIANT_A },
+            link_prefix: ctx.campaignLinkPrefix,
           },
         },
         {
@@ -2150,7 +2212,8 @@ const campaign = await ctx.ensure(
             tool_call_type: 'email_request',
             to: { type: 'custom', body: '{{ event_dataset.email }}' },
             subject: { type: 'custom', body: 'Your loyalty reward is waiting' },
-            body: { type: 'custom', body: VARIANT_B },
+            body: { type: 'custom', body: EMAIL_VARIANT_B },
+            link_prefix: ctx.campaignLinkPrefix,
           },
         },
       ],
@@ -2246,15 +2309,25 @@ for (const wel of sentWels) {
 }
 ```
 
-## 040 — the short link belongs to one recipient
+## 040 — every link belongs to one recipient
 
-Every message the campaign rendered carries a `/t/<hash>`. It is **not** one
-campaign link shared by everyone: the token was minted against this
-recipient's own subject — the one §034 stamped and §038 resolved — so a
-click is attributable to a person rather than to a send.
+Ada was sent one variant on both channels: two messages, each pointing at
+the same booking page. Neither carries a campaign link shared by everyone.
+Each URL went out as `<link_prefix>/<token>` with a token minted for that
+one message, and the message names the subject §034 stamped and §038
+resolved — so a tap is attributable to a person, and to the channel that
+reached them, rather than to a send.
 
 Keyed on the idempotency key again, so this reads the durable record and
-answers on every run rather than only the one that dispatched.
+answers on every run rather than only the one that dispatched. The email is
+told apart by its `href`; the booking page itself must appear in neither
+body, or a link was never minted.
+
+The tap is the SMS link, forwarded with the person's own request details as
+in §030. The answer names Ada as `legal_entity_id`, and the message
+carries what `metadata_template` rendered for her — her own
+`end_customer_id` — which is all a booking page needs to know whose visit
+it is booking.
 
 ```typescript
 const { data: campaignMsgSearch } = await api.datasets.createUserSearch(tenantSlug, datalakeSlug, 'message', {
@@ -2265,33 +2338,54 @@ if (campaignMsgSearch.status !== 'completed') {
 }
 
 const linkDeadline = Date.now() + 120_000
-let campaignShortPath: string | undefined
-while (Date.now() < linkDeadline && !campaignShortPath) {
+let adaBodies: string[] = []
+while (Date.now() < linkDeadline && adaBodies.length < 2) {
   const { data: found } = await api.datasets.search(tenantSlug, datalakeSlug, 'message', {
     userSearchId: campaignMsgSearch.id!,
     dataAccessMode: 'raw',
   })
-  const bodies = ((found.data ?? []) as Array<Record<string, unknown>>).map((m) => String(m.body ?? ''))
-  campaignShortPath = bodies.find((b) => b.includes('/t/'))?.match(/\/t\/([A-Za-z0-9_-]+)/)?.[1]
-  if (!campaignShortPath) await new Promise((r) => setTimeout(r, 2_000))
+  adaBodies = ((found.data ?? []) as Array<Record<string, unknown>>).map((m) => String(m.body ?? ''))
+  if (adaBodies.length < 2) await new Promise((r) => setTimeout(r, 2_000))
+}
+const adaSms = adaBodies.find((b) => !b.includes('href='))
+const adaEmail = adaBodies.find((b) => b.includes('href='))
+if (!adaSms || !adaEmail) {
+  throw new Error(`expected Ada's SMS and email within 120s, got: ${JSON.stringify(adaBodies)}`)
+}
+
+const campaignLinkStart = `${ctx.campaignLinkPrefix}/`
+const tokenIn = (body: string) => body.split(campaignLinkStart)[1]?.match(/^[A-Za-z0-9_-]{15}/)?.[0]
+for (const body of [adaSms, adaEmail]) {
+  if (body.includes(ctx.bookingPageUrl)) throw new Error(`the booking page went out as written: ${body}`)
+}
+const smsToken = tokenIn(adaSms)
+const emailToken = tokenIn(adaEmail)
+if (!smsToken) throw new Error(`no ${campaignLinkStart}<token> in Ada's SMS: ${adaSms}`)
+if (!emailToken) throw new Error(`no ${campaignLinkStart}<token> in Ada's email href: ${adaEmail}`)
+if (smsToken === emailToken) throw new Error('each message mints its own link, but the SMS and email share one')
+
+const { data: campaignTap } = await api.authenticatedLinks.exchange(tenantSlug, datalakeSlug, {
+  token: smsToken,
+  method: 'GET',
+  user_agent: ctx.personOnAPhone,
+  headers: { 'accept-language': 'en-US' },
+})
+if (campaignTap.destination_url !== ctx.bookingPageUrl) {
+  throw new Error(`the link should lead to ${ctx.bookingPageUrl}, got ${campaignTap.destination_url}`)
 }
-if (!campaignShortPath) {
-  throw new Error(`no campaign message for ${ctx.adaId} carried a /t/ short link within 120s`)
+if (campaignTap.legal_entity_id !== ctx.adaSubjectId) {
+  throw new Error(`the link should name Ada (${ctx.adaSubjectId}), got ${campaignTap.legal_entity_id}`)
 }
-
-const { data: campaignResolved } = await api.connectedApps.resolvePage(
-  tenantSlug, datalakeSlug, ctx.bookingAppSlug,
-  { short_path: campaignShortPath, user_agent: 'cookbook-doctest/marketing-campaign-send' },
-)
-if (campaignResolved.route_path !== '/forms/campaign') {
-  throw new Error(`resolvePage route_path mismatch: ${campaignResolved.route_path}`)
+if (campaignTap.message.metadata?.end_customer_id !== ctx.adaId) {
+  throw new Error(`metadata_template did not reach the message: ${JSON.stringify(campaignTap.message.metadata)}`)
 }
 
-const { data: campaignTracked } = await api.connectedApps.updateMessageTracking(
-  tenantSlug, datalakeSlug, ctx.bookingAppSlug,
-  { short_path: campaignShortPath, opened_at: new Date().toISOString() },
-)
-if (!campaignTracked.message?.opened_at) {
+const { data: campaignTracked } = await api.authenticatedLinks.updateMessageTracking(tenantSlug, datalakeSlug, {
+  token: smsToken,
+  status: 'opened',
+  opened_at: new Date().toISOString(),
+})
+if (!campaignTracked.message.opened_at) {
   throw new Error('message tracking did not persist opened_at')
 }
 ```