@alvera-ai/platform-sdk 0.12.1-next.g9121cfc → 0.12.1-next.ga66b8a5

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 (50) hide show
  1. package/.agent/AGENTS.md +75 -19
  2. package/.agent/account_management.md +59 -41
  3. package/.agent/action_logs.md +8 -3
  4. package/.agent/action_status_updaters.md +129 -52
  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 +97 -3
  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/{payment_risk.md → payments.md} +27 -27
  17. package/.agent/cookbook/_setup/{accounts_receivable.md → subscription.md} +27 -27
  18. package/.agent/cookbook/action-status-updaters.md +25 -18
  19. package/.agent/cookbook/bulk-ingest.md +15 -15
  20. package/.agent/cookbook/dunning-sms-for-delinquent.md +21 -21
  21. package/.agent/cookbook/generic-tables.md +6 -6
  22. package/.agent/cookbook/invite-team.md +6 -6
  23. package/.agent/cookbook/kyc-notification-on-account-activation.md +26 -26
  24. package/.agent/cookbook/marketing-campaign-send.md +1003 -0
  25. package/.agent/cookbook/rest-fetch.md +9 -9
  26. package/.agent/cookbook/sanctions-screening-with-agent-review.md +22 -22
  27. package/.agent/cookbook/system-templates.md +15 -15
  28. package/.agent/cookbook/triage-prospects-by-priority.md +17 -17
  29. package/.agent/cookbook/welcome-sms-for-customers.md +21 -21
  30. package/.agent/data_activation_clients.md +152 -42
  31. package/.agent/data_sources.md +53 -35
  32. package/.agent/datalakes.md +29 -16
  33. package/.agent/debugging.md +47 -14
  34. package/.agent/errors.md +39 -17
  35. package/.agent/generic_tables.md +150 -51
  36. package/.agent/interoperability_contracts.md +85 -15
  37. package/.agent/mdm.md +171 -103
  38. package/.agent/messages.md +99 -19
  39. package/.agent/templates.md +21 -4
  40. package/.agent/tool-call-configs.md +1 -1
  41. package/.agent/tools.md +114 -59
  42. package/.agent/type_naming.md +79 -18
  43. package/.agent/workflows.md +287 -53
  44. package/README.md +1 -1
  45. package/dist/index.d.mts +311 -29
  46. package/dist/index.d.mts.map +1 -1
  47. package/dist/index.mjs +42 -14
  48. package/dist/index.mjs.map +1 -1
  49. package/package.json +8 -5
  50. /package/.agent/cookbook/_fixtures/{accounts_receivable → subscription}/stripe_customers_batch1.csv +0 -0
package/.agent/AGENTS.md CHANGED
@@ -52,6 +52,28 @@ opening it. If you find yourself emitting a claim about a kind's
52
52
  wire shape without having opened that kind's MD in the current
53
53
  session, **stop and open it now**.
54
54
 
