@alvera-ai/platform-sdk 0.17.0 → 0.18.0

package/.agent/cookbook/generic-tables.md

@@ -1,244 +0,0 @@
----
-title: "Capability: stand up a generic table the platform doesn't model"
-summary: A capability walk for generic tables. Create a generic table with typed, privacy-tagged columns (`api.genericTables.create`), wait for it to deploy, use the default ingestion client the platform auto-provisions for it, ingest a row (`api.dataActivationClients.ingest`), and read it back with read-only SQL (`api.datalakes.executeSql`). For data the built-in datasets don't cover.
-industry: subscription
-slug: generic-tables
-vitest_source:
-  - integration-tests/tests/subscription/generic-tables.test.ts
-  - integration-tests/tests/subscription/bootstrap.test.ts
-status: green
----
-
-# Capability
-
-**What you get:** a first-class dataset for data the platform's built-in
-datasets (customer, message, …) don't model — defined by you, deployed by the
-platform, and queryable like any other dataset.
-
-The lifecycle is:
-
-1. `genericTables.create(...)` — declare the table: a title and typed columns,
-   each with a `privacy_requirement` (`none` / `tokenize` / `redact_only`).
-2. The platform deploys it asynchronously (`status: 'new'` → `'deployed'`) and
-   **auto-provisions a default Data Activation Client** bound to an identity
-   contract — no tool, contract, or DAC to wire by hand.
-3. `dataActivationClients.ingest(...)` a row through that default client.
-4. `datalakes.executeSql(...)` reads it back by its unique column with read-only SQL.
-
-This is **global** to every datalake — only the table's domain meaning differs.
-See `generic_tables.md` for the column reference.
-
-# Walkthrough
-
-The `_setup/subscription.md` bootstrap left `api`, `tenantSlug`, and
-`datalakeSlug` populated.
-
-## 001 — list existing generic tables (sanity)
-
-`genericTables.list` returns the paginated `{ data, meta }` envelope. A fresh
-datalake has none; the call just confirms the surface is reachable.
-
-```typescript
-const { data: existing } = await api.genericTables.list(tenantSlug, datalakeSlug)
-if (!Array.isArray(existing.data)) {
-  throw new Error('expected a paginated generic-tables list with a data array')
-}
-```
-
-## 002 — create the generic table
-
-Declare the table with a `title` and `columns`. Each column has a `type`, an
-`is_unique` flag, and — load-bearing — a `privacy_requirement` that decides how
-the platform stores and exposes the value (`tokenize` for PII, `redact_only`
-for free text, `none` for safe fields). The server **derives the table `name`**
-(slugified + `alvera_custom_` prefix) and returns a `checksum`; you don't set
-the name. The `checksum(...)` call recomputes that fingerprint from a body
-without persisting — handy for drift checks.
-
-```typescript
-const tableBody = {
-  title: `Customer Inquiries ${runSuffix}`,
-  description: 'Inbound customer billing / dunning inquiries',
-  columns: [
-    { name: 'submission_id', title: 'Submission ID', type: 'string', description: 'Unique inquiry identifier', is_unique: true, privacy_requirement: 'none' },
-    { name: 'customer_name', title: 'Customer Name', type: 'string', description: 'Inquiring customer name', is_unique: false, privacy_requirement: 'tokenize' },
-    { name: 'email', title: 'Email', type: 'string', description: 'Contact email', is_unique: false, privacy_requirement: 'tokenize' },
-    { name: 'message', title: 'Message', type: 'string', description: 'Inquiry message body', is_unique: false, privacy_requirement: 'redact_only' },
-    { name: 'source_channel', title: 'Source Channel', type: 'string', description: 'Origin channel (web/portal/email)', is_unique: false, privacy_requirement: 'none' },
-  ],
-}
-
-const { data: table } = await api.genericTables.create(tenantSlug, datalakeSlug, tableBody)
-genericTableId = table.id!
-ctx.tableName = table.name!     // server-derived, e.g. alvera_custom_customer_inquiries_<suffix>
-
-const { data: ck } = await api.genericTables.checksum(tenantSlug, datalakeSlug, tableBody)
-if (ck.checksum !== table.checksum) {
-  throw new Error('checksum of the create body should match the created table')
-}
-```
-
-## 003 — wait for the table to deploy
-
-Creation returns immediately with `status: 'new'`; the platform then runs the
-schema migration in the background. Poll `genericTables.get` until `status` is
-`'deployed'`. Only then is it safe to ingest.
-
-```typescript
-const deadline = Date.now() + 60_000
-let status: string | undefined
-while (Date.now() < deadline) {
-  const { data: row } = await api.genericTables.get(tenantSlug, datalakeSlug, genericTableId)
-  status = row.status
-  if (status === 'deployed') break
-  await new Promise((r) => setTimeout(r, 1_000))
-}
-if (status !== 'deployed') {
-  throw new Error(`generic table did not reach :deployed within 60s (last: ${status})`)
-}
-```
-
-## 004 — find the auto-provisioned default ingestion client
-
-Deploying the table also creates a default Data Activation Client bound to an
-auto-generated identity contract. You don't create it — you find it. It shows up
-in the DAC list with the table's derived name in its own name. Poll briefly, as
-it appears a moment after `:deployed`.
-
-```typescript
-const deadline = Date.now() + 30_000
-let defaultDacSlug: string | undefined
-while (Date.now() < deadline && !defaultDacSlug) {
-  const { data: dacs } = await api.dataActivationClients.list(tenantSlug, datalakeSlug)
-  const match = (dacs.data ?? []).find((d) => (d.name ?? '').includes(ctx.tableName))
-  defaultDacSlug = match?.slug ?? undefined
-  if (!defaultDacSlug) await new Promise((r) => setTimeout(r, 1_000))
-}
-if (!defaultDacSlug) {
-  throw new Error('default DAC for the generic table was not provisioned within 30s')
-}
-ctx.defaultDacSlug = defaultDacSlug
-```
-
-## 005 — ingest a row
-
-Submit one row as inline JSON through the default client. The keys are your
-column `name`s. `submission_id` is the unique column, so give it a per-run value.
-
-```typescript
-ctx.submissionId = `CDS-${runSuffix}`
-const { data: ingest } = await api.dataActivationClients.ingest(
-  tenantSlug, datalakeSlug, ctx.defaultDacSlug,
-  {
-    data: {
-      submission_id: ctx.submissionId,
-      customer_name: 'Ada Lovelace',
-      email: 'ada@example.test',
-      message: 'My invoice total looks wrong this month.',
-      source_channel: 'portal',
-    },
-  },
-)
-if (!ingest.batch_id) {
-  throw new Error('ingest did not return a batch_id')
-}
-```
-
-## 006 — read the row back with read-only SQL
-
-`executeSql` runs a read-only statement against the datalake and returns a page
-as `{ data, meta }` — `data` is an array-of-arrays aligned positionally to
-`meta.columns`. `mode: 'unregulated'` runs it against the unregulated schema, so
-you reference the table by its server-derived `name` (the `alvera_custom_…`
-value from §002 — `mode` selects the schema, so no `regulated_`/`unregulated_`
-prefix). Ingestion is async, so poll until the row lands.
-
-```typescript
-const deadline = Date.now() + 45_000
-let row: Record<string, unknown> | undefined
-while (Date.now() < deadline && !row) {
-  const { data: result } = await api.datalakes.executeSql(tenantSlug, datalakeSlug, {
-    sql: `SELECT submission_id, customer_name, source_channel
-          FROM ${ctx.tableName}
-          WHERE submission_id = '${ctx.submissionId}'`,
-    mode: 'unregulated',
-  })
-  // JSON envelope (a `string` only for `{ format: 'csv' }`); zip the positional
-  // row back into an object keyed by meta.columns.
-  if (typeof result !== 'string' && result.data.length > 0) {
-    row = Object.fromEntries(result.meta.columns.map((c, i) => [c, result.data[0][i]]))
-  }
-  if (!row) await new Promise((r) => setTimeout(r, 1_000))
-}
-if (!row || row.submission_id !== ctx.submissionId) {
-  throw new Error('ingested row not found in the generic table within 45s')
-}
-```
-
-## 007 — write the integration test
-
-End the build with a test you keep: re-read the table and prove the two
-facts every consumer of it depends on — the deploy completed (with the
-server-derived physical name), and the ingest path accepts a row. The
-probe row is `test-`-prefixed so it is unmistakably synthetic wherever it
-surfaces. This block runs live under `make validate-cookbook`.
-
-```typescript
-// Re-GET — deployed, with the server-derived alvera_custom_ name.
-const { data: tableRow } = await api.genericTables.get(tenantSlug, datalakeSlug, genericTableId)
-if (tableRow.status !== 'deployed') {
-  throw new Error(`generic table regressed from deployed: ${tableRow.status}`)
-}
-if (tableRow.name !== ctx.tableName) {
-  throw new Error(`physical name drifted on read-back: ${tableRow.name}`)
-}
-// Behavioural probe — one synthetic row through the auto-provisioned
-// default client; ingest is async (202), so assert the batch
-// acknowledgement, never synchronous row completion.
-const { data: probeAck } = await api.dataActivationClients.ingest(
-  tenantSlug, datalakeSlug, ctx.defaultDacSlug,
-  {
-    data: {
-      submission_id: `test-CDS-probe-${runSuffix}`,
-      customer_name: 'test-Ada Lovelace',
-      email: 'test-ada@example.test',
-      message: 'test: integration-test probe row.',
-      source_channel: 'portal',
-    },
-  },
-)
-if (typeof probeAck.batch_id !== 'string' || probeAck.batch_id.length === 0) {
-  throw new Error('default-client ingest did not enqueue a batch')
-}
-```
-
-If the probe fails in production, escalate with the failing response —
-don't re-create the table or hand-edit the physical schema.
-
-# Gotchas
-
-- **`privacy_requirement` is load-bearing.** It drives the regulated/unregulated
-  split — `tokenize` columns are masked in the unregulated view, `redact_only`
-  free text is scrubbed, `none` passes through. Dropping it silently changes who
-  can see what.
-- **The table name is server-derived, never set by you.** The platform slugifies
-  the title and prefixes `alvera_custom_`. Read `name` off the create response and
-  reference it directly in `executeSql`; `mode` selects the schema, so you don't
-  add a `regulated_`/`unregulated_` prefix yourself.
-- **You don't create the ingestion client.** Deploying the table auto-provisions
-  a default DAC + identity contract. Find it by name; don't build one.
-- **Two async waits.** Wait for `:deployed` before ingesting, then poll
-  `executeSql` until the row materializes — ingestion is async like every other
-  ingest path.
-- **`mode` picks the schema, and `tokenize` columns come back masked.** In
-  `mode: 'unregulated'` the read runs against the tokenized view, so filter and
-  assert on a `none` column (here `submission_id`); a `tokenize` column like
-  `customer_name` returns its token, not the raw value.
-
-# See also
-
-- `generic_tables.md` — column types, `privacy_requirement`, lifecycle reference
-- `data_activation_clients.md` — the `.ingest` runtime verb + dataset search
-- `_setup/subscription.md` — the bootstrap this walk starts from
-- `integration-tests/tests/subscription/generic-tables.test.ts` — the
-  green test these calls are lifted from

