@alvera-ai/platform-sdk 0.10.0-rc.8 → 0.11.0

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 (66) hide show
  1. package/.agent/AGENTS.md +499 -0
  2. package/.agent/account_management.md +456 -0
  3. package/.agent/action_status_updaters.md +264 -0
  4. package/.agent/ai_agents.md +462 -0
  5. package/.agent/ai_sandbox.md +265 -0
  6. package/.agent/async.md +112 -0
  7. package/.agent/connected_apps.md +408 -0
  8. package/.agent/cookbook/_fixtures/README.md +106 -0
  9. package/.agent/cookbook/_fixtures/accounts_receivable/_customers_accounts_receivable_customer.liquid +32 -0
  10. package/.agent/cookbook/_fixtures/accounts_receivable/_customers_accounts_receivable_mdm.liquid +20 -0
  11. package/.agent/cookbook/_fixtures/accounts_receivable/stripe_customers_batch1.csv +5 -0
  12. package/.agent/cookbook/_fixtures/foundation/_lead_submissions_foundation_generic_table.liquid +33 -0
  13. package/.agent/cookbook/_fixtures/foundation/_lead_submissions_foundation_legal_entity.liquid +88 -0
  14. package/.agent/cookbook/_fixtures/foundation/_lead_submissions_foundation_mdm.liquid +48 -0
  15. package/.agent/cookbook/_fixtures/healthcare/_cahps_appointments_healthcare_appointment.liquid +47 -0
  16. package/.agent/cookbook/_fixtures/healthcare/_cahps_appointments_healthcare_mdm.liquid +24 -0
  17. package/.agent/cookbook/_fixtures/healthcare/_cahps_appointments_healthcare_patient.liquid +38 -0
  18. package/.agent/cookbook/_fixtures/healthcare/memorandum-of-association-01.png +0 -0
  19. package/.agent/cookbook/_fixtures/healthcare/sample_two_page.pdf +43 -0
  20. package/.agent/cookbook/_fixtures/payment_risk/_compliance_screenings_payment_risk_compliance_screening.liquid +59 -0
  21. package/.agent/cookbook/_fixtures/payment_risk/_compliance_screenings_payment_risk_mdm.liquid +36 -0
  22. package/.agent/cookbook/_fixtures/payment_risk/_payment_accounts_payment_risk_mdm.liquid +30 -0
  23. package/.agent/cookbook/_fixtures/payment_risk/_payment_accounts_payment_risk_payment_account.liquid +55 -0
  24. package/.agent/cookbook/_setup/accounts_receivable.md +282 -0
  25. package/.agent/cookbook/_setup/foundation.md +277 -0
  26. package/.agent/cookbook/_setup/healthcare.md +279 -0
  27. package/.agent/cookbook/_setup/payment_risk.md +283 -0
  28. package/.agent/cookbook/action-status-updaters.md +212 -0
  29. package/.agent/cookbook/ai-agent-invoke.md +243 -0
  30. package/.agent/cookbook/appointment-review-sms-workflow.md +761 -0
  31. package/.agent/cookbook/birthday-greeting-sms-trigger.md +656 -0
  32. package/.agent/cookbook/bulk-ingest.md +254 -0
  33. package/.agent/cookbook/contact-us-triage-with-llm.md +622 -0
  34. package/.agent/cookbook/custom-tables.md +201 -0
  35. package/.agent/cookbook/dunning-sms-for-delinquent.md +619 -0
  36. package/.agent/cookbook/invite-team.md +194 -0
  37. package/.agent/cookbook/kyc-notification-on-account-activation.md +619 -0
  38. package/.agent/cookbook/rest-fetch.md +246 -0
  39. package/.agent/cookbook/sanctions-screening-with-agent-review.md +733 -0
  40. package/.agent/cookbook/score-leads-with-llm-categorization.md +624 -0
  41. package/.agent/cookbook/system-templates.md +129 -0
  42. package/.agent/cookbook/triage-prospects-by-priority.md +533 -0
  43. package/.agent/cookbook/welcome-sms-for-customers.md +607 -0
  44. package/.agent/data_activation_clients.md +559 -0
  45. package/.agent/data_sources.md +235 -0
  46. package/.agent/datalakes.md +714 -0
  47. package/.agent/debugging.md +137 -0
  48. package/.agent/errors.md +190 -0
  49. package/.agent/generic_tables.md +351 -0
  50. package/.agent/interoperability_contracts.md +417 -0
  51. package/.agent/mdm.md +293 -0
  52. package/.agent/mutations.md +126 -0
  53. package/.agent/templates.md +98 -0
  54. package/.agent/tool-call-configs.md +90 -0
  55. package/.agent/tools.md +547 -0
  56. package/.agent/type_naming.md +129 -0
  57. package/.agent/workflows.md +617 -0
  58. package/README.md +178 -0
  59. package/dist/bin/platform-sdk.d.mts +1 -0
  60. package/dist/bin/platform-sdk.mjs +106 -0
  61. package/dist/bin/platform-sdk.mjs.map +1 -0
  62. package/dist/index.d.mts +1310 -44116
  63. package/dist/index.d.mts.map +1 -1
  64. package/dist/index.mjs +1194 -7344
  65. package/dist/index.mjs.map +1 -1
  66. package/package.json +19 -10
