@alvera-ai/platform-sdk 0.17.0 → 0.17.2

package/.agent/cookbook/marketing-campaign-send.md

@@ -61,6 +61,9 @@ starts from there.
 | Audience contracts + audience activation client | build  |
 | SMS tool (SNS-backed)                         | build    |
 | Email tool (`provider: 'mock'`)               | build    |
+| SES email tool (LocalStack)                   | build    |
+| SES event reader tool + SES delivery updater  | build    |
+| SES Delivery Check workflow                   | build    |
 | Campaign Booking Form connected app           | build    |
 | Loyalty Campaign workflow                     | build    |
 | Reply contract + reply activation client      | build    |
@@ -130,7 +133,7 @@ it, so a suppressed customer is unselectable by *any* campaign, not
 merely hidden in a UI. `phone` and `email` are the two channel
 destinations, and their presence is the reachability gate. `bucket`
 is the A/B assignment, an integer 0–99 stamped at ingest (§006) and
-split on by the decision node (§009).
+split on by the decision node (§010).
 
 The three PII columns are `tokenize`; `suppressed` and `bucket` are
 `none` — they are campaign mechanics, not personal data, and the
@@ -197,7 +200,7 @@ load-bearing.
 
 The data source's `uri` flows into every ingested row as
 `source_uri`, and the contracts render it onto the MDM identifier's
-`system`. The reply (§012) re-attaches by looking up
+`system`. The reply (§013) re-attaches by looking up
 `(system, handle)`. If the reply arrived through a *different* data
 source, its `system` would differ, the lookup would miss, and the
 reply would attach to nobody. One capture system, one `uri`, one
@@ -238,7 +241,7 @@ The `legal_entity` contract shapes the MDM subject
 the table row — and its `mdm_input_config` is what tells the platform
 which subject this row belongs to. The platform then **stamps that
 subject's id onto the row** as `legal_entity_id`. That stamp is the
-whole point: §009's workflow resolves a row's MDM subject from the
+whole point: §010's workflow resolves a row's MDM subject from the
 stamped FK, never from the row's own id.
 
 ```typescript
@@ -317,7 +320,7 @@ campaign.
 First, each recipient resolves to an **individual** legal entity —
 their own MDM subject, keyed on their contact handle (phone if
 present, else email). That subject is what the per-recipient short
-link (§011) is minted against.
+link (§012) is minted against.
 
 Second, the generic-table contract assigns the **`bucket`**. It is
 derived from the last two digits of the vendor's own id
@@ -494,7 +497,7 @@ ctx.adaSubjectId = String(byId.get(`EC-${runSuffix}-10`)!.legal_entity_id)
 
 **Two sender tools, not one.** An SMS number and an email identity
 are different assets, provisioned and billed separately, so they are
-separate tools — and §009's actions bind each channel to its own.
+separate tools — and §010's actions bind each channel to its own.
 
 The email tool uses `provider: 'mock'`, which delivers in-process to
 the dev mailbox at `/dev/mailbox` — no credentials, no provider
@@ -505,7 +508,7 @@ deployment to be in "test mode". Swap `mock` for `ses` and the same
 workflow sends real email.
 
 The connected app is the campaign's booking form. It is registered
-here, and §009's actions deep-link into it.
+here, and §010's actions deep-link into it.
 
 ```typescript
 const { ToolIntent } = await import('@alvera-ai/platform-sdk')
