@antelopejs/interface-dms 0.10.4 → 0.12.0

package/docs/1.core/11.modules-and-dynamic-menus.md

@@ -0,0 +1,178 @@
+---
+title: "Modules and dynamic menus"
+description: "Register a module root in the sidebar, report its state on the modules catalog, and add menu entries resolved per request."
+mode: reference
+---
+
+A module is a feature area with its own root in the sidebar, under `/modules`. A dynamic menu provider adds menu entries resolved for each request, such as one entry per project a tenant owns. Both live in `@antelopejs/interface-dms/page`. Pages and categories, which modules group, are described in [Pages and modules](/docs/interfaces/core/pages-and-modules).
+
+## Declare a module
+
+`RegisterModule(info)` creates the module root under `modulesCategory` and returns its `CategoryInfo`.
+
+```typescript
+import { RegisterModule } from "@antelopejs/interface-dms/page";
+
+RegisterModule({
+  id: "automation",
+  title: "$dms_automation.module.title",
+  description: "$dms_automation.module.description",
+  icon: "i-ph-flow-arrow",
+  defaultCategory: { displayName: "$dms_automation.module.pages", order: 0 },
+});
+```
+
+Call `RegisterModule` before any page that names the module id. A page resolves its module inside the `PageController` call of its class declaration, before `@RegisterPage()` runs, and an unknown module id throws. Registering the same id twice also throws.
+
+### `ModuleInfo`
+
+| Option | Type | Description |
+| ------ | ---- | ----------- |
+| `id` | `string` | Module id. Also the URL segment under `/modules`. Required. |
+| `title` | `string` | Display name of the module root. Required. |
+| `description` | `string` | Description carried on the module root. Required. |
+| `icon` | `string` | Icon name. Required. |
+| `landingPage` | `string` | Id of the page the module opens on. `/modules/<id>` redirects to it and keeps the query and hash. Defaults to the first page by `order`. An id that matches no page of the module logs a warning and falls back to that default. |
+| `version` | `string` | Version shown on the catalog tile (`1.4.0`). |
+| `catalogCategory` | `string` | Category the module is filed under in the module catalog (`"Content"`, `"Developer"`), possibly a `$` i18n key. The Modules page and the module store both use it. Without one, a store module takes the category of the store catalog, and any other module goes under "Other". It has no relation to menu categories (`MenuOptions.category`, `defaultCategory`). |
+| `status` | `(context: ModuleCatalogContext) => MaybePromise<ModuleStatus>` | Reports the module's state on its catalog tile. |
+| `readout` | `(context: ModuleCatalogContext) => MaybePromise<ModuleReadoutLine[]>` | Returns short lines that say what the module is doing now. |
+| `defaultCategory` | `{ displayName?, icon?, order?, urlSlug? }` | Groups the module's pages that declare `module` without a `category`. Without it, those pages attach directly to the module root. |
+
+The generated default category has the id `pages` and the `urlSlug` `"pages"` unless you set one. Its label falls back to `"$menu.section.pages"` when `displayName` is empty or omitted.
+
+### Catalog hooks
+
+The DMS calls `status` and `readout` on each load of the modules catalog. The catalog is for platform owners only. Each hook receives a `ModuleCatalogContext`:
+
+```typescript fragment
+interface ModuleCatalogContext {
+  user: User | undefined;
+  tenantId: string;
+}
+```
+
+`ModuleStatus` is `"live" | "beta" | "update" | "attention"`. `live` means the module works normally, `beta` that it is usable and still changing, `update` that a newer version is available, and `attention` that a platform owner must act, for example on a failing job. A module without `status` shows as `live`.
+
+`ModuleReadoutLine` is `{ text: string; tone?: ModuleReadoutTone }`, where `text` may be a `$` i18n key and `ModuleReadoutTone` is `"success" | "info" | "warning" | "error"`. The tile shows at most three lines. A line with empty text is dropped, and a tone outside the four values shows as `info`.
+
+A hook that throws, or that does not answer within two seconds, is ignored and logged once. The tile then shows `live` and no readout. A `status` that returns a value outside `ModuleStatus` also falls back to `live`.
+
+### Attach pages to a module
+
+Set `module` on the page options. `category` stays available to group pages inside the module:
+
+```typescript fragment
+import {
+  PageController,
+  RegisterPage,
+} from "@antelopejs/interface-dms/page";
+import "./module";
+
+@RegisterPage()
+export class OverviewPage extends PageController("overview", {
+  displayName: "$dms_automation.overview.title",
+  icon: "i-ph-gauge",
+  module: "automation",
+  order: 0,
+}) {}
+```
+
+The bare `./module` import runs the file that calls `RegisterModule`, so the module exists before the page declares itself.
+
+A page that declares both `module` and a `category` must name a category under that module's root. Otherwise registration throws. A page or category that declares `module` cannot sit under `settingsCategory` either. Registration throws for that combination too.
+
+### Module URLs and ids
+
+`MODULE_URL_PREFIX` is `"/modules"`. The module root's `urlSlug` is the module id and its parent is `modulesCategory`, so module pages resolve under `/modules/<moduleId>/...`. Their ids follow the same chain. The module root's `fullId` is `modules.<moduleId>`. A page attached to the root is `modules.<moduleId>.<pageId>`, and a page in the default category is `modules.<moduleId>.pages.<pageId>`.
+
+`isInsideModule(entry)` returns whether an entry belongs to a module. It accepts any object with optional `module`, `category` and `isModuleRoot` fields, so a `CategoryInfo` or a `PageInfo` qualifies. It returns `true` when the entry is a module root or declares `module`, and otherwise walks the category chain looking for a module root.
+
+```typescript fragment
+import { isInsideModule } from "@antelopejs/interface-dms/page";
+
+if (isInsideModule(pageInfo)) {
+  showOwnerBadge();
+}
+```
+
+The permissions of a module entry are marked module-scoped instead of entering the grantable permission tree, and a module page is served to platform owners only. [Module-scoped permissions](/docs/interfaces/core/permissions#module-scoped-permissions) describes the consequences.
+
+## Contribute menu entries at request time
+
+`Category`, `PageController` and `RegisterModule` declare the menu at import time. A dynamic menu provider adds entries resolved for each request, such as one entry for each project or workspace the tenant owns.
+
+```typescript fragment
+import { RegisterDynamicMenuProvider } from "@antelopejs/interface-dms/page";
+
+RegisterDynamicMenuProvider("pages.projects", async (user, tenantId) => {
+  const projects = await listProjects(tenantId);
+  return projects.map((project, index) => ({
+    id: project.slug,
+    displayName: project.name,
+    fullSlug: "/projects/:projectId",
+    params: { projectId: project.id },
+    icon: "i-ph-folder",
+    order: index,
+  }));
+});
+```
+
+```typescript fragment
+function RegisterDynamicMenuProvider(
+  categoryFullId: string,
+  resolver: DynamicMenuResolver,
+): () => void;
+
+type DynamicMenuResolver = (
+  user: User | undefined,
+  tenantId: string,
+  permissions: Set<string>,
+) => MaybePromise<DynamicMenuItem[]>;
+```
+
+A registration is a `DynamicMenuProviderInfo`, which pairs the `categoryFullId` and the `resolver`. The resolver runs during `/sitelayout`. Its entries go into that request's copy of the tree only, and the global navigation tree never changes, so one tenant's entries never reach another tenant's site layout. The dynamic and static children of a category sort together by `order`, then by display name and id, so entries of equal rank keep the same order on every host and across restarts.
+
+`permissions` is the caller's effective permission set as the parent category sees it. The set is empty while a tenant access gate denies the tenant, unless the category is flagged `bypassTenantAccessGate`, which keeps the real set. `user` is `undefined` for an unauthenticated request.
+
+Providers run concurrently. A provider that throws, or that does not answer within two seconds, contributes nothing to that request and is reported once. The rest of the menu still resolves, and the provider's entries return when it answers again.
+
+The registration belongs to the registering module, not to the category it targets. A provider whose category is not registered stays dormant and resolves as soon as the category appears, so module start order and hot reloads need no coordination. The registration is removed when the registering module unloads. The returned function removes it earlier, for a module that stops providing entries while it stays loaded.
+
+### `DynamicMenuItem`
+
+An item is not a page. It links to a registered page, so one page can back any number of entries. That page typically has `:name` segments in its slug, or declares `validation.requiredQueryParams`.
+
+`params` fills the `:name` segments of `fullSlug` with URL-encoded values, and the entry links to the result. `fullSlug: "/projects/:projectId"` with `params: { projectId: "acme" }` links to `/projects/acme`. The values must fill every segment and nothing else. An entry that leaves a segment empty, or that names a parameter the slug does not have, is skipped with a warning.
+
+| Field | Type | Description |
+| ----- | ---- | ----------- |
+| `id` | `string` | Unique among siblings. The DMS appends it to the parent's `fullId` with a dot, and top-level entries use the provider category as their parent. An id that contains a dot is skipped with a warning. For a duplicate sibling id, the first admitted entry wins and the others are skipped with a warning. Required. |
+| `displayName` | `string` | Entry label. Required. |
+| `fullSlug` | `string` | Full slug of the page the entry links to, `:name` segments included. Required. |
+| `params` | `MenuItemParams` | Values for the `:name` segments of `fullSlug`. `MenuItemParams` is `Record<string, string>`. |
+| `query` | `MenuItemQuery` | Query parameters added to the link. |
+| `description` | `string` | Longer description. |
+| `icon` | `string` | Icon name. |
+| `order` | `number` | Sort order among the category's children, dynamic and static alike. |
+| `variant` | `MenuItemVariant` | Semantic look. |
+| `status` | `MenuItemStatus` | Status dot. It trails a leaf entry and sits on the leading icon of a parent, so a parent with a status declares an icon. |
+| `badge` | `string` | Short count or label at the end of the entry (`3`, `new`). |
+| `permissionId` | `string` | Permission required to see the entry, as a raw id. Unset means always visible. |
+| `children` | `readonly DynamicMenuItem[]` | Nested entries. An omitted or empty array means a leaf. |
+
+The DMS lists an entry only when the caller can access its target page, so the menu never offers a link that the target refuses. Each child is admitted on its own target access and permission, and a parent that is not admitted drops its whole subtree. The tree is at most three levels deep, counting provider entries as level 1. Deeper entries are dropped with a warning.
+
+`permissionId` is a raw id, unlike `MenuOptions.permission`, which takes a whole permission or an `Action`. It is matched against the permission set the caller's browser receives, the way the browser matches it: the wildcard or a literal grant, never a `defaultGranted` fallback. The sidebar therefore never offers an entry whose controls would be inert. While a gate denies the tenant, that set holds only the surfaces flagged `bypassTenantAccessGate`, so a recovery entry declares its permission under its target page, as in `<recoveryPageFullId>.settle`.
+
+`permissionId` decides only whether the entry is listed. The target page receives the entry's `query` like any other input from the caller, and it authorizes the value itself.
+
+### `NotifyMenuChanged`
+
+```typescript fragment
+const NotifyMenuChanged: (tenantId?: string) => void;
+```
+
+Call `NotifyMenuChanged` when the data behind a provider changes, for example after a project is created or deleted, so connected clients resync. The signal carries no data. Each client fetches its own `/sitelayout` again, resolved against its own permissions.
+
+Pass the `tenantId` whose data changed, so only that tenant's sessions fetch again. Without it, the menu of every connected session is invalidated, which suits changes that are not scoped to a tenant.

package/docs/1.core/12.frontend-modules-and-request-helpers.md

@@ -0,0 +1,155 @@
+---
+title: "Frontend modules and request helpers"
+description: "Register the frontend a module ships, sign upload fields, build public links, read the client address, and save native files from a write route."
+mode: reference
+---
+
+A module's backend uses these functions to ship a frontend, to serve components outside a registered page, and to handle requests. Each section names the subpath it imports from. Pages, which call most of them for you, are described in [Pages and modules](/docs/interfaces/core/pages-and-modules).
+
+## Ship a frontend module
+
+`AddFrontendModule(config)` registers a frontend module that your module ships. Call it from your module's `construct()`.
+
+```typescript
+import path from "node:path";
+import { AddFrontendModule } from "@antelopejs/interface-dms/page";
+
+export async function construct(): Promise<void> {
+  await AddFrontendModule({
+    name: "@acme/dms-billing",
+    sourcePath: path.join(__dirname, "../frontend-vue"),
+    renderer: { name: "vue", version: "3" },
+    configKey: "dmsBilling",
+    priority: 0,
+    options: { prefix: "Billing" },
+  });
+}
+```
+
+### `AddFrontendModuleOptions`
+
+| Option | Type | Description |
+| ------ | ---- | ----------- |
+| `name` | `string` | Logical frontend module name. The registry identity also includes the renderer name and major version. Required. |
+| `sourcePath` | `string` | Absolute path to the frontend module directory. Required. |
+| `renderer` | `FrontendRendererMetadata` | Framework the module is written for: a `name` and a `version` compared by major only. Use `{ name: "vue", version: "3" }` for the Inertia and Vue frontend. The `package.json` of `sourcePath` declares the loader releases the module runs on ([Frontend layer](/docs/building/frontend-layer#declaring-the-loader-releases-a-module-supports)). Required. |
+| `options` | `FrontendModuleOptions` | JSON-like values handed to the layer's configuration. Defaults to `{}`. |
+| `privateOptions` | `FrontendModuleOptions` | A second set of values for the layer, kept apart from `options` and left out of `GetFrontendModules()`. Defaults to `{}`. |
+| `priority` | `number` | Order among registered layers. Defaults to `0`. |
+| `configKey` | `string` | Configuration key the layer is published under. |
+| `authEstablishEndpoints` | `string[]` | Backend routes under `/api/` from which the frontend server may open a session for the module, through its `/auth/establish` route. Each is an absolute path with no query string and no segment that climbs out. A malformed entry fails the registration. |
+| `publicEndpoints` | `FrontendPublicEndpoint[]` | Backend routes the module serves to callers outside the dashboard, such as a provider's webhook. See [Public endpoints](#public-endpoints). |
+| `backendProxies` | `FrontendBackendProxy[]` | Backend prefixes outside `/api/**` and `/dms/**` that the browser reaches through the frontend server, such as `{ path: "/media/**", auth: "none" }`. |
+
+A `FrontendBackendProxy` has a `path` and an optional `auth`. `path` is `/x`, `/x/*` or `/x/**`, with a literal first segment outside the renderer's own paths (`/api/_dms`, `/@`, `/assets`, `/node_modules`). `auth` is `"session"`, the default, which adds the session's access token on the server and requires the frontend's own `Origin` on a state-changing request, or `"none"`, which never sends the session. A malformed entry fails the registration.
+
+Within one logical name, renderer and major version, the registration with the highest `priority` wins, and among equal priorities the latest one wins. The manifest and archive endpoints select a renderer with the paired `renderer` and `rendererVersion` query parameters, matched on the major version. A selection that matches no registered renderer answers `404`, and a request that passes only one of the two parameters answers `400`. A request with neither selects `renderer=vue` and `rendererVersion=3`.
+
+#### Public endpoints
+
+The frontend server's proxy requires a same-site `Origin` on every state-changing request, forwards it with the signed-in user's session, and relays only a few headers. A webhook that a mail or payment provider calls through the dashboard's public URL fails both checks. Declare such a route public:
+
+```typescript fragment
+await AddFrontendModule({
+  name: "@acme/dms-mailing",
+  sourcePath: path.join(__dirname, "../frontend-vue"),
+  renderer: { name: "vue", version: "3" },
+  publicEndpoints: [
+    {
+      path: "/api/mailing/events/*/*",
+      methods: ["POST"],
+      headers: ["x-mailing-webhook-secret"],
+    },
+  ],
+});
+```
+
+A request to a declared route needs no `Origin`, carries the declared headers, and is never sent the session, even from a signed-in browser. A cross-site form that posts to it acts as nobody, so the route authenticates its caller itself, with a shared secret or a signature.
+
+A `FrontendPublicEndpoint` has three fields:
+
+- `path` is absolute under `/api/`. Its first segment after `/api/` is literal, the module's own prefix and never `*`, and each later `*` matches exactly one segment. It has no query string, no prefix match, and no `.` or `..` segment.
+- `methods` lists the methods it answers, among `GET`, `HEAD`, `POST`, `PUT`, `PATCH` and `DELETE`. Defaults to `["POST"]`.
+- `headers` names the module's own `x-` request headers. Headers that a proxy or the DMS gives a meaning to (`x-forwarded-*`, `x-real-ip`, `x-dms-*`, `x-inertia*`, method overrides) are refused.
+
+A malformed entry fails the registration. The declarations reach the frontend server through the manifest it is built from, on an authenticated build only, and its `DMS_PUBLIC_ENDPOINTS` setting adds routes that no module declares.
+
+### Frontend module discovery
+
+`GetFrontendModules()` returns a `FrontendModuleMetadata` for each registered frontend module: its `name`, `sourcePath`, `renderer`, `priority`, `options`, `authEstablishEndpoints`, `publicEndpoints`, and `backendProxies` with each `auth` filled in. It never returns `privateOptions`. `FrontendModulesChanged` is an event that fires whenever that list changes. Modules start in parallel, so a module that reads the list in its own `start()` registers a handler, reads the list once, and reads it again in the handler.
+
+A module can also ship a pure `FrontendModuleFunction`, exported as `frontendModule` from the file its `package.json` names under `dmsFrontend`. It takes the module's configuration and a `FrontendModuleContext` (`{ dev: boolean }`) and returns a `FrontendModuleRegistration`, the same shape as `AddFrontendModuleOptions`, or `undefined` when the configuration registers no frontend. The backend passes the result to `AddFrontendModule`, and `@antelopejs/dms-frontend` calls the function itself, so a frontend builds and starts without a backend. The function reads only its arguments. Any `privateOptions` it returns hold their shape only, every value an empty string, and the backend and the frontend server fill in the secrets.
+
+## Stamp upload tokens
+
+`StampUploadFieldTokens(options)` from `@antelopejs/interface-dms/uploads` takes a component's serialized options and returns them with a signed upload token in every file and image field. That covers the component's own fields and the forms it embeds, such as a relation field's inline add form or a table view's `new`, `edit` and `view` forms. The token binds each field to the storage and path it declares, so a client cannot presign an upload elsewhere.
+
+The builders that carry upload fields attach it through `transformOptions`, and page registration stamps the authoritative declaration, so pages declared with `@RegisterPage()` are already covered. Call it yourself only to serialize and serve components outside that path. A token produced outside a registered page stays unbound and cannot authorize an upload.
+
+```typescript fragment
+import { StampUploadFieldTokens } from "@antelopejs/interface-dms/uploads";
+
+const components = await StampUploadFieldTokens(layout.components);
+```
+
+Options without an upload field come back untouched. Otherwise the return value is a deep clone, because serialization runs again on a hot reload and each pass must start from the declaration as written.
+
+## Public URLs
+
+`GetApiBaseUrl()` from `@antelopejs/interface-dms/api-base-url` and `GetClientBaseUrl()` from `@antelopejs/interface-dms/client-base-url` return the public origins of the DMS API and of the dashboard. They come from the DMS configuration (`apiBaseUrl`, `clientBaseUrl`), and under `ajs dms dev` they follow the dev server's origins. Build an absolute link on them, not on the request's headers. Behind a reverse proxy that forwards no `X-Forwarded-Host`, the request knows only the internal host.
+
+```typescript
+import { GetApiBaseUrl } from "@antelopejs/interface-dms/api-base-url";
+import { GetClientBaseUrl } from "@antelopejs/interface-dms/client-base-url";
+
+const apiBase = await GetApiBaseUrl();
+const downloadUrl = `${apiBase}/i18n/site/fr.json`;
+const inviteUrl = `${await GetClientBaseUrl()}/auth/signup`;
+```
+
+Both return `string | undefined`, such as `"https://api.example.com"`. They return `undefined` only when the configuration clears the value.
+
+## Client address
+
+`getClientIp(context)` from `@antelopejs/interface-dms/client-ip` returns the address a request came from, resolved the way the DMS resolves the address it records on a session:
+
+- When `auth.clientIpHeader` is configured, from the header the hosting platform writes ([Client address from the platform](/docs/building/configuration#client-address-from-the-platform)).
+- Otherwise behind the `auth.trustedProxies` reverse proxies of the configuration ([Client address behind proxies](/docs/building/configuration#client-address-behind-proxies)). Each trusted hop vouches for the `x-forwarded-for` entry it appended, and nothing to the left of it counts.
+
+An IPv4-mapped address (`::ffff:10.0.0.1`) comes back as plain IPv4. Key a rate limit or an anonymous visitor on it, not on `x-forwarded-for` read by hand, so the operator declares the proxies once for the DMS and every module.
+
+```typescript
+import { Context, Controller, Post, type RequestContext } from "@antelopejs/interface-api";
+import { getClientIp } from "@antelopejs/interface-dms/client-ip";
+
+export class CollectController extends Controller("/api/collect") {
+  @Context()
+  declare requestContext: RequestContext;
+
+  @Post("/")
+  async collect(): Promise<{ address: string }> {
+    const address = await getClientIp(this.requestContext);
+    return { address };
+  }
+}
+```
+
+It returns an empty string when the request carries no address. `ResolveClientIp(source)` applies the same resolution to values a module already holds, such as a request it queued for later. Its `ClientAddressSource` has `socketAddress` and `forwardedFor`, both `string | undefined`, and optional `headers`, where the `auth.clientIpHeader` header is read.
+
+## `SaveComponentFiles`
+
+`SaveComponentFiles<T>(request: AttachmentSaveRequest, save: (promoted: Record<string, unknown>) => Promise<AttachmentSaveResult<T>>): Promise<T>` comes from `@antelopejs/interface-dms/attachments`. Call it from a write route, after authorization, to validate where native files came from, promote staging keys, and persist once through `save`. The [file storage guide](/docs/components/file-storage) covers the form and upload flow and storage authorization.
+
+`AttachmentSaveRequest` contains:
+
+| Field | Type | Contract |
+| --- | --- | --- |
+| `context` | `RequestContext` | The authorized server request. |
+| `componentIds` | `string[]` | Trusted component identities, never ids the client supplies. |
+| `fields` | `AttachmentField[]` | Attachment fields the server declares. |
+| `submitted` | `Record<string, unknown>` | The submitted values. |
+| `before` | `Record<string, unknown>` | The values persisted before, loaded by the server. |
+
+Each `AttachmentField` has `id` (matching the form's `attachmentField`), `key` (the document field), and `kind: "file" | "image"`. The optional `storage`, `visibility: "private" | "public"` and `constraints: UploadConstraints` select the provider and the upload policy. `UploadConstraints` comes from `@antelopejs/interface-file-storage`.
+
+The callback returns an `AttachmentSaveResult<T>` of `{ document, result }`. `document` holds the values actually saved, used for cleanup, and `result` goes back to the caller. Retained objects keep their declared visibility. Removed native files are deleted only after persistence succeeds, and cleanup failures are logged. A failed save leaves promoted objects in place, because another save may reference them. Cleanup is not reference-counted, so the caller must not share file keys between documents. The internal attachment validators and the table view save proxies are not entry points for consumers.

package/docs/1.core/13.tenant-data-export.md

@@ -0,0 +1,120 @@
+---
+title: "Tenant data export"
+description: "How a module contributes to the tenant data export. The contributor handler, the archive it writes into, and the manifest that records the outcome."
+mode: reference
+---
+
+`Hook.TENANT_DATA_EXPORT` asks every module for its part of one tenant's data, and the DMS assembles the parts into a single ZIP archive. It is the one hook whose handler produces something. A handler receives the tenant id, an archive to write into, and an `AbortSignal`. It contributes in either or both of two ways:
+
+- It returns a `TenantDataExportContribution`. The DMS serializes its `data` to `modules/<moduleId>.json`.
+- It writes entries into the `archive`, for data too large to hold in memory or that is not JSON.
+
+The types on this page live in `@antelopejs/interface-dms/tenant-export`. `@antelopejs/interface-dms/hooks` re-exports them, so either import path works. [Hooks](/docs/interfaces/core/hooks) covers the hook registry this contract builds on.
+
+## Register a contributor
+
+`RegisterTenantDataExportContributor` registers the handler with an explicit module id. That id namespaces the contributor's archive entries, so it no longer depends on the call site the runtime attributes the registration to. Prefer it to a bare `RegisterHook`.
+
+```typescript fragment
+import { RegisterTenantDataExportContributor } from "@antelopejs/interface-dms/hooks";
+
+RegisterTenantDataExportContributor(
+  "acme-billing",
+  async (tenantId, archive, signal) => {
+    await archive.addStream(
+      "invoices.ndjson",
+      streamInvoices(tenantId, signal),
+    );
+    return {
+      moduleId: "acme-billing",
+      data: await collectBillingSettings(tenantId),
+    };
+  },
+);
+```
+
+The helper's signature:
+
+```typescript
+import type { Hook, HookHandler } from "@antelopejs/interface-dms/hooks";
+
+declare function RegisterTenantDataExportContributor(
+  moduleId: string,
+  handler: HookHandler<Hook.TENANT_DATA_EXPORT>,
+): void;
+```
+
+The handler's arguments are `tenantId: string`, `archive: TenantExportArchive` and `signal: AbortSignal`. It returns a `TenantDataExportContribution`, or nothing when it only writes archive entries.
+
+```typescript
+interface TenantDataExportContribution {
+  moduleId: string;
+  data: unknown;
+}
+```
+
+## Module ids in the archive
+
+The DMS derives each contributor's directory name from the module id its registration recorded:
+
+- Every character other than a letter, a digit, `.`, `_` or `-` becomes `-`. A registration under `@acme/dms-billing` writes under `modules/-acme-dms-billing/`.
+- A registration with no module id gets `module-<index>`, its position among the contributors.
+- When two contributors resolve to the same name, the second gets the suffix `-2`, the third `-3`, and so on.
+
+The `moduleId` a contribution returns does not move its entries. When it differs from the resolved name, the manifest records it as `declaredModuleId`. Return the same id the registration uses, written in the allowed characters, to keep the two equal.
+
+## `TenantExportArchive`
+
+```typescript
+import type { Readable } from "node:stream";
+import type { JsonValue } from "@antelopejs/interface-dms/json";
+
+interface TenantExportArchive {
+  addJson(path: string, data: JsonValue): Promise<void>;
+  addFile(path: string, localPath: string): Promise<void>;
+  addStream(path: string, stream: Readable): Promise<void>;
+}
+```
+
+| Method | Adds |
+| ------ | ---- |
+| `addJson` | `data`, a JSON value (`JsonValue` from `@antelopejs/interface-dms/json`), serialized as a JSON entry. |
+| `addFile` | An artifact already on disk, read from `localPath`. The call rejects when `localPath` does not exist. |
+| `addStream` | A remote or generated dump, without holding it in memory. |
+
+Paths are relative. The DMS prefixes every entry with `modules/<moduleId>/`, so two contributors can both write `invoices.ndjson` without a collision. It drops empty, `.` and `..` segments from the path, and rejects a path left with no segment.
+
+Each method resolves only once the archiver has consumed the entry. Awaiting each call passes the archiver's back-pressure to whatever produces the data, and keeps memory flat at any export size. A call that is not awaited loses both.
+
+The archive accepts writes only while the handler runs. A write after the handler has settled throws `Tenant export archive for '<moduleId>' is no longer writable`.
+
+## Abort signal
+
+The `signal` aborts when an export job runs longer than its `maxExecutionTimeMs`, or when the caller of `buildTenantExportArchive` aborts the signal it passed. Pass it down to whatever produces your data, so an aborted export stops reading. An abort fails the whole export. The DMS does not write a partial archive for it.
+
+## Manifest
+
+Every run writes a `manifest.json` at the archive root. It records what each contributor produced:
+
+```typescript
+interface TenantExportManifest {
+  tenantId: string;
+  exportedAt: string;
+  partial: boolean;
+  modules: TenantExportModuleReport[];
+}
+
+interface TenantExportModuleReport {
+  moduleId: string;
+  declaredModuleId?: string;
+  entries: string[];
+  failed: boolean;
+  error?: string;
+}
+```
+
+Contributors run one after another, in registration order. A contributor that throws does not fail the export, unless the export was aborted or the ZIP stream broke. Its report carries `failed: true` and the error message, keeps the entries it wrote before it failed, and `partial` is `true` on the manifest. A consumer reads `partial` to tell an incomplete archive from a complete one.
+
+`declaredModuleId` is present when the returned contribution named another id than the one the archive namespaced the entries under. It is a sign that the registration and the return value disagree.
+
+`buildTenantExportArchive` runs the contributors and writes the ZIP, and `startTenantExportJob` runs it as a background export job. Both are covered in [Export a tenant's data](/docs/interfaces/base/helpers#export-a-tenants-data).