@mj-biz-apps/forms-core-entities-server 0.0.0 → 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @mj-biz-apps/forms-core-entities-server
+ *
+ * Server-side entity subclasses for MJ Forms entities. These classes override
+ * Save()/Delete()/ValidateAsync() to add lifecycle hooks (anonymous-submission
+ * hardening, cross-record invariants, version snapshotting) that must run only
+ * on the server.
+ *
+ * Import this package from the server bootstrap so its @RegisterClass decorators
+ * fire at startup.
+ */
+import './magic-link/FormDistributionEntityServer.js';
+export { MagicLinkMinterRegistry, type IAnonymousMagicLinkMinter, type MintAnonymousInviteParams, type MintAnonymousInviteResult, } from './magic-link/minter.js';
+export { getMagicLinkProvisioningConfig, resetMagicLinkProvisioningConfigForTests, type MagicLinkProvisioningConfig, type DistributionChannelType, } from './magic-link/config.js';
+export { decideProvisioning, resolveExpiry, type DistributionProvisioningState, type ProvisioningDecision, } from './magic-link/provisioning-decision.js';
+export { runProvisioning, DISTRIBUTION_ENTITY_NAME, type ProvisionContext, type ProvisionOutcome, } from './magic-link/provision-runner.js';
+export { FormDistributionEntityServer } from './magic-link/FormDistributionEntityServer.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAKH,OAAO,8CAA8C,CAAC;AAKtD,OAAO,EACL,uBAAuB,EACvB,KAAK,yBAAyB,EAC9B,KAAK,yBAAyB,EAC9B,KAAK,yBAAyB,GAC/B,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,8BAA8B,EAC9B,wCAAwC,EACxC,KAAK,2BAA2B,EAChC,KAAK,uBAAuB,GAC7B,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,kBAAkB,EAClB,aAAa,EACb,KAAK,6BAA6B,EAClC,KAAK,oBAAoB,GAC1B,MAAM,uCAAuC,CAAC;AAC/C,OAAO,EACL,eAAe,EACf,wBAAwB,EACxB,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,GACtB,MAAM,kCAAkC,CAAC;AAC1C,OAAO,EAAE,4BAA4B,EAAE,MAAM,8CAA8C,CAAC"}

package/dist/index.js

@@ -0,0 +1,24 @@
+/**
+ * @mj-biz-apps/forms-core-entities-server
+ *
+ * Server-side entity subclasses for MJ Forms entities. These classes override
+ * Save()/Delete()/ValidateAsync() to add lifecycle hooks (anonymous-submission
+ * hardening, cross-record invariants, version snapshotting) that must run only
+ * on the server.
+ *
+ * Import this package from the server bootstrap so its @RegisterClass decorators
+ * fire at startup.
+ */
+// FormDistribution lifecycle hook: mints the anonymous magic-link invite when a
+// public/anonymous distribution goes live (FORMS_BUILD_PLAN §4 item 4). The import
+// triggers its @RegisterClass decorator so the class factory uses this subclass.
+import './magic-link/FormDistributionEntityServer.js';
+// The minting seam (interface + registry) and provisioning config/decisions —
+// re-exported so the host bootstrap (`@mj-biz-apps/forms-server`) can register a
+// concrete minter, and so tests can drive the pure decision logic.
+export { MagicLinkMinterRegistry, } from './magic-link/minter.js';
+export { getMagicLinkProvisioningConfig, resetMagicLinkProvisioningConfigForTests, } from './magic-link/config.js';
+export { decideProvisioning, resolveExpiry, } from './magic-link/provisioning-decision.js';
+export { runProvisioning, DISTRIBUTION_ENTITY_NAME, } from './magic-link/provision-runner.js';
+export { FormDistributionEntityServer } from './magic-link/FormDistributionEntityServer.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,gFAAgF;AAChF,mFAAmF;AACnF,iFAAiF;AACjF,OAAO,8CAA8C,CAAC;AAEtD,8EAA8E;AAC9E,iFAAiF;AACjF,mEAAmE;AACnE,OAAO,EACL,uBAAuB,GAIxB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,8BAA8B,EAC9B,wCAAwC,GAGzC,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,kBAAkB,EAClB,aAAa,GAGd,MAAM,uCAAuC,CAAC;AAC/C,OAAO,EACL,eAAe,EACf,wBAAwB,GAGzB,MAAM,kCAAkC,CAAC;AAC1C,OAAO,EAAE,4BAA4B,EAAE,MAAM,8CAA8C,CAAC"}

package/dist/magic-link/FormDistributionEntityServer.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Server-side lifecycle hook for `MJ_BizApps_Forms: Form Distributions`.
+ *
+ * Mints an anonymous, multi-use, resource-scoped magic-link invite the first
+ * time a distribution becomes an active public/anonymous channel, and stores the
+ * resulting invite ID on `MagicLinkInviteID`. Fires from `Save()`, so it runs
+ * however the distribution is created/activated — builder, AI, import, or API.
+ *
+ * Registered via `@RegisterClass(BaseEntity, 'MJ_BizApps_Forms: Form Distributions')`
+ * so MJ's class factory instantiates THIS subclass server-side. The minting is
+ * delegated through the `MagicLinkMinterRegistry` seam (see minter.ts); when no
+ * host minter is registered (host has not enabled core `magicLink`), the hook
+ * logs a clear warning and leaves `MagicLinkInviteID` null WITHOUT failing the
+ * save. The orchestration lives in `runProvisioning` (provision-runner.ts) so it
+ * is unit-testable without a DB; this class is the thin BaseEntity adapter.
+ *
+ * See FORMS_BUILD_PLAN §4 item 4.
+ */
+import { type EntitySaveOptions } from '@memberjunction/core';
+import { mjBizAppsFormsFormDistributionEntity } from '@mj-biz-apps/forms-entities';
+export declare class FormDistributionEntityServer extends mjBizAppsFormsFormDistributionEntity {
+    /**
+     * Persists the distribution, then (post-save) provisions its anonymous
+     * magic-link invite when warranted. Provisioning never blocks the save:
+     * a missing minter or a mint failure is logged, and the distribution stands.
+     */
+    Save(options?: EntitySaveOptions): Promise<boolean>;
+    /**
+     * Writes the freshly minted invite ID and raw public-link token back onto this
+     * record with a single targeted second save. The re-entry is idempotent: the
+     * now-set `MagicLinkInviteID` makes the provisioning decision short-circuit on
+     * the recursive `Save()`, so no re-mint occurs. The raw token is written only
+     * when the column is still empty, so a repeat call never clobbers it (a public
+     * link's redeem URL must stay stable).
+     */
+    private persistMintResult;
+}
+//# sourceMappingURL=FormDistributionEntityServer.d.ts.map

