@alvera-ai/platform-sdk 0.17.0 → 0.18.0

package/.agent/data_activation_clients.md

@@ -38,7 +38,6 @@ const { data: created } = await api.dataActivationClients.create(
     tool_call: { tool_call_type: 'manual_upload' },
     interoperability_contract_ids: [patientContractId, appointmentContractId],
     cron_expressions: [],              // omit for on-demand; e.g. ['0 7,19 * * *']
-    loop_over: [],                     // 'services' | 'locations' | 'providers'
     row_filter: undefined,             // Liquid pre-filter; see §2
     downstream_connection_ids: [],     // DAC chaining; cycle-checked
   },
@@ -75,8 +74,9 @@ Discover it and ingest through it:
 const { data: clients } = await api.dataActivationClients.list(tenantSlug, datalakeSlug)
 // `list` returns the paged envelope { data, meta } — the DAC array is clients.data
 const seedDac = (clients.data ?? []).find(
-  (c) => c.is_default && c.name.endsWith('customer DataActivationClient'),
+  (c) => c.is_default && (c.name ?? '').endsWith('customer DataActivationClient'),
 )
+if (!seedDac?.slug) throw new Error('no default activation client for that table')
 // ingest is SLUG-keyed (see §6) — pass seedDac.slug, not seedDac.id
 await api.dataActivationClients.ingest(tenantSlug, datalakeSlug, seedDac.slug, { data: row })
 ```
@@ -203,7 +203,8 @@ response_extractor              optional embed — TemplateConfig ({ type, body
                                   a Liquid template that unwraps a nested API
                                   envelope into the row array (e.g.
                                   `{{ msg.data | to_json }}`). Load-bearing for
-                                  `rest_api` fetch DACs; see `rest-fetch.md` §004
+                                  `rest_api` fetch clients; see
+                                  `cookbook/subscription-saas.md` §032–035
 ```
 
 **Write-only (Request-only).** None — every caller-supplied
@@ -429,7 +430,7 @@ rows_ingested       number — count of top-level rows the contract emitted
 dataset_updated     number — count of dataset rows whose batch_id this run wrote
                               (load-bearing: see Gotcha 7)
 output_files        { object_key, mode }[] — merged ndjson archive refs, one per
-                                bucket; mode is 'regulated' | 'unregulated'
+                                bucket; mode is 'raw' | 'tokenized' | 'redacted'
                                 (empty until the post-batch merge worker commits).
                                 NOT a string[] — each entry is an embed object;
                                 use /logs/:id/download to fetch a presigned URL
@@ -483,12 +484,12 @@ durable" signal — not just the presence of the log row.
 >
 > ```typescript
 > const { data: probe } = await api.datalakes.executeSql(tenantSlug, datalakeSlug, {
->   sql: `SELECT 1 FROM patients WHERE batch_id = '${batchId}' LIMIT 1`,
->   mode: 'unregulated',
+>   sql: `SELECT 1 FROM ${tableName} WHERE batch_id = '${batchId}' LIMIT 1`,
+>   mode: 'raw',
 > })
 > // `data` is an array-of-arrays (a `string` only for { format: 'csv' });
-> // a non-empty page proves the batch landed. Reference the unregulated
-> // table by its base name — `mode: 'regulated'` uses the `regulated_` prefix.
+> // a non-empty page proves the batch landed. The table is named the same
+> // in every lake — `mode` selects which copy answers, not which name.
 > const landed = typeof probe !== 'string' && probe.data.length > 0
 > ```
 >
