@alvera-ai/platform-sdk 0.10.0-rc.23 → 0.10.0-rc.25

package/.agent/AGENTS.md

@@ -135,6 +135,26 @@ rather than the singleton `createPlatformApi`. The singleton
 mutates a shared client; the most-recent construction call
 clobbers earlier instances' auth.
 
+## Using this corpus: building an app vs. writing a test
+
+The `api.*` call sequences in this corpus are framework-agnostic — the
+**same** code powers all of these:
+
+- **A React / CopilotKit app** — call `api.workflows.create(...)`,
+  `api.dataActivationClients.ingest(...)`, etc. from an event handler, a
+  server action, or a CopilotKit action; render the typed response.
+- **A backend / Bun / Node script** — drive the client straight through.
+- **A vitest / integration test** — thread the same calls through a test
+  closure, asserting on each typed response.
+
+What changes between them is only *where you put the calls* (a component
+handler vs. a test body), never the calls themselves. The cookbooks under
+`cookbook/` read as test-style sequences because that is how they are
+validated, but every step is a plain `api.*` call you can lift into an app
+unchanged. The per-capability docs (e.g. `bulk-ingest.md`, `ai-agent-invoke.md`)
+show one capability at a time; the cookbooks weave capabilities into a
+business outcome.
+
 ## Resources
 
 ```
@@ -326,15 +346,27 @@ repo's own integration tests use.
   template plus the cookbooks that depend on it. No need to
   read cookbook code first to know what fixtures exist.
 
+### Two kinds of doc here: business cookbooks vs. capability docs
+
+The `cookbook/` directory holds two kinds of recipe, both validated by
+`make validate-cookbook`:
+
+- **Business cookbooks** (`<use-case>.md`) — one real business outcome each,
+  told as a numbered API-call sequence (e.g. `welcome-sms-for-customers`,
+  `dunning-sms-for-delinquent`). Read these to see how resources compose into
+  an outcome.
+- **Capability docs** (`<capability>.md`) — one platform capability each,
+  shown as the minimal call sequence that proves it (e.g. `bulk-ingest`,
+  `ai-agent-invoke`, `custom-tables`, `invite-team`). Read these to learn one
+  capability in isolation; cookbooks weave them into outcomes.
+
 ### Available cookbooks
 
-The eight cookbook scenarios shipped at v0.10. Each is anchored
-to a green end-to-end vitest scenario in the platform's
-integration-tests suite and is verified at dev time by
-`make validate-cookbook` at the platform-sdk repo root (not a
-CLI verb). The entries between the managed markers below are
-what Milestone 12's `alvera-sdk-init` lifts into consumer
-`<cwd>/AGENTS.md` files as a managed block.
+The nine business-cookbook scenarios. Each is anchored to a green
+end-to-end vitest scenario in the platform's integration-tests suite and is
+verified at dev time by `make validate-cookbook` at the platform-sdk repo root.
+The entries between the managed markers below are what `alvera-sdk-init` lifts
+into consumer `<cwd>/AGENTS.md` files as a managed block.
 
 <!-- BEGIN:cookbook-index -->
 
@@ -357,6 +389,10 @@ what Milestone 12's `alvera-sdk-init` lifts into consumer
   — Send a payment-reminder SMS to delinquent customers
   (filtered on phone-on-file and tax-id-verified) with a
   pay-invoice link.
+- [triage-prospects-by-priority](./cookbook/triage-prospects-by-priority.md)
+  — Triage inbound AR customers into priority bands
+  (high / medium / low) via an LLM agent, route each band to a
+  tailored SMS action.
 
 **Payment Risk**
 
@@ -380,6 +416,29 @@ what Milestone 12's `alvera-sdk-init` lifts into consumer
 
 <!-- END:cookbook-index -->
 
+### Capability docs
+
+One platform capability each — the minimal call sequence that proves it,
+anchored to a green vitest scenario. Read the matching reference MD for the
+full wire shape.
+
+- [bulk-ingest](./cookbook/bulk-ingest.md) — load a whole file of records in
+  one upload (presigned link → PUT → `ingestFile` → search by batch).
+- [rest-fetch](./cookbook/rest-fetch.md) — pull records from a third-party REST
+  API on demand (Bearer + OAuth2), no file upload.
+- [ai-agent-invoke](./cookbook/ai-agent-invoke.md) — read an uploaded
+  document/image and pull structured JSON out of it (`aiAgents.invoke` with
+  files). The correct file-vision path — the agent reads the file; the DAC
+  ingests it.
+- [custom-tables](./cookbook/custom-tables.md) — stand up a custom table the
+  built-in datasets don't model; deploy → ingest → search.
+- [action-status-updaters](./cookbook/action-status-updaters.md) — reconcile
+  the delivery status of messages you send, on a schedule.
+- [system-templates](./cookbook/system-templates.md) — discover the platform's
+  built-in row-mapping Liquid templates.
+- [invite-team](./cookbook/invite-team.md) — invite a teammate into your tenant
+  (root / tenantless / tenant-scoped sessions in one flow).
+
 ## Utility namespaces
 
 Cross-resource utilities not documented in this corpus:
@@ -407,7 +466,7 @@ of restating:
 | Topic                                         | File             |
 |-----------------------------------------------|------------------|
 | Error envelope shape                          | `errors.md`      |
-| Mutations (PUT and limited exceptions)        | `mutations.md`   |
+| Mutations (`update()` replaces whole; exceptions) | `mutations.md` |
 | Async + readiness                             | `async.md`       |
 | Debugging (HTTP interceptor + safe redaction) | `debugging.md`   |
 | Type naming + server-derived fields           | `type_naming.md` |

package/.agent/account_management.md

@@ -293,7 +293,7 @@ carry through unchanged.
 The Invitation/Membership schema (Vocabulary A) is the
 coarse-grained role assignment surfaced at invite time. The
 Role-record system (Vocabulary B) is the fine-grained policy
-entity that drives Postgres RLS and permission checks at every
+entity that drives row-level access and permission checks at every
 request. They co-exist because the invitation captures the
 caller's intent ("admin-tier user"), while the role record
 captures the platform's enforcement vocabulary
@@ -307,9 +307,10 @@ sessions appear in console-mediated flows and are uncommon in
 SDK-consumer code.
 
 Reserved roles (`platform_admin`, `system`, `system_api`,
-`bot_*`) bypass tenant-based RLS and are created only via DB
-migrations — they never appear on consumer-minted sessions or
-invitations and are out of scope for SDK consumers.
+`bot_*`) bypass tenant-based access isolation and are
+provisioned only by the platform itself — they never appear on
+consumer-minted sessions or invitations and are out of scope
+for SDK consumers.
 
 ### Inviting humans into a tenant
 

package/.agent/action_status_updaters.md

@@ -15,7 +15,7 @@ SDK namespace: `api.actionStatusUpdaters`.
 
 Action status updaters are **Datalake-DB-resident** — the
 parent datalake must be `status: 'ready'` and every
-referenced tool must exist before POST.
+referenced tool must exist before you `create()`.
 
 ## 1. Wire shape
 
@@ -213,13 +213,15 @@ branch.
 
 ### Update
 
-`PUT` replays the full body. The polymorphic `updater_body`
-must keep the same `updater_body_type` on update — changing
-the discriminator requires delete + recreate.
+`update()` replaces the whole resource — resupply the full
+body; there's no partial update. The polymorphic `updater_body`
+must keep the same `updater_body_type` on update — the
+discriminator can't change on `update()`; to change body type,
+`delete()` and `create()` fresh.
 
 ### Delete
 
-`DELETE` removes the row and cancels future scheduled polls.
+`delete()` removes the row and cancels future scheduled polls.
 In-flight polls complete; their writebacks land normally.
 
 The delete is **graceful** with respect to scheduler state: if

package/.agent/ai_agents.md

@@ -11,7 +11,7 @@ SDK namespace: `api.aiAgents`.
 
 AI agents are **Datalake-DB-resident** — the parent datalake
 must be `status: 'ready'` and the bound tool must exist before
-POST.
+you `create()`.
 
 ## 1. Wire shape
 
@@ -188,9 +188,9 @@ namespace clean.
 
 An agent runs as an **enrichment** step on a workflow or an
 interoperability contract. The agent is **nested directly on the
-parent body** — `agentic-workflows` and `interoperability-contracts`
-create/PUT bodies accept a `workflow_ai_agents` /
-`interoperability_contract_ai_agents` array (a `cast_assoc`). There is
+parent body** — workflow and interoperability-contract
+create/update bodies accept a `workflow_ai_agents` /
+`interoperability_contract_ai_agents` array. There is
 no separate attach/detach endpoint, and **no per-join checksum**: the
 nested agents fold into the parent's own checksum.
 
@@ -225,24 +225,26 @@ workflow.checksum   // the PARENT checksum — the nested agents fold into it
 ```
 
 Interoperability contracts nest the same way, via the
