@mj-biz-apps/orders-core-entities-server 0.0.1 → 5.2.0

package/dist/EntitlementBehavior.js

@@ -0,0 +1,330 @@
+/**
+ * What a purchase grants, and for how long — the arithmetic, with no database in sight.
+ *
+ * A `ProductEntitlement` is a TEMPLATE: this product confers this feature, access level, or resource
+ * quantity. An `EntitlementGrant` is the INSTANCE created when somebody buys it, carrying a
+ * beneficiary and a validity window. This module decides what that instance should look like.
+ *
+ * THREE SETTINGS, ONE WALK (D76). Timing, quantity and validity are all configurable per deployment,
+ * and all three resolve down the SAME chain taxability uses:
+ *
+ *     product → its category → that category's ancestors → the product type
+ *
+ * Nullable at product and category so "ask my parent" is sayable; NOT NULL at the type so the walk
+ * always terminates with a real answer. Sharing the chain is deliberate rather than tidy: anyone who
+ * understands how taxability resolves already understands this, and the two cannot drift into
+ * disagreeing about what "the product's category tree" means.
+ *
+ * WHY VALIDITY IS DIFFERENT FROM THE OTHER TWO. It is read from the `ProductEntitlement` FIRST and
+ * from the walk only when the template is silent, because one product can grant two entitlements with
+ * different windows. A course might give perpetual access to the downloadable materials and ninety
+ * days in the discussion forum. A policy resolved purely from the product could not say that.
+ *
+ * THE NON-SUBSCRIPTION CASES ARE THE INTERESTING ONES. It is tempting to assume access follows a
+ * subscription term, because that is the case with the most moving parts. But the commonest grants
+ * have nothing to do with subscriptions at all: a digital download is good forever, and a ticket to
+ * an online event is good for the length of the event and not a minute longer.
+ *
+ * CONNECTS TO:
+ *   SERVER: ./EntitlementEngine.ts (the lookups and the writes)
+ *   CALLER: OrderEntityServer (grants are created inside the booking transaction)
+ *   MIRROR: ./TaxResolver.ts — the same walk, for the same reason
+ *   DOC:    plans/archive/bizapps-orders-master.md D27, D76
+ */
+/**
+ * Walk the chain for all three settings at once.
+ *
+ * ONE walk rather than three, because they resolve identically and a caller that walked separately
+ * would do the same lookups three times and could be given three different category chains.
+ *
+ * `entitlement` is consulted for VALIDITY ONLY — see the module header. Timing and quantity are
+ * properties of the purchase, not of the individual thing granted: it would make no sense for one
+ * entitlement on a line to appear at confirm and another to wait for payment.
+ */
+export function ResolveEntitlementPolicy(product, 
+/** NEAREST FIRST: the product's own category, then its parent, up to the root. */
+categoryChain, type, entitlement) {
+    const walk = (key, typeValue) => {
+        const own = product[key];
+        if (own != null)
+            return { value: own, level: 'Product' };
+        for (const level of categoryChain) {
+            const v = level[key];
+            if (v != null)
+                return { value: v, level: 'ProductCategory' };
+        }
+        return { value: typeValue, level: 'ProductType' };
+    };
+    const timing = walk('EntitlementGrantTiming', type.DefaultEntitlementGrantTiming);
+    const quantity = walk('EntitlementQuantityMode', type.DefaultEntitlementQuantityMode);
+    // The template wins on validity, and only on validity.
+    const fromTemplate = entitlement?.ValidityMode ?? null;
+    const validity = fromTemplate != null
+        ? { value: fromTemplate, level: 'ProductEntitlement' }
+        : walk('EntitlementValidityMode', type.DefaultEntitlementValidityMode);
+    return {
+        GrantTiming: timing.value,
+        QuantityMode: quantity.value,
+        ValidityMode: validity.value,
+        DecidedAt: {
+            GrantTiming: timing.level,
+            QuantityMode: quantity.level,
+            ValidityMode: validity.level,
+        },
+    };
+}
+/**
+ * How much of the entitlement this line grants.
+ *
+ * `PerUnit` multiplies, so three 5-seat packs give fifteen seats — which is what somebody buying
+ * three packs expects. `Flat` ignores the line quantity entirely, for entitlements that are not
+ * countable: "access to the member portal" does not become three portals.
+ *
+ * ROUNDED UP, and only ever up. A prorated subscription line carries a fractional quantity (0.5833
+ * for a short first period), and 0.5833 × 5 seats is 2.9165. Rounding down hands the customer two
+ * seats for a five-seat product and generates a support ticket; rounding up hands them three and
+ * generates nothing. Under-granting is the expensive direction, exactly as under-collecting is with
+ * tax, and for the same reason: the customer notices.
+ *
+ * A null template quantity means the entitlement is not a countable thing (a Feature or AccessLevel
+ * rather than a ResourceQuantity), and stays null rather than becoming zero — zero would read as
+ * "granted none of it".
+ */
+export function ResolveGrantQuantity(templateQuantity, lineQuantity, mode) {
+    if (templateQuantity == null)
+        return null;
+    if (mode === 'Flat')
+        return templateQuantity;
+    const scaled = templateQuantity * Math.abs(lineQuantity);
+    return Math.ceil(Math.round(scaled * 1e6) / 1e6);
+}
+const HOUR = 60 * 60 * 1000;
+const DAY = 24 * HOUR;
+/**
+ * Turn a validity mode plus its context into an actual window.
+ *
+ * FALLS BACK RATHER THAN THROWING when a mode's own inputs are missing, and records what it actually
+ * applied. A ticket whose product has no event dates should not fail the customer's order — but the
+ * grant must not silently claim to be an event window either, so `ModeApplied` says `Perpetual` and
+ * an auditor can see the mode was requested and could not be honoured.
+ *
+ * The one thing it will not do is produce a window that ends before it starts. An event whose end
+ * date precedes its start, or a lag that somehow lands behind the lead, yields a window ending at its
+ * own start — an instantaneous grant, which reads as "nothing was granted" and is at least honest,
+ * rather than a negative window the database CHECK would reject at insert time with an error naming
+ * neither the product nor the event.
+ */
+export function ResolveValidityWindow(mode, ctx) {
+    const clamp = (from, to) => ({
+        ValidFrom: from,
+        ValidTo: to != null && to.getTime() < from.getTime() ? new Date(from.getTime()) : to,
+        ModeApplied: mode,
+    });
+    switch (mode) {
+        case 'Perpetual':
+            // A digital download. Good forever, and that is a fact rather than an omission.
+            return { ValidFrom: ctx.GrantedOn, ValidTo: null, ModeApplied: 'Perpetual' };
+        case 'FixedDuration': {
+            const days = ctx.DurationDays ?? 0;
+            if (days <= 0) {
+                return { ValidFrom: ctx.GrantedOn, ValidTo: null, ModeApplied: 'Perpetual' };
+            }
+            return clamp(ctx.GrantedOn, new Date(ctx.GrantedOn.getTime() + days * DAY));
+        }
+        case 'EventWindow': {
+            if (!ctx.EventStartsAt || !ctx.EventEndsAt) {
+                return { ValidFrom: ctx.GrantedOn, ValidTo: null, ModeApplied: 'Perpetual' };
+            }
+            // Lead and lag are separate decisions, which is why they are separate columns: opening
+            // the stream an hour early is a courtesy, and leaving the recording up for a day
+            // afterwards is a different courtesy with different cost.
+            const lead = (ctx.AccessLeadHours ?? 0) * HOUR;
+            const lag = (ctx.AccessLagHours ?? 0) * HOUR;
+            return clamp(new Date(ctx.EventStartsAt.getTime() - lead), new Date(ctx.EventEndsAt.getTime() + lag));
+        }
+        case 'SubscriptionTerm': {
+            if (!ctx.TermStartDate || !ctx.TermEndDate) {
+                // Asked to follow a term that does not exist — a non-subscription product configured
+                // as though it were one. Perpetual is the safe read: the customer bought something.
+                return { ValidFrom: ctx.GrantedOn, ValidTo: null, ModeApplied: 'Perpetual' };
+            }
+            return clamp(ctx.TermStartDate, ctx.TermEndDate);
+        }
+    }
+}
+/**
+ * Should the grant be ACTIVE yet, given when access is supposed to begin?
+ *
+ * The grant row is written at confirm either way — downstream apps poll grants (D27), and a grant
+ * that does not exist until payment clears cannot be seen coming. What timing changes is the STATUS:
+ *
+ *   OnConfirm     Active immediately. A confirmed order is a claim on the seller.
+ *   OnPaidInFull  Suspended until the order's balance reaches zero. Access follows cash.
+ *   OnActivation  Suspended until something explicitly activates it. Note that nothing does yet —
+ *                 this exists because it was asked for, and a deployment choosing it is choosing to
+ *                 grant nothing until it builds the caller.
+ *
+ * `Suspended` rather than a missing row, and rather than `Revoked`: revoked means somebody took it
+ * away, which is a different fact that an access dispute turns on.
+ */
+export function InitialGrantStatus(timing, order) {
+    if (timing === 'OnConfirm')
+        return 'Active';
+    if (timing === 'OnActivation')
+        return 'Suspended';
+    // OnPaidInFull. A zero-value order is paid by definition — a free line should not leave the
+    // customer waiting for a payment that will never arrive.
+    const gross = Number(order.TotalGross ?? 0);
+    if (gross <= 0)
+        return 'Active';
+    return Number(order.Balance ?? gross) <= 0 ? 'Active' : 'Suspended';
+}
+/**
+ * How much of a grant survives a partial return.
+ *
+ * A customer who bought five seats and sent two back keeps three. Returning everything revokes the
+ * grant outright rather than leaving a zero-quantity row, because zero is indistinguishable from a
+ * Feature grant that never had a quantity.
+ */
+export function ReduceGrantForReturn(grantQuantity, originalLineQuantity, returnedQuantity) {
+    const returned = Math.abs(returnedQuantity);
+    const original = Math.abs(originalLineQuantity);
+    if (original <= 0 || returned >= original)
+        return { Quantity: grantQuantity, Revoke: true };
+    if (grantQuantity == null) {
+        // A Feature or AccessLevel: not countable, so a partial return cannot partially remove it.
+        // The customer still holds some of the thing that conferred it, so the grant stands.
+        return { Quantity: null, Revoke: false };
+    }
+    const remaining = grantQuantity * ((original - returned) / original);
+    // Rounded UP, for the same reason ResolveGrantQuantity rounds up: taking away a seat the customer
+    // still paid for is worse than leaving one they did not.
+    return { Quantity: Math.ceil(Math.round(remaining * 1e6) / 1e6), Revoke: false };
+}
+/** Subscription statuses that still confer access. Anything else is inactive. */
+const ACCESSING_SUB_STATUS = new Set(['Active', 'Trialing']);
+/**
+ * Is this grant in force at `asOf`?
+ *
+ * ONE function, because a second “is this in force” will drift from the first — that failure
+ * has already bitten this codebase twice. Bounds are inclusive: access holds at the exact
+ * `ValidFrom` / `ValidTo` / cancel `EndDate` instant.
+ *
+ * Cancelled subscriptions are the interesting case. The grant's `ValidTo` is the original term
+ * end, which is a LIE after an immediate cancel: access-through is `subscription.EndDate`
+ * (grace included). Grace can also EXTEND past `ValidTo`. Either way, `EndDate` is the bound
+ * once the sub is `Canceled`. Paused/Migrated refuse immediately — they have no grace story.
+ */
+export function EvaluateGrantAccess(grant, asOf, subscription, term) {
+    const denied = (Decision) => ({
+        HasAccess: false,
+        Decision,
+        ValidFrom: grant.ValidFrom,
+        ValidTo: grant.ValidTo,
+    });
+    const granted = () => ({
+        HasAccess: true,
+        Decision: 'Granted',
+        ValidFrom: grant.ValidFrom,
+        ValidTo: grant.ValidTo,
+    });
+    if (grant.Status === 'Revoked')
+        return denied('Revoked');
+    if (grant.Status === 'Suspended')
+        return denied('Suspended');
+    if (grant.Status === 'Expired')
+        return denied('Expired');
+    if (grant.Status !== 'Active')
+        return denied('NoGrant');
+    if (grant.ValidFrom && asOf.getTime() < grant.ValidFrom.getTime()) {
+        return denied('NotYetValid');
+    }
+    // Linked rows we could not load: fail closed rather than grant on a guess.
+    if (grant.LinkedToSubscription && !subscription)
+        return denied('SubscriptionInactive');
+    if (grant.LinkedToTerm && !term)
+        return denied('SubscriptionInactive');
+    if (subscription && !ACCESSING_SUB_STATUS.has(subscription.Status)) {
+        if (subscription.Status === 'Canceled') {
+            if (!subscription.EndDate || asOf.getTime() > subscription.EndDate.getTime()) {
+                return {
+                    HasAccess: false,
+                    Decision: 'SubscriptionInactive',
+                    ValidFrom: grant.ValidFrom,
+                    ValidTo: subscription.EndDate,
+                };
+            }
+            // Inside access-through: EndDate is the operative bound — it can cut the original
+            // ValidTo short or extend it (grace). Report that, so CacheUntil and "access
+            // through {ValidTo}" both tell the truth.
+            return {
+                HasAccess: true,
+                Decision: 'Granted',
+                ValidFrom: grant.ValidFrom,
+                ValidTo: subscription.EndDate,
+            };
+        }
+        return denied('SubscriptionInactive');
+    }
+    if (grant.ValidTo && asOf.getTime() > grant.ValidTo.getTime()) {
+        return denied('Expired');
+    }
+    if (term) {
+        if (asOf.getTime() < term.StartDate.getTime())
+            return denied('NotYetValid');
+        if (asOf.getTime() > term.EndDate.getTime())
+            return denied('SubscriptionInactive');
+    }
+    return granted();
+}
+/** Lower rank wins among denials — “not yet” is a more useful screen than “an old grant was revoked”. */
+const DENIAL_RANK = {
+    Granted: 0,
+    NotYetValid: 1,
+    Suspended: 2,
+    SubscriptionInactive: 3,
+    Expired: 4,
+    Revoked: 5,
+    NoGrant: 6,
+};
+/**
+ * One answer from many grants for the same Code. A Granted perpetual beats a Granted with an
+ * end; among denials the most useful reason wins, not the most recent row.
+ */
+export function PickWinningAccess(results) {
+    if (!results.length)
+        return null;
+    const granted = results.filter((r) => r.HasAccess);
+    if (granted.length) {
+        return granted.reduce((best, r) => {
+            if (best.ValidTo == null)
+                return best;
+            if (r.ValidTo == null)
+                return r;
+            return r.ValidTo.getTime() > best.ValidTo.getTime() ? r : best;
+        });
+    }
+    return results.reduce((best, r) => DENIAL_RANK[r.Decision] < DENIAL_RANK[best.Decision] ? r : best);
+}
+/** Default CacheUntil cap for a check answer. Short so a revoke is felt quickly. */
+export const ENTITLEMENT_CHECK_TTL_MS = 60_000;
+/**
+ * When the caller may reuse this answer. Never past `ValidTo` on a grant that is in force —
+ * caching a Granted past its own end is how paid content stays open after the window closed.
+ */
+export function CacheUntilFor(evaluatedAt, validTo, hasAccess) {
+    const cap = new Date(evaluatedAt.getTime() + ENTITLEMENT_CHECK_TTL_MS);
+    if (hasAccess && validTo != null && validTo.getTime() < cap.getTime()) {
+        return new Date(validTo.getTime());
+    }
+    return cap;
+}
+/**
+ * After `Orders.CancelSubscription`, stored grant Status is a lie unless we revoke when
+ * access has already ended. Grace (`AccessThroughDate` in the future) leaves the rows
+ * standing — the evaluator honours `subscription.EndDate`.
+ */
+export function ShouldRevokeGrantsOnCancel(accessThroughDate, now) {
+    return now.getTime() > accessThroughDate.getTime();
+}
+//# sourceMappingURL=EntitlementBehavior.js.map

