@antelopejs/interface-dms 0.13.3 → 0.14.1

package/docs/3.base/15.table-sources-and-gates.md

@@ -1,10 +1,10 @@
 ---
 title: "Table sources and tenant gates"
-description: Table views over a module's own route, and table views that stay readable behind a tenant access gate.
+description: Table views over a module's own route, table views that stay readable behind a tenant access gate, and table views over an external connection.
 mode: reference
 ---
 
-A [table view](/docs/interfaces/base/tables) usually reads a data controller. These two cases differ: a table view over a module's own route, and a table view that stays readable while a tenant access gate denies the tenant.
+A [table view](/docs/interfaces/base/tables) usually reads a data controller. These three cases differ: a table view over a module's own route, a table view that stays readable while a tenant access gate denies the tenant, and a table view over a table of an external connection.
 
 ## Tables over a module's route
 
@@ -22,3 +22,15 @@ Data routes are registered against the controller, not against a page, so the op
 
 - Declaring the flag on a controller opens its routes for every table view built on it, including one mounted on an ordinary page.
 - Actions that carry no permission id, such as a plain list on a component that was never mounted, are then served to any member of a denied tenant. That is the escape hatch working as intended, so keep every action of a flagged controller stamped with a permission.
+
+## Write to an external connection
+
+`@ExternalConnection(connection)`, from `@antelopejs/interface-dms/connection-access`, marks a data controller whose table belongs to an external connection, as the builder does on each table it maps. Its `TableViewRoutes` write routes (`new`, `edit`, `delete`, `archive`, `restore`) then call `AssertConnectionWritable` first, which answers 403 unless `GetConnectionAccess(connection)` is `"read-write"`. Reads are not affected.
+
+```typescript fragment
+@RegisterDataController()
+@ExternalConnection("erp")
+export class CountryDataAPI extends DataController(Country, TableViewRoutes.All, Controller("/erp/countries")) {}
+```
+
+The module that owns the connections answers their access with `RegisterConnectionAccessSource(id, source)` during `construct()`, as `dms-database` does from `config.externalConnections`. `source(connection)` returns `"read"`, `"read-write"`, or `undefined` for a connection it does not own. A connection is `"read-write"` only when a source answers `"read-write"` and none answers `"read"`, so a connection no source answers stays read-only. A route a module writes itself on a marked controller calls `AssertConnectionWritable(controller)` before it writes.

package/docs/3.base/3.forms.md

@@ -301,7 +301,7 @@ The option interfaces live in the same namespace. The ones with more than a plac
 | `DatePickerRangeOptions` | `minDate?`, `maxDate?` |
 | `RelationOptions` | `searchUrl: string`, `placeholder?`, `multiple?`, `deselectable?`, `keyMapping?: { label?, value?, avatar?, disabled? }`, `addForm?: ComponentInfoSerialized<FormPropsSerialized>`, `addPermissionIds?: string[]`, `addFormTexts?: { displayName?, description? }` |
 | `CascaderRelationKeyMapping` | `label: string`, `value: string`, `parent: string`, `disabled?` |
-| `CascaderRelationOptions` | `searchUrl: string`, `keyMapping: CascaderRelationKeyMapping`, `placeholder?`, `multiple?`, `deselectable?`, `maxDepth?`, `leafOnly?`, `fallback?` |
+| `CascaderRelationOptions` | `searchUrl: string`, `keyMapping: CascaderRelationKeyMapping`, `placeholder?`, `multiple?`, `deselectable?`, `maxDepth?`, `leafOnly?` |
 | `AddressOptions` | `placeholder?` (per address component), `autocomplete?: DefaultDataTypes.AddressAutocomplete` |
 | `FileOptions` | `multiple?`, `constraints?: { maxSize?, allowedMimetypes? }`, `path?`, `storage?` |
 | `ImageOptions` | `FileOptions` plus `max?` and `resize?: ImageResizeOptions` |

