@alvera-ai/platform-sdk 0.10.0-rc.8 → 0.11.0

package/.agent/action_status_updaters.md

@@ -0,0 +1,264 @@
+# Action status updaters
+
+An **action status updater** is a scheduled job that polls an
+external system (e.g. a cloud-provider log group, a delivery
+provider's API) for status updates on actions the platform
+previously fired, and writes those updates back onto the
+matching message rows.
+
+The typical use case: a workflow's SMS action fires through a
+provider (a sender tool), and a status updater periodically
+polls the provider's log group to mark each message as
+`delivered` / `failed` / `bounced` on its tracked record.
+
+SDK namespace: `api.actionStatusUpdaters`.
+
+Action status updaters are **Datalake-DB-resident** — the
+parent datalake must be `status: 'ready'` and every
+referenced tool must exist before you `create()`.
+
+## 1. Wire shape
+
+```typescript
+import type {
+  ActionStatusUpdaterRequestWritable,
+  ActionStatusUpdaterResponse,
+} from '@alvera-ai/platform-sdk'
+
+const { data: created } = await api.actionStatusUpdaters.create(
+  tenantSlug,
+  datalakeSlug,
+  {
+    name: 'SMS Delivery Updater',
+    cron_expression: '*/30 * * * *',                  // every 30 minutes
+    updater_type: 'cloud_watch',                      // polling source family
+    updater_tool_id: cloudWatchToolId,                // the tool that issues the poll
+    sender_tool_ids: [smsToolId],                     // tools whose sent messages this updater tracks
+    datalake_id: datalakeId,
+
+    // Polymorphic — discriminator: updater_body_type
+    updater_body: {
+      updater_body_type: 'cloud_watch_request',
+      log_group_name: 'sns/us-east-1/...',
+      start_time: '{{ now | minutes_ago: 45 }}',     // Liquid window
+      end_time:   '{{ now }}',
+    },
+
+    // Liquid template emitting JSON that maps poll events to message updates
+    message_config: {
+      type: 'custom',
+      body:
+        '{% for event in events %}' +
+        '{"external_id": "{{ event.message_id }}", "set_params": {"status": "{{ event.status }}"}}' +
+        '{% endfor %}',
+    },
+  },
+)
+```
+
+## 2. Rules the type cannot encode
+
+### `updater_body` is polymorphic on `updater_body_type`
+
+The body's discriminator selects the polling shape. Each
+variant declares the fields the platform needs to construct
+the poll request:
+
+```
+updater_body_type: 'cloud_watch_request'
+  log_group_name   string — the log group to scan
+  start_time       string — Liquid template producing a timestamp
+  end_time         string — Liquid template producing a timestamp
+```
+
+(See the SDK type for the full set of body types — others
+follow the same `<verb>_request` naming and carry the fields
+their target API requires.)
+
+`start_time` / `end_time` accept Liquid expressions using the
+`now` variable plus relative-time filters (`minutes_ago: N`,
+`hours_ago: N`, ...). A literal ISO 8601 string also works for
+fixed windows.
+
+### `message_config.body` emits a JSON event stream
+
+The template runs against an `events` array — the parsed
+response from the polling tool. Each iteration must render
+one JSON object with two required fields:
+
+```
+external_id  string — the message identifier to update (typically
+                       the provider's id, matching the recipient
+                       record's external_id column)
+set_params   object — fields to update on the matching message row
+                       (e.g. { status, delivered_at, error_code })
+```
+
+The platform parses the rendered output, joins each event to a
+message row by `external_id`, and applies `set_params` as the
+update. Events that don't match any message are silently
+discarded.
+
+### `cron_expression` is a standard 5-field cron string
+
+```
+*/30 * * * *      — every 30 minutes
+0 * * * *         — every hour on the minute
+0 9 * * 1-5       — 9am Mon-Fri
+```
+
+Sub-minute cadences are NOT supported. The minimum interval
+the scheduler honors depends on platform-level configuration;
+default minimum is 5 minutes.
+
+### `updater_type` and `updater_body.updater_body_type` must correspond
+
+The body carries TWO discriminator fields that name the same
+choice from different angles:
+
+```
+   updater_type                  outer field on the request body
+                                  (top-level)
+   updater_body.updater_body_type   inner field on the polymorphic
+                                  body embed
+```
+
+They must agree according to a fixed mapping:
+
+```
+   updater_type: "cloud_watch"   ↔   updater_body_type: "cloud_watch_request"
+   updater_type: "restapi"       ↔   updater_body_type: "restapi_request"
+```
+
+A mismatched pair (e.g. `updater_type: "cloud_watch"` +
+`updater_body_type: "restapi_request"`) returns 422 — typically
+on `/updater_type` with a "type / body type mismatch" message.
+The full mapping is exported by the SDK; the `updater_type` enum
+and the `updater_body_type` enum are kept in lockstep by the
+generated types.
+
+### `updater_tool_id` and `sender_tool_ids` serve different roles
+
+- `updater_tool_id` (single) — the tool the updater uses to
+  ISSUE the poll. Must be a tool whose `intent` is
+  `status_poller` (e.g. a `cloud_watch_log_group` body type).
+- `sender_tool_ids` (array) — the tools whose sent messages
+  this updater is responsible for tracking. The match logic
+  joins each polled event back to a message row that was
+  sent through one of these tools.
+
+A single status updater can track messages from multiple
+sender tools (e.g. an SMS tool plus a voice tool routed
+through the same provider).
+
+## 3. Field ownership
+
+**Server-derived (Response-only).** Universal set from
+`type_naming.md`.
+
+**Caller-supplied (round-trip).**
+
+```
+name                  required string
+cron_expression       required string — standard cron
+updater_type          required enum   — e.g. 'cloud_watch'
+updater_tool_id       required UUID   — the polling tool
+sender_tool_ids       required UUID[] — tools whose messages this updater tracks
+datalake_id           required UUID
+updater_body          required embed  — { updater_body_type, ... }
+message_config        required embed  — { type, body }
+```
+
+**Write-only (Request-only).** None.
+
+## 4. Error envelopes
+
+Standard JSON:API envelopes per `errors.md`. Common rejections:
+
+| `source.pointer`                    | Cause                                              |
+|-------------------------------------|----------------------------------------------------|
+| `/cron_expression`                  | invalid cron syntax or below minimum interval      |
+| `/updater_tool_id`                  | tool's intent isn't `status_poller`                |
+| `/sender_tool_ids/0`                | tool id doesn't exist or wrong datalake            |
+| `/updater_body/updater_body_type`   | enum mismatch                                      |
+| `/updater_type`                     | mismatch with `updater_body.updater_body_type`     |
+| `/message_config/body`              | empty when `type: 'custom'`                        |
+| `/base`                             | `cron_management_failed` — body validated and saved but scheduler registration failed; the row is rolled back |
+
+## 5. Lifecycle
+
+### Create
+
+Synchronous. A successful create registers a scheduled poll
+under the supplied `cron_expression`; the first run fires at
+the next cron slot at-or-after create time.
+
+The cron registration is part of the create transaction — if
+the body validates but scheduler registration fails, the
+platform rolls the row back and returns 422 with
+`cron_management_failed` on `/base` (see §4). Conversely, a
+body that fails structural validation never reaches the
+scheduler; cron-job registration only happens on the success
+branch.
+
+### Read shapes
+
+```
+.list(tenantSlug, datalakeSlug)              Paged: { data, meta }
+.get(tenantSlug, datalakeSlug, idOrSlug)     One row
+.metadata(tenantSlug, datalakeSlug)          Markdown — catalog
+.metadataDetails(tenantSlug, datalakeSlug,   Markdown — one updater
+                  idOrSlug)
+```
+
+### Update
+
+`update()` replaces the whole resource — resupply the full
+body; there's no partial update. The polymorphic `updater_body`
+must keep the same `updater_body_type` on update — the
+discriminator can't change on `update()`; to change body type,
+`delete()` and `create()` fresh.
+
+### Delete
+
+`delete()` removes the row and cancels future scheduled polls.
+In-flight polls complete; their writebacks land normally.
+
+The delete is **graceful** with respect to scheduler state: if
+the row exists but its cron-job entry is somehow missing or
+the scheduler raises during cancellation, the row is still
+deleted and the DELETE returns 204. Consumers do not need to
+check or retry for partial-delete states.
+
+## 6. Gotchas
+
+1. **The polling tool's `intent` must be `status_poller`.**
+   A tool with `intent: 'sms'` or any other non-poller intent
+   is rejected at create time. The poller intent gates the
+   tool's eligibility as an `updater_tool_id`.
+
+2. **`message_config.body` must emit valid JSON.** The
+   template is rendered against the polling tool's parsed
+   response and the output is then JSON-parsed. A render that
+   produces malformed JSON (e.g. trailing comma, unquoted
+   string) makes the entire poll cycle silently no-op for
+   that updater — events stay unprocessed.
+
+3. **`external_id` join is exact-match.** Events whose
+   `external_id` doesn't match a message row are discarded
+   silently. If your provider returns a prefixed id (e.g.
+   `provider-prefix/12345`) but your message rows carry
+   the bare id, transform inside the Liquid template (string
+   filters) so the rendered `external_id` matches.
+
+4. **`set_params` keys must be writable columns on the
+   message row.** Unknown keys are silently dropped during
+   the update. Refer to the message dataset's schema to
+   confirm which columns are writable from updater output.
+
+5. **Cron windows + polling-window overlap.** Choose
+   `start_time` / `end_time` to overlap consecutive cron
+   intervals (e.g. cron every 30 min, window of 45 min) so
+   transient delivery delays don't fall between two polls.
+   The defaults in the wire-shape example illustrate this
+   pattern: 30-minute cron, 45-minute window.