package/dist/magic-link/FormDistributionEntityServer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FormDistributionEntityServer.d.ts","sourceRoot":"","sources":["../../src/magic-link/FormDistributionEntityServer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,EAAwB,KAAK,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAEpF,OAAO,EAAE,oCAAoC,EAAE,MAAM,6BAA6B,CAAC;AAKnF,qBACa,4BAA6B,SAAQ,oCAAoC;IACpF;;;;OAIG;IACmB,IAAI,CAAC,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,OAAO,CAAC;IAkCzE;;;;;;;OAOG;YACW,iBAAiB;CAchC"}

package/dist/magic-link/FormDistributionEntityServer.js

@@ -0,0 +1,84 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+/**
+ * Server-side lifecycle hook for `MJ_BizApps_Forms: Form Distributions`.
+ *
+ * Mints an anonymous, multi-use, resource-scoped magic-link invite the first
+ * time a distribution becomes an active public/anonymous channel, and stores the
+ * resulting invite ID on `MagicLinkInviteID`. Fires from `Save()`, so it runs
+ * however the distribution is created/activated — builder, AI, import, or API.
+ *
+ * Registered via `@RegisterClass(BaseEntity, 'MJ_BizApps_Forms: Form Distributions')`
+ * so MJ's class factory instantiates THIS subclass server-side. The minting is
+ * delegated through the `MagicLinkMinterRegistry` seam (see minter.ts); when no
+ * host minter is registered (host has not enabled core `magicLink`), the hook
+ * logs a clear warning and leaves `MagicLinkInviteID` null WITHOUT failing the
+ * save. The orchestration lives in `runProvisioning` (provision-runner.ts) so it
+ * is unit-testable without a DB; this class is the thin BaseEntity adapter.
+ *
+ * See FORMS_BUILD_PLAN §4 item 4.
+ */
+import { BaseEntity, LogError } from '@memberjunction/core';
+import { RegisterClass } from '@memberjunction/global';
+import { mjBizAppsFormsFormDistributionEntity } from '@mj-biz-apps/forms-entities';
+import { getMagicLinkProvisioningConfig } from './config.js';
+import { MagicLinkMinterRegistry } from './minter.js';
+import { runProvisioning, DISTRIBUTION_ENTITY_NAME } from './provision-runner.js';
+let FormDistributionEntityServer = class FormDistributionEntityServer extends mjBizAppsFormsFormDistributionEntity {
+    /**
+     * Persists the distribution, then (post-save) provisions its anonymous
+     * magic-link invite when warranted. Provisioning never blocks the save:
+     * a missing minter or a mint failure is logged, and the distribution stands.
+     */
+    async Save(options) {
+        const saved = await super.Save(options);
+        if (!saved) {
+            return false;
+        }
+        try {
+            await runProvisioning({
+                distributionId: this.ID,
+                channelType: this.ChannelType,
+                status: this.Status,
+                isActive: this.IsActive,
+                magicLinkInviteId: this.MagicLinkInviteID,
+                closeAt: this.CloseAt,
+            }, getMagicLinkProvisioningConfig(), MagicLinkMinterRegistry.Instance.Minter, this.ContextCurrentUser, (mint) => this.persistMintResult(mint));
+        }
+        catch (e) {
+            // Defensive: the runner is fail-soft, but a thrown error must never undo a
+            // successful distribution save.
+            LogError(`[FormDistributionEntityServer] Provisioning threw for distribution ${this.ID}: ${e instanceof Error ? e.message : String(e)}`);
+        }
+        return true;
+    }
+    /**
+     * Writes the freshly minted invite ID and raw public-link token back onto this
+     * record with a single targeted second save. The re-entry is idempotent: the
+     * now-set `MagicLinkInviteID` makes the provisioning decision short-circuit on
+     * the recursive `Save()`, so no re-mint occurs. The raw token is written only
+     * when the column is still empty, so a repeat call never clobbers it (a public
+     * link's redeem URL must stay stable).
+     */
+    async persistMintResult(mint) {
+        this.MagicLinkInviteID = mint.inviteId;
+        if (mint.rawToken && !this.PublicLinkToken) {
+            this.PublicLinkToken = mint.rawToken;
+        }
+        if (!(await this.Save())) {
+            LogError(`[FormDistributionEntityServer] Failed to store invite ${mint.inviteId} on distribution ${this.ID}: ` +
+                `${this.LatestResult?.CompleteMessage ?? 'unknown error'}`);
+            return false;
+        }
+        return true;
+    }
+};
+FormDistributionEntityServer = __decorate([
+    RegisterClass(BaseEntity, DISTRIBUTION_ENTITY_NAME)
+], FormDistributionEntityServer);
+export { FormDistributionEntityServer };
+//# sourceMappingURL=FormDistributionEntityServer.js.map

package/dist/magic-link/FormDistributionEntityServer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"FormDistributionEntityServer.js","sourceRoot":"","sources":["../../src/magic-link/FormDistributionEntityServer.ts"],"names":[],"mappings":";;;;;;AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,EAAE,UAAU,EAAE,QAAQ,EAA0B,MAAM,sBAAsB,CAAC;AACpF,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AACvD,OAAO,EAAE,oCAAoC,EAAE,MAAM,6BAA6B,CAAC;AACnF,OAAO,EAAE,8BAA8B,EAAE,MAAM,aAAa,CAAC;AAC7D,OAAO,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,EAAE,eAAe,EAAE,wBAAwB,EAAmB,MAAM,uBAAuB,CAAC;AAG5F,IAAM,4BAA4B,GAAlC,MAAM,4BAA6B,SAAQ,oCAAoC;IACpF;;;;OAIG;IACa,KAAK,CAAC,IAAI,CAAC,OAA2B;QACpD,MAAM,KAAK,GAAG,MAAM,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACxC,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,OAAO,KAAK,CAAC;QACf,CAAC;QAED,IAAI,CAAC;YACH,MAAM,eAAe,CACnB;gBACE,cAAc,EAAE,IAAI,CAAC,EAAE;gBACvB,WAAW,EAAE,IAAI,CAAC,WAAW;gBAC7B,MAAM,EAAE,IAAI,CAAC,MAAM;gBACnB,QAAQ,EAAE,IAAI,CAAC,QAAQ;gBACvB,iBAAiB,EAAE,IAAI,CAAC,iBAAiB;gBACzC,OAAO,EAAE,IAAI,CAAC,OAAO;aACtB,EACD,8BAA8B,EAAE,EAChC,uBAAuB,CAAC,QAAQ,CAAC,MAAM,EACvC,IAAI,CAAC,kBAAkB,EACvB,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,CACvC,CAAC;QACJ,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,2EAA2E;YAC3E,gCAAgC;YAChC,QAAQ,CACN,sEAAsE,IAAI,CAAC,EAAE,KAC3E,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAC3C,EAAE,CACH,CAAC;QACJ,CAAC;QAED,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;;;;OAOG;IACK,KAAK,CAAC,iBAAiB,CAAC,IAAgB;QAC9C,IAAI,CAAC,iBAAiB,GAAG,IAAI,CAAC,QAAQ,CAAC;QACvC,IAAI,IAAI,CAAC,QAAQ,IAAI,CAAC,IAAI,CAAC,eAAe,EAAE,CAAC;YAC3C,IAAI,CAAC,eAAe,GAAG,IAAI,CAAC,QAAQ,CAAC;QACvC,CAAC;QACD,IAAI,CAAC,CAAC,MAAM,IAAI,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC;YACzB,QAAQ,CACN,yDAAyD,IAAI,CAAC,QAAQ,oBAAoB,IAAI,CAAC,EAAE,IAAI;gBACnG,GAAG,IAAI,CAAC,YAAY,EAAE,eAAe,IAAI,eAAe,EAAE,CAC7D,CAAC;YACF,OAAO,KAAK,CAAC;QACf,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;CACF,CAAA;AA9DY,4BAA4B;IADxC,aAAa,CAAC,UAAU,EAAE,wBAAwB,CAAC;GACvC,4BAA4B,CA8DxC"}