package/dist/EntitlementBehavior.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"EntitlementBehavior.js","sourceRoot":"","sources":["../src/EntitlementBehavior.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAwCH;;;;;;;;;GASG;AACH,MAAM,UAAU,wBAAwB,CACpC,OAAgC;AAChC,kFAAkF;AAClF,aAAoC,EACpC,IAAwB,EACxB,WAA0D;IAE1D,MAAM,IAAI,GAAG,CACT,GAAM,EACN,SAAY,EACoB,EAAE;QAClC,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAwB,CAAC;QAChD,IAAI,GAAG,IAAI,IAAI;YAAE,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC;QACzD,KAAK,MAAM,KAAK,IAAI,aAAa,EAAE,CAAC;YAChC,MAAM,CAAC,GAAG,KAAK,CAAC,GAAG,CAAwB,CAAC;YAC5C,IAAI,CAAC,IAAI,IAAI;gBAAE,OAAO,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE,iBAAiB,EAAE,CAAC;QACjE,CAAC;QACD,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,aAAa,EAAE,CAAC;IACtD,CAAC,CAAC;IAEF,MAAM,MAAM,GAAG,IAAI,CAAC,wBAAwB,EAAE,IAAI,CAAC,6BAA6B,CAAC,CAAC;IAClF,MAAM,QAAQ,GAAG,IAAI,CAAC,yBAAyB,EAAE,IAAI,CAAC,8BAA8B,CAAC,CAAC;IAEtF,uDAAuD;IACvD,MAAM,YAAY,GAAG,WAAW,EAAE,YAAY,IAAI,IAAI,CAAC;IACvD,MAAM,QAAQ,GAAG,YAAY,IAAI,IAAI;QACjC,CAAC,CAAC,EAAE,KAAK,EAAE,YAAY,EAAE,KAAK,EAAE,oBAAmC,EAAE;QACrE,CAAC,CAAC,IAAI,CAAC,yBAAyB,EAAE,IAAI,CAAC,8BAA8B,CAAC,CAAC;IAE3E,OAAO;QACH,WAAW,EAAE,MAAM,CAAC,KAAK;QACzB,YAAY,EAAE,QAAQ,CAAC,KAAK;QAC5B,YAAY,EAAE,QAAQ,CAAC,KAAK;QAC5B,SAAS,EAAE;YACP,WAAW,EAAE,MAAM,CAAC,KAAK;YACzB,YAAY,EAAE,QAAQ,CAAC,KAAK;YAC5B,YAAY,EAAE,QAAQ,CAAC,KAAK;SAC/B;KACJ,CAAC;AACN,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,oBAAoB,CAChC,gBAA+B,EAC/B,YAAoB,EACpB,IAAkB;IAElB,IAAI,gBAAgB,IAAI,IAAI;QAAE,OAAO,IAAI,CAAC;IAC1C,IAAI,IAAI,KAAK,MAAM;QAAE,OAAO,gBAAgB,CAAC;IAC7C,MAAM,MAAM,GAAG,gBAAgB,GAAG,IAAI,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;IACzD,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,GAAG,CAAC,GAAG,GAAG,CAAC,CAAC;AACrD,CAAC;AAyBD,MAAM,IAAI,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAC5B,MAAM,GAAG,GAAG,EAAE,GAAG,IAAI,CAAC;AAEtB;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,qBAAqB,CAAC,IAAkB,EAAE,GAAoB;IAC1E,MAAM,KAAK,GAAG,CAAC,IAAU,EAAE,EAAe,EAAoB,EAAE,CAAC,CAAC;QAC9D,SAAS,EAAE,IAAI;QACf,OAAO,EAAE,EAAE,IAAI,IAAI,IAAI,EAAE,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE;QACpF,WAAW,EAAE,IAAI;KACpB,CAAC,CAAC;IAEH,QAAQ,IAAI,EAAE,CAAC;QACX,KAAK,WAAW;YACZ,gFAAgF;YAChF,OAAO,EAAE,SAAS,EAAE,GAAG,CAAC,SAAS,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,WAAW,EAAE,CAAC;QAEjF,KAAK,eAAe,CAAC,CAAC,CAAC;YACnB,MAAM,IAAI,GAAG,GAAG,CAAC,YAAY,IAAI,CAAC,CAAC;YACnC,IAAI,IAAI,IAAI,CAAC,EAAE,CAAC;gBACZ,OAAO,EAAE,SAAS,EAAE,GAAG,CAAC,SAAS,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,WAAW,EAAE,CAAC;YACjF,CAAC;YACD,OAAO,KAAK,CAAC,GAAG,CAAC,SAAS,EAAE,IAAI,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,OAAO,EAAE,GAAG,IAAI,GAAG,GAAG,CAAC,CAAC,CAAC;QAChF,CAAC;QAED,KAAK,aAAa,CAAC,CAAC,CAAC;YACjB,IAAI,CAAC,GAAG,CAAC,aAAa,IAAI,CAAC,GAAG,CAAC,WAAW,EAAE,CAAC;gBACzC,OAAO,EAAE,SAAS,EAAE,GAAG,CAAC,SAAS,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,WAAW,EAAE,CAAC;YACjF,CAAC;YACD,uFAAuF;YACvF,iFAAiF;YACjF,0DAA0D;YAC1D,MAAM,IAAI,GAAG,CAAC,GAAG,CAAC,eAAe,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC;YAC/C,MAAM,GAAG,GAAG,CAAC,GAAG,CAAC,cAAc,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC;YAC7C,OAAO,KAAK,CACR,IAAI,IAAI,CAAC,GAAG,CAAC,aAAa,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC,EAC5C,IAAI,IAAI,CAAC,GAAG,CAAC,WAAW,CAAC,OAAO,EAAE,GAAG,GAAG,CAAC,CAC5C,CAAC;QACN,CAAC;QAED,KAAK,kBAAkB,CAAC,CAAC,CAAC;YACtB,IAAI,CAAC,GAAG,CAAC,aAAa,IAAI,CAAC,GAAG,CAAC,WAAW,EAAE,CAAC;gBACzC,qFAAqF;gBACrF,oFAAoF;gBACpF,OAAO,EAAE,SAAS,EAAE,GAAG,CAAC,SAAS,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,WAAW,EAAE,CAAC;YACjF,CAAC;YACD,OAAO,KAAK,CAAC,GAAG,CAAC,aAAa,EAAE,GAAG,CAAC,WAAW,CAAC,CAAC;QACrD,CAAC;IACL,CAAC;AACL,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,kBAAkB,CAC9B,MAAmB,EACnB,KAA4D;IAE5D,IAAI,MAAM,KAAK,WAAW;QAAE,OAAO,QAAQ,CAAC;IAC5C,IAAI,MAAM,KAAK,cAAc;QAAE,OAAO,WAAW,CAAC;IAElD,4FAA4F;IAC5F,yDAAyD;IACzD,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,UAAU,IAAI,CAAC,CAAC,CAAC;IAC5C,IAAI,KAAK,IAAI,CAAC;QAAE,OAAO,QAAQ,CAAC;IAChC,OAAO,MAAM,CAAC,KAAK,CAAC,OAAO,IAAI,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,WAAW,CAAC;AACxE,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,oBAAoB,CAChC,aAA4B,EAC5B,oBAA4B,EAC5B,gBAAwB;IAExB,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;IAC5C,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,oBAAoB,CAAC,CAAC;IAEhD,IAAI,QAAQ,IAAI,CAAC,IAAI,QAAQ,IAAI,QAAQ;QAAE,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;IAC5F,IAAI,aAAa,IAAI,IAAI,EAAE,CAAC;QACxB,2FAA2F;QAC3F,qFAAqF;QACrF,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;IAC7C,CAAC;IAED,MAAM,SAAS,GAAG,aAAa,GAAG,CAAC,CAAC,QAAQ,GAAG,QAAQ,CAAC,GAAG,QAAQ,CAAC,CAAC;IACrE,kGAAkG;IAClG,yDAAyD;IACzD,OAAO,EAAE,QAAQ,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,SAAS,GAAG,GAAG,CAAC,GAAG,GAAG,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;AACrF,CAAC;AAqDD,iFAAiF;AACjF,MAAM,oBAAoB,GAAG,IAAI,GAAG,CAAC,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC,CAAC;AAE7D;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,mBAAmB,CAC/B,KAAuB,EACvB,IAAU,EACV,YAA6C,EAC7C,IAA6B;IAE7B,MAAM,MAAM,GAAG,CAAC,QAA6B,EAAyB,EAAE,CAAC,CAAC;QACtE,SAAS,EAAE,KAAK;QAChB,QAAQ;QACR,SAAS,EAAE,KAAK,CAAC,SAAS;QAC1B,OAAO,EAAE,KAAK,CAAC,OAAO;KACzB,CAAC,CAAC;IACH,MAAM,OAAO,GAAG,GAA0B,EAAE,CAAC,CAAC;QAC1C,SAAS,EAAE,IAAI;QACf,QAAQ,EAAE,SAAS;QACnB,SAAS,EAAE,KAAK,CAAC,SAAS;QAC1B,OAAO,EAAE,KAAK,CAAC,OAAO;KACzB,CAAC,CAAC;IAEH,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS;QAAE,OAAO,MAAM,CAAC,SAAS,CAAC,CAAC;IACzD,IAAI,KAAK,CAAC,MAAM,KAAK,WAAW;QAAE,OAAO,MAAM,CAAC,WAAW,CAAC,CAAC;IAC7D,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS;QAAE,OAAO,MAAM,CAAC,SAAS,CAAC,CAAC;IACzD,IAAI,KAAK,CAAC,MAAM,KAAK,QAAQ;QAAE,OAAO,MAAM,CAAC,SAAS,CAAC,CAAC;IAExD,IAAI,KAAK,CAAC,SAAS,IAAI,IAAI,CAAC,OAAO,EAAE,GAAG,KAAK,CAAC,SAAS,CAAC,OAAO,EAAE,EAAE,CAAC;QAChE,OAAO,MAAM,CAAC,aAAa,CAAC,CAAC;IACjC,CAAC;IAED,2EAA2E;IAC3E,IAAI,KAAK,CAAC,oBAAoB,IAAI,CAAC,YAAY;QAAE,OAAO,MAAM,CAAC,sBAAsB,CAAC,CAAC;IACvF,IAAI,KAAK,CAAC,YAAY,IAAI,CAAC,IAAI;QAAE,OAAO,MAAM,CAAC,sBAAsB,CAAC,CAAC;IAEvE,IAAI,YAAY,IAAI,CAAC,oBAAoB,CAAC,GAAG,CAAC,YAAY,CAAC,MAAM,CAAC,EAAE,CAAC;QACjE,IAAI,YAAY,CAAC,MAAM,KAAK,UAAU,EAAE,CAAC;YACrC,IAAI,CAAC,YAAY,CAAC,OAAO,IAAI,IAAI,CAAC,OAAO,EAAE,GAAG,YAAY,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC;gBAC3E,OAAO;oBACH,SAAS,EAAE,KAAK;oBAChB,QAAQ,EAAE,sBAAsB;oBAChC,SAAS,EAAE,KAAK,CAAC,SAAS;oBAC1B,OAAO,EAAE,YAAY,CAAC,OAAO;iBAChC,CAAC;YACN,CAAC;YACD,kFAAkF;YAClF,6EAA6E;YAC7E,0CAA0C;YAC1C,OAAO;gBACH,SAAS,EAAE,IAAI;gBACf,QAAQ,EAAE,SAAS;gBACnB,SAAS,EAAE,KAAK,CAAC,SAAS;gBAC1B,OAAO,EAAE,YAAY,CAAC,OAAO;aAChC,CAAC;QACN,CAAC;QACD,OAAO,MAAM,CAAC,sBAAsB,CAAC,CAAC;IAC1C,CAAC;IAED,IAAI,KAAK,CAAC,OAAO,IAAI,IAAI,CAAC,OAAO,EAAE,GAAG,KAAK,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC;QAC5D,OAAO,MAAM,CAAC,SAAS,CAAC,CAAC;IAC7B,CAAC;IAED,IAAI,IAAI,EAAE,CAAC;QACP,IAAI,IAAI,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE;YAAE,OAAO,MAAM,CAAC,aAAa,CAAC,CAAC;QAC5E,IAAI,IAAI,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE;YAAE,OAAO,MAAM,CAAC,sBAAsB,CAAC,CAAC;IACvF,CAAC;IAED,OAAO,OAAO,EAAE,CAAC;AACrB,CAAC;AAED,yGAAyG;AACzG,MAAM,WAAW,GAAwC;IACrD,OAAO,EAAE,CAAC;IACV,WAAW,EAAE,CAAC;IACd,SAAS,EAAE,CAAC;IACZ,oBAAoB,EAAE,CAAC;IACvB,OAAO,EAAE,CAAC;IACV,OAAO,EAAE,CAAC;IACV,OAAO,EAAE,CAAC;CACb,CAAC;AAQF;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAA2B,OAAY;IACpE,IAAI,CAAC,OAAO,CAAC,MAAM;QAAE,OAAO,IAAI,CAAC;IACjC,MAAM,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;IACnD,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;QACjB,OAAO,OAAO,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE;YAC9B,IAAI,IAAI,CAAC,OAAO,IAAI,IAAI;gBAAE,OAAO,IAAI,CAAC;YACtC,IAAI,CAAC,CAAC,OAAO,IAAI,IAAI;gBAAE,OAAO,CAAC,CAAC;YAChC,OAAO,CAAC,CAAC,OAAO,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;QACnE,CAAC,CAAC,CAAC;IACP,CAAC;IACD,OAAO,OAAO,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE,CAC9B,WAAW,CAAC,CAAC,CAAC,QAAQ,CAAC,GAAG,WAAW,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAClE,CAAC;AACN,CAAC;AAED,oFAAoF;AACpF,MAAM,CAAC,MAAM,wBAAwB,GAAG,MAAM,CAAC;AAE/C;;;GAGG;AACH,MAAM,UAAU,aAAa,CACzB,WAAiB,EACjB,OAAgC,EAChC,SAAkB;IAElB,MAAM,GAAG,GAAG,IAAI,IAAI,CAAC,WAAW,CAAC,OAAO,EAAE,GAAG,wBAAwB,CAAC,CAAC;IACvE,IAAI,SAAS,IAAI,OAAO,IAAI,IAAI,IAAI,OAAO,CAAC,OAAO,EAAE,GAAG,GAAG,CAAC,OAAO,EAAE,EAAE,CAAC;QACpE,OAAO,IAAI,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;IACvC,CAAC;IACD,OAAO,GAAG,CAAC;AACf,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,0BAA0B,CAAC,iBAAuB,EAAE,GAAS;IACzE,OAAO,GAAG,CAAC,OAAO,EAAE,GAAG,iBAAiB,CAAC,OAAO,EAAE,CAAC;AACvD,CAAC"}

