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

package/dist/EntitlementEngine.js

@@ -0,0 +1,338 @@
+/**
+ * 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 { CompositeKey, RunView, } from '@memberjunction/core';
+import { InitialGrantStatus, ReduceGrantForReturn, ResolveEntitlementPolicy, ResolveGrantQuantity, ResolveValidityWindow, ShouldRevokeGrantsOnCancel, } from './EntitlementBehavior.js';
+import { RequireUUID } from './sql-guards.js';
+const PRODUCT_ENTITLEMENT_ENTITY = 'MJ_BizApps_Orders: Product Entitlements';
+const ENTITLEMENT_GRANT_ENTITY = 'MJ_BizApps_Orders: Entitlement Grants';
+const PRODUCT_ENTITY = 'MJ_BizApps_Orders: Products';
+const PRODUCT_CATEGORY_ENTITY = 'MJ_BizApps_Orders: Product Categories';
+const PRODUCT_TYPE_ENTITY = 'MJ_BizApps_Orders: Product Types';
+const EVENT_PRODUCT_ENTITY = 'MJ_BizApps_Orders: Event Products';
+const SUBSCRIPTION_TERM_ENTITY = 'MJ_BizApps_Orders: Subscription Terms';
+const key = (id) => (id ?? '').toLowerCase();
+const quote = (ids) => [...new Set(ids.map((i) => `'${i}'`))].join(',');
+/**
+ * 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 async function CreateEntitlementGrants(order, lines, termsByLine, provider, user, options) {
+    const out = { Created: 0, Grants: [] };
+    // Reversal lines and anything with no positive quantity confer nothing.
+    const grantable = lines.filter((l) => Number(l.Quantity ?? 0) > 0);
+    if (!grantable.length)
+        return out;
+    const rv = new RunView(provider);
+    const productIDs = [...new Set(grantable.map((l) => l.ProductID))];
+    // THE FAST PATH. One query, and most orders stop here.
+    const templates = await rv.RunView({
+        EntityName: PRODUCT_ENTITLEMENT_ENTITY,
+        ExtraFilter: `ProductID IN (${quote(productIDs)}) AND IsActive = 1`,
+        ResultType: 'simple',
+    }, user);
+    const templateRows = templates?.Results ?? [];
+    if (!templateRows.length)
+        return out;
+    const templatesByProduct = new Map();
+    for (const t of templateRows) {
+        const list = templatesByProduct.get(key(t.ProductID)) ?? [];
+        list.push(t);
+        templatesByProduct.set(key(t.ProductID), list);
+    }
+    // Only the products that actually grant something need their policy resolved.
+    const relevantProductIDs = productIDs.filter((id) => templatesByProduct.has(key(id)));
+    const policy = await loadPolicyInputs(relevantProductIDs, provider, user);
+    // Event dates, for EventWindow. One query for every event product on the order.
+    const events = await rv.RunView({
+        EntityName: EVENT_PRODUCT_ENTITY,
+        ExtraFilter: `ID IN (${quote(relevantProductIDs)})`,
+        ResultType: 'simple',
+    }, user);
+    const eventByProduct = new Map((events?.Results ?? []).map((e) => [key(e.ID), e]));
+    // NORMALISE THE CALLER'S KEYS. `materializeSubscriptions` keys `TermsByLine` by the raw line ID
+    // as SQL returned it — uppercase — and a lowercased lookup here found nothing, so EVERY
+    // subscription grant fell back to Perpetual while looking entirely correct. The suite caught it
+    // only because EN6 asserts `ValidityModeApplied` rather than just the dates.
+    //
+    // Re-keying here rather than asking the caller to change: a map that arrives with unknown casing
+    // is the caller's business, and normalising on receipt cannot be forgotten by the next caller.
+    const termsByLineKey = new Map();
+    for (const [lineID, term] of termsByLine)
+        termsByLineKey.set(key(lineID), term);
+    // Subscription IDs behind the terms, so a grant can point at both.
+    const termIDs = [...termsByLineKey.values()].map((t) => t.ID);
+    const subscriptionByTerm = new Map();
+    if (termIDs.length) {
+        const terms = await rv.RunView({
+            EntityName: SUBSCRIPTION_TERM_ENTITY,
+            ExtraFilter: `ID IN (${quote(termIDs)})`,
+            ResultType: 'simple',
+        }, user);
+        for (const t of terms?.Results ?? [])
+            subscriptionByTerm.set(key(t.ID), t.SubscriptionID);
+    }
+    for (const line of grantable) {
+        const forThisProduct = templatesByProduct.get(key(line.ProductID)) ?? [];
+        if (!forThisProduct.length)
+            continue;
+        const inputs = policy.get(key(line.ProductID));
+        if (!inputs) {
+            // The product grants something but could not be read. Refusing beats granting on a guess:
+            // an access decision made from defaults nobody configured is not a decision.
+            throw new Error(`Order line for product ${line.ProductID} confers entitlements, but the product's ` +
+                `policy could not be resolved (its type or category tree could not be read). ` +
+                `Access is refused rather than granted on assumed defaults.`);
+        }
+        const term = termsByLineKey.get(key(line.ID)) ?? null;
+        for (const template of forThisProduct) {
+            const resolved = ResolveEntitlementPolicy(inputs.Product, inputs.CategoryChain, inputs.Type, { ValidityMode: template.ValidityMode });
+            const event = eventByProduct.get(key(line.ProductID));
+            const validity = ResolveValidityWindow(resolved.ValidityMode, {
+                GrantedOn: order.OrderDate,
+                DurationDays: template.ValidityDurationDays,
+                EventStartsAt: event?.EventStartsAt ? new Date(event.EventStartsAt) : null,
+                EventEndsAt: event?.EventEndsAt ? new Date(event.EventEndsAt) : null,
+                AccessLeadHours: template.AccessLeadHours,
+                AccessLagHours: template.AccessLagHours,
+                TermStartDate: term ? new Date(term.StartDate) : null,
+                TermEndDate: term ? new Date(term.EndDate) : null,
+            });
+            const grant = await provider.GetEntityObject(ENTITLEMENT_GRANT_ENTITY, user);
+            grant.NewRecord();
+            grant.ProductEntitlementID = template.ID;
+            grant.OrderLineID = line.ID;
+            if (term) {
+                grant.SubscriptionTermID = term.ID;
+                const subID = subscriptionByTerm.get(key(term.ID));
+                if (subID)
+                    grant.SubscriptionID = subID;
+            }
+            // BENEFICIARY: the line's own ship-to first, because that is where 'who is this for'
+            // lives (D61) — a seat bought for a named colleague, a ticket for an attendee, a gift for
+            // a recipient. Only then the buyer.
+            const person = line.ShipToPersonID ?? order.BillToPersonID ?? null;
+            const organization = line.ShipToOrganizationID ?? order.BillToOrganizationID ?? null;
+            if (person)
+                grant.BeneficiaryPersonID = person;
+            if (organization)
+                grant.BeneficiaryOrganizationID = organization;
+            grant.Quantity = ResolveGrantQuantity(template.Quantity, Number(line.Quantity ?? 0), resolved.QuantityMode);
+            grant.ValidFrom = validity.ValidFrom;
+            grant.ValidTo = validity.ValidTo;
+            grant.ValidityModeApplied = validity.ModeApplied;
+            const status = InitialGrantStatus(resolved.GrantTiming, order);
+            grant.Status = status;
+            if (!(await grant.Save(options))) {
+                throw new Error(`Failed to grant entitlement '${template.Code}' for order line ${line.ID}: ` +
+                    `${grant.LatestResult?.CompleteMessage ?? 'unknown error'}`);
+            }
+            out.Created++;
+            out.Grants.push({
+                ID: grant.ID,
+                OrderLineID: line.ID,
+                Code: template.Code,
+                Status: status,
+                ValidityModeApplied: validity.ModeApplied,
+            });
+        }
+    }
+    return out;
+}
+/**
+ * Load the policy chain for every relevant product, in a bounded number of queries.
+ *
+ * The category tree is walked BREADTH-FIRST across all products at once rather than depth-first per
+ * product: one query per LEVEL of the deepest tree, not one per ancestor per product. A three-level
+ * tree over forty products is three queries instead of a hundred and twenty.
+ *
+ * The depth cap is a cycle guard, not a modelling limit. `CK_ProductCategory_NoSelfParent` stops a
+ * category being its own parent but nothing stops A→B→A, and an unbounded walk on that would hang
+ * inside the booking transaction — the worst possible place.
+ */
+async function loadPolicyInputs(productIDs, provider, user) {
+    const rv = new RunView(provider);
+    const out = new Map();
+    if (!productIDs.length)
+        return out;
+    const products = await rv.RunView({
+        EntityName: PRODUCT_ENTITY,
+        ExtraFilter: `ID IN (${quote(productIDs)})`,
+        ResultType: 'simple',
+    }, user);
+    const productRows = products?.Results ?? [];
+    if (!productRows.length)
+        return out;
+    const types = await rv.RunView({
+        EntityName: PRODUCT_TYPE_ENTITY,
+        ExtraFilter: `ID IN (${quote(productRows.map((p) => p.ProductTypeID))})`,
+        ResultType: 'simple',
+    }, user);
+    const typeByID = new Map((types?.Results ?? []).map((t) => [key(t.ID), t]));
+    // Breadth-first up the tree, gathering every level in one query each.
+    const categoryByID = new Map();
+    let frontier = [...new Set(productRows.map((p) => p.ProductCategoryID).filter((c) => !!c))];
+    const MAX_DEPTH = 20;
+    for (let depth = 0; depth < MAX_DEPTH && frontier.length; depth++) {
+        const level = await rv.RunView({
+            EntityName: PRODUCT_CATEGORY_ENTITY,
+            ExtraFilter: `ID IN (${quote(frontier)})`,
+            ResultType: 'simple',
+        }, user);
+        const rows = level?.Results ?? [];
+        if (!rows.length)
+            break;
+        for (const r of rows) {
+            categoryByID.set(key(r.ID), {
+                ID: r.ID,
+                ParentProductCategoryID: r.ParentProductCategoryID,
+                EntitlementGrantTiming: r.DefaultEntitlementGrantTiming,
+                EntitlementQuantityMode: r.DefaultEntitlementQuantityMode,
+                EntitlementValidityMode: r.DefaultEntitlementValidityMode,
+            });
+        }
+        frontier = [
+            ...new Set(rows
+                .map((r) => r.ParentProductCategoryID)
+                .filter((c) => !!c && !categoryByID.has(key(c)))),
+        ];
+    }
+    for (const p of productRows) {
+        const type = typeByID.get(key(p.ProductTypeID));
+        if (!type)
+            continue; // caller refuses — see CreateEntitlementGrants
+        // NEAREST FIRST, and stop on a repeat: a cyclic tree must not loop forever.
+        const chain = [];
+        const seen = new Set();
+        let cursor = p.ProductCategoryID;
+        while (cursor && !seen.has(key(cursor)) && chain.length < MAX_DEPTH) {
+            seen.add(key(cursor));
+            const cat = categoryByID.get(key(cursor));
+            if (!cat)
+                break;
+            chain.push({
+                ID: cat.ID,
+                EntitlementGrantTiming: cat.EntitlementGrantTiming,
+                EntitlementQuantityMode: cat.EntitlementQuantityMode,
+                EntitlementValidityMode: cat.EntitlementValidityMode,
+            });
+            cursor = cat.ParentProductCategoryID;
+        }
+        out.set(key(p.ID), {
+            Product: {
+                EntitlementGrantTiming: p.EntitlementGrantTiming,
+                EntitlementQuantityMode: p.EntitlementQuantityMode,
+                EntitlementValidityMode: p.EntitlementValidityMode,
+            },
+            CategoryChain: chain,
+            Type: type,
+        });
+    }
+    return out;
+}
+/**
+ * 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 async function RevokeGrantsForReturn(originOrderLineID, originQuantity, returnedQuantity, reason, provider, user, options) {
+    const rv = new RunView(provider);
+    const grants = await rv.RunView({
+        EntityName: ENTITLEMENT_GRANT_ENTITY,
+        ExtraFilter: `OrderLineID = '${originOrderLineID}' AND Status IN ('Active','Suspended')`,
+        ResultType: 'simple',
+    }, user);
+    let revoked = 0;
+    let reduced = 0;
+    for (const row of grants?.Results ?? []) {
+        const decision = ReduceGrantForReturn(row.Quantity, originQuantity, returnedQuantity);
+        // `GetEntityObject` with a CompositeKey loads it — the house idiom, same as
+        // CancelSubscriptionOperation.
+        const grant = await provider.GetEntityObject(ENTITLEMENT_GRANT_ENTITY, CompositeKey.FromID(row.ID), user);
+        if (decision.Revoke) {
+            grant.Status = 'Revoked';
+            grant.RevokedAt = new Date();
+            grant.RevocationReason = reason;
+            revoked++;
+        }
+        else {
+            if (decision.Quantity === row.Quantity)
+                continue; // nothing to change
+            grant.Quantity = decision.Quantity;
+            reduced++;
+        }
+        if (!(await grant.Save(options))) {
+            throw new Error(`Failed to unwind entitlement grant ${row.ID} for the returned line: ` +
+                `${grant.LatestResult?.CompleteMessage ?? 'unknown error'}`);
+        }
+    }
+    return { Revoked: revoked, Reduced: reduced };
+}
+/**
+ * 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 async function RevokeGrantsForCanceledSubscription(subscriptionID, accessThroughDate, reason, provider, user, options, now = new Date()) {
+    const id = RequireUUID(subscriptionID, 'SubscriptionID');
+    const rv = new RunView(provider);
+    const grants = await rv.RunView({
+        EntityName: ENTITLEMENT_GRANT_ENTITY,
+        ExtraFilter: `SubscriptionID = '${id}' AND Status IN ('Active','Suspended')`,
+        ResultType: 'simple',
+        BypassCache: true,
+    }, user);
+    const rows = grants?.Results ?? [];
+    if (!rows.length)
+        return { Revoked: 0, LeftStanding: 0 };
+    if (!ShouldRevokeGrantsOnCancel(accessThroughDate, now)) {
+        return { Revoked: 0, LeftStanding: rows.length };
+    }
+    let revoked = 0;
+    for (const row of rows) {
+        const grant = await provider.GetEntityObject(ENTITLEMENT_GRANT_ENTITY, CompositeKey.FromID(row.ID), user);
+        grant.Status = 'Revoked';
+        grant.RevokedAt = now;
+        grant.RevocationReason = reason;
+        if (!(await grant.Save(options))) {
+            throw new Error(`Failed to revoke entitlement grant ${row.ID} after subscription cancel: ` +
+                `${grant.LatestResult?.CompleteMessage ?? 'unknown error'}`);
+        }
+        revoked++;
+    }
+    return { Revoked: revoked, LeftStanding: 0 };
+}
+//# sourceMappingURL=EntitlementEngine.js.map

package/dist/EntitlementEngine.js.map

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

package/dist/EntitlementGrantClaimDriver.d.ts

@@ -0,0 +1,42 @@
+/**
+ * @fileoverview Entitlement Grant Claim Driver
+ *
+ * Implements the BaseIdentityClaimDriver interface for BizApps Orders entitlement grants.
+ * When an external user redeems an invitation or magic link claim, this driver attaches the
+ * EntitlementGrant to their authenticated Person record and activates the grant.
+ *
+ * @module @mj-biz-apps/orders-core-entities-server/EntitlementGrantClaimDriver
+ */
+import { BaseIdentityClaimDriver, type ClaimContext, type ClaimRedeemContext, type ClaimResult } from './identityClaimContracts.js';
+/**
+ * Pluggable driver for EntitlementGrant identity claims.
+ */
+export declare class EntitlementGrantClaimDriver extends BaseIdentityClaimDriver {
+    /**
+     * Hook called after an entitlement claim is created.
+     */
+    OnCreate(context: ClaimContext): Promise<void>;
+    /**
+     * Hook called when an entitlement claim is redeemed by an authenticated user.
+     */
+    OnClaim(context: ClaimRedeemContext): Promise<ClaimResult>;
+    /**
+     * Hook called when an entitlement claim is revoked.
+     *
+     * `CK_EntitlementGrant_Revocation` (and the generated `ValidateRevokedAtBasedOnStatus`
+     * rule) require `RevokedAt` whenever Status is 'Revoked' — a revocation without the
+     * timestamp fails validation and the grant silently stays Active. Stamp both, and
+     * surface a failed save instead of swallowing it.
+     */
+    OnRevoke(context: ClaimContext): Promise<void>;
+    /**
+     * Hook called when an entitlement claim expires. (`RevokedAt` must NOT be set here — the
+     * validation rule requires it to be null for any non-Revoked status.)
+     */
+    OnExpire(context: ClaimContext): Promise<void>;
+}
+/**
+ * Registration helper to ensure class factory decorator executes.
+ */
+export declare function LoadEntitlementGrantClaimDriver(): void;
+//# sourceMappingURL=EntitlementGrantClaimDriver.d.ts.map

