@antelopejs/interface-dms 0.3.5 → 0.3.6

package/dist/invite-extensions/{payload-slices.js → internal/payload-slices.js}

@@ -7,11 +7,21 @@ exports.readPayload = readPayload;
 const interface_api_util_1 = require("@antelopejs/interface-api-util");
 const field_ids_1 = require("./field-ids");
 const registry_1 = require("./registry");
+/** @internal */
 exports.HTTP_BAD_REQUEST = 400;
 function issuesOf(error) {
     const issues = error.issues;
     return Array.isArray(issues) ? issues : undefined;
 }
+/**
+ * Report the failure against the ids the browser knows — the prefixed ones it
+ * submitted — so the invite form can point at the offending field rather than
+ * at a name only the extension uses.
+ *
+ * An issue raised on the object itself (a schema-wide `refine`) names no field:
+ * it keeps an empty path rather than being handed a fabricated one, which the
+ * form could not attach to anything either way.
+ */
 function describeFailure(key, error) {
     const issues = issuesOf(error);
     if (!issues)
@@ -25,6 +35,11 @@ function describeFailure(key, error) {
         })),
     };
 }
+/**
+ * The submitted values of one extension's fields, keyed by unprefixed id.
+ *
+ * @internal
+ */
 function sliceOf(key, body) {
     const slice = {};
     for (const [id, value] of Object.entries(body)) {
@@ -35,9 +50,24 @@ function sliceOf(key, body) {
     }
     return slice;
 }
+/**
+ * @throws HTTPResult 400 when the slice does not satisfy the schema
+ *
+ * @internal
+ */
 function assertSliceValid(info, slice) {
     (0, interface_api_util_1.assertValidation)(slice, (v) => info.schema.parse(v), (error) => describeFailure(info.key, error), exports.HTTP_BAD_REQUEST);
 }
+/**
+ * Parse the stored submission into the payload `onAccept` is typed for.
+ *
+ * The schema runs here rather than being trusted from storage: an invitation
+ * can outlive the version of the module that wrote its payload, and this is
+ * also where a transforming schema produces its output — exactly once, on the
+ * input as the admin submitted it.
+ *
+ * @internal
+ */
 function readPayload(info, payloads, options) {
     const stored = payloads?.[info.key];
     if (stored === undefined)

package/dist/invite-extensions/internal/payload-slices.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"payload-slices.js","sourceRoot":"","sources":["../../../src/invite-extensions/internal/payload-slices.ts"],"names":[],"mappings":";;;AAsDA,0BAYC;AAOD,4CAUC;AAYD,kCAmBC;AAlHD,uEAAkE;AAClE,2CAGqB;AACrB,yCAAuD;AAIvD,gBAAgB;AACH,QAAA,gBAAgB,GAAG,GAAG,CAAC;AAYpC,SAAS,QAAQ,CAAC,KAAc;IAC9B,MAAM,MAAM,GAAI,KAA8B,CAAC,MAAM,CAAC;IACtD,OAAO,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAE,MAAsB,CAAC,CAAC,CAAC,SAAS,CAAC;AACrE,CAAC;AAED;;;;;;;;GAQG;AACH,SAAS,eAAe,CAAC,GAAW,EAAE,KAAc;IAClD,MAAM,MAAM,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;IAC/B,IAAI,CAAC,MAAM;QAAE,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;IAClC,OAAO;QACL,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC,CAAC;YACzC,IAAI,EAAE,IAAI,CAAC,MAAM;gBACf,CAAC,CAAC,CAAC,IAAA,kCAAsB,EAAC,GAAG,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;gBAClE,CAAC,CAAC,EAAE;YACN,OAAO;SACR,CAAC,CAAC;KACJ,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,SAAgB,OAAO,CACrB,GAAW,EACX,IAA6B;IAE7B,MAAM,KAAK,GAA4B,EAAE,CAAC;IAC1C,KAAK,MAAM,CAAC,EAAE,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QAC/C,MAAM,KAAK,GAAG,IAAA,uCAA2B,EAAC,EAAE,CAAC,CAAC;QAC9C,IAAI,KAAK,EAAE,GAAG,KAAK,GAAG,EAAE,CAAC;YACvB,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,KAAK,CAAC;QAC/B,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;GAIG;AACH,SAAgB,gBAAgB,CAC9B,IAAyB,EACzB,KAA8B;IAE9B,IAAA,qCAAgB,EACd,KAAK,EACL,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,EAC3B,CAAC,KAAK,EAAE,EAAE,CAAC,eAAe,CAAC,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,EAC3C,wBAAgB,CACjB,CAAC;AACJ,CAAC;AAED;;;;;;;;;GASG;AACH,SAAgB,WAAW,CACzB,IAAyB,EACzB,QAAoD,EACpD,OAA8B;IAE9B,MAAM,MAAM,GAAG,QAAQ,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACpC,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAE3C,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;IAC7C,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACpB,IAAA,oCAAyB,EACvB,IAAI,CAAC,GAAG,EACR,yBAAyB,EACzB,MAAM,CAAC,KAAK,CACb,CAAC;QACF,IAAI,OAAO,CAAC,cAAc;YAAE,MAAM,MAAM,CAAC,KAAK,CAAC;QAC/C,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,MAAM,CAAC,IAAI,EAAE,CAAC;AAChC,CAAC"}

package/dist/invite-extensions/internal/registry.d.ts

@@ -0,0 +1,48 @@
+import type { InviteExtensionInfo, InviteFieldContribution } from "./types";
+/**
+ * A registration plus the contribution it serializes to. The contribution is
+ * built once, lazily, and cached on the entry: serializing runs the form's
+ * option transforms — which is where its upload fields claim their tokens —
+ * and those must not be re-signed on every layout request.
+ *
+ * @internal
+ */
+export interface InviteExtensionEntry {
+    info: InviteExtensionInfo;
+    contribution?: Promise<InviteFieldContribution | undefined>;
+}
+/** @internal */
+export declare const inviteExtensions: Map<string, InviteExtensionEntry>;
+/** @internal */
+export declare function listInviteExtensionEntries(): InviteExtensionEntry[];
+/** @internal */
+export declare function listInviteExtensions(): InviteExtensionInfo[];
+/** @internal */
+export declare function getInviteExtension(key: string): InviteExtensionInfo | undefined;
+/** @internal */
+export declare function logInviteExtensionFailure(key: string, action: string, error: unknown): void;
+/**
+ * The last registration wins, rather than a key collision being fatal: a hot
+ * reload registers the replacement before the old one unregisters, so the
+ * common case of a key already being held is a module reclaiming its own.
+ * Throwing there would fail the reloaded module's construction and — once
+ * the departing one unregisters — leave the invite modal without the fields
+ * until a full restart.
+ *
+ * The holder is told apart by the module that registered it, not by the
+ * object: a reload re-registers a new one, and a DMS reload is replayed a
+ * fresh view of the same one. Two different modules on one key would
+ * overwrite each other's payload on the invitation, which is a declaration
+ * error; it is reported rather than raised, for the reason above.
+ *
+ * @internal
+ */
+export declare function applyInviteExtension(info: InviteExtensionInfo): void;
+/** @internal */
+export declare function revokeInviteExtension(info: InviteExtensionInfo): void;
+/**
+ * Test seam: drops every registration without going through the proxy.
+ *
+ * @internal
+ */
+export declare function clearInviteExtensions(): void;

package/dist/invite-extensions/internal/registry.js

@@ -0,0 +1,77 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.inviteExtensions = void 0;
+exports.listInviteExtensionEntries = listInviteExtensionEntries;
+exports.listInviteExtensions = listInviteExtensions;
+exports.getInviteExtension = getInviteExtension;
+exports.logInviteExtensionFailure = logInviteExtensionFailure;
+exports.applyInviteExtension = applyInviteExtension;
+exports.revokeInviteExtension = revokeInviteExtension;
+exports.clearInviteExtensions = clearInviteExtensions;
+const logging_1 = require("@antelopejs/interface-core/logging");
+/** @internal */
+exports.inviteExtensions = new Map();
+/** @internal */
+function listInviteExtensionEntries() {
+    return [...exports.inviteExtensions.values()];
+}
+/** @internal */
+function listInviteExtensions() {
+    return listInviteExtensionEntries().map((entry) => entry.info);
+}
+/** @internal */
+function getInviteExtension(key) {
+    return exports.inviteExtensions.get(key)?.info;
+}
+/** @internal */
+function logInviteExtensionFailure(key, action, error) {
+    logging_1.Logging.Error(`[dms] invite extension "${key}" failed to ${action}:`, error);
+}
+// An unresolved module matches nothing: two registrations whose owner is
+// unknown are not known to be the same module, so they still warn.
+function isSameRegisteringModule(held, incoming) {
+    if (held === incoming)
+        return true;
+    return held.moduleId !== undefined && held.moduleId === incoming.moduleId;
+}
+/**
+ * The last registration wins, rather than a key collision being fatal: a hot
+ * reload registers the replacement before the old one unregisters, so the
+ * common case of a key already being held is a module reclaiming its own.
+ * Throwing there would fail the reloaded module's construction and — once
+ * the departing one unregisters — leave the invite modal without the fields
+ * until a full restart.
+ *
+ * The holder is told apart by the module that registered it, not by the
+ * object: a reload re-registers a new one, and a DMS reload is replayed a
+ * fresh view of the same one. Two different modules on one key would
+ * overwrite each other's payload on the invitation, which is a declaration
+ * error; it is reported rather than raised, for the reason above.
+ *
+ * @internal
+ */
+function applyInviteExtension(info) {
+    const existing = exports.inviteExtensions.get(info.key);
+    if (existing && !isSameRegisteringModule(existing.info, info)) {
+        logging_1.Logging.Warn(`[dms] invite extension key "${info.key}" was already registered by another module; the latest registration now owns it. If two modules claim this key, one of them silently loses its payload — give them distinct keys.`);
+    }
+    exports.inviteExtensions.set(info.key, { info });
+}
+/** @internal */
+function revokeInviteExtension(info) {
+    const existing = exports.inviteExtensions.get(info.key);
+    // A hot reload registers the replacement before the old one unregisters,
+    // so an unconditional delete would drop the live registration.
+    if (!existing || existing.info !== info)
+        return;
+    exports.inviteExtensions.delete(info.key);
+}
+/**
+ * Test seam: drops every registration without going through the proxy.
+ *
+ * @internal
+ */
+function clearInviteExtensions() {
+    exports.inviteExtensions.clear();
+}
+//# sourceMappingURL=registry.js.map

package/dist/invite-extensions/internal/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../../src/invite-extensions/internal/registry.ts"],"names":[],"mappings":";;;AAoBA,gEAEC;AAGD,oDAEC;AAGD,gDAIC;AAGD,8DAMC;AA4BD,oDAQC;AAGD,sDAMC;AAOD,sDAEC;AAjGD,gEAA6D;AAgB7D,gBAAgB;AACH,QAAA,gBAAgB,GAAG,IAAI,GAAG,EAAgC,CAAC;AAExE,gBAAgB;AAChB,SAAgB,0BAA0B;IACxC,OAAO,CAAC,GAAG,wBAAgB,CAAC,MAAM,EAAE,CAAC,CAAC;AACxC,CAAC;AAED,gBAAgB;AAChB,SAAgB,oBAAoB;IAClC,OAAO,0BAA0B,EAAE,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;AACjE,CAAC;AAED,gBAAgB;AAChB,SAAgB,kBAAkB,CAChC,GAAW;IAEX,OAAO,wBAAgB,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,IAAI,CAAC;AACzC,CAAC;AAED,gBAAgB;AAChB,SAAgB,yBAAyB,CACvC,GAAW,EACX,MAAc,EACd,KAAc;IAEd,iBAAO,CAAC,KAAK,CAAC,2BAA2B,GAAG,eAAe,MAAM,GAAG,EAAE,KAAK,CAAC,CAAC;AAC/E,CAAC;AAED,yEAAyE;AACzE,mEAAmE;AACnE,SAAS,uBAAuB,CAC9B,IAAyB,EACzB,QAA6B;IAE7B,IAAI,IAAI,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IACnC,OAAO,IAAI,CAAC,QAAQ,KAAK,SAAS,IAAI,IAAI,CAAC,QAAQ,KAAK,QAAQ,CAAC,QAAQ,CAAC;AAC5E,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,SAAgB,oBAAoB,CAAC,IAAyB;IAC5D,MAAM,QAAQ,GAAG,wBAAgB,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAChD,IAAI,QAAQ,IAAI,CAAC,uBAAuB,CAAC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,CAAC;QAC9D,iBAAO,CAAC,IAAI,CACV,+BAA+B,IAAI,CAAC,GAAG,mLAAmL,CAC3N,CAAC;IACJ,CAAC;IACD,wBAAgB,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC;AAC3C,CAAC;AAED,gBAAgB;AAChB,SAAgB,qBAAqB,CAAC,IAAyB;IAC7D,MAAM,QAAQ,GAAG,wBAAgB,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAChD,yEAAyE;IACzE,+DAA+D;IAC/D,IAAI,CAAC,QAAQ,IAAI,QAAQ,CAAC,IAAI,KAAK,IAAI;QAAE,OAAO;IAChD,wBAAgB,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACpC,CAAC;AAED;;;;GAIG;AACH,SAAgB,qBAAqB;IACnC,wBAAgB,CAAC,KAAK,EAAE,CAAC;AAC3B,CAAC"}

package/dist/invite-extensions/internal/types.d.ts

@@ -0,0 +1,61 @@
+import type { FieldGroupSerialized, FormBuilder } from "../../base/form";
+import type { WatchAction } from "../../base/types/watch";
+import type { ZodType, ZodTypeDef } from "zod";
+import type { PlacementSide } from "../../component";
+import type { InviteAcceptHandler, InviteCleanupHandler, InviteUpdateHandler } from "../types";
+/**
+ * Resolved placement of a registered extension.
+ *
+ * @internal
+ */
+export interface ResolvedInvitePlacement {
+    side: PlacementSide;
+    anchorField?: string;
+    order: number;
+}
+/** @internal */
+export interface InviteDeliveryOptions {
+    /** Retains durable work by propagating contributor failures after all callbacks run. */
+    retryOnFailure?: boolean;
+}
+/**
+ * A registration as the registry holds it: placement resolved, payload type
+ * erased. The object itself is the handle — it is what the registering proxy
+ * hands back to unregister when the extending module stops.
+ *
+ * @internal
+ */
+export interface InviteExtensionInfo {
+    key: string;
+    component: FormBuilder;
+    schema: ZodType<unknown, ZodTypeDef, unknown>;
+    onAccept: InviteAcceptHandler<unknown>;
+    onCleanup?: InviteCleanupHandler<unknown>;
+    /** Unset reads as `true`, as it does on the options. */
+    editable?: boolean;
+    onUpdate?: InviteUpdateHandler<unknown>;
+    label?: string;
+    description?: string;
+    placement: ResolvedInvitePlacement;
+    /** The module that registered the extension, undefined when unresolved. */
+    moduleId?: string;
+}
+/**
+ * One extension's contribution to the invite form, serialized once when it
+ * registers: the block of fields, the JSON-schema entries the browser
+ * validates them against, and the watches the contributed form declared —
+ * all keyed by the prefixed field ids the merged form uses.
+ *
+ * @internal
+ */
+export interface InviteFieldContribution {
+    key: string;
+    side: PlacementSide;
+    anchorField?: string;
+    order: number;
+    editable: boolean;
+    group: FieldGroupSerialized;
+    properties: Record<string, unknown>;
+    requiredProperties: string[];
+    watchActions: WatchAction[];
+}

package/dist/invite-extensions/internal/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/invite-extensions/internal/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/invite-extensions/internal/types.ts"],"names":[],"mappings":""}

package/dist/invite-extensions/registry.d.ts

@@ -1,17 +1,49 @@
 import { RegisteringProxy } from "@antelopejs/interface-core";
-import type { InviteExtensionInfo, InviteExtensionOptions, InviteFieldContribution } from "./types";
-export interface InviteExtensionEntry {
-    info: InviteExtensionInfo;
-    contribution?: Promise<InviteFieldContribution | undefined>;
-}
-export declare function listInviteExtensionEntries(): InviteExtensionEntry[];
-export declare function listInviteExtensions(): InviteExtensionInfo[];
-export declare function getInviteExtension(key: string): InviteExtensionInfo | undefined;
+import type { InviteExtensionInfo } from "./internal/types";
+import type { InviteExtensionOptions } from "./types";
+/**
+ * Attach module data to member invitations: the fields of `component` are
+ * merged into the DMS invite modal, the values the admin fills are validated
+ * against `schema` and stored on the invitation, and `onAccept` receives them
+ * once the invitee is a member of the tenant.
+ *
+ * Placement follows `@RegisterPageExtension`: `anchorField` names a field of
+ * the invite form to sit before or after, `order` breaks ties between
+ * extensions landing at the same spot, and equal orders fall back to the
+ * extension key — so the modal assembles the same way on every host and
+ * across restarts, never depending on module start order.
+ *
+ * Field ids are namespaced by `key`, so two extensions may both contribute a
+ * `plan` field; `schema` and `onAccept` see them unprefixed.
+ *
+ * An invitee who already has an account is added to the tenant on the spot and
+ * no invitation row is written: `onAccept` still runs, with `inviteId` unset.
+ * `onCleanup` runs when the invitation is cancelled or replaced and when a
+ * member is removed — never on acceptance, which also deletes the invitation.
+ *
+ * The fields also appear in the edit form of a pending invitation, prefilled
+ * with the stored payload: an admin can change it until the invitee accepts,
+ * unless `editable` is `false`, and `onUpdate` hears about each change.
+ *
+ * The registration is bound to the registering module and lifted when it
+ * stops, so the fields leave the modal with it.
+ *
+ * ```ts
+ * RegisterInviteExtension({
+ *   key: "billing",
+ *   component: Form({ fields: [{ id: "costCenter", type: new StringType() }] }),
+ *   schema: z.object({ costCenter: z.string().min(1) }),
+ *   onAccept: (payload, member) => assignCostCenter(member, payload.costCenter),
+ * });
+ * ```
+ *
+ * @returns Removes this extension, for a module that drops it while staying
+ * loaded.
+ */
 export declare function RegisterInviteExtension<T>(options: InviteExtensionOptions<T>): () => void;
+/**
+ * @internal
+ */
 export declare namespace internal {
     const RegisterInviteExtension: RegisteringProxy<(info: InviteExtensionInfo) => void>;
-    function applyInviteExtension(info: InviteExtensionInfo): void;
-    function revokeInviteExtension(info: InviteExtensionInfo): void;
-    function clearInviteExtensions(): void;
 }
-export declare function logInviteExtensionFailure(key: string, action: string, error: unknown): void;

package/dist/invite-extensions/registry.js

@@ -1,28 +1,15 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.internal = void 0;
-exports.listInviteExtensionEntries = listInviteExtensionEntries;
-exports.listInviteExtensions = listInviteExtensions;
-exports.getInviteExtension = getInviteExtension;
 exports.RegisterInviteExtension = RegisterInviteExtension;
-exports.logInviteExtensionFailure = logInviteExtensionFailure;
 const interface_core_1 = require("@antelopejs/interface-core");
-const logging_1 = require("@antelopejs/interface-core/logging");
-const field_ids_1 = require("./field-ids");
-const inviteExtensions = new Map();
-function listInviteExtensionEntries() {
-    return [...inviteExtensions.values()];
-}
-function listInviteExtensions() {
-    return listInviteExtensionEntries().map((entry) => entry.info);
-}
-function getInviteExtension(key) {
-    return inviteExtensions.get(key)?.info;
-}
+const field_ids_1 = require("./internal/field-ids");
 const DEFAULT_PLACEMENT = { side: "end", order: 0 };
 function resolvePlacement(options) {
     if (!options)
         return DEFAULT_PLACEMENT;
+    // `anchorField` is set only when the placement names one: its absence is
+    // what the assembler reads as "append at the end".
     const placement = {
         side: options.side ?? DEFAULT_PLACEMENT.side,
         order: options.order ?? DEFAULT_PLACEMENT.order,
@@ -39,11 +26,54 @@ function assertUsableKey(key) {
         throw new Error(`Invite extension key "${key}" may not contain "${field_ids_1.INVITE_EXTENSION_FIELD_SEPARATOR}": it separates the key from the field id in the merged invite form.`);
     }
 }
+/**
+ * Attach module data to member invitations: the fields of `component` are
+ * merged into the DMS invite modal, the values the admin fills are validated
+ * against `schema` and stored on the invitation, and `onAccept` receives them
+ * once the invitee is a member of the tenant.
+ *
+ * Placement follows `@RegisterPageExtension`: `anchorField` names a field of
+ * the invite form to sit before or after, `order` breaks ties between
+ * extensions landing at the same spot, and equal orders fall back to the
+ * extension key — so the modal assembles the same way on every host and
+ * across restarts, never depending on module start order.
+ *
+ * Field ids are namespaced by `key`, so two extensions may both contribute a
+ * `plan` field; `schema` and `onAccept` see them unprefixed.
+ *
+ * An invitee who already has an account is added to the tenant on the spot and
+ * no invitation row is written: `onAccept` still runs, with `inviteId` unset.
+ * `onCleanup` runs when the invitation is cancelled or replaced and when a
+ * member is removed — never on acceptance, which also deletes the invitation.
+ *
+ * The fields also appear in the edit form of a pending invitation, prefilled
+ * with the stored payload: an admin can change it until the invitee accepts,
+ * unless `editable` is `false`, and `onUpdate` hears about each change.
+ *
+ * The registration is bound to the registering module and lifted when it
+ * stops, so the fields leave the modal with it.
+ *
+ * ```ts
+ * RegisterInviteExtension({
+ *   key: "billing",
+ *   component: Form({ fields: [{ id: "costCenter", type: new StringType() }] }),
+ *   schema: z.object({ costCenter: z.string().min(1) }),
+ *   onAccept: (payload, member) => assignCostCenter(member, payload.costCenter),
+ * });
+ * ```
+ *
+ * @returns Removes this extension, for a module that drops it while staying
+ * loaded.
+ */
 function RegisterInviteExtension(options) {
     assertUsableKey(options.key);
     const info = {
         key: options.key,
         component: options.component,
+        // The source and the target do not overlap, so this cannot be one
+        // assertion: the value reaches here through a decorator, a JWT
+        // payload or a filter tuple, none of which the type system sees.
+        // oxlint-disable-next-line anti-slop/no-chained-type-assertions
         schema: options.schema,
         onAccept: options.onAccept,
         onCleanup: options.onCleanup,
@@ -52,40 +82,18 @@ function RegisterInviteExtension(options) {
         label: options.label,
         description: options.description,
         placement: resolvePlacement(options.placement),
+        // The core answers an empty string when it resolves no module, which
+        // must not read as one module shared by every unresolved registration.
         moduleId: (0, interface_core_1.GetResponsibleModule)() || undefined,
     };
     internal.RegisterInviteExtension.register(info);
     return () => internal.RegisterInviteExtension.unregister(info);
 }
-function isSameRegisteringModule(held, incoming) {
-    if (held === incoming)
-        return true;
-    return held.moduleId !== undefined && held.moduleId === incoming.moduleId;
-}
+/**
+ * @internal
+ */
 var internal;
 (function (internal) {
     internal.RegisterInviteExtension = new interface_core_1.RegisteringProxy();
-    function applyInviteExtension(info) {
-        const existing = inviteExtensions.get(info.key);
-        if (existing && !isSameRegisteringModule(existing.info, info)) {
-            logging_1.Logging.Warn(`[dms] invite extension key "${info.key}" was already registered by another module; the latest registration now owns it. If two modules claim this key, one of them silently loses its payload — give them distinct keys.`);
-        }
-        inviteExtensions.set(info.key, { info });
-    }
-    internal.applyInviteExtension = applyInviteExtension;
-    function revokeInviteExtension(info) {
-        const existing = inviteExtensions.get(info.key);
-        if (!existing || existing.info !== info)
-            return;
-        inviteExtensions.delete(info.key);
-    }
-    internal.revokeInviteExtension = revokeInviteExtension;
-    function clearInviteExtensions() {
-        inviteExtensions.clear();
-    }
-    internal.clearInviteExtensions = clearInviteExtensions;
 })(internal || (exports.internal = internal = {}));
-function logInviteExtensionFailure(key, action, error) {
-    logging_1.Logging.Error(`[dms] invite extension "${key}" failed to ${action}:`, error);
-}
 //# sourceMappingURL=registry.js.map

package/dist/invite-extensions/registry.js.map

@@ -1 +1 @@
-{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/invite-extensions/registry.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/invite-extensions/registry.ts"],"names":[],"mappings":";;;AA6EA,0DA2BC;AAxGD,+DAGoC;AACpC,oDAAwE;AAOxE,MAAM,iBAAiB,GAA4B,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC;AAE7E,SAAS,gBAAgB,CACvB,OAAmD;IAEnD,IAAI,CAAC,OAAO;QAAE,OAAO,iBAAiB,CAAC;IACvC,yEAAyE;IACzE,mDAAmD;IACnD,MAAM,SAAS,GAA4B;QACzC,IAAI,EAAE,OAAO,CAAC,IAAI,IAAI,iBAAiB,CAAC,IAAI;QAC5C,KAAK,EAAE,OAAO,CAAC,KAAK,IAAI,iBAAiB,CAAC,KAAK;KAChD,CAAC;IACF,IAAI,OAAO,CAAC,WAAW;QAAE,SAAS,CAAC,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;IACrE,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,SAAS,eAAe,CAAC,GAAW;IAClC,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,CAAC;QAChB,MAAM,IAAI,KAAK,CAAC,mDAAmD,CAAC,CAAC;IACvE,CAAC;IACD,IAAI,GAAG,CAAC,QAAQ,CAAC,4CAAgC,CAAC,EAAE,CAAC;QACnD,MAAM,IAAI,KAAK,CACb,yBAAyB,GAAG,sBAAsB,4CAAgC,sEAAsE,CACzJ,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,SAAgB,uBAAuB,CACrC,OAAkC;IAElC,eAAe,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAE7B,MAAM,IAAI,GAAwB;QAChC,GAAG,EAAE,OAAO,CAAC,GAAG;QAChB,SAAS,EAAE,OAAO,CAAC,SAAS;QAC5B,kEAAkE;QAClE,+DAA+D;QAC/D,iEAAiE;QACjE,gEAAgE;QAChE,MAAM,EAAE,OAAO,CAAC,MAAkD;QAClE,QAAQ,EAAE,OAAO,CAAC,QAA2C;QAC7D,SAAS,EAAE,OAAO,CAAC,SAA6C;QAChE,QAAQ,EAAE,OAAO,CAAC,QAAQ;QAC1B,QAAQ,EAAE,OAAO,CAAC,QAA2C;QAC7D,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,WAAW,EAAE,OAAO,CAAC,WAAW;QAChC,SAAS,EAAE,gBAAgB,CAAC,OAAO,CAAC,SAAS,CAAC;QAC9C,qEAAqE;QACrE,uEAAuE;QACvE,QAAQ,EAAE,IAAA,qCAAoB,GAAE,IAAI,SAAS;KAC9C,CAAC;IAEF,QAAQ,CAAC,uBAAuB,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;IAChD,OAAO,GAAG,EAAE,CAAC,QAAQ,CAAC,uBAAuB,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;AACjE,CAAC;AAED;;GAEG;AACH,IAAiB,QAAQ,CAIxB;AAJD,WAAiB,QAAQ;IACV,gCAAuB,GAAG,IAAI,iCAAgB,EAExD,CAAC;AACN,CAAC,EAJgB,QAAQ,wBAAR,QAAQ,QAIxB"}

package/dist/invite-extensions/types.d.ts

@@ -1,74 +1,99 @@
-import type { FieldGroupSerialized, FormBuilder } from "../base/form";
-import type { WatchAction } from "../base/types/watch";
+import type { FormBuilder } from "../base/form";
 import type { ZodType, ZodTypeDef } from "zod";
 import type { PlacementSide } from "../component";
 import type { TenantMember } from "../db";
 import type { MaybePromise } from "../types";
+/**
+ * Where an extension's fields sit among the invite form's own. `anchorField`
+ * names a top-level field (or field group) id of the invite form; without one,
+ * `before` puts the block above every own field and `after`/`end` below them.
+ */
 export interface InviteExtensionPlacement {
     side?: PlacementSide;
     anchorField?: string;
+    /**
+     * Breaks the tie when several extensions land at the same spot: lower first,
+     * equal orders fall back to the extension key — never to module start order.
+     */
     order?: number;
 }
-export interface ResolvedInvitePlacement {
-    side: PlacementSide;
-    anchorField?: string;
-    order: number;
-}
+/** The invitation an extension's payload is being delivered for. */
 export interface InviteExtensionContext {
     tenantId: string;
     email: string;
+    /** Stable durable delivery identity. Handlers must deduplicate effects when present. */
     deliveryId?: string;
+    /**
+     * Unset when the invitee already had an account: they are added to the
+     * tenant straight away and no `user_invites` row is ever written.
+     */
     inviteId?: string;
 }
 export type InviteCleanupReason = "invite-deleted" | "member-removed";
+/** What went away, so a contributor knows which of its data to drop. */
 export interface InviteCleanupContext {
     reason: InviteCleanupReason;
     tenantId: string;
+    /** Stable durable delivery identity. Cleanup must tolerate concurrent retries. */
     deliveryId?: string;
+    /** Set for `invite-deleted`. */
     inviteId?: string;
     email?: string;
+    /** Set for `member-removed`. */
     userId?: string;
 }
 export type InviteAcceptHandler<T> = (payload: T, member: TenantMember, context: InviteExtensionContext) => MaybePromise<void>;
+/**
+ * Receives the payload an admin just saved on a pending invitation, parsed by
+ * the extension's schema, and the one it replaced — `undefined` when the
+ * invitation carried none or the schema no longer accepts it.
+ */
 export type InviteUpdateHandler<T> = (payload: T, previous: T | undefined, context: InviteExtensionContext) => MaybePromise<void>;
 export type InviteCleanupHandler<T> = (payload: T | undefined, context: InviteCleanupContext) => MaybePromise<void>;
-export interface InviteDeliveryOptions {
-    retryOnFailure?: boolean;
-}
 export interface InviteExtensionOptions<T> {
+    /**
+     * Namespace of the extension, on the invite row and on the form fields it
+     * contributes. May not contain `__`, which separates it from the field id.
+     */
     key: string;
+    /** Form whose fields are merged into the invite modal. */
     component: FormBuilder;
+    /**
+     * Validates the payload, at submit and again at delivery. Its keys are the
+     * field ids of `component`, unprefixed.
+     *
+     * The input side is `unknown` because the schema is handed the raw slice of
+     * the submission — which also lets it transform, `onAccept` receiving the
+     * output.
+     */
     schema: ZodType<T, ZodTypeDef, unknown>;
+    /** Called after membership exists; durable deliveries can replay with the same deliveryId. */
     onAccept: InviteAcceptHandler<T>;
+    /**
+     * Called when the invitation is cancelled or replaced, and when a member is
+     * removed from the tenant. Not called on acceptance. Durable expiry and
+     * retirement can replay concurrently; deduplicate external effects by
+     * context.deliveryId and scope resource deletion to context.inviteId.
+     */
     onCleanup?: InviteCleanupHandler<T>;
+    /**
+     * Whether an admin may change the payload while the invitation is pending,
+     * from its edit form. Defaults to `true`: the payload is only ever handed
+     * over at acceptance, so an edit before then reads exactly as if the admin
+     * had typed the new value when inviting. `false` shows the fields read-only
+     * there.
+     */
     editable?: boolean;
+    /**
+     * Called after an admin saved a changed payload on a pending invitation, for
+     * an extension that derives something from it before acceptance. The edit is
+     * already stored: a failure is logged, never raised.
+     */
     onUpdate?: InviteUpdateHandler<T>;
+    /** Heading of the contributed block. Defaults to the form's own title. */
     label?: string;
     description?: string;
     placement?: InviteExtensionPlacement;
 }
-export interface InviteExtensionInfo {
-    key: string;
-    component: FormBuilder;
-    schema: ZodType<unknown, ZodTypeDef, unknown>;
-    onAccept: InviteAcceptHandler<unknown>;
-    onCleanup?: InviteCleanupHandler<unknown>;
-    editable?: boolean;
-    onUpdate?: InviteUpdateHandler<unknown>;
-    label?: string;
-    description?: string;
-    placement: ResolvedInvitePlacement;
-    moduleId?: string;
-}
+/** Payloads stored on an invitation, keyed by extension key. */
 export type InviteExtensionPayloads = Record<string, unknown>;
-export interface InviteFieldContribution {
-    key: string;
-    side: PlacementSide;
-    anchorField?: string;
-    order: number;
-    editable: boolean;
-    group: FieldGroupSerialized;
-    properties: Record<string, unknown>;
-    requiredProperties: string[];
-    watchActions: WatchAction[];
-}

package/dist/invite-extensions.d.ts

@@ -1,7 +1,33 @@
+/**
+ * Module data carried by a member invitation — the invitation-side counterpart
+ * of `@RegisterPageExtension`, split by concern under `./invite-extensions/`:
+ *
+ * - `types` — the contracts a contributor implements
+ * - `registry` — `RegisterInviteExtension` and the registration proxy that
+ *   binds an extension to its module's lifetime
+ * - `availability` — `RegisterInviteAvailability`, which disables the invite
+ *   action with a reason
+ *
+ * The rest is driven by the DMS runtime alone and lives under
+ * `./invite-extensions/internal/`: the namespacing of contributed fields
+ * (`field-ids`), their serialization, placement and merging into the DMS
+ * invite modal (`form-slot`), validation at submit, delivery at acceptance and
+ * cleanup (`delivery`), and the prefill, validation and notification of a
+ * pending invitation's edit (`edit`).
+ *
+ * `form-slot` claims the invite forms' component slots on import, so importing
+ * this barrel is what opens the modal and the edit form to extensions.
+ */
+import "./invite-extensions/internal/form-slot";
+import * as availability from "./invite-extensions/internal/availability";
 export { type InviteAvailabilityResolver, RegisterInviteAvailability, } from "./invite-extensions/availability";
-export * from "./invite-extensions/field-ids";
-export * from "./invite-extensions/form-slot";
-export { internal } from "./invite-extensions/internal";
-export { HTTP_BAD_REQUEST } from "./invite-extensions/payload-slices";
 export * from "./invite-extensions/registry";
 export * from "./invite-extensions/types";
+/**
+ * @internal
+ */
+export declare namespace internal {
+    const RegisterInviteExtension: import("@antelopejs/interface-core").RegisteringProxy<(info: import("./invite-extensions/internal/types").InviteExtensionInfo) => void>;
+    /** Kept for module compatibility; the DMS imports it from `internal/availability`. */
+    const ResolveInviteAvailability: typeof availability.ResolveInviteAvailability;
+}