@antelopejs/interface-dms 0.7.1 → 0.7.2

package/docs/1.core/5.tenancy.md

@@ -0,0 +1,356 @@
+---
+title: "Tenancy"
+description: "The DMS serves several tenants from one backend."
+---
+
+# Tenancy
+
+## Overview
+
+The DMS serves several tenants from one backend. Tenant-owned tables live in a per-tenant schema, and a model handle is bound to one tenant when you obtain it: `GetModel(TenantMemberModel, tenantId)` reads and writes that tenant's rows only. No query filters rows by tenant, and no table carries a `tenantId` column — the isolation is in the handle.
+
+The tenancy surface spans several subpaths:
+
+| Subpath | Contains |
+| ------- | -------- |
+| `@antelopejs/interface-dms/constants` | Schema names and the default tenant |
+| `@antelopejs/interface-dms/db` | The `Tenant`, `TenantMember` and `Role` tables and their models |
+| `@antelopejs/interface-dms/request-tenant` | Resolving the request's tenant |
+| `@antelopejs/interface-dms/tenant-scoped-model` | Injecting a tenant-bound model |
+| `@antelopejs/interface-dms/tenant-access` | Tenant access gates |
+| `@antelopejs/interface-dms/tenant-ownership` | Membership and ownership writes |
+| `@antelopejs/interface-dms/tenant-lifecycle` | Producer admission and permanent closure before deletion |
+| `@antelopejs/interface-dms/utils/saas-mode` | Declaring SaaS mode |
+| `@antelopejs/interface-dms/data-controllers` | The built-in members and roles data controllers |
+
+## Constants
+
+```typescript
+import {
+  CORE_SCHEMA_NAME,
+  DEFAULT_TENANT_ID,
+  DEFAULT_TENANT_NAME,
+  TENANT_SCHEMA_NAME,
+} from "@antelopejs/interface-dms/constants";
+```
+
+| Constant | Value | Meaning |
+| -------- | ----- | ------- |
+| `CORE_SCHEMA_NAME` | `"dms-core"` | Schema for tables with a single instance across the whole backend. |
+| `TENANT_SCHEMA_NAME` | `"dms-tenant"` | Schema instantiated once per tenant. |
+| `DEFAULT_TENANT_ID` | `"default"` | The tenant an unauthenticated request resolves to, and the only tenant a single-tenant project uses. |
+| `DEFAULT_TENANT_NAME` | `"Default"` | Display name of that tenant. |
+
+Register your own table in `TENANT_SCHEMA_NAME` to make it per-tenant, or in `CORE_SCHEMA_NAME` to keep one instance of it:
+
+```typescript
+import {
+  Field,
+  Index,
+  RegisterTable,
+  Table,
+} from "@antelopejs/interface-database-decorators";
+import { TENANT_SCHEMA_NAME } from "@antelopejs/interface-dms/constants";
+
+@RegisterTable("invoices", TENANT_SCHEMA_NAME)
+export class Invoice extends Table {
+  @Field("string")
+  declare _id: string;
+
+  @Index()
+  @Field("string")
+  declare reference: string;
+}
+```
+
+## The Tenancy Tables
+
+All three tables and their models are exported from `@antelopejs/interface-dms/db`, along with their table-name constants `tenantsTableName`, `tenantMembersTableName` and `ROLES_TABLE_NAME`.
+
+### `Tenant`
+
+Table `tenants` in `dms-core` — one row per tenant, shared across the backend.
+
+| Field | Type | Notes |
+| ----- | ---- | ----- |
+| `_id` | `string` | Tenant id. This is the instance id every per-tenant model handle takes. |
+| `name` | `string` | Display name. |
+| `createdAt` | `Date` | Creation time, indexed. |
+| `updatedAt` | `Date` | Update time, indexed. |
+
+`TenantModel` extends `BasicDataModel(Tenant, tenantsTableName)` and adds `getMany(ids: string[]): Promise<Tenant[]>`, which returns `[]` for an empty id list.
+
+Being a core-schema table, `TenantModel` is obtained without an instance id: `GetModel(TenantModel)`.
+
+### `TenantMember`
+
+Table `tenant_members` in `dms-tenant` — one row per member of the tenant the handle is bound to.
+
+| Field | Type | Notes |
+| ----- | ---- | ----- |
+| `_id` | `string` | Membership id. |
+| `userId` | `string` | Indexed, related to the `User` table of the [Auth](/docs/interfaces/auth/introduction) domain. |
+| `roleIds` | `string[]` | Related to `Role`, many. The roles whose grants make up the member's base permission set. |
+| `isTenantOwner` | `boolean` | Whether the member owns the tenant. |
+| `joinedAt` | `Date` | Creation time, indexed. |
+| `invitedBy` | `string \| null` | Indexed, related to `User`. |
+
+`TenantMemberModel` extends `BasicDataModel(TenantMember, tenantMembersTableName)`:
+
+| Method | Returns |
+| ------ | ------- |
+| `getByUser(userId)` | `Promise<TenantMember \| undefined>` |
+| `existsByUser(userId)` | `Promise<boolean>` |
+| `listAll()` | `Promise<TenantMember[]>` |
+| `listOwners()` | `Promise<TenantMember[]>` — members with `isTenantOwner` set |
+| `listByUserWithTenantIds(userId)` | `Promise<Array<{ tenantId: string; member: TenantMember }>>` |
+| `getOldestByUser(userId)` | `Promise<{ tenantId: string; member: TenantMember } \| undefined>` — earliest `joinedAt` |
+| `countOwnersExcluding(excludedUserIds)` | `Promise<number>` |
+
+The two methods that return a `tenantId` alongside the row report which tenant each row came from, which is what a lookup that spans instances needs.
+
+### `Role`
+
+Table `roles` in `dms-tenant` — the tenant's roles.
+
+| Field | Type | Notes |
+| ----- | ---- | ----- |
+| `_id` | `string` | Role id, as referenced by `TenantMember.roleIds`. |
+| `createdAt` | `Date` | Creation time, indexed. |
+| `updatedAt` | `Date` | Update time, indexed. |
+| `name` | `string` | Indexed. |
+| `permissions` | `string[]` | Granted permission ids ([Permissions](/docs/interfaces/core/permissions)). |
+
+`RoleModel` extends `BasicDataModel(Role, ROLES_TABLE_NAME)` and adds `getByName(name): Promise<Role | undefined>`.
+
+## Resolve the Request's Tenant
+
+`getRequestTenantId(ctx)` reads the `tenantId` claim of the request's bearer token and returns `DEFAULT_TENANT_ID` when there is no token or no claim.
+
+```typescript
+import {
+  Context,
+  Controller,
+  Get,
+  type RequestContext,
+} from "@antelopejs/interface-api";
+import { AuthUser } from "@antelopejs/interface-dms/auth";
+import { getRequestTenantId } from "@antelopejs/interface-dms/request-tenant";
+import type { User } from "@antelopejs/interface-dms/auth/db";
+
+export class WorkspaceController extends Controller("/api/workspace") {
+  @Get("/current")
+  async current(@AuthUser() _user: User, @Context() ctx: RequestContext) {
+    return { tenantId: getRequestTenantId(ctx) };
+  }
+}
+```
+
+The returned id is **decoded, not verified**: the function does not check the token's signature. It is safe behind a decorator that already authenticated the request — the guards from [Permissions](/docs/interfaces/core/permissions), `AuthUser` from `@antelopejs/interface-dms/auth`, or the auth a `PageController` installs. Do not authorize on the id in a route that no such decorator gates.
+
+## Scope a Model to the Request's Tenant
+
+`TenantScopedModel(ModelClass)` is a parameter and property decorator that injects `GetModel(ModelClass, getRequestTenantId(ctx))`.
+
+```typescript
+import { Controller, Get } from "@antelopejs/interface-api";
+import { AuthTenantMember } from "@antelopejs/interface-dms/guards";
+import { RoleModel } from "@antelopejs/interface-dms/db";
+import { TenantScopedModel } from "@antelopejs/interface-dms/tenant-scoped-model";
+import type { User } from "@antelopejs/interface-dms/auth/db";
+
+export class RoleController extends Controller("/api/roles") {
+  @Get("/list")
+  async list(
+    @AuthTenantMember() _user: User,
+    @TenantScopedModel(RoleModel) roles: RoleModel,
+  ) {
+    return roles.getAll();
+  }
+}
+```
+
+As a property decorator it fills a data controller's `@ModelReference()` field:
+
+```typescript
+import { ModelReference } from "@antelopejs/interface-data-api/metadata";
+import { RoleModel } from "@antelopejs/interface-dms/db";
+import { TenantScopedModel } from "@antelopejs/interface-dms/tenant-scoped-model";
+
+// inside a DataController subclass
+@ModelReference()
+@TenantScopedModel(RoleModel)
+declare model: RoleModel;
+```
+
+Only use it for a model whose table lives in `TENANT_SCHEMA_NAME` or another schema with one instance per tenant. For a core-schema table, take the model without an instance id.
+
+## Tenant Access Gates
+
+A gate is a binary, tenant-level check, evaluated at every tenant authorization surface. It answers whether the tenant may use the product at all, independently of any permission set.
+
+```typescript
+import { RegisterTenantAccessGate } from "@antelopejs/interface-dms/tenant-access";
+
+export async function construct(): Promise<void> {
+  RegisterTenantAccessGate({
+    id: "my_app.subscription-status",
+    order: 100,
+    gate: async (userId, tenantId) => {
+      if (await tenantIsSuspended(tenantId)) {
+        return { allowed: false, code: "my_app.errors.tenant_suspended" };
+      }
+      return { allowed: true };
+    },
+  });
+}
+```
+
+```typescript
+type TenantAccessResult = { allowed: true } | { allowed: false; code: string };
+
+type TenantAccessGateFn = (
+  userId: string | undefined,
+  tenantId: string,
+) => Promise<TenantAccessResult> | TenantAccessResult;
+```
+
+`TenantAccessGateInfo` carries `id`, `gate` and `order`.
+
+Semantics the interface guarantees:
+
+- Gates run in ascending `order`, ties in registration order; the first denial wins and its `code` is what reaches the client.
+- Registering an id twice replaces the earlier gate rather than adding a second one.
+- A gate that throws fails the request.
+- The registration is removed when the registering module unloads.
+- Register in `construct()` so the gate is active before the API serves requests.
+- `userId` is `undefined` for an unauthenticated request.
+
+Two functions evaluate the gates:
+
+| Function | Behavior |
+| -------- | -------- |
+| `CheckTenantAccess(userId, tenantId)` | Resolves to the first denial, or `{ allowed: true }`. |
+| `AssertTenantAccess(userId, tenantId)` | Calls `CheckTenantAccess` and throws a `403` whose body is the denying gate's `code`. |
+
+```typescript
+import {
+  AssertTenantAccess,
+  CheckTenantAccess,
+} from "@antelopejs/interface-dms/tenant-access";
+
+const access = await CheckTenantAccess(user._id, tenantId);
+if (!access.allowed) {
+  // access.code is a machine-readable key
+}
+
+await AssertTenantAccess(user._id, tenantId); // or let it throw
+```
+
+`AuthTenantOwner` and `AuthTenantMember` call `AssertTenantAccess` unless the route opts out with `bypassTenantAccessGate` ([Permissions](/docs/interfaces/core/permissions)).
+
+Use a gate to deny a tenant outright; use a permissions resolver to shape what its users may do.
+
+## Memberships and Ownership
+
+`applyTenantOwnership(userModel, userId, tenantId, patch)` upserts a membership row for the user in the tenant.
+
+```typescript
+import { GetModel } from "@antelopejs/interface-database-decorators";
+import { applyTenantOwnership } from "@antelopejs/interface-dms/tenant-ownership";
+import { UserModel } from "@antelopejs/interface-dms/auth/db";
+
+await applyTenantOwnership(GetModel(UserModel), userId, tenantId, {
+  roleIds: ["role-editor"],
+  isTenantOwner: false,
+});
+```
+
+`TenantMembershipPatch` is the fourth argument:
+
+| Field | Type | Description |
+| ----- | ---- | ----------- |
+| `roleIds` | `string[]` | Roles the member holds after the write. Replaces the previous list. |
+| `isTenantOwner` | `boolean` | Ownership flag after the write. |
+| `invitedBy` | `string \| null` | Recorded on insert. Ignored when the membership row already exists. |
+
+When the user is not yet a member, `applyTenantOwnership` fires `Hook.MEMBER_BEING_ADDED` before the write and `Hook.MEMBER_ADDED` after it. For an existing member it updates `roleIds` and `isTenantOwner` and fires neither ([Hooks](/docs/interfaces/core/hooks)).
+
+Two helpers keep the legacy platform-owner flag on the user row aligned with tenant ownership:
+
+| Function | Signature |
+| -------- | --------- |
+| `syncPlatformOwnerOnTenantOwnerChange` | `(userModel, userId, tenantId, nextIsTenantOwner: boolean) => Promise<void>` |
+| `clearPlatformOwnerOnMemberRemoval` | `(userModel, userId, tenantId, removedMemberWasTenantOwner: boolean) => Promise<void>` |
+
+Both mirror the value onto `User.owner`, and both are no-ops outside the default tenant and when the backend runs in [SaaS mode](#saas-mode) — where `User.owner` means platform ownership rather than tenant ownership. `clearPlatformOwnerOnMemberRemoval` additionally does nothing when the removed member was not a tenant owner. Call them after a write that changes ownership by a path other than `applyTenantOwnership`, which already mirrors on its own.
+
+### SaaS Mode
+
+By default, the owners of the default tenant are the platform owners. In SaaS mode the two are independent: tenant owners are customers, and platform ownership is managed on its own. The SaaS module declares that mode itself with `RegisterSaasMode`; the DMS never infers it from the modules it finds loaded.
+
+```typescript
+import { RegisterSaasMode } from "@antelopejs/interface-dms/utils/saas-mode";
+
+export async function construct(): Promise<void> {
+  RegisterSaasMode();
+}
+```
+
+While SaaS mode is on:
+
+- the default tenant's owner flag is no longer mirrored onto `User.owner`, by `applyTenantOwnership` or by the two helpers above;
+- removing members from the default tenant no longer refuses to remove the last platform owner.
+
+The registration is removed when the registering module unloads, and the mode stays on while at least one registration is active. `isSaasMode()` resolves to the current state, `false` until a module registers. Both behaviours read it on every request, so it does not matter whether the SaaS module registers before or after the DMS starts.
+
+## Tenant Lifecycle Admission
+
+Membership and invite producers coordinate with tenant deletion through `@antelopejs/interface-dms/tenant-lifecycle`. This is a write-lifecycle contract, not an authorization check or a transaction: authorize the caller separately.
+
+### `runTenantLifecycleOperation`
+
+`runTenantLifecycleOperation<T>(tenantId: string, work: () => Promise<T>): Promise<T>` admits one invocation before calling `work`, then returns its result after releasing that invocation's admission. Closed admission rejects without running `work`. Built-in membership and invite entry points already participate; custom producers must use this entry point and await every effect, with no detached writer.
+
+A successful callback releases its admission. A deliberate HTTP 4xx refusal also attempts release and rethrows the original refusal; other failures retain admission because their effects may be indeterminate. Retrying is a new invocation and never retires the failed one's identity. There is no automatic expiry or reconciliation API.
+
+### `closeTenantLifecycleAdmission`
+
+`closeTenantLifecycleAdmission(tenantId: string): Promise<void>` permanently closes admission, then checks that no admitted operation remains. It rejects if work is active or indeterminate, or if the database cannot confirm the transition. Rejection can leave admission closed: it never authorizes deletion or reopening.
+
+Call it before any destructive tenant phase, including deletion hooks. Do not delete business data when closure rejects. Preserve the `tenant_lifecycle` and `invite_resolutions` safety rows after deletion; dropping the tenant schema or recreating those rows can reopen admission. Mixed-version writers and raw model writes bypassing admission prevent a safe rollout. These table names describe a preservation obligation, not supported raw-model APIs.
+
+The [backend-services guide](/docs/building/backend-services#tenant-deletion-closes-producer-admission-first) explains where this fits in a module's deletion flow.
+
+## Built-in Data Controllers
+
+The interface ships the two data controllers the built-in settings screens are built on. The DMS module registers both itself, so their routes exist as soon as it is loaded: reference them, do not register them again.
+
+| Export | Import from | Table | Base path |
+| ------ | ----------- | ----- | --------- |
+| `memberSettingDataAPI` | `@antelopejs/interface-dms/data-controllers` | `TenantMember` | `/api/tables/members` |
+| `roleSettingDataAPI` | `@antelopejs/interface-dms/data-controllers/roles` | `Role` | `/api/tables/roles` |
+
+The `/data-controllers` barrel re-exports the members controller only; the roles controller is imported from its own path.
+
+```typescript
+import { roleSettingDataAPI } from "@antelopejs/interface-dms/data-controllers/roles";
+import { DefaultDataTypes } from "@antelopejs/interface-dms/base/data-types/default-types";
+
+// a role picker on one of your own form fields
+const reviewerRolesField = {
+  id: "reviewerRoleIds",
+  label: "Reviewer roles",
+  type: new DefaultDataTypes.RelationType({
+    multiple: true,
+    dataApiController: roleSettingDataAPI,
+    keyMapping: { label: "name", value: "_id" },
+  }),
+};
+```
+
+Both bind their model with `TenantScopedModel`, so they read and write the request's tenant. `memberSettingDataAPI` exposes the member's `name` and `email` joined from the `User` table, the member's roles as a plain relation onto `roleSettingDataAPI` (the DMS members page draws it with its own role picker, through the edit form's component slot), `isTenantOwner`, `joinedAt`, `isValidated` and a computed `connected` field; `roleSettingDataAPI` exposes `name`, `permissions`, `createdAt` and `updatedAt`. Reference either one as the relation target of your own columns when you need a member or role picker, or feed one to a `TableView` to render it.
+
+## Next Steps
+
+[Invites](/docs/interfaces/core/invites) covers bringing a user into a tenant that has no membership row for them yet.

package/docs/1.core/6.invites.md

@@ -0,0 +1,239 @@
+---
+title: "Invites"
+description: "An invite brings a person into a tenant by email."
+---
+
+# Invites
+
+## Overview
+
+An invite brings a person into a tenant by email. `inviteUserToTenant` is the entry point: when the email already belongs to a user it grants them membership directly, and otherwise it creates a token-bearing invite row the person redeems later. The two outcomes are distinguished by the `kind` field of the result.
+
+The functions live in `@antelopejs/interface-dms/invites`; the `UserInvite` table and its model live in `@antelopejs/interface-dms/db`.
+
+## Invite a User
+
+```typescript
+import { inviteUserToTenant } from "@antelopejs/interface-dms/invites";
+
+const result = await inviteUserToTenant({
+  tenantId,
+  email: "alice@example.com",
+  roleIds: ["role-editor"],
+  asTenantOwner: false,
+  sendEmail: true,
+});
+
+if (result.kind === "added") {
+  // an account with that email existed: membership granted, no token
+  return { userId: result.userId };
+}
+
+// no account yet: an invite row was created
+return { inviteId: result.inviteId, token: result.token };
+```
+
+### `InviteUserToTenantOptions`
+
+| Option | Type | Description |
+| ------ | ---- | ----------- |
+| `tenantId` | `string` | Tenant the person is invited into. Required. |
+| `email` | `string` | Email to look up and, failing that, to invite. Required. |
+| `firstname` | `string \| null` | Invitee's first name, stored on the invite row and used to address the email. Defaults to `null`. |
+| `lastname` | `string \| null` | Invitee's last name. Defaults to `null`. |
+| `language` | `string` | Language stored on the invite row. Defaults to `"en"`. |
+| `roleIds` | `string[]` | Roles granted on join. Defaults to `[]`. |
+| `asTenantOwner` | `boolean` | Grant tenant ownership on join. Defaults to `false`. |
+| `sendEmail` | `boolean` | Dispatch the admin invite email after the row is created. Defaults to `false`. |
+| `awaitEmailDelivery` | `boolean` | With `sendEmail`, wait for the email and report its outcome as `emailDelivery` instead of sending it in the background. Defaults to `false`. |
+| `inviterName` | `string` | Name of the sender shown in the invitation email. |
+| `invitedBy` | `string \| null` | Id of the inviting user, stored on the invitation. |
+| `extensions` | `InviteExtensionPayloads` | Payloads keyed by registered invite extension key. |
+
+### `InviteUserToTenantResult`
+
+```typescript
+type InviteEmailDelivery = "sent" | "failed";
+
+type InviteUserToTenantResult =
+  | { kind: "added"; userId: string }
+  | InvitedUserResult;
+
+interface InvitedUserResult {
+  kind: "invited";
+  inviteId: string;
+  token: string;
+  emailDelivery?: InviteEmailDelivery; // only with sendEmail + awaitEmailDelivery
+}
+```
+
+The `"added"` branch runs `applyTenantOwnership` with `roleIds` and `asTenantOwner` ([Tenancy](/docs/interfaces/core/tenancy)), so the member hooks fire and no token is generated. The `"invited"` branch creates the invite row through `createUserInviteToken`, then dispatches the email when `sendEmail` is set. By default that is fire-and-forget: the call does not wait on delivery and does not fail when delivery does.
+
+Pass `awaitEmailDelivery: true` when someone is waiting on the answer and has to learn that the email did not leave. The call then waits for the email and sets `emailDelivery` to `"sent"` or `"failed"`. It still does not throw: the invitation is kept either way, so the caller can offer to resend it. The failure's details (the provider's error) go to the server log only; tell the user something generic. The DMS members **Invite** form and the pending invitations' **Resend** action both work this way.
+
+```typescript
+const result = await inviteUserToTenant({
+  tenantId,
+  email: "alice@example.com",
+  sendEmail: true,
+  awaitEmailDelivery: true,
+});
+
+if (result.kind === "invited" && result.emailDelivery === "failed") {
+  // the invite exists, but its email did not leave: say so, offer a resend
+}
+```
+
+The function is deliberately side-effect-light: it does not throw on duplicates and performs no context-specific pre-checks. Decide in the caller what "already a member" should answer.
+
+## Create an Invite Token Directly
+
+`createUserInviteToken` is the lower-level half — it always creates a row and never touches memberships or email.
+
+```typescript
+import { createUserInviteToken } from "@antelopejs/interface-dms/invites";
+
+const { inviteId, token } = await createUserInviteToken({
+  tenantId,
+  email: "alice@example.com",
+  language: "en",
+  roleIds: [],
+  asTenantOwner: false,
+});
+```
+
+`CreateUserInviteTokenOptions` requires `tenantId`, `email`, `language`, `roleIds` and `asTenantOwner`; `firstname` and `lastname` are optional and default to `null`. Optional `invitedBy` records the sender and `extensions` carries `InviteExtensionPayloads`. `replacementReason` selects `"replaced"` (default) or `"resent"` when retiring an existing invitation. `CreateUserInviteTokenResult` is `{ inviteId: string; token: string }`.
+
+Optional `replacesInvite: UserInvite` identifies the exact incarnation being replaced, including a retained snapshot during a retry.
+
+`inviteeDisplayName(firstname?, lastname?)` joins the two into the name the invite email addresses the person by, and returns `undefined` when the invite carries neither. `inviteUserToTenant` calls it for you; call it yourself when you render your own invite surface from a stored row, so the fallback for a nameless invite matches what the email does.
+
+An existing invite for the same email in the same tenant is retired through a durable decision. Completion invokes `Hook.INVITE_DELETED` for the old invitation, then creates the replacement through `Hook.INVITE_BEING_CREATED` and `Hook.INVITE_CREATED`, and removes the old row. Failed completion can replay hooks with the same delivery identity; see [durable invite resolution](#durable-invite-resolution) and [Hooks](/docs/interfaces/core/hooks).
+
+## Token Constants
+
+| Constant | Value | Meaning |
+| -------- | ----- | ------- |
+| `INVITE_TOKEN_LENGTH` | `64` | Length of the generated token. |
+| `INVITE_EXPIRY_DAYS` | `7` | Days from creation to `expiresAt`. |
+
+```typescript
+import {
+  INVITE_EXPIRY_DAYS,
+  INVITE_TOKEN_LENGTH,
+} from "@antelopejs/interface-dms/invites";
+```
+
+## The `UserInvite` Table
+
+Table `user_invites` in the `dms-tenant` schema, so invites are per-tenant like memberships. The table-name constant `USER_INVITES_TABLE_NAME` is exported next to it.
+
+| Field | Type | Notes |
+| ----- | ---- | ----- |
+| `_id` | `string` | Invite id — the `inviteId` the create functions return. |
+| `createdAt` | `Date` | Creation time, indexed. |
+| `email` | `string` | Indexed. |
+| `firstname` | `string \| null` | Invitee's first name, when the invite carried one. |
+| `lastname` | `string \| null` | Invitee's last name, when the invite carried one. |
+| `roles_ids` | `string[]` | Related to `Role`, many. Roles to grant on redemption. |
+| `language` | `string` | Language the invite was issued in. |
+| `token` | `string` | Indexed. The secret handed to the invitee. |
+| `asTenantOwner` | `boolean` | Grant tenant ownership on redemption. |
+| `expiresAt` | `Date` | Indexed. `INVITE_EXPIRY_DAYS` after creation. |
+
+Note the field is `roles_ids`, not `roleIds` — the membership field of that name lives on `TenantMember` ([Tenancy](/docs/interfaces/core/tenancy)).
+
+## `UserInviteModel`
+
+`UserInviteModel` extends `BasicDataModel(UserInvite, USER_INVITES_TABLE_NAME)`:
+
+| Method | Returns |
+| ------ | ------- |
+| `getByEmail(email)` | `Promise<UserInvite \| undefined>` |
+| `getByToken(token)` | `Promise<UserInvite \| undefined>` |
+| `getByTokenWithTenant(token)` | `Promise<{ invite: UserInvite; tenantId: string } \| undefined>` |
+| `deleteByToken(token)` | Deletes every row carrying the token |
+
+Invitations are stored with their e-mail trimmed and lowercased, and `getByEmail` normalizes its argument the same way, so the casing a caller passes does not matter.
+
+```ts docs-check
+import { GetModel } from "@antelopejs/interface-database-decorators";
+import { UserInviteModel } from "@antelopejs/interface-dms/db";
+
+export async function hasExpiredInvite(tenantId: string, email: string): Promise<boolean> {
+  const invite = await GetModel(UserInviteModel, tenantId).getByEmail(email);
+  return invite !== undefined && invite.expiresAt.getTime() < Date.now();
+}
+```
+
+`getByTokenWithTenant` reports the tenant the row came from, which is what a redemption flow needs: the person following an invite link is not authenticated yet, so there is no tenant claim to bind the handle to.
+
+Raw deletion, including `deleteByToken`, does not coordinate durable decisions or extension cleanup. Use the invite-resolution contract below for terminal actions, not direct model writes.
+
+## `RegisterInviteExtension`
+
+`RegisterInviteExtension<T>(options: InviteExtensionOptions<T>): () => void`, from `@antelopejs/interface-dms/invite-extensions`, contributes fields to the members invite form. Registration belongs to the module and is removed when it stops; the returned function removes it earlier.
+
+| Option | Type | Contract |
+| --- | --- | --- |
+| `key` | `string` | Required non-empty namespace. Must not contain `__`, the field-id separator. |
+| `component` | `FormBuilder` | Required form whose fields join the invite modal. |
+| `schema` | `ZodType<T, ZodTypeDef, unknown>` | Required validator at submission and delivery. Uses unprefixed field ids; callbacks receive parsed output `T`. |
+| `onAccept` | `InviteAcceptHandler<T>` | Required callback after membership exists. |
+| `onCleanup` | `InviteCleanupHandler<T>` | Optional cleanup on cancellation, replacement, expiry or member removal, never acceptance. |
+| `editable` | `boolean` | Defaults to `true`. `false` makes fields read-only on the pending-invitation edit form. |
+| `onUpdate` | `InviteUpdateHandler<T>` | Called after a changed pending payload is stored. Failure is logged, not raised to the caller. |
+| `label` | `string` | Heading, defaulting to the form's title. |
+| `description` | `string` | Description of the contribution. |
+| `placement` | `InviteExtensionPlacement` | Optional `side` (`"before"`, `"after"`, `"end"`), `anchorField`, and numeric `order`. Defaults to end, order 0. |
+
+`anchorField` names a top-level field or group of the invite form. Without an anchor, `before` places the contribution first; `after` and `end` append it. Lower orders come first, with extension keys breaking ties. Form field ids are namespaced by `key`; stored `InviteExtensionPayloads` is `Record<string, unknown>`, keyed by extension.
+
+### Callback contracts
+
+| Callback | Arguments | Return |
+| --- | --- | --- |
+| `InviteAcceptHandler<T>` | `(payload: T, member: TenantMember, context: InviteExtensionContext)` | `MaybePromise<void>` |
+| `InviteUpdateHandler<T>` | `(payload: T, previous: T \| undefined, context: InviteExtensionContext)` | `MaybePromise<void>` |
+| `InviteCleanupHandler<T>` | `(payload: T \| undefined, context: InviteCleanupContext)` | `MaybePromise<void>` |
+
+`InviteExtensionContext` has `tenantId`, `email`, and optional `deliveryId` and `inviteId`. Direct addition of an existing account calls `onAccept` without an `inviteId`. `previous` is undefined when no old payload exists or it no longer validates.
+
+`InviteCleanupContext` has `tenantId`, `reason: "invite-deleted" | "member-removed"`, and optional `deliveryId`, `inviteId`, `email`, and `userId`. Invite cleanup identifies the invitation; member cleanup identifies the user. Durable delivery may replay concurrently with the same `deliveryId`: deduplicate external effects and scope invite resource cleanup to `inviteId`. See [durable delivery guidance](/docs/building/backend-services#extension-and-hook-delivery) for operational obligations.
+
+## Durable Invite Resolution
+
+The functions in `@antelopejs/interface-dms/invite-resolution` coordinate competing terminal actions. They do not authorize the caller. Prefer the higher-level invitation entry points unless implementing a terminal action yourself.
+
+| Function | Signature and result |
+| --- | --- |
+| `loadInviteForAction` | `(tenantId: string, inviteId: string) => Promise<UserInvite \| undefined>` — loads the exact invitation or its durable snapshot after the live row is gone. |
+| `assertInviteReady` | `(tenantId: string, invite: UserInvite) => Promise<void>` — rejects with HTTP 409 while a replacement's creation is incomplete. |
+| `decideInvite` | `(input: ResolveInviteInput) => Promise<InviteResolution>` — records one permanent terminal outcome before effects. Conflicting reason, user or replacement content rejects with HTTP 409. A new acceptance of an expired invitation also rejects. |
+| `completeInviteResolution` | `(resolution: InviteResolution) => Promise<void>` — enters tenant lifecycle admission and replays effects; callback failures retain the snapshot for retry. |
+
+`ResolveInviteInput` contains `tenantId`, `invite: UserInvite`, `reason: InviteResolutionReason`, and optional `userId` and `replacement: UserInvite`. `InviteResolutionReason` is `"accepted" | "cancelled" | "replaced" | "resent" | "expired"`. The API captures extension keys itself; callers do not supply them.
+
+`InviteResolution` (from `/db/tables/inviteResolutions.table`) is the stored decision and retry snapshot: `_id`, `tenantId`, `reason`, nullable `userId`, `invite`, optional `inviteToken`, nullable `replacement`, `extensionKeys`, `revision`, `membershipPhase`, `replacementPhase`, `completed`, and `decidedAt`. Both phase fields use `InviteMembershipPhase` (`"pending" | "applying" | "applied"`). Treat these as read-only results and pass the decision back to completion; do not mutate the model to advance phases.
+
+Custom membership/invite producers must follow [tenant lifecycle admission](/docs/interfaces/core/tenancy#tenant-lifecycle-admission), and all competing terminal paths must decide before producing effects. A durable decision does not make external effects exactly-once; callback implementations still own idempotency.
+
+## Mark the Invite Action Unavailable
+
+`RegisterInviteAvailability`, from `@antelopejs/interface-dms/invite-extensions`, lets a module disable the members page's **Invite** button while one of its conditions holds — a plan whose seats are all taken, say. The resolver runs per request while the page layout is built, with `{ tenantId, user }`; returning `{ reason }` disables the button and shows the reason next to it, `undefined` leaves it enabled. The first resolver to refuse wins, and one that throws is logged and ignored.
+
+```typescript
+import { RegisterInviteAvailability } from "@antelopejs/interface-dms/invite-extensions";
+
+RegisterInviteAvailability(async ({ tenantId }) =>
+  (await hasFreeSeat(tenantId))
+    ? undefined
+    : { reason: "$acme.seats.invite_unavailable" },
+);
+```
+
+It only shapes the UI. A module that must refuse the invitation itself does so from `Hook.INVITE_BEING_CREATED` and `Hook.MEMBER_BEING_ADDED`. The registration is lifted when the registering module stops; the returned function removes it earlier.
+
+## Next Steps
+
+[Hooks](/docs/interfaces/core/hooks) covers the invite and membership events these functions fire, and how to react to them.