@alvera-ai/platform-sdk 0.19.2 → 0.20.0-next.gcd2f231

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alvera-ai/platform-sdk",
-  "version": "0.19.2",
+  "version": "0.20.0-next.gcd2f231",
   "description": "Typed SDK for the Alvera platform API — manage data sources, tools, generic tables, AI agents, and action status updaters.",
   "type": "module",
   "sideEffects": false,

package/.agent/connected_apps.md

@@ -1,525 +0,0 @@
-# Connected apps
-
-A **connected app** is an external web application registered with
-the platform — typically a customer-facing forms portal hosted on
-Cloudflare Workers / Pages or any other deployment target. The
-platform mints magic links into the app from workflow actions:
-each action renders a URL of the form
-
-```
-   https://<app-primary-url>/t/<short_path>
-```
-
-The customer clicks the link, lands on a route the app discovered
-via `/.well-known/routes.json`, and the app calls back to the
-platform to resolve the page (fetch the underlying message + its
-metadata) and update tracking (opened_at, form_submitted_at).
-
-SDK namespace: `api.connectedApps`.
-
-The namespace splits into **two roles**:
-
-- **Datalake-scoped management** — the admin side. CRUD on the
-  connected-app row, route discovery + sync. Uses the app's
-  UUID `id` as the path key.
-- **Tenant-scoped runtime** — the consumer side. Called BY the
-  connected app itself (authenticated with its auto-provisioned
-  machine-to-machine API key) when a customer hits a magic link. Uses the app's
-  `slug` as the path key.
-
-**Connected apps are single-tenant, full stop.** A connected app
-belongs to exactly ONE tenant (and one datalake under it): its
-auto-provisioned M2M key is tenant-scoped, its magic links resolve
-against that tenant's data, and its publishable browser key carries
-that tenant's origin allowlist. Do NOT design a connected app that
-serves multiple tenants from one deployment — per tenant, register
-a separate connected app (separate keys, separate routes). There is
-no cross-tenant resolution path, by construction.
-
-Connected apps are **Datalake-DB-resident** — the parent datalake
-must be `status: 'ready'` before you `create()`.
-
-## 1. Wire shape
-
-```typescript
-import type {
-  ConnectedAppResponse,
-} from '@alvera-ai/platform-sdk'
-
-const { data: created } = await api.connectedApps.create(
-  tenantSlug,
-  datalakeSlug,
-  {
-    name: 'The Doctors Center',
-    description: 'Patient-facing forms portal',
-    mode: 'self_hosted',                              // 'self_hosted' (only mode active today; see §2)
-    urls: [
-      {
-        url: 'https://the-doctors-center.pages.dev',  // app's deployed origin
-        is_primary: true,                             // exactly one URL must be primary
-        label: 'Production',
-      },
-    ],
-  },
-)
-// created.id, created.slug         — server-derived
-// created.status                   === 'pending' (transient) → 'synced' after route fetch
-// (an M2M key IS auto-provisioned at create (see §2), but its id is NOT
-//  echoed on the resource — no response carries an api_key_id field)
-// created.routes                   — array populated from .well-known/routes.json
-//                                     (empty until first sync)
-// created.last_synced_at           — set when routes successfully validated
-```
-
-The platform validates `/.well-known/routes.json` at the primary
-URL during create. If validation succeeds, routes are saved and
-the status flips to `'synced'`. If it fails, the row persists
-with `status: 'error'` and the failure message in `error`.
-
-## 2. Rules the type cannot encode
-
-### URLs: at least one, exactly one primary
-
-The `urls` array requires at least one entry, and **exactly one
-entry must have `is_primary: true`**. The primary URL is the host
-the platform fetches `/.well-known/routes.json` from and the
-host that magic links are rooted at. Submitting zero primaries
-or multiple primaries returns a 422 on `/urls`.
-
-Additional URLs (staging, preview) are stored for reference but
-aren't used for route discovery or link minting.
-
-**`urls` models environments, NOT tracking domains.** The list is
-production / staging / preview deployments of the *same* app — and the
-one flagged `is_primary` silently becomes the domain of **every** magic
-link this app mints (see §6). It is NOT a way to serve links from
-several tracking domains: to mint links on two different domains you
-need **two connected apps**, one per domain. An agent that sees
-`urls: [...]` and reaches for "add another tracking domain here" gets
-this wrong — reach for a second connected app instead.
-
-### Route discovery is automatic + re-triggerable
-
-```
-/.well-known/routes.json   served by the connected app at its primary URL.
-                            Must return application/json with a JSON array
-                            of route objects:
-
-[
-  { "name": "Review Form",  "path": "/forms/review", "description": "..." },
-  { "name": "CAHPS Survey", "path": "/forms/cahps",  "description": "..." }
-]
-```
-
-Validation rules at fetch time:
-
-- Response content-type must be `application/json`
-- Body must be a JSON array
-- Each route requires `name` (string) and `path` (string);
-  `description` is optional
-
-The platform fetches the manifest at two moments:
-
-1. **At create time** — automatic. Failure flips the row to
-   `status: 'error'` (the row still persists; routes stay empty).
-2. **On explicit `.syncRoutes(id)`** — operator-triggered re-fetch.
-   Updates the saved routes and `last_synced_at`.
-
-The SDK does NOT auto-re-sync routes on a schedule. Re-sync is
-deliberate.
-
-### Modes: only `self_hosted` is active today
-
-```
-mode: 'self_hosted'   active — operator runs the deployment
-                       themselves (e.g. `wrangler deploy`); the
-                       platform registers the resulting URL and
-                       discovers routes from it.
-mode: 'managed'       reserved for a future Cloudflare-Pages
-                       auto-deploy flow. Not provisioned at
-                       runtime today — submitting it succeeds
-                       structurally but no deploy fires.
-```
-
-Treat `'self_hosted'` as the only practical choice for current
-consumers.
-
-### machine-to-machine API key is auto-provisioned
-
-Creating a connected app automatically provisions a machine-to-
-machine API key named `ConnectedApp: <app name>` with the `api`
-role. The key is exposed on the response once (typically rendered
-in the create-flow UI) so the operator can configure it as a
-secret in the deployed app's environment. The platform stores only
-the key's id (`api_key_id` on the response).
-
-The connected app deployment should be configured with:
-
-```
-ALVERA_API_KEY="<auto-provisioned key>"
-ALVERA_DATALAKE_ID="<datalake-uuid>"
-ALVERA_API_URL="https://<platform-host>"
-```
-
-Deleting the connected app deletes the API key.
-
-### `slug` is the runtime reference; `id` is the admin reference
-
-Management endpoints (`list`, `get`, `update`, `syncRoutes`,
-`metadataDetails`) take the UUID `id` as the path key — the
-datalake-scoped admin context.
-
-Runtime endpoints (`resolvePage`, `updateMessageTracking`) take
-the `slug` and skip the datalake path segment entirely. This is
-deliberate: the connected app deployment is authenticated with
-the tenant-scoped machine-to-machine API key and may not know which datalake
-its row lives under.
-
-## 3. Field ownership
-
-**Server-derived (Response-only).** Universal set from
-`type_naming.md`, plus:
-
-```
-status            enum   — 'pending' | 'deploying' | 'deployed' | 'synced' | 'error'
-                            — for the dominant `'self_hosted'` mode the status
-                              flows 'pending' → 'synced' (or 'error' on a
-                              failed route fetch). 'deploying' / 'deployed'
-                              are reserved for the future `'managed'`
-                              Cloudflare-Pages auto-deploy flow (see §2)
-                              and won't appear on self-hosted rows today.
-last_synced_at    string — ISO 8601; set at successful route sync
-error             string — populated when status === 'error'
-routes            array  — discovered from .well-known/routes.json
-                            (each: { name, path, description? })
-```
-
-(The auto-provisioned M2M key's id is **not** among these — neither
-`.get` nor `get-metadata` returns an `api_key_id`. Don't assert on it
-in a contract hook; the key itself reaches the deployment as
-`ALVERA_API_KEY`, §2.)
-
-**Caller-supplied (round-trip).**
-
-```
-name              required string
-description       optional string
-mode              required enum   — 'self_hosted' (only active)
-urls              required array  — see §2; exactly one primary
-```
-
-**Write-only (Request-only).** None. The auto-provisioned API key's
-plaintext value is returned ONCE on the create response (not on
-subsequent reads), but it isn't a "write-only" field in the
-caller-supplied sense.
-
-## 4. Error envelopes
-
-Standard JSON:API envelopes per `errors.md`. Common rejections:
-
-| `source.pointer`              | Cause                                                  |
-|-------------------------------|--------------------------------------------------------|
-| `/urls`                       | empty, missing primary, or multiple primaries          |
-| `/urls/0/url`                 | not a valid URL                                        |
-| `/mode`                       | value not in enum                                      |
-| `/name`                       | uniqueness within datalake — server error literal: "name must be unique within a datalake" |
-
-Route-fetch failures (primary URL unreachable, manifest malformed)
-do NOT reject the create — the row persists with `status: 'error'`
-and `error` populated. Use `.syncRoutes(id)` to retry after fixing
-the deployment.
-
-## 5. Lifecycle
-
-### Create
-
-Synchronous. The platform attempts a single fetch of
-`/.well-known/routes.json` at the primary URL during create.
-Success → `status: 'synced'` and `routes` populated. Failure →
-`status: 'error'` and `error` populated; the row still exists
-and can be retried via `.syncRoutes`.
-
-### Read shapes — management
-
-```
-.list(tenantSlug, datalakeSlug, query?)      Paged: { data, meta }
-                                              (full Flop query — type_naming.md)
-.get(tenantSlug, datalakeSlug, id)           One row, by UUID
-.metadata(tenantSlug, datalakeSlug)          Markdown catalog
-.metadataDetails(tenantSlug, datalakeSlug,   Markdown for one app
-                  id)
-```
-
-### Sync routes
-
-```typescript
-const { data: ack } = await api.connectedApps.syncRoutes(
-  tenantSlug, datalakeSlug, appId,
-)
-// 202 Accepted — the sync runs in a background worker:
-// ack.status            — 'enqueued'
-// ack.job_id            — background job id
-// ack.connected_app_id  — echo of the app id
-// ack.enqueued_at       — enqueue timestamp
-```
-
-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 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'`.
-
-**Route-sync is the only "does this domain work" check the platform
-performs — there is NO DNS verification.** The platform never resolves
-or validates the primary URL's DNS/ownership; it just attempts the
-HTTP fetch of `/.well-known/routes.json`. A `status: 'synced'` means
-"the manifest was fetched and parsed", not "this domain is verified as
-yours". Domain trust is your responsibility, not a platform gate.
-
-Discovery failure modes the platform handles explicitly — each
-leaves the row at `status: 'error'` with `error` populated:
-
-```
-   HTTP 404 from primary URL                — manifest not found
-   HTTP 5xx from primary URL                — server error at the app
-   request timeout                          — primary URL slow / hung
-   TCP connection refused                   — deployment not running
-   response content-type != application/json — wrong endpoint or proxy
-   response body is not a JSON array        — manifest schema wrong
-   route entry missing required `name`      — per-route schema gap
-   route entry missing required `path`      — per-route schema gap
-```
-
-Per-route schema failures stop the sync — the platform validates
-every entry in the array and refuses partial saves. Empty
-manifests (`[]`) succeed with zero routes registered.
-
-The primary URL has a trailing slash stripped before the
-`/.well-known/routes.json` join, so both `https://app.example.com`
-and `https://app.example.com/` produce the same fetch URL.
-
-### Update
-
-`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
-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
-workflow actions first.
-
-Delete latency depends on the app's `mode`:
-
-- `mode: 'self_hosted'` — synchronous. The row is gone when
-  the `delete()` call returns.
-- `mode: 'managed'` — async. The `delete()` response returns
-  immediately, but the actual teardown (Cloudflare Pages
-  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.
-
-## 6. How a tracked link is minted
-
-Before the runtime resolve flow, understand what the platform does at
-fire time to produce the link. When a workflow action that carries a
-`connected_app_id` executes, the platform mints a **page token** and
-injects its URL into the message body:
-
-```
-   action fires
-      │  action.connected_app_id + connected_app_route
-      │  + rendered connected_app_metadata_template (Liquid → JSON)
-      ▼
-   page token row  ── keyed on the MDM SUBJECT id + the route,
-      │              carrying the rendered metadata JSON INSIDE it
-      ▼
-   {{ connected_app_form_url }}  =  https://<primary-url>/t/<url_hash>
-      │  (primary-url = the connected app's is_primary URL)
-      ▼
-   message row created with the link in its body
-      │
-      ▼
-   page token backfilled with that message's id  ← wires token → message
-```
-
-Key consequences to design around:
-
-- **The `connected_app_metadata_template` is how per-recipient data
-  reaches the app without hard-coding a URL.** It's a Liquid template
-  that renders to a JSON object, stored *inside* the page token; the
-  app reads it back at `resolvePage` time (as `page.metadata`) and uses
-  it to prefill / redirect that specific recipient. This is the
-  mechanism for "send each recipient to their own destination" — put
-  the per-recipient values in the metadata template, not in the URL.
-
-- **No MDM subject ⇒ no page token ⇒ no link.** The page token
-  *requires* a subject id (it is keyed on the resolved MDM subject). If
-  the row didn't resolve to a subject, the mint fails — but **the send
-  still goes out**: the mint failure is a logged warning, not an action
-  failure, so `{{ connected_app_form_url }}` simply renders **empty**
-  and the recipient gets a message with a missing link. A
-  message-with-no-link is the symptom of a workflow whose
-  `skip_mdm_resolution` was left `true`, or whose row carries no entity
-  FK (see `workflows.md` §3). If your action mints links, the workflow
-  MUST resolve a subject.
-
-- **Tracked links expire — 7 days by default.** The page token is
-  stamped with a TTL (604,800 s) at mint; `resolvePage` checks
-  `expires_at` and an expired token fails to resolve (HTTP 410).
-  "How long does a campaign link stay live?" — a week, unless the
-  platform default changes. Long-lead campaigns must account for it.
-
-The `{{ connected_app_form_url }}` variable is available only in action
-bodies whose action has a `connected_app_id`; it renders empty
-otherwise.
-
-## 7. Runtime: how magic links resolve
-
-This section covers the runtime callers — the connected app
-deployment itself, not the admin.
-
-At workflow run time, an action with `connected_app_id` +
-`connected_app_route` renders a message body that contains a
-URL of the form:
-
-```
-   https://<primary-url>/t/<short_path>
-```
-
-The customer clicks the link, lands on the app, and the app
-resolves the page:
-
-```typescript
-const { data: page } = await api.connectedApps.resolvePage(
-  tenantSlug, datalakeSlug, slug,                   // tenant + datalake + app slug
-  {
-    short_path: '<the-short-path-from-the-URL>',
-    user_agent: req.headers.get('user-agent') ?? '',
-  },
-)
-// page.message            — the rendered message row
-// page.message.body       — the rendered body, real values (raw lake)
-// page.route_path         — the route the link was minted against
-//                            (e.g. '/forms/review')
-// page.metadata           — parsed `connected_app_metadata_template`
-//                            output from the workflow action; arbitrary JSON
-```
-
-The app routes to the page named by `route_path`, renders the
-form using `metadata` for prefill, and updates tracking when
-the customer opens or submits the form:
-
-```typescript
-await api.connectedApps.updateMessageTracking(
-  tenantSlug, datalakeSlug, slug,
-  {
-    short_path: '<same-short-path>',
-    opened_at: new Date().toISOString(),
-    form_submitted_at: new Date().toISOString(),   // only when form completes
-  },
-)
-```
-
-Both calls are authenticated with the connected app's
-auto-provisioned machine-to-machine API key (typically configured as
-`ALVERA_API_KEY` in the deployment environment). Both are also on
-the `public_api` (publishable-key) allowlist — alongside `ingest`,
-`ingest-file`, and `mdm/verify` — so a browser-side app holding
-only a publishable key can call them.
-
-**This is the engagement seam.** `updateMessageTracking` writes
-`opened_at` / `form_submitted_at` onto the message row — the
-open/click/conversion half of campaign analytics — and it NEVER
-changes `status` (delivery truth belongs to the action status
-updater; see `messages.md` §1 for who writes which field).
-
-### Workflow-side wiring
-
-A workflow action that emits a magic link must set:
-
-```
-connected_app_id                 UUID  — the registered app
-connected_app_route              string — must match a discovered route's path
-                                          (e.g. '/forms/review')
-connected_app_metadata_template  string — Liquid template rendering a JSON
-                                          object the resolved page returns
-                                          to the app (arbitrary shape; the
-                                          app decides how to use it for
-                                          prefill, headers, etc.)
-```
-
-See `workflows.md` §7 for the action-level field detail.
-
-## 8. Gotchas
-
-1. **Exactly one URL must be `is_primary: true`.** Zero or
-   multiple primaries returns 422. The primary is what the
-   platform fetches routes from AND what magic links are minted
-   against; additional URLs are reference-only.
-
-2. **`status: 'error'` after create is recoverable.** A failed
-   route fetch (manifest 404, malformed JSON, primary URL DNS
-   failure) doesn't reject the row. Fix the deployment and call
-   `.syncRoutes(id)` to retry.
-
-3. **Mode `'managed'` is reserved.** It's structurally valid in
-   the request type but no deploy fires today. Use `'self_hosted'`
-   and run your own deployment.
-
-4. **`.syncRoutes` is NOT automatic.** The platform only fetches
-   the manifest at create time and on explicit re-sync. Operators
-   who change their `/.well-known/routes.json` between deploys
-   must trigger a sync.
-
-5. **Runtime calls use `slug`, not `id`.** `.resolvePage` and
-   `.updateMessageTracking` skip the datalake path segment and
-   key on the app's slug + tenant. The auto-provisioned M2M key
-   is tenant-scoped, so the connected-app deployment authenticates
-   without knowing the datalake.
-
-6. **`connected_app_route` on a workflow action must match a
-   discovered route.** Action templates reference
-   `{{ connected_app_form_url }}` which the platform constructs
-   from the bound app's primary URL + the route path. A route
-   that hasn't been synced into the app's `routes` array still
-   accepts the action at create time but the magic-link
-   resolution fails when a customer clicks the link.
-
-7. **The auto-provisioned API key is revealed ONCE.** It appears
-   on the create response and is never returned again. The
-   create-flow caller is responsible for capturing the plaintext
-   value and configuring it into the connected-app deployment's
-   environment. The platform stores only the key id on the row.
-
-8. **Route manifests must be JSON arrays, not objects.** A
-   common mistake is wrapping the routes in `{ "routes": [...] }`
-   — the manifest's top-level must be the array itself.
-
-9. **No MDM subject ⇒ no link (but the message still sends).** Minting
-   a page token needs the resolved MDM subject; if the workflow row
-   didn't resolve one, the mint is skipped with a logged warning and
-   `{{ connected_app_form_url }}` renders empty — the recipient gets a
-   linkless message, not an error. If an action mints links, the
-   workflow must resolve a subject (`skip_mdm_resolution: false` + an
-   entity FK on the row; see `workflows.md` §3). See §6.
-
-10. **Tracked links expire (7-day default TTL).** A page token is valid
-    for 604,800 s from mint; `resolvePage` returns 410 for an expired
-    token. Account for it on long-lead campaigns.
-
-11. **`urls` are environments, not tracking domains.** The `is_primary`
-    URL becomes the domain of every minted link; the others are
-    reference-only. Multiple tracking domains = multiple connected apps
-    (see §2).
-
-12. **No DNS verification exists.** `status: 'synced'` means the
-    manifest was fetched and parsed, not that the domain is verified as
-    yours. Route-sync is the only reachability check the platform runs
-    (see §5).