@alvera-ai/platform-sdk 0.21.1-next.ge834089 → 0.21.2

package/.agent/advanced_migrations.md

@@ -104,6 +104,14 @@ END $$;
 The same applies to `down_statement`, which is likelier to be run against a
 database that is not in the state you assumed.
 
+### One statement per body
+
+The platform runs each body as a single prepared statement. Two commands in one
+`up_statement` are accepted at create and fail at migrate with Postgres `42601`
+`cannot insert multiple commands into a prepared statement`. The two examples
+above are therefore two migrations, not one body. A `DO $$ … $$` block counts as
+one statement, so steps that must travel together go inside one.
+
 ### The table names are the platform's, not yours
 
 A generic table you declared as `contact_submissions` is physically

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

@@ -2826,46 +2826,51 @@ if (advancingPoller.status !== 'active') {
 }
 ```
 
-## 045 — an SES sender on its own endpoint, and SES's events reconciled
+## 045 — an SES sender on its own endpoint, and its delivery reconciled
 
 The campaign's email went out through the mock provider. A real deployment
-sends through SES, and two things about SES are worth proving rather than
+sends through SES, and three things about SES are worth proving rather than
 reading about.
 
 **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
-a local AWS stand-in, every call goes there instead, which is how this walk
-proves it without an AWS account. The stand-in at `localhost:4566` answers
-SES and lists every message it received at `GET /_ministack/ses/messages`,
-so a test call through the tool comes back with the id the stand-in gave it,
-and the stand-in's list holds a message with that id. Nothing else could
-have issued it. The stand-in serves SES only when `ses` is on its services
-list; without it, every SES call answers 400 `Unsupported service: ses`.
-
-**SES has no CloudWatch Logs destination of its own.** Its events travel
-configuration set → EventBridge → rule → log group, and EventBridge wraps
-each SES event in `detail`. The platform's SES templates read that envelope:
-`detail.mail.messageId` is the id SES returned to the send, the one the
-message row carries as `external_id`. The stand-in does not publish SES
-events, so the step writes three in that shape itself, under account
-`000000000000`: a send and a delivery for the message the test call just
-sent, and a bounce for another. Then it points an updater at that log
-group.
+a local AWS stand-in, every send goes there instead, which is how this walk
+sends without an AWS account. A send that reached SES comes back with SES's
+message id, and the message row keeps it as `external_id`.
+
+**A message row comes from a workflow, not from a test call.** A tool's
+`testInvocation` sends, but writes no message row, so there would be nothing
+to reconcile. The step sends one email to one recipient from a workflow
+whose only action uses the SES tool. The action fires after the run is
+recorded, so the step waits for the row. A user search keeps the rows that
+matched when it was created and never picks up a later one, so each try
+creates a new search.
 
 **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`.
 
+**Delivery comes from SES's events.** SES has no CloudWatch Logs destination
+of its own: its events travel configuration set → EventBridge → rule → log
+group, and the platform's SES template reads each one. `detail.mail.messageId`
+finds the message by its `external_id`; a Delivery moves it to `delivered`;
+a Bounce, Complaint or Reject moves it to `failed`; any other event leaves it
+where it is. The local stand-in keeps every email it was sent but publishes
+none of SES's events, so locally the poll finds nothing and the message stays
+`sent`. Against real SES, with the configuration set routed to the updater's
+log group, the same poll moves it to `delivered` at SES's own delivery time.
+The step accepts either, and nothing else.
+
 **`refresh` only enqueues a poll.** It answers 202 with the row as it was;
 read the row again until `last_run_at` moves. `last_run_status` is `ok` when
 the run read its whole window and `error` when it stopped, never anything in