package/dist/EntitlementGrantClaimDriver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EntitlementGrantClaimDriver.d.ts","sourceRoot":"","sources":["../src/EntitlementGrantClaimDriver.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH,OAAO,EACH,uBAAuB,EACvB,KAAK,YAAY,EACjB,KAAK,kBAAkB,EACvB,KAAK,WAAW,EACnB,MAAM,6BAA6B,CAAC;AAMrC;;GAEG;AACH,qBACa,2BAA4B,SAAQ,uBAAuB;IACpE;;OAEG;IACU,QAAQ,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAI3D;;OAEG;IACU,OAAO,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,WAAW,CAAC;IAiEvE;;;;;;;OAOG;IACU,QAAQ,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IA0B3D;;;OAGG;IACU,QAAQ,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;CAuB9D;AAED;;GAEG;AACH,wBAAgB,+BAA+B,IAAI,IAAI,CAEtD"}

package/dist/EntitlementGrantClaimDriver.js

@@ -0,0 +1,158 @@
+/**
+ * @fileoverview Entitlement Grant Claim Driver
+ *
+ * Implements the BaseIdentityClaimDriver interface for BizApps Orders entitlement grants.
+ * When an external user redeems an invitation or magic link claim, this driver attaches the
+ * EntitlementGrant to their authenticated Person record and activates the grant.
+ *
+ * @module @mj-biz-apps/orders-core-entities-server/EntitlementGrantClaimDriver
+ */
+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;
+};
+import { RegisterClass } from '@memberjunction/global';
+import { LogError, Metadata } from '@memberjunction/core';
+// Local fallback contracts — see identityClaimContracts.ts. Restore this import to
+// '@memberjunction/core-entities' once MJ publishes these exports.
+import { BaseIdentityClaimDriver, } from './identityClaimContracts.js';
+import { resolvePersonID } from './claimDriverHelpers.js';
+const ENTITLEMENT_GRANT_ENTITY = 'MJ_BizApps_Orders: Entitlement Grants';
+/**
+ * Pluggable driver for EntitlementGrant identity claims.
+ */
+let EntitlementGrantClaimDriver = class EntitlementGrantClaimDriver extends BaseIdentityClaimDriver {
+    /**
+     * Hook called after an entitlement claim is created.
+     */
+    async OnCreate(context) {
+        // Claim registered in pending state
+    }
+    /**
+     * Hook called when an entitlement claim is redeemed by an authenticated user.
+     */
+    async OnClaim(context) {
+        const { Claim, User } = context;
+        let grantID = Claim.RecordID;
+        if (!grantID && Claim.PayloadJSON) {
+            try {
+                const payload = JSON.parse(Claim.PayloadJSON);
+                if (typeof payload.GrantID === 'string') {
+                    grantID = payload.GrantID;
+                }
+                else if (typeof payload.grantId === 'string') {
+                    grantID = payload.grantId;
+                }
+            }
+            catch {
+                // Ignore parse errors
+            }
+        }
+        if (!grantID) {
+            return {
+                Success: false,
+                ErrorMessage: 'Claim does not reference an EntitlementGrant RecordID'
+            };
+        }
+        const md = new Metadata();
+        const grant = await md.GetEntityObject(ENTITLEMENT_GRANT_ENTITY, User);
+        const loaded = await grant.Load(grantID);
+        if (!loaded) {
+            return {
+                Success: false,
+                ErrorMessage: `EntitlementGrant with ID ${grantID} not found`
+            };
+        }
+        const personID = await resolvePersonID(User, Claim.ProviderToUse);
+        if (personID && (!grant.BeneficiaryPersonID || grant.BeneficiaryPersonID !== personID)) {
+            grant.BeneficiaryPersonID = personID;
+        }
+        grant.Status = 'Active';
+        grant.ProvisionedAt = new Date();
+        const saved = await grant.Save();
+        if (!saved) {
+            return {
+                Success: false,
+                ErrorMessage: `Failed to activate EntitlementGrant: ${grant.LatestResult?.Message ?? 'Unknown save error'}`
+            };
+        }
+        return {
+            Success: true,
+            Data: {
+                GrantID: grant.ID,
+                BeneficiaryPersonID: grant.BeneficiaryPersonID,
+                ProductEntitlementID: grant.ProductEntitlementID,
+                ProvisionedAt: grant.ProvisionedAt?.toISOString()
+            }
+        };
+    }
+    /**
+     * Hook called when an entitlement claim is revoked.
+     *
+     * `CK_EntitlementGrant_Revocation` (and the generated `ValidateRevokedAtBasedOnStatus`
+     * rule) require `RevokedAt` whenever Status is 'Revoked' — a revocation without the
+     * timestamp fails validation and the grant silently stays Active. Stamp both, and
+     * surface a failed save instead of swallowing it.
+     */
+    async OnRevoke(context) {
+        const { Claim, User } = context;
+        if (!Claim.RecordID)
+            return;
+        try {
+            const md = new Metadata();
+            const grant = await md.GetEntityObject(ENTITLEMENT_GRANT_ENTITY, User);
+            const loaded = await grant.Load(Claim.RecordID);
+            if (loaded && grant.Status === 'Active') {
+                grant.Status = 'Revoked';
+                grant.RevokedAt = new Date();
+                grant.RevocationReason = 'Identity claim revoked';
+                const saved = await grant.Save();
+                if (!saved) {
+                    LogError(`[EntitlementGrantClaimDriver] OnRevoke failed to save grant ${grant.ID}: ${grant.LatestResult?.CompleteMessage ?? 'unknown error'}`);
+                }
+            }
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            LogError(`[EntitlementGrantClaimDriver] OnRevoke error for claim ${Claim.ID}: ${msg}`);
+        }
+    }
+    /**
+     * Hook called when an entitlement claim expires. (`RevokedAt` must NOT be set here — the
+     * validation rule requires it to be null for any non-Revoked status.)
+     */
+    async OnExpire(context) {
+        const { Claim, User } = context;
+        if (!Claim.RecordID)
+            return;
+        try {
+            const md = new Metadata();
+            const grant = await md.GetEntityObject(ENTITLEMENT_GRANT_ENTITY, User);
+            const loaded = await grant.Load(Claim.RecordID);
+            if (loaded && grant.Status === 'Active') {
+                grant.Status = 'Expired';
+                const saved = await grant.Save();
+                if (!saved) {
+                    LogError(`[EntitlementGrantClaimDriver] OnExpire failed to save grant ${grant.ID}: ${grant.LatestResult?.CompleteMessage ?? 'unknown error'}`);
+                }
+            }
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            LogError(`[EntitlementGrantClaimDriver] OnExpire error for claim ${Claim.ID}: ${msg}`);
+        }
+    }
+};
+EntitlementGrantClaimDriver = __decorate([
+    RegisterClass(BaseIdentityClaimDriver, 'EntitlementGrantClaimDriver')
+], EntitlementGrantClaimDriver);
+export { EntitlementGrantClaimDriver };
+/**
+ * Registration helper to ensure class factory decorator executes.
+ */
+export function LoadEntitlementGrantClaimDriver() {
+    // Explicit trigger for bundler tree-shaking preservation
+}
+//# sourceMappingURL=EntitlementGrantClaimDriver.js.map