package/dist/magic-link/config.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Configuration for distribution magic-link provisioning.
+ *
+ * Generic + host-configurable. Every knob is read from `process.env` ONCE and
+ * frozen (same pattern as the public-submit config in `@mj-biz-apps/forms-server`),
+ * so a host tunes behaviour without code changes and the defaults are safe.
+ *
+ * Env vars:
+ *  - `FORMS_MAGICLINK_CHANNELS`   Comma-separated `ChannelType` values that get an
+ *                                 anonymous link minted. Default `PublicLink,Embed,QR`
+ *                                 (NOT `Email` — email distributions are individually
+ *                                 addressed, not anonymous public links).
+ *  - `FORMS_MAGICLINK_MAX_USES`   Default `maxUses` for the minted invite. Default
+ *                                 1,000,000 — effectively a public URL. A distribution's
+ *                                 own `MaxResponses` quota is enforced separately at submit.
+ *  - `FORMS_MAGICLINK_EXPIRY_HOURS`  Fixed expiry (hours) applied to every minted link.
+ *                                 Unset (default) = no fixed expiry; expiry is instead
+ *                                 driven by the distribution's `CloseAt` when set.
+ *  - `FORMS_MAGICLINK_APPLICATION`   Application name the anonymous session is scoped to.
+ *                                 Default `Forms` (the app WP-A seeds).
+ *  - `FORMS_MAGICLINK_ROLE`       Restricted role the invite grants. Default
+ *                                 `Form Respondent` (the role WP-A seeds). Must be
+ *                                 magic-link grantable on the host.
+ */
+/** A `ChannelType` value on `FormDistribution`. */
+export type DistributionChannelType = 'Email' | 'Embed' | 'PublicLink' | 'QR';
+/** Frozen, validated configuration for distribution magic-link provisioning. */
+export interface MagicLinkProvisioningConfig {
+    /** Channel types that receive a minted anonymous link. */
+    linkableChannels: ReadonlySet<DistributionChannelType>;
+    /** Default `maxUses` for the minted invite. */
+    defaultMaxUses: number;
+    /** Fixed expiry in hours, or `undefined` to use the distribution `CloseAt` (or none). */
+    fixedExpiryHours: number | undefined;
+    /** Application name the anonymous session is scoped to. */
+    applicationName: string;
+    /** Restricted role the invite grants. */
+    roleName: string;
+}
+/** Read (and memoize) the magic-link provisioning configuration from the environment. */
+export declare function getMagicLinkProvisioningConfig(): MagicLinkProvisioningConfig;
+/** Test-only: clear the memoized config so env changes take effect. */
+export declare function resetMagicLinkProvisioningConfigForTests(): void;
+//# sourceMappingURL=config.d.ts.map

package/dist/magic-link/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/magic-link/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,mDAAmD;AACnD,MAAM,MAAM,uBAAuB,GAAG,OAAO,GAAG,OAAO,GAAG,YAAY,GAAG,IAAI,CAAC;AAE9E,gFAAgF;AAChF,MAAM,WAAW,2BAA2B;IAC1C,0DAA0D;IAC1D,gBAAgB,EAAE,WAAW,CAAC,uBAAuB,CAAC,CAAC;IACvD,+CAA+C;IAC/C,cAAc,EAAE,MAAM,CAAC;IACvB,yFAAyF;IACzF,gBAAgB,EAAE,MAAM,GAAG,SAAS,CAAC;IACrC,2DAA2D;IAC3D,eAAe,EAAE,MAAM,CAAC;IACxB,yCAAyC;IACzC,QAAQ,EAAE,MAAM,CAAC;CAClB;AA4CD,yFAAyF;AACzF,wBAAgB,8BAA8B,IAAI,2BAA2B,CAY5E;AAED,uEAAuE;AACvE,wBAAgB,wCAAwC,IAAI,IAAI,CAE/D"}

package/dist/magic-link/config.js