-between, and `last_run_events_found` counts the events it read.
+between.
 
 ```typescript
 const SES_ENDPOINT = 'http://localhost:4566'
 const SES_LOG_GROUP = '/aws/events/cookbook-ses-delivery'
-const SES_LOG_STREAM = 'cookbook-ses-walk'
+const SES_DECISION_KEY = 'ses_delivery_check'
 
 const sesTool = await ctx.ensure(
   'SES email sender',
@@ -2902,30 +2907,6 @@ if (storedSesBody.provider !== 'ses' || storedSesBody.endpoint_url !== SES_ENDPO
   throw new Error(`the SES tool must keep its endpoint, read back ${JSON.stringify(storedSesBody)}`)
 }
 
-// A test call goes where the tool points, and the stand-in keeps what it received.
-const { data: sesSend } = await api.tools.testInvocation(tenantSlug, datalakeSlug, ctx.sesToolId, {
-  tool_call: {
-    tool_call_type: 'email_request',
-    to: { type: 'custom', body: 'test-recipient@example.com' },
-    subject: { type: 'custom', body: 'SES endpoint check' },
-    body: { type: 'custom', body: 'test' },
-    link_prefix: ctx.campaignLinkPrefix,
-  },
-})
-if (sesSend.status === 'error') {
-  throw new Error(`the SES test call failed: ${sesSend.error_message}`)
-}
-const received = (await (await fetch(`${SES_ENDPOINT}/_ministack/ses/messages`)).json()) as {
-  messages: Record<string, { MessageId: string; Subject: string }[]>
-}
-const sentHere = Object.values(received.messages)
-  .flat()
-  .find((m) => m.Subject === 'SES endpoint check' && JSON.stringify(sesSend.result).includes(m.MessageId))
-if (!sentHere) {
-  throw new Error(`the stand-in holds no message with the id the test call returned: ${JSON.stringify(sesSend.result)}`)
-}
-const sentMessageId = sentHere.MessageId
-
 // The bare name is ambiguous between Mailgun and SES.
 let bareName: unknown
 try {
@@ -2940,74 +2921,91 @@ if (!JSON.stringify(bareName).includes('status_poller/aws_ses/email_message_stat
   throw new Error(`the 409 must name the SES path among its candidates: ${JSON.stringify(bareName)}`)
 }
 
-// Three SES events as EventBridge delivers them to a log group. The stand-in reads the
-// Authorization header for region and key but does not check the signature.
-async function logs(target: string, payload: Record<string, unknown>): Promise<void> {
-  const resp = await fetch(SES_ENDPOINT, {
-    method: 'POST',
-    headers: {
-      'Content-Type': 'application/x-amz-json-1.1',
-      'X-Amz-Target': `Logs_20140328.${target}`,
-      Authorization:
-        'AWS4-HMAC-SHA256 Credential=localkey/20260101/us-east-1/logs/aws4_request, ' +
-        'SignedHeaders=content-type;host;x-amz-target, Signature=local',
-    },
-    body: JSON.stringify(payload),
-  })
-  if (resp.ok) return
-  const text = await resp.text()
-  if (text.includes('ResourceAlreadyExistsException')) return
-  throw new Error(`log group call ${target} failed (${resp.status}): ${text}`)
-}
-
-const sentAt = Date.now() - 3_000
-const sesEnvelope = (detailType: string, detail: Record<string, unknown>) => ({
-  version: '0',
-  id: crypto.randomUUID(),
-  'detail-type': detailType,
-  source: 'aws.ses',
-  account: '000000000000',
-  time: new Date(sentAt).toISOString(),
-  region: 'us-east-1',
-  resources: ['arn:aws:ses:us-east-1:000000000000:configuration-set/cookbook-ses'],
-  detail,
-})
-const sesMail = (messageId: string) => ({
-  timestamp: new Date(sentAt).toISOString(),
-  source: 'campaigns@bloom-salon.example.com',
-  messageId,
-  destination: ['test-recipient@example.com'],
-})
-const sesEvents = [
-  sesEnvelope('Email Sent', { eventType: 'Send', mail: sesMail(sentMessageId), send: {} }),
-  sesEnvelope('Email Delivered', {
-    eventType: 'Delivery',
-    mail: sesMail(sentMessageId),
-    delivery: {
-      timestamp: new Date(sentAt + 1_000).toISOString(),
-      recipients: ['test-recipient@example.com'],
-      smtpResponse: '250 2.0.0 OK',
-    },
-  }),
-  sesEnvelope('Email Bounced', {
-    eventType: 'Bounce',
-    mail: sesMail('test-ses-bounced-000000'),
-    bounce: {
-      bounceType: 'Permanent',
-      bounceSubType: 'General',
-      bouncedRecipients: [
-        { emailAddress: 'test-bounce@example.com', status: '5.1.1', diagnosticCode: 'smtp; 550 5.1.1 user unknown' },
+// One email, to one recipient, through the SES tool.
+const sesCheck = await ctx.ensure(
+  'SES delivery check workflow',
+  async () => {
+    const { data } = await api.workflows.list(tenantSlug, datalakeSlug)
+    return (data.data ?? []).find((w: { name?: string }) => w.name === 'Cookbook SES Delivery Check')
+  },
+  async () => {
+    const { data } = await api.workflows.create(tenantSlug, datalakeSlug, {
+      name: 'Cookbook SES Delivery Check',
+      description: 'One email through the SES tool, so its delivery can be reconciled.',
+      dataset_type: 'generic_table',
+      generic_table_id: ctx.audienceTableId,
+      status: 'live',
+      tags: ['marketing', 'ses'],
+      skip_mdm_resolution: false,
+      filter_config: { type: 'custom', body: '{% if event_dataset.email and event_dataset.email != "" %}true{% endif %}' },
+      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:
+                `<p>Hi {{ event_dataset.name }}, we have kept your slot.</p>` +
+                `<p><a href="${ctx.bookingPageUrl}">See your booking</a></p>`,
+            },
+            link_prefix: ctx.campaignLinkPrefix,
+          },
+        },
       ],
-    },
-  }),
-]
-await logs('CreateLogGroup', { logGroupName: SES_LOG_GROUP })
-await logs('CreateLogStream', { logGroupName: SES_LOG_GROUP, logStreamName: SES_LOG_STREAM })
-await logs('PutLogEvents', {
-  logGroupName: SES_LOG_GROUP,
-  logStreamName: SES_LOG_STREAM,
-  logEvents: sesEvents.map((event, i) => ({ timestamp: sentAt + i * 1_000, message: JSON.stringify(event) })),
+    })
+    return data
+  },
+)
+ctx.sesCheckWorkflowSlug = sesCheck.slug!
+
+const { data: sesRun } = await api.workflows.run(tenantSlug, datalakeSlug, ctx.sesCheckWorkflowSlug, {
+  sql_where_clause: `end_customer_id = '${ctx.adaId}'`,
+  mode: 'live',
+  manual_override: false,
 })
+await ctx.waitForFiredRun(datalakeSlug, sesRun.workflow_run_id)
+
+// The message row, found by its idempotency key, which names the same send on every rerun.
+// A search keeps the rows that matched when it was created, so each try creates a new one.
+const sesSentDeadline = Date.now() + 45_000
+let sesMessage: { status?: string; external_id?: string | null; sender_tool_id?: string } | undefined
+while (Date.now() < sesSentDeadline) {
+  const { data: sesSearch } = await api.datasets.createUserSearch(tenantSlug, datalakeSlug, 'message', {
+    search_query: `m.idempotency_key = '${ctx.adaId}/ses-delivery-check'`,
+  })
+  if (sesSearch.status !== 'completed') {
+    throw new Error(`message user-search status=${sesSearch.status} error=${sesSearch.error_message ?? '(none)'}`)
+  }
+  const { data } = await api.datasets.search(tenantSlug, datalakeSlug, 'message', {
+    userSearchId: sesSearch.id!,
+    dataAccessMode: 'raw',
+  })
+  sesMessage = (data.data ?? [])[0] as typeof sesMessage
+  if (sesMessage?.external_id) break
+  await new Promise((r) => setTimeout(r, 1_000))
+}
+if (!sesMessage?.external_id) {
+  throw new Error(`the SES send must leave a message carrying SES's id, got ${JSON.stringify(sesMessage)}`)
+}
+if (sesMessage.sender_tool_id !== ctx.sesToolId) {
+  throw new Error(`the message must name the SES tool as its sender, got ${sesMessage.sender_tool_id}`)
+}
+if (!['sent', 'delivered'].includes(sesMessage.status ?? '')) {
+  throw new Error(`the SES send must leave the message sent, got ${sesMessage.status}`)
+}
 
 const sesUpdater = await ctx.ensure(
   'SES delivery reconciler',
@@ -3051,8 +3049,22 @@ if (polled.last_run_at === beforePoll.last_run_at) {
 if (polled.last_run_status !== 'ok') {
   throw new Error(`the SES poll must read its whole window, got ${polled.last_run_status}: ${polled.last_run_error}`)
 }
-if ((polled.last_run_events_found ?? 0) < sesEvents.length) {
-  throw new Error(`the SES poll must find the ${sesEvents.length} events, found ${polled.last_run_events_found}`)
+
+// The message as the poll left it: delivered where SES published a Delivery, still sent where nothing did.
+const sesExternalId = sesMessage.external_id
+const { data: sesPage } = await api.datalakes.executeSql(tenantSlug, datalakeSlug, {
+  sql: `SELECT status, external_id FROM messages WHERE sender_tool_id = '${ctx.sesToolId}' AND channel = 'email'`,
+  mode: 'raw',
+})
+if (typeof sesPage === 'string') {
+  throw new Error('executeSql answered CSV where it should answer rows')
+}
+const sesAfter = (sesPage.data as unknown[][]).find((row) => row[1] === sesExternalId)
+if (!sesAfter) {
+  throw new Error(`no message with SES's id ${sesExternalId} after the poll: ${JSON.stringify(sesPage.data)}`)
+}
+if (!['sent', 'delivered'].includes(String(sesAfter[0]))) {
+  throw new Error(`after the poll the message must be sent or delivered, got ${sesAfter[0]}`)
 }
 ```
 
@@ -3360,8 +3372,9 @@ datalake**:
   provider delivery events into updates on a schedule, its stored body is
   read back against its checksum, and a poller whose request could never move
   to the next page is refused at create (§042–§044). An SES sender sends to
-  its own endpoint, and an updater reads SES's delivery events through the
-  platform's SES template (§045).
+  its own endpoint, a workflow's email through it leaves a message carrying
+  SES's id, and an updater reconciles that message through the platform's SES
+  template (§045).
 - **The lake answers in plain language.** Text-to-SQL proposes a query
   without running it; the read-only executor runs one and returns the same
   page as CSV (§046–§047).

package/.agent/generic_tables.md

@@ -335,7 +335,11 @@ definition must name a unique combination, and a table is sometimes
 unique only together with its id — say `(organization_id, id)`.
 Declaring `id` with `is_unique: true` puts it in that combination and
 adds no column (every table already has one). Declared any other way,
-`id` is a reserved name like the rest.
+`id` is a reserved name like the rest. And it may join the combination,
+never be the whole of it: create accepts a table whose only unique
+column is `id`, but the column sync drops reserved names before it
+reads the unique columns, finds none, and fails every migrate of the
+lake, which stays at `new`. Mark a column of the table's own unique.
 
 **`legal_entity_id` is the one that catches people.** It is not a
 column you declare and fill — a contract's `mdm_input_config`

package/.agent/mock-services.md

@@ -14,9 +14,11 @@ 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 MiniStack cannot serve.
 
-**MiniStack** serves AWS itself: `s3,lambda,sns,ssm,sqs,sts,logs,secretsmanager,cloudformation`
+**MiniStack** serves AWS itself: `s3,lambda,sns,ssm,sqs,sts,logs,secretsmanager,cloudformation,rds,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 MiniStack, which lists every message it received at
+`http://localhost:4566/_ministack/ses/messages`.
 
 The division is not arbitrary. No AWS emulator here serves
 `pinpoint-sms-voice-v2` — LocalStack Community answered 501 (Ultimate tier

package/dist/index.d.mts

@@ -1804,10 +1804,10 @@ type GenericTableListResponse = {
 /**
  * MMSCallResponse
  *
- * MMS tool-call config — Liquid-templated recipient and body, plain public media URL, and the prefix its links go out on.
+ * MMS tool-call config — Liquid-templated recipient, optional caption, plain public media URL, and the prefix its links go out on.
  */
 type MmsCallResponse = {
-  body: SimpleTemplateConfigResponse;
+  body?: SimpleTemplateConfigResponse;
   /**
    * Address of the host that serves this action's links. Every URL in the body goes out as <link_prefix>/<token>. An absolute http or https URL, path allowed, with no query, fragment or trailing slash.
    */
@@ -4777,10 +4777,10 @@ type InteroperabilityContractAiAgentRequestWritable = {
 /**
  * MMSCallRequest
  *
- * MMS tool-call config — Liquid-templated recipient and body, plain public media URL, and the prefix its links go out on. Request
+ * MMS tool-call config — Liquid-templated recipient, optional caption, plain public media URL, and the prefix its links go out on. Request
  */
 type MmsCallRequestWritable = {
-  body: SimpleTemplateConfigRequest;
+  body?: SimpleTemplateConfigRequest;
   /**
    * Address of the host that serves this action's links. Every URL in the body goes out as <link_prefix>/<token>. An absolute http or https URL, path allowed, with no query, fragment or trailing slash.
    */