package/dist/EntitlementEngine.d.ts

@@ -0,0 +1,97 @@
+/**
+ * EntitlementEngine — turns a confirmed order into the grants it confers, and unwinds them on return.
+ *
+ * The server half of `EntitlementBehavior`: this finds the rows, that decides what they mean. Same
+ * split as `PriceResolver`/`PricingBehavior`, for the same reason — the rules about quantity, validity
+ * and timing are provable without a database, and only finding the templates needs one.
+ *
+ * BATCHED, NOT PER LINE. Every lookup here is one `RunView` across the whole order: the entitlement
+ * templates, the products, the category ancestors, the event dates, the terms. A sixty-line order
+ * would otherwise issue several hundred round trips inside the booking transaction, holding write
+ * locks the entire time. The volume bundle confirms sixty-line orders precisely to make that visible.
+ *
+ * THE FAST PATH MATTERS. Most orders grant nothing at all — no product on them has a single
+ * `ProductEntitlement` row. That case is one query and an early return, because entitlements must not
+ * make ordinary orders slower.
+ *
+ * WHY GRANTS ARE WRITTEN INSIDE THE BOOKING TRANSACTION. Access and the receivable are the same
+ * decision: an order that booked revenue but failed to grant access has charged for nothing, and one
+ * that granted access without booking has given something away. All-or-none is the only coherent
+ * option, which is also why a failure here rolls back the confirm rather than being logged.
+ *
+ * CONNECTS TO:
+ *   PURE:   ./EntitlementBehavior.ts
+ *   CALLER: OrderEntityServer.Save (after subscriptions materialize — terms drive validity)
+ *   DOC:    plans/archive/bizapps-orders-master.md D27, D76
+ */
+import { EntitySaveOptions, IMetadataProvider, UserInfo } from '@memberjunction/core';
+import { type ValidityMode } from './EntitlementBehavior.js';
+/** The line facts grant creation needs. Deliberately structural, so a caller can pass anything shaped right. */
+export interface GrantableLine {
+    ID: string;
+    ProductID: string;
+    Quantity: number;
+    /** Per-line ship-to doubles as WHO an intangible line is for (D61) — the natural beneficiary. */
+    ShipToPersonID?: string | null;
+    ShipToOrganizationID?: string | null;
+}
+/** The order facts. `Balance`/`TotalGross` decide whether an OnPaidInFull grant starts Active. */
+export interface GrantableOrder {
+    ID: string;
+    OrderDate: Date;
+    Balance: number | null;
+    TotalGross: number | null;
+    BillToPersonID?: string | null;
+    BillToOrganizationID?: string | null;
+}
+/** What `materializeSubscriptions` already knows, passed in rather than re-queried. */
+export interface TermForLine {
+    ID: string;
+    StartDate: Date;
+    EndDate: Date;
+}
+export interface GrantOutcome {
+    Created: number;
+    /** Per grant, for the caller to log or assert on. */
+    Grants: Array<{
+        ID: string;
+        OrderLineID: string;
+        Code: string;
+        Status: string;
+        ValidityModeApplied: ValidityMode;
+    }>;
+}
+/**
+ * Create every grant this order's lines confer.
+ *
+ * A REVERSAL LINE GRANTS NOTHING. It unwinds a purchase, so running the grant path on it would hand
+ * the customer access as a side effect of returning the thing that conferred it — the same class of
+ * mistake as materializing a second subscription on a cancellation (D16).
+ */
+export declare function CreateEntitlementGrants(order: GrantableOrder, lines: GrantableLine[], termsByLine: Map<string, TermForLine>, provider: IMetadataProvider, user: UserInfo, options?: EntitySaveOptions): Promise<GrantOutcome>;
+/**
+ * Unwind the grants a returned line conferred.
+ *
+ * A full return REVOKES; a partial return reduces the quantity proportionally. Revocation stamps
+ * `RevokedAt` and a reason, because "this grant is revoked" with no record of when or why is exactly
+ * the shape that makes an access dispute unanswerable — and the database CHECK enforces the pairing.
+ *
+ * Uncountable grants (a Feature, an AccessLevel) survive a partial return: the customer still holds
+ * some of the thing that conferred it. Only sending all of it back takes the feature away.
+ */
+export declare function RevokeGrantsForReturn(originOrderLineID: string, originQuantity: number, returnedQuantity: number, reason: string, provider: IMetadataProvider, user: UserInfo, options?: EntitySaveOptions): Promise<{
+    Revoked: number;
+    Reduced: number;
+}>;
+/**
+ * After a subscription cancel, make stored grant Status less of a lie — still not the read path.
+ *
+ * Access-through in the future (grace) leaves the rows `Active`; `EvaluateGrantAccess` honours
+ * `subscription.EndDate`. Access-through already passed (immediate cancel, no remaining grace)
+ * REVOKES, with a reason, so a poll of Status at least stops saying Active.
+ */
+export declare function RevokeGrantsForCanceledSubscription(subscriptionID: string, accessThroughDate: Date, reason: string, provider: IMetadataProvider, user: UserInfo, options?: EntitySaveOptions, now?: Date): Promise<{
+    Revoked: number;
+    LeftStanding: number;
+}>;
+//# sourceMappingURL=EntitlementEngine.d.ts.map

