@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.
- package/.agent/AGENTS.md +75 -19
- package/.agent/account_management.md +59 -41
- package/.agent/action_logs.md +8 -3
- package/.agent/action_status_updaters.md +129 -52
- 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 +97 -3
- 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/{payment_risk.md → payments.md} +27 -27
- package/.agent/cookbook/_setup/{accounts_receivable.md → subscription.md} +27 -27
- package/.agent/cookbook/action-status-updaters.md +25 -18
- package/.agent/cookbook/bulk-ingest.md +15 -15
- package/.agent/cookbook/dunning-sms-for-delinquent.md +21 -21
- package/.agent/cookbook/generic-tables.md +6 -6
- package/.agent/cookbook/invite-team.md +6 -6
- package/.agent/cookbook/kyc-notification-on-account-activation.md +26 -26
- package/.agent/cookbook/marketing-campaign-send.md +1003 -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 +152 -42
- package/.agent/data_sources.md +53 -35
- package/.agent/datalakes.md +29 -16
- package/.agent/debugging.md +47 -14
- package/.agent/errors.md +39 -17
- package/.agent/generic_tables.md +150 -51
- package/.agent/interoperability_contracts.md +85 -15
- package/.agent/mdm.md +171 -103
- package/.agent/messages.md +99 -19
- package/.agent/templates.md +21 -4
- package/.agent/tool-call-configs.md +1 -1
- package/.agent/tools.md +114 -59
- package/.agent/type_naming.md +79 -18
- package/.agent/workflows.md +287 -53
- package/README.md +1 -1
- package/dist/index.d.mts +311 -29
- package/dist/index.d.mts.map +1 -1
- package/dist/index.mjs +42 -14
- package/dist/index.mjs.map +1 -1
- package/package.json +8 -5
- /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
|
-
|
|
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
|
-
//
|
|
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, //
|
|
117
|
-
apiKey, // REQUIRED
|
|
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
|
-
|
|
143
|
-
|
|
144
|
-
|
|
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
|
-
|
|
148
|
-
- **tenant-scoped** — the canonical Bearer for tenant operations
|
|
149
|
-
|
|
150
|
-
`X-API-Key required to sign
|
|
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
|
-
**
|
|
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
|
-
**
|
|
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.
|
|
495
|
-
|
|
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.
|
|
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
|
-
| `
|
|
25
|
-
| `
|
|
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
|
|
42
|
+
### Three scopes, two minters
|
|
43
43
|
|
|
44
|
-
|
|
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
|
-
//
|
|
50
|
-
//
|
|
51
|
-
|
|
52
|
-
|
|
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
|
-
//
|
|
56
|
-
|
|
57
|
-
|
|
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
|
|
62
|
-
// REQUIRES
|
|
63
|
-
//
|
|
64
|
-
//
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
218
|
+
admin.signUp admin.signUp
|
|
207
219
|
│ │
|
|
208
220
|
api.admin.confirmUser* api.admin.confirmUser* (* production: email link)
|
|
209
221
|
│ │
|
|
210
|
-
|
|
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.
|
|
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**:
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
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
|
-
| `'
|
|
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" | `
|
|
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
|
-
|
|
433
|
-
|
|
434
|
-
|
|
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.
|
|
444
|
-
|
|
445
|
-
`
|
|
446
|
-
|
|
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)
|
package/.agent/action_logs.md
CHANGED
|
@@ -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): `
|
|
102
|
-
`channel`, `
|
|
103
|
-
`
|
|
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
|
|
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`
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
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
|
-
|
|
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
|
|
86
|
-
|
|
87
|
-
|
|
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
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
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
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
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`
|
|
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
|
-
|
|
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
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
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.
|
|
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
|
|
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
|
|
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)
|
|
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
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
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.
|
|
255
|
-
message row
|
|
256
|
-
|
|
257
|
-
|
|
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.
|
|
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:
|