-`interoperability_contract_ai_agents` array on the contract create/PUT
-body. The one difference: a contract join's `context_mapping_config`
-**does** carry `output_schema` (the server does not pin it there).
+`interoperability_contract_ai_agents` array on the contract
+create/update body. The one difference: a contract join's
+`context_mapping_config` **does** carry `output_schema` (the server
+does not pin it there).
 
-Adding, repositioning, and removing agents are all expressed as a
-**full-set PUT** on the parent (`on_replace: :delete`):
+Adding, repositioning, and removing agents are all expressed by
+re-supplying the full set on the parent's `update()` — `update()`
+replaces the whole array, and any item you omit is removed:
 
 | Operation  | How                                                  | Result |
 |------------|------------------------------------------------------|--------|
-| add / nest | include in `*_ai_agents` on create or PUT            | parent checksum reflects the agents |
-| reposition | PUT with the same agent at a new `position`          | full-set replace |
-| detach     | PUT omitting that agent (or `[]` to clear all)       | `on_replace: :delete` removes it |
+| add / nest | include in `*_ai_agents` on create or update         | parent checksum reflects the agents |
+| reposition | `update()` with the same agent at a new `position`   | full-set replace |
+| detach     | `update()` omitting that agent (or `[]` to clear all)| the omitted agent is removed |
 | drift      | parent `checksum()` endpoint over the full body      | the would-be parent checksum (no persist) |
 