package/docs/3.base/4.tables.md

@@ -178,7 +178,7 @@ export class customerDataAPI extends DataController(/* … */) {
 
 ### The archive field
 
-`@ArchiveField` marks the boolean field that carries the archived state. It records the field on the table view metadata and also applies `Filter()` and `Listable()` to it, because archive filtering needs both.
+`@ArchiveField` marks the boolean field that carries the archived state. It makes the field `Listable()` and registers a filter that reads `true` or `false` with `eq` or `ne`. `TableView` throws when another `Filter` replaces it.
 
 ```typescript fragment
 import { ArchiveField } from "@antelopejs/interface-dms/base/table-view";

package/docs/3.base/5.charts-and-widgets.md

@@ -310,7 +310,7 @@ const card = ChartCard({
 | `periodScope` | `string` | Id of the `PeriodSelector` to follow. |
 | `valueFormat` | `ValueFormat` | How the headline value is formatted. |
 | `currencyCode` | `string` | Currency for `valueFormat: "currency"`. |
-| `valuePrecision` | `ValuePrecision` | Fixed fraction digits or `"native"` Intl defaults; omitted keeps legacy formatting. Also applies to the previous value and nested chart's value axis and tooltip. |
+| `valuePrecision` | `ValuePrecision` | Fixed fraction digits or `"native"` Intl defaults; omitted uses the format's default: whole currency amounts, at most one fraction digit for percent and compact. Also applies to the previous value and nested chart's value axis and tooltip. |
 | `showDelta` | `boolean` | Show the change against the comparison period. |
 | `invert` | `boolean` | Treat an increase as bad, for metrics where lower is better. |
 | `showLegend` | `boolean` | Show the primary / comparison legend. Defaults to `true`. |
@@ -349,7 +349,7 @@ const denied = KpiCard({
 | `realtimeTopic` | `string \| string[]` | Topics whose events make the card read `fetchUrl` again, through the page's `live` gate. The builder registers them on the page. |
 | `valueFormat` | `ValueFormat` | How the value is formatted. |
 | `currencyCode` | `string` | Currency for `valueFormat: "currency"`. |
-| `valuePrecision` | `ValuePrecision` | Fixed fraction digits or `"native"` Intl defaults; omitted keeps legacy formatting. |
+| `valuePrecision` | `ValuePrecision` | Fixed fraction digits or `"native"` Intl defaults; omitted uses the format's default: whole currency amounts, at most one fraction digit for percent and compact. |
 | `showDelta` | `boolean` | Show the change against the comparison period. |
 | `showPreviousValue` | `boolean` | Show the route's `previousValue` next to the change ("vs €42,900"), formatted as the value. Defaults to `true`. |
 | `showSparkline` | `boolean` | Show the sparkline. |
@@ -389,7 +389,7 @@ const topSkills = TopListCard({
 | `periodScope` | `string` | Id of the `PeriodSelector` to follow. |
 | `valueFormat` | `ValueFormat` | How each item's value is formatted. |
 | `currencyCode` | `string` | Currency for `valueFormat: "currency"`. |
-| `valuePrecision` | `ValuePrecision` | Fixed fraction digits or `"native"` Intl defaults; omitted keeps legacy formatting. |
+| `valuePrecision` | `ValuePrecision` | Fixed fraction digits or `"native"` Intl defaults; omitted uses the format's default: whole currency amounts, at most one fraction digit for percent and compact. |
 | `valueSuffix` | `string` | Unit written right after each formatted value, space included (`" ms"`); a `$`-prefixed key is translated. Not added to a `valueLabel`. |
 | `showRank` | `boolean` | Show the rank number. |
 | `highlightTopN` | `number` | How many leading items are highlighted. |

package/docs/3.base/8.data-types.md

@@ -361,7 +361,7 @@ The type's options are `placeholder` (one string per address component), `autoco
 
 `FileTypeOptions` has `multiple?`, `constraints?: UploadConstraints`, `path?`, `storage?` and `fallback?`. `ImageTypeOptions` has `multiple?`, `max?`, `constraints?`, `path?`, `storage?` and `resize?`, the `FormComponents.ImageResizeOptions` the input applies client-side before uploading ([Forms](/docs/interfaces/base/forms)). Both accept `attachmentField?` for a stable native field identity and `visibility?: "private" | "public"`, defaulting to private. `constraints` is the `UploadConstraints` type from `@antelopejs/interface-file-storage`; `storage` names the storage backend and `path` the prefix uploads land under.
 
-A file value is the resource key as a string. Metadata-based validation checks configured constraints, matching `allowedMimetypes` patterns including the `type/*` form. A native field's save integration also validates upload provenance and canonical metadata before persistence. Existing unclassified legacy values may be retained, but cannot be introduced as new native attachments or read through the native metadata endpoint. A storage outage propagates as a server error rather than becoming a field validation error. An image value is an `ImageValue`, `{ key: string; alt?: string; principal?: boolean }`, and `ImageType` defaults `allowedMimetypes` to `["image/*"]`, caps the array at `max` when `multiple` is set, and rejects a list with more than one `principal` image.
+A file value is the resource key as a string. Metadata-based validation checks configured constraints, matching `allowedMimetypes` patterns including the `type/*` form. A native field's save integration also validates upload provenance and canonical metadata before persistence. A key with no recorded upload is refused with HTTP 403, both in the submitted document and in the previously stored one, and the native metadata endpoint does not read it. A storage outage propagates as a server error rather than becoming a field validation error. An image value is an `ImageValue`, `{ key: string; alt?: string; principal?: boolean }`, and `ImageType` defaults `allowedMimetypes` to `["image/*"]`, caps the array at `max` when `multiple` is set, and rejects a list with more than one `principal` image.
 
 Both types enable the table view's native file handling: authorized saves promote staging keys, and successful edits or deletes clean removed native references. Failed saves retain promoted objects; cleanup is not reference-counted across records. See [File storage](/docs/components/file-storage) for authorization, visibility, retries, and custom save routes, and [Helpers](/docs/interfaces/base/helpers) for comparing references within records.
 

package/docs/3.base/9.helpers.md

@@ -145,7 +145,7 @@ function runExportJob<TContext = unknown>(
 | `ctx` | `RequestContext` | The request. The job is stored in the schema of the tenant the request resolves to. Required. |
 | `user` | `User` | The owner of the job. Required; a missing user fails with `401`. |
 | `scope` | `string` | Free-form identifier for the origin of the job, checked again on status and download when you pass it there. Required. |
-| `context` | `TContext` | Scope-specific payload stored with the job and handed back to `generate` and to `isOwnedBy`. |
+| `context` | `TContext` | Scope-specific payload stored with the job as JSON. `generate` receives it as passed; `isOwnedBy` receives it read back through `contextSchema`. |
 | `filename` | `string` | Base name of the produced file, without extension or timestamp. Required. |
 | `extension` | `string` | File extension. Required. |
 | `contentType` | `string` | MIME type used when uploading and when streaming the file back. Required. |
@@ -188,7 +188,7 @@ By default a job is deleted once it has been downloaded. Set `retainUntilExpiry`
 | `jobId` | `string` | Identifier of this job. |
 | `tenantId` | `string` | Tenant the job belongs to. |
 | `localPath` | `string` | Path your generator writes the file to. |
-| `context` | `TContext` | The payload passed as `context` to `runExportJob`. |
+| `context` | `TContext \| undefined` | The payload passed as `context` to `runExportJob`, `undefined` when it passed none. |
 | `reportProgress` | `(progress: number) => Promise<void>` | Records progress. The value is floored and clamped to `0` through `99`; repeating the last value writes nothing. Throws once the job is aborted. |
 | `signal` | `AbortSignal` | Aborted when the job exceeds `maxExecutionTimeMs`. |
 
@@ -216,7 +216,7 @@ function downloadExportJob<TContext = unknown>(
 
 `downloadExportJob` requires a completed job with a stored result. Anything else fails with `400` or `500`. It sets `Content-Disposition` (with a filename built by `buildExportFilename`), `Content-Length` when the size is known, and `Access-Control-Expose-Headers`, then pipes the stored object to the response. The function returns as soon as the pipe is set up rather than awaiting it; once the response stream closes, the stored object and the job record are both deleted.
 
-`loadExportJobForUser(ctx, user, jobId, access?)` is the shared step underneath both: it resolves the tenant, loads the record, runs the access checks, and returns the model, the record and the parsed context. Use it when you need the record itself rather than its status.
+`loadExportJobForUser(ctx, user, jobId, access?)` is the shared step underneath both: it resolves the tenant, loads the record, runs the access checks, and returns the model and the record. Use it when you need the record itself rather than its status.
 
 `downloadExportJob` deletes the stored object and the job record once the response stream closes, unless the job was started with `retainUntilExpiry`, in which case both survive until the sweep.
 
@@ -239,9 +239,20 @@ Returns the caller's own jobs, most recent first: the history a scope such as a
 | Option | Type | Description |
 | --- | --- | --- |
 | `scope` | `string` | When set, the job's stored `scope` must match. |
-| `isOwnedBy` | `(record, context, user) => boolean` | Extra ACL evaluated after the ownership and scope checks. |
+| `contextSchema` | `ZodType<TContext, ZodTypeDef, unknown>` | Reads back the `context` the job was started with, from the JSON it was stored as: `null` for a job started without one, a `Date` as its ISO string. A stored context it refuses refuses the job. Required with `isOwnedBy`. |
+| `isOwnedBy` | `(record, context, user) => boolean` | Extra ACL evaluated after the ownership and scope checks, on the context `contextSchema` read. Required with `contextSchema`. |
 
-`ExportJobOwnership<TContext>` carries only `isOwnedBy`; `ExportJobAccessOptions<TContext>` extends it with `scope`. The job's `userId` is always compared against the caller regardless of what you pass, and every failed check answers `403`.
+`ExportJobContextCheck<TContext>` is the pair `contextSchema` and `isOwnedBy`. `ExportJobOwnership<TContext>` is that pair or neither of its members, and `ExportJobAccessOptions<TContext>` adds `scope` to it. The job's `userId` is always compared against the caller regardless of what you pass, and every failed check answers `403`.
+
+```typescript fragment
+import { z } from "zod";
+
+const status = await getExportJobStatus(ctx, user, jobId, {
+  scope: SCOPE,
+  contextSchema: z.object({ year: z.number() }),
+  isOwnedBy: (_record, context) => context.year === new Date().getFullYear(),
+});
+```
 
 ### Formats and delivery
 

package/docs/4.notifications/3.sending.md

@@ -202,17 +202,6 @@ A shared-read send derives a stable group ID from the event key. The DMS checks
 
 Realtime publishing is best-effort and happens only after a newly inserted delivery. A crash or a lost acknowledgement can leave a stored notification without a realtime event, and a retry does not replay it. The delivery rules still apply, and a skipped recipient gets no receipt.
 
-Before it sends, every keyed dispatch asks the DMS implementation, through `SupportsIdempotency`, whether it supports keyed delivery. If the implementation does not answer `true`, the dispatch throws `DMS idempotent notification delivery is unavailable` and sends nothing, rather than delivering without deduplication.
-
-If your module can load against a DMS implementation that has no `toUsersIdempotently` method, check for the method and fail closed. Keep the pending outbox work until the DMS packages provide it:
-
-```typescript fragment
-if (!("toUsersIdempotently" in shipped) || typeof shipped.toUsersIdempotently !== "function") {
-  throw new Error("DMS idempotent notification delivery is unavailable");
-}
-await shipped.toUsersIdempotently([ownerId, managerId], event.id);
-```
-
 ## Delivery rules
 
 Every dispatch method resolves to one delivery per user, so the DMS applies the same rules to each of them:

package/docs/index.md

@@ -87,7 +87,7 @@ Each subpath is its own entry point, and importing one does not load the others.
 
 Beyond these entry points, built files are importable through the `./*` export (`@antelopejs/interface-dms/base/form-types`). Moving or renaming a public path is a breaking change, like removing an export.
 
-Importability does not make a declaration public. Paths under `internal/`, symbols tagged `@internal`, and `internal` namespaces are wiring between the interface and its implementation, not supported consumer APIs. This includes compatibility exports retained at old paths. Public types named by a supported signature remain part of its contract. Use the documented entry points rather than calling internal proxies or raw writer helpers.
+Importability does not make a declaration public. Paths under `internal/`, symbols tagged `@internal`, and `internal` namespaces are wiring between the interface and its implementation, not supported consumer APIs. This includes internal symbols kept at a path a module already imports. Public types named by a supported signature remain part of its contract. Use the documented entry points rather than calling internal proxies or raw writer helpers.
 
 ## How a domain folder is laid out
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antelopejs/interface-dms",
-  "version": "0.13.3",
+  "version": "0.14.1",
   "description": "Public AntelopeJS interfaces of the DMS: pages, components, permissions, tenancy, auth, notifications and HTML rendering.",
   "keywords": [
     "antelopejs",
@@ -43,25 +43,25 @@
   },
   "dependencies": {
     "randomstring": "^1.3.1",
-    "zod": "~3.24.2",
+    "zod": "^3.24.2",
     "zod-to-json-schema": "~3.24.6"
   },
   "peerDependencies": {
     "@antelopejs/interface-api": ">=0.3.0 <1.0.0",
     "@antelopejs/interface-api-util": ">=0.1.3 <1.0.0",
-    "@antelopejs/interface-core": ">=0.4.0 <1.0.0",
-    "@antelopejs/interface-data-api": ">=0.6.0 <1.0.0",
-    "@antelopejs/interface-database": ">=0.1.11 <1.0.0",
-    "@antelopejs/interface-database-decorators": ">=0.3.0 <1.0.0",
+    "@antelopejs/interface-core": ">=0.5.1 <1.0.0",
+    "@antelopejs/interface-data-api": ">=0.8.0 <0.9.0",
+    "@antelopejs/interface-database": ">=0.4.0 <0.5.0",
+    "@antelopejs/interface-database-decorators": ">=0.5.2 <0.6.0",
     "@antelopejs/interface-file-storage": ">=0.1.4 <1.0.0"
   },
   "devDependencies": {
-    "@antelopejs/interface-api": ">=0.2.0 <1.0.0",
+    "@antelopejs/interface-api": ">=0.3.0 <1.0.0",
     "@antelopejs/interface-api-util": ">=0.3.0 <1.0.0",
-    "@antelopejs/interface-core": ">=0.4.0 <1.0.0",
-    "@antelopejs/interface-data-api": ">=0.6.0 <1.0.0",
-    "@antelopejs/interface-database": ">=0.3.0 <1.0.0",
-    "@antelopejs/interface-database-decorators": ">=0.3.1 <1.0.0",
+    "@antelopejs/interface-core": ">=0.5.1 <1.0.0",
+    "@antelopejs/interface-data-api": ">=0.8.0 <0.9.0",
+    "@antelopejs/interface-database": ">=0.4.0 <0.5.0",
+    "@antelopejs/interface-database-decorators": ">=0.5.2 <0.6.0",
     "@antelopejs/interface-file-storage": ">=0.1.4 <1.0.0",
     "@types/node": "^24.0.0",
     "@types/randomstring": "^1.3.0",