@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.
- package/.agent/AGENTS.md +121 -19
- package/.agent/account_management.md +110 -38
- package/.agent/action_logs.md +144 -0
- package/.agent/action_status_updaters.md +302 -53
- package/.agent/ai_agents.md +149 -53
- package/.agent/ai_sandbox.md +11 -4
- package/.agent/async.md +16 -6
- package/.agent/connected_apps.md +123 -6
- package/.agent/cookbook/_fixtures/README.md +9 -9
- package/.agent/cookbook/_fixtures/{payment_risk/_compliance_screenings_payment_risk_compliance_screening.liquid → payments/_compliance_screenings_payments_compliance_screening.liquid} +1 -1
- package/.agent/cookbook/_fixtures/{payment_risk/_compliance_screenings_payment_risk_mdm.liquid → payments/_compliance_screenings_payments_mdm.liquid} +1 -1
- package/.agent/cookbook/_fixtures/{payment_risk/_payment_accounts_payment_risk_mdm.liquid → payments/_payment_accounts_payments_mdm.liquid} +1 -1
- package/.agent/cookbook/_fixtures/{payment_risk/_payment_accounts_payment_risk_payment_account.liquid → payments/_payment_accounts_payments_payment_account.liquid} +1 -1
- package/.agent/cookbook/_fixtures/{accounts_receivable/_customers_accounts_receivable_customer.liquid → subscription/_customers_subscription_customer.liquid} +1 -1
- package/.agent/cookbook/_fixtures/{accounts_receivable/_customers_accounts_receivable_mdm.liquid → subscription/_customers_subscription_mdm.liquid} +1 -1
- package/.agent/cookbook/_setup/foundation.md +24 -4
- package/.agent/cookbook/_setup/healthcare.md +24 -4
- package/.agent/cookbook/_setup/{payment_risk.md → payments.md} +51 -31
- package/.agent/cookbook/_setup/{accounts_receivable.md → subscription.md} +51 -31
- package/.agent/cookbook/action-status-updaters.md +41 -18
- package/.agent/cookbook/bulk-ingest.md +15 -15
- package/.agent/cookbook/dunning-sms-for-delinquent.md +21 -21
- package/.agent/cookbook/fork-and-apply-cold.md +192 -0
- package/.agent/cookbook/{custom-tables.md → generic-tables.md} +44 -41
- package/.agent/cookbook/invite-team.md +19 -13
- package/.agent/cookbook/kyc-notification-on-account-activation.md +26 -26
- package/.agent/cookbook/marketing-campaign-send.md +1003 -0
- package/.agent/cookbook/paginated-restapi-poller.md +284 -0
- package/.agent/cookbook/rest-fetch.md +9 -9
- package/.agent/cookbook/sanctions-screening-with-agent-review.md +22 -22
- package/.agent/cookbook/system-templates.md +15 -15
- package/.agent/cookbook/triage-prospects-by-priority.md +17 -17
- package/.agent/cookbook/welcome-sms-for-customers.md +21 -21
- package/.agent/data_activation_clients.md +177 -42
- package/.agent/data_sources.md +55 -37
- package/.agent/datalakes.md +54 -17
- package/.agent/debugging.md +48 -14
- package/.agent/errors.md +39 -17
- package/.agent/generic_tables.md +150 -51
- package/.agent/interoperability_contracts.md +114 -15
- package/.agent/mdm.md +171 -93
- package/.agent/messages.md +252 -0
- package/.agent/templates.md +21 -4
- package/.agent/tool-call-configs.md +12 -1
- package/.agent/tools.md +181 -63
- package/.agent/type_naming.md +83 -18
- package/.agent/workflows.md +408 -62
- package/LICENSE +21 -93
- package/README.md +2 -2
- package/dist/bin/platform-sdk.mjs +53 -1
- package/dist/bin/platform-sdk.mjs.map +1 -1
- package/dist/index.d.mts +737 -70
- package/dist/index.d.mts.map +1 -1
- package/dist/index.mjs +656 -105
- package/dist/index.mjs.map +1 -1
- package/package.json +10 -6
- /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
|
|
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
|
-
|
|
52
|
-
|
|
53
|
-
|
|
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
|
-
`
|
|
79
|
-
`
|
|
80
|
-
`
|
|
81
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
91
|
-
|
|
92
|
-
|
|
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
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
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`
|
|
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
|
-
|
|
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
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
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.
|
|
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
|
|
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
|
|
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)
|
|
208
|
-
|
|
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
|
-
|
|
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
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
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.
|
|
255
|
-
message row
|
|
256
|
-
|
|
257
|
-
|
|
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`.
|