55
+ ### You are NOT entitled to conclude "the platform cannot do X"
56
+
57
+ This corpus is your window onto the platform, not its floor plan.
58
+ **Absence from these guides is not evidence the platform lacks a
59
+ capability** — it usually just means no use case had yet forced that
60
+ capability into the docs. The platform is deliberately generic; the
61
+ same primitives back many verticals, and each new build surfaces a
62
+ fresh batch of capabilities the corpus never had a reason to spell out.
63
+
64
+ So when a build seems to need something you can't find here, the honest
65
+ output is a **problem statement to the platform team** ("I need to do
66
+ X; the corpus doesn't document a way — does one exist?"), **not a
67
+ verdict** ("the platform can't do X"). A wrong "can't" is expensive: it
68
+ sends an agent to build the wrong thing or to file a request for a
69
+ feature that already ships. Real examples that were *all* in the
70
+ platform but missing from the corpus until a single build forced them
71
+ in: SMS quiet-hours send windows, pausing a scheduled campaign by
72
+ editing an action's `runtime_filter`, scheduling on the action rather
73
+ than the run, per-recipient tracked-link minting, and per-variant
74
+ `GROUP BY decision_key` analytics. Each was momentarily mistaken for a
75
+ platform gap. Don't repeat that — escalate the question, don't rule.
76
+
55
77
  ---
56
78
 
57
79
  ## If you know MCP — vocabulary mapping
@@ -100,23 +122,32 @@ construction.
100
122
  ## SDK auth + client construction
101
123
 
102
124
  The SDK is a strict-TypeScript REST client for the Alvera
103
- platform. Two-step auth + client construction:
125
+ platform. Two-step auth + client construction — and there are **two**
126
+ session minters, not one (see `account_management.md` for the full
127
+ treatment):
104
128
 
105
129
  import {
106
- createSession,
130
+ createBootstrapSession, // tenantless / root Bearer
131
+ createSession, // tenant-scoped Bearer
107
132
  createIsolatedPlatformApi,
108
133
  type PlatformApi,
109
134
  } from '@alvera-ai/platform-sdk'
110
135
 
111
- // 1. mint a session
136
+ // 1a. tenantless / root — POST /api/v1/admin/bootstrap-session.
137
+ // Keyless by structural necessity (it mints the FIRST Bearer of an
138
+ // environment, before any tenant key exists). Returned tenant + role
139
+ // are always null. Dev / integration-test route — absent from prod.
140
+ const bootstrap = await createBootstrapSession({ baseUrl, email, password })
141
+
142
+ // 1b. tenant-scoped — the canonical app session. tenantSlug AND apiKey
143
+ // are BOTH required; sign-in 401s ("X-API-Key required to sign in to
144
+ // a tenant") without a resolvable X-API-Key.
112
145
  const session = await createSession({
113
146
  baseUrl,
114
147
  email,
115
148
  password,
116
- tenantSlug, // optional; omit for tenantless session
117
- apiKey, // REQUIRED. tenant-scoped sign-in is 401'd without a
118
- // resolvable X-API-Key; pass '' for root/tenantless
119
- // (the field is required by the type, inert on the wire)
149
+ tenantSlug, // REQUIRED
150
+ apiKey, // REQUIRED — the tenant's publishable key
120
151
  })
121
152
 
122
153
  // 2. build a typed client
@@ -139,15 +170,33 @@ in the platform's API-keys page (Settings → API Keys), or
139
170
  programmatically via `api.admin.createTenantApiKey(tenantSlug,
140
171
  { name, data_access_mode })` (platform-admin-gated).
141
172
 
142
- Sessions come in three scopes:
143
- - **root** — Alvera root admin; user signup + confirmation
144
- (`apiKey: ''` — no tenant to scope a key to)
173
+ **A CORS preflight is NOT proof the key admits your origin.** A
174
+ browser `OPTIONS` preflight carries no `X-API-Key` (only the method
175
+ + `Access-Control-Request-Headers`), so the server cannot resolve a
176
+ key and answers permissively — EVERY origin gets a friendly
177
+ `access-control-allow-origin` echo. The enforced policy runs on the
178
+ actual authenticated request, against the resolved key's
179
+ `allowed_origins`. Never verify origins with a preflight — verify
180
+ with a real signed-in round-trip. Triage for a failing browser
181
+ sign-in: (1) console says the key env var is missing → your `.env`
182
+ didn't load (restart the dev server after editing it); (2) the REAL
183
+ call is blocked by CORS (no ACAO on it) → the key's
184
+ `allowed_origins` doesn't include your dev origin — mint/patch the
185
+ key, and don't trust the earlier green preflight; (3) a `401` with
186
+ NO CORS error → the request PASSED CORS; the fault is the
187
+ credentials or the key not resolving, not origins.
188
+
189
+ Sessions come in three scopes, minted by two functions:
190
+ - **root** — Alvera root admin; user signup + confirmation. Minted by
191
+ `createBootstrapSession` (a tenantless Bearer that belongs to a
192
+ platform-admin user).
145
193
  - **tenantless** — authenticated user with no tenant chosen yet;
146
- used once to create a tenant via `api.tenants.create(...)`
147
- (`apiKey: ''`)
148
- - **tenant-scoped** — the canonical Bearer for tenant operations
149
- (**requires a real tenant API key** — the login 401s with
150
- `X-API-Key required to sign in to a tenant` otherwise)
194
+ used once to create a tenant via `api.tenants.create(...)`. Also
195
+ minted by `createBootstrapSession`.
196
+ - **tenant-scoped** — the canonical Bearer for tenant operations,
197
+ minted by `createSession` (**requires both `tenantSlug` and a real
198
+ tenant API key** — the login 401s with `X-API-Key required to sign
199
+ in to a tenant` otherwise).
151
200
 
152
201
  **Build apps tenant-scoped, and only tenant-scoped.** The root and
153
202
  tenantless scopes exist for the platform's own UI and for
@@ -424,7 +473,7 @@ into consumer `<cwd>/AGENTS.md` files as a managed block.
424
473
  buckets (appointment / job-application / spam) via an LLM
425
474
  agent, route each to a tailored SMS action.
426
475
 
427
- **Accounts Receivable**
476
+ **Subscription**
428
477
 
429
478
  - [welcome-sms-for-customers](./cookbook/welcome-sms-for-customers.md)
430
479
  — Send a welcome SMS to newly contracted customers with a
@@ -438,7 +487,7 @@ into consumer `<cwd>/AGENTS.md` files as a managed block.
438
487
  (high / medium / low) via an LLM agent, route each band to a
439
488
  tailored SMS action.
440
489
 
441
- **Payment Risk**
490
+ **Payments**
442
491
 
443
492
  - [kyc-notification-on-account-activation](./cookbook/kyc-notification-on-account-activation.md)
444
493
  — Send a KYC-notification SMS when a payment account
@@ -457,6 +506,11 @@ into consumer `<cwd>/AGENTS.md` files as a managed block.
457
506
  — Score inbound leads into four bands
458
507
  (hot / warm / cold / spam) via an LLM agent, route each band
459
508
  to a tailored SMS action.
509
+ - [marketing-campaign-send](./cookbook/marketing-campaign-send.md)
510
+ — Send an A/B marketing campaign across SMS and email: the
511
+ suppression and reachability gates and the A/B split all live
512
+ in the workflow, each send carries a per-recipient short link,
513
+ and the reply re-attaches to the customer who sent it.
460
514
 
461
515
  <!-- END:cookbook-index -->
462
516
 
@@ -491,8 +545,10 @@ full wire shape.
491
545
 
492
546
  Cross-resource utilities not documented in this corpus:
493
547
 
494
- api.auth signUp + auth helpers
495
- api.admin confirmUser + admin actions
548
+ api.admin signUp + confirmUser + createTenantApiKey
549
+ (dev / integration-test fixtures)
550
+ api.sessions verify; top-level createBootstrapSession /
551
+ createSession / revokeSession mint + revoke Bearers
496
552
  api.tenants create + tenant lifecycle
497
553
  api.datasets cross-resource search / metadata /
498
554
  user-saved searches
@@ -15,14 +15,14 @@ together:
15
15
 
16
16
  | Namespace | Methods |
17
17
  |--------------------|-----------------------------------------------|
18
- | `api.auth` | `signUp` |
19
- | `api.admin` | `confirmUser` — **dev fixture only** |
18
+ | `api.admin` | `signUp`, `confirmUser`, `createTenantApiKey` — **dev / integration-test fixtures only** |
20
19
  | `api.sessions` | `verify` |
21
20
  | `api.tenants` | `create`, `list` |
22
21
  | `api.invitations` | `create`, `list`, `accept` |
23
22
  | `api.ping` | unauthenticated health check (`GET /api/ping`) |
24
- | `createSession` | mint a Bearer (top-level helper, not a namespace) |
25
- | `revokeSession` | revoke the current Bearer (top-level helper, parallel to `createSession`) |
23
+ | `createBootstrapSession` | mint a **tenantless** Bearer (top-level helper, not a namespace) |
24
+ | `createSession` | mint a **tenant-scoped** Bearer (top-level helper, not a namespace) |
25
+ | `revokeSession` | revoke the current Bearer (top-level helper, parallel to the two minters) |
26
26
 
27
27
  Two top-level concerns sit above the surface:
28
28
 
@@ -39,29 +39,39 @@ The Bearer carries the trust-boundary coordinates and travels in
39
39
  the `Authorization: Bearer <token>` header on every subsequent
40
40
  request.
41
41
 
42
- ### Three Bearer scopes
42
+ ### Three scopes, two minters
43
43
 
44
- `createSession` mints a Bearer at one of three scopes:
44
+ Sessions come in three scopes — **root**, **tenantless**, and
45
+ **tenant-scoped** — but there are only **two** functions that mint a
46
+ Bearer. `createBootstrapSession` mints the keyless tenantless Bearer
47
+ (root is a tenantless Bearer that happens to belong to a platform-admin
48
+ user); `createSession` mints the tenant-scoped Bearer.
45
49
 
46
50
  ```typescript
47
- import { createSession } from '@alvera-ai/platform-sdk'
48
-
49
- // root admin (no tenant) — for confirmUser, signUp on behalf of, etc.
50
- // apiKey is required by the type but inert for non-tenant scopes — pass ''.
51
- const root = await createSession({
52
- baseUrl, email: rootEmail, password: rootPassword, apiKey: '',
51
+ import { createBootstrapSession, createSession } from '@alvera-ai/platform-sdk'
52
+
53
+ // tenantless — POST /api/v1/admin/bootstrap-session. Keyless by structural
54
+ // necessity (it mints the very first Bearer of an environment, before any
55
+ // tenant key exists). Returned tenant + role are ALWAYS null. This is an
56
+ // integration-test / dev-only route — absent from prod builds.
57
+ const tenantless = await createBootstrapSession({
58
+ baseUrl, email, password,
53
59
  })
60
+ // tenantless.tenant === null && tenantless.role === null
54
61
 
55
- // tenantless — authenticated user who has not picked a tenant yet
56
- const tenantless = await createSession({
57
- baseUrl, email, password, apiKey: '',
62
+ // root — the SAME call, with a platform-admin user's credentials. The
63
+ // admin capability comes from the user, not a different function. Use it
64
+ // for admin.signUp / admin.confirmUser / admin.createTenantApiKey.
65
+ const root = await createBootstrapSession({
66
+ baseUrl, email: rootEmail, password: rootPassword,
58
67
  })
59
- // tenantless.tenant === null
60
68
 
61
- // tenant-scoped — the canonical Bearer for tenant operations.
62
- // REQUIRES a real tenant API key (sent as X-API-Key): the server 401s
63
- // with "X-API-Key required to sign in to a tenant" without one. The
64
- // minted Bearer inherits the origin policy of the key that minted it.
69
+ // tenant-scoped — POST /api/v1/sessions, the canonical Bearer for tenant
70
+ // operations. REQUIRES both tenantSlug AND a resolvable tenant publishable
71
+ // key (sent as X-API-Key): the server 401s with "X-API-Key required to
72
+ // sign in to a tenant" without one, and 403s a key belonging to a different
73
+ // tenant. The minted Bearer inherits the origin policy of the key that
74
+ // minted it, and that same key must accompany every subsequent request.
65
75
  const tenant = await createSession({
66
76
  baseUrl, email, password, tenantSlug, apiKey: tenantApiKey,
67
77
  })
@@ -71,7 +81,7 @@ const tenant = await createSession({
71
81
 
72
82
  The tenant API key is minted by a tenant admin in the platform's
73
83
  API-keys page (Settings → API Keys), or programmatically via the
74
- platform-admin-gated side door:
84
+ platform-admin side door (a root Bearer):
75
85
 
76
86
  ```typescript
77
87
  const { data: minted } = await rootApi.admin.createTenantApiKey(tenantSlug, {
@@ -133,7 +143,9 @@ local server before authentication failures muddy the diagnostic.
133
143
  ### Sign up
134
144
 
135
145
  ```typescript
136
- const { data: user } = await rootApi.auth.signUp({
146
+ // signUp lives under the admin namespace (there is no `api.auth`); it is an
147
+ // integration-test fixture, reachable only from a root Bearer.
148
+ const { data: user } = await rootApi.admin.signUp({
137
149
  email: 'sarah@example.com',
138
150
  password: '...',
139
151
  first_name: 'Sarah',
@@ -203,11 +215,11 @@ to many tenants; a Bearer is scoped to exactly one.
203
215
  ```
204
216
  ┌─ creator path ─┐ ┌─ invitee path ─┐
205
217
  │ │
206
- api.auth.signUp api.auth.signUp
218
+ admin.signUp admin.signUp
207
219
  │ │
208
220
  api.admin.confirmUser* api.admin.confirmUser* (* production: email link)
209
221
  │ │
210
- createSession (no tenantSlug) createSession (no tenantSlug)
222
+ createBootstrapSession createBootstrapSession
211
223
  │ │
212
224
  api.tenants.create api.invitations.list → .accept
213
225
  │ │
@@ -226,26 +238,30 @@ role specified in their invitation.
226
238
  const { data } = await tenantlessApi.tenants.create({
227
239
  name: 'Acme Health',
228
240
  })
229
- // data.tenant.id, data.tenant.slug — server-derived
230
- // data.session_token — see "Gotchas" below
241
+ // data.id, data.slug, data.name — server-derived (flat TenantResponse)
231
242
  ```
232
243
 
233
244
  The slug is server-derived from `name` per the universal slug
234
245
  rules (see `type_naming.md` "Never pre-compute the slug
235
246
  client-side"). Use the returned slug for downstream calls.
236
247
 
237
- **Gotcha**: the response carries a `session_token` field, but this
238
- is an *incidental* token — do not treat it as a freshly minted
239
- tenant-scoped Bearer. The authoritative pattern is to call
240
- `createSession({ ..., tenantSlug, apiKey })` after `tenants.create`. This
241
- gives a fresh Bearer with all role + tenant claims correctly
242
- populated.
248
+ **Gotcha**: `tenants.create` returns only the tenant — a flat
249
+ `TenantResponse` (`id`, `slug`, `name`, `description`), **not** a Bearer
250
+ and with no `session_token`. The caller's tenantless Bearer stays valid,
251
+ but it is still tenantless. To act on the new tenant, mint a tenant-scoped
252
+ Bearer via `createSession({ ..., tenantSlug, apiKey })` — which is also
253
+ where the mandatory `X-API-Key` first enters the flow. (The tenant's
254
+ default `public_api` key is auto-minted at creation, but its plaintext is
255
+ not returned here — read it from Settings → API Keys, or mint a fresh key
256
+ via `admin.createTenantApiKey`.)
243
257
 
244
258
  ### `api.tenants.list`
245
259
 
246
260
  ```typescript
247
261
  const { data: tenants } = await api.tenants.list()
248
262
  // tenants.data: TenantResponse[] — every tenant the current Bearer can see
263
+ // takes an optional Flop query (page/page_size/order_by/filters —
264
+ // see type_naming.md "List response types")
249
265
  ```
250
266
 
251
267
  A root Bearer sees every tenant; a tenant-scoped Bearer typically
@@ -294,7 +310,7 @@ the invitation enum:
294
310
  |-------------------------|------------------------------------|--------------|
295
311
  | `'tenant_admin'` | Full tenant management | invitation `'admin'` |
296
312
  | `'member'` | Standard tenant user | invitation `'member'` |
297
- | `'tenant_api'` | Programmatic tenant access (most API keys) | provisioned, not invited |
313
+ | `'public_api'` | Lowest-privilege publishable key (Stripe `pk_` analogue); the mandatory `X-API-Key` companion | provisioned, not invited |
298
314
  | `'datalake_admin'` | Full datalake management (requires `datalake_id` on session) | console-mediated |
299
315
  | `'researcher'` | Tokenized-only datalake access | invitation `'researcher'` |
300
316
  | `'datalake_api'` | Programmatic datalake access | provisioned, not invited |
@@ -422,16 +438,18 @@ documented in `errors.md`. Common rejections:
422
438
 
423
439
  | `source.pointer` / shape | Cause |
424
440
  |-------------------------------------------------|----------------------------------------------|
425
- | `/email` "has already been taken" | `auth.signUp` with an existing email |
441
+ | `/email` "has already been taken" | `admin.signUp` with an existing email |
426
442
  | `/password` "is too short" | password below minimum length |
427
443
  | top-level 401 (no envelope) | Bearer missing, expired, or revoked |
428
444
  | top-level 403 (no envelope) | role lacks permission for the action |
429
445
  | `/email` "already invited" | duplicate `invitations.create` |
430
446
  | `/tenant_slug` "not found" | tenant slug doesn't exist or invisible to Bearer |
431
447
 
432
- The `tenants.create` 422 is typically `/name` uniqueness — names
433
- must be unique platform-wide. Re-attempt with a different name or
434
- treat as "already exists" via `api.tenants.list` lookup.
448
+ A `tenants.create` `/name` uniqueness collision comes back as a
449
+ **409 Conflict** (not 422 — uniqueness constraints route to 409; see
450
+ `errors.md`) — names must be unique platform-wide. Re-attempt with a
451
+ different name or treat as "already exists" via `api.tenants.list`
452
+ lookup.
435
453
 
436
454
  ## 6. Gotchas
437
455
 
@@ -440,10 +458,10 @@ treat as "already exists" via `api.tenants.list` lookup.
440
458
  the SDK method as a test fixture; do not ship code that calls
441
459
  it from a customer-facing path.
442
460
 
443
- 2. **The `session_token` returned by `tenants.create` is
444
- incidental.** Always re-mint a fresh tenant-scoped Bearer via
445
- `createSession({ ..., tenantSlug, apiKey })` after creating a tenant.
446
- This guarantees clean role+tenant claims on the Bearer.
461
+ 2. **`tenants.create` returns a tenant, not a Bearer.** The response is
462
+ a flat `TenantResponse` (`id`, `slug`, `name`, `description`) with no
463
+ `session_token`. After creating a tenant, mint a tenant-scoped Bearer
464
+ via `createSession({ ..., tenantSlug, apiKey })` to act on it.
447
465
 
448
466
  3. **Tenantless Bearer is a transient state.** Only two
449
467
  operations are useful with it: `tenants.create` (creator path)
@@ -37,6 +37,8 @@ id, workflow_id, action_id, workflow_execution_log_id,
37
37
  batch_id — the run this outcome belongs to; THE
38
38
  campaign key (messages does not have it)
39
39
  decision_key — which action fired
40
+ context_key — companion string key; like decision_key, it is
41
+ SQL-lane only (neither is Flop-filterable, §5)
40
42
  mdm_subject_id, subject_name, session_id
41
43
  action_type ('sms'|'email'|'voice'|'data_exchange'), channel,
42
44
  classification
@@ -98,9 +100,12 @@ const { data: page } = await api.datasets.search(
98
100
  )
99
101
  ```
100
102
 
101
- Filterable columns (Flop): `status`, `batch_id`, `action_type`,
102
- `channel`, `classification`, `workflow_id`, `sent_at`,
103
- `external_id`, `mdm_subject_id`, `inserted_at`.
103
+ Filterable columns (Flop, the full set): `id`, `inserted_at`,
104
+ `action_type`, `channel`, `status`, `batch_id`, `classification`,
105
+ `workflow_id`, `sent_at`, `external_id`, `mdm_subject_id`. Note
106
+ there is **no `global_search`** here (unlike the message dataset) —
107
+ `decision_key`/`context_key` are not in this set either; scope them
108
+ via the `search_query` SQL fragment above.
104
109
 
105
110
  "Who did this campaign go to" = the query above (subject columns
106
111
  + status per row — exportable as-is). For bulk export the platform
@@ -44,13 +44,12 @@ 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"}',
54
53
  },
55
54
  },
56
55
  )
