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

package/.agent/cookbook/payments-compliance.md

@@ -877,7 +877,7 @@ await ctx.deployGenericTable(ctx.screeningsTableName)
 
 Filter, decision, actions — plus the agent **nested** in the create body
 via `workflow_ai_agents` (a `cast_assoc`, not a separate attach call).
-Three pieces are worth stopping on.
+Four pieces are worth stopping on.
 
 The **filter** is the gray-zone band: it passes only screenings scoring at
 least `0.80` and below `0.95`. Below `0.80` is an auto-clear and at or
@@ -895,6 +895,13 @@ contains hyphens — into a single-element decision array. The two actions
 are keyed `decision_key: verified|blocked`; whichever verdict the agent
 emits picks the action that fires and leaves the other `:skipped`.
 
+The **`link_prefix`** is required on every SMS call, these two included.
+The verdict SMS carries no link of the walk's own, but its body echoes the
+agent's free-text comments, and a URL the model writes there 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 VERDICTS = ['verified', 'blocked'] as const
 
@@ -948,6 +955,7 @@ const workflow = await ctx.ensure(
             body: `[${verdict}] {{ additional_context["${ctx.agentSlug}"].comments }}`,
           },
           sms_type: 'transactional',
+          link_prefix: 'https://go.compliance.example.local/l',
         },
       })),
       // Workflow joins omit output_schema — the server pins it from the
@@ -1420,32 +1428,25 @@ if (!verdictBody.includes('[verified]')) {
 }
 ```
 
-## 026 — the KYC portal, as a connected app
+## 026 — the KYC portal, and the host in front of it
+
+The second scenario's SMS carries a link to a self-serve KYC portal, hosted
+outside the platform. Two addresses are in play, and neither is registered
+with the platform — there is nothing to create here.
+
+The **portal page** is the URL written into the SMS body, exactly as the
+holder 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 holder on to the portal — §036 does exactly that.
 
-The second scenario's SMS carries a deep link to a self-serve KYC portal.
-The connected app is a thin registration of that portal's URL and mode —
-the page itself is hosted outside the platform (`mode: 'self_hosted'`). The
-server-derived slug is what §036 resolves the link against.
+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 connectedApp = await ctx.ensure(
-  'KYC portal connected app',
-  async () => {
-    const { data } = await api.connectedApps.list(tenantSlug, datalakeSlug)
-    return (data.data ?? []).find((c: { name?: string }) => c.name === 'Cookbook KYC Portal')
-  },
-  async () => {
-    const { data } = await api.connectedApps.create(tenantSlug, datalakeSlug, {
-      name: 'Cookbook KYC Portal',
-      description: 'Self-serve KYC portal linked from the outbound notification SMS.',
-      mode: 'self_hosted',
-      urls: [{ url: 'https://kyc.example.local', is_primary: true, label: 'production' }],
-    })
-    return data
-  },
-)
-connectedAppId = connectedApp.id!
-ctx.connectedAppSlug = connectedApp.slug!
+ctx.kycPortalUrl = 'https://kyc.example.local/portal/kyc'
+ctx.kycLinkPrefix = 'https://go.kyc.example.local/l'
 ```
 
 ## 027 — the payment-accounts table
@@ -1504,12 +1505,17 @@ await ctx.deployGenericTable(ctx.accountsTableName)
 Standard shape: a filter passing accounts whose `status` is `active`, a
 decision naming one key, and one SMS action. The body references the
 account's external id so the recipient knows which account activated, and
-`{{ connected_app_form_url }}` so the platform bakes in the `/t/<token>`
-portal link.
+the portal URL itself — the platform swaps it at send for an authenticated
+link, because the action carries §026's `link_prefix`. `link_prefix` is
+required on every SMS call; `metadata_template` renders once per send and
+rides on the message, so the host behind the prefix gets the account's
+external id back with the link.
 
 `skip_mdm_resolution: false` is set explicitly and **must be**. The account
-holder is the subject the portal token is minted against, and it reaches
-the workflow only through the `legal_entity_id` stamped on the row.
+holder reaches the workflow only through the `legal_entity_id` stamped on
+the row, and resolution is what makes the message — and the link minted
+with it — name that holder. Skip it and the link still resolves, but it
+cannot say whose portal session it opens.
 
 A `context_datasets` entry queries the `message` dataset for any
 KYC notification already sent to the same legal entity in the last six
@@ -1529,7 +1535,7 @@ const KYC_DECISION_OUTPUT_SCHEMA = { type: 'array', items: { type: 'string' } }
 const SMS_BODY_TEMPLATE =
   'Alvera PR notification — payment_account ' +
   '{{ event_dataset.payment_account_external_id }} has been activated. ' +
