@alvera-ai/platform-sdk 0.12.1 → 0.13.0-next.g14c04ff

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (57) hide show
  1. package/.agent/AGENTS.md +121 -19
  2. package/.agent/account_management.md +110 -38
  3. package/.agent/action_logs.md +144 -0
  4. package/.agent/action_status_updaters.md +302 -53
  5. package/.agent/ai_agents.md +149 -53
  6. package/.agent/ai_sandbox.md +11 -4
  7. package/.agent/async.md +16 -6
  8. package/.agent/connected_apps.md +123 -6
  9. package/.agent/cookbook/_fixtures/README.md +9 -9
  10. package/.agent/cookbook/_fixtures/{payment_risk/_compliance_screenings_payment_risk_compliance_screening.liquid → payments/_compliance_screenings_payments_compliance_screening.liquid} +1 -1
  11. package/.agent/cookbook/_fixtures/{payment_risk/_compliance_screenings_payment_risk_mdm.liquid → payments/_compliance_screenings_payments_mdm.liquid} +1 -1
  12. package/.agent/cookbook/_fixtures/{payment_risk/_payment_accounts_payment_risk_mdm.liquid → payments/_payment_accounts_payments_mdm.liquid} +1 -1
  13. package/.agent/cookbook/_fixtures/{payment_risk/_payment_accounts_payment_risk_payment_account.liquid → payments/_payment_accounts_payments_payment_account.liquid} +1 -1
  14. package/.agent/cookbook/_fixtures/{accounts_receivable/_customers_accounts_receivable_customer.liquid → subscription/_customers_subscription_customer.liquid} +1 -1
  15. package/.agent/cookbook/_fixtures/{accounts_receivable/_customers_accounts_receivable_mdm.liquid → subscription/_customers_subscription_mdm.liquid} +1 -1
  16. package/.agent/cookbook/_setup/foundation.md +24 -4
  17. package/.agent/cookbook/_setup/healthcare.md +24 -4
  18. package/.agent/cookbook/_setup/{payment_risk.md → payments.md} +51 -31
  19. package/.agent/cookbook/_setup/{accounts_receivable.md → subscription.md} +51 -31
  20. package/.agent/cookbook/action-status-updaters.md +41 -18
  21. package/.agent/cookbook/bulk-ingest.md +15 -15
  22. package/.agent/cookbook/dunning-sms-for-delinquent.md +21 -21
  23. package/.agent/cookbook/fork-and-apply-cold.md +192 -0
  24. package/.agent/cookbook/{custom-tables.md → generic-tables.md} +44 -41
  25. package/.agent/cookbook/invite-team.md +19 -13
  26. package/.agent/cookbook/kyc-notification-on-account-activation.md +26 -26
  27. package/.agent/cookbook/marketing-campaign-send.md +1003 -0
  28. package/.agent/cookbook/paginated-restapi-poller.md +284 -0
  29. package/.agent/cookbook/rest-fetch.md +9 -9
  30. package/.agent/cookbook/sanctions-screening-with-agent-review.md +22 -22
  31. package/.agent/cookbook/system-templates.md +15 -15
  32. package/.agent/cookbook/triage-prospects-by-priority.md +17 -17
  33. package/.agent/cookbook/welcome-sms-for-customers.md +21 -21
  34. package/.agent/data_activation_clients.md +177 -42
  35. package/.agent/data_sources.md +55 -37
  36. package/.agent/datalakes.md +54 -17
  37. package/.agent/debugging.md +48 -14
  38. package/.agent/errors.md +39 -17
  39. package/.agent/generic_tables.md +150 -51
  40. package/.agent/interoperability_contracts.md +114 -15
  41. package/.agent/mdm.md +171 -93
  42. package/.agent/messages.md +252 -0
  43. package/.agent/templates.md +21 -4
  44. package/.agent/tool-call-configs.md +12 -1
  45. package/.agent/tools.md +181 -63
  46. package/.agent/type_naming.md +83 -18
  47. package/.agent/workflows.md +408 -62
  48. package/LICENSE +21 -93
  49. package/README.md +2 -2
  50. package/dist/bin/platform-sdk.mjs +53 -1
  51. package/dist/bin/platform-sdk.mjs.map +1 -1
  52. package/dist/index.d.mts +737 -70
  53. package/dist/index.d.mts.map +1 -1
  54. package/dist/index.mjs +656 -105
  55. package/dist/index.mjs.map +1 -1
  56. package/package.json +10 -6
  57. /package/.agent/cookbook/_fixtures/{accounts_receivable → subscription}/stripe_customers_batch1.csv +0 -0
