@alvera-ai/platform-sdk 0.16.2 → 0.17.0-next.g00fdd4c

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 (82) hide show
  1. package/.agent/AGENTS.md +88 -143
  2. package/.agent/account_management.md +2 -2
  3. package/.agent/action_logs.md +4 -4
  4. package/.agent/ai_agents.md +28 -21
  5. package/.agent/ai_sandbox.md +49 -39
  6. package/.agent/connected_apps.md +3 -3
  7. package/.agent/cookbook/_fixtures/README.md +1 -1
  8. package/.agent/cookbook/_fixtures/{foundation → organic-marketing}/_lead_submissions_foundation_generic_table.liquid +1 -1
  9. package/.agent/cookbook/_fixtures/organic-marketing/_lead_submissions_foundation_legal_entity.liquid +80 -0
  10. package/.agent/cookbook/_fixtures/{foundation → organic-marketing}/_lead_submissions_foundation_mdm.liquid +2 -1
  11. package/.agent/cookbook/_fixtures/payments-compliance/_compliance_screenings_generic_table.liquid +57 -0
  12. package/.agent/cookbook/_fixtures/payments-compliance/_compliance_screenings_legal_entity.liquid +30 -0
  13. package/.agent/cookbook/_fixtures/payments-compliance/_compliance_screenings_mdm.liquid +44 -0
  14. package/.agent/cookbook/_fixtures/payments-compliance/_payment_accounts_generic_table.liquid +57 -0
  15. package/.agent/cookbook/_fixtures/payments-compliance/_payment_accounts_legal_entity.liquid +36 -0
  16. package/.agent/cookbook/_fixtures/payments-compliance/_payment_accounts_mdm.liquid +41 -0
  17. package/.agent/cookbook/_fixtures/primary-care-feedback/_cahps_appointments_generic_table.liquid +70 -0
  18. package/.agent/cookbook/_fixtures/primary-care-feedback/_cahps_appointments_legal_entity.liquid +52 -0
  19. package/.agent/cookbook/_fixtures/primary-care-feedback/_cahps_appointments_mdm.liquid +42 -0
  20. package/.agent/cookbook/_fixtures/subscription-saas/_customers_subscription_generic_table.liquid +38 -0
  21. package/.agent/cookbook/_fixtures/subscription-saas/_customers_subscription_legal_entity.liquid +48 -0
  22. package/.agent/cookbook/_fixtures/subscription-saas/_customers_subscription_mdm.liquid +49 -0
  23. package/.agent/cookbook/organic-marketing.md +2801 -0
  24. package/.agent/cookbook/payments-compliance.md +2180 -0
  25. package/.agent/cookbook/primary-care.md +2175 -0
  26. package/.agent/cookbook/subscription-saas.md +2403 -0
  27. package/.agent/data_activation_clients.md +65 -52
  28. package/.agent/datalakes.md +338 -171
  29. package/.agent/errors.md +3 -3
  30. package/.agent/generic_tables.md +151 -62
  31. package/.agent/interoperability_contracts.md +57 -22
  32. package/.agent/mdm.md +136 -153
  33. package/.agent/messages.md +81 -40
  34. package/.agent/mock-services.md +192 -0
  35. package/.agent/mutations.md +2 -2
  36. package/.agent/templates.md +14 -13
  37. package/.agent/tools.md +108 -26
  38. package/.agent/type_naming.md +13 -13
  39. package/.agent/workflows.md +99 -53
  40. package/dist/bin/platform-sdk.mjs +33 -47
  41. package/dist/bin/platform-sdk.mjs.map +1 -1
  42. package/dist/index.d.mts +521 -385
  43. package/dist/index.d.mts.map +1 -1
  44. package/dist/index.mjs +493 -59
  45. package/dist/index.mjs.map +1 -1
  46. package/package.json +4 -3
  47. package/.agent/cookbook/_fixtures/foundation/_lead_submissions_foundation_legal_entity.liquid +0 -88
  48. package/.agent/cookbook/_fixtures/healthcare/_cahps_appointments_healthcare_appointment.liquid +0 -47
  49. package/.agent/cookbook/_fixtures/healthcare/_cahps_appointments_healthcare_mdm.liquid +0 -24
  50. package/.agent/cookbook/_fixtures/healthcare/_cahps_appointments_healthcare_patient.liquid +0 -38
  51. package/.agent/cookbook/_fixtures/payments/_compliance_screenings_payments_compliance_screening.liquid +0 -59
  52. package/.agent/cookbook/_fixtures/payments/_compliance_screenings_payments_mdm.liquid +0 -36
  53. package/.agent/cookbook/_fixtures/payments/_payment_accounts_payments_mdm.liquid +0 -30
  54. package/.agent/cookbook/_fixtures/payments/_payment_accounts_payments_payment_account.liquid +0 -55
  55. package/.agent/cookbook/_fixtures/subscription/_customers_subscription_mdm.liquid +0 -20
  56. package/.agent/cookbook/_setup/foundation.md +0 -359
  57. package/.agent/cookbook/_setup/healthcare.md +0 -361
  58. package/.agent/cookbook/_setup/payments.md +0 -365
  59. package/.agent/cookbook/_setup/subscription.md +0 -364
  60. package/.agent/cookbook/action-status-updaters.md +0 -278
  61. package/.agent/cookbook/ai-agent-invoke.md +0 -279
  62. package/.agent/cookbook/appointment-review-sms-workflow.md +0 -801
  63. package/.agent/cookbook/birthday-greeting-sms-trigger.md +0 -696
  64. package/.agent/cookbook/bulk-ingest.md +0 -302
  65. package/.agent/cookbook/contact-us-triage-with-llm.md +0 -663
  66. package/.agent/cookbook/dunning-sms-for-delinquent.md +0 -659
  67. package/.agent/cookbook/generic-tables.md +0 -244
  68. package/.agent/cookbook/invite-team.md +0 -200
  69. package/.agent/cookbook/kyc-notification-on-account-activation.md +0 -661
  70. package/.agent/cookbook/marketing-campaign-send.md +0 -1044
  71. package/.agent/cookbook/paginated-restapi-poller.md +0 -383
  72. package/.agent/cookbook/rest-fetch.md +0 -273
  73. package/.agent/cookbook/sanctions-screening-with-agent-review.md +0 -773
  74. package/.agent/cookbook/score-leads-with-llm-categorization.md +0 -665
  75. package/.agent/cookbook/system-templates.md +0 -165
  76. package/.agent/cookbook/talk-to-data.md +0 -178
  77. package/.agent/cookbook/triage-prospects-by-priority.md +0 -571
  78. package/.agent/cookbook/welcome-sms-for-customers.md +0 -647
  79. /package/.agent/cookbook/_fixtures/{healthcare → primary-care-feedback}/memorandum-of-association-01.png +0 -0
  80. /package/.agent/cookbook/_fixtures/{healthcare → primary-care-feedback}/sample_two_page.pdf +0 -0
  81. /package/.agent/cookbook/_fixtures/{subscription → subscription-saas}/_customers_subscription_customer.liquid +0 -0
  82. /package/.agent/cookbook/_fixtures/{subscription → subscription-saas}/stripe_customers_batch1.csv +0 -0