package/.agent/cookbook/invite-team.md

@@ -1,200 +0,0 @@
----
-title: "Capability: invite a teammate into your tenant"
-summary: A capability walk for multi-user onboarding. An admin invites a colleague by email (`api.invitations.create`), the colleague signs up and is confirmed, signs in without a tenant to find the pending invite (`invitations.list`), accepts it (`invitations.accept`), and finally signs in tenant-scoped as a member. Shows the three session scopes — root, tenantless, tenant-scoped — in one flow.
-industry: subscription
-slug: invite-team
-vitest_source:
-  - integration-tests/tests/subscription/invite-team.test.ts
-  - integration-tests/tests/subscription/bootstrap.test.ts
-status: green
----
-
-# Capability
-
-**What you get:** a second person on your tenant, added entirely through the
-SDK — no console, no out-of-band steps.
-
-The flow touches all three session scopes (see `AGENTS.md` § SDK auth):
-
-- **tenant-scoped** (the admin) — `api.invitations.create(tenantSlug, { email, role })`
-- **root** — signs the new user up and confirms them
-  (`api.admin.signUp` + `api.admin.confirmUser`)
-- **tenantless** (the invitee, before they belong anywhere) — lists pending
-  invites and accepts one (`api.invitations.list` / `api.invitations.accept`)
-
-After accepting, the invitee re-authenticates **tenant-scoped** and is a member.
-This capability is **global** — it works the same on every datalake's tenant.
-
-# Walkthrough
-
-The `_setup/subscription.md` bootstrap already provisioned the tenant and
-left `api` as the admin's tenant-scoped client, with `tenantSlug` and
-`ctx.sarahEmail` / `ctx.sarahPassword` populated. Root credentials come from the
-`ALVERA_ROOT_EMAIL` / `ALVERA_ROOT_PASSWORD` env vars the validator already
-exports.
-
-## 001 — confirm the admin can invite
-
-Before inviting, verify the current session is a tenant-scoped admin of the
-expected tenant. `api.sessions.verify()` echoes the session's `tenant.slug` and
-`role.name`. Only an admin can create invitations.
-
-```typescript
-const { data: who } = await api.sessions.verify()
-if (who.tenant?.slug !== tenantSlug) {
-  throw new Error(`expected an admin session on ${tenantSlug}, got ${who.tenant?.slug}`)
-}
-if (!/admin/i.test(who.role?.name ?? '')) {
-  throw new Error(`expected an admin role, got ${who.role?.name}`)
-}
-```
-
-## 002 — invite the teammate by email
-
-The admin invites a colleague with their email and a role (`member`). The
-invite is keyed on `(tenant, email)`, so re-inviting the same address returns a
-422 with "already invited" — handle that as success so the step is idempotent on
-re-runs. The teammate's per-run email is derived from `runSuffix` so parallel
-runs don't collide.
-
-```typescript
-ctx.emmaEmail = `cookbook-emma-${runSuffix}@dev.local`
-ctx.emmaPassword = 'CookbookPass1!'
-
-try {
-  const { data: invite } = await api.invitations.create(tenantSlug, {
-    email: ctx.emmaEmail,
-    role: 'member',
-  })
-  if (invite.email !== ctx.emmaEmail || invite.role !== 'member') {
-    throw new Error(`unexpected invite: ${JSON.stringify(invite)}`)
-  }
-} catch (err) {
-  const detail = JSON.stringify(err)
-  if (!detail.includes('already invited')) throw err
-  // already invited on a re-run — fine
-}
-```
-
-## 003 — root signs the teammate up and confirms them
-
-The invitee needs an account before they can accept. Signup + confirmation are
-root-scoped actions, so build a root client from the `ALVERA_ROOT_*` credentials
-and use it. `confirmUser` activates the account so the invitee can sign in.
-
-```typescript
-const rootSession = await createBootstrapSession({
-  baseUrl: process.env.ALVERA_BASE_URL!,
-  email: process.env.ALVERA_ROOT_EMAIL!,
-  password: process.env.ALVERA_ROOT_PASSWORD!,
-})
-const rootApi = createIsolatedPlatformApi({
-  baseUrl: process.env.ALVERA_BASE_URL!,
-  sessionToken: rootSession.sessionToken,
-  apiKey: '',
-})
-
-const { data: emmaUser } = await rootApi.admin.signUp({
-  email: ctx.emmaEmail,
-  password: ctx.emmaPassword,
-  first_name: 'Emma',
-  last_name: 'Wilson',
-})
-await rootApi.admin.confirmUser(emmaUser.id!)
-```
-
-## 004 — teammate signs in WITHOUT a tenant and finds the invite
-
-The invitee has an account but belongs to no tenant yet, so they sign in
-**tenantless** — `createBootstrapSession` (`createSession` is tenant login
-only since the universal-key contract). The resulting session has
-`tenant: null`. A tenantless client can list the invitations waiting for that
-user. Find the one for this tenant by matching `tenant.slug`.
-
-```typescript
-const emmaTenantless = await createBootstrapSession({
-  baseUrl: process.env.ALVERA_BASE_URL!,
-  email: ctx.emmaEmail,
-  password: ctx.emmaPassword,
-})
-if (emmaTenantless.tenant !== null) {
-  throw new Error('expected a tenantless session (tenant should be null)')
-}
-const emmaTenantlessApi = createIsolatedPlatformApi({
-  baseUrl: process.env.ALVERA_BASE_URL!,
-  sessionToken: emmaTenantless.sessionToken,
-  apiKey: '',
-})
-ctx.emmaTenantlessToken = emmaTenantless.sessionToken
-
-const { data: invites } = await emmaTenantlessApi.invitations.list()
-const ours = (invites.data ?? []).find((i) => i.tenant?.slug === tenantSlug)
-if (!ours?.id) {
-  throw new Error(`no pending invite for ${tenantSlug} found for the new user`)
-}
-ctx.invitationId = ours.id
-```
-
-## 005 — teammate accepts the invitation
-
-Accepting consumes the invite and creates the membership. The response echoes
-the new `role` and the `tenant.slug` the user just joined.
-
-```typescript
-const emmaTenantlessApi = createIsolatedPlatformApi({
-  baseUrl: process.env.ALVERA_BASE_URL!,
-  sessionToken: ctx.emmaTenantlessToken,
-  apiKey: '',
-})
-
-const { data: membership } = await emmaTenantlessApi.invitations.accept(ctx.invitationId)
-if (membership.tenant?.slug !== tenantSlug || membership.role !== 'member') {
-  throw new Error(`unexpected membership: ${JSON.stringify(membership)}`)
-}
-```
-
-## 006 — teammate signs in tenant-scoped as a member
-
-Now that the membership exists, the invitee re-authenticates **with** the
-tenant slug — which requires the tenant's API key (`ctx.tenantApiKey`, minted
-during setup): tenant-scoped sign-in is 401'd without a resolvable
-`X-API-Key`. The new session carries `tenant.slug` and a `member` role — they
-are in.
-
-```typescript
-const emmaScoped = await createSession({
-  baseUrl: process.env.ALVERA_BASE_URL!,
-  email: ctx.emmaEmail,
-  password: ctx.emmaPassword,
-  tenantSlug,
-  apiKey: ctx.tenantApiKey,
-})
-if (emmaScoped.tenant?.slug !== tenantSlug) {
-  throw new Error(`expected a tenant-scoped session on ${tenantSlug}`)
-}
-if (!/member/i.test(emmaScoped.role?.name ?? '')) {
-  throw new Error(`expected a member role, got ${emmaScoped.role?.name}`)
-}
-```
-
-# Gotchas
-
-- **Invitations are created tenant-scoped, accepted tenantless.** The admin
-  calls `invitations.create(tenantSlug, …)` on their tenant-scoped client; the
-  invitee calls `invitations.list()` / `accept(id)` on a **tenantless** client
-  (they have no tenant yet). Mixing the scopes up is the #1 mistake here.
-- **Re-inviting the same email 422s.** The `(tenant, email)` pair is unique —
-  catch "already invited" and treat it as success for idempotent re-runs.
-- **The invitee re-authenticates twice.** Once tenantless (to find + accept the
-  invite), then again tenant-scoped (to act as a member). Accepting does not
-  upgrade the existing tenantless session in place — you mint a new one.
-- **Signup + confirm are root-scoped.** A tenant admin can invite, but only root
-  can create and confirm the underlying user account.
-
-# See also
-
-- `AGENTS.md` § SDK auth + client construction — root / tenantless / tenant-scoped
-- `account_management.md` — users, roles, invitations reference
-- `_setup/subscription.md` — the bootstrap this walk starts from
-- `integration-tests/tests/subscription/invite-team.test.ts` — the green
-  test these calls are lifted from