-The parent surfaces its nested agents on GET: a workflow GET returns
-`workflow_ai_agents: [...]` and a contract GET returns
+The parent surfaces its nested agents on read: a workflow `get()`
+returns `workflow_ai_agents: [...]` and a contract `get()` returns
 `interoperability_contract_ai_agents: [...]`. Both arrays are writable
-on the parent body (create + PUT).
+on the parent body (create + update).
 
 The workflow's own `decision_config` reads the agent's parsed output
 at `additional_context.<agent_slug>.<field>` (property paths match the
@@ -344,14 +346,15 @@ templates).
 
 ### Update
 
-`PUT` replays the full body — no PATCH. Replace-on-PUT means
-all required fields must be re-supplied verbatim, including
+`update()` replaces the whole resource — resupply the full
+body; there's no partial update. That means all required
+fields must be re-supplied verbatim, including
 `input_schema`, `llm_response_schema`, and `prompt_config`.
 Omitting any returns a 422.
 
 ### Delete
 
-`DELETE` removes the row. Workflows that still reference the
+`delete()` removes the row. Workflows that still reference the
 agent in their `ai_agents` array fail at run time with
 `error_code: 'ai_agent_not_found'`; clean up workflow
 references first.
@@ -436,13 +439,14 @@ with `{ status: 'skipped' }` and no per-agent entries.
    workflow decision and action templates reference. Capture it
    from the create response — don't pre-compute.
 
-4. **`.get` takes UUID `id`, not slug.** The SHOW route is
-   `/ai-agents/:id`. The slug is only a runtime template key.
+4. **`.get` takes UUID `id`, not slug.** The single-row read
+   route is `/ai-agents/:id`. The slug is only a runtime template key.
 