package/dist/EntitlementEngine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EntitlementEngine.d.ts","sourceRoot":"","sources":["../src/EntitlementEngine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,OAAO,EAGH,iBAAiB,EACjB,iBAAiB,EAGjB,QAAQ,EACX,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAUH,KAAK,YAAY,EACpB,MAAM,0BAA0B,CAAC;AAclC,gHAAgH;AAChH,MAAM,WAAW,aAAa;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,iGAAiG;IACjG,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,oBAAoB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACxC;AAED,kGAAkG;AAClG,MAAM,WAAW,cAAc;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,IAAI,CAAC;IAChB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,oBAAoB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACxC;AAED,uFAAuF;AACvF,MAAM,WAAW,WAAW;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,IAAI,CAAC;IAChB,OAAO,EAAE,IAAI,CAAC;CACjB;AAED,MAAM,WAAW,YAAY;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,qDAAqD;IACrD,MAAM,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,mBAAmB,EAAE,YAAY,CAAA;KAAE,CAAC,CAAC;CACvH;AAED;;;;;;GAMG;AACH,wBAAsB,uBAAuB,CACzC,KAAK,EAAE,cAAc,EACrB,KAAK,EAAE,aAAa,EAAE,EACtB,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,EACrC,QAAQ,EAAE,iBAAiB,EAC3B,IAAI,EAAE,QAAQ,EACd,OAAO,CAAC,EAAE,iBAAiB,GAC5B,OAAO,CAAC,YAAY,CAAC,CAsKvB;AA+ID;;;;;;;;;GASG;AACH,wBAAsB,qBAAqB,CACvC,iBAAiB,EAAE,MAAM,EACzB,cAAc,EAAE,MAAM,EACtB,gBAAgB,EAAE,MAAM,EACxB,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,iBAAiB,EAC3B,IAAI,EAAE,QAAQ,EACd,OAAO,CAAC,EAAE,iBAAiB,GAC5B,OAAO,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,CA2C/C;AAED;;;;;;GAMG;AACH,wBAAsB,mCAAmC,CACrD,cAAc,EAAE,MAAM,EACtB,iBAAiB,EAAE,IAAI,EACvB,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,iBAAiB,EAC3B,IAAI,EAAE,QAAQ,EACd,OAAO,CAAC,EAAE,iBAAiB,EAC3B,GAAG,GAAE,IAAiB,GACvB,OAAO,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,CAAC,CAsCpD"}