@@ -553,7 +556,344 @@ connectedAppId = app.id!
 ctx.connectedAppSlug = app.slug!
 ```
 
-## 009 — the campaign workflow
+## 009 — an SES sender on LocalStack, and its delivery read back from SES's own events
+
+§008's email tool delivers in-process. A deployment sends through Amazon
+SES, and this step proves the SES path end to end on a laptop, with
+LocalStack standing in for AWS.
+
+**An SES tool sends to its own `endpoint_url`.** It is the whole request
+URL; left blank, the tool uses `https://email.<region>.amazonaws.com`.
+Pointed at LocalStack (`http://localhost:4566`), every send goes there
+instead, so the walk needs no AWS account. LocalStack keeps each message
+it accepts, raw, at `http://localhost:4566/_aws/ses`.
+
+**LocalStack refuses an unverified sender, as SES does.** Verify the
+from address first. Outside this walk that is
+`aws --endpoint-url http://localhost:4566 --region us-east-1 ses verify-email-identity --email-address <sender>`
+with LocalStack's keys (`localkey` / `localsecret`); the step makes the
+same call over HTTP. A send from the address before it is verified is
+refused; after, it is accepted.
+
+**A test call sends, but writes no message row.** `testInvocation` is
+the quick check that the tool reaches its provider. Reconciling a
+delivery needs a message row, and a message row comes from a workflow,
+so the step also sends one email to one recipient from a workflow whose
+only action uses the SES tool. That workflow is `status: 'manual'`: it
+runs only when invoked. A `live` workflow is also fired by event
+sampling, so a live check workflow over the audience would go on to
+email everyone in it, the suppressed customer included, the next time
+the audience changes.
+
+**Name a status template by its provider's path.** Mailgun and SES both
+ship an `email_message_status` under `status_poller`, so the bare name
+answers 409 with both paths as candidates. The updater names
+`status_poller/aws_ses/email_message_status` and
+`status_poller/aws_ses/email_action_log_status`.
+
+**Delivery comes from SES's own events.** SES has no CloudWatch Logs
+destination of its own: its events travel configuration set →
+EventBridge → rule → log group, each wrapped in EventBridge's envelope
+with the SES event under `detail`. The SES templates find the message by
+`detail.mail.messageId`, which is the row's `external_id`, and record:
+
+| SES event | Message becomes | Also set |
+|---|---|---|
+| Delivery | `delivered` | `delivered_at` |
+| Bounce, Reject | `failed` | `failure_reason` |
+| Complaint | `customer_rejected` | |
+| Open | `read` | `read_at` |
+| Click | `clicked` | `clicked_at` |
+| anything else (Send, DeliveryDelay, …) | unchanged | |
+
+LocalStack publishes none of those events, so the step writes them
+into a log group itself: a Send and a Delivery for the message it just
+sent, and a Bounce for another message.
+
+**`refresh` only enqueues a poll.** Read the updater again until
+`last_run_at` is set. The poll reads the log group one page per job to
+the end of its window, so `last_run_status` is `ok` when it read the
+whole window and `error` when it stopped, never anything in between.
+
+```typescript
+const { ToolIntent } = await import('@alvera-ai/platform-sdk')
+
+const SES_ENDPOINT = 'http://localhost:4566'
+const SES_LOG_GROUP = `/aws/events/cookbook-ses-${runSuffix}`
+const SES_DECISION_KEY = 'ses_delivery_check'
+const sesSender = `campaigns-${runSuffix}@bloom-salon.example.com`
+
+// LocalStack reads the region and account from the Authorization header
+// and does not check the signature, so a fixed header stands in for SigV4.
+const localstack = (service: string, contentType: string, body: string, target?: string) =>
+  fetch(SES_ENDPOINT, {
+    method: 'POST',
+    headers: {
+      'Content-Type': contentType,
+      Authorization:
+        `AWS4-HMAC-SHA256 Credential=localkey/20260101/us-east-1/${service}/aws4_request, ` +
+        'SignedHeaders=content-type;host, Signature=localstack',
+      ...(target ? { 'X-Amz-Target': target } : {}),
+    },
+    body,
+  })
+const logs = async (action: string, payload: Record<string, unknown>) => {
+  const res = await localstack('logs', 'application/x-amz-json-1.1', JSON.stringify(payload), `Logs_20140328.${action}`)
+  const text = await res.text()
+  if (!res.ok && !text.includes('ResourceAlreadyExistsException')) {
+    throw new Error(`LocalStack logs ${action} failed (${res.status}): ${text}`)
+  }
+}
+
+// The SES tool, pointed at LocalStack.
+const { data: sesTool } = await api.tools.create(tenantSlug, datalakeSlug, {
+  name: `Cookbook Campaign SES Sender ${runSuffix}`,
+  description: 'SES email dispatcher, pointed at LocalStack by endpoint_url.',
+  intent: ToolIntent.EMAIL,
+  status: 'active',
+  datalake_id: ctx.datalakeId,
+  body: {
+    tool_body_type: 'email',
+    provider: 'ses',
+    from_email: sesSender,
+    from_name: 'Bloom Salon',
+    region: 'us-east-1',
+    access_key_id: 'localkey',
+    secret_access_key: 'localsecret',
+    endpoint_url: SES_ENDPOINT,
+  },
+})
+ctx.sesToolId = sesTool.id!
+const { data: storedSes } = await api.tools.get(tenantSlug, datalakeSlug, ctx.sesToolId)
+const storedSesBody = storedSes.body as { provider?: string; endpoint_url?: string | null }
+if (storedSesBody.provider !== 'ses' || storedSesBody.endpoint_url !== SES_ENDPOINT) {
+  throw new Error(`the SES tool must keep its endpoint, read back ${JSON.stringify(storedSesBody)}`)
+}
+
+// A test call before the sender is verified is refused; after, accepted.
+const testCall = {
+  tool_call: {
+    tool_call_type: 'email_request' as const,
+    to: { type: 'custom' as const, body: 'test-ses-check@example.com' },
+    subject: { type: 'custom' as const, body: 'SES check' },
+    body: { type: 'custom' as const, body: 'Sent through LocalStack.' },
+  },
+}
+const tryIt = async (): Promise<{ status?: string; result?: unknown; error_message?: string | null }> => {
+  try {
+    const { data } = await api.tools.testInvocation(tenantSlug, datalakeSlug, ctx.sesToolId, testCall)
+    return data
+  } catch (err) {
+    return { status: 'error', error_message: JSON.stringify(err) }
+  }
+}
+const refused = await tryIt()
+if (refused.status !== 'error') {
+  throw new Error(`a send from an unverified sender must be refused, got ${JSON.stringify(refused)}`)
+}
+const verified = await localstack(
+  'ses',
+  'application/x-www-form-urlencoded',
+  new URLSearchParams({ Action: 'VerifyEmailIdentity', Version: '2010-12-01', EmailAddress: sesSender }).toString(),
+)
+if (!verified.ok) throw new Error(`VerifyEmailIdentity failed (${verified.status}): ${await verified.text()}`)
+const accepted = await tryIt()
+if (accepted.status !== 'success') {
+  throw new Error(`a send from a verified sender must be accepted, got ${JSON.stringify(accepted)}`)
+}
+const inbox = (await (await fetch(`${SES_ENDPOINT}/_aws/ses`)).json()) as {
+  messages?: Array<{ Id?: string; Source?: string }>
+}
+const keptByLocalStack = (inbox.messages ?? []).filter((m) => String(m.Source ?? '').includes(sesSender))
+if (keptByLocalStack.length !== 1 || !JSON.stringify(accepted.result ?? {}).includes(String(keptByLocalStack[0]!.Id))) {
+  throw new Error(
+    `the test call's message must be the one LocalStack keeps: ${JSON.stringify({ accepted, keptByLocalStack })}`,
+  )
+}
+
+// The bare template name is ambiguous between Mailgun and SES.
+let bareName: unknown
+try {
+  await api.templates.metadataDetails(tenantSlug, datalakeSlug, 'email_message_status', 'status_poller')
+} catch (err) {
+  bareName = err
+}
+if ((bareName as { _httpStatus?: number } | undefined)?._httpStatus !== 409) {
+  throw new Error(`the bare email_message_status must answer 409, got ${JSON.stringify(bareName)}`)
+}
+if (!JSON.stringify(bareName).includes('status_poller/aws_ses/email_message_status')) {
+  throw new Error(`the 409 must name the SES path among its candidates: ${JSON.stringify(bareName)}`)
+}
+
+// The log group SES's events land in, its reader, and the updater.
+await logs('CreateLogGroup', { logGroupName: SES_LOG_GROUP })
+const { data: sesReader } = await api.tools.create(tenantSlug, datalakeSlug, {
+  name: `Cookbook SES Event Reader ${runSuffix}`,
+  description: "Reads SES's delivery events from a CloudWatch log group on LocalStack.",
+  intent: 'status_poller',
+  status: 'active',
+  datalake_id: ctx.datalakeId,
+  data_source_id: dataSourceId,
+  body: {
+    tool_body_type: 'cloud_watch_log_group',
+    auth_method: 'access_key',
+    region: 'us-east-1',
+    endpoint_url: SES_ENDPOINT,
+    access_key_id: 'localkey',
+    secret_access_key: 'localsecret',
+  },
+})
+const { data: sesUpdater } = await api.actionStatusUpdaters.create(tenantSlug, datalakeSlug, {
+  name: `Cookbook SES Delivery Updater ${runSuffix}`,
+  cron_expression: '*/30 * * * *',
+  updater_type: 'cloud_watch',
+  updater_tool_id: sesReader.id!,
+  sender_tool_ids: [ctx.sesToolId],
+  datalake_id: ctx.datalakeId,
+  updater_body: {
+    updater_body_type: 'cloud_watch_request',
+    log_group_name: SES_LOG_GROUP,
+    start_time: '{{ now_msec | minutes_ago: 45 }}',
+    end_time: '{{ now_msec }}',
+  },
+  message_config: { type: 'system', path: 'status_poller/aws_ses/email_message_status' },
+  action_log_config: { type: 'system', path: 'status_poller/aws_ses/email_action_log_status' },
+})
+ctx.sesUpdaterId = sesUpdater.id!
+
+// One email, to Ada, from a workflow whose only action is the SES tool.
+const { data: sesCheck } = await api.workflows.create(tenantSlug, datalakeSlug, {
+  name: `Cookbook SES Delivery Check ${runSuffix}`,
+  description: 'One email through the SES tool, so its delivery can be read back.',
+  dataset_type: 'generic_table',
+  generic_table_id: ctx.audienceTableId,
+  status: 'manual',
+  tags: ['marketing', 'ses'],
+  skip_mdm_resolution: false,
+  filter_config: {
+    type: 'custom',
+    body: '{% if event_dataset.email and event_dataset.email != "" %}true{% endif %}',
+    output_schema: { type: 'boolean' },
+  },
+  decision_config: {
+    type: 'custom',
+    body: `["${SES_DECISION_KEY}"]`,
+    output_schema: { type: 'array', items: { type: 'string' } },
+  },
+  actions: [
+    {
+      action_type: 'email',
+      tool_id: ctx.sesToolId,
+      decision_key: SES_DECISION_KEY,
+      position: 0,
+      trigger_template: 'now',
+      idempotency_template: '{{ event_dataset.end_customer_id }}/ses-delivery-check',
+      tool_call: {
+        tool_call_type: 'email_request',
+        to: { type: 'custom', body: '{{ event_dataset.email }}' },
+        subject: { type: 'custom', body: 'Your slot at Bloom Salon' },
+        body: { type: 'custom', body: 'Your appointment is confirmed.' },
+      },
+    },
+  ],
+})
+const { data: sesRun } = await api.workflows.run(tenantSlug, datalakeSlug, sesCheck.slug!, {
+  sql_where_clause: `end_customer_id = 'EC-${runSuffix}-10'`,
+  mode: 'live',
+  manual_override: false,
+})
+await ctx.waitForFiredRun(datalakeSlug, sesRun.workflow_run_id)
+
+const readSesMessage = async (): Promise<Record<string, unknown> | undefined> => {
+  const { data } = await api.datalakes.executeSql(tenantSlug, datalakeSlug, {
+    sql:
+      'SELECT external_id, status, delivered_at FROM messages ' +
+      `WHERE sender_tool_id = '${ctx.sesToolId}' ORDER BY inserted_at DESC LIMIT 1`,
+    mode: 'unregulated',
+  })
+  if (typeof data === 'string' || data.data.length === 0) return undefined
+  const row = data.data[0]!
+  return Object.fromEntries(data.meta.columns.map((c, i) => [c, row[i]]))
+}
+let sesMessage: Record<string, unknown> | undefined
+const sentBy = Date.now() + 120_000
+while (Date.now() < sentBy) {
+  sesMessage = await readSesMessage()
+  if (sesMessage?.status === 'sent' && sesMessage.external_id) break
+  await new Promise((r) => setTimeout(r, 2_000))
+}
+if (sesMessage?.status !== 'sent' || !sesMessage.external_id) {
+  throw new Error(`the SES send must leave a sent message with SES's id, got ${JSON.stringify(sesMessage)}`)
+}
+const sesMessageId = String(sesMessage.external_id)
+
+// SES's events, in EventBridge's envelope, written where SES would put them.
+const envelope = (detailType: string, detail: Record<string, unknown>) => ({
+  version: '0',
+  id: crypto.randomUUID(),
+  'detail-type': detailType,
+  source: 'aws.ses',
+  account: '000000000000',
+  time: new Date().toISOString(),
+  region: 'us-east-1',
+  resources: [],
+  detail,
+})
+const adaEmail = `ada-${runSuffix}@example.com`
+const now = Date.now()
+const sesEvents = [
+  envelope('Email Sent', { eventType: 'Send', mail: { messageId: sesMessageId, source: sesSender, destination: [adaEmail] }, send: {} }),
+  envelope('Email Delivered', {
+    eventType: 'Delivery',
+    mail: { messageId: sesMessageId, source: sesSender, destination: [adaEmail] },
+    delivery: { timestamp: new Date(now).toISOString(), recipients: [adaEmail], smtpResponse: '250 2.0.0 OK' },
+  }),
+  envelope('Email Bounced', {
+    eventType: 'Bounce',
+    mail: { messageId: `cookbook-other-${runSuffix}`, source: sesSender, destination: ['bounce@simulator.amazonses.com'] },
+    bounce: {
+      bounceType: 'Permanent',
+      bounceSubType: 'General',
+      bouncedRecipients: [{ emailAddress: 'bounce@simulator.amazonses.com', status: '5.1.1', diagnosticCode: 'smtp; 550 5.1.1 user unknown' }],
+    },
+  }),
+]
+const stream = `cookbook-${runSuffix}`
+await logs('CreateLogStream', { logGroupName: SES_LOG_GROUP, logStreamName: stream })
+await logs('PutLogEvents', {
+  logGroupName: SES_LOG_GROUP,
+  logStreamName: stream,
+  logEvents: sesEvents.map((e, i) => ({ timestamp: now - 2_000 + i * 1_000, message: JSON.stringify(e) })),
+})
+
+// Refresh enqueues one poll; read the updater until the run is stamped.
+await api.actionStatusUpdaters.refresh(tenantSlug, datalakeSlug, ctx.sesUpdaterId)
+type UpdaterRun = { last_run_at?: string | null; last_run_status?: string | null; last_run_events_found?: number | null }
+let sesRun2: UpdaterRun = {}
+const polledBy = Date.now() + 120_000
+while (Date.now() < polledBy) {
+  const { data } = await api.actionStatusUpdaters.get(tenantSlug, datalakeSlug, ctx.sesUpdaterId)
+  sesRun2 = data as UpdaterRun
+  if (sesRun2.last_run_at && sesRun2.last_run_status) break
+  await new Promise((r) => setTimeout(r, 2_000))
+}
+if (sesRun2.last_run_status !== 'ok' || (sesRun2.last_run_events_found ?? 0) < sesEvents.length) {
+  throw new Error(`the poll must read every event and end ok, got ${JSON.stringify(sesRun2)}`)
+}
+
+// The Delivery moved the message; the Bounce, for another message, did not.
+const deliveredBy = Date.now() + 60_000
+while (Date.now() < deliveredBy) {
+  sesMessage = await readSesMessage()
+  if (sesMessage?.status === 'delivered') break
+  await new Promise((r) => setTimeout(r, 2_000))
+}
+if (sesMessage?.status !== 'delivered' || !sesMessage.delivered_at) {
+  throw new Error(`SES's Delivery must leave the message delivered, got ${JSON.stringify(sesMessage)}`)
+}
+```
+
+## 010 — the campaign workflow
 
 This is where all four rules live.
 
@@ -671,7 +1011,7 @@ if ((workflow.actions ?? []).length !== 4) {
 }
 ```
 