-5. **Replace-on-PUT.** Update bodies must re-supply
-   `input_schema`, `llm_response_schema`, `prompt_config`
-   verbatim. Partial PUT silently drops fields and returns
-   422 on the missing required field.
+5. **`update()` replaces the whole resource.** Update bodies
+   must re-supply `input_schema`, `llm_response_schema`,
+   `prompt_config` verbatim — there's no partial update. A
+   partial body silently drops fields and returns 422 on the
+   missing required field.
 
 6. **`data_access` is immutable post-create.** Flipping the
    compliance tier requires delete + recreate.

package/.agent/async.md

@@ -70,7 +70,7 @@ the table above, its MD is authoritative.
 
 Downstream operations (creating child resources, running
 workflows, invoking tools) MUST NOT proceed until the parent
-resource is in a terminal-success status. Posting a child
+resource is in a terminal-success status. Creating a child
 resource against an unready parent typically surfaces as a
 500 (server-internal) or a 422 with a "parent not ready"
 detail — both are recoverable but indicate a missing wait in
@@ -78,11 +78,12 @@ the caller.
 
 ## Idempotency on create
 
-POST creates are NOT idempotent by default. Repeating a POST
-with the same body yields a 422 on uniqueness fields (typically
-the name within scope). Consumers handling retry should:
+`create()` calls are NOT idempotent by default. Repeating a
+`create()` with the same body yields a 422 on uniqueness fields
+(typically the name within scope). Consumers handling retry
+should:
 
-1. Catch the post-HTTP throw (see `errors.md`).
+1. Catch the thrown error after the call returns (see `errors.md`).
 2. Inspect for a uniqueness `detail` on a `source.pointer`
    that names the uniqueness key (usually `/name` or `/slug`).
 3. Treat as "already created" and fetch the existing row.
@@ -94,8 +95,8 @@ to the server but failed to capture the response locally).
 
 ## Polling cost
 
-Polling at 1s intervals against the platform's
-`/<resource>/:slug` endpoint is cheap for most resources but
+Polling at 1s intervals via `get()` on the resource is cheap
+for most resources but
 becomes expensive at high concurrency. For long-running
 operations (lambda deployments, large data-activation-client
 runs), back off the interval (e.g. 2s → 5s → 10s) after the
@@ -103,7 +104,7 @@ first ~30s of waiting.
 
 ## What the SDK does NOT auto-poll
 
-The typed client returns the immediate POST response — it
+The typed client returns the immediate `create()` response — it
 does NOT block until the resource reaches terminal status.
 Consumers explicitly write the wait loop above where it
 matters. This is intentional: not every caller wants to

package/.agent/connected_apps.md

@@ -28,7 +28,7 @@ The namespace splits into **two roles**:
   `slug` as the path key.
 
 Connected apps are **Datalake-DB-resident** — the parent datalake
-must be `status: 'ready'` before POST.
+must be `status: 'ready'` before you `create()`.
 
 ## 1. Wire shape
 