@@ -44,13 +44,20 @@ const { data: created } = await api.actionStatusUpdaters.create(
44
44
  end_time: '{{ now }}',
45
45
  },
46
46
 
47
- // Liquid template emitting JSON that maps poll events to message updates
47
+ // Liquid, rendered ONCE PER EVENT — the event IS the assigns, so there is no
48
+ // `events` list to loop. Emits a FLAT object: the message to update, plus the
49
+ // fields to set at the top level.
48
50
  message_config: {
49
51
  type: 'custom',
50
- body:
51
- '{% for event in events %}' +
52
- '{"external_id": "{{ event.message_id }}", "set_params": {"status": "{{ event.status }}"}}' +
53
- '{% endfor %}',
52
+ body: '{"external_id": "{{ notification.messageId }}", "status": "delivered"}',
53
+ },
54
+
55
+ // REQUIRED on every updater, both types, on create AND update. Same
56
+ // per-event rendering contract as `message_config`, but targets the
57
+ // action_log row instead of the message row.
58
+ action_log_config: {
59
+ type: 'custom',
60
+ body: '{"external_id": "{{ notification.messageId }}", "status": "delivered"}',
54
61
  },
55
62
  },
56
63
  )
@@ -75,29 +82,108 @@ updater_body_type: 'cloud_watch_request'
75
82
  follow the same `<verb>_request` naming and carry the fields
76
83
  their target API requires.)
77
84
 
78
- `start_time` / `end_time` accept Liquid expressions using the
79
- `now` variable plus relative-time filters (`minutes_ago: N`,
80
- `hours_ago: N`, ...). A literal ISO 8601 string also works for
81
- fixed windows.
85
+ `updater_body_type: 'restapi_request'` additionally **requires an
86
+ `events_template` field**. Without it the REST poll fails with
87
+ `missing_events_template`. `events_template` is specific to the REST
88
+ poll's event-list extraction — it is not read by data-activation
89
+ fetches.
82
90
 
83
- ### `message_config.body` emits a JSON event stream
91
+ `start_time` / `end_time` are Liquid, and they **must render to
92
+ unix milliseconds** — that is what the poll request takes. On
93
+ these two fields `now` is a **variable already holding unix ms**,
94
+ so pipe it through the relative-time filters:
95
+
96
+ ```
97
+ start_time: '{{ now | minutes_ago: 45 }}' // 45 minutes back
98
+ end_time: '{{ now }}' // right now
99
+ ```
84
100
 
85
- The template runs against an `events` array — the parsed
86
- response from the polling tool. Each iteration must render
87
- one JSON object with two required fields:
101
+ Also available: `hours_ago: N`.
88
102
 
103
+ **Do not use the ISO-8601 `now` filter here.** `{{ "" | now }}` is
104
+ a different thing — it renders a datetime *string*, which is not a
105
+ valid window, and the platform rejects it at create. An ISO 8601
106
+ literal is not valid on these fields either.
107
+
108
+ ### `message_config.body` renders ONCE PER EVENT
109
+
110
+ The template is rendered **once for each fetched event, with that
111
+ event as the entire assigns**. There is no `events` collection in
112
+ scope — do not loop.
113
+
114
+ ```liquid
115
+ {"external_id": "{{ notification.messageId }}", "status": "delivered"}
89
116
  ```
