@alvera-ai/platform-sdk 0.10.0-rc.2 → 0.10.0-rc.21

package/.agent/cookbook/_setup/healthcare.md

@@ -0,0 +1,279 @@
+---
+title: Healthcare industry bootstrap setup
+summary: Auth as root, sign up + confirm a fresh industry-admin user, create a healthcare tenant + datalake. Shared by every healthcare scenario cookbook.
+industry: healthcare
+slug: healthcare
+vitest_source:
+  - integration-tests/tests/healthcare/bootstrap.test.ts
+status: green
+---
+
+# Problem
+
+Every healthcare scenario cookbook needs the same starting point:
+a fresh tenant on the platform with a healthcare-domain datalake
+attached, accessed by an industry-admin user. Authoring this
+prelude inline inside every scenario cookbook would duplicate the
+auth + tenant + datalake chain across two cookbooks (and six more
+across the other industries). The validator auto-discovers this
+file from each cookbook's `industry: healthcare` front-matter and
+inlines its numbered steps ahead of the scenario's own, so the
+generated bun:test spec is hermetic without the cookbook author
+having to copy-paste this prelude.
+
+# Composition
+
+| Resource provisioned          | Owner       |
+|-------------------------------|-------------|
+| Root session                  | setup       |
+| Industry-admin user (`sarah`) | setup       |
+| Healthcare tenant             | setup       |
+| Healthcare datalake           | setup       |
+
+# Walkthrough
+
+## 001 — root admin signs in and provisions a fresh industry-admin user
+
+Authenticate as the platform's root admin (`admin@dev.local` /
+`devpassword` in local dev). Then sign up a per-run industry-admin
+user (`sarah`) under a unique email derived from `runSuffix`, and
+confirm them so they can sign in. Both the signup and the confirm
+endpoints require root scope.
+
+```typescript
+ctx.rootSession = await createSession({
+  baseUrl: process.env.ALVERA_BASE_URL!,
+  email: process.env.ALVERA_ROOT_EMAIL!,
+  password: process.env.ALVERA_ROOT_PASSWORD!,
+})
+ctx.rootApi = createIsolatedPlatformApi({
+  baseUrl: process.env.ALVERA_BASE_URL!,
+  sessionToken: ctx.rootSession.sessionToken,
+})
+
+ctx.sarahEmail = `cookbook-sarah-${runSuffix}@dev.local`
+ctx.sarahPassword = 'CookbookPass1!'
+
+const signUpResp = await ctx.rootApi.auth.signUp({
+  email: ctx.sarahEmail,
+  password: ctx.sarahPassword,
+  first_name: 'Cookbook',
+  last_name: 'Sarah',
+})
+ctx.sarahUserId = signUpResp.data.id
+await ctx.rootApi.admin.confirmUser(ctx.sarahUserId)
+```
+
+## 002 — sarah signs in (tenantless) and creates the healthcare tenant
+
+Sarah signs in for the first time without a tenant scope (no
+tenant exists yet for her), then immediately creates a fresh
+healthcare tenant. The tenant's server-derived `slug` is captured
+into the closure-scoped `tenantSlug` slot for downstream steps.
+
+```typescript
+ctx.sarahTenantlessSession = await createSession({
+  baseUrl: process.env.ALVERA_BASE_URL!,
+  email: ctx.sarahEmail,
+  password: ctx.sarahPassword,
+})
+ctx.sarahTenantlessApi = createIsolatedPlatformApi({
+  baseUrl: process.env.ALVERA_BASE_URL!,
+  sessionToken: ctx.sarahTenantlessSession.sessionToken,
+})
+
+const tenantResp = await ctx.sarahTenantlessApi.tenants.create({
+  name: `Cookbook Healthcare ${runSuffix}`,
+})
+tenantSlug = tenantResp.data.slug!
+```
+
+## 003 — sarah signs in tenant-scoped — the canonical client
+
+Re-mint sarah's session with the new tenant slug. This bearer is
+the canonical tenant-scoped client every subsequent step uses; it
+is assigned to the closure-scoped `api` slot so the scenario
+cookbook's steps inherit it via inlining.
+
+```typescript
+const sarahTenantSession = await createSession({
+  baseUrl: process.env.ALVERA_BASE_URL!,
+  email: ctx.sarahEmail,
+  password: ctx.sarahPassword,
+  tenantSlug,
+})
+api = createIsolatedPlatformApi({
+  baseUrl: process.env.ALVERA_BASE_URL!,
+  sessionToken: sarahTenantSession.sessionToken,
+})
+```
+
+## 004 — sarah creates the healthcare datalake
+
+Provision a healthcare-domain datalake on the new tenant. The DB
+schemas are scoped to the cookbook run via `runSuffix` so parallel
+cookbook runs do not collide on schema names. Local-dev defaults
+(`postgres` on `localhost:5432`, `alvera_dev_healthcare`) match
+the seeded `dev.exs` setup; LocalStack S3 (`localhost:4566`)
+serves the unregulated + regulated buckets. The datalake's
+server-derived `slug` is captured into `datalakeSlug`.
+
+```typescript
+const DB_HOST = 'localhost'
+const DB_PORT = 5432
+const DB_USER = 'postgres'
+const DB_PASS = 'postgres'
+const DB_NAME = 'alvera_dev_healthcare'
+const UNREG_SCHEMA = `cookbook_${runSuffix}_unreg`
+const REG_SCHEMA = `cookbook_${runSuffix}_reg`
+
+const S3 = {
+  cloud_storage_type: 'aws' as const,
+  region: 'us-east-1',
+  access_key_id: 'test',
+  secret_access_key: 'test',
+  endpoint: 'http://localhost:4566',
+}
+
+const datalakeResp = await api.datalakes.create(tenantSlug, {
+  name: `Cookbook Healthcare Datalake ${runSuffix}`,
+  description: 'Healthcare datalake provisioned by cookbook doctest.',
+  data_domain: 'healthcare',
+  timezone: 'America/New_York',
+  pool_size: 5,
+
+  unregulated_db_writer_host: DB_HOST,
+  unregulated_db_writer_port: DB_PORT,
+  unregulated_db_writer_name: DB_NAME,
+  unregulated_db_writer_schema: UNREG_SCHEMA,
+  unregulated_db_writer_auth_method: 'password',
+  unregulated_db_writer_user: DB_USER,
+  unregulated_db_writer_pass: DB_PASS,
+  unregulated_db_writer_enable_ssl: false,
+  unregulated_db_reader_host: DB_HOST,
+  unregulated_db_reader_port: DB_PORT,
+  unregulated_db_reader_name: DB_NAME,
+  unregulated_db_reader_schema: UNREG_SCHEMA,
+  unregulated_db_reader_auth_method: 'password',
+  unregulated_db_reader_user: DB_USER,
+  unregulated_db_reader_pass: DB_PASS,
+  unregulated_db_reader_enable_ssl: false,
+
+  regulated_data_db_writer_host: DB_HOST,
+  regulated_data_db_writer_port: DB_PORT,
+  regulated_data_db_writer_name: DB_NAME,
+  regulated_data_db_writer_schema: REG_SCHEMA,
+  regulated_data_db_writer_auth_method: 'password',
+  regulated_data_db_writer_user: DB_USER,
+  regulated_data_db_writer_pass: DB_PASS,
+  regulated_data_db_writer_enable_ssl: false,
+  regulated_data_db_reader_host: DB_HOST,
+  regulated_data_db_reader_port: DB_PORT,
+  regulated_data_db_reader_name: DB_NAME,
+  regulated_data_db_reader_schema: REG_SCHEMA,
+  regulated_data_db_reader_auth_method: 'password',
+  regulated_data_db_reader_user: DB_USER,
+  regulated_data_db_reader_pass: DB_PASS,
+  regulated_data_db_reader_enable_ssl: false,
+
+  unregulated_cloud_storage: { ...S3, bucket: 'healthcare-lake-unregulated' },
+  regulated_cloud_storage: { ...S3, bucket: 'healthcare-lake-regulated' },
+})
+datalakeSlug = datalakeResp.data.slug!
+// `tools.create` and a few other endpoints accept the datalake by
+// UUID in the request body rather than only the slug in the URL,
+// so keep it on `ctx` for downstream steps that need it.
+ctx.datalakeId = datalakeResp.data.id!
+```
+
+## 005 — enqueue the datalake migrations
+
+`datalakes.create` persists the datalake row in `:new` status but
+does not itself run the schema migrations. Migration is a
+separately-triggered async job so the operator controls when the
+(potentially slow) per-industry DDL runs. `datalakes.migrate`
+enqueues the `DatalakeMigrationWorker` Oban job and returns
+immediately with `status: 'enqueued'` plus the Oban `job_id`. The
+poll in §006 then waits for that worker to finish — without this
+call the datalake would sit at `:new` forever.
+
+```typescript
+const migrateResp = await api.datalakes.migrate(tenantSlug, datalakeSlug)
+if (migrateResp.data.status !== 'enqueued') {
+  throw new Error(
+    `datalake migration not enqueued (status: ${migrateResp.data.status})`,
+  )
+}
+```
+
+## 006 — poll the datalake until status is ready
+
+Datalake migrations are async — the §005 migrate call enqueued a
+`DatalakeMigrationWorker` Oban job that runs the per-industry
+schema migrations (the regulated FHIR R4 patient + appointment
+tables and their join tables), deploys PostgREST roles, and
+provisions the service-account bot user. Downstream resource
+creates (tools, workflows) only need `datalakeId` to be persisted
+(which it is the moment §004 returns), but any scenario step that
+ingests into the regulated/unregulated DBs or runs a dataset
+search requires `status: 'ready'`. Polling here makes every
+healthcare scenario cookbook deterministic regardless of how long
+the cold migration takes on a given host; the loop exits the
+moment the datalake reaches `:ready`, so the 5-minute cap is paid
+only in failure mode.
+
+```typescript
+const READY_TIMEOUT_MS = 5 * 60_000
+const READY_POLL_MS = 5_000
+const deadline = Date.now() + READY_TIMEOUT_MS
+let datalakeStatus: string | undefined
+while (Date.now() < deadline) {
+  const { data } = await api.datalakes.get(tenantSlug, ctx.datalakeId)
+  datalakeStatus = data.status
+  if (datalakeStatus === 'ready') break
+  await new Promise((r) => setTimeout(r, READY_POLL_MS))
+}
+if (datalakeStatus !== 'ready') {
+  throw new Error(
+    `datalake did not reach :ready within ${READY_TIMEOUT_MS}ms (last status: ${datalakeStatus})`,
+  )
+}
+```
+
+# Rollback
+
+The cookbook doctest harness does not currently tear down the
+created tenant / datalake / user — each run mints fresh names via
+`runSuffix` so reruns do not collide, and the seeded local DB is
+cheap to reset (`mix ecto.reset` on the platform). When the
+validator graduates to continuous integration at Milestone 18
+(running against the mockoon-backed mock env at `ALVERA_ENV=mock`),
+no real state is created at all.
+
+# Outcome
+
+After this setup runs, the closure-scoped slots are populated as:
+
+- `api` — a tenant-scoped `PlatformApi` client authenticated as
+  the industry-admin user
+- `tenantSlug` — server-derived slug of the fresh healthcare
+  tenant
+- `datalakeSlug` — server-derived slug of the fresh healthcare
+  datalake
+- `ctx.sarahEmail` / `ctx.sarahPassword` — the per-run admin
+  credentials (kept on `ctx` because no scenario cookbook needs
+  to re-authenticate by default)
+
+Scenario cookbooks under `industry: healthcare` start at their own
+`§001` with these slots already populated.
+
+# See also
+
+- `.agent/datalakes.md` — datalake create body shape (regulated +
+  unregulated tier configuration)
+- `.agent/AGENTS.md` § SDK auth + client construction — root vs
+  tenantless vs tenant-scoped session scopes
+- `integration-tests/tests/healthcare/bootstrap.test.ts` — the
+  green test these snippets are lifted from (the §7b sibling
+  datalake creation and the §10–§13 sanity probes are out of
+  scope for this lean cookbook setup)