@@ -241,9 +241,9 @@ const { data: ack } = await api.connectedApps.syncRoutes(
 
 This is the explicit "re-fetch and save" verb — asynchronous. The
 202 acknowledgement proves the app id resolved and a sync job was
-accepted; the worker then refreshes `routes` + `last_synced_at` and
-lands `status: 'synced'` (or `'error'`) on the app row. Poll
-`.get()` for the outcome. Use it after deploying a new manifest,
+accepted; the platform then refreshes `routes` + `last_synced_at` and
+lands `status: 'synced'` (or `'error'`) on the app row asynchronously.
+Poll `.get()` for the outcome. Use it after deploying a new manifest,
 fixing a primary URL outage, or recovering from `status: 'error'`.
 
 Discovery failure modes the platform handles explicitly — each
@@ -270,13 +270,14 @@ and `https://app.example.com/` produce the same fetch URL.
 
 ### Update
 
-`PUT` replays the full body. Mutating the primary URL does NOT
-auto-trigger a route sync — call `.syncRoutes` after the update if
-the new primary URL serves a different manifest.
+`update()` replaces the whole resource — resupply the full
+body; there's no partial update. Mutating the primary URL does
+NOT auto-trigger a route sync — call `.syncRoutes` after the
+update if the new primary URL serves a different manifest.
 
 ### Delete
 
-`DELETE` removes the connected app AND the auto-provisioned API
+`delete()` removes the connected app AND the auto-provisioned API
 key. Workflows that still reference the app's id in action
 `connected_app_id` fields fail at run time with the action's
 template-render step erroring on the missing relation. Detach
@@ -285,11 +286,11 @@ workflow actions first.
 Delete latency depends on the app's `mode`:
 
 - `mode: 'self_hosted'` — synchronous. The row is gone when
-  the DELETE response returns.
-- `mode: 'managed'` — async. The DELETE response returns
+  the `delete()` call returns.
+- `mode: 'managed'` — async. The `delete()` response returns
   immediately, but the actual teardown (Cloudflare Pages
-  project deletion + DNS unregistration) runs in a background
-  worker. The row's `status` transitions through
+  project deletion + DNS unregistration) runs in the background.
+  The row's `status` transitions through
   `'deploying'` (during teardown) before disappearing. Poll
   `.get()` until 404 to confirm removal.
 

package/.agent/cookbook/_fixtures/README.md

@@ -1,12 +1,16 @@
 # Cookbook fixtures
 
-Vendored Liquid templates and CSV fixtures the
-[cookbook recipes](../) load at runtime via
+Vendored Liquid templates, CSV bodies, and sample documents the
+[cookbook recipes](../) and [capability docs](../) load at runtime via
 `fs.readFileSync`. Organized by industry so the corpus stays
 self-describing — an agent crawling this directory can list
-every template available to every cookbook in a given industry
+every fixture available to every recipe in a given industry
 by reading one path.
 
+Two kinds of fixture live here: **Liquid templates** (row-mapping
+templates an interoperability contract loads) and **data fixtures**
+(CSV bodies and sample PDFs/images a capability walk uploads or ingests).
+
 ## Convention
 
 Cookbook code reads fixtures via the
@@ -77,6 +81,8 @@ passes against the new template shape.
 | `_cahps_appointments_healthcare_patient.liquid` | `appointment-review-sms-workflow` | `priv/liquid_templates/data_activation/interoperability/healthcare/fhir4/athena/_cahps_appointments_healthcare_patient.liquid` |
 | `_cahps_appointments_healthcare_appointment.liquid` | `appointment-review-sms-workflow` | `priv/liquid_templates/data_activation/interoperability/healthcare/fhir4/athena/_cahps_appointments_healthcare_appointment.liquid` |
 | `_cahps_appointments_healthcare_mdm.liquid` | `appointment-review-sms-workflow` | `priv/liquid_templates/data_activation/interoperability/healthcare/fhir4/athena/_cahps_appointments_healthcare_mdm.liquid` |
+| `sample_two_page.pdf` (data) | `ai-agent-invoke` | `integration-tests/tests/healthcare/fixtures/documents/sample_two_page.pdf` |
+| `memorandum-of-association-01.png` (data) | `ai-agent-invoke` | `integration-tests/tests/healthcare/fixtures/documents/memorandum-of-association-01.png` |
 
 The `contact-us-triage-with-llm` cookbook ingests into a generic
 table via the auto-provisioned identity contract, so it loads no
@@ -86,8 +92,9 @@ vendored template.
 
 | File | Consumed by cookbook(s) | Source-of-truth |
 |---|---|---|