@@ -75,29 +74,54 @@ updater_body_type: 'cloud_watch_request'
75
74
  follow the same `<verb>_request` naming and carry the fields
76
75
  their target API requires.)
77
76
 
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.
77
+ `start_time` / `end_time` are Liquid, and they **must render to
78
+ unix milliseconds** — that is what the poll request takes. On
79
+ these two fields `now` is a **variable already holding unix ms**,
80
+ so pipe it through the relative-time filters:
82
81
 
83
- ### `message_config.body` emits a JSON event stream
82
+ ```
83
+ start_time: '{{ now | minutes_ago: 45 }}' // 45 minutes back
84
+ end_time: '{{ now }}' // right now
85
+ ```
86
+
87
+ Also available: `hours_ago: N`.
88
+
89
+ **Do not use the ISO-8601 `now` filter here.** `{{ "" | now }}` is
90
+ a different thing — it renders a datetime *string*, which is not a
91
+ valid window, and the platform rejects it at create. An ISO 8601
92
+ literal is not valid on these fields either.
93
+
94
+ ### `message_config.body` renders ONCE PER EVENT
84
95
 
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:
96
+ The template is rendered **once for each fetched event, with that
97
+ event as the entire assigns**. There is no `events` collection in
98
+ scope — do not loop.
88
99
 
