@alvera-ai/platform-sdk 0.10.0-rc.8 → 0.11.0

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

@@ -0,0 +1,194 @@
+---
+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: accounts_receivable
+slug: invite-team
+vitest_source:
+  - integration-tests/tests/accounts_receivable/invite-team.test.ts
+  - integration-tests/tests/accounts_receivable/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.auth.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/accounts_receivable.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 createSession({
+  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,
+})
+
+const { data: emmaUser } = await rootApi.auth.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** — `createSession` with no `tenantSlug`. 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 createSession({
+  baseUrl: process.env.ALVERA_BASE_URL!,
+  email: ctx.emmaEmail,
+  password: ctx.emmaPassword,
+  // no tenantSlug → tenantless session
+})
+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,
+})
+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,
+})
+
+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. 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,
+})
+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/accounts_receivable.md` — the bootstrap this walk starts from
+- `integration-tests/tests/accounts_receivable/invite-team.test.ts` — the green
+  test these calls are lifted from