@@ -31,24 +31,33 @@ Read it like any dataset: `api.datasets.createUserSearch` +
31
31
  the plural `messages` is the SQL *table* name (used in
32
32
  `executeSql` queries and as this page's title), and passing it as
33
33
  the dataset type 422s with `/resource_type is not valid`. Base SQL
34
- alias: `rm`.
34
+ alias: `m`.
35
35
 
36
36
  ## 1. The status lifecycle — and who writes each hop
37
37
 
38
38
  ```
39
- pending → queued → sent → delivered
40
- └──→ failed (+ failure_reason)
39
+ pending → accepted → queued → sending → sent → delivered
40
+ └──→ failed (+ failure_reason)
41
41
 
42
- also: invalidated (idempotency rejected a duplicate)
42
+ also: duplicate (provider id already held by another send —
43
+ the send HAPPENED; terminal, never retried)
44
+ invalidated (idempotency key collision — the fire was
45
+ rejected, nothing went out)
43
46
  received (inbound message, direction: 'inbound')
44
47
  clicked (link in the message was clicked)
45
48
  ```
46
49
 
50
+ `accepted` (the provider took the send request) and `sending`
51
+ (dispatching to the carrier) are intermediate hops between `pending`
52
+ and `sent`; the order above is the order the contract declares them.
53
+ Treat any of them as "in flight, outcome unknown" — see **Status is
54
+ eventually honest** below.
55
+
47
56
  Three different writers touch a message row. Know which is which:
48
57
 
49
58
  | Writer | Writes | When |
50
59
  |---|---|---|
51
- | the action executor | the row itself; `pending`→`sent`, `external_id`, `sent_at` | at execution (writes the row at `pending`; advances to `sent` + sets `external_id` only on a live tool call — a dry-run stops at `pending`) |
60
+ | the action executor | the row itself; `pending`→`sent`, `external_id`, `sent_at`; also `duplicate` | at execution (writes the row at `pending`; advances to `sent` + sets `external_id` only on a live tool call — a dry-run stops at `pending`). Lands `duplicate` when the provider id it got back is already held by another send through the same tool |
52
61
  | the action status updater | `delivered` / `failed`, `delivered_at`, `failure_reason` | later, when its poll runs (see `action_status_updaters.md` §7) |
53
62
  | `connectedApps.updateMessageTracking` | `opened_at`, `form_submitted_at` — **never `status`** | when the recipient opens/submits the magic-link page |
54
63
 
@@ -63,17 +72,45 @@ Two consequences:
63
72
  delivered nor failed yet. A UI should show that in-between state,
64
73
  not guess.
65
74
 
75
+ ### `failed` vs `duplicate` — never retry the second
76
+
77
+ These are **not** interchangeable, and the difference decides whether
78
+ a row is safe to re-send:
79
+
80
+ | | `failed` | `duplicate` |
81
+ |---|---|---|
82
+ | provider id | none was ever returned | one came back, but another send through the same tool already holds it |
83
+ | did anything go out? | no | **yes — the send happened** |
84
+ | retryable? | yes | **no** — never retried, never re-sent |
85
+
86
+ So a "retry everything that didn't reach `delivered`" sweep is wrong:
87
+ it must select on `failed`, never on "not delivered". Re-sending a
88
+ `duplicate` sends a second real message to a recipient who already
89
+ got one.
90
+
91
+ One consequence worth internalising: **the send path never records a
92
+ message that has an `external_id` as `failed`.** Once a provider id
93
+ comes back, the row stays `pending` until the delivery poller
94
+ resolves it. `failed` therefore means "nothing left the building",
95
+ not "we don't know yet".
96
+
97
+ `invalidated` is a third, separate thing — an idempotency-key
98
+ collision rejected the fire before it went out (see `idempotency_key`
99
+ in §2). Do not read the word "duplicate" in that context as the
100
+ `duplicate` status: `invalidated` means nothing was sent,
101
+ `duplicate` means something was.
102
+
66
103
  ## 2. Fields
67
104
 
68
105
  Identity + routing:
69
106
 
70
107
  ```
71
108
  id, direction ('outbound'|'inbound'), channel ('sms'|'email'|
72
- 'voice'|'web_form'|'push'), sender_type, mdm_subject_id,
109
+ 'voice'|'web_form'|'push'), sender_type, legal_entity_id,
73
110
  thread_id, in_reply_to_id
74
111
  ```
75
112
 
76
- Content (tokenized in unregulated mode):
113
+ Content (masked in the tokenized and redacted lakes):
77
114
 
78
115
  ```
79
116
  subject, body, attachments, metadata, sender_id
@@ -97,9 +134,11 @@ Provenance (which workflow produced this):
97
134
 
98
135
  ```
99
136
  workflow_id, action_id, decision_key, context_key,
100
- idempotency_key — unique per (mdm_subject_id,
101
- idempotency_key); a duplicate fire
102
- lands as status 'invalidated'
137
+ idempotency_key — unique per (legal_entity_id,
138
+ idempotency_key); a repeat fire on the
139
+ same key lands as status 'invalidated'
140
+ (nothing sent) — NOT status 'duplicate',
141
+ which means a send did go out
103
142
  sender_tool_id
104
143
  ```
105
144
 
@@ -110,58 +149,60 @@ goes through `action_logs` (which has `batch_id` AND `external_id`)
110
149
  ## 3. Reading messages
111
150
 
112
151
  ```typescript
113
- // (1) materialise a search — WHERE fragment against alias `rm`
152
+ // (1) materialise a search — WHERE fragment against alias `m`
114
153
  // dataset type is SINGULAR 'message' (the table is plural)
115
154
  const { data: search } = await api.datasets.createUserSearch(
116
155
  tenantSlug, datalakeSlug, 'message',
117
- { search_query: `rm.status = 'failed' AND rm.channel = 'sms'` },
156
+ { search_query: `m.status = 'failed' AND m.channel = 'sms'` },
118
157
  )
119
158
  // (2) page through it
120
159
  const { data: page } = await api.datasets.search(
121
160
  tenantSlug, datalakeSlug, 'message',
122
- { userSearchId: search.id, dataAccessMode: 'unregulated' },
161
+ { userSearchId: search.id, dataAccessMode: 'tokenized' },
123
162
  )
124
163
  ```
125
164
 
126
165
  Filterable columns (Flop, the full set): `id`, `inserted_at`,
127
166
  `direction`, `channel`, `status`, `sender_type`, `body`, `subject`,
128
- `mdm_subject_id`, `sender_id`, `sent_at`, `queued_at`, `delivered_at`,
167
+ `legal_entity_id`, `sender_id`, `sent_at`, `queued_at`, `delivered_at`,
129
168
  `thread_id`, `external_id`, `global_search`.
130
169
 
131
170
  **`decision_key` is NOT in the Flop-filterable set** — you cannot
132
171
  `?filter[decision_key]=…` (nor can the workflow-run-log endpoints; see
133
172
  §4). But you CAN still scope a search by it two other ways, both
134
- cookbook-proven: put `rm.decision_key = '…'` in the `createUserSearch`
173
+ cookbook-proven: put `m.decision_key = '…'` in the `createUserSearch`
135
174
  **`search_query`** SQL WHERE fragment (as the SMS-workflow cookbooks
136
- do), or `GROUP BY rm.decision_key` in `executeSql` for analytics (§4).
175
+ do), or `GROUP BY m.decision_key` in `executeSql` for analytics (§4).
137
176
  The Flop bracket-filter and the raw-SQL surfaces are different lanes —
138
177
  `decision_key` lives only on the SQL lane.
139
178
 
140
- `dataAccessMode: 'regulated'` returns raw content; `'unregulated'`
141
- returns tokenized objects for content columns (see
142
- `data_activation_clients.md` §6.5 for the shape).
179
+ `dataAccessMode` selects which lake answers: `'raw'` returns the real
180
+ content, `'tokenized'` returns a stable `tok_<hash>` per masked column,
181
+ and `'redacted'` returns an unjoinable placeholder. All three return
182
+ **plain values of the column's own type** — a masked column is a string,
183
+ not a wrapper object.
143
184
 
144
185
  ## 4. Campaign math (the dashboard recipe)
145
186
 
146
187
  "How did campaign X do?" — where X is one run's `batch_id`:
147
188
 
148
189
  ```
149
- action_logs (ral) — has batch_id + external_id
190
+ action_logs (al) — has batch_id + external_id
150
191
  │ join on external_id
151
192
  ▼
152
- messages (rm) — has status + engagement timestamps
193
+ messages (m) — has status + engagement timestamps
153
194
  ```
154
195
 
155
196
  ```sql
156
197
  SELECT
157
198
  count(*) AS sent,
158
- count(*) FILTER (WHERE rm.status = 'delivered') AS delivered,
159
- count(*) FILTER (WHERE rm.status = 'failed') AS undelivered,
160
- count(*) FILTER (WHERE rm.opened_at IS NOT NULL) AS opened,
161
- count(*) FILTER (WHERE rm.status = 'clicked') AS clicked
162
- FROM action_logs ral
163
- JOIN messages rm ON rm.external_id = ral.external_id
164
- WHERE ral.batch_id = '<batch_id>'
199
+ count(*) FILTER (WHERE m.status = 'delivered') AS delivered,
200
+ count(*) FILTER (WHERE m.status = 'failed') AS undelivered,
201
+ count(*) FILTER (WHERE m.opened_at IS NOT NULL) AS opened,
202
+ count(*) FILTER (WHERE m.status = 'clicked') AS clicked
203
+ FROM action_logs al
204
+ JOIN messages m ON m.external_id = al.external_id
205
+ WHERE al.batch_id = '<batch_id>'
165
206
  ```
166
207
 
167
208
  Run it with `api.datalakes.executeSql` (read-only tier). Delivered
@@ -172,8 +213,8 @@ merged NDJSON artifact (see `action_logs.md` §5).
172
213
 
173
214
  ### The message log IS your per-variant analytics table
174
215
 
175
- Every message row (both the regulated and unregulated tier) carries
176
- the full provenance of the send:
216
+ Every message row, in all three lakes, carries the full provenance of
217
+ the send:
177
218
 
178
219
  ```
179
220
  decision_key which action fired — the A/B variant key
@@ -181,7 +222,7 @@ channel sms | email | voice | web_form | push
181
222
  status delivery state
182
223
  delivered_at when the carrier confirmed
183
224
  opened_at engagement (from updateMessageTracking)
184
- workflow_id, action_id, sender_tool_id, mdm_subject_id
225
+ workflow_id, action_id, sender_tool_id, legal_entity_id
185
226
  ```
186
227
 
187
228
  So "how did variant A do vs variant B?" or "SMS vs email open rate?"
@@ -190,15 +231,15 @@ is a plain `GROUP BY` over the datalake `messages` table via
190
231
 
191
232
  ```sql
192
233
  SELECT
193
- rm.decision_key,
194
- rm.channel,
234
+ m.decision_key,
235
+ m.channel,
195
236
  count(*) AS sent,
196
- count(*) FILTER (WHERE rm.status = 'delivered') AS delivered,
197
- count(*) FILTER (WHERE rm.status = 'failed') AS failed,
198
- count(*) FILTER (WHERE rm.opened_at IS NOT NULL) AS opened
199
- FROM messages rm
200
- GROUP BY rm.decision_key, rm.channel
201
- ORDER BY rm.decision_key, rm.channel
237
+ count(*) FILTER (WHERE m.status = 'delivered') AS delivered,
238
+ count(*) FILTER (WHERE m.status = 'failed') AS failed,
239
+ count(*) FILTER (WHERE m.opened_at IS NOT NULL) AS opened
240
+ FROM messages m
241
+ GROUP BY m.decision_key, m.channel
242
+ ORDER BY m.decision_key, m.channel
202
243
  ```
203
244
 
204
245
  Scope it to one campaign run by joining `action_logs` (which carries
@@ -243,7 +284,7 @@ per-channel reporting.
243
284
  `opened_at` from an earlier attempt in the thread — read both.
244
285
 
245
286
  4. **`status: 'invalidated'` is the idempotency guard firing** —
246
- the same `(mdm_subject_id, idempotency_key)` already sent. Not
287
+ the same `(legal_entity_id, idempotency_key)` already sent. Not
247
288
  an error; usually exactly what you want.
248
289
 
249
290
  5. **Delivery events that don't match are dropped silently.** The
@@ -0,0 +1,192 @@
1
+ # Mock Services
2
+
3
+ <!-- MDOC !-->
4
+
5
+ How the platform reaches mocked third-party APIs, on a laptop and from deployed
6
+ environments. Two mock surfaces exist and they answer different questions:
7
+ **WireMock** stands in for third-party SaaS APIs, **LocalStack** stands in for AWS.
8
+
9
+ ## The two surfaces
10
+
11
+ **WireMock** (`wiremock/wiremock:3.10.0`) serves the stub corpus in
12
+ `wm_mappings/`, with response bodies in `wm_response_files/`. It covers the
13
+ third-party APIs the platform integrates with — Athenahealth, Twilio, Mailgun,
14
+ Stripe, SendGrid, HubSpot, QuickBooks, Airtable, Atomic FI, the LLM providers,
15
+ and a small set of AWS endpoints LocalStack cannot serve.
16
+
17
+ **LocalStack** serves AWS itself: `s3,lambda,sns,ssm,sqs,sts,logs,secretsmanager,cloudformation`
18
+ (`local-dependencies.yml`). See [Datalakes](datalakes.md) for how datalake
19
+ provisioning uses it.
20
+
21
+ The division is not arbitrary. LocalStack Community **cannot** serve
22
+ `pinpoint-sms-voice-v2` (501 — Ultimate tier only), so End User Messaging points
23
+ at WireMock for its send, its S3 media staging, and its STS credential probe. A
24
+ tool has one `endpoint_url`, so all three land on the same host.
25
+
26
+ ## The corpus
27
+
28
+ Counted on `release/0.23.0` — 16 files, 98 stubs. The feature mix is what makes
29
+ WireMock itself load-bearing rather than incidental:
30
+
31
+ | Feature | Uses | What it does |
32
+ |---|---:|---|
33
+ | `urlPathPattern` | 80 | Regex path matching |
34
+ | `jsonBody` / `body` / `base64Body` | 85 | Inline response bodies |
35
+ | `bodyFileName` | 21 | Bodies served from `wm_response_files/` |
36
+ | `bodyPatterns` | 11 | Request-body matching |
37
+ | `queryParameters` | 9 | Query matching |
38
+ | `scenarioName` + `newScenarioState` | 7 | **Stateful scenarios — a state machine across requests** |
39
+ | `--global-response-templating` | on | Handlebars templating in responses |
40
+
41
+ The last two rows are why the corpus is served by the real WireMock image
42
+ everywhere rather than by a bespoke matcher. Reimplementing stateful scenarios
43
+ and a templating engine means re-earning fidelity, and a gap in a mock surfaces
44
+ as a test passing against a fiction rather than as a failure.
45
+
46
+ ### Two gotchas that cost real time
47
+
48
+ **WireMock rejects unknown keys on a stub mapping.** A stray `_comment` field
49
+ makes it refuse to load the *whole file* and 404 everything in it, while
50
+ `json.load` and any JSON linter pass it happily. Put prose in the free-form
51
+ `metadata` object instead.
52
+
53
+ **WireMock loads mappings at boot.** After editing `wm_mappings/`, reload the
54
+ local container without restarting it:
55
+
56
+ ```bash
57
+ curl -X POST http://localhost:8080/__admin/mappings/reset
58
+ ```
59
+
60
+ That is the first thing to try when a stub 404s locally. It is not available on
61
+ the hosted instance — see below.
62
+
63
+ ## Running locally
64
+
65
+ `make run-backing-services` starts both. WireMock listens on `:8080`, LocalStack
66
+ on `:4566`. Tool bodies reach them by setting `endpoint_url` — blank means real
67
+ AWS, any value replaces host, port and scheme.
68
+
69
+ LocalStack's S3 state does **not** survive a container restart. Recreate a bucket
70
+ after one:
71
+
72
+ ```bash
73
+ AWS_ACCESS_KEY_ID=test AWS_SECRET_ACCESS_KEY=test AWS_DEFAULT_REGION=us-east-1 \
74
+ aws s3 mb s3://healthcare-lake --endpoint-url http://localhost:4566
75
+ ```
76
+
77
+ ## The hosted mock — `wiremock.alvera.ai`
78
+
79
+ Deployed environments used to need their own always-on WireMock, which is the
80
+ wrong billing shape for a service that is idle almost all of the time. The corpus
81
+ now runs on Cloudflare Containers behind one hostname, billed only while awake.
82
+
83
+ ```mermaid
84
+ flowchart TD
85
+ C["Consumers<br/>platform dev · UAT · integration-tests · CI"]
86
+ C -->|"https://wiremock.alvera.ai"| W
87
+
88
+ subgraph CF["Cloudflare"]
89
+ F["WAF custom rule<br/>/__admin → Block"]
90
+ W["Worker + Durable Object<br/>container binding"]
91
+ K["Container — basic<br/>wiremock/wiremock:3.10.0<br/>/mappings ◀ wm_mappings/<br/>/__files ◀ wm_response_files/"]
92
+ F -.->|"blocks before the Worker runs"| W
93
+ W -->|fetch| K
94
+ end
95
+ ```
96
+
97
+ **It lives in this repo**, at `mock-edge/`. Deploy from a normal checkout:
98
+
99
+ ```bash
100
+ cd mock-edge && wrangler deploy
101
+ ```
102
+
103
+ The single line that makes this work without a vendored copy of the corpus:
104
+
105
+ ```jsonc
106
+ "image_build_context": ".."
107
+ ```
108
+
109
+ That sets the Docker build context to the repo root, so the Dockerfile copies
110
+ `wm_mappings/` and `wm_response_files/` from where they already live. Without it
111
+ the context is `mock-edge/` and the corpus would have to be duplicated there —
112
+ two directories that look identical until they quietly aren't.
113
+
114
+ ### There is no authentication
115
+
116
+ The hostname is public and deliberately so. The corpus is synthetic fixture data,
117
+ the mock authenticates nobody, and a gate in front of it caused more problems
118
+ than it solved:
119
+
120
+ - Nineteen of the 98 stubs match on the `Authorization` header, because they
121
+ assert the *tool* authenticated to the API being mocked. Cloudflare Access
122
+ consumes `Authorization` for its own credential, so gating on that header made
123
+ those nineteen stubs stop matching.
124
+ - Any gate means a credential per consumer, which means minting, distributing,
125
+ rotating and revoking — for a service whose contents are fixtures.
126
+
127
+ The accepted risk is bot traffic waking the container. Workers include 10 million
128
+ requests a month before any charge, so the exposure is container time, not
129
+ request volume — and it is small enough to deal with if it ever shows up.
130
+
131
+ ### The admin API is blocked
132
+
133
+ WireMock's admin API has no authentication of its own: anything that can reach
134
+ `/__admin` can read the request journal, reset scenarios, or reprogram stubs.
135
+ Publicly hosted, that surfaces as CI failing for no visible reason. A WAF custom
136
+ rule on the zone refuses it:
137
+
138
+ ```
139
+ (http.host eq "wiremock.alvera.ai" and http.request.uri.path contains "/__admin") → Block
140
+ ```
141
+
142
+ Scoped by `http.host` so it cannot affect the other services on `alvera.ai`.
143
+ Cloudflare normalises the URL before evaluating rules, so `/%5f%5fadmin` and
144
+ `//__admin` are blocked too — verified, not assumed.
145
+
146
+ > #### The block is safe *because* the corpus is baked {: .warning}
147
+ >
148
+ > Stubs live in the image. Nothing registers them at runtime, so nothing needs
149
+ > the admin API in production. **If that ever changes — if an app wants to
150
+ > register stubs at runtime — this rule must be reconsidered, not worked
151
+ > around.** It would also need `max_instances: 1` and a fixed container name,
152
+ > because registrations do not survive an instance sleeping or a request landing
153
+ > on a different instance.
154
+
155
+ ### Adding or changing a stub
156
+
157
+ Edit `wm_mappings/` (or `wm_response_files/`), then redeploy. There is no hot
158
+ reload on the hosted instance — the image is the state, which makes the hosted
159
+ mock immutable per deploy and reproducible for CI.
160
+
161
+ ### Verifying the hosted mock matches local
162
+
163
+ The failure worth catching is the two environments quietly disagreeing. Compare
164
+ them by hashing responses rather than asserting content, so the check does not
165
+ break when someone edits a stub — only when local and edge diverge:
166
+
167
+ ```bash
168
+ for base in http://localhost:8080 https://wiremock.alvera.ai; do
169
+ curl -s -X POST -H 'content-type: application/json' -d '{"contents":[]}' \
170
+ "$base/gemini/v1beta/models/gemini-2.0-flash:generateContent" | shasum -a 256
171
+ done
172
+ ```
173
+
174
+ The gemini stubs are the sharpest test: they use a seven-state scenario, so three
175
+ identical POSTs return three *different* bodies in a fixed order. Matching hashes
176
+ across three successive calls proves both environments walked the same state
177
+ machine — something no stateless matcher could fake.
178
+
179
+ ## LocalStack at the edge
180
+
181
+ Not done, and deliberately scoped apart. LocalStack is also just an image and
182
+ rides the same mechanism, but Containers **sleep by design** and LocalStack's S3
183
+ state already does not survive a restart. What is an occasional annoyance locally
184
+ becomes routine when instances sleep between runs. Anything depending on objects
185
+ persisting must move to R2, which speaks S3 natively — migration work, not a flag
186
+ flip.
187
+
188
+ ## Related
189
+
190
+ - [Tools](tools.md) — tool bodies, `endpoint_url`, and REST API auth methods
191
+ - [Datalakes](datalakes.md) — how datalake provisioning uses LocalStack
192
+ - [Connected Apps](connected_apps.md) — the third-party integrations the corpus stands in for
@@ -37,9 +37,9 @@ const { data: current } = await api.tools.get(
37
37
  // 2. change in memory
38
38
  const next = { ...current, status: 'inactive' }
39
39
 
40
- // 3. send the whole body back
40
+ // 3. send the whole body back. The cast is required — see below.
41
41
  const { data: updated } = await api.tools.update(
42
- tenantSlug, datalakeSlug, toolId, next,
42
+ tenantSlug, datalakeSlug, toolId, next as unknown as ToolRequestWritable,
43
43
  )
44
44
  ```
45
45
 
@@ -4,9 +4,8 @@ Templates are an **INFRASTRUCTURE** building block: the platform
4
4
  ships a library of Liquid templates that other infrastructure
5
5
  resources consume — interoperability contracts, AI agent prompts,
6
6
  workflow definitions, status poller bodies. Templates are
7
- **read-only** from the SDK; the platform composes them
8
- per-industry, and each datalake's `data_domain` selects which
9
- surface in its catalog.
7
+ **read-only** from the SDK — they ship with the platform and a
8
+ datalake's catalog is whatever the platform exposes to it.
10
9
 
11
10
  SDK namespace: `api.templates`.
12
11
 
@@ -21,14 +20,15 @@ Three discovery methods, two complementary response shapes —
21
20
  structured (for code) and markdown (for agents):
22
21
 
23
22
  ```typescript
24
- import type { SystemTemplate } from '@alvera-ai/platform-sdk'
23
+ // The systemTemplates catalog response has no exported type on the
24
+ // public surface yet — `catalog` is inferred from the call.
25
25
 
26
26
  // Structured catalog
27
27
  const { data: catalog } = await api.templates.systemTemplates(
28
28
  tenantSlug,
29
29
  datalakeSlug,
30
30
  )
31
- // catalog.data: SystemTemplate[] — the full in-scope list, NOT paginated
31
+ // catalog.data — the full in-scope list, NOT paginated
32
32
  // { path, content, output_schema }
33
33
  // path category/sub-category/name segment string
34
34
  // content Liquid template body
@@ -59,10 +59,12 @@ const { data: templateMd } = await api.templates.metadataDetails(
59
59
  Template paths follow `<category>/<sub-category>/<name>`.
60
60
  Categories the SDK exposes include
61
61
  `data_activation/interoperability/`, `ai_agents/`, `workflows/`,
62
- `status_poller/`. Categories with an industry segment (e.g.
63
- `ai_agents/<industry>/*`) filter to the datalake's `data_domain`;
64
- categories without (e.g. `status_poller/*/*`) are globals
65
- present in every catalog.
62
+ `status_poller/`. Path segments below the category are platform-owned and have
63
+ outlived at least one naming scheme, so **discover paths via
64
+ `api.templates` rather than constructing them.** The
65
+ `data_domain` filter that used to select a datalake's slice of
66
+ the catalog was removed with GH-859; what remains is
67
+ server-decided.
66
68
 
67
69
  ## 3. Lifecycle
68
70
 
@@ -84,10 +86,9 @@ trying to add to the catalog.
84
86
  `'data_activation_interoperability'`). Check the typed
85
87
  parameter for the valid set; multiple templates can share a
86
88
  basename across intents. Within a single intent, the basename
87
- must resolve uniquely under its `<intent>+<data_domain>`
88
- prefix — if two sub-directories under that prefix ship the same
89
- basename (e.g. two vendors under
90
- `data_activation/interoperability/<industry>/`),
89
+ must resolve uniquely under its `<intent>` prefix — if two
90
+ sub-directories under that prefix ship the same basename (e.g.
91
+ two vendors under `data_activation/interoperability/`),
91
92
  `metadataDetails` returns `409 Conflict` with the candidate
92
93
  paths; a missing basename returns `404`.
93
94