-## 010 — run the campaign once
+## 011 — run the campaign once
 
 One pass over all four recipients. Both gates and the split run in
 the same run — the two reachable, un-suppressed recipients send; the
@@ -742,12 +1082,12 @@ for (const wel of sent) {
 }
 ```
 
-## 011 — the per-recipient short link
+## 012 — the per-recipient short link
 
 Every message the campaign rendered carries a `/t/<hash>` link. It is
 not one campaign link shared by everyone: the platform minted a page
 token against **this recipient's own MDM subject** — the one §006
-stamped and §009 resolved — so the click is attributable to one
+stamped and §010 resolved — so the click is attributable to one
 person.
 
 `resolvePage` exchanges the hash for the page, and
@@ -796,7 +1136,7 @@ if (!tracked.message?.opened_at) {
 }
 ```
 
-## 012 — the reply comes back, and attaches
+## 013 — the reply comes back, and attaches
 
 A reply arrives as an inbound message on the same handle the campaign
 sent to. It re-ingests through a reply activation client into the
@@ -922,7 +1262,7 @@ while (Date.now() < flagDeadline) {
 if (!flagged) throw new Error('the re-ingest did not flag the reply potential_duplicate within 120s')
 ```
 
-## 013 — write the integration test
+## 014 — write the integration test
 
 End the build with a test you keep: re-read the workflow and prove the
 pipeline still executes — without a side effect. `mode: 'dry_run'` with a
@@ -978,9 +1318,15 @@ chase the error.
   variant. Had it been random, a mid-campaign re-ingest would move
   people between arms and the A/B result would be unreadable.
 - **The ambiguous reply attaches and is flagged.** It is never
-  withheld and never an error. §012's detection query is what finds
+  withheld and never an error. §013's detection query is what finds
   the ambiguity; the flag is what routes it to a human. The platform
   does not silently pick a "best" match and hide the choice.
+- **An unverified SES sender is refused, not queued.** LocalStack, like
+  SES, refuses a send from an address it has not verified; the tool and
+  its keys are fine, and verifying the address is the whole fix.
+- **The bare `email_message_status` is a 409, not a default.** Two
+  providers ship a template by that name, so name the provider's path
+  (`status_poller/aws_ses/...`) rather than hoping for Mailgun's.
 - **`provider: 'mock'` is data, not a deploy mode.** It sits on the
   tool row, so the same manifest runs anywhere; the tool — not the
   environment — decides where email goes.
@@ -994,7 +1340,7 @@ is cheap to reset (`mix ecto.reset` on the platform repo).
 
 # Outcome
 
-After this cookbook's twelve steps run green:
+After this cookbook's thirteen steps run green:
 
 - A business roster and an end-customer audience exist as generic
   tables, and the foundation datalake's **system** inbound-messages
@@ -1014,6 +1360,9 @@ After this cookbook's twelve steps run green:
 - A reply re-ingested on the sender's handle attached back to the
   customer who sent it, and the duplicate-handle path flags rather
   than blocks
+- An SES tool pointed at LocalStack sent one email from a workflow,
+  and SES's own Delivery event, read from a CloudWatch log group by
+  the SES status templates, moved that message to `delivered`
 
 The business outcome — a compliant, attributable, A/B-split campaign
 that can be replied to — is demonstrated end-to-end, not merely

package/.agent/mock-services.md

@@ -14,9 +14,12 @@ third-party APIs the platform integrates with — Athenahealth, Twilio, Mailgun,
 Stripe, SendGrid, HubSpot, QuickBooks, Airtable, Atomic FI, the LLM providers,
 and a small set of AWS endpoints LocalStack cannot serve.
 
-**LocalStack** serves AWS itself: `s3,lambda,sns,ssm,sqs,sts,logs,secretsmanager,cloudformation`
+**LocalStack** serves AWS itself: `s3,lambda,sns,ssm,sqs,sts,logs,secretsmanager,cloudformation,ses`
 (`local-dependencies.yml`). See [Datalakes](datalakes.md) for how datalake
-provisioning uses it.
+provisioning uses it. An SES email tool whose endpoint URL is `http://localhost:4566`
+sends into LocalStack once the sender's address is verified there
+(`aws ses verify-email-identity`), and LocalStack keeps each message, raw, at
+`http://localhost:4566/_aws/ses`.
 
 The division is not arbitrary. LocalStack Community **cannot** serve
 `pinpoint-sms-voice-v2` (501 — Ultimate tier only), so End User Messaging points

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/dist/index.d.mts

@@ -1896,12 +1896,12 @@ type GenericTableListResponse = {
 /**
  * MMSCallResponse
  *
- * MMS tool-call config — Liquid-templated recipient and body, plain public media URL.
+ * MMS tool-call config — Liquid-templated recipient, optional caption, and plain public media URL.
  */
 type MmsCallResponse = {
-  body: SimpleTemplateConfigResponse;
+  body?: SimpleTemplateConfigResponse;
   /**
-   * Public http(s) URL of the media to attach — fetched and re-staged into the tool's S3 media bucket
+   * Public http(s) URL of the media to attach — re-staged into the tool's S3 media bucket (End User Messaging) or fetched by Twilio directly
    */
   media_url: string;
   to: SimpleTemplateConfigResponse;
@@ -3416,7 +3416,7 @@ type EmailResponse = {
    */
   domain?: string;
   /**
-   * Custom Mailgun API base URL (e.g., https://api.eu.mailgun.net/v3 for EU domains, or a WireMock endpoint for integration tests); leave blank for real Mailgun
+   * Custom provider endpoint. Mailgun: the API base URL, which the sending domain is appended to (e.g., https://api.eu.mailgun.net/v3 for EU domains, or a WireMock endpoint for integration tests). SES: the whole request URL (e.g., https://email.us-west-2.amazonaws.com, or http://localhost:4566 for LocalStack). Leave blank for the provider's own endpoint.
    */
   endpoint_url?: string | null;
   /**
@@ -3850,13 +3850,21 @@ type ToolCloudWatchLogGroupResponse = CloudWatchLogGroupResponse & {
 /**
  * TwilioRequest
  *
- * Twilio tool configuration for sending SMS via the Programmable Messaging API. A primary holds the account credential; a variant names its primary and carries only its own sender identity. Request
+ * Twilio tool configuration for sending SMS and MMS via the Programmable Messaging API. A primary holds the account credential; a variant names its primary and carries only its own sender identity. Request
  */
 type TwilioRequest = {
   /**
    * Twilio Account SID (required on a primary; supplied by the primary on a variant)
    */
   account_sid?: string | null;
+  /**
+   * Twilio API Key SID (required when auth_method is api_key)
+   */
+  api_key_sid?: string | null;
+  /**
+   * How this primary authenticates to Twilio. Defaults to auth_token.
+   */
+  auth_method?: 'auth_token' | 'api_key';
   base_message?: ComplexTemplateConfigRequest;
   /**
    * Custom Twilio API base URL (e.g., http://localhost:8080 for WireMock); leave blank for https://api.twilio.com
@@ -4474,13 +4482,21 @@ type DataSourceResponse = {
 /**
  * TwilioResponse
  *
- * Twilio tool configuration for sending SMS via the Programmable Messaging API. A primary holds the account credential; a variant names its primary and carries only its own sender identity.
+ * Twilio tool configuration for sending SMS and MMS via the Programmable Messaging API. A primary holds the account credential; a variant names its primary and carries only its own sender identity.
  */
 type TwilioResponse = {
   /**
    * Twilio Account SID (required on a primary; supplied by the primary on a variant)
    */
   account_sid?: string | null;
+  /**
+   * Twilio API Key SID (required when auth_method is api_key)
+   */
+  api_key_sid?: string | null;
+  /**
+   * How this primary authenticates to Twilio. Defaults to auth_token.
+   */
+  auth_method?: 'auth_token' | 'api_key';
   base_message?: ComplexTemplateConfigResponse | null;
   /**
    * Custom Twilio API base URL (e.g., http://localhost:8080 for WireMock); leave blank for https://api.twilio.com
@@ -4796,12 +4812,12 @@ type InteroperabilityContractAiAgentRequestWritable = {
 /**
  * MMSCallRequest
  *
- * MMS tool-call config — Liquid-templated recipient and body, plain public media URL. Request
+ * MMS tool-call config — Liquid-templated recipient, optional caption, and plain public media URL. Request
  */
 type MmsCallRequestWritable = {
-  body: SimpleTemplateConfigRequest;
+  body?: SimpleTemplateConfigRequest;
   /**
-   * Public http(s) URL of the media to attach — fetched and re-staged into the tool's S3 media bucket
+   * Public http(s) URL of the media to attach — re-staged into the tool's S3 media bucket (End User Messaging) or fetched by Twilio directly
    */
   media_url: string;
   to: SimpleTemplateConfigRequest;
@@ -5160,7 +5176,7 @@ type EmailRequestWritable = {
    */
   domain?: string;
   /**
-   * Custom Mailgun API base URL (e.g., https://api.eu.mailgun.net/v3 for EU domains, or a WireMock endpoint for integration tests); leave blank for real Mailgun
+   * Custom provider endpoint. Mailgun: the API base URL, which the sending domain is appended to (e.g., https://api.eu.mailgun.net/v3 for EU domains, or a WireMock endpoint for integration tests). SES: the whole request URL (e.g., https://email.us-west-2.amazonaws.com, or http://localhost:4566 for LocalStack). Leave blank for the provider's own endpoint.
    */
   endpoint_url?: string | null;
   /**
@@ -5960,13 +5976,25 @@ type ActionAwsLambdaCallRequestWritable = AwsLambdaCallRequestWritable & {
 /**
  * TwilioRequest
  *
- * Twilio tool configuration for sending SMS via the Programmable Messaging API. A primary holds the account credential; a variant names its primary and carries only its own sender identity. Request
+ * Twilio tool configuration for sending SMS and MMS via the Programmable Messaging API. A primary holds the account credential; a variant names its primary and carries only its own sender identity. Request
  */
 type TwilioRequestWritable = {
   /**
    * Twilio Account SID (required on a primary; supplied by the primary on a variant)
    */
   account_sid?: string | null;
+  /**
+   * Twilio API Key Secret (required when auth_method is api_key)
+   */
+  api_key_secret?: string | null;
+  /**
+   * Twilio API Key SID (required when auth_method is api_key)
+   */
+  api_key_sid?: string | null;
+  /**
+   * How this primary authenticates to Twilio. Defaults to auth_token.
+   */
+  auth_method?: 'auth_token' | 'api_key';
   /**
    * Twilio Auth Token (required on a primary; supplied by the primary on a variant)
    */