@@ -0,0 +1,80 @@
+/**
+ * Configuration for distribution magic-link provisioning.
+ *
+ * Generic + host-configurable. Every knob is read from `process.env` ONCE and
+ * frozen (same pattern as the public-submit config in `@mj-biz-apps/forms-server`),
+ * so a host tunes behaviour without code changes and the defaults are safe.
+ *
+ * Env vars:
+ *  - `FORMS_MAGICLINK_CHANNELS`   Comma-separated `ChannelType` values that get an
+ *                                 anonymous link minted. Default `PublicLink,Embed,QR`
+ *                                 (NOT `Email` — email distributions are individually
+ *                                 addressed, not anonymous public links).
+ *  - `FORMS_MAGICLINK_MAX_USES`   Default `maxUses` for the minted invite. Default
+ *                                 1,000,000 — effectively a public URL. A distribution's
+ *                                 own `MaxResponses` quota is enforced separately at submit.
+ *  - `FORMS_MAGICLINK_EXPIRY_HOURS`  Fixed expiry (hours) applied to every minted link.
+ *                                 Unset (default) = no fixed expiry; expiry is instead
+ *                                 driven by the distribution's `CloseAt` when set.
+ *  - `FORMS_MAGICLINK_APPLICATION`   Application name the anonymous session is scoped to.
+ *                                 Default `Forms` (the app WP-A seeds).
+ *  - `FORMS_MAGICLINK_ROLE`       Restricted role the invite grants. Default
+ *                                 `Form Respondent` (the role WP-A seeds). Must be
+ *                                 magic-link grantable on the host.
+ */
+const ALL_CHANNELS = ['Email', 'Embed', 'PublicLink', 'QR'];
+const DEFAULT_CHANNELS = ['PublicLink', 'Embed', 'QR'];
+const DEFAULT_MAX_USES = 1_000_000;
+const DEFAULT_APPLICATION = 'Forms';
+const DEFAULT_ROLE = 'Form Respondent';
+/** Numeric env read with a default; non-numeric / non-positive falls back. */
+function positiveNumberFromEnv(key, fallback) {
+    const raw = process.env[key];
+    if (raw === undefined || raw.trim() === '') {
+        return fallback;
+    }
+    const parsed = Number(raw);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+}
+/** Optional positive-number env read; returns `undefined` when unset/invalid. */
+function optionalPositiveNumberFromEnv(key) {
+    const raw = process.env[key];
+    if (raw === undefined || raw.trim() === '') {
+        return undefined;
+    }
+    const parsed = Number(raw);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : undefined;
+}
+/** Parse the channel allow-list; unknown tokens are ignored; empty falls back to defaults. */
+function channelsFromEnv(key) {
+    const raw = process.env[key];
+    if (raw === undefined || raw.trim() === '') {
+        return new Set(DEFAULT_CHANNELS);
+    }
+    const valid = new Set(ALL_CHANNELS);
+    const parsed = raw
+        .split(',')
+        .map((s) => s.trim())
+        .filter((s) => valid.has(s));
+    return parsed.length > 0 ? new Set(parsed) : new Set(DEFAULT_CHANNELS);
+}
+let cached;
+/** Read (and memoize) the magic-link provisioning configuration from the environment. */
+export function getMagicLinkProvisioningConfig() {
+    if (cached) {
+        return cached;
+    }
+    cached = Object.freeze({
+        linkableChannels: channelsFromEnv('FORMS_MAGICLINK_CHANNELS'),
+        defaultMaxUses: positiveNumberFromEnv('FORMS_MAGICLINK_MAX_USES', DEFAULT_MAX_USES),
+        fixedExpiryHours: optionalPositiveNumberFromEnv('FORMS_MAGICLINK_EXPIRY_HOURS'),
+        applicationName: process.env.FORMS_MAGICLINK_APPLICATION?.trim() || DEFAULT_APPLICATION,
+        roleName: process.env.FORMS_MAGICLINK_ROLE?.trim() || DEFAULT_ROLE,
+    });
+    return cached;
+}
+/** Test-only: clear the memoized config so env changes take effect. */
+export function resetMagicLinkProvisioningConfigForTests() {
+    cached = undefined;
+}
+//# sourceMappingURL=config.js.map

package/dist/magic-link/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/magic-link/config.ts"],"names":[],"mappings":"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"}