90
- external_id string — the message identifier to update (typically
91
- the provider's id, matching the recipient
92
- record's external_id column)
93
- set_params object — fields to update on the matching message row
94
- (e.g. { status, delivered_at, error_code })
117
+
118
+ It must render a **flat** JSON object:
119
+
95
120
  ```
121
+ external_id string — the message to update (matches the message row's
122
+ external_id, i.e. the provider's id)
123
+ <field> any — each remaining TOP-LEVEL key is a field to set:
124
+ status, sent_at, delivered_at, read_at, opened_at
125
+ ```
126
+
127
+ There is **no `set_params` wrapper**. Every key that is not
128
+ `external_id` *is* the update. Nesting the fields under
129
+ `set_params` renders an object the platform's field allowlist
130
+ drops, so the update silently applies to nothing.
131
+
132
+ The platform joins each rendered `external_id` to a message row
133
+ and applies the remaining fields. Events that don't match any
134
+ message are silently discarded — a provider poll routinely sees
135
+ events for messages this updater doesn't own.
136
+
137
+ Custom Liquid filters (`json_escape`, `e164`, `to_json`, ...) are
138
+ available here, as everywhere.
139
+
140
+ ### MMS delivery tracking uses a system `message_config` template
96
141
 
97
- The platform parses the rendered output, joins each event to a
98
- message row by `external_id`, and applies `set_params` as the
99
- update. Events that don't match any message are silently
100
- discarded.
142
+ MMS delivery tracking is wired as a `cloud_watch` updater whose
143
+ `message_config` points at a system-defined template rather than a
144
+ hand-authored `custom` body — the system template lives at
145
+ `status_poller/end_user_messaging/mms_delivery_status`. Everything
146
+ else about the updater is ordinary: it still needs an
147
+ `action_log_config` like every other updater (see below) — the
148
+ system template covers `message_config` only.
149
+
150
+ ### `action_log_config` is required — same rendering contract as `message_config`
151
+
152
+ `action_log_config` is a **required** field on every action status
153
+ updater — `cloud_watch` and `restapi` alike — on **both `create()` and
154
+ `update()`**. There is no updater for which it is optional and no way
155
+ to omit it on a PUT.
156
+
157
+ It follows the same per-event rendering contract as `message_config`
158
+ (§2 above), but targets the **action_log** row instead of the message
159
+ row: it must render a JSON object containing `external_id` plus at
160
+ least one updatable action-log field — one of `status`, `sent_at`, or
161
+ `metadata`. A minimal valid value:
162
+
163
+ ```liquid
164
+ {"external_id": "{{ notification.messageId }}", "status": "delivered"}
165
+ ```
166
+
167
+ Two distinct rejections come off this field, and they read differently:
168
+
169
+ - **Missing entirely** — omitting `action_log_config` on create or
170
+ update is a 422 with `Missing field: action_log_config` at
171
+ `source.pointer: /action_log_config`.
172
+ - **Present but renders nothing** — a value that passes shallow
173
+ validation but renders `null` or an empty result at run time (e.g.
174
+ a `{"type": "null"}` config) is refused with a 422 whose detail
175
+ begins `must render a JSON object containing external_id`.
176
+
177
+ **Response nullability is lazy, not retroactive.** Updaters created
178
+ before this became required still read back `action_log_config: null`
179
+ — the platform does not backfill a template onto old rows. That
180
+ `null` persists until the row's **next edit** forces a real template
181
+ through, and "next edit" is broader than a plain field change: it
182
+ also includes resuming a halted updater by setting `status` back to
183
+ `'active'` (§7) and issuing a `refresh()` call with a one-shot
184
+ `updater_body` override (§7) — both now require `action_log_config`
185
+ to be present too, which is what completes the migration for an old
186
+ row.
101
187
 
102
188
  ### `cron_expression` is a standard 5-field cron string
103
189
 
@@ -111,7 +197,7 @@ Sub-minute cadences are NOT supported. The minimum interval
111
197
  the scheduler honors depends on platform-level configuration;
112
198
  default minimum is 5 minutes.
113
199
 
114
- ### `updater_type` and `updater_body.updater_body_type` must correspond
200
+ ### `updater_type` and `updater_body.updater_body_type` — set them to agree, but only one is load-bearing
115
201
 
116
202
  The body carries TWO discriminator fields that name the same
117
203
  choice from different angles:
@@ -123,25 +209,35 @@ choice from different angles:
123
209
  body embed
124
210
  ```
125
211
 
126
- They must agree according to a fixed mapping:
212
+ The intended pairing is a fixed mapping:
127
213
 
128
214
  ```
129
215
  updater_type: "cloud_watch" ↔ updater_body_type: "cloud_watch_request"
130
216
  updater_type: "restapi" ↔ updater_body_type: "restapi_request"
131
217
  ```
132
218
 
133
- A mismatched pair (e.g. `updater_type: "cloud_watch"` +
134
- `updater_body_type: "restapi_request"`) returns 422 — typically
135
- on `/updater_type` with a "type / body type mismatch" message.
136
- The full mapping is exported by the SDK; the `updater_type` enum
137
- and the `updater_body_type` enum are kept in lockstep by the
138
- generated types.
219
+ **But the platform does NOT cross-validate the pair — a mismatch is
220
+ NOT rejected.** The two fields are cast independently; there is no
221
+ create-time check that `updater_type` matches
222
+ `updater_body_type`, so a mismatched-but-well-formed pair (e.g.
223
+ `updater_type: "cloud_watch"` + a `restapi_request` body) **persists
224
+ silently**. At runtime the platform dispatches on the polymorphic
225
+ **body** struct, so `updater_body_type` is the one that matters and
226
+ `updater_type` is effectively informational. Set them to agree
227
+ anyway — a future release may start enforcing it, and a lying
228
+ `updater_type` is a debugging trap — but don't expect a 422 to catch
229
+ a mismatch for you today.
139
230
 
140
231
  ### `updater_tool_id` and `sender_tool_ids` serve different roles
141
232
 
142
233
  - `updater_tool_id` (single) — the tool the updater uses to
143
- ISSUE the poll. Must be a tool whose `intent` is
144
- `status_poller` (e.g. a `cloud_watch_log_group` body type).
234
+ ISSUE the poll. By convention this is a tool whose `intent` is
235
+ `status_poller` (e.g. a `cloud_watch_log_group` body type) — but
236
+ the platform does **not** verify the intent at create time (it
237
+ checks only that the tool exists and belongs to the tenant). A
238
+ wrong-intent tool is accepted and only fails later, when the poll
239
+ actually runs. Wire a `status_poller` tool anyway; just don't rely
240
+ on a create-time 422 to enforce it.
145
241
  - `sender_tool_ids` (array) — the tools whose sent messages
146
242
  this updater is responsible for tracking. The match logic
147
243
  joins each polled event back to a message row that was
@@ -167,6 +263,7 @@ sender_tool_ids required UUID[] — tools whose messages this updater trac
167
263
  datalake_id required UUID
168
264
  updater_body required embed — { updater_body_type, ... }
169
265
  message_config required embed — { type, body }
266
+ action_log_config required embed — { type, body } (required on create AND update)
170
267
  ```
171
268
 
172
269
  **Write-only (Request-only).** None.
@@ -178,11 +275,12 @@ Standard JSON:API envelopes per `errors.md`. Common rejections:
178
275
  | `source.pointer` | Cause |
179
276
  |-------------------------------------|----------------------------------------------------|
180
277
  | `/cron_expression` | invalid cron syntax or below minimum interval |
181
- | `/updater_tool_id` | tool's intent isn't `status_poller` |
278
+ | `/updater_tool_id` | tool id doesn't exist or wrong datalake (intent is NOT checked — see §2) |
182
279
  | `/sender_tool_ids/0` | tool id doesn't exist or wrong datalake |
183
- | `/updater_body/updater_body_type` | enum mismatch |
184
- | `/updater_type` | mismatch with `updater_body.updater_body_type` |
280
+ | `/updater_body/updater_body_type` | value not in the polymorphic embed's type enum |
185
281
  | `/message_config/body` | empty when `type: 'custom'` |
282
+ | `/action_log_config` | missing entirely — `Missing field: action_log_config` (create AND update) |
283
+ | (detail, not pointer) | `action_log_config` present but renders `null`/empty — detail begins `must render a JSON object containing external_id` |
186
284
  | `/base` | `cron_management_failed` — body validated and saved but scheduler registration failed; the row is rolled back |
187
285
 
188
286
  ## 5. Lifecycle
@@ -204,11 +302,12 @@ branch.
204
302
  ### Read shapes
205
303
 
206
304
  ```
207
- .list(tenantSlug, datalakeSlug) Paged: { data, meta }
208
- .get(tenantSlug, datalakeSlug, idOrSlug) One row
305
+ .list(tenantSlug, datalakeSlug, query?) Paged: { data, meta }
306
+ (full Flop query — type_naming.md)
307
+ .get(tenantSlug, datalakeSlug, id) One row — UUID only
209
308
  .metadata(tenantSlug, datalakeSlug) Markdown — catalog
210
309
  .metadataDetails(tenantSlug, datalakeSlug, Markdown — one updater
211
- idOrSlug)
310
+ id) (UUID only)
212
311
  ```
213
312
 
214
313
  ### Update
@@ -232,17 +331,23 @@ check or retry for partial-delete states.
232
331
 
233
332
  ## 6. Gotchas
234
333
 
235
- 1. **The polling tool's `intent` must be `status_poller`.**
236
- A tool with `intent: 'sms'` or any other non-poller intent
237
- is rejected at create time. The poller intent gates the
238
- tool's eligibility as an `updater_tool_id`.
239
-
240
- 2. **`message_config.body` must emit valid JSON.** The
241
- template is rendered against the polling tool's parsed
242
- response and the output is then JSON-parsed. A render that
243
- produces malformed JSON (e.g. trailing comma, unquoted
244
- string) makes the entire poll cycle silently no-op for
245
- that updater — events stay unprocessed.
334
+ 1. **The polling tool should be `status_poller` — but nothing
335
+ enforces it at create.** By convention `updater_tool_id` points
336
+ at a `status_poller`-intent tool, and the runtime poll assumes
337
+ that shape. The create endpoint, however, does not check the
338
+ tool's intent (only existence + tenant), so an `intent: 'sms'`
339
+ tool is accepted and fails only when the poll runs. Wire the
340
+ right tool; don't count on a create-time rejection to catch a
341
+ wrong one.
342
+
343
+ 2. **`message_config.body` must render one flat JSON object per
344
+ event.** The two authoring mistakes that cannot work:
345
+ looping a `{% for event in events %}` collection (there is
346
+ none — the event *is* the assigns, so the loop renders
347
+ nothing), and nesting the fields under a `set_params` key
348
+ (the platform's allowlist drops them, so the update applies
349
+ to nothing). Both are now **rejected at create**. A render
350
+ that fails at run time is reported in `last_run_error`.
246
351
 
247
352
  3. **`external_id` join is exact-match.** Events whose
248
353
  `external_id` doesn't match a message row are discarded
@@ -251,10 +356,11 @@ check or retry for partial-delete states.
251
356
  the bare id, transform inside the Liquid template (string
252
357
  filters) so the rendered `external_id` matches.
253
358
 
254
- 4. **`set_params` keys must be writable columns on the
255
- message row.** Unknown keys are silently dropped during
256
- the update. Refer to the message dataset's schema to
257
- confirm which columns are writable from updater output.
359
+ 4. **The fields you set must be writable columns on the
360
+ message row** — `status`, `sent_at`, `delivered_at`,
361
+ `read_at`, `opened_at`. Unknown keys are silently dropped
362
+ during the update. They go at the TOP LEVEL of the rendered
363
+ object, alongside `external_id`.
258
364
 
259
365
  5. **Cron windows + polling-window overlap.** Choose
260
366
  `start_time` / `end_time` to overlap consecutive cron
@@ -262,3 +368,146 @@ check or retry for partial-delete states.
262
368
  transient delivery delays don't fall between two polls.
263
369
  The defaults in the wire-shape example illustrate this
264
370
  pattern: 30-minute cron, 45-minute window.
371
+
372
+ 6. **Key `has_next` off the page being NON-EMPTY, not off the
373
+ cursor's presence.** Real providers (Mailgun is one) return a
374
+ `paging.next` URL on EVERY page — including the final, empty
375
+ one — so a pagination template that emits `"has_next": true`
376
+ whenever the cursor exists loops until the runaway cap. The
377
+ canonical template keys off content instead:
378
+
379
+ ```liquid
380
+ "has_next": {% if items.size > 0 %}true{% else %}false{% endif %}
381
+ ```
382
+
383
+ The poll follows pages while `has_next` is true and stops on
384
+ the first empty page.
385
+
386
+ ## 7. Manual trigger via `refresh` — 202, and what `last_run_*` means
387
+
388
+ An action status updater CAN be fired on demand:
389
+
390
+ ```ts
391
+ const { data } = await api.actionStatusUpdaters.refresh(
392
+ tenantSlug, datalakeSlug, updaterId,
393
+ );
394
+ ```
395
+
396
+ **`refresh` answers `202` with the updater row AS-IS — the poll is
397
+ ENQUEUED, not run.** The `last_run_*` fields on that response are the
398
+ PREVIOUS run's stamps; reading them as the outcome of the refresh you
399
+ just issued is the single most common mistake here. An optional body
400
+ carries a one-shot `updater_body` override (e.g. a widened
401
+ `start_time`/`end_time` window for a backfill) that does not mutate
402
+ the persisted updater. Apply jobs are asynchronous too — observe
403
+ delivery status on the message rows, not in this response.
404
+ (CLI: `alvera refresh-action-status-updater --id <uuid>`, alias
405
+ `refresh-updater`.)
406
+
407
+ The correct read is baseline-then-advance:
408
+
409
+ ```ts
410
+ const before = await api.actionStatusUpdaters.get(tenantSlug, datalakeSlug, updaterId)
411
+ const baseline = before.data.last_run_at ?? null // BEFORE refreshing
412
+
413
+ await api.actionStatusUpdaters.refresh(tenantSlug, datalakeSlug, updaterId)
414
+
415
+ let row = before.data
416
+ const deadline = Date.now() + 60_000
417
+ while (Date.now() < deadline) {
418
+ await new Promise((r) => setTimeout(r, 2_000))
419
+ const { data } = await api.actionStatusUpdaters.get(tenantSlug, datalakeSlug, updaterId)
420
+ if (data.last_run_at && data.last_run_at !== baseline) { row = data; break }
421
+ }
422
+ // row.last_run_status / last_run_error now describe THIS run
423
+ ```
424
+
425
+ What the ASU still does NOT have is a **per-run log** (nothing like
426
+ a data activation client's `logs` or a workflow's `batchLogs`). The
427
+ run-outcome surface is four fields on the row itself, plus the halt
428
+ flag:
429
+
430
+ ```
431
+ last_run_at when the poll worker last stamped a page
432
+ last_run_status 'ok' | 'error'
433
+ last_run_error why the last run failed (structured text)
434
+ last_run_events_found events fetched so far in the current run
435
+ status 'active' | 'cycle_detected'
436
+ ```
437
+
438
+ **A paginated run stamps `last_run_*` on EVERY page, not only the
439
+ final one.** Two consequences for anything asserting on them:
440
+
441
+ - `last_run_status: 'ok'` means *a page* succeeded — not that the run
442
+ completed. Do not treat it as terminal.
443
+ - `last_run_events_found` is a **running total** for the current run,
444
+ so a mid-run read is legitimately smaller than the final count.
445
+
446
+ Per-page stamping exists because the alternative hid a real incident:
447
+ an updater that polled continuously for 45 minutes was
448
+ indistinguishable from one that had never started, because only the
449
+ terminal page stamped and no page was ever terminal.
450
+
451
+ **`status` is the halt flag.** The server sets `'cycle_detected'` when
452
+ a run re-reads events it has already handled — the runtime backstop for
453
+ a poll whose pagination does not advance (a provider cursor that never
454
+ drains, or a one-shot `updater_body` override). Every later job then
455
+ fails without calling the provider, and `last_run_error` carries the
456
+ diagnostic. **Nothing clears it but setting `status` back to
457
+ `'active'`.** It is also the cheapest deterministic failure to assert
458
+ on: a non-advancing config trips it within seconds, no provider
459
+ credential rejection required. Related: a `restapi` updater that
460
+ declares pagination but whose `path`/`params`/`body` never read
461
+ `msg.pagination_context` or `msg.page` is now refused at create/update
462
+ — see §2's template contract.
463
+
464
+ **If a message's status is not reconciling, do this — in order:**
465
+
466
+ 1. Call `refresh()`, wait for `last_run_at` to advance past the
467
+ baseline you captured, then read `last_run_status` /
468
+ `last_run_error` / `status`. They name the failing stage: window
469
+ render, source fetch, template render, JSON parse — or a halted
470
+ poll cycle.
471
+ 2. Check the config against §2 above. A config that violates the
472
+ template contract is rejected at create, so a *deployed* updater's
473
+ templates are structurally sound — the fault is more likely the
474
+ event shape or the `external_id` join.
475
+ 3. **If those don't explain it, ESCALATE TO A HUMAN.** Report the
476
+ updater id, `last_run_error`, and the event shape you expected.
477
+
478
+ A wrong config guess is worse than no change: replacing the unix-ms
479
+ poll window with the ISO-8601 `now` filter, for example, stops the
480
+ updater polling at all — verify each `refresh` outcome before
481
+ touching the config again.
482
+
483
+ ## 8. Where delivery truth comes from (consumer view)
484
+
485
+ If you only READ the platform (an operator UI, a dashboard), this
486
+ is the part that matters:
487
+
488
+ ```
489
+ dispatch writes: messages row, status 'sent',
490
+ external_id = provider's id
491
+ THIS updater writes: 'delivered' or 'failed' +
492
+ failure_reason (+ delivered_at)
493
+ nothing else writes those.
494
+ ```
495
+
496
+ - **No updater configured → no delivery truth.** Rows stay `sent`
497
+ forever; a delivery-rate number computed from them is fiction.
498
+ Updaters are created manually (this page §1) — the platform does
499
+ not auto-create them per sender tool.
500
+ - **The join is `{external_id, set_params}`,** exact-match, silent
501
+ on misses (gotcha 3). "Eventually honest": a just-sent row is
502
+ neither delivered nor failed yet — show the in-between state.
503
+ - **Retry is not here.** The updater only reports. Re-sending a
504
+ failed message is `workflows.execute` for that subject +
505
+ decision (`mode: 'live'`, `manual_override: true`) — the same
506
+ call as any manual dispatch; there is no retry endpoint. See
507
+ `workflows.md` §8.
508
+ - **Engagement is not here either.** `opened_at` /
509
+ `form_submitted_at` arrive via
510
+ `connectedApps.updateMessageTracking` (magic-link seam,
511
+ `connected_apps.md` §6) and never touch `status`.
512
+ - Field-by-field semantics of the rows being updated:
513
+ `messages.md`, `action_logs.md`.