@@ -507,7 +508,7 @@ default — the datalake is mandatory and explicit, mirroring
 
 ```typescript
 // (1) POST creates a user search and runs the underlying SQL
-//     synchronously against the regulated schema. The result
+//     synchronously against the raw lake. The result
 //     set is materialised server-side and identified by the
 //     returned UUID.
 const { data: search } = await api.datasets.createUserSearch(
@@ -516,24 +517,32 @@ const { data: search } = await api.datasets.createUserSearch(
   'patient',                                              // dataset name
   {
     search_query: `ri.value = '${externalPatientId}'`     // SQL WHERE-clause fragment
-                   + ` AND rp.batch_id = '${batchId}'`,
+                   + ` AND le.batch_id = '${batchId}'`,
   },
 )
 // search.id            — UUID of the materialised result set
-// search.status        — 'completed' on success; 'failed' surfaces error_message
+// search.status        — 'new' | 'in_progress' | 'completed' | 'error'.
+//                        The failure member is 'error', NOT 'failed' — and it is
+//                        'error' that carries error_message. There is no 'failed'.
 // search.results_count — ALWAYS null on the POST response (see Gotcha 5)
 
 // (2) GET paginates rows from the materialised result set.
-//     dataAccessMode selects the storage tier:
-//       'regulated'   — raw values verbatim (PHI/PII intact)
-//       'unregulated' — tokenized columns return as
-//                       { redacted_data, token, type } objects;
-//                       plain columns return as their primitive type
+//     dataAccessMode selects which lake answers:
+//       'raw'       — real values verbatim
+//       'tokenized' — masked columns return a stable tok_<hash>
+//       'redacted'  — masked columns return an unjoinable placeholder
+// `search.id` is `string | undefined` on the response type, and
+// `DatasetSearchOptions.userSearchId` is declared `?: string` — optional, but
+// NOT `| undefined`. So an app with `exactOptionalPropertyTypes` will not
+// compile the shorthand, and an app without it gets a runtime 404 that reads
+// like a wrong path. Narrow it first.
+if (!search.id) throw new Error(`createUserSearch returned no id (status ${search.status})`)
+
 const { data: page } = await api.datasets.search(
   tenantSlug,
   datalakeSlug,
   'patient',
-  { userSearchId: search.id, dataAccessMode: 'unregulated' },
+  { userSearchId: search.id, dataAccessMode: 'tokenized' },
 )
 // page.data — array of rows
 // page.meta — pagination
@@ -541,50 +550,54 @@ const { data: page } = await api.datasets.search(
 
 #### SQL aliases
 
-`createUserSearch` accepts a WHERE-clause fragment against a
-fixed set of table aliases. Each dataset has a base alias for its
-primary regulated table, plus `ri` for the regulated_identifiers
-join. **The base alias is assigned by that dataset's server-side
-decomposed query — it is NOT derivable from the dataset name, and
-different datasets reuse the same letters.** Verified examples:
+`createUserSearch` accepts a WHERE-clause fragment against a fixed set
+of server-assigned table aliases. **The alias is assigned by the
+dataset's server-side decomposed query — it is not derivable from the
+dataset name**, so confirm it rather than guessing:
 
 ```
-patient        → rp  (regulated_patients)  + ri
-appointment    → ra  (regulated_appointments) + ri
-customer       → ra  (regulated_customers)  + ri   ← 'ra', NOT 'rc'
+legal_entity      → le
+message           → m
+action_log        → al
+document          → d
+beneficial_owner  → bo
 ```
 
-`customer` is a live trap: its primary table is aliased `ra`, not
-`rc` (both `rest-fetch.md` §006 and `bulk-ingest.md` §008 query it as
-`ra.batch_id`). Don't guess the alias from the dataset name — confirm
-it from the dataset's green cookbook/test before writing the fragment.
-The `ri.value` predicate filters on external identifiers (the values
-your inbound rows carried); the `<base_alias>.batch_id` predicate
-scopes the search to one run.
+GH-859 removed the per-domain datasets this list used to name —
+`patient`, `appointment`, `customer` and their `regulated_*` tables
+are gone, and with them the `rp` / `ra` / `rc` aliases. **A customer,
+a patient or an appointment is now a generic table you declare, plus
+the legal entity its rows resolve to**; there is no dataset of that
+name to search. The four cookbooks all take this shape.
 
-#### Tokenized vs plain column shape
+The `<alias>.batch_id` predicate scopes a search to one run, which is
+the usual reason to reach for this surface at all.
 
-In `dataAccessMode: 'unregulated'`, tokenized columns surface
-as objects, NOT primitives:
+#### What a masked column looks like coming back
 
-```typescript
-{
-  redacted_data: '*****',    // server-redacted preview
-  token:         'tk_...',   // stable opaque token
-  type:          'string'    // original column's logical type — one of:
-               | 'text'      //   'string' / 'text': free-form text content
-               | 'email'     //   'email': RFC 5322 email
-               | 'phone'     //   'phone': E.164 / display phone number
-               | 'date'      //   'date': ISO 8601 date
-               | 'image',    //   'image': image file reference
-}
+**Every column comes back as a plain value of its own type, in every
+mode.** A masked column is a string; it is not wrapped in an object.
+
+Measured on a live three-lake tenant, the same `first_name` read three
+ways through `datasets.search`:
+
+```
+   raw        "Teodoro"
+   tokenized  "tok_def1e9dd0d0d276ea8e39f885790f5ad"
+   redacted   "xxxx-oro"
 ```
 
-Plain columns (non-tokenized) surface as the same primitive
-the regulated schema stores. A consumer code path that
-unconditionally treats every field as a string will crash on
-tokenized columns — type-check `typeof row.field === 'object'`
-first.
+An older version of this guide described tokenized columns arriving as
+`{ redacted_data, token, type }` objects and told consumers to branch on
+`typeof row.field === 'object'`. That branch can never be taken. If you
+are carrying such a guard, it is dead code — and worse, the `else` arm
+it guards is the one doing all the work.
+
+The two masked forms differ in what they are *for*. `tok_<hash>` is
+stable, so the same input yields the same token and a machine can join
+on it across tables without ever resolving it. `xxxx-<tail>` is
+deliberately unjoinable — a placeholder for a person glancing at a
+screen. Pick the mode by which of those two readers you are serving.
 
 ## 7. Gotchas