@@ -0,0 +1,714 @@
1
+ # Datalakes
2
+
3
+ A **datalake** is the storage layer for one tenant slice. It holds
4
+ two databases under one roof:
5
+
6
+ - an **unregulated** database for tokenized data, exposed to AI
7
+ workflows and downstream agents
8
+ - a **regulated** database for raw values that never leave the
9
+ trust boundary
10
+
11
+ Every other resource in the platform (data sources, tools, AI
12
+ agents, workflows, etc.) scopes under a datalake. A tenant can own
13
+ many datalakes; the canonical pattern is one per data domain (e.g.
14
+ `healthcare`, `foundation`, `payment_risk`).
15
+
16
+ ```typescript
17
+ import type { PlatformApi } from '@alvera-ai/platform-sdk'
18
+
19
+ const api: PlatformApi = /* see AGENTS.md */
20
+ const { data: created } = await api.datalakes.create(tenantSlug, body)
21
+ const datalakeSlug = created.slug // canonical — use for downstream scoping
22
+ ```
23
+
24
+ SDK namespace: `api.datalakes`.
25
+
26
+ ## 1. Wire shape
27
+
28
+ The request type splits across two layers: top-level database +
29
+ identity fields, plus two polymorphic cloud-storage embeds.
30
+
31
+ ```typescript
32
+ import type {
33
+ DatalakeRequestWritable,
34
+ DatalakeResponse,
35
+ } from '@alvera-ai/platform-sdk'
36
+ ```
37
+
38
+ See `type_naming.md` for the `Writable` convention and the
39
+ universal server-derived field set. (The SDK exports types only —
40
+ there is no runtime validator; validation is server-authoritative.)
41
+
42
+ ### Polymorphic cloud-storage embed
43
+
44
+ `unregulated_cloud_storage` and `regulated_cloud_storage` are
45
+ polymorphic. The discriminator field is **`cloud_storage_type`**
46
+ (see `mutations.md` "Polymorphic discriminator naming") with three
47
+ branches:
48
+
49
+ | `cloud_storage_type` | TypeScript branch |
50
+ |----------------------|-----------------------------------------|
51
+ | `"aws"` | `DatalakeCloudStorageAwsRequest` |
52
+ | `"r2"` | `DatalakeCloudStorageR2Request` |
53
+ | `"custom"` | `DatalakeCloudStorageCustomRequest` |
54
+
55
+ Each branch carries its own field set; the shared keys are
56
+ `bucket`, `region`, `access_key_id`, `secret_access_key`. `custom`
57
+ adds `endpoint` (used for LocalStack and self-hosted S3-compatible
58
+ stores).
59
+
60
+ The `aws` branch also carries an `auth_method` field —
61
+ `"access_key"` (default) or `"iam_role"` — that pairs with the
62
+ credentials the same way the DB-profile `auth_method` does. See
63
+ §2 "AWS cloud-storage `auth_method = iam_role` forbids
64
+ credentials" for the conditional the type cannot encode.
65
+
66
+ The two embeds are independent — a datalake can pair an `aws`
67
+ unregulated bucket with a `custom` regulated bucket. Both embeds
68
+ ship in the same POST/PUT body.
69
+
70
+ ### Cloud storage is also the cold-archive destination
71
+
72
+ Beyond being the platform's primary blob store for inline payloads
73
+ (image uploads, large context payloads, presigned-URL ingest), the
74
+ configured `regulated_cloud_storage` and `unregulated_cloud_storage`
75
+ buckets are the **cold-archive destination** for the datalake. As
76
+ data flows through the pipeline, two NDJSON streams land under
77
+ well-defined key prefixes inside the bucket the credentials point at:
78
+
79
+ ```
80
+ {datalake_slug}/data-activations/{client_slug}/{batch_id}/{dataset_table}.ndjson
81
+ {datalake_slug}/workflows/{wf_slug}/{batch_id}/merged.ndjson
82
+ {datalake_slug}/workflows/{wf_slug}/{batch_id}/{decision_key}/merged.ndjson
83
+ ```
84
+
85
+ The merged NDJSONs are produced by background jobs
86
+ after each Data Activation Client batch and each workflow run
87
+ completes. The platform never streams the merged bytes through its
88
+ own process — the merge happens via DuckDB's `httpfs` extension
89
+ operating directly against the bucket.
90
+
91
+ The same DuckDB-over-`httpfs` pattern is available to **consumers**
92
+ for cold-data analytics. With the datalake's cloud-storage
93
+ credentials (or a separately-provisioned reader key on the same
94
+ bucket), an external DuckDB process can read the archived NDJSONs
95
+ directly:
96
+
97
+ ```sql
98
+ INSTALL httpfs; LOAD httpfs;
99
+ CREATE OR REPLACE SECRET (TYPE S3, KEY_ID '...', SECRET '...', ENDPOINT '...');
100
+ SELECT * FROM read_ndjson_auto(
101
+ 's3://{bucket}/{datalake_slug}/data-activations/{client_slug}/*/{dataset_table}.ndjson'
102
+ );
103
+ ```
104
+
105
+ The platform does NOT expose a query API over the archive itself —
106
+ cold reads happen externally so the platform's processes aren't
107
+ responsible for analytical workloads. Live data lives in the
108
+ datalake's Postgres halves (queryable via the dataset search
109
+ two-step pattern in `data_activation_clients.md` §6.5); historical
110
+ data lives in the cloud-storage buckets configured here.
111
+
112
+ ### Canonical create body
113
+
114
+ Paste-ready TypeScript body. The four database-role groups
115
+ (unregulated writer + reader, regulated writer + reader) share
116
+ an identical eight-field shape; the type lists all 32 explicitly
117
+ with no role-level union:
118
+
119
+ ```typescript
120
+ import type { DatalakeRequestWritable } from '@alvera-ai/platform-sdk'
121
+
122
+ // Pick one of four supported industries. The body shape below is
123
+ // identical across them; only `data_domain` and the names it
124
+ // interpolates differ.
125
+ const dataDomain = 'healthcare'
126
+ // ^ swap to 'foundation' | 'accounts_receivable' | 'payment_risk'
127
+
128
+ // Secrets resolved upstream by your code (secret store, config loader, etc.)
129
+ const pgHost = '...'
130
+ const pgUser = '...'
131
+ const pgPass = '...'
132
+ const pgReaderHost = '...'
133
+ const pgReaderUser = '...'
134
+ const pgReaderPass = '...'
135
+ const awsAccessKeyId = '...'
136
+ const awsSecretAccessKey = '...'
137
+
138
+ const body: DatalakeRequestWritable = {
139
+ name: 'Production Lake',
140
+ description: `Primary ${dataDomain} datalake`,
141
+ data_domain: dataDomain,
142
+ timezone: 'America/New_York',
143
+ pool_size: 5,
144
+
145
+ unregulated_db_writer_host: pgHost,
146
+ unregulated_db_writer_port: 5432,
147
+ unregulated_db_writer_name: `alvera_${dataDomain}`,
148
+ unregulated_db_writer_schema: 'tenant_acme_unreg',
149
+ unregulated_db_writer_auth_method: 'password',
150
+ unregulated_db_writer_user: pgUser,
151
+ unregulated_db_writer_pass: pgPass,
152
+ unregulated_db_writer_enable_ssl: true,
153
+ unregulated_db_reader_host: pgReaderHost,
154
+ unregulated_db_reader_port: 5432,
155
+ unregulated_db_reader_name: `alvera_${dataDomain}`,
156
+ unregulated_db_reader_schema: 'tenant_acme_unreg',
157
+ unregulated_db_reader_auth_method: 'password',
158
+ unregulated_db_reader_user: pgReaderUser,
159
+ unregulated_db_reader_pass: pgReaderPass,
160
+ unregulated_db_reader_enable_ssl: true,
161
+
162
+ regulated_data_db_writer_host: pgHost,
163
+ regulated_data_db_writer_port: 5432,
164
+ regulated_data_db_writer_name: `alvera_${dataDomain}`,
165
+ regulated_data_db_writer_schema: 'tenant_acme_reg',
166
+ regulated_data_db_writer_auth_method: 'password',
167
+ regulated_data_db_writer_user: pgUser,
168
+ regulated_data_db_writer_pass: pgPass,
169
+ regulated_data_db_writer_enable_ssl: true,
170
+ regulated_data_db_reader_host: pgReaderHost,
171
+ regulated_data_db_reader_port: 5432,
172
+ regulated_data_db_reader_name: `alvera_${dataDomain}`,
173
+ regulated_data_db_reader_schema: 'tenant_acme_reg',
174
+ regulated_data_db_reader_auth_method: 'password',
175
+ regulated_data_db_reader_user: pgReaderUser,
176
+ regulated_data_db_reader_pass: pgReaderPass,
177
+ regulated_data_db_reader_enable_ssl: true,
178
+
179
+ unregulated_cloud_storage: {
180
+ cloud_storage_type: 'aws',
181
+ region: 'us-east-1',
182
+ bucket: `acme-${dataDomain}-unregulated`,
183
+ access_key_id: awsAccessKeyId,
184
+ secret_access_key: awsSecretAccessKey,
185
+ },
186
+ regulated_cloud_storage: {
187
+ cloud_storage_type: 'aws',
188
+ region: 'us-east-1',
189
+ bucket: `acme-${dataDomain}-regulated`,
190
+ access_key_id: awsAccessKeyId,
191
+ secret_access_key: awsSecretAccessKey,
192
+ },
193
+ }
194
+
195
+ const { data: created } = await api.datalakes.create(tenantSlug, body)
196
+ // created.id, created.slug — server-derived; use slug for downstream scoping
197
+ // created.status === 'new' — migration NOT yet started; see §5 Lifecycle
198
+ ```
199
+
200
+ ## 2. Rules the type cannot encode
201
+
202
+ ### `auth_method = "iam_role"` relaxes the password requirement
203
+
204
+ All eight `*_pass` fields are typed as required strings. When a
205
+ role's `auth_method` is `"iam_role"`, its matching `*_pass` value
206
+ is **server-cleared at write time** — the value submitted is
207
+ ignored. The typed validator does not encode this conditional, so
208
+ the field is still structurally required.
209
+
210
+ The convention is to supply a sentinel literal (e.g.
211
+ `"unused-iam-role"`) so a reviewer sees intent. **Real credentials
212
+ do not belong in this slot** — the value never leaves the
213
+ validator.
214
+
215
+ ### AWS cloud-storage `auth_method = iam_role` forbids credentials
216
+
217
+ Mirrors the DB `auth_method` rule above but with the **opposite
218
+ disposition** on the credential fields. Inside an AWS cloud-storage
219
+ embed:
220
+
221
+ - `auth_method: "access_key"` (default) — `access_key_id` and
222
+ `secret_access_key` are **required**.
223
+ - `auth_method: "iam_role"` — `access_key_id` and
224
+ `secret_access_key` MUST be omitted. Supplying either yields a
225
+ field-level rejection at create. Unlike the DB case, the values
226
+ are NOT silently server-cleared — the platform treats their
227
+ presence as a configuration conflict.
228
+
229
+ The two embeds (`unregulated_cloud_storage` and
230
+ `regulated_cloud_storage`) are validated independently, so a body
231
+ can pair `iam_role` on one side with `access_key` on the other.
232
+
233
+ ### Database identifiers follow strict format rules
234
+
235
+ The four `*_db_*_schema` and four `*_db_*_name` fields must be
236
+ lowercase identifiers (letters, digits, underscore) — uppercase
237
+ letters and dashes are rejected with a `/<role>_schema` or
238
+ `/<role>_name` pointer. The eight `*_db_*_host` fields must match
239
+ a hostname pattern; values like `"invalid_host!"` (with
240
+ non-hostname punctuation) are rejected.
241
+
242
+ This is the only field-format constraint surfaced before the
243
+ synchronous reachability probe runs (see §6 Gotcha 9) — a
244
+ malformed identifier never gets as far as a connection attempt.
245
+
246
+ ### Schema names must be unique within a database
247
+
248
+ `*_db_*_schema` fields name the PostgreSQL schema the platform
249
+ creates inside the target database. Sibling datalakes sharing a
250
+ `*_db_*_name` (same physical database) **must** use distinct
251
+ schema values. Collision produces a 422 at create time.
252
+
253
+ The reader and writer for the same role typically share a schema
254
+ (they're two connection profiles into the same logical schema);
255
+ unregulated and regulated must not (different trust boundaries).
256
+
257
+ ### The discriminator can't change on `update()`
258
+
259
+ Per `mutations.md`, `cloud_storage_type` on update must match the
260
+ existing row's discriminator. To change the embed type (e.g. `aws`
261
+ → `r2`), `delete()` and `create()` fresh — you can't change body
262
+ type on `update()`.
263
+
264
+ ### `data_domain` is a closed enum
265
+
266
+ Industry values are enumerated in the OpenAPI spec
267
+ (`DatalakeDataDomain`); the SDK exports them as a const-style
268
+ value (see `type_naming.md` "Enum types"). The enum drifts as
269
+ new industries land — consult the SDK's `DatalakeDataDomain`
270
+ const for the live set rather than hardcoding values.
271
+
272
+ ## 3. Field ownership
273
+
274
+ Datalake's fields split across three POV-relevant categories —
275
+ distinguishing them by whether they round-trip determines how a
276
+ consumer constructs the PUT body (see §5 Update).
277
+
278
+ **Server-derived (Response-only).** The universal set (`id`,
279
+ `slug`, `created_at`, `updated_at`, `status`, `status_reason`)
280
+ is documented in `type_naming.md`. Datalake adds no extras here
281
+ — but the `status` field has a richer lifecycle than most
282
+ resources (see §5).
283
+
284
+ **Caller-supplied (round-trip).** Present on both
285
+ `DatalakeRequestWritable` and `DatalakeResponse`:
286
+
287
+ ```
288
+ identification name, description, data_domain
289
+ global settings timezone, pool_size
290
+ db profiles (×4) <role>_{host, port, name, schema, user,
291
+ auth_method, enable_ssl}
292
+ cloud storage (×2) <role>_cloud_storage.{cloud_storage_type,
293
+ bucket, region,
294
+ + branch-specific
295
+ fields per §1}
296
+ ```
297
+
298
+ **Write-only (Request-only).** Present on
299
+ `DatalakeRequestWritable`, absent from `DatalakeResponse`. The
300
+ consumer must re-supply these on every PUT from their secret
301
+ store (see §5 Update for the canonical pattern):
302
+
303
+ ```
304
+ db credentials (×4) unregulated_db_writer_pass
305
+ unregulated_db_reader_pass
306
+ regulated_data_db_writer_pass
307
+ regulated_data_db_reader_pass
308
+
309
+ cloud storage unregulated_cloud_storage.access_key_id
310
+ credentials (×4) unregulated_cloud_storage.secret_access_key
311
+ regulated_cloud_storage.access_key_id
312
+ regulated_cloud_storage.secret_access_key
313
+ ```
314
+
315
+ The `slug` returned in the Response is the canonical reference
316
+ for all downstream scoping. Never pre-compute it client-side —
317
+ see `type_naming.md` "Never pre-compute the slug client-side".
318
+
319
+ ## 4. Error envelopes
320
+
321
+ The platform returns a standardized JSON:API envelope — see
322
+ `errors.md` for the canonical shape (`{ errors: [{ source:
323
+ { pointer }, title, detail }, ...] }`) and the two-layer
324
+ validation model (structural cast → server-side semantic check).
325
+
326
+ All validation errors come back from the server as a thrown 422
327
+ `AlveraApiError` (the SDK does not validate client-side). See
328
+ `errors.md` for the typed narrowing pattern.
329
+
330
+ Datalake-specific common rejections:
331
+
332
+ | `source.pointer` | Typical cause |
333
+ |-------------------------------------------------|------------------------------------------------------|
334
+ | `/name` | name collision within tenant (uniqueness) |
335
+ | `/data_domain` | value not in the live enum |
336
+ | `/unregulated_cloud_storage/cloud_storage_type` | discriminator value doesn't match any oneOf branch |
337
+ | `/unregulated_db_writer_schema` | schema-name collision within the target DB; or identifier format violation (uppercase / dash) |
338
+ | `/unregulated_db_writer_name` | identifier format violation |
339
+ | `/unregulated_db_writer_host` | hostname format violation, OR synchronous probe could not reach the host |
340
+ | `/unregulated_cloud_storage` | synchronous probe could not reach the bucket with the supplied credentials |
341
+ | `/unregulated_cloud_storage/access_key_id` | supplied under `auth_method: "iam_role"` (must be omitted) |
342
+ | `/pool_size` | out of the inclusive range 1–50 |
343
+ | `/timezone` | not a valid IANA timezone identifier |
344
+
345
+ For polymorphic embeds, the `cloud_storage_type` value is the
346
+ first thing to inspect — it routes downstream field validation to
347
+ one of the three branches.
348
+
349
+ ## 5. Lifecycle
350
+
351
+ Datalakes have the richest lifecycle of any platform resource.
352
+ The status enum (wire-level values):
353
+
354
+ ```
355
+ new POST returned; migration not yet started
356
+ processing platform provisioning the per-datalake schemas and
357
+ supporting infrastructure
358
+ ready both DBs migrated; downstream Datalake-DB-resident
359
+ resources can be created
360
+ ```
361
+
362
+ The platform console UI renders `processing` as the label
363
+ "Migrating..." — the wire-level enum value is `processing`.
364
+ Code that switches on status MUST use the wire values, not the
365
+ UI labels.
366
+
367
+ The status enum has NO terminal failure value. If a migration
368
+ fails, the datalake remains in `processing` (or `new` if it
369
+ never started); failures surface in the admin console's Migration
370
+ Logs view, which is not exposed over the SDK. Consumers polling
371
+ for readiness must therefore rely on a sensible timeout — see §5.
372
+
373
+ ### Create
374
+
375
+ ```typescript
376
+ const { data: created } = await api.datalakes.create(tenantSlug, body)
377
+ // created.status === 'new'
378
+ // created.slug === '<server-derived>'
379
+ ```
380
+
381
+ `create()` returns immediately with `status: "new"`. **Migration is
382
+ not auto-enqueued** — the caller explicitly invokes it.
383
+
384
+ ### Migrate (explicit, async)
385
+
386
+ ```typescript
387
+ const { data: enqueued } = await api.datalakes.migrate(
388
+ tenantSlug,
389
+ created.slug,
390
+ )
391
+ // enqueued.status === 'enqueued'
392
+ // enqueued.job_id === <number>
393
+ // enqueued.datalake_id === created.id
394
+ ```
395
+
396
+ `api.datalakes.migrate(...)` enqueues the schema-creation job. The
397
+ response is the *job acknowledgement* (`status: "enqueued"`), NOT
398
+ the datalake row — it carries `job_id` + `datalake_id` +
399
+ `enqueued_at` only. To learn the datalake's live status, GET
400
+ separately:
401
+
402
+ ```typescript
403
+ const { data: dl } = await api.datalakes.get(tenantSlug, created.slug)
404
+ // dl.status === 'new' | 'processing' | 'ready'
405
+ ```
406
+
407
+ Use the canonical `waitUntilReady` from `async.md`:
408
+
409
+ ```typescript
410
+ const dl = await waitUntilReady(
411
+ () => api.datalakes.get(tenantSlug, created.slug),
412
+ (status) => status === 'ready' ? 'ready' : 'pending',
413
+ { intervalMs: 15_000, timeoutMs: 5 * 60_000 },
414
+ )
415
+ ```
416
+
417
+ Local-dev migration takes seconds to a minute; remote deployments
418
+ can run several minutes. **Most** downstream resource creates
419
+ must wait for the datalake to reach `ready` — but the rule has
420
+ one exception worth understanding.
421
+
422
+ Downstream resources split into two categories by storage
423
+ location:
424
+
425
+ | Where the resource's state lives | Examples | Wait for `ready`? |
426
+ |----------------------------------|------------------------------------------------|-------------------|
427
+ | Platform DB (tenant-wide) | Data sources | No |
428
+ | Per-datalake DB (tenant + datalake schemas) | Tools, AI agents, generic tables, interoperability contracts, data activation clients, workflows | **Yes** |
429
+
430
+ Data sources can be created against a `new`-status datalake
431
+ because their metadata writes to the platform DB, not the
432
+ per-datalake schemas. Everything else needs the per-datalake
433
+ schemas in place — creating them against an unready datalake
434
+ produces server-side errors (table-not-found, capability-gate,
435
+ etc.) that are recoverable but indicate a missing wait.
436
+
437
+ In practice: a sibling datalake left unmigrated is still a valid
438
+ target for data-source creation, since data sources are
439
+ platform-DB-resident and don't depend on per-datalake readiness.
440
+
441
+ ### Update
442
+
443
+ `update()` replaces the whole resource — resupply the full body
444
+ (see `mutations.md`). Common pattern: get current → re-supply
445
+ write-only fields from your secret store → mutate target fields
446
+ → pass the whole shape to `update()`. Changing the
447
+ cloud-storage discriminator is rejected — `delete()` and
448
+ `create()` fresh instead.
449
+
450
+ **`DatalakeResponse` omits write-only fields.** Eight fields on
451
+ `DatalakeRequestWritable` — the four `*_pass` fields plus both
452
+ cloud-storage embeds' `access_key_id` / `secret_access_key` — are
453
+ write-only: present on the request type, absent from the response
454
+ type. A naive spread of `current` into the update body is therefore
455
+ missing those 8 required fields. The server rejects this with a 422
456
+ `AlveraApiError` pointing at the missing fields (see `errors.md`).
457
+ Re-supply them explicitly from your secret store:
458
+
459
+ ```typescript
460
+ const { data: current } = await api.datalakes.get(tenantSlug, datalakeId)
461
+ // `current` is a DatalakeResponse — write-only fields (DB passwords +
462
+ // cloud-storage secrets) are not present on the response type.
463
+
464
+ const next = {
465
+ ...current,
466
+
467
+ // Re-supply every write-only field from your secret store:
468
+ unregulated_db_writer_pass: pgPass,
469
+ unregulated_db_reader_pass: pgReaderPass,
470
+ regulated_data_db_writer_pass: pgPass,
471
+ regulated_data_db_reader_pass: pgReaderPass,
472
+ unregulated_cloud_storage: {
473
+ ...current.unregulated_cloud_storage,
474
+ access_key_id: awsAccessKeyId,
475
+ secret_access_key: awsSecretAccessKey,
476
+ },
477
+ regulated_cloud_storage: {
478
+ ...current.regulated_cloud_storage,
479
+ access_key_id: awsAccessKeyId,
480
+ secret_access_key: awsSecretAccessKey,
481
+ },
482
+
483
+ // Mutate your target fields:
484
+ description: 'Now with revised description',
485
+ }
486
+
487
+ const { data: updated } = await api.datalakes.update(
488
+ tenantSlug,
489
+ datalakeId,
490
+ next,
491
+ )
492
+ // updated.id === datalakeId — path-key stable
493
+ // updated.description === 'Now with revised description'
494
+ ```
495
+
496
+ The canonical pattern: caller re-supplies the write-only DB +
497
+ cloud-storage fields verbatim, mutates only what changes (e.g.
498
+ `description`). The eight write-only fields are enumerated in
499
+ §3 Field ownership.
500
+
501
+ **`update()` fires server-side connectivity probes before persisting.**
502
+ Submitting a body produces a successful 200 only after two
503
+ probes pass for each role profile:
504
+
505
+ - **Cloud-storage probe** — verifies the bucket exists + the
506
+ supplied `access_key_id` / `secret_access_key` (or IAM role)
507
+ can list it.
508
+ - **DB-connection probe** — verifies the platform can connect
509
+ to the supplied host:port with the supplied user + auth
510
+ method.
511
+
512
+ A body that's structurally valid but carries stale or wrong
513
+ credentials therefore fails at `update()` time, not at later
514
+ write time. The 422 envelope (see `errors.md`) names the failing
515
+ probe via `source.pointer` (e.g. `/unregulated_cloud_storage` or
516
+ `/regulated_data_db_writer_host`). This makes drift-then-update
517
+ workflows fail fast and locally rather than mid-pipeline.
518
+
519
+ Most field changes do NOT re-trigger migration. Schema-name or
520
+ auth-method changes DO — the status reverts to `processing` and
521
+ downstream operations must wait again.
522
+
523
+ `api.datalakes.update(...)` accepts the datalake's `id` OR `slug`
524
+ as the path key (same as `.get`); both are stable across migrate
525
+ status changes.
526
+
527
+ ### Delete
528
+
529
+ `delete()` requires the datalake to be empty of dependent resources
530
+ (no data sources, tools, AI agents, workflows scoped under it). A
531
+ non-empty datalake `delete()` returns a 422 with a `source.pointer`
532
+ naming the blocking dependency type. Cleanup is operator-driven in
533
+ most deployments.
534
+
535
+ ### Read shapes
536
+
537
+ `api.datalakes` exposes five distinct read methods, each
538
+ returning a different shape:
539
+
540
+ | Method | Returns |
541
+ |--------------------------------------|-------------------------------------------------------------|
542
+ | `.list(tenantSlug)` | Paged list: `{ data: DatalakeResponse[], meta }` |
543
+ | `.get(tenantSlug, idOrSlug)` | One row: `DatalakeResponse` |
544
+ | `.metadata(tenantSlug, slug)` | **Markdown string** describing the lake |
545
+ | `.indexMetadata(tenantSlug)` | **Markdown string** listing every lake |
546
+ | `.systemDatasets(tenantSlug, slug)` | `{ datasets: string[] }` — industry-built dataset names |
547
+
548
+ The two `metadata` methods return `string`, not a structured
549
+ object — they're agent-facing summaries (`data: string`, not `data:
550
+ {...}`). Test the shape with `typeof data === 'string'`.
551
+
552
+ `.indexMetadata(tenantSlug)` body begins with `# Datalakes on
553
+ tenant` and lists every datalake by slug — useful for agent-side
554
+ discovery without paging through `.list`.
555
+
556
+ `.systemDatasets(...)` enumerates the dataset names the platform
557
+ auto-creates for the datalake's `data_domain`. Each industry's
558
+ catalog mixes **domain-anchored names** (the primary subject of
559
+ the industry plus related entities) with **cross-cutting concepts**
560
+ (audit logs,
561
+ messages, documents, etc.) that the platform composes per
562
+ industry — agents iterating the catalog should not hardcode a
563
+ closed set of expected names; discover them at runtime via
564
+ this call. The array is sorted, unique, and **excludes
565
+ operator-defined generic tables** — those live under
566
+ `api.genericTables.list(...)`. The
567
+ literal placeholder `"generic_table"` is also absent. Each name
568
+ can be drilled into via
569
+ `api.datasets.metadataDetails(tenantSlug, datalakeSlug, name)` for
570
+ agent-facing markdown, or the whole-domain catalog can be fetched
571
+ in one shot via `api.datasets.metadata(tenantSlug, datalakeSlug)`. Pair `.systemDatasets()` with a
572
+ `page_size: 1` probe per name as a post-migration smoke (proves
573
+ each industry-built table is queryable; the post-ready probe
574
+ code is in §6 Gotcha 3).
575
+
576
+ ```typescript
577
+ const { data: catalog } = await api.datalakes.systemDatasets(
578
+ tenantSlug,
579
+ datalakeSlug,
580
+ )
581
+ // catalog.datasets: sorted, unique array of industry-built dataset names
582
+
583
+ for (const name of catalog.datasets) {
584
+ const { data: md } = await api.datasets.metadataDetails(tenantSlug, datalakeSlug, name)
585
+ // md is a string — agent-facing markdown describing the dataset
586
+ }
587
+ ```
588
+
589
+ ## 6. Gotchas
590
+
591
+ 1. **`create()` does NOT auto-enqueue migration.** The create response
592
+ returns immediately with `status: 'new'`; Datalake-DB-resident
593
+ downstream resources (tools, AI agents, generic tables,
594
+ interoperability contracts, data activation clients,
595
+ workflows) MUST wait for `ready` (see §5 Lifecycle for the
596
+ storage-location split). The canonical sequence:
597
+
598
+ ```typescript
599
+ const { data: created } = await api.datalakes.create(tenantSlug, body)
600
+ // created.status === 'new'
601
+
602
+ await api.datalakes.migrate(tenantSlug, created.slug)
603
+
604
+ const ready = await waitUntilReady(
605
+ () => api.datalakes.get(tenantSlug, created.slug),
606
+ (s) => s === 'ready' ? 'ready' : 'pending',
607
+ { intervalMs: 15_000, timeoutMs: 5 * 60_000 },
608
+ )
609
+ // ready.status === 'ready' — safe to POST tools, AI agents, etc.
610
+ ```
611
+
612
+ 2. **`migrate` returns the job ack, not the datalake.** The
613
+ `{ status: "enqueued", job_id, ... }` shape can be mistaken for
614
+ the datalake row. To learn live status, `.get` separately and
615
+ poll per `async.md`.
616
+
617
+ 3. **`status: "ready"` is necessary but not sufficient.** A
618
+ partial-migration failure can leave a datalake in `ready`
619
+ with some tables silently missing — a failure mode that
620
+ otherwise only surfaces mid-pipeline (during downstream
621
+ resource creation or live data ingestion), far from its
622
+ root cause.
623
+ Pair the status check with a post-ready probe:
624
+
625
+ ```typescript
626
+ const { data: catalog } = await api.datalakes.systemDatasets(
627
+ tenantSlug, datalakeSlug,
628
+ )
629
+ // catalog.datasets is the industry-built name list —
630
+ // discovered at runtime; don't hardcode names.
631
+
632
+ for (const dataset of catalog.datasets) {
633
+ const { data } = await api.datasets.createUserSearch(
634
+ tenantSlug,
635
+ datalakeSlug,
636
+ dataset,
637
+ { search_query: '1 = 1' },
638
+ )
639
+ if (data.status !== 'completed') {
640
+ throw new Error(
641
+ `post-ready probe failed: dataset=${dataset} status=${data.status}`,
642
+ )
643
+ }
644
+ }
645
+ ```
646
+
647
+ 4. **`id` and `slug` are interchangeable as path keys.**
648
+ `.get`, `.update`, `.migrate`, `.metadata` all accept either.
649
+ The `slug` is human-readable; the `id` is a UUID. Pick one
650
+ convention per code path to avoid mixed references.
651
+
652
+ 5. **Schema-name collisions surface at create, not migrate.** A
653
+ sibling datalake reusing a `*_schema` value gets a 422
654
+ immediately — well before the asynchronous schema-creation job
655
+ would have hit the conflict.
656
+
657
+ 6. **`iam_role` auth still requires a `*_pass` value structurally.**
658
+ The TypeScript type (and the server's schema) treat the field as
659
+ a required string. Supply a sentinel literal (e.g.
660
+ `"unused-iam-role"`); the platform clears it server-side.
661
+
662
+ 7. **`cloud_storage_type` lives inside each embed, not at the
663
+ top level.** A single body has two discriminators
664
+ (`unregulated_cloud_storage.cloud_storage_type` and
665
+ `regulated_cloud_storage.cloud_storage_type`); they're
666
+ independently validated and can carry different values.
667
+
668
+ 8. **`delete()` is rare in practice.** Datalakes accrete dependents
669
+ quickly; routine cleanup is via operator-driven console
670
+ actions, not SDK calls. Treat `.delete` as an integration-test
671
+ teardown method, not a production operation.
672
+
673
+ 9. **Create and update run synchronous reachability probes.** Before
674
+ the row is written, the platform opens connections to every
675
+ declared endpoint — all four DB profiles (unregulated reader +
676
+ writer, regulated reader + writer) AND both cloud-storage
677
+ buckets — and only proceeds if every probe succeeds. A
678
+ structurally valid body can still fail with field-level
679
+ rejections on `*_db_*_host` (unreachable, wrong credentials, or
680
+ SSL-mismatch) or `*_cloud_storage` (bucket inaccessible). The
681
+ same probe runs on update; an update that only changes the
682
+ datalake's `name` still re-probes if the body re-supplies any
683
+ `*_host` or `*_cloud_storage` field.
684
+
685
+ Two consumer-relevant consequences:
686
+
687
+ - **Multiple probe failures are surfaced in a single envelope.**
688
+ Two bad reader hosts produce two field-level entries —
689
+ consumer agents iterating on a single response can correct
690
+ several fields per round-trip.
691
+ - **`enable_ssl: true` against a non-SSL database fails the
692
+ probe.** The flag looks client-side but is validated by the
693
+ probe attempting an SSL handshake. Match it to what the
694
+ target database actually supports.
695
+
696
+ 10. **`pool_size` is clamped to the inclusive range 1–50.** The
697
+ typed field accepts any integer; the server rejects values
698
+ outside `[1, 50]` with a `/pool_size` pointer. The error message
699
+ mentions a `greater_than: 0` or `less_than_or_equal_to: 50`
700
+ constraint depending on which side was crossed.
701
+
702
+ 11. **`timezone` is a closed IANA enum.** Submit a non-IANA string
703
+ (e.g. `"Bad/Timezone"` or `"EST"`) and the platform rejects
704
+ with `is not a valid IANA timezone` on `/timezone`. The set of
705
+ valid identifiers is not exposed over the SDK as a discovery
706
+ surface — consumers must source IANA tz database names
707
+ externally (e.g. JavaScript's `Intl.supportedValuesOf('timeZone')`,
708
+ or the IANA tz data directly).
709
+
710
+ 12. **`auth_method` defaults to `"password"` on every DB profile.**
711
+ Omitting `*_auth_method` or supplying `null` is equivalent to
712
+ `"password"` — and consequently requires both `*_user` and
713
+ `*_pass` to be supplied. The IAM-role relaxation in §2 applies
714
+ only when `auth_method` is explicitly `"iam_role"`.