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

package/.agent/cookbook/_setup/accounts_receivable.md

@@ -0,0 +1,282 @@
+---
+title: Accounts-receivable industry bootstrap setup
+summary: Auth as root, sign up + confirm a fresh industry-admin user, create an accounts-receivable tenant + datalake. Shared by every accounts-receivable scenario cookbook.
+industry: accounts_receivable
+slug: accounts_receivable
+vitest_source:
+  - integration-tests/tests/accounts_receivable/bootstrap.test.ts
+status: green
+---
+
+# Problem
+
+Every accounts-receivable scenario cookbook needs the same
+starting point: a fresh tenant on the platform with an
+accounts-receivable-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: accounts_receivable` 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       |
+| Accounts-receivable tenant     | setup       |
+| Accounts-receivable 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 accounts-receivable tenant
+
+Sarah signs in for the first time without a tenant scope (no
+tenant exists yet for her), then immediately creates a fresh
+accounts-receivable 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 Accounts Receivable ${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 accounts-receivable datalake
+
+Provision an accounts-receivable-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_accounts_receivable`) 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_accounts_receivable'
+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 Accounts Receivable Datalake ${runSuffix}`,
+  description: 'Accounts-receivable datalake provisioned by cookbook doctest.',
+  data_domain: 'accounts_receivable',
+  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: 'accounts-receivable-lake-unregulated' },
+  regulated_cloud_storage: { ...S3, bucket: 'accounts-receivable-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 customer + invoice 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 accounts-receivable
+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
+  accounts-receivable tenant
+- `datalakeSlug` — server-derived slug of the fresh
+  accounts-receivable 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: accounts_receivable` 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/accounts_receivable/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)

package/.agent/cookbook/_setup/foundation.md

@@ -0,0 +1,277 @@
+---
+title: Foundation industry bootstrap setup
+summary: Auth as root, sign up + confirm a fresh industry-admin user, create a foundation tenant + datalake. Shared by every foundation scenario cookbook.
+industry: foundation
+slug: foundation
+vitest_source:
+  - integration-tests/tests/foundation/bootstrap.test.ts
+status: green
+---
+
+# Problem
+
+Every foundation scenario cookbook needs the same starting point:
+a fresh tenant on the platform with a foundation-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 four more
+across the other industries). The validator auto-discovers this
+file from each cookbook's `industry: foundation` 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       |
+| Foundation tenant             | setup       |
+| Foundation 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 foundation tenant
+
+Sarah signs in for the first time without a tenant scope (no
+tenant exists yet for her), then immediately creates a fresh
+foundation 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 Foundation ${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 foundation datalake
+
+Provision a foundation-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_foundation`) 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_foundation'
+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 Foundation Datalake ${runSuffix}`,
+  description: 'Foundation datalake provisioned by cookbook doctest.',
+  data_domain: 'foundation',
+  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: 'foundation-lake-unregulated' },
+  regulated_cloud_storage: { ...S3, bucket: 'foundation-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, 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 touches
+the regulated/unregulated DBs or the dataset infrastructure
+requires `status: 'ready'`. Polling here makes every foundation
+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 foundation
+  tenant
+- `datalakeSlug` — server-derived slug of the fresh foundation
+  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: foundation` 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/foundation/bootstrap.test.ts` — the
+  green test these snippets are lifted from (the §7b sibling
+  datalake creation is out of scope for this lean cookbook setup)