package/.agent/cookbook/_setup/payment_risk.md

@@ -0,0 +1,283 @@
+---
+title: Payment-risk industry bootstrap setup
+summary: Auth as root, sign up + confirm a fresh industry-admin user, create a payment-risk tenant + datalake. Shared by every payment-risk scenario cookbook.
+industry: payment_risk
+slug: payment_risk
+vitest_source:
+  - integration-tests/tests/payment_risk/bootstrap.test.ts
+status: green
+---
+
+# Problem
+
+Every payment-risk scenario cookbook needs the same starting
+point: a fresh tenant on the platform with a payment-risk-domain
+datalake attached, accessed by an industry-admin user. Authoring
+this prelude inline inside every scenario cookbook would
+duplicate the auth + tenant + datalake chain across two cookbooks
+(and six more across the other industries). The validator
+auto-discovers this file from each cookbook's
+`industry: payment_risk` front-matter and inlines its numbered
+steps ahead of the scenario's own, so the generated bun:test spec
+is hermetic without the cookbook author having to copy-paste this
+prelude.
+
+# Composition
+
+| Resource provisioned          | Owner       |
+|-------------------------------|-------------|
+| Root session                  | setup       |
+| Industry-admin user (`sarah`) | setup       |
+| Payment-risk tenant            | setup       |
+| Payment-risk datalake          | setup       |
+
+# Walkthrough
+
+## 001 — root admin signs in and provisions a fresh industry-admin user
+
+Authenticate as the platform's root admin (`admin@dev.local` /
+`devpassword` in local dev). Then sign up a per-run industry-admin
+user (`sarah`) under a unique email derived from `runSuffix`, and
+confirm them so they can sign in. Both the signup and the confirm
+endpoints require root scope.
+
+```typescript
+ctx.rootSession = await createSession({
+  baseUrl: process.env.ALVERA_BASE_URL!,
+  email: process.env.ALVERA_ROOT_EMAIL!,
+  password: process.env.ALVERA_ROOT_PASSWORD!,
+})
+ctx.rootApi = createIsolatedPlatformApi({
+  baseUrl: process.env.ALVERA_BASE_URL!,
+  sessionToken: ctx.rootSession.sessionToken,
+})
+
+ctx.sarahEmail = `cookbook-sarah-${runSuffix}@dev.local`
+ctx.sarahPassword = 'CookbookPass1!'
+
+const signUpResp = await ctx.rootApi.auth.signUp({
+  email: ctx.sarahEmail,
+  password: ctx.sarahPassword,
+  first_name: 'Cookbook',
+  last_name: 'Sarah',
+})
+ctx.sarahUserId = signUpResp.data.id
+await ctx.rootApi.admin.confirmUser(ctx.sarahUserId)
+```
+
+## 002 — sarah signs in (tenantless) and creates the payment-risk tenant
+
+Sarah signs in for the first time without a tenant scope (no
+tenant exists yet for her), then immediately creates a fresh
+payment-risk tenant. The tenant's server-derived `slug` is
+captured into the closure-scoped `tenantSlug` slot for downstream
+steps.
+
+```typescript
+ctx.sarahTenantlessSession = await createSession({
+  baseUrl: process.env.ALVERA_BASE_URL!,
+  email: ctx.sarahEmail,
+  password: ctx.sarahPassword,
+})
+ctx.sarahTenantlessApi = createIsolatedPlatformApi({
+  baseUrl: process.env.ALVERA_BASE_URL!,
+  sessionToken: ctx.sarahTenantlessSession.sessionToken,
+})
+
+const tenantResp = await ctx.sarahTenantlessApi.tenants.create({
+  name: `Cookbook Payment Risk ${runSuffix}`,
+})
+tenantSlug = tenantResp.data.slug!
+```
+
+## 003 — sarah signs in tenant-scoped — the canonical client
+
+Re-mint sarah's session with the new tenant slug. This bearer is
+the canonical tenant-scoped client every subsequent step uses; it
+is assigned to the closure-scoped `api` slot so the scenario
+cookbook's steps inherit it via inlining.
+
+```typescript
+const sarahTenantSession = await createSession({
+  baseUrl: process.env.ALVERA_BASE_URL!,
+  email: ctx.sarahEmail,
+  password: ctx.sarahPassword,
+  tenantSlug,
+})
+api = createIsolatedPlatformApi({
+  baseUrl: process.env.ALVERA_BASE_URL!,
+  sessionToken: sarahTenantSession.sessionToken,
+})
+```
+
+## 004 — sarah creates the payment-risk datalake
+
+Provision a payment-risk-domain datalake on the new tenant. The
+DB schemas are scoped to the cookbook run via `runSuffix` so
+parallel cookbook runs do not collide on schema names. Local-dev
+defaults (`postgres` on `localhost:5432`, `alvera_dev_payment_risk`)
+match the seeded `dev.exs` setup; LocalStack S3
+(`localhost:4566`) serves the unregulated + regulated buckets.
+The datalake's server-derived `slug` is captured into
+`datalakeSlug`.
+
+```typescript
+const DB_HOST = 'localhost'
+const DB_PORT = 5432
+const DB_USER = 'postgres'
+const DB_PASS = 'postgres'
+const DB_NAME = 'alvera_dev_payment_risk'
+const UNREG_SCHEMA = `cookbook_${runSuffix}_unreg`
+const REG_SCHEMA = `cookbook_${runSuffix}_reg`
+
+const S3 = {
+  cloud_storage_type: 'aws' as const,
+  region: 'us-east-1',
+  access_key_id: 'test',
+  secret_access_key: 'test',
+  endpoint: 'http://localhost:4566',
+}
+
+const datalakeResp = await api.datalakes.create(tenantSlug, {
+  name: `Cookbook Payment Risk Datalake ${runSuffix}`,
+  description: 'Payment-risk datalake provisioned by cookbook doctest.',
+  data_domain: 'payment_risk',
+  timezone: 'America/New_York',
+  pool_size: 5,
+
+  unregulated_db_writer_host: DB_HOST,
+  unregulated_db_writer_port: DB_PORT,
+  unregulated_db_writer_name: DB_NAME,
+  unregulated_db_writer_schema: UNREG_SCHEMA,
+  unregulated_db_writer_auth_method: 'password',
+  unregulated_db_writer_user: DB_USER,
+  unregulated_db_writer_pass: DB_PASS,
+  unregulated_db_writer_enable_ssl: false,
+  unregulated_db_reader_host: DB_HOST,
+  unregulated_db_reader_port: DB_PORT,
+  unregulated_db_reader_name: DB_NAME,
+  unregulated_db_reader_schema: UNREG_SCHEMA,
+  unregulated_db_reader_auth_method: 'password',
+  unregulated_db_reader_user: DB_USER,
+  unregulated_db_reader_pass: DB_PASS,
+  unregulated_db_reader_enable_ssl: false,
+
+  regulated_data_db_writer_host: DB_HOST,
+  regulated_data_db_writer_port: DB_PORT,
+  regulated_data_db_writer_name: DB_NAME,
+  regulated_data_db_writer_schema: REG_SCHEMA,
+  regulated_data_db_writer_auth_method: 'password',
+  regulated_data_db_writer_user: DB_USER,
+  regulated_data_db_writer_pass: DB_PASS,
+  regulated_data_db_writer_enable_ssl: false,
+  regulated_data_db_reader_host: DB_HOST,
+  regulated_data_db_reader_port: DB_PORT,
+  regulated_data_db_reader_name: DB_NAME,
+  regulated_data_db_reader_schema: REG_SCHEMA,
+  regulated_data_db_reader_auth_method: 'password',
+  regulated_data_db_reader_user: DB_USER,
+  regulated_data_db_reader_pass: DB_PASS,
+  regulated_data_db_reader_enable_ssl: false,
+
+  unregulated_cloud_storage: { ...S3, bucket: 'payment-risk-lake-unregulated' },
+  regulated_cloud_storage: { ...S3, bucket: 'payment-risk-lake-regulated' },
+})
+datalakeSlug = datalakeResp.data.slug!
+// `tools.create` and a few other endpoints accept the datalake by
+// UUID in the request body rather than only the slug in the URL,
+// so keep it on `ctx` for downstream steps that need it.
+ctx.datalakeId = datalakeResp.data.id!
+```
+
+## 005 — enqueue the datalake migrations
+
+`datalakes.create` persists the datalake row in `:new` status but
+does not itself run the schema migrations. Migration is a
+separately-triggered async job so the operator controls when the
+(potentially slow) per-industry DDL runs. `datalakes.migrate`
+enqueues the `DatalakeMigrationWorker` Oban job and returns
+immediately with `status: 'enqueued'` plus the Oban `job_id`. The
+poll in §006 then waits for that worker to finish — without this
+call the datalake would sit at `:new` forever.
+
+```typescript
+const migrateResp = await api.datalakes.migrate(tenantSlug, datalakeSlug)
+if (migrateResp.data.status !== 'enqueued') {
+  throw new Error(
+    `datalake migration not enqueued (status: ${migrateResp.data.status})`,
+  )
+}
+```
+
+## 006 — poll the datalake until status is ready
+
+Datalake migrations are async — the §005 migrate call enqueued a
+`DatalakeMigrationWorker` Oban job that runs the per-industry
+schema migrations (the regulated payment-account, compliance-
+screening, and legal-entity tables and their join tables),
+deploys PostgREST roles, and provisions the service-account bot
+user. Downstream resource creates (tools, workflows) only need
+`datalakeId` to be persisted (which it is the moment §004
+returns), but any scenario step that ingests into the
+regulated/unregulated DBs or runs a dataset search requires
+`status: 'ready'`. Polling here makes every payment-risk scenario
+cookbook deterministic regardless of how long the cold migration
+takes on a given host; the loop exits the moment the datalake
+reaches `:ready`, so the 5-minute cap is paid only in failure
+mode.
+
+```typescript
+const READY_TIMEOUT_MS = 5 * 60_000
+const READY_POLL_MS = 5_000
+const deadline = Date.now() + READY_TIMEOUT_MS
+let datalakeStatus: string | undefined
+while (Date.now() < deadline) {
+  const { data } = await api.datalakes.get(tenantSlug, ctx.datalakeId)
+  datalakeStatus = data.status
+  if (datalakeStatus === 'ready') break
+  await new Promise((r) => setTimeout(r, READY_POLL_MS))
+}
+if (datalakeStatus !== 'ready') {
+  throw new Error(
+    `datalake did not reach :ready within ${READY_TIMEOUT_MS}ms (last status: ${datalakeStatus})`,
+  )
+}
+```
+
+# Rollback
+
+The cookbook doctest harness does not currently tear down the
+created tenant / datalake / user — each run mints fresh names via
+`runSuffix` so reruns do not collide, and the seeded local DB is
+cheap to reset (`mix ecto.reset` on the platform). When the
+validator graduates to continuous integration at Milestone 18
+(running against the mockoon-backed mock env at `ALVERA_ENV=mock`),
+no real state is created at all.
+
+# Outcome
+
+After this setup runs, the closure-scoped slots are populated as:
+
+- `api` — a tenant-scoped `PlatformApi` client authenticated as
+  the industry-admin user
+- `tenantSlug` — server-derived slug of the fresh payment-risk
+  tenant
+- `datalakeSlug` — server-derived slug of the fresh payment-risk
+  datalake
+- `ctx.sarahEmail` / `ctx.sarahPassword` — the per-run admin
+  credentials (kept on `ctx` because no scenario cookbook needs
+  to re-authenticate by default)
+
+Scenario cookbooks under `industry: payment_risk` start at their
+own `§001` with these slots already populated.
+
+# See also
+
+- `.agent/datalakes.md` — datalake create body shape (regulated +
+  unregulated tier configuration)
+- `.agent/AGENTS.md` § SDK auth + client construction — root vs
+  tenantless vs tenant-scoped session scopes
+- `integration-tests/tests/payment_risk/bootstrap.test.ts` — the
+  green test these snippets are lifted from (the sibling datalake
+  creation and the sanity probes are out of scope for this lean
+  cookbook setup)