@alvera-ai/platform-sdk 0.12.1 → 0.13.0-next.gf3d2a4a
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.agent/AGENTS.md +121 -19
- package/.agent/account_management.md +79 -38
- package/.agent/action_logs.md +144 -0
- package/.agent/action_status_updaters.md +237 -53
- package/.agent/ai_agents.md +149 -53
- package/.agent/ai_sandbox.md +11 -4
- package/.agent/async.md +16 -6
- package/.agent/connected_apps.md +116 -4
- package/.agent/cookbook/_fixtures/README.md +9 -9
- package/.agent/cookbook/_fixtures/{payment_risk/_compliance_screenings_payment_risk_compliance_screening.liquid → payments/_compliance_screenings_payments_compliance_screening.liquid} +1 -1
- package/.agent/cookbook/_fixtures/{payment_risk/_compliance_screenings_payment_risk_mdm.liquid → payments/_compliance_screenings_payments_mdm.liquid} +1 -1
- package/.agent/cookbook/_fixtures/{payment_risk/_payment_accounts_payment_risk_mdm.liquid → payments/_payment_accounts_payments_mdm.liquid} +1 -1
- package/.agent/cookbook/_fixtures/{payment_risk/_payment_accounts_payment_risk_payment_account.liquid → payments/_payment_accounts_payments_payment_account.liquid} +1 -1
- package/.agent/cookbook/_fixtures/{accounts_receivable/_customers_accounts_receivable_customer.liquid → subscription/_customers_subscription_customer.liquid} +1 -1
- package/.agent/cookbook/_fixtures/{accounts_receivable/_customers_accounts_receivable_mdm.liquid → subscription/_customers_subscription_mdm.liquid} +1 -1
- package/.agent/cookbook/_setup/foundation.md +24 -4
- package/.agent/cookbook/_setup/healthcare.md +24 -4
- package/.agent/cookbook/_setup/{payment_risk.md → payments.md} +51 -31
- package/.agent/cookbook/_setup/{accounts_receivable.md → subscription.md} +51 -31
- package/.agent/cookbook/action-status-updaters.md +25 -18
- package/.agent/cookbook/bulk-ingest.md +15 -15
- package/.agent/cookbook/dunning-sms-for-delinquent.md +21 -21
- package/.agent/cookbook/{custom-tables.md → generic-tables.md} +44 -41
- package/.agent/cookbook/invite-team.md +19 -13
- package/.agent/cookbook/kyc-notification-on-account-activation.md +26 -26
- package/.agent/cookbook/marketing-campaign-send.md +1003 -0
- package/.agent/cookbook/rest-fetch.md +9 -9
- package/.agent/cookbook/sanctions-screening-with-agent-review.md +22 -22
- package/.agent/cookbook/system-templates.md +15 -15
- package/.agent/cookbook/triage-prospects-by-priority.md +17 -17
- package/.agent/cookbook/welcome-sms-for-customers.md +21 -21
- package/.agent/data_activation_clients.md +177 -42
- package/.agent/data_sources.md +55 -37
- package/.agent/datalakes.md +30 -17
- package/.agent/debugging.md +48 -14
- package/.agent/errors.md +39 -17
- package/.agent/generic_tables.md +150 -51
- package/.agent/interoperability_contracts.md +114 -15
- package/.agent/mdm.md +171 -93
- package/.agent/messages.md +252 -0
- package/.agent/templates.md +21 -4
- package/.agent/tool-call-configs.md +1 -1
- package/.agent/tools.md +150 -60
- package/.agent/type_naming.md +79 -18
- package/.agent/workflows.md +408 -62
- package/LICENSE +21 -93
- package/README.md +2 -2
- package/dist/bin/platform-sdk.mjs +53 -1
- package/dist/bin/platform-sdk.mjs.map +1 -1
- package/dist/index.d.mts +582 -66
- package/dist/index.d.mts.map +1 -1
- package/dist/index.mjs +654 -105
- package/dist/index.mjs.map +1 -1
- package/package.json +10 -6
- /package/.agent/cookbook/_fixtures/{accounts_receivable → subscription}/stripe_customers_batch1.csv +0 -0
package/.agent/debugging.md
CHANGED
|
@@ -28,6 +28,7 @@ const debugConfig: ApiDebugConfig = {
|
|
|
28
28
|
const api = createIsolatedPlatformApi({
|
|
29
29
|
baseUrl,
|
|
30
30
|
sessionToken,
|
|
31
|
+
apiKey, // the tenant's publishable key (X-API-Key)
|
|
31
32
|
debug: debugConfig,
|
|
32
33
|
})
|
|
33
34
|
```
|
|
@@ -69,8 +70,9 @@ type ApiDebugConfig = {
|
|
|
69
70
|
```
|
|
70
71
|
|
|
71
72
|
- `log` is the sink. The SDK emits formatted log messages
|
|
72
|
-
(request method + URL + body, response status + body)
|
|
73
|
-
|
|
73
|
+
(request method + URL + body, response status + URL + body)
|
|
74
|
+
— one call per request and one per response, so TWO calls
|
|
75
|
+
per HTTP exchange, each a separate string.
|
|
74
76
|
- `redactStrings` is an array of LITERAL values the SDK
|
|
75
77
|
should scrub from log output. Empty / absent = no
|
|
76
78
|
redaction (use only when no secrets are in the request
|
|
@@ -87,10 +89,14 @@ consumers wrap the `log` callback with their own emitter.
|
|
|
87
89
|
error-rendering path includes the offending request body,
|
|
88
90
|
redact it yourself before rendering. See `errors.md` for
|
|
89
91
|
the throw mechanism.
|
|
90
|
-
- **
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
92
|
+
- **Secrets the server MINTS that you never installed**.
|
|
93
|
+
Response bodies ARE filtered through `redactStrings` — the
|
|
94
|
+
same scrub the request gets — so any literal in your redact
|
|
95
|
+
list is masked whichever direction it travels. But a
|
|
96
|
+
credential the server generates and returns (rare but
|
|
97
|
+
possible) is by definition not in `redactStrings`, so it
|
|
98
|
+
passes through un-masked; the consumer is responsible for
|
|
99
|
+
not logging it.
|
|
94
100
|
- **Anything OUTSIDE the SDK's HTTP path**. `redactStrings`
|
|
95
101
|
only filters what the SDK itself writes to `log`. Your own
|
|
96
102
|
log statements that touch request/response data must
|
|
@@ -123,15 +129,43 @@ guarantee a fresh snapshot.
|
|
|
123
129
|
|
|
124
130
|
## What's in the log line
|
|
125
131
|
|
|
126
|
-
|
|
132
|
+
The SDK fires `log` TWICE per exchange — once for the request
|
|
133
|
+
(prefixed `→`), once for the response (prefixed `←`) — not once
|
|
134
|
+
per round-trip. Each is a separate string. The request line
|
|
135
|
+
carries method + URL; a body, if present, follows on the next
|
|
136
|
+
lines indented four spaces. The response line carries status +
|
|
137
|
+
URL, then its body the same way. A pair looks roughly like:
|
|
127
138
|
|
|
128
139
|
```
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
140
|
+
→ POST https://demo.example.com/api/v1/tenants/acme/datalakes/main/tools
|
|
141
|
+
{
|
|
142
|
+
"name": "...",
|
|
143
|
+
"intent": "data_exchange",
|
|
144
|
+
"body": {
|
|
145
|
+
"tool_body_type": "s3",
|
|
146
|
+
"access_key_id": "********",
|
|
147
|
+
"secret_access_key": "********"
|
|
148
|
+
}
|
|
149
|
+
}
|
|
150
|
+
← 201 https://demo.example.com/api/v1/tenants/acme/datalakes/main/tools
|
|
151
|
+
{
|
|
152
|
+
"id": "...",
|
|
153
|
+
"slug": "...",
|
|
154
|
+
"name": "..."
|
|
155
|
+
}
|
|
134
156
|
```
|
|
135
157
|
|
|
136
|
-
|
|
137
|
-
|
|
158
|
+
The URL is **absolute** — origin included — by design, not
|
|
159
|
+
path-only. The origin is the only thing distinguishing one
|
|
160
|
+
environment from another: a path-only line reads identically
|
|
161
|
+
whether the call hit localhost or a demo server, which defeats
|
|
162
|
+
the question the log is most often asked, *where did this
|
|
163
|
+
actually go?*. The query string is deliberately omitted (it
|
|
164
|
+
carries filter values, not routing; the body is where those
|
|
165
|
+
are read). Only the request/response BODY is logged — never
|
|
166
|
+
headers, so the `Authorization: Bearer …` and `X-API-Key`
|
|
167
|
+
credentials (see `AGENTS.md` for the two-credentials model)
|
|
168
|
+
never reach the log at all.
|
|
169
|
+
|
|
170
|
+
(Format is plain-string; the `→`/`←` prefixes and field
|
|
171
|
+
ordering are SDK-internal and may evolve.)
|
package/.agent/errors.md
CHANGED
|
@@ -46,19 +46,23 @@ try {
|
|
|
46
46
|
```
|
|
47
47
|
|
|
48
48
|
The thrown body is typed as `AlveraApiError` (exported from the package root)
|
|
49
|
-
|
|
49
|
+
— the JSON:API `errors[]` envelope the platform returns on 4xx. **Both 422
|
|
50
|
+
and 409 carry it** (same shape, different status). A few endpoints declare the
|
|
51
|
+
older field-keyed `ErrorResponse` map (`{ errors: { field: string[] } }`) for a
|
|
52
|
+
500 instead.
|
|
50
53
|
|
|
51
|
-
##
|
|
54
|
+
## The error envelope shape (422 and 409)
|
|
52
55
|
|
|
53
56
|
The platform standardizes ALL 422 response bodies on a single shape —
|
|
54
|
-
regardless of which validation layer fired
|
|
57
|
+
regardless of which validation layer fired — and **409 Conflict bodies use the
|
|
58
|
+
identical shape** (see below for which failures are 409, not 422):
|
|
55
59
|
|
|
56
60
|
```json
|
|
57
61
|
{
|
|
58
62
|
"errors": [
|
|
59
63
|
{
|
|
60
64
|
"source": { "pointer": "/<field_path>" },
|
|
61
|
-
"title": "
|
|
65
|
+
"title": "Invalid value",
|
|
62
66
|
"detail": "<specific reason this field failed>"
|
|
63
67
|
},
|
|
64
68
|
...
|
|
@@ -67,13 +71,19 @@ regardless of which validation layer fired:
|
|
|
67
71
|
```
|
|
68
72
|
|
|
69
73
|
- `errors` is always an ARRAY of error objects (never a field-keyed map).
|
|
70
|
-
- `source.pointer` is
|
|
71
|
-
`/nested/field` for embeds) naming the offending field on the request
|
|
72
|
-
|
|
74
|
+
- `source.pointer` is an RFC 6901 JSON Pointer (`/field_name` for top-level
|
|
75
|
+
fields; `/nested/field` for embeds) naming the offending field on the request
|
|
76
|
+
body.
|
|
77
|
+
- `detail` is the human-readable reason. `title` is a **machine-readable
|
|
78
|
+
category, not a per-field summary**: the constant `"Invalid value"` for every
|
|
79
|
+
validation error (422 and the 409 conflict cases), the status reason phrase
|
|
80
|
+
(`"Conflict"`, `"Not Found"`, …) for status-only errors, and a stage code
|
|
81
|
+
(`"transform_failed"`, `"template_body_missing"`, …) for `/run` pipeline
|
|
82
|
+
errors. Pattern-match on `title` for dispatch; show `detail` to a human.
|
|
73
83
|
- Multiple errors may share the same `source.pointer` if more than one check
|
|
74
84
|
fired on the same field.
|
|
75
85
|
|
|
76
|
-
## Two layers behind the standardized
|
|
86
|
+
## Two layers behind the standardized envelope
|
|
77
87
|
|
|
78
88
|
The platform validates a request in two layers; both surface through the
|
|
79
89
|
same envelope above:
|
|
@@ -94,8 +104,15 @@ fields), foreign-key constraints, custom platform validations. Layer-2
|
|
|
94
104
|
errors are normalized into the same envelope shape as layer 1 — consumers
|
|
95
105
|
don't distinguish layers from the JSON.
|
|
96
106
|
|
|
97
|
-
|
|
98
|
-
|
|
107
|
+
**But layer 2 is not always a 422.** The envelope is identical; the *status*
|
|
108
|
+
depends on the failure. Ordinary field validation (`"can't be blank"`,
|
|
109
|
+
`"is invalid"`, a custom `add_error` rule) is **422**. A failure that collides
|
|
110
|
+
with the current state of the resource is **409 Conflict**: a **uniqueness
|
|
111
|
+
collision** (`unique_constraint` / `unsafe_validate_unique`) or a **delete
|
|
112
|
+
blocked by dependants** (a foreign-key/assoc constraint firing on delete). So
|
|
113
|
+
do not assume every semantic conflict is a tidy 422 — read `_httpStatus`, not
|
|
114
|
+
just the body. Read `source.pointer`, fix the field (or resolve the collision),
|
|
115
|
+
resubmit.
|
|
99
116
|
|
|
100
117
|
## Concrete examples
|
|
101
118
|
|
|
@@ -124,8 +141,9 @@ body):
|
|
|
124
141
|
}
|
|
125
142
|
```
|
|
126
143
|
|
|
127
|
-
**Layer 2 — semantic rule** (`delete()` on a default-flagged data
|
|
128
|
-
client)
|
|
144
|
+
**Layer 2 — semantic rule → 422** (`delete()` on a default-flagged data
|
|
145
|
+
activation client). A custom `add_error` rule (not a uniqueness/FK constraint)
|
|
146
|
+
stays a **422**, unlike the uniqueness case below:
|
|
129
147
|
|
|
130
148
|
```json
|
|
131
149
|
{
|
|
@@ -136,13 +154,15 @@ client):
|
|
|
136
154
|
}
|
|
137
155
|
```
|
|
138
156
|
|
|
139
|
-
**Layer 2 — uniqueness** (`invitations.create()` for an
|
|
140
|
-
email)
|
|
157
|
+
**Layer 2 — uniqueness → 409, not 422** (`invitations.create()` for an
|
|
158
|
+
already-invited email). Same `errors[]` envelope, but a uniqueness collision
|
|
159
|
+
comes back as a **409 Conflict** (`_httpStatus === 409`):
|
|
141
160
|
|
|
142
161
|
```json
|
|
143
162
|
{
|
|
144
163
|
"errors": [
|
|
145
164
|
{ "source": { "pointer": "/email" },
|
|
165
|
+
"title": "Invalid value",
|
|
146
166
|
"detail": "is already invited" }
|
|
147
167
|
]
|
|
148
168
|
}
|
|
@@ -163,14 +183,16 @@ platform maps:
|
|
|
163
183
|
| 401 | Missing or invalid Bearer / `x-api-key` |
|
|
164
184
|
| 403 | Authenticated but role lacks permission |
|
|
165
185
|
| 404 | Resource doesn't exist OR cross-tenant access (404, not 403) |
|
|
186
|
+
| 409 | Uniqueness collision, delete blocked by dependants, or URL/body id mismatch — same `errors[]` envelope |
|
|
166
187
|
| 422 | Validation failed; envelope above is the thrown body |
|
|
167
188
|
| 5xx | Platform-internal failure; safe to retry with backoff |
|
|
168
189
|
|
|
169
190
|
## Retry semantics
|
|
170
191
|
|
|
171
|
-
Treat 5xx as infra noise — retry with exponential backoff. Treat 422
|
|
172
|
-
real consumer-correctable error — fix the body
|
|
173
|
-
422 with the same
|
|
192
|
+
Treat 5xx as infra noise — retry with exponential backoff. Treat 422 (and the
|
|
193
|
+
409 conflict cases) as a real consumer-correctable error — fix the body, or
|
|
194
|
+
resolve the collision, then resubmit. **Never retry a 422 or 409 with the same
|
|
195
|
+
body** — the failure won't clear on its own.
|
|
174
196
|
|
|
175
197
|
## Mapping `source.pointer` back to your TypeScript type
|
|
176
198
|
|
package/.agent/generic_tables.md
CHANGED
|
@@ -11,6 +11,29 @@ in the datalake's schema. The parent datalake MUST be
|
|
|
11
11
|
`status: 'ready'` before the job can run end-to-end — see
|
|
12
12
|
`datalakes.md` §5 Lifecycle.
|
|
13
13
|
|
|
14
|
+
> ## ⚠ `api.genericTables` manages table DEFINITIONS, never rows
|
|
15
|
+
>
|
|
16
|
+
> This namespace is DDL, not DML. It creates, updates (see §2), reads,
|
|
17
|
+
> and deletes the *table* — its schema. **It does not write rows.**
|
|
18
|
+
> There is **no** `POST /generic-tables/:id/rows`, no `insertRow`, no
|
|
19
|
+
> `updateRow` — the endpoint an agent reaches for does not exist.
|
|
20
|
+
>
|
|
21
|
+
> **Rows are written by exactly one path: a bound data activation
|
|
22
|
+
> client's `.ingest` / `.ingestFile`** (see `data_activation_clients.md`).
|
|
23
|
+
> Ingest is asynchronous — it returns **`202` + a batch id, NOT the
|
|
24
|
+
> saved row.** Every "Save" you see in a CRUD-looking UI over a generic
|
|
25
|
+
> table is an ingest under the hood, and it lands eventually, not
|
|
26
|
+
> inline.
|
|
27
|
+
>
|
|
28
|
+
> - To **seed / add rows**: `.ingest` through the table's default
|
|
29
|
+
> manual-upload DAC (gotcha 7).
|
|
30
|
+
> - To **edit a row**: re-ingest it with the same unique-column value —
|
|
31
|
+
> ingest is an **upsert** (full-row replace on the unique key), so
|
|
32
|
+
> "update row X" is just "ingest X again with new values". There is
|
|
33
|
+
> no partial row patch.
|
|
34
|
+
> - To **read rows**: `api.datasets.search` (paged) or
|
|
35
|
+
> `api.datalakes.executeSql` (SQL) — never a `genericTables` verb.
|
|
36
|
+
|
|
14
37
|
## 1. Wire shape
|
|
15
38
|
|
|
16
39
|
```typescript
|
|
@@ -46,15 +69,31 @@ const { data: created } = await api.genericTables.create(
|
|
|
46
69
|
|
|
47
70
|
The response returns immediately — the row exists in Platform-DB,
|
|
48
71
|
but the *physical* Postgres table does not yet. Consumers MUST
|
|
49
|
-
poll `.get(
|
|
50
|
-
the table as queryable. See §5 Lifecycle.
|
|
72
|
+
poll `.get(id)` until `status === 'deployed'` before treating
|
|
73
|
+
the table as queryable. See §5 Lifecycle. (**`.get` keys on the
|
|
74
|
+
UUID `id`, not `name`** — see §2.)
|
|
51
75
|
|
|
52
76
|
## 2. Rules the type cannot encode
|
|
53
77
|
|
|
54
|
-
### `
|
|
78
|
+
### Two identifiers: the UUID `id` (API key) vs the `name` (SQL table)
|
|
79
|
+
|
|
80
|
+
A created generic table carries **two** server-derived identifiers,
|
|
81
|
+
and they are used in different places — mixing them up is the most
|
|
82
|
+
common mistake against this resource:
|
|
83
|
+
|
|
84
|
+
```
|
|
85
|
+
id server-derived UUID — the API path key AND the FK.
|
|
86
|
+
.get(id) / .update(id) / .delete(id) all
|
|
87
|
+
take it, and workflows / DACs / contracts
|
|
88
|
+
reference the table via generic_table_id = id.
|
|
89
|
+
name 'alvera_custom_<slug>' — the PHYSICAL Postgres table name.
|
|
90
|
+
Used in executeSql (`FROM alvera_custom_…`)
|
|
91
|
+
and to recognise the table's auto-provisioned
|
|
92
|
+
DAC by name. NOT an API path key.
|
|
93
|
+
```
|
|
55
94
|
|
|
56
|
-
|
|
57
|
-
|
|
95
|
+
`name` is server-derived from `title` — slugify + `alvera_custom_`
|
|
96
|
+
prefix:
|
|
58
97
|
|
|
59
98
|
```
|
|
60
99
|
title: 'Contact Us Submissions'
|
|
@@ -62,13 +101,13 @@ title: 'Contact Us Submissions'
|
|
|
62
101
|
name: 'alvera_custom_contact_us_submissions'
|
|
63
102
|
```
|
|
64
103
|
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
the
|
|
70
|
-
|
|
71
|
-
|
|
104
|
+
**`.get` / `.update` / `.delete` key on the UUID `id`, NOT `name`.**
|
|
105
|
+
Passing `name` (or any non-UUID) to `.get` 422s with `Invalid format.
|
|
106
|
+
Expected :uuid` — the same id/slug trap as other resources. To go from
|
|
107
|
+
a known `name` back to its `id`, `list()` with a `handle` filter and
|
|
108
|
+
read the row's `id`. Never pre-compute either identifier client-side —
|
|
109
|
+
read both back from the create response and pass `id` to CRUD,
|
|
110
|
+
`name` to `executeSql`.
|
|
72
111
|
|
|
73
112
|
### `columns` is operator-authored schema
|
|
74
113
|
|
|
@@ -121,11 +160,14 @@ for the tier split):
|
|
|
121
160
|
|
|
122
161
|
Two type-level restrictions the typed validator does not encode:
|
|
123
162
|
|
|
124
|
-
- **`type: 'jsonb'`
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
163
|
+
- **`type: 'jsonb'` REQUIRES `privacy_requirement: 'redact_only'` —
|
|
164
|
+
`'none'` is rejected too, not just `'tokenize'`.** The platform
|
|
165
|
+
can't tokenize an arbitrary JSON document (no canonical
|
|
166
|
+
"identity" to tokenize), and it won't let an unredacted JSON
|
|
167
|
+
blob flow into the unregulated tier either. `'redact_only'` is
|
|
168
|
+
the ONLY valid privacy value for a jsonb column — submitting
|
|
169
|
+
`{ type: 'jsonb', privacy_requirement: 'tokenize' }` OR
|
|
170
|
+
`{ type: 'jsonb', privacy_requirement: 'none' }` both return
|
|
129
171
|
422 on `/columns/N/privacy_requirement`.
|
|
130
172
|
- **Tokenize widens primitive types at the schema layer.** A
|
|
131
173
|
`{ type: 'integer', privacy_requirement: 'tokenize' }` column
|
|
@@ -136,8 +178,10 @@ Two type-level restrictions the typed validator does not encode:
|
|
|
136
178
|
This affects `integer`, `float`, `boolean`, `is_array string`,
|
|
137
179
|
`date`, `datetime`, and `time`.
|
|
138
180
|
|
|
139
|
-
The privacy choice is **immutable post-create** —
|
|
140
|
-
|
|
181
|
+
The privacy choice is **immutable post-create** — `update()` exists
|
|
182
|
+
but its migration is additive-only and never re-privacy's an existing
|
|
183
|
+
column (see §2 update note), so the only way to change a column's
|
|
184
|
+
`privacy_requirement` is `delete()` + `create()`.
|
|
141
185
|
|
|
142
186
|
**Privacy is operator-decided per column, not implied by name.**
|
|
143
187
|
A field called `message` can be `redact_only` in one tenant and
|
|
@@ -168,7 +212,7 @@ in `columns[N].name`:
|
|
|
168
212
|
```
|
|
169
213
|
healthcare patient_id
|
|
170
214
|
core_banking party_id
|
|
171
|
-
|
|
215
|
+
subscription customer_id
|
|
172
216
|
(other domains as they land)
|
|
173
217
|
```
|
|
174
218
|
|
|
@@ -187,13 +231,30 @@ create with 422 on `/title`. Pick a title that slugifies to
|
|
|
187
231
|
something else (e.g. avoid leading "Alvera System" in the title
|
|
188
232
|
text).
|
|
189
233
|
|
|
190
|
-
###
|
|
191
|
-
|
|
192
|
-
There is
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
the
|
|
234
|
+
### `update()` exists — but the schema migration is ADDITIVE-only
|
|
235
|
+
|
|
236
|
+
There **is** an `update()` (`PUT /generic-tables/:id`, full-replace —
|
|
237
|
+
the same body shape as `create`, all fields required). It exists so a
|
|
238
|
+
declarative `alvera apply` can resend a table's full manifest and
|
|
239
|
+
reconcile drift. On update the platform re-runs the schema migration
|
|
240
|
+
for the new column set — but the migration is **strictly additive**:
|
|
241
|
+
|
|
242
|
+
- **New columns in the body are added** to the physical table
|
|
243
|
+
(test-pinned) and to the regulated mirror.
|
|
244
|
+
- **Columns you omit are NOT dropped.** The migration never
|
|
245
|
+
auto-drops a column ("keep down as noop to avoid destructive
|
|
246
|
+
change"), so a shrunken `columns` array does not remove storage.
|
|
247
|
+
- **Existing columns are NOT retyped or re-privacy'd.** The additive
|
|
248
|
+
migration only adds; it does not `ALTER` an existing column's type
|
|
249
|
+
or `privacy_requirement`.
|
|
250
|
+
|
|
251
|
+
So `update()` is the right tool to **add a column** to a live table
|
|
252
|
+
without losing data. To **drop or retype** a column you still
|
|
253
|
+
`delete()` + `create()` fresh — the additive migration won't do it,
|
|
254
|
+
and column `privacy_requirement` remains immutable in place (§2 privacy
|
|
255
|
+
note). One validation guardrail: an update that would leave the table
|
|
256
|
+
with **zero** `is_unique` columns is rejected (422), same rule as
|
|
257
|
+
create.
|
|
197
258
|
|
|
198
259
|
## 3. Field ownership
|
|
199
260
|
|
|
@@ -202,7 +263,9 @@ the data activation client.
|
|
|
202
263
|
|
|
203
264
|
```
|
|
204
265
|
name string — `alvera_custom_<slugified-title>`
|
|
205
|
-
status enum — 'new' | 'processing' | 'deployed' | '
|
|
266
|
+
status enum — 'new' | 'processing' | 'deployed' | 'stale'
|
|
267
|
+
(no 'failed' — a failed migration just never
|
|
268
|
+
reaches 'deployed'; 'stale' = drifted definition)
|
|
206
269
|
```
|
|
207
270
|
|
|
208
271
|
**Caller-supplied (round-trip).**
|
|
@@ -252,29 +315,37 @@ const { data: created } = await api.genericTables.create(
|
|
|
252
315
|
)
|
|
253
316
|
// created.status === 'new' (or 'processing' if worker raced)
|
|
254
317
|
|
|
255
|
-
|
|
318
|
+
const deadline = Date.now() + 60_000
|
|
319
|
+
while (Date.now() < deadline) {
|
|
256
320
|
const { data: row } = await api.genericTables.get(
|
|
257
|
-
tenantSlug, datalakeSlug, created.name
|
|
321
|
+
tenantSlug, datalakeSlug, created.id, // UUID id, NOT created.name
|
|
258
322
|
)
|
|
259
323
|
if (row.status === 'deployed') break
|
|
260
|
-
if (row.status === 'failed') throw new Error('migration failed')
|
|
261
324
|
await new Promise((r) => setTimeout(r, 1_000))
|
|
262
325
|
}
|
|
263
326
|
```
|
|
264
327
|
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
poll above
|
|
328
|
+
**The status enum has no terminal-failure value** — it is `new →
|
|
329
|
+
processing → deployed` (plus `stale`, an already-deployed table whose
|
|
330
|
+
definition drifted; never a fresh-create state). A migration that
|
|
331
|
+
fails does not flip to a `failed` status; the row simply never reaches
|
|
332
|
+
`deployed`, so bound the poll with a **timeout** (as above) rather than
|
|
333
|
+
watching for a failure value. (This is the same timeout-bounded idiom
|
|
334
|
+
the validated `cookbook/generic-tables.md` runs, passing the UUID
|
|
335
|
+
`id`.) `.get(id)` distinguishes "row never
|
|
336
|
+
created" (404) from "deployment in progress" (200 with a
|
|
337
|
+
sub-`deployed` status) — two distinct signals on the same endpoint.
|
|
338
|
+
Use the 404 to short-circuit retry loops; use the 200+status to drive
|
|
339
|
+
the poll above.
|
|
270
340
|
|
|
271
341
|
### Read shapes
|
|
272
342
|
|
|
273
343
|
```
|
|
274
|
-
.list(tenantSlug, datalakeSlug)
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
344
|
+
.list(tenantSlug, datalakeSlug, query?) Paged: { data, meta }
|
|
345
|
+
(full Flop query — type_naming.md)
|
|
346
|
+
.get(tenantSlug, datalakeSlug, id) One row, by UUID id
|
|
347
|
+
(NOT name/slug; resolve a
|
|
348
|
+
name → id via list + handle filter)
|
|
278
349
|
```
|
|
279
350
|
|
|
280
351
|
Plus the polymorphic dataset surface for per-table markdown:
|
|
@@ -298,6 +369,18 @@ See `datalakes.md` §5 `.systemDatasets` for the system-dataset
|
|
|
298
369
|
sibling of this verb; the `'generic_table'` kind is the entry
|
|
299
370
|
point for generic-table metadata.
|
|
300
371
|
|
|
372
|
+
### Update
|
|
373
|
+
|
|
374
|
+
`update(tenantSlug, datalakeSlug, id, body)` — `PUT`, full-replace
|
|
375
|
+
(same body shape as `create`, addressed by **UUID `id`**, not `name`).
|
|
376
|
+
Re-runs the schema migration for the new column set, **additively**:
|
|
377
|
+
new columns are added; omitted columns are not dropped; existing
|
|
378
|
+
columns are not retyped (see §2). Its intended use is declarative
|
|
379
|
+
drift reconciliation (`alvera apply` resends the whole manifest) and
|
|
380
|
+
adding a column to a live table without data loss. Rejected (422) if
|
|
381
|
+
the new column set has no `is_unique` column. It writes the schema, not
|
|
382
|
+
rows (rows still flow through the DAC — see the box at the top).
|
|
383
|
+
|
|
301
384
|
### Delete
|
|
302
385
|
|
|
303
386
|
`delete()` removes the row and drops the physical table. Tables
|
|
@@ -307,12 +390,15 @@ dependency. Detach dependents first.
|
|
|
307
390
|
|
|
308
391
|
## 6. Gotchas
|
|
309
392
|
|
|
310
|
-
1. **`.get`
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
|
|
315
|
-
`
|
|
393
|
+
1. **`.get` / `.update` / `.delete` take the UUID `id`, not `name`.**
|
|
394
|
+
The API path key is the UUID `id`, and downstream bindings
|
|
395
|
+
(`generic_table_id` on workflows / DACs / contracts) are that same
|
|
396
|
+
`id`. The `name` (`alvera_custom_<slug>`) is the *physical SQL table
|
|
397
|
+
name* — for `executeSql` and for recognising the table's
|
|
398
|
+
auto-provisioned DAC — not an API key. Stash **both** `data.id` and
|
|
399
|
+
`data.name` from create: `id` for CRUD + bindings, `name` for SQL.
|
|
400
|
+
Passing `name` to `.get` 422s (`Invalid format. Expected :uuid`);
|
|
401
|
+
resolve `name → id` via `list()` with a `handle` filter (§2).
|
|
316
402
|
|
|
317
403
|
2. **`status` reaches `deployed` asynchronously.** A bare
|
|
318
404
|
`.create` response with `status: 'new'` is NOT yet bindable.
|
|
@@ -325,8 +411,9 @@ dependency. Detach dependents first.
|
|
|
325
411
|
`tokenize` columns surface as an opaque stable token in the
|
|
326
412
|
unregulated tier; `redact_only` strips the value from that
|
|
327
413
|
tier entirely; `none` keeps the raw value only in the
|
|
328
|
-
regulated tier.
|
|
329
|
-
recreate the table to change
|
|
414
|
+
regulated tier. `update()`'s additive migration never re-privacy's
|
|
415
|
+
an existing column, so recreate the table to change a column's
|
|
416
|
+
privacy.
|
|
330
417
|
|
|
331
418
|
4. **System-dataset enumeration EXCLUDES generic tables.**
|
|
332
419
|
`api.datalakes.systemDatasets(...)` returns only the
|
|
@@ -346,6 +433,18 @@ dependency. Detach dependents first.
|
|
|
346
433
|
`submission_id`, `name`, `email`) sit alongside columns
|
|
347
434
|
reserved for downstream resources to update (e.g. a reply
|
|
348
435
|
column written by a workflow, or a scoring column written
|
|
349
|
-
by an agent). Plan the column set for the full lifecycle
|
|
350
|
-
|
|
351
|
-
|
|
436
|
+
by an agent). Plan the column set for the full lifecycle —
|
|
437
|
+
though you CAN **add** a forgotten column later via `update()`'s
|
|
438
|
+
additive migration (§2), without losing data. Dropping or
|
|
439
|
+
retyping still needs delete + recreate.
|
|
440
|
+
|
|
441
|
+
7. **A new generic table auto-provisions a default manual-upload
|
|
442
|
+
DAC — ingest through it, don't create one.** Alongside the
|
|
443
|
+
identity contract (see `interoperability_contracts.md` §5), the
|
|
444
|
+
platform stands up a default data activation client named
|
|
445
|
+
`"<Datalake Name> <table> DataActivationClient"` (`is_default:
|
|
446
|
+
true`) for every generic table, so a table is immediately
|
|
447
|
+
ingestable with no extra declaration. To seed rows, discover
|
|
448
|
+
that default DAC by name/`is_default` and `.ingest` through it —
|
|
449
|
+
never hand-create a second DAC (untracked, non-idempotent,
|
|
450
|
+
collides on re-run). See `data_activation_clients.md` §2.
|