package/dist/EntitlementGrantClaimDriver.js.map

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

package/dist/EntitlementRead.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Entitlement read path — load the rows, then ask `EvaluateGrantAccess`.
+ *
+ * `Orders.CheckEntitlement` and `Orders.ListEntitlements` share this so they cannot disagree
+ * about which grants count, how email resolves, or how a cancelled subscription is read.
+ * The judgement itself lives in `EntitlementBehavior` and has no database.
+ *
+ * v1 is person grants only. Org-only rows (`BeneficiaryPersonID` null) are never loaded.
+ * Email is a convenience: normalised, and refused when it matches more than one person —
+ * first-match would be an authorization bug dressed as helpfulness.
+ *
+ * CONNECTS TO:
+ *   PURE:   ./EntitlementBehavior.ts
+ *   OPS:    ./CheckEntitlementOperation.ts, ./ListEntitlementsOperation.ts
+ *   DOC:    plans/entitlement-read-contract.md
+ */
+import { IMetadataProvider, UserInfo } from '@memberjunction/core';
+import { type EntitlementDecision } from './EntitlementBehavior.js';
+export interface CheckEntitlementInput {
+    /** Authoritative. When present, Email is ignored. */
+    PersonID?: string | null;
+    /** Convenience. Normalised; ambiguous-if-duplicate → NoGrant, same shape as unknown. */
+    Email?: string | null;
+    /** Capability key (`ProductEntitlement.Code`), unique per product not globally. */
+    Code: string;
+    /**
+     * Diagnostics only — historical audit. The trust path omits this (evaluates at now).
+     * Values more than a minute in the future are rejected (NTP skew is allowed).
+     * CacheUntil is always issued from wall-clock now, never from this date.
+     */
+    AsOf?: string | Date | null;
+    /** Optional company narrowing via the template's product. */
+    CompanyID?: string | null;
+}
+export interface CheckEntitlementOutput {
+    HasAccess: boolean;
+    Decision: EntitlementDecision;
+    ValidFrom?: string;
+    ValidTo?: string;
+    Quantity?: number;
+    GrantID?: string;
+    EvaluatedAt: string;
+    CacheUntil: string;
+}
+export interface ListEntitlementsInput {
+    PersonID?: string | null;
+    Email?: string | null;
+    AsOf?: string | Date | null;
+    CompanyID?: string | null;
+    /** When false, only in-force capabilities. Default true — a library includes lapsed ones. */
+    IncludeInactive?: boolean;
+}
+export interface ListedEntitlement {
+    Code: string;
+    HasAccess: boolean;
+    Decision: EntitlementDecision;
+    ValidFrom?: string;
+    ValidTo?: string;
+    Quantity?: number;
+    GrantID?: string;
+    CacheUntil: string;
+}
+export interface ListEntitlementsOutput {
+    EvaluatedAt: string;
+    Items: ListedEntitlement[];
+}
+/** NTP skew between LXP and Orders. CacheUntil does not use AsOf, so this cannot mint a long cache. */
+export declare const ASOF_FUTURE_TOLERANCE_MS = 60000;
+/**
+ * Ask: does this person currently have this capability?
+ *
+ * Unknown person, ambiguous email, unknown code, and known-person-without-access share one
+ * response shape. Lookup faults fail closed the same way. Caller bugs (missing Code, bad
+ * UUID) throw `InvalidOperationInputError` so an integrator learns they sent garbage.
+ */
+export declare function CheckPersonEntitlement(input: CheckEntitlementInput, provider: IMetadataProvider, user: UserInfo): Promise<CheckEntitlementOutput>;
+/**
+ * The person's library, one row per Code, each evaluated the same way as a point check.
+ * Empty when the person cannot be resolved — same non-leak as the check.
+ */
+export declare function ListPersonEntitlements(input: ListEntitlementsInput, provider: IMetadataProvider, user: UserInfo): Promise<ListEntitlementsOutput>;
+//# sourceMappingURL=EntitlementRead.d.ts.map