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

package/.agent/tool-call-configs.md

@@ -84,11 +84,11 @@ Sends an SMS message via the configured SMS provider.
 
 ## Tool Call Configuration (mms_request)
 
-Sends an MMS (media message) via AWS End User Messaging.
+Sends an MMS (media message) via AWS End User Messaging or Twilio.
 
 - **to** (TemplateConfig) — Recipient phone number in E.164 format, rendered as Liquid template
 - **body** (TemplateConfig) — Message body (caption), rendered as Liquid template
-- **media_url** (string) — Public http(s) URL of the media to attach; verified reachable (GET 2xx + image/*) at authoring, fetched and re-staged into the tool's S3 media bucket at send
+- **media_url** (string) — Public http(s) URL of the media to attach; verified reachable (GET 2xx + image/*) at authoring, fetched at send (re-staged into the tool's S3 media bucket for End User Messaging; passed to Twilio as `MediaUrl`)
 
 <!-- alvera:section kind="tool-call-config" atom="email_request" module="Platform.Tools.ToolCallConfig.EmailRequest" -->
 

package/.agent/tools.md

@@ -628,6 +628,7 @@ await api.tools.testInvocation(
       to:   { type: 'custom', body: '+15551234567' },
       body: { type: 'custom', body: 'Hello' },
       sms_type: 'transactional',       // sms_request-specific
+      link_prefix: 'https://go.example.com/l',   // required on sms / mms / email
     },
   },
 )
@@ -671,11 +672,15 @@ per-branch required-list for the five test-invocable variants:
 
 ```
    tool_call_type: 'sms_request'
-     required:   to, body, sms_type
+     required:   to, body, sms_type, link_prefix
+     optional:   link_validity_days (default 365)
      enums:      sms_type ∈ { 'transactional' (default), 'promotional' }
+     notes:      every URL in body goes out as <link_prefix>/<token> —
+                 see authenticated_links.md
 
    tool_call_type: 'mms_request'
-     required:   to, body, media_url
+     required:   to, body, media_url, link_prefix
+     optional:   link_validity_days (default 365)
      notes:      body is the message caption; media_url is a PLAIN
                  STRING — a public http(s) URL, no Liquid. The server
                  verifies it at authoring (GET must answer 2xx with an
@@ -685,7 +690,9 @@ per-branch required-list for the five test-invocable variants:
                  is end_user_messaging
 
    tool_call_type: 'email_request'
-     required:   to, subject, body
+     required:   to, subject, body, link_prefix
+     optional:   link_validity_days (default 365)
+     notes:      every href in body goes out as <link_prefix>/<token>
      embeds:     TemplateConfig variants accepted on each ({ type:
                  'custom', body } or { type: 'identity' } or
                  { type: 'system', path }); 'null' is not valid here

package/.agent/type_naming.md

@@ -67,8 +67,7 @@ they are **not** interchangeable as call arguments:
    slug    the human handle — the path key for runtime / operations
              verbs (workflows `execute` / `run` / logs, datalakes
              `migrate`, data-activation-client ingest / run, interop
-             `run`, connected-apps `resolvePage` /
-             `updateMessageTracking`). NOT accepted by a CRUD `.get`.
+             `run`). NOT accepted by a CRUD `.get`.
    name    generic tables only — the physical Postgres table name
              (`alvera_custom_<slug>`) a DAC ingests into. NOT an API
              path key; CRUD still keys on the UUID `id`. See
@@ -100,8 +99,8 @@ const toolId = created.id!      // <-- CRUD + cross-resource refs
 // A tool has NO slug, and neither does a generic table — they are
 // addressed by id and by name respectively. The slug-bearing responses
 // are the ones whose ops verbs take a slug in the path: datalakes,
-// workflows, data activation clients, connected apps, AI agents and
-// interoperability contracts. Reach for `.slug` only on those, and
+// workflows, data activation clients, AI agents and interoperability
+// contracts. Reach for `.slug` only on those, and
 // note every id and slug is optional on the wire, so a strict consumer
 // needs the `!` (or a guard) that the cookbooks use.
 

package/.agent/workflows.md

@@ -30,8 +30,8 @@ api.workflows.workflowLogs    — one log row per dataset row processed
 ```
 
 Workflows are **Datalake-DB-resident** — the parent datalake must
-be `status: 'ready'` and every referenced resource (tools,
-connected apps, AI agents) must exist before you `create()`.
+be `status: 'ready'` and every referenced resource (tools, AI
+agents) must exist before you `create()`.
 
 ## 1. Wire shape
 
@@ -54,9 +54,9 @@ const { data: created } = await api.workflows.create(
     dataset_type: 'generic_table',
     generic_table_id: appointmentsTableId,
 
-    // Load-bearing whenever an action mints a per-subject
-    // `connected_app_form_url`: resolution is what attaches the row
-    // to its legal entity. See §2.
+    // Load-bearing whenever a message carries a link: resolution is
+    // what gives the link its `legal_entity_id`, the person a tap on
+    // it belongs to. See §2 and authenticated_links.md.
     skip_mdm_resolution: false,
 
     status: 'live',                         // 'live' | 'draft' | 'manual' (see §5)
@@ -99,15 +99,19 @@ const { data: created } = await api.workflows.create(
         idempotency_template:
           '{{ event_dataset.appointment_id }}-{{ decision_key }}',
 
-        connected_app_id: connectedAppId,
-        connected_app_route: '/forms/review',
-        connected_app_metadata_template:
+        // Rendered once per send and stored on the message; the host
+        // behind link_prefix reads it back from the exchange's
+        // `message.metadata`. See §7.
+        metadata_template:
           '{"appointment_id":"{{ event_dataset.appointment_id }}"}',
         tool_call: {
           tool_call_type: 'sms_request',
           to:   { type: 'custom', body: '{{ event_dataset.patient_mobile | e164 }}' },
-          body: { type: 'custom', body: 'Hi {{ event_dataset.patient_name | split: " " | first }}, please share your feedback at {{ connected_app_form_url }}' },
+          // Write the real destination. At send, every URL in the body
+          // goes out as <link_prefix>/<token>.
+          body: { type: 'custom', body: 'Hi {{ event_dataset.patient_name | split: " " | first }}, please share your feedback at https://reviews.example.com/visit' },
           sms_type: 'transactional',
+          link_prefix: 'https://go.example.com/l',   // REQUIRED on sms / mms / email calls
         },
       },
     ],
@@ -446,9 +450,9 @@ for every dataset type.** Choose it by what the workflow needs:
 
 - **Leave it `false`** whenever the workflow must resolve the row to an
   MDM subject — which is required for anything keyed on a subject: a
-  connected-app page token / tracked link (the token *requires* a
-  subject id — see `connected_apps.md`), a `messages` row, or
-  cross-dataset context. A `generic_table` workflow can absolutely run
+  link that knows who tapped it (without resolution its
+  `legal_entity_id` is `null` — see `authenticated_links.md`), a
+  `messages` row, or cross-dataset context. A `generic_table` workflow can absolutely run
   with resolution ON: stamp the entity FK (e.g. `legal_entity_id`) onto
   the row at ingestion and the workflow resolves its subject from that
   FK.
@@ -573,11 +577,14 @@ position                     optional int  — display order, default 0
 runtime_filter               optional string — fire-time skip / pause lever (§2)
 action_window_start          optional int  — send-window open hour 0–23 (§2)
 action_window_end            optional int  — send-window close hour 0–23 (§2)
-connected_app_id             optional UUID — :sms/:email only (see connected_apps.md)
-connected_app_route          optional string — required when connected_app_id set
-connected_app_metadata_template  optional string — Liquid→JSON stored in the page token
+metadata_template            optional string — Liquid→JSON rendered once per send, stored
+                                              on the message (§7); every action type
 ```
 
+Inside `tool_call`, the `sms_request`, `mms_request` and `email_request`
+variants also take `link_prefix` (**required**) and `link_validity_days`
+(optional, default 365) — see §7.
+
 **Write-only (Request-only).** None.
 
 ## 5. Lifecycle
@@ -714,7 +721,7 @@ an error to retry.
 tables. For a **platform dataset** the server assigns the alias
 (`le` legal entities, `m` messages, `al` action logs, `d` documents,
 `bo` beneficial owners — same scheme as `data_activation_clients.md`
-§6.5), and `id` is ambiguous across the base query's joins, so always
+§6.6), and `id` is ambiguous across the base query's joins, so always
 prefix it: `le.id`.
 
 For a **generic-table** workflow there is no alias — the run selects
@@ -970,34 +977,31 @@ workflow execution log row's `error_message` is intentionally
 coarse so the database column doesn't grow with arbitrary
 provider responses. Always read `error.json` for diagnostics.
 
-## 7. Connected apps as action sinks
-
-Workflows that send messages (SMS, email) typically link to a
-**connected app** — a registered consumer of the action's
-rendered URL. See `api.connectedApps`:
+## 7. Links in a message
 
-```typescript
-await api.connectedApps.create(tenantSlug, datalakeSlug, {
-  name: 'Review form',
-  description: '...',
-  mode: 'self_hosted',                               // 'self_hosted' | 'managed'
-  urls: [{ url: 'https://app.example.com', is_primary: true, label: 'production' }],
-})
-```
+Every URL in an SMS or MMS body, and every `href` in an email body,
+goes out as an authenticated link, `<link_prefix>/<token>`. Write the
+real destination into the body; the platform rewrites it at send.
 
 Action wiring on the workflow:
-- `connected_app_id` — UUID of the bound connected app
-- `connected_app_route` — path on the app (e.g. `/forms/review`)
-- `connected_app_metadata_template` — Liquid template rendering
-  a JSON object that the recipient can introspect after
-  resolving the token
-
-At fire time, the action's message body's `{{ connected_app_form_url }}`
-expands to `https://<app-primary>/t/<short_path>`. The recipient
-hits that URL; the connected app calls
-`api.connectedApps.resolvePage` with the `short_path` to fetch
-the metadata, then `api.connectedApps.updateMessageTracking` to
-record `opened_at` / `form_submitted_at`.
+- `tool_call.link_prefix` — **required** on `sms_request`,
+  `mms_request` and `email_request`: the address of the host you run
+  to serve the links. Absolute `http`/`https`, path allowed, no query,
+  fragment or trailing slash.
+- `tool_call.link_validity_days` — how many days each link resolves
+  after the send; default 365.
+- `metadata_template` — on the action itself, any action type: a
+  Liquid template rendering a JSON object, once per send. It is
+  stored on the message, beside the recipient's `to`, and a template
+  that does not render fails the send.
+
+When a person taps the link, your host calls
+`api.authenticatedLinks.exchange` with the token and gets back where
+the link goes, who it was for, and the message — its `metadata`
+included. When the page opens or the form is submitted, the host
+reports it with `api.authenticatedLinks.updateMessageTracking`. The
+whole surface, its refusals (404 · 410 · 503) and what counts as a
+person's tap are in `authenticated_links.md`.
 
 ## 8. Watching a run — what to read for which question
 

package/README.md

@@ -138,7 +138,7 @@ Every resource is a typed namespace on the client (`api.<resource>.<verb>`):
 | `genericTables`              | `list`, `create`                                                                                                                             |
 | `actionStatusUpdaters`       | `list`, `create`, `update`                                                                                                                   |
 | `aiAgents`                   | `list`, `get`, `create`, `update`, `delete`, `invoke`                                                                                        |
-| `connectedApps`              | `list`, `get`, `create`, `update`, `syncRoutes`, `resolvePage`, `updateMessageTracking`                                                      |
+| `authenticatedLinks`         | `exchange`, `updateMessageTracking`                                                                                                          |
 | `dataActivationClients`      | `list`, `get`, `create`, `update`, `delete`, `metadata`, `runManually`, `ingest`, `ingestFile`, `logs.list`, `logs.get`                      |
 | `interoperabilityContracts`  | `list`, `get`, `create`, `update`, `delete`, `metadata`, `run`                                                                               |
 | `mdm`                        | `verify`                                                                                                                                     |