-| `_customers_accounts_receivable_customer.liquid` | `welcome-sms-for-customers`, `dunning-sms-for-delinquent` | `priv/liquid_templates/data_activation/interoperability/accounts_receivable/stripe/_customers_accounts_receivable_customer.liquid` |
-| `_customers_accounts_receivable_mdm.liquid` | `welcome-sms-for-customers`, `dunning-sms-for-delinquent` | `priv/liquid_templates/data_activation/interoperability/accounts_receivable/stripe/_customers_accounts_receivable_mdm.liquid` |
+| `_customers_accounts_receivable_customer.liquid` | `welcome-sms-for-customers`, `dunning-sms-for-delinquent`, `bulk-ingest`, `rest-fetch` | `priv/liquid_templates/data_activation/interoperability/accounts_receivable/stripe/_customers_accounts_receivable_customer.liquid` |
+| `_customers_accounts_receivable_mdm.liquid` | `welcome-sms-for-customers`, `dunning-sms-for-delinquent`, `bulk-ingest`, `rest-fetch` | `priv/liquid_templates/data_activation/interoperability/accounts_receivable/stripe/_customers_accounts_receivable_mdm.liquid` |
+| `stripe_customers_batch1.csv` (data) | `bulk-ingest` | `integration-tests/tests/accounts_receivable/fixtures/csv/stripe_customers_batch1.csv` |
 
 ### `payment_risk/`
 

package/.agent/cookbook/_fixtures/accounts_receivable/stripe_customers_batch1.csv

@@ -0,0 +1,5 @@
+customer_number,customer_type,status,name,email,phone,tax_id,currency,delinquent,tax_exempt,preferred_locales,address_line1,address_line2,address_city,address_state,address_postal_code,address_country,shipping_name,shipping_phone,shipping_address_line1,shipping_address_line2,shipping_address_city,shipping_address_state,shipping_address_postal_code,shipping_address_country
+CUS-10001,individual,contracted,James Whitfield,james.whitfield@gmail.com,+12025551001,123-45-6789,USD,false,none,en,742 Evergreen Terrace,,Springfield,IL,62704,US,James Whitfield,+12025551001,742 Evergreen Terrace,,Springfield,IL,62704,US
+CUS-10002,individual,contracted,Maria Garcia,maria.garcia@outlook.com,+12025551002,,EUR,false,none,en|es,89 Elm Street,Apt 4B,Miami,FL,33101,US,Maria Garcia,+12025551002,89 Elm Street,Apt 4B,Miami,FL,33101,US
+CUS-10003,enterprise,contracted,Pinnacle Financial Group,info@pinnaclefg.com,+12125559000,84-2156789,USD,false,exempt,en,1 Wall Street,Floor 42,New York,NY,10005,US,,,,,,,,,
+CUS-10004,individual,prospect,Chen Wei,chen.wei@protonmail.com,+14155551004,,USD,false,none,en|zh,350 Mission Street,,San Francisco,CA,94105,US,,,,,,,,,

package/.agent/cookbook/_fixtures/healthcare/sample_two_page.pdf

@@ -0,0 +1,43 @@
+%PDF-1.4
+1 0 obj
+<< /Type /Catalog /Pages 2 0 R >>
+endobj
+2 0 obj
+<< /Type /Pages /Kids [3 0 R 5 0 R] /Count 2 >>
+endobj
+3 0 obj
+<< /Type /Page /Parent 2 0 R /MediaBox [0 0 300 200] /Resources << /Font << /F1 7 0 R >> >> /Contents 4 0 R >>
+endobj
+4 0 obj
+<< /Length 45 >>
+stream
+BT /F1 24 Tf 40 110 Td (Page One Hello) Tj ET
+endstream
+endobj
+5 0 obj
+<< /Type /Page /Parent 2 0 R /MediaBox [0 0 300 200] /Resources << /Font << /F1 7 0 R >> >> /Contents 6 0 R >>
+endobj
+6 0 obj
+<< /Length 45 >>
+stream
+BT /F1 24 Tf 40 110 Td (Page Two World) Tj ET
+endstream
+endobj
+7 0 obj
+<< /Type /Font /Subtype /Type1 /BaseFont /Helvetica >>
+endobj
+xref
+0 8
+0000000000 65535 f 
+0000000009 00000 n 
+0000000058 00000 n 
+0000000121 00000 n 
+0000000247 00000 n 
+0000000342 00000 n 
+0000000468 00000 n 
+0000000563 00000 n 
+trailer
+<< /Size 8 /Root 1 0 R >>
+startxref
+633
+%%EOF