100
+ ```liquid
101
+ {"external_id": "{{ notification.messageId }}", "status": "delivered"}
89
102
  ```
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 })
103
+
104
+ It must render a **flat** JSON object:
105
+
106
+ ```
107
+ external_id string — the message to update (matches the message row's
108
+ external_id, i.e. the provider's id)
109
+ <field> any — each remaining TOP-LEVEL key is a field to set:
110
+ status, sent_at, delivered_at, read_at, opened_at
95
111
  ```
96
112
 
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.
113
+ There is **no `set_params` wrapper**. Every key that is not
114
+ `external_id` *is* the update. Nesting the fields under
115
+ `set_params` renders an object the platform's field allowlist
116
+ drops, so the update silently applies to nothing.
117
+
118
+ The platform joins each rendered `external_id` to a message row
119
+ and applies the remaining fields. Events that don't match any
120
+ message are silently discarded — a provider poll routinely sees
121
+ events for messages this updater doesn't own.
122
+
123
+ Custom Liquid filters (`json_escape`, `e164`, `to_json`, ...) are
124
+ available here, as everywhere.
101
125
 
102
126
  ### `cron_expression` is a standard 5-field cron string
103
127
 
@@ -111,7 +135,7 @@ Sub-minute cadences are NOT supported. The minimum interval
111
135
  the scheduler honors depends on platform-level configuration;
