@alvera-ai/platform-sdk 0.10.0-rc.9 → 0.12.0

package/.agent/AGENTS.md

@@ -0,0 +1,503 @@
+# AGENTS.md — `@alvera-ai/platform-sdk` corpus
+
+This corpus documents the platform's resource surface. It ships
+inside the npm package and is read directly via `node_modules`
+filesystem walk. Consumers include downstream agents writing
+code in CLIs, React apps, integration test suites, and code
+generators.
+
+> **Wiring this into your project:** run `npx @alvera-ai/platform-sdk
+> llm-export` from your project root to add a pointer to this corpus in
+> your `AGENTS.md` (and a `@AGENTS.md` import in `CLAUDE.md`). Idempotent.
+
+## ⚠ This file is a LOOKUP ONLY. Read the per-kind MD before emitting code.
+
+`AGENTS.md` (this file) is a **DIRECTORY**. It points you to
+per-kind MDs (`tools.md`, `workflows.md`, `data_sources.md`,
+etc.). It is **NOT** a schema reference, and you **CANNOT**
+ground any wire-level claim from this file alone.
+
+### Mandatory protocol before emitting any code that touches a kind
+
+1. **Locate the kind** in the Resources section below.
+2. **Open the kind's MD** (`<kind>.md`).
+3. **Read §1 (Wire shape) and §2 (Rules the type cannot encode)**
+   at minimum.
+4. **Every claim you emit** about wire shape, polymorphism,
+   constraints, enum values, or required fields **MUST be
+   grounded in §1 or §2 of the kind's MD**. If you cannot
+   point at the section, re-read before emitting.
+
+### Failure mode this prevents
+
+The one-line summaries in the Resources section are
+**navigation labels**, not schemas. Example:
+
+> The index line `workflows.md — Filter + decision + action;
+> standard + agent-driven variants` **cannot** tell you whether
+> `variant` is a body field. It is not. `workflows.md` §1 shows
+> the variant is **structural** — an agent-driven workflow simply
+> has one or more AI agents *nested* on its body (the
+> `workflow_ai_agents` array) — **not** a top-level `variant` discriminator.
+
+An agent that paraphrases the index into a wire-level claim is
+**hallucinating**. The index summary is too compressed to encode
+polymorphism, constraints, enum values, or required fields.
+
+### Rule of thumb
+
+Treat index summaries like file names in a directory listing:
+useful for finding the right file, useless as a substitute for
+opening it. If you find yourself emitting a claim about a kind's
+wire shape without having opened that kind's MD in the current
+session, **stop and open it now**.
+
+---
+
+## If you know MCP — vocabulary mapping
+
+The platform's resources don't implement MCP wire format, but
+the conceptual roles map cleanly onto MCP terms. If you've
+landed here from an MCP background, this table tells you which
+corpus page documents the surface you already know:
+
+| MCP concept           | Alvera resource              | Corpus page                                   |
+|-----------------------|------------------------------|-----------------------------------------------|
+| Host                  | The platform itself          | This corpus + `account_management.md`         |
+| Client                | Data Activation Client       | `data_activation_clients.md`                  |
+| Server                | Agentic Workflow             | `workflows.md`                                |
+| Resources             | Datasets (per data domain)   | `generic_tables.md`, `mdm.md`                |
+| Prompts               | Interoperability Contracts   | `interoperability_contracts.md`, `templates.md` |
+| Sampling              | Dataset event triggers       | `data_activation_clients.md` §6.4 logs        |
+| Tools                 | Tool Calls (polymorphic body)| `tools.md`                                    |
+| Roots                 | Datalake boundaries          | `datalakes.md`                                |
+| Human-in-the-loop     | Connected Apps + page tokens | `connected_apps.md`                           |
+| Sandboxed execution   | Liquid + SQL fragment lanes  | `ai_sandbox.md`                               |
+
+A few caveats on the mapping:
+
+- **Capability negotiation is configuration, not runtime
+  handshake.** Tools declare their `intent` and `tool_body_type`
+  at create time; data activation clients declare their bound
+  contracts and tool call shape; workflows declare their event
+  dataset and decision keys. The platform doesn't negotiate
+  these per session — they're fixed by the resource records.
+- **Sampling is lossless, not subscribed.** Dataset events
+  surface through database triggers and per-tenant work queues
+  rather than an MCP-style sampling subscription. Consumers
+  observe outcomes through the log subresource on the data
+  activation client or the workflow, not through a streaming
+  channel.
+- **Roots are the tenancy boundary, full stop.** Cross-datalake
+  reads and writes are physically blocked at the connection
+  layer; a session scoped to one datalake can never reach
+  another tenant's data even if the calling code addresses a
+  different slug.
+
+The rest of this preamble covers the actual SDK auth and client
+construction.
+
+## SDK auth + client construction
+
+The SDK is a strict-TypeScript REST client for the Alvera
+platform. Two-step auth + client construction:
+
+    import {
+      createSession,
+      createIsolatedPlatformApi,
+      type PlatformApi,
+    } from '@alvera-ai/platform-sdk'
+
+    // 1. mint a session
+    const session = await createSession({
+      baseUrl,
+      email,
+      password,
+      tenantSlug,    // optional; omit for tenantless session
+    })
+
+    // 2. build a typed client
+    const api: PlatformApi = createIsolatedPlatformApi({
+      baseUrl,
+      sessionToken: session.sessionToken,
+    })
+
+Sessions come in three scopes:
+- **root** — Alvera root admin; user signup + confirmation
+- **tenantless** — authenticated user with no tenant chosen yet;
+  used once to create a tenant via `api.tenants.create(...)`
+- **tenant-scoped** — the canonical Bearer for tenant operations
+
+Consumers holding multiple concurrent clients in the same file
+(e.g. integration tests that need root + tenantless + tenant-
+scoped APIs concurrently) MUST use `createIsolatedPlatformApi`
+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
+
+```
+   INFRASTRUCTURE  (stood up before data flows)
+   ──────────────
+   datalakes.md                  Storage layer; regulated +
+                                  unregulated tiers.
+   data_sources.md               External ingestion endpoints.
+   tools.md                      Authenticated connections for
+                                  action execution.
+   templates.md                  Platform-shipped Liquid templates
+                                  consumed by other resources.
+   ai_agents.md                  LLM-backed workers.
+   action_status_updaters.md     Polling reconcilers.
+   connected_apps.md             External app bridges.
+   mdm.md                        Entity resolution + identity
+                                  verification across domains.
+   ai_sandbox.md                 Three-layer safety contract
+                                  bounding every AI-authored
+                                  fragment: compliance gates,
+                                  Liquid sandbox, SQL boundary.
+
+   DATA ACTIVATION  (how data flows in)
+   ───────────────
+   generic_tables.md            Schema-on-write tables.
+   interoperability_contracts.md Liquid template mappings.
+   data_activation_clients.md    Ingestion pipelines — both the
+                                  binding row (CRUD) and the
+                                  runtime verbs (.ingest, .ingestFile,
+                                  .runManually, logs, dataset search).
+
+   WORKFLOWS  (composition on top)
+   ─────────
+   workflows.md                  Filter + decision + action;
+                                  standard + agent-driven variants.
+```
+
+Axes are mostly disjoint but a few resources cross. AI Agents
+anchor INFRASTRUCTURE and appear in DATA ACTIVATION (they
+tokenize during ingestion) and WORKFLOWS (workflows invoke
+them). Connected Apps anchor INFRASTRUCTURE and tag into
+WORKFLOWS.
+
+Each resource is exposed via a TypeScript namespace on the
+typed client. The SDK namespace name follows TS conventions
+(camelCase); the corpus MD filename matches the platform's
+wire name (snake_case):
+
+    SDK namespace                       Corpus MD
+    ────────────────────                ───────────────────────────
+    api.datalakes                       datalakes.md
+    api.dataSources                     data_sources.md
+    api.tools                           tools.md
+    api.aiAgents                        ai_agents.md
+    api.actionStatusUpdaters            action_status_updaters.md
+    api.connectedApps                   connected_apps.md
+    api.mdm                             mdm.md
+    api.genericTables                   generic_tables.md
+    api.interoperabilityContracts       interoperability_contracts.md
+    api.dataActivationClients           data_activation_clients.md
+    api.workflows                       workflows.md
+
+## Cookbooks (Golden Path scenarios)
+
+`.agent/cookbook/<slug>.md` files are pure-markdown scenario
+stories — one business outcome each, told as a numbered API-call
+sequence drawn from a green end-to-end vitest scenario in the
+platform's integration-tests suite. Agents read these directly
+from the filesystem at
+`node_modules/@alvera-ai/platform-sdk/.agent/cookbook/`; there
+is no SDK function and no CLI verb that returns cookbook bytes
+at runtime.
+
+Each cookbook structure:
+
+- **Front matter** — `title`, `summary`, `industry`, `slug`,
+  `vitest_source` (list of integration-test files the snippets
+  are lifted from, anchor file first), `status`. The `industry:`
+  field also drives automatic discovery of the per-industry
+  bootstrap setup file at `_setup/<industry>.md` — see
+  "Industry-derived setup files" below.
+- **Problem** — the business-outcome statement in domain terms,
+  sourced from the anchor vitest's behaviour (not from
+  customer-narrative documentation).
+- **Composition** — table of resources provisioned, mapped to
+  the audience skill that owns each (setup / build / compose).
+- **Walkthrough** — numbered `## NNN — <step>` subsections, each
+  carrying one fenced TypeScript block lifted from the anchor or
+  ancillary vitest. State threads forward across subsections via
+  plain JavaScript variables in the validator's generated
+  `describe` closure.
+- **Branches** — alternate paths the anchor vitest covers (a
+  filter rejection, a transport failure, an agent-classification
+  fallback).
+- **Rollback** — teardown order for the resources the cookbook
+  provisioned.
+- **Outcome** — author's prose summary of what the scenario
+  produces.
+- **See also** — links to relevant per-resource reference MDs
+  and to the anchor + ancillary vitest files.
+
+### Industry-derived setup files
+
+Cookbook authoring uses per-industry bootstrap setup files
+under `.agent/cookbook/_setup/<industry>.md` to DRY out the
+auth + tenant + datalake + dataset-seeding steps every
+scenario in an industry shares. The convention matches the
+markdown-doctest ecosystem pattern — setup belongs to a
+scope (the industry), and any cookbook in that scope
+inherits the setup by being there. No per-cookbook opt-in
+field is required.
+
+- Setup files live under `_setup/`. The leading underscore on
+  the directory marks them as fragments (not standalone
+  scenarios); the validator's discovery walk skips them and
+  the corpus index does not list them under "Available
+  cookbooks."
+- The validator reads each scenario cookbook's existing
+  `industry:` front-matter field and auto-discovers the
+  setup file at `_setup/<industry>.md`. A cookbook in an
+  industry that has no setup file gets nothing inlined; the
+  validator does not fail if the setup file is absent.
+  Cookbook authors write no additional front-matter for
+  setup inclusion — the relationship is implicit, by
+  convention.
+- The validator inlines the setup file's numbered `it()`
+  blocks BEFORE the scenario's own numbered `it()` blocks
+  inside the same `describe(...)`. Each `it()` label is
+  prefixed with its source slug so failure output
+  unambiguously points at the file to open (e.g.
+  `_setup/foundation §001 — auth` versus
+  `birthday-greeting-sms-trigger §001 — create workflow`).
+  Cookbook authors keep clean local §001-§00N numbering
+  inside their own markdown.
+- An agent reading a scenario cookbook discovers the matching
+  setup file at the predictable conventional path
+  `_setup/<industry>.md` — one extra file open at a
+  fixed-by-convention location, not via cookbook-specific
+  metadata the agent has to learn.
+
+### Vendored fixtures (Liquid templates, CSV bodies)
+
+End-to-end cookbooks walk the full data-activation chain
+(data source → interoperability contract → Data Activation
+Client → CSV ingest), which requires Liquid templates that
+map inbound rows into the platform's upsert shapes. Inlining
+those templates verbatim inside every cookbook markdown
+bloats each recipe to several hundred lines of Liquid noise
+that obscures the cookbook's lesson. The corpus ships them
+as **vendored fixtures** instead — same pattern the platform
+repo's own integration tests use.
+
+- Fixtures live under
+  `.agent/cookbook/_fixtures/<industry>/`. The leading
+  underscore marks the directory as fragment infrastructure
+  (not a cookbook); the validator's discovery walk skips it.
+  Each `<industry>/` subdirectory carries a `README.md`
+  listing every template + which cookbook consumes it + the
+  production source-of-truth path it was vendored from
+  (`platform/priv/liquid_templates/…`).
+- Cookbook code loads fixtures via the
+  `COOKBOOK_FIXTURES_DIR` environment variable:
+  ```typescript
+  import fs from 'node:fs'
+  import path from 'node:path'
+
+  const LE_TEMPLATE = fs.readFileSync(
+    path.join(
+      process.env.COOKBOOK_FIXTURES_DIR!,
+      'foundation/_lead_submissions_foundation_legal_entity.liquid',
+    ),
+    'utf8',
+  )
+  ```
+  Same env-var pattern as the `ALVERA_BASE_URL` /
+  `ALVERA_ROOT_EMAIL` / `ALVERA_ROOT_PASSWORD` credentials
+  the generated specs already consume.
+  `make validate-cookbook` exports
+  `COOKBOOK_FIXTURES_DIR=<absolute path to _fixtures>` to the
+  spawned `bun test` process; any operator running cookbook
+  code directly from a Bun script must set the same variable.
+- The fixtures ship with the `@alvera-ai/platform-sdk` npm
+  package via the `files: [.agent]` field, so a consumer
+  who installed the package finds the templates at
+  `node_modules/@alvera-ai/platform-sdk/.agent/cookbook/_fixtures/`.
+- An agent reading the corpus discovers vendored templates by
+  directory walk:
+  `_fixtures/` → `<industry>/` → `README.md` lists every
+  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 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 -->
+
+**Healthcare**
+
+- [appointment-review-sms-workflow](./cookbook/appointment-review-sms-workflow.md)
+  — Send a patient review-request SMS after a fulfilled
+  appointment, deep-linked to a connected-app feedback form.
+- [contact-us-triage-with-llm](./cookbook/contact-us-triage-with-llm.md)
+  — Triage inbound contact-us messages into three priority
+  buckets (appointment / job-application / spam) via an LLM
+  agent, route each to a tailored SMS action.
+
+**Accounts Receivable**
+
+- [welcome-sms-for-customers](./cookbook/welcome-sms-for-customers.md)
+  — Send a welcome SMS to newly contracted customers with a
+  self-serve billing-portal link.
+- [dunning-sms-for-delinquent](./cookbook/dunning-sms-for-delinquent.md)
+  — 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**
+
+- [kyc-notification-on-account-activation](./cookbook/kyc-notification-on-account-activation.md)
+  — Send a KYC-notification SMS when a payment account
+  transitions to active status.
+- [sanctions-screening-with-agent-review](./cookbook/sanctions-screening-with-agent-review.md)
+  — Disambiguate gray-zone sanctions screenings via an LLM
+  agent, route confirmed-clean and confirmed-block outcomes to
+  distinct SMS actions.
+
+**Foundation**
+
+- [birthday-greeting-sms-trigger](./cookbook/birthday-greeting-sms-trigger.md)
+  — Send a happy-birthday SMS on each contact's next birthday
+  using a pure-Liquid trigger (year-roll math).
+- [score-leads-with-llm-categorization](./cookbook/score-leads-with-llm-categorization.md)
+  — Score inbound leads into four bands
+  (hot / warm / cold / spam) via an LLM agent, route each band
+  to a tailored SMS action.
+
+<!-- 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).
+- [talk-to-data](./cookbook/talk-to-data.md) — turn a datalake conversational:
+  natural language → reviewable SQL (`datalakes.textToSql`, data-free by
+  construction) → read-only execution returning a `{ data, meta }` row page or a
+  CSV export (`datalakes.executeSql`).
+
+## Utility namespaces
+
+Cross-resource utilities not documented in this corpus:
+
+    api.auth          signUp + auth helpers
+    api.admin         confirmUser + admin actions
+    api.tenants       create + tenant lifecycle
+    api.datasets      cross-resource search / metadata /
+                       user-saved searches
+    api.templates     system-template discovery + per-tenant
+                       metadata
+
+## Resource page structure
+
+Each per-resource MD (e.g. `tools.md`) follows a consistent
+6-section structure: Wire shape, Rules the type cannot encode,
+Field ownership, Error envelopes, Lifecycle, Gotchas.
+
+## Common sections (apply to all resources)
+
+These sibling files cover patterns that apply uniformly across
+all resources. Per-resource MDs reference them by name instead
+of restating:
+
+| Topic                                         | File             |
+|-----------------------------------------------|------------------|
+| Error envelope shape                          | `errors.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` |
+
+## Just getting started?
+
+In your consumer repo, run:
+
+```
+npx @alvera-ai/platform-sdk llm-export
+```
+
+This writes a managed block into your `AGENTS.md` pointing back
+at this corpus, and an `@AGENTS.md` import into `CLAUDE.md` for
+Claude Code compatibility. Re-running replaces only the managed
+block — content outside the markers is preserved.
+
+## Base path
+
+All resources are scoped under a tenant + datalake:
+
+```
+/api/v1/tenants/{tenant_slug}/datalakes/{datalake_slug}/<resource>
+```
+
+The `{tenant_slug}` comes from your authenticated session's
+tenant; the `{datalake_slug}` comes from the response of
+`api.datalakes.create(tenantSlug, body)` (server-derived; never
+pre-compute client-side — see `type_naming.md` "Server-derived
+fields auto-excluded from Writable").