package/dist/magic-link/minter.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Dependency-inversion seam for magic-link invite minting.
+ *
+ * WHY a seam (and not a direct call into MJ core's `MagicLinkService`):
+ *  - `@memberjunction/server` does NOT re-export `MagicLinkService`, and its
+ *    package `exports` map only exposes `.`, so the class cannot be imported
+ *    from this package (deep imports throw `ERR_PACKAGE_PATH_NOT_EXPORTED`).
+ *  - Even where reachable, `@memberjunction/server` is heavy (Apollo, the whole
+ *    GraphQL stack, AI/action bundles) and validates DB config at import time —
+ *    pulling it into this lightweight entity-subclass package would be wrong.
+ *  - On the pinned MJ 5.43.0, `MagicLinkService.CreateInvite` cannot set the
+ *    `IdentityMode='anonymous'` / `Kind='resource-share'` / resource-scope fields
+ *    a Forms distribution link requires anyway.
+ *
+ * So this package (the entity-lifecycle layer) defines a minimal minting
+ * CONTRACT and a registry; `@mj-biz-apps/forms-server` (which already depends on
+ * `@memberjunction/server`) registers a concrete minter at bootstrap. The hook
+ * calls whatever is registered, and gates gracefully when nothing is — which is
+ * exactly the "host has not enabled magicLink" case. Any host could register a
+ * different minting backend without touching this package.
+ */
+import { BaseSingleton } from '@memberjunction/global';
+import type { UserInfo } from '@memberjunction/core';
+/** What the hook asks the minter to provision. Generic over any resource. */
+export interface MintAnonymousInviteParams {
+    /** Application the anonymous session is scoped to (the minter resolves the ID from this name). */
+    applicationName: string;
+    /** Restricted role the invite grants (e.g. "Form Respondent"). Must be magic-link grantable on the host. */
+    roleName: string;
+    /** Resource-share scope: the entity name of the scoped resource (e.g. the distribution entity). */
+    resourceTypeName: string;
+    /** Resource-share scope: the primary key (stringified) of the scoped resource. */
+    resourceId: string;
+    /** Maximum redemptions. A public URL uses a high value (effectively unlimited). */
+    maxUses: number;
+    /** Hard expiry; `null`/`undefined` means the minter applies its own default (typically none / very long). */
+    expiresAt?: Date | null;
+}
+/** Outcome of a mint attempt. `skipped` is the graceful-gate signal (NOT an error). */
+export interface MintAnonymousInviteResult {
+    /** True when an invite row was created. */
+    success: boolean;
+    /** The created `MJ: Magic Link Invites` row ID — stored on `FormDistribution.MagicLinkInviteID`. */
+    inviteId?: string;
+    /**
+     * The RAW redeemable magic-link token (the secret half of the link). The invite
+     * row persists only its SHA-256 hash; this raw value travels in the result so the
+     * caller can store it on `FormDistribution.PublicLinkToken` and build the shareable
+     * public redeem URL. A public form link is low-secrecy by design (the URL is meant
+     * to be shared), so persisting the raw token on the distribution is intentional —
+     * the raw token is NOT stored on the invite row.
+     */
+    rawToken?: string;
+    /**
+     * True when minting was deliberately skipped because the host has not enabled
+     * magic links (or the minter is otherwise unavailable). The caller must NOT
+     * treat this as a failure: it leaves `MagicLinkInviteID` null and logs a warning.
+     */
+    skipped?: boolean;
+    /** Human-readable reason for a skip or failure. */
+    message?: string;
+}
+/**
+ * The contract a host registers to provision anonymous magic-link invites.
+ * Implemented in `@mj-biz-apps/forms-server` over MJ core's magic-link tables.
+ */
+export interface IAnonymousMagicLinkMinter {
+    /**
+     * Mints an anonymous, resource-scoped, multi-use invite and returns its ID.
+     * Implementations MUST return `{ success:false, skipped:true }` (never throw)
+     * when the host has not enabled magic links, so a distribution still saves.
+     *
+     * @param params       what to scope/grant the invite to
+     * @param creatingUser the internal staff user saving the distribution (becomes the invite's issuer)
+     */
+    MintAnonymousInvite(params: MintAnonymousInviteParams, creatingUser: UserInfo): Promise<MintAnonymousInviteResult>;
+}
+/**
+ * Process-wide registry holding the host's minter, if any. A `BaseSingleton`
+ * per CLAUDE.md rule 6. The hook reads `Instance.Minter`; `undefined` means no
+ * host registered one → the hook gates gracefully.
+ */
+export declare class MagicLinkMinterRegistry extends BaseSingleton<MagicLinkMinterRegistry> {
+    private _minter;
+    static get Instance(): MagicLinkMinterRegistry;
+    /** The registered minter, or `undefined` when no host has registered one. */
+    get Minter(): IAnonymousMagicLinkMinter | undefined;
+    /** Registers (or replaces) the host's minter. Called once at server bootstrap. */
+    Register(minter: IAnonymousMagicLinkMinter): void;
+    /** Test-only: clears the registered minter. */
+    ClearForTests(): void;
+}
+//# sourceMappingURL=minter.d.ts.map

package/dist/magic-link/minter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"minter.d.ts","sourceRoot":"","sources":["../../src/magic-link/minter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AACvD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAErD,6EAA6E;AAC7E,MAAM,WAAW,yBAAyB;IACxC,kGAAkG;IAClG,eAAe,EAAE,MAAM,CAAC;IACxB,4GAA4G;IAC5G,QAAQ,EAAE,MAAM,CAAC;IACjB,mGAAmG;IACnG,gBAAgB,EAAE,MAAM,CAAC;IACzB,kFAAkF;IAClF,UAAU,EAAE,MAAM,CAAC;IACnB,mFAAmF;IACnF,OAAO,EAAE,MAAM,CAAC;IAChB,6GAA6G;IAC7G,SAAS,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;CACzB;AAED,uFAAuF;AACvF,MAAM,WAAW,yBAAyB;IACxC,2CAA2C;IAC3C,OAAO,EAAE,OAAO,CAAC;IACjB,oGAAoG;IACpG,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,mDAAmD;IACnD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;GAGG;AACH,MAAM,WAAW,yBAAyB;IACxC;;;;;;;OAOG;IACH,mBAAmB,CACjB,MAAM,EAAE,yBAAyB,EACjC,YAAY,EAAE,QAAQ,GACrB,OAAO,CAAC,yBAAyB,CAAC,CAAC;CACvC;AAED;;;;GAIG;AACH,qBAAa,uBAAwB,SAAQ,aAAa,CAAC,uBAAuB,CAAC;IACjF,OAAO,CAAC,OAAO,CAAwC;IAEvD,WAAkB,QAAQ,IAAI,uBAAuB,CAEpD;IAED,6EAA6E;IAC7E,IAAW,MAAM,IAAI,yBAAyB,GAAG,SAAS,CAEzD;IAED,kFAAkF;IAC3E,QAAQ,CAAC,MAAM,EAAE,yBAAyB,GAAG,IAAI;IAIxD,+CAA+C;IACxC,aAAa,IAAI,IAAI;CAG7B"}

package/dist/magic-link/minter.js

@@ -0,0 +1,45 @@
+/**
+ * Dependency-inversion seam for magic-link invite minting.
+ *
+ * WHY a seam (and not a direct call into MJ core's `MagicLinkService`):
+ *  - `@memberjunction/server` does NOT re-export `MagicLinkService`, and its
+ *    package `exports` map only exposes `.`, so the class cannot be imported
+ *    from this package (deep imports throw `ERR_PACKAGE_PATH_NOT_EXPORTED`).
+ *  - Even where reachable, `@memberjunction/server` is heavy (Apollo, the whole
+ *    GraphQL stack, AI/action bundles) and validates DB config at import time —
+ *    pulling it into this lightweight entity-subclass package would be wrong.
+ *  - On the pinned MJ 5.43.0, `MagicLinkService.CreateInvite` cannot set the
+ *    `IdentityMode='anonymous'` / `Kind='resource-share'` / resource-scope fields
+ *    a Forms distribution link requires anyway.
+ *
+ * So this package (the entity-lifecycle layer) defines a minimal minting
+ * CONTRACT and a registry; `@mj-biz-apps/forms-server` (which already depends on
+ * `@memberjunction/server`) registers a concrete minter at bootstrap. The hook
+ * calls whatever is registered, and gates gracefully when nothing is — which is
+ * exactly the "host has not enabled magicLink" case. Any host could register a
+ * different minting backend without touching this package.
+ */
+import { BaseSingleton } from '@memberjunction/global';
+/**
+ * Process-wide registry holding the host's minter, if any. A `BaseSingleton`
+ * per CLAUDE.md rule 6. The hook reads `Instance.Minter`; `undefined` means no
+ * host registered one → the hook gates gracefully.
+ */
+export class MagicLinkMinterRegistry extends BaseSingleton {
+    static get Instance() {
+        return super.getInstance();
+    }
+    /** The registered minter, or `undefined` when no host has registered one. */
+    get Minter() {
+        return this._minter;
+    }
+    /** Registers (or replaces) the host's minter. Called once at server bootstrap. */
+    Register(minter) {
+        this._minter = minter;
+    }
+    /** Test-only: clears the registered minter. */
+    ClearForTests() {
+        this._minter = undefined;
+    }
+}
+//# sourceMappingURL=minter.js.map

package/dist/magic-link/minter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"minter.js","sourceRoot":"","sources":["../../src/magic-link/minter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AA+DvD;;;;GAIG;AACH,MAAM,OAAO,uBAAwB,SAAQ,aAAsC;IAG1E,MAAM,KAAK,QAAQ;QACxB,OAAO,KAAK,CAAC,WAAW,EAA2B,CAAC;IACtD,CAAC;IAED,6EAA6E;IAC7E,IAAW,MAAM;QACf,OAAO,IAAI,CAAC,OAAO,CAAC;IACtB,CAAC;IAED,kFAAkF;IAC3E,QAAQ,CAAC,MAAiC;QAC/C,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC;IACxB,CAAC;IAED,+CAA+C;IACxC,aAAa;QAClB,IAAI,CAAC,OAAO,GAAG,SAAS,CAAC;IAC3B,CAAC;CACF"}

package/dist/magic-link/provision-runner.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Orchestration for distribution magic-link provisioning, decoupled from the
+ * BaseEntity so it is unit-testable without a DB or entity metadata. The entity
+ * hook (`FormDistributionEntityServer`) is a thin adapter that supplies this
+ * runner with the distribution's current state, the context user, and a
+ * persist-callback that writes the minted invite id back onto the record.
+ */
+import { type UserInfo } from '@memberjunction/core';
+import type { MagicLinkProvisioningConfig } from './config.js';
+import { type DistributionProvisioningState } from './provisioning-decision.js';
+import type { IAnonymousMagicLinkMinter } from './minter.js';
+/** Entity name of the distribution itself — the resource the invite is scoped to. */
+export declare const DISTRIBUTION_ENTITY_NAME = "MJ_BizApps_Forms: Form Distributions";
+/** Inputs the runner needs from the saved distribution record. */
+export interface ProvisionContext extends DistributionProvisioningState {
+    /** The distribution's primary key (the scoped resource id). */
+    distributionId: string;
+}
+/** The persistable artifacts of a successful mint, written back onto the distribution. */
+export interface MintedLink {
+    /** The `MJ: Magic Link Invites` row ID → `FormDistribution.MagicLinkInviteID`. */
+    inviteId: string;
+    /**
+     * The raw redeemable token → `FormDistribution.PublicLinkToken`. May be absent
+     * if a (non-default) minter does not surface it; the invite is still linked.
+     */
+    rawToken?: string;
+}
+/** Outcome of a provisioning run (for logging/assertions; never throws). */
+export interface ProvisionOutcome {
+    /** What happened: minted+stored, or why it was skipped. */
+    result: 'minted' | 'skipped-decision' | 'skipped-no-minter' | 'skipped-no-user' | 'skipped-minter' | 'mint-failed' | 'store-failed';
+    /** The minted invite id, when `result==='minted'`. */
+    inviteId?: string;
+}
+/**
+ * Run the provisioning decision and, when warranted, mint + persist the invite.
+ * Fail-soft throughout: a missing minter / user, a minter skip, or a mint/store
+ * failure is logged and returned — never thrown — so the caller's save stands.
+ *
+ * @param ctx          current distribution state
+ * @param config       provisioning configuration
+ * @param minter       the registered minter, or `undefined` when none is registered
+ * @param contextUser  the internal staff user saving the record (the invite issuer)
+ * @param storeMintResult  persists the minted invite id + raw public-link token back
+ *                         onto the record in a single write; returns its save success
+ */
+export declare function runProvisioning(ctx: ProvisionContext, config: MagicLinkProvisioningConfig, minter: IAnonymousMagicLinkMinter | undefined, contextUser: UserInfo | undefined, storeMintResult: (mint: MintedLink) => Promise<boolean>): Promise<ProvisionOutcome>;
+//# sourceMappingURL=provision-runner.d.ts.map

package/dist/magic-link/provision-runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provision-runner.d.ts","sourceRoot":"","sources":["../../src/magic-link/provision-runner.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAuB,KAAK,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAC1E,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,aAAa,CAAC;AAC/D,OAAO,EAAqC,KAAK,6BAA6B,EAAE,MAAM,4BAA4B,CAAC;AACnH,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,aAAa,CAAC;AAE7D,qFAAqF;AACrF,eAAO,MAAM,wBAAwB,yCAAyC,CAAC;AAE/E,kEAAkE;AAClE,MAAM,WAAW,gBAAiB,SAAQ,6BAA6B;IACrE,+DAA+D;IAC/D,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,0FAA0F;AAC1F,MAAM,WAAW,UAAU;IACzB,kFAAkF;IAClF,QAAQ,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,4EAA4E;AAC5E,MAAM,WAAW,gBAAgB;IAC/B,2DAA2D;IAC3D,MAAM,EAAE,QAAQ,GAAG,kBAAkB,GAAG,mBAAmB,GAAG,iBAAiB,GAAG,gBAAgB,GAAG,aAAa,GAAG,cAAc,CAAC;IACpI,sDAAsD;IACtD,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,eAAe,CACnC,GAAG,EAAE,gBAAgB,EACrB,MAAM,EAAE,2BAA2B,EACnC,MAAM,EAAE,yBAAyB,GAAG,SAAS,EAC7C,WAAW,EAAE,QAAQ,GAAG,SAAS,EACjC,eAAe,EAAE,CAAC,IAAI,EAAE,UAAU,KAAK,OAAO,CAAC,OAAO,CAAC,GACtD,OAAO,CAAC,gBAAgB,CAAC,CA2D3B"}

package/dist/magic-link/provision-runner.js

@@ -0,0 +1,66 @@
+/**
+ * Orchestration for distribution magic-link provisioning, decoupled from the
+ * BaseEntity so it is unit-testable without a DB or entity metadata. The entity
+ * hook (`FormDistributionEntityServer`) is a thin adapter that supplies this
+ * runner with the distribution's current state, the context user, and a
+ * persist-callback that writes the minted invite id back onto the record.
+ */
+import { LogError, LogStatus } from '@memberjunction/core';
+import { decideProvisioning, resolveExpiry } from './provisioning-decision.js';
+/** Entity name of the distribution itself — the resource the invite is scoped to. */
+export const DISTRIBUTION_ENTITY_NAME = 'MJ_BizApps_Forms: Form Distributions';
+/**
+ * Run the provisioning decision and, when warranted, mint + persist the invite.
+ * Fail-soft throughout: a missing minter / user, a minter skip, or a mint/store
+ * failure is logged and returned — never thrown — so the caller's save stands.
+ *
+ * @param ctx          current distribution state
+ * @param config       provisioning configuration
+ * @param minter       the registered minter, or `undefined` when none is registered
+ * @param contextUser  the internal staff user saving the record (the invite issuer)
+ * @param storeMintResult  persists the minted invite id + raw public-link token back
+ *                         onto the record in a single write; returns its save success
+ */
+export async function runProvisioning(ctx, config, minter, contextUser, storeMintResult) {
+    const decision = decideProvisioning(ctx, config);
+    if (!decision.shouldMint) {
+        return { result: 'skipped-decision' };
+    }
+    if (!minter) {
+        LogStatus(`[FormDistribution] Anonymous links unavailable for distribution ${ctx.distributionId}: ` +
+            `no magic-link minter registered. Enable core 'magicLink' (with role '${config.roleName}' grantable) ` +
+            `to provision public form links. MagicLinkInviteID left null; the distribution was saved.`);
+        return { result: 'skipped-no-minter' };
+    }
+    if (!contextUser) {
+        LogError(`[FormDistribution] Cannot mint magic link for distribution ${ctx.distributionId}: no context user.`);
+        return { result: 'skipped-no-user' };
+    }
+    const mint = await minter.MintAnonymousInvite({
+        applicationName: config.applicationName,
+        roleName: config.roleName,
+        resourceTypeName: DISTRIBUTION_ENTITY_NAME,
+        resourceId: ctx.distributionId,
+        maxUses: config.defaultMaxUses,
+        expiresAt: resolveExpiry(ctx.closeAt, config.fixedExpiryHours, new Date()),
+    }, contextUser);
+    if (mint.skipped) {
+        LogStatus(`[FormDistribution] Anonymous link skipped for distribution ${ctx.distributionId}: ` +
+            `${mint.message ?? 'magic-link not enabled on this host'}. MagicLinkInviteID left null; the distribution was saved.`);
+        return { result: 'skipped-minter' };
+    }
+    if (!mint.success || !mint.inviteId) {
+        LogError(`[FormDistribution] Magic-link mint failed for distribution ${ctx.distributionId}: ` +
+            `${mint.message ?? 'unknown error'}. MagicLinkInviteID left null.`);
+        return { result: 'mint-failed' };
+    }
+    const stored = await storeMintResult({ inviteId: mint.inviteId, rawToken: mint.rawToken });
+    if (!stored) {
+        LogError(`[FormDistribution] Minted invite ${mint.inviteId} but failed to store it on distribution ${ctx.distributionId}. ` +
+            `The invite exists but is not linked.`);
+        return { result: 'store-failed', inviteId: mint.inviteId };
+    }
+    LogStatus(`[FormDistribution] Provisioned anonymous magic-link invite ${mint.inviteId} for distribution ${ctx.distributionId}.`);
+    return { result: 'minted', inviteId: mint.inviteId };
+}
+//# sourceMappingURL=provision-runner.js.map

package/dist/magic-link/provision-runner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provision-runner.js","sourceRoot":"","sources":["../../src/magic-link/provision-runner.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAiB,MAAM,sBAAsB,CAAC;AAE1E,OAAO,EAAE,kBAAkB,EAAE,aAAa,EAAsC,MAAM,4BAA4B,CAAC;AAGnH,qFAAqF;AACrF,MAAM,CAAC,MAAM,wBAAwB,GAAG,sCAAsC,CAAC;AA2B/E;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,GAAqB,EACrB,MAAmC,EACnC,MAA6C,EAC7C,WAAiC,EACjC,eAAuD;IAEvD,MAAM,QAAQ,GAAG,kBAAkB,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;IACjD,IAAI,CAAC,QAAQ,CAAC,UAAU,EAAE,CAAC;QACzB,OAAO,EAAE,MAAM,EAAE,kBAAkB,EAAE,CAAC;IACxC,CAAC;IAED,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,SAAS,CACP,mEAAmE,GAAG,CAAC,cAAc,IAAI;YACvF,wEAAwE,MAAM,CAAC,QAAQ,eAAe;YACtG,0FAA0F,CAC7F,CAAC;QACF,OAAO,EAAE,MAAM,EAAE,mBAAmB,EAAE,CAAC;IACzC,CAAC;IAED,IAAI,CAAC,WAAW,EAAE,CAAC;QACjB,QAAQ,CAAC,8DAA8D,GAAG,CAAC,cAAc,oBAAoB,CAAC,CAAC;QAC/G,OAAO,EAAE,MAAM,EAAE,iBAAiB,EAAE,CAAC;IACvC,CAAC;IAED,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,mBAAmB,CAC3C;QACE,eAAe,EAAE,MAAM,CAAC,eAAe;QACvC,QAAQ,EAAE,MAAM,CAAC,QAAQ;QACzB,gBAAgB,EAAE,wBAAwB;QAC1C,UAAU,EAAE,GAAG,CAAC,cAAc;QAC9B,OAAO,EAAE,MAAM,CAAC,cAAc;QAC9B,SAAS,EAAE,aAAa,CAAC,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,gBAAgB,EAAE,IAAI,IAAI,EAAE,CAAC;KAC3E,EACD,WAAW,CACZ,CAAC;IAEF,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;QACjB,SAAS,CACP,8DAA8D,GAAG,CAAC,cAAc,IAAI;YAClF,GAAG,IAAI,CAAC,OAAO,IAAI,qCAAqC,4DAA4D,CACvH,CAAC;QACF,OAAO,EAAE,MAAM,EAAE,gBAAgB,EAAE,CAAC;IACtC,CAAC;IAED,IAAI,CAAC,IAAI,CAAC,OAAO,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC;QACpC,QAAQ,CACN,8DAA8D,GAAG,CAAC,cAAc,IAAI;YAClF,GAAG,IAAI,CAAC,OAAO,IAAI,eAAe,gCAAgC,CACrE,CAAC;QACF,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,CAAC;IACnC,CAAC;IAED,MAAM,MAAM,GAAG,MAAM,eAAe,CAAC,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC;IAC3F,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,QAAQ,CACN,oCAAoC,IAAI,CAAC,QAAQ,2CAA2C,GAAG,CAAC,cAAc,IAAI;YAChH,sCAAsC,CACzC,CAAC;QACF,OAAO,EAAE,MAAM,EAAE,cAAc,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,CAAC;IAC7D,CAAC;IAED,SAAS,CAAC,8DAA8D,IAAI,CAAC,QAAQ,qBAAqB,GAAG,CAAC,cAAc,GAAG,CAAC,CAAC;IACjI,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,CAAC;AACvD,CAAC"}

package/dist/magic-link/provisioning-decision.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Pure decision logic for distribution magic-link provisioning — no DB, no MJ
+ * runtime, deterministic given its inputs, unit-testable with plain assertions.
+ * The entity hook is the imperative shell that wires these decisions to the
+ * minter and the entity record.
+ */
+import type { MagicLinkProvisioningConfig, DistributionChannelType } from './config.js';
+/** The subset of `FormDistribution` state the provisioning decision needs. */
+export interface DistributionProvisioningState {
+    channelType: DistributionChannelType;
+    status: 'Active' | 'Closed' | 'Draft';
+    isActive: boolean;
+    /** Current value of `MagicLinkInviteID` (null/empty when not yet minted). */
+    magicLinkInviteId: string | null;
+    /** The distribution's `CloseAt`, if set — drives expiry when no fixed expiry is configured. */
+    closeAt: Date | null;
+}
+/** Why provisioning is or isn't warranted for the current save. */
+export interface ProvisioningDecision {
+    /** True when the hook should attempt to mint and store an invite. */
+    shouldMint: boolean;
+    /** Diagnostic reason (for the not-minting case), useful in logs/tests. */
+    reason: 'mint' | 'already-minted' | 'channel-not-linkable' | 'not-active-public-channel';
+}
+/**
+ * Decide whether to mint a magic-link invite for this distribution save.
+ *
+ * Idempotent + scoped to active public/anonymous channels:
+ *  - Skip when an invite already exists (`MagicLinkInviteID` set) — never re-mint.
+ *  - Skip when the channel type is not in the configured linkable set (e.g. Email).
+ *  - Skip unless the distribution is an active public/anonymous channel
+ *    (`Status='Active'` AND `IsActive=true`) — a Draft/Closed/disabled distribution
+ *    gets a link only once it actually goes live.
+ */
+export declare function decideProvisioning(state: DistributionProvisioningState, config: MagicLinkProvisioningConfig): ProvisioningDecision;
+/**
+ * Resolve the invite's hard expiry for this distribution.
+ *
+ * Policy: a configured fixed expiry (hours-from-now) wins; otherwise the
+ * distribution's `CloseAt` (when set) is the expiry; otherwise no expiry
+ * (`null`) — an effectively-permanent public link, matching a high `maxUses`.
+ */
+export declare function resolveExpiry(closeAt: Date | null, fixedExpiryHours: number | undefined, now: Date): Date | null;
+//# sourceMappingURL=provisioning-decision.d.ts.map

package/dist/magic-link/provisioning-decision.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provisioning-decision.d.ts","sourceRoot":"","sources":["../../src/magic-link/provisioning-decision.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,2BAA2B,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAExF,8EAA8E;AAC9E,MAAM,WAAW,6BAA6B;IAC5C,WAAW,EAAE,uBAAuB,CAAC;IACrC,MAAM,EAAE,QAAQ,GAAG,QAAQ,GAAG,OAAO,CAAC;IACtC,QAAQ,EAAE,OAAO,CAAC;IAClB,6EAA6E;IAC7E,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,+FAA+F;IAC/F,OAAO,EAAE,IAAI,GAAG,IAAI,CAAC;CACtB;AAED,mEAAmE;AACnE,MAAM,WAAW,oBAAoB;IACnC,qEAAqE;IACrE,UAAU,EAAE,OAAO,CAAC;IACpB,0EAA0E;IAC1E,MAAM,EACF,MAAM,GACN,gBAAgB,GAChB,sBAAsB,GACtB,2BAA2B,CAAC;CACjC;AAOD;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,6BAA6B,EACpC,MAAM,EAAE,2BAA2B,GAClC,oBAAoB,CAWtB;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,IAAI,GAAG,IAAI,EACpB,gBAAgB,EAAE,MAAM,GAAG,SAAS,EACpC,GAAG,EAAE,IAAI,GACR,IAAI,GAAG,IAAI,CAQb"}

package/dist/magic-link/provisioning-decision.js

@@ -0,0 +1,43 @@
+/** Non-empty (trimmed) string guard for the existing invite id. */
+function hasInviteId(id) {
+    return typeof id === 'string' && id.trim().length > 0;
+}
+/**
+ * Decide whether to mint a magic-link invite for this distribution save.
+ *
+ * Idempotent + scoped to active public/anonymous channels:
+ *  - Skip when an invite already exists (`MagicLinkInviteID` set) — never re-mint.
+ *  - Skip when the channel type is not in the configured linkable set (e.g. Email).
+ *  - Skip unless the distribution is an active public/anonymous channel
+ *    (`Status='Active'` AND `IsActive=true`) — a Draft/Closed/disabled distribution
+ *    gets a link only once it actually goes live.
+ */
+export function decideProvisioning(state, config) {
+    if (hasInviteId(state.magicLinkInviteId)) {
+        return { shouldMint: false, reason: 'already-minted' };
+    }
+    if (!config.linkableChannels.has(state.channelType)) {
+        return { shouldMint: false, reason: 'channel-not-linkable' };
+    }
+    if (state.status !== 'Active' || !state.isActive) {
+        return { shouldMint: false, reason: 'not-active-public-channel' };
+    }
+    return { shouldMint: true, reason: 'mint' };
+}
+/**
+ * Resolve the invite's hard expiry for this distribution.
+ *
+ * Policy: a configured fixed expiry (hours-from-now) wins; otherwise the
+ * distribution's `CloseAt` (when set) is the expiry; otherwise no expiry
+ * (`null`) — an effectively-permanent public link, matching a high `maxUses`.
+ */
+export function resolveExpiry(closeAt, fixedExpiryHours, now) {
+    if (typeof fixedExpiryHours === 'number' && fixedExpiryHours > 0) {
+        return new Date(now.getTime() + fixedExpiryHours * 3600 * 1000);
+    }
+    if (closeAt instanceof Date && !Number.isNaN(closeAt.getTime())) {
+        return closeAt;
+    }
+    return null;
+}
+//# sourceMappingURL=provisioning-decision.js.map

package/dist/magic-link/provisioning-decision.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provisioning-decision.js","sourceRoot":"","sources":["../../src/magic-link/provisioning-decision.ts"],"names":[],"mappings":"AA+BA,mEAAmE;AACnE,SAAS,WAAW,CAAC,EAAiB;IACpC,OAAO,OAAO,EAAE,KAAK,QAAQ,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC;AACxD,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,kBAAkB,CAChC,KAAoC,EACpC,MAAmC;IAEnC,IAAI,WAAW,CAAC,KAAK,CAAC,iBAAiB,CAAC,EAAE,CAAC;QACzC,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,EAAE,gBAAgB,EAAE,CAAC;IACzD,CAAC;IACD,IAAI,CAAC,MAAM,CAAC,gBAAgB,CAAC,GAAG,CAAC,KAAK,CAAC,WAAW,CAAC,EAAE,CAAC;QACpD,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,EAAE,sBAAsB,EAAE,CAAC;IAC/D,CAAC;IACD,IAAI,KAAK,CAAC,MAAM,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC;QACjD,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,EAAE,2BAA2B,EAAE,CAAC;IACpE,CAAC;IACD,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;AAC9C,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAC3B,OAAoB,EACpB,gBAAoC,EACpC,GAAS;IAET,IAAI,OAAO,gBAAgB,KAAK,QAAQ,IAAI,gBAAgB,GAAG,CAAC,EAAE,CAAC;QACjE,OAAO,IAAI,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,GAAG,gBAAgB,GAAG,IAAI,GAAG,IAAI,CAAC,CAAC;IAClE,CAAC;IACD,IAAI,OAAO,YAAY,IAAI,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,EAAE,CAAC;QAChE,OAAO,OAAO,CAAC;IACjB,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/package.json

@@ -1,8 +1,37 @@
 {
   "name": "@mj-biz-apps/forms-core-entities-server",
-  "version": "0.0.0",
-  "description": "Placeholder — reserving name for MJ Forms. Real release lands via CI.",
-  "license": "MIT",
-  "repository": { "type": "git", "url": "git+https://github.com/MemberJunction/bizapps-forms.git" },
-  "publishConfig": { "access": "public" }
+  "type": "module",
+  "version": "0.2.0",
+  "description": "Server-side entity subclasses for MJ Forms — lifecycle hooks (validation, hardening, cross-record invariants) that run only on the server.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "/dist"
+  ],
+  "scripts": {
+    "build": "tsc && tsc-alias -f",
+    "test": "vitest run"
+  },
+  "author": "MemberJunction.com",
+  "license": "ISC",
+  "devDependencies": {
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4"
+  },
+  "dependencies": {
+    "@mj-biz-apps/forms-entities": "0.2.0"
+  },
+  "peerDependencies": {
+    "@memberjunction/core": "^5.43.0",
+    "@memberjunction/core-entities": "^5.43.0",
+    "@memberjunction/global": "^5.43.0",
+    "@memberjunction/sqlserver-dataprovider": "^5.43.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/MemberJunction/bizapps-forms"
+  }
 }

package/README.md

@@ -1,3 +0,0 @@
-# @mj-biz-apps/forms-core-entities-server
-
-Placeholder reserving the package name for [MJ Forms](https://github.com/MemberJunction/bizapps-forms). The first real release is published by CI.