112
136
  default minimum is 5 minutes.
113
137
 
114
- ### `updater_type` and `updater_body.updater_body_type` must correspond
138
+ ### `updater_type` and `updater_body.updater_body_type` — set them to agree, but only one is load-bearing
115
139
 
116
140
  The body carries TWO discriminator fields that name the same
117
141
  choice from different angles:
@@ -123,25 +147,35 @@ choice from different angles:
123
147
  body embed
124
148
  ```
125
149
 
126
- They must agree according to a fixed mapping:
150
+ The intended pairing is a fixed mapping:
127
151
 
128
152
  ```
129
153
  updater_type: "cloud_watch" ↔ updater_body_type: "cloud_watch_request"
130
154
  updater_type: "restapi" ↔ updater_body_type: "restapi_request"
131
155
  ```
132
156
 
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.
157
+ **But the platform does NOT cross-validate the pair — a mismatch is
158
+ NOT rejected.** The two fields are cast independently; there is no
159
+ create-time check that `updater_type` matches
160
+ `updater_body_type`, so a mismatched-but-well-formed pair (e.g.
161
+ `updater_type: "cloud_watch"` + a `restapi_request` body) **persists
162
+ silently**. At runtime the platform dispatches on the polymorphic
163
+ **body** struct, so `updater_body_type` is the one that matters and
164
+ `updater_type` is effectively informational. Set them to agree
165
+ anyway — a future release may start enforcing it, and a lying
166
+ `updater_type` is a debugging trap — but don't expect a 422 to catch
167
+ a mismatch for you today.
139
168
 
140
169
  ### `updater_tool_id` and `sender_tool_ids` serve different roles
141
170
 
142
171
  - `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).