-  'Manage KYC: {{ connected_app_form_url }}'
+  `Manage KYC: ${ctx.kycPortalUrl}`
 
 const kycWorkflow = await ctx.ensure(
   'KYC notification workflow',
@@ -1571,15 +1577,14 @@ const kycWorkflow = await ctx.ensure(
           position: 0,
           trigger_template: 'now',
           idempotency_template: '{{ event_dataset.payment_account_external_id }}-{{ decision_key }}',
-          connected_app_id: connectedAppId,
-          connected_app_route: '/portal/kyc',
-          connected_app_metadata_template:
+          metadata_template:
             '{"payment_account_external_id":"{{ event_dataset.payment_account_external_id }}"}',
           tool_call: {
             tool_call_type: 'sms_request',
             to: { type: 'custom', body: '+15551234567' },
             body: { type: 'custom', body: SMS_BODY_TEMPLATE },
             sms_type: 'transactional',
+            link_prefix: ctx.kycLinkPrefix,
           },
         },
       ],
@@ -1836,11 +1841,13 @@ if ((kycByStatus.filtered ?? 0) !== 1) {
 }
 ```
 
-## 035 — read the notification SMS back, and pull its portal token
+## 035 — read the notification SMS back, and pull its link token
 
 The passing action fired immediately and persisted a `message` row with
-the fully-rendered body. Extract the `/t/<token>` shortlink the platform
-baked in when it minted the connected-app page token.
+the body as sent. The portal URL is not in it: in its place stand §026's
+link prefix and a fifteen-character token. Finding the portal URL itself in
+the stored body would mean no link was minted, and the holder was sent
+straight to the portal with nothing to say who tapped.
 
 End-state assertion again, keyed the same way §025 is and for the same
 reason: on a repeat run the SMS was not re-sent, and the row from the first
@@ -1873,50 +1880,88 @@ if (kycMessages.length === 0) {
   )
 }
 
-const withLink = kycMessages
+const notification = kycMessages
   .map((m) => String(m.body ?? ''))
-  .find((body) => body.includes('/t/') && body.includes('Alvera PR notification'))
-if (!withLink) {
-  throw new Error(`no rendered body with a /t/ link — bodies: ${JSON.stringify(kycMessages.map((m) => m.body))}`)
+  .find((body) => body.includes('Alvera PR notification'))
+if (!notification) {
+  throw new Error(`no notification body — bodies: ${JSON.stringify(kycMessages.map((m) => m.body))}`)
 }
-const tokenMatch = withLink.match(/\/t\/([A-Za-z0-9_-]+)/)
-if (!tokenMatch) {
-  throw new Error(`no /t/<token> in rendered body: ${withLink}`)
+if (notification.includes(ctx.kycPortalUrl)) {
+  throw new Error(`the portal URL went out as written, so no link was minted: ${notification}`)
 }
-ctx.kycShortPath = tokenMatch[1]!
+const kycLinkStart = `${ctx.kycLinkPrefix}/`
+const kycToken = notification.split(kycLinkStart)[1]?.match(/^[A-Za-z0-9_-]{15}/)?.[0]
+if (!kycToken) throw new Error(`no ${kycLinkStart}<token> in the notification: ${notification}`)
+ctx.kycLinkToken = kycToken
 ```
 
-## 036 — resolve the deep link, and close the loop with tracking
+## 036 — the tap, the portal, and the submitted 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 holder and whom the link was
+for. Both calls here need only the tenant's publishable key — the host is
+not a signed-in user.
 
-The `/t/<token>` shortlink resolves through `connectedApps.resolvePage`,
-and the `route_path` must match the action's `connected_app_route`.
-Posting `opened_at` and `form_submitted_at` through
-`updateMessageTracking` then mirrors exactly what the portal frontend does
-when the holder opens it — closing the SMS-to-reply loop end to end.
+**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.
+
+The answer names the holder §028 resolved as `legal_entity_id`, and carries
+`metadata_template`'s output on the **message**, as `message.metadata` — the
+account's external id, which is all the portal needs to open the right
+account.
+
+Then the portal reports what the holder 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: resolved } = await api.connectedApps.resolvePage(
-  tenantSlug, datalakeSlug, ctx.connectedAppSlug,
-  { short_path: ctx.kycShortPath, user_agent: 'cookbook-doctest/kyc-notification' },
-)
-if (resolved.route_path !== '/portal/kyc') {
-  throw new Error(`resolvePage route_path mismatch: ${resolved.route_path}`)
+const { data: kycTap } = await api.authenticatedLinks.exchange(tenantSlug, datalakeSlug, {
+  token: ctx.kycLinkToken,
+  method: 'GET',
+  user_agent:
+    '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',
+  headers: { 'accept-language': 'en-US' },
+})
+if (kycTap.destination_url !== ctx.kycPortalUrl) {
+  throw new Error(`the link should lead to ${ctx.kycPortalUrl}, got ${kycTap.destination_url}`)
+}
+if (!kycTap.legal_entity_id) {
+  throw new Error('the link names no holder — MDM resolution did not reach the message')
+}
+if (kycTap.message.metadata?.payment_account_external_id !== ctx.activeExternalId) {
+  throw new Error(`metadata_template did not reach the message: ${JSON.stringify(kycTap.message.metadata)}`)
 }
-if (!(resolved.message?.body ?? '').includes('Alvera PR notification')) {
-  throw new Error('resolved page message body missing the notification copy')
+if (!kycTap.link_clicked_at || !kycTap.message.clicked_at) {
+  throw new Error("a person's tap should stamp link_clicked_at and the message's clicked_at")
 }
 
 const now = new Date().toISOString()
-const { data: tracked } = await api.connectedApps.updateMessageTracking(
-  tenantSlug, datalakeSlug, ctx.connectedAppSlug,
-  { short_path: ctx.kycShortPath, opened_at: now, form_submitted_at: now },
-)
-if (!tracked.message?.opened_at || !tracked.message?.form_submitted_at) {
+await api.authenticatedLinks.updateMessageTracking(tenantSlug, datalakeSlug, {
+  token: ctx.kycLinkToken,
+  status: 'opened',
+  opened_at: now,
+})
+const { data: tracked } = await api.authenticatedLinks.updateMessageTracking(tenantSlug, datalakeSlug, {
+  token: ctx.kycLinkToken,
+  status: 'form_submitted',
+  form_submitted_at: now,
+})
+if (!tracked.message.opened_at || !tracked.message.form_submitted_at) {
   throw new Error('message tracking did not persist opened_at + form_submitted_at')
 }
+if (tracked.message.status !== 'form_submitted') {
+  throw new Error(`the message should end at form_submitted, got ${tracked.message.status}`)
+}
 ```
 
-
 ## 037 — read one row back through all three lakes
 
 This is what §007 was for. The same row, the same SQL, three modes — and

package/.agent/cookbook/primary-care.md

@@ -47,7 +47,7 @@ needs to see that a message came in without seeing whose it was.
 | SMS tool, LLM tool, vision tool   | One dispatcher, two models                 |
 | Two AI agents                     | Triage, and document extraction            |
 | Two workflows                     | Review request, and category fan-out       |
-| Connected app                     | The review form the SMS links to           |
+| Authenticated link                | The review form the SMS links to           |
 
 # Walkthrough
 
@@ -499,7 +499,7 @@ ctx.deployGenericTable = async (tableName: string, timeoutMs = 180_000): Promise
 }
 ```
 
-## 009 — the SMS tool and the review connected app
+## 009 — the SMS tool and the review page
 
 One SMS tool dispatches every outbound message in this walk. **The
 per-message body lives on the workflow action, never on the tool**, which is
@@ -507,10 +507,15 @@ what lets one tool serve both the review request and the triage fan-out.
 Local dev points at LocalStack's SNS on `:4566`, so nothing leaves the
 machine.
 
-The connected app is the review form the SMS links to — a thin registration
-of the page's URL and hosting mode, with the page itself living outside the
-platform. Capture the server-derived slug; resolving the link in §019 is
-addressed by it.
+The review form the SMS links to lives outside the platform, and it is two
+addresses, neither registered with the platform. The **page** is the URL
+written into the SMS body, exactly as the patient 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 reaches that host first. The host asks the
+platform what the link is, then sends the patient on to the form — §019
+does exactly that. 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 smsTool = await ctx.ensure(
@@ -542,25 +547,8 @@ const smsTool = await ctx.ensure(
 toolId = smsTool.id!
 ctx.smsToolId = smsTool.id!
 
-const reviewApp = await ctx.ensure(
-  'review connected app',
-  async () => {
-    const { data } = await api.connectedApps.list(tenantSlug, datalakeSlug, { page_size: 100 })
-    return ctx.firstNamed(data.data, 'Cookbook Visit Review Form')
-  },
-  async () => {
-    const { data } = await api.connectedApps.create(tenantSlug, datalakeSlug, {
-      name: 'Cookbook Visit Review Form',
-      description: 'Post-visit review form linked from the outbound review SMS.',
-      mode: 'self_hosted',
-      urls: [{ url: 'https://review.example.local', is_primary: true, label: 'production' }],
-    })
-    return data
-  },
-)
-connectedAppId = reviewApp.id!
-ctx.reviewAppId = reviewApp.id!
-ctx.reviewAppSlug = reviewApp.slug!
+ctx.reviewFormUrl = 'https://review.example.local/review/visit'
+ctx.reviewLinkPrefix = 'https://go.review.example.local/l'
 ```
 
 ## 010 — the appointments table, and the one column that exercises everything
@@ -902,7 +890,9 @@ The **row count** catches an ingest that reported green over nothing. The
 **status values** catch a contract whose mapping silently fell through to the
 `pending` default — which would leave the filter in §018 with nothing to
 route and make the whole scenario a false green. The **stamp** catches a
-resolve that never ran, which would leave every link minted against nobody.
+resolve that never ran, which would leave every link naming nobody — so the
+fulfilled visit's stamp is kept, and §019 checks the review link names that
+same patient.
 
 And **`patient_mobile` must not be null**, which is the one that catches a
 misspelled vendor key. A template reading a field the payload does not carry
@@ -954,6 +944,7 @@ for (const [id, row] of byId) {
     )
   }
 }
+ctx.fulfilledPatientId = String(byId.get(ctx.fulfilledId)!.stamp)
 ```
 
 ## 016 — a populated masked array survives the copy
@@ -1064,10 +1055,15 @@ Standard shape — filter, decision, one action — targeting §010's table.
 
 `skip_mdm_resolution: false` is set explicitly, and must be. A generic-table
 row is never its own subject; the subject is the patient §012's pair 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 }}` *this
-patient's* review link. Skip it and the token is never minted and the link
-renders empty.
+onto it. With resolution on, the platform loads that subject, and the message
+— and the link minted with it — names *this patient* as its
+`legal_entity_id`. Skip it and the link still resolves, but it cannot say
+whose review it is.
+
+The body carries §009's form URL itself; the action's `link_prefix` is what
+turns it into this message's own link at send, and it is required on every
+SMS call. `metadata_template` renders once per send and rides on the
+message, so the host gets the appointment back with the link.
 
 The filter is one comparison — `status == "fulfilled"` — and it carries the
 whole clinical rule this scenario exists for: never ask someone to review a
@@ -1120,9 +1116,7 @@ const reviewWorkflow = await ctx.ensure(
           position: 0,
           trigger_template: 'now',
           idempotency_template: `{{ event_dataset.appointment_id }}-${REVIEW_KEY}`,
-          connected_app_id: ctx.reviewAppId,
-          connected_app_route: '/review/visit',
-          connected_app_metadata_template: '{"appointment_id":"{{ event_dataset.appointment_id }}"}',
+          metadata_template: '{"appointment_id":"{{ event_dataset.appointment_id }}"}',
           tool_call: {
             tool_call_type: 'sms_request',
             to: { type: 'custom', body: '{{ event_dataset.patient_mobile }}' },
@@ -1131,9 +1125,10 @@ const reviewWorkflow = await ctx.ensure(
               body:
                 'Hi {{ event_dataset.patient_name }}, thanks for visiting ' +
                 '{{ event_dataset.department }}. How did we do? ' +
-                '{{ connected_app_form_url }}',
+                ctx.reviewFormUrl,
             },
             sms_type: 'transactional',
+            link_prefix: ctx.reviewLinkPrefix,
           },
         },
       ],
@@ -1220,9 +1215,22 @@ Search on the **idempotency key**, never on `workflow_id`. The key is
 names the same message forever. A workflow id is stable only as long as the
 workflow resource is.
 
-Then resolve the `/t/<token>` the platform baked into the body when it minted
-the page token, and post the tracking a connected-app frontend would post
-when the patient opens the form.
+The stored body is the body as sent, so the form URL is not in it: in its
+place stand the link prefix and a fifteen-character token. Finding the form
+URL itself would mean no link was minted.
+
+Then play the host behind the prefix. Hand the token to
+`authenticatedLinks.exchange` with what the tap's request said about itself
+— a phone's browser, because the platform judges from those details whether
+a person tapped, and only a person's tap stamps `link_clicked_at` and the
+message's `clicked_at`. The answer names the patient and carries the
+appointment on `message.metadata`. Both calls need only the tenant's
+publishable key.
+
+Then the form reports what the patient did, with the same token. The message
+status only moves forward, and `opened` ranks below `clicked`, so 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: search } = await api.datasets.createUserSearch(tenantSlug, datalakeSlug, 'message', {
@@ -1241,32 +1249,57 @@ while (Date.now() < msgDeadline && !reviewBody) {
   })
   reviewBody = ((data.data ?? []) as Array<Record<string, unknown>>)
     .map((m) => String(m.body ?? ''))
-    .find((b) => b.includes('/t/') && b.includes('How did we do?'))
+    .find((b) => b.includes('How did we do?'))
   if (!reviewBody) await new Promise((r) => setTimeout(r, 2_000))
 }
 if (!reviewBody) {
   throw new Error(`no rendered review SMS for ${ctx.fulfilledId} within 90s`)
 }
+if (reviewBody.includes(ctx.reviewFormUrl)) {
+  throw new Error(`the form URL went out as written, so no link was minted: ${reviewBody}`)
+}
+const reviewLinkStart = `${ctx.reviewLinkPrefix}/`
+const reviewToken = reviewBody.split(reviewLinkStart)[1]?.match(/^[A-Za-z0-9_-]{15}/)?.[0]
+if (!reviewToken) throw new Error(`no ${reviewLinkStart}<token> in the review body: ${reviewBody}`)
 
-const token = reviewBody.match(/\/t\/([A-Za-z0-9_-]+)/)
-if (!token) throw new Error(`no /t/<token> in the review body: ${reviewBody}`)
-
-const { data: resolved } = await api.connectedApps.resolvePage(
-  tenantSlug, datalakeSlug, ctx.reviewAppSlug,
-  { short_path: token[1]!, user_agent: 'cookbook-doctest/primary-care' },
-)
-if (resolved.route_path !== '/review/visit') {
-  throw new Error(`the review link resolved to the wrong route: ${resolved.route_path}`)
+const { data: tap } = await api.authenticatedLinks.exchange(tenantSlug, datalakeSlug, {
+  token: reviewToken,
+  method: 'GET',
+  user_agent:
+    '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',
+  headers: { 'accept-language': 'en-US' },
+})
+if (tap.destination_url !== ctx.reviewFormUrl) {
+  throw new Error(`the review link should lead to ${ctx.reviewFormUrl}, got ${tap.destination_url}`)
+}
+if (tap.legal_entity_id !== ctx.fulfilledPatientId) {
+  throw new Error(`the review link should name patient ${ctx.fulfilledPatientId}, got ${tap.legal_entity_id}`)
+}
+if (tap.message.metadata?.appointment_id !== ctx.fulfilledId) {
+  throw new Error(`metadata_template did not reach the message: ${JSON.stringify(tap.message.metadata)}`)
+}
+if (!tap.link_clicked_at || !tap.message.clicked_at) {
+  throw new Error("a person's tap should stamp link_clicked_at and the message's clicked_at")
 }
 
 const now = new Date().toISOString()
-const { data: tracked } = await api.connectedApps.updateMessageTracking(
-  tenantSlug, datalakeSlug, ctx.reviewAppSlug,
-  { short_path: token[1]!, opened_at: now, form_submitted_at: now },
-)
-if (!tracked.message?.opened_at || !tracked.message?.form_submitted_at) {
+await api.authenticatedLinks.updateMessageTracking(tenantSlug, datalakeSlug, {
+  token: reviewToken,
+  status: 'opened',
+  opened_at: now,
+})
+const { data: tracked } = await api.authenticatedLinks.updateMessageTracking(tenantSlug, datalakeSlug, {
+  token: reviewToken,
+  status: 'form_submitted',
+  form_submitted_at: now,
+})
+if (!tracked.message.opened_at || !tracked.message.form_submitted_at) {
   throw new Error('message tracking did not persist opened_at + form_submitted_at')
 }
+if (tracked.message.status !== 'form_submitted') {
+  throw new Error(`the message should end at form_submitted, got ${tracked.message.status}`)
+}
 ```
 
 ## 020 — the Contact Us table, and its client you did not create
@@ -1469,6 +1502,11 @@ query, and obvious solicitation — so the classification is not a coin toss
 and the assertion in §023 means something. `category` is left unset on
 ingest; assigning it is the agent's job.
 
+`link_prefix` is required on every SMS call, these routing alerts
+included, though their bodies carry no URL — a body with none is sent
+unchanged. Leave it off and the workflow is refused at create with a 422 on
+`/actions/<n>/tool_call/link_prefix`.
+
 ```typescript
 const CATEGORIES = ['clinical', 'billing', 'appointment', 'spam'] as const
 
@@ -1508,6 +1546,7 @@ const triageWorkflow = await ctx.ensure(
             body: `[${category}] contact-us submission {{ event_dataset.submission_id }} needs routing.`,
           },
           sms_type: 'transactional' as const,
+          link_prefix: 'https://go.triage.example.local/l',
         },
       })),
       workflow_ai_agents: [