172
+ ISSUE the poll. By convention this is a tool whose `intent` is
173
+ `status_poller` (e.g. a `cloud_watch_log_group` body type) — but
174
+ the platform does **not** verify the intent at create time (it
175
+ checks only that the tool exists and belongs to the tenant). A
176
+ wrong-intent tool is accepted and only fails later, when the poll
177
+ actually runs. Wire a `status_poller` tool anyway; just don't rely
178
+ on a create-time 422 to enforce it.
145
179
  - `sender_tool_ids` (array) — the tools whose sent messages
146
180
  this updater is responsible for tracking. The match logic
147
181
  joins each polled event back to a message row that was
@@ -178,10 +212,9 @@ Standard JSON:API envelopes per `errors.md`. Common rejections:
178
212
  | `source.pointer` | Cause |
179
213
  |-------------------------------------|----------------------------------------------------|
180
214
  | `/cron_expression` | invalid cron syntax or below minimum interval |
181
- | `/updater_tool_id` | tool's intent isn't `status_poller` |
215
+ | `/updater_tool_id` | tool id doesn't exist or wrong datalake (intent is NOT checked — see §2) |
182
216
  | `/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` |
217
+ | `/updater_body/updater_body_type` | value not in the polymorphic embed's type enum |
185
218
  | `/message_config/body` | empty when `type: 'custom'` |
186
219
  | `/base` | `cron_management_failed` — body validated and saved but scheduler registration failed; the row is rolled back |
187
220
 
@@ -204,7 +237,8 @@ branch.
204
237
  ### Read shapes
205
238
 
206
239
  ```
207
- .list(tenantSlug, datalakeSlug) Paged: { data, meta }
240
+ .list(tenantSlug, datalakeSlug, query?) Paged: { data, meta }
241
+ (full Flop query — type_naming.md)
208
242
  .get(tenantSlug, datalakeSlug, id) One row — UUID only
209
243
  .metadata(tenantSlug, datalakeSlug) Markdown — catalog
210
244
  .metadataDetails(tenantSlug, datalakeSlug, Markdown — one updater
@@ -232,17 +266,23 @@ check or retry for partial-delete states.
232
266
 
233
267
  ## 6. Gotchas
234
268
 
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.
269
+ 1. **The polling tool should be `status_poller` — but nothing
270
+ enforces it at create.** By convention `updater_tool_id` points
271
+ at a `status_poller`-intent tool, and the runtime poll assumes
272
+ that shape. The create endpoint, however, does not check the
273
+ tool's intent (only existence + tenant), so an `intent: 'sms'`
274
+ tool is accepted and fails only when the poll runs. Wire the
275
+ right tool; don't count on a create-time rejection to catch a
276
+ wrong one.
277
+
278
+ 2. **`message_config.body` must render one flat JSON object per
279
+ event.** The two authoring mistakes that cannot work:
280
+ looping a `{% for event in events %}` collection (there is
281
+ none — the event *is* the assigns, so the loop renders
282
+ nothing), and nesting the fields under a `set_params` key
283
+ (the platform's allowlist drops them, so the update applies
284
+ to nothing). Both are now **rejected at create**. A render
285
+ that fails at run time is reported in `last_run_error`.
246
286
 
247
287
  3. **`external_id` join is exact-match.** Events whose
248
288
  `external_id` doesn't match a message row are discarded
@@ -251,10 +291,11 @@ check or retry for partial-delete states.
251
291
  the bare id, transform inside the Liquid template (string
252
292
  filters) so the rendered `external_id` matches.
253
293
 
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.
294
+ 4. **The fields you set must be writable columns on the
295
+ message row** — `status`, `sent_at`, `delivered_at`,
296
+ `read_at`, `opened_at`. Unknown keys are silently dropped
297
+ during the update. They go at the TOP LEVEL of the rendered
298
+ object, alongside `external_id`.
258
299
 
259
300
  5. **Cron windows + polling-window overlap.** Choose
260
301
  `start_time` / `end_time` to overlap consecutive cron
@@ -263,7 +304,43 @@ check or retry for partial-delete states.
263
304
  The defaults in the wire-shape example illustrate this
264
305
  pattern: 30-minute cron, 45-minute window.
265
306
 
266
- ## 7. Where delivery truth comes from (consumer view)
307
+ ## 7. KNOWN LIMITATION — no manual trigger, no per-run log. ESCALATE, don't iterate.
308
+
309
+ Unlike a data activation client (`runManually` + `logs`) or an
310
+ agentic workflow (`execute` + `workflowLogs` + `batchLogs`), an
311
+ action status updater **cannot be fired on demand and keeps no
312
+ per-run log.** The only run-outcome surface is four fields on the
313
+ row itself, describing the most recent poll only:
314
+
315
+ ```
316
+ last_run_at when the poll worker last completed a run
317
+ last_run_status 'ok' | 'error'
318
+ last_run_error why the last run failed (structured text)
319
+ last_run_events_found how many events that run fetched
320
+ ```
321
+
322
+ **If a message's status is not reconciling, do this — in order:**
323
+
324
+ 1. `get()` the updater and read `last_run_status` / `last_run_error`.
325
+ They name the failing stage: window render, source fetch, template
326
+ render, or JSON parse.
327
+ 2. Check the config against §2 above. A config that violates the
328
+ template contract is rejected at create, so a *deployed* updater's
329
+ templates are structurally sound — the fault is more likely the
330
+ event shape or the `external_id` join.
331
+ 3. **If those don't explain it, ESCALATE TO A HUMAN.** Report the
332
+ updater id, `last_run_error`, and the event shape you expected.
333
+
334
+ **Do not keep rewriting the config and waiting for the next cron
335
+ tick.** You cannot trigger a poll, so every iteration costs a full
336
+ cron interval, and a wrong guess is worse than no change: replacing
337
+ the unix-ms poll window with the ISO-8601 `now` filter, for example,
338
+ stops the updater polling at all.
339
+
340
+ Tracked as tech debt — the ASU is the only scheduled resource on the
341
+ platform without a manual trigger and per-run logs.
342
+
343
+ ## 8. Where delivery truth comes from (consumer view)
267
344
 
268
345
  If you only READ the platform (an operator UI, a dashboard), this
269
346
  is the part that matters: