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

package/dist/GiftCardBehavior.js

@@ -0,0 +1,121 @@
+/**
+ * Gift-card issuance decisions, with no database in sight.
+ *
+ * WHAT SELLING A GIFT CARD ACTUALLY IS. It is not a sale. Nothing has been delivered and no revenue
+ * has been earned — the company has taken money and now OWES goods. So the line books a LIABILITY,
+ * and revenue appears later, on whatever order the card is eventually spent on. Getting this wrong
+ * is the classic gift-card error: recognise at issue and you book revenue twice, once when the card
+ * is sold and again when it is redeemed.
+ *
+ * THE ONE THAT LOOKS RIGHT AND IS NOT. Face value is `UnitPrice`, deliberately NOT the discounted
+ * line amount. Sell a $50 card in a 10%-off promotion and the customer pays $45 — but the card is
+ * still worth $50 and the company still owes $50 of goods. Deriving the liability from what was
+ * PAID understates it by exactly the discount, and every downstream number still reconciles, because
+ * the order, the payment and the journal entry all agree with each other. Only the balance sheet is
+ * wrong, and only until somebody redeems.
+ *
+ * ONE CARD PER UNIT. Quantity 3 at $50 is three $50 cards, not one $150 card. That is how a person
+ * buying three gift cards expects it to work, and it is why quantity must be a whole number here —
+ * half a gift card is not a thing, and silently flooring it would hand the customer less than they
+ * bought.
+ *
+ * CONNECTS TO:
+ *   CODE: GiftCardEngine (the rows) · OrderEntityServer.issueGiftCards (the lifecycle point)
+ *   DOC:  plans/archive/bizapps-orders-master.md D4 (GiftCard product type), D27 (beneficiary), D44
+ */
+/** The ProductType.Code that marks a product as a gift card. Seeded per D4. */
+export const GIFT_CARD_PRODUCT_TYPE_CODE = 'GiftCard';
+const EMPTY = (reason) => ({ Cards: [], Refusal: reason });
+/** Round to cents the way the rest of the engine does. */
+const Money = (n) => Math.round((n + Number.EPSILON) * 100) / 100;
+/** Is this line for a gift-card product at all? */
+export function IsGiftCardLine(line) {
+    return (line.ProductTypeCode ?? '').trim().toLowerCase() === GIFT_CARD_PRODUCT_TYPE_CODE.toLowerCase();
+}
+/**
+ * Decide what a line issues.
+ *
+ * Returns an empty plan WITH a reason rather than throwing, because most lines are not gift cards
+ * and that is not an error. The caller distinguishes "nothing to do" from "something was wrong" by
+ * looking at `Refusal`, which is why the two cases are never both empty and silent.
+ */
+export function PlanGiftCardIssuance(line, order) {
+    if (!IsGiftCardLine(line))
+        return EMPTY('NotAGiftCardProduct');
+    // A reversal line carries a negative quantity and points at the line it undoes. It must not mint
+    // more cards — the return path voids the origin's cards instead (see PlanGiftCardVoid).
+    if (line.ReversesOrderLineID)
+        return EMPTY('ReversalLine');
+    const qty = Number(line.Quantity ?? 0);
+    if (!(qty > 0))
+        return EMPTY('NonPositiveQuantity');
+    if (!Number.isInteger(qty))
+        return EMPTY('FractionalQuantity');
+    const faceValue = Money(Number(line.UnitPrice ?? 0));
+    if (!(faceValue > 0))
+        return EMPTY('NonPositiveFaceValue');
+    // WHO THE CARD IS FOR (D27). A gift card is the archetypal case of a line bought by one person
+    // for another, so the line's ship-to wins when stated. The order's bill-to is the fallback for
+    // the ordinary case of buying a card for yourself — NOT a default that overrides an explicit
+    // recipient, which is why each side falls back independently.
+    const beneficiaryPersonID = line.ShipToPersonID ?? order.BillToPersonID ?? null;
+    const beneficiaryOrganizationID = line.ShipToOrganizationID ?? order.BillToOrganizationID ?? null;
+    const cards = [];
+    for (let i = 1; i <= qty; i++) {
+        cards.push({
+            OrderLineID: line.ID,
+            Sequence: i,
+            FaceValue: faceValue,
+            BeneficiaryPersonID: beneficiaryPersonID,
+            BeneficiaryOrganizationID: beneficiaryOrganizationID,
+        });
+    }
+    return { Cards: cards, Refusal: null };
+}
+/** How many of a line's cards a return of `reversalQuantity` units should void. */
+export function PlanGiftCardVoid(reversalQuantity, issuedCount) {
+    // The reversal quantity is negative by convention (D10); its magnitude is what was sent back.
+    const returned = Math.abs(Number(reversalQuantity ?? 0));
+    if (!(returned > 0) || !(issuedCount > 0))
+        return 0;
+    // Never void more than were issued. A partial return of a three-card line voids that many, and
+    // returning the whole line voids the lot.
+    return Math.min(Math.floor(returned), issuedCount);
+}
+/**
+ * A card code: `GC-` + 16 unambiguous characters in groups of four.
+ *
+ * The alphabet omits I, L, O, 0, 1, U — the pairs people mistype when reading a card aloud or off a
+ * printed insert, and U because it turns short random runs into words nobody wants printed on a gift
+ * card. 30 symbols over 16 positions is ~78 bits, so collisions are not a practical concern; the
+ * UNIQUE constraint on `StoredValueAccount.Code` is the actual guarantee and this only has to make
+ * hitting it vanishingly unlikely.
+ *
+ * `randomChar` is injected so tests can make this deterministic without stubbing global crypto.
+ */
+export const GIFT_CARD_ALPHABET = '23456789ABCDEFGHJKMNPQRSTVWXYZ';
+export function FormatGiftCardCode(randomChar, groups = 4, groupSize = 4) {
+    const parts = [];
+    for (let g = 0; g < groups; g++) {
+        let part = '';
+        for (let i = 0; i < groupSize; i++)
+            part += randomChar();
+        parts.push(part);
+    }
+    return `GC-${parts.join('-')}`;
+}
+/** True if a string looks like a code this module would have produced. */
+export function IsGiftCardCode(code) {
+    return /^GC-([23456789ABCDEFGHJKMNPQRSTVWXYZ]{4}-){3}[23456789ABCDEFGHJKMNPQRSTVWXYZ]{4}$/.test(code);
+}
+/**
+ * The total liability a plan creates.
+ *
+ * Deliberately separate from the line's own money. `LineTotalNet` is what the CUSTOMER PAID, after
+ * discounts and promotions; this is what the COMPANY OWES. On an undiscounted line they are equal,
+ * which is exactly why a bug here would go unnoticed until the first discounted card.
+ */
+export function GiftCardLiability(plan) {
+    return Money(plan.Cards.reduce((sum, c) => sum + c.FaceValue, 0));
+}
+//# sourceMappingURL=GiftCardBehavior.js.map

package/dist/GiftCardBehavior.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"GiftCardBehavior.js","sourceRoot":"","sources":["../src/GiftCardBehavior.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,+EAA+E;AAC/E,MAAM,CAAC,MAAM,2BAA2B,GAAG,UAAU,CAAC;AA8CtD,MAAM,KAAK,GAAG,CAAC,MAAuB,EAAgB,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC;AAE1F,0DAA0D;AAC1D,MAAM,KAAK,GAAG,CAAC,CAAS,EAAU,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,OAAO,CAAC,GAAG,GAAG,CAAC,GAAG,GAAG,CAAC;AAElF,mDAAmD;AACnD,MAAM,UAAU,cAAc,CAAC,IAAgD;IAC3E,OAAO,CAAC,IAAI,CAAC,eAAe,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,KAAK,2BAA2B,CAAC,WAAW,EAAE,CAAC;AAC3G,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,oBAAoB,CAChC,IAAuB,EACvB,KAAyB;IAEzB,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC;QAAE,OAAO,KAAK,CAAC,qBAAqB,CAAC,CAAC;IAE/D,iGAAiG;IACjG,wFAAwF;IACxF,IAAI,IAAI,CAAC,mBAAmB;QAAE,OAAO,KAAK,CAAC,cAAc,CAAC,CAAC;IAE3D,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,QAAQ,IAAI,CAAC,CAAC,CAAC;IACvC,IAAI,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC;QAAE,OAAO,KAAK,CAAC,qBAAqB,CAAC,CAAC;IACpD,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC;QAAE,OAAO,KAAK,CAAC,oBAAoB,CAAC,CAAC;IAE/D,MAAM,SAAS,GAAG,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,IAAI,CAAC,CAAC,CAAC,CAAC;IACrD,IAAI,CAAC,CAAC,SAAS,GAAG,CAAC,CAAC;QAAE,OAAO,KAAK,CAAC,sBAAsB,CAAC,CAAC;IAE3D,+FAA+F;IAC/F,+FAA+F;IAC/F,6FAA6F;IAC7F,8DAA8D;IAC9D,MAAM,mBAAmB,GAAG,IAAI,CAAC,cAAc,IAAI,KAAK,CAAC,cAAc,IAAI,IAAI,CAAC;IAChF,MAAM,yBAAyB,GAAG,IAAI,CAAC,oBAAoB,IAAI,KAAK,CAAC,oBAAoB,IAAI,IAAI,CAAC;IAElG,MAAM,KAAK,GAAsB,EAAE,CAAC;IACpC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC;QAC5B,KAAK,CAAC,IAAI,CAAC;YACP,WAAW,EAAE,IAAI,CAAC,EAAE;YACpB,QAAQ,EAAE,CAAC;YACX,SAAS,EAAE,SAAS;YACpB,mBAAmB,EAAE,mBAAmB;YACxC,yBAAyB,EAAE,yBAAyB;SACvD,CAAC,CAAC;IACP,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;AAC3C,CAAC;AAED,mFAAmF;AACnF,MAAM,UAAU,gBAAgB,CAAC,gBAAwB,EAAE,WAAmB;IAC1E,8FAA8F;IAC9F,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,gBAAgB,IAAI,CAAC,CAAC,CAAC,CAAC;IACzD,IAAI,CAAC,CAAC,QAAQ,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,WAAW,GAAG,CAAC,CAAC;QAAE,OAAO,CAAC,CAAC;IACpD,+FAA+F;IAC/F,0CAA0C;IAC1C,OAAO,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,WAAW,CAAC,CAAC;AACvD,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,gCAAgC,CAAC;AAEnE,MAAM,UAAU,kBAAkB,CAAC,UAAwB,EAAE,MAAM,GAAG,CAAC,EAAE,SAAS,GAAG,CAAC;IAClF,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAC9B,IAAI,IAAI,GAAG,EAAE,CAAC;QACd,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,SAAS,EAAE,CAAC,EAAE;YAAE,IAAI,IAAI,UAAU,EAAE,CAAC;QACzD,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACrB,CAAC;IACD,OAAO,MAAM,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;AACnC,CAAC;AAED,0EAA0E;AAC1E,MAAM,UAAU,cAAc,CAAC,IAAY;IACvC,OAAO,mFAAmF,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1G,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAkB;IAChD,OAAO,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,CAAC,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,CAAC;AACtE,CAAC"}

package/dist/GiftCardEngine.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Turn gift-card lines into StoredValueAccount rows and their opening ledger entries.
+ *
+ * The DECISIONS live in `GiftCardBehavior` and are unit-tested without a database. What lives here
+ * is the part that needs one: finding which lines are gift cards, minting codes that survive the
+ * UNIQUE constraint, and writing the account plus its `Issue` transaction as one act.
+ *
+ * IDEMPOTENCY IS THE WHOLE GAME. `OrderEntityServer.Save` re-runs on every save of an already
+ * confirmed order, and issuing a second set of cards would hand the customer free money that
+ * reconciles perfectly — the accounts exist, the ledger balances, the order is unchanged. So
+ * issuance keys on `IssuedFromOrderLineID`: a line that has already issued issues nothing. That is
+ * checked against the DATABASE rather than a flag in memory, because the second save is a different
+ * object than the first.
+ *
+ * CONNECTS TO:
+ *   PURE: GiftCardBehavior (+ its unit tests)
+ *   CODE: OrderEntityServer.issueGiftCards (lifecycle) · StoredValuePaymentProvider (redemption)
+ *   DOC:  plans/archive/bizapps-orders-master.md D4, D27, D44
+ */
+import { EntitySaveOptions, IMetadataProvider, UserInfo } from '@memberjunction/core';
+import { type GiftCardOrderFacts } from './GiftCardBehavior.js';
+/** What the caller hands us about the order. */
+export interface GiftCardOrder extends GiftCardOrderFacts {
+    ID: string;
+    IssuingCompanyID: string;
+}
+/** What the caller hands us about each line. `ProductTypeCode` is resolved here, not by the caller. */
+export interface GiftCardOrderLine {
+    ID: string;
+    ProductID: string;
+    Quantity: number;
+    UnitPrice: number;
+    ReversesOrderLineID: string | null;
+    ShipToPersonID: string | null;
+    ShipToOrganizationID: string | null;
+}
+export interface GiftCardOutcome {
+    /** Accounts created by this call. Empty on a re-save, which is correct rather than a failure. */
+    Issued: Array<{
+        ID: string;
+        Code: string;
+        FaceValue: number;
+        OrderLineID: string;
+    }>;
+    /** Total face value minted. What the company now OWES — not what the customer paid. */
+    Liability: number;
+    /** Accounts voided because a reversal line sent cards back. */
+    Voided: string[];
+}
+/**
+ * Issue every gift card this order's lines confer.
+ *
+ * Returns an outcome rather than throwing when there is nothing to do — most orders sell no gift
+ * cards, and that is not an error. A genuine failure (a save the database refused) does throw, so
+ * the enclosing confirm transaction rolls back: an order that took the money and failed to mint the
+ * card has sold nothing, and that must not be committed.
+ */
+export declare function IssueGiftCards(order: GiftCardOrder, lines: GiftCardOrderLine[], provider: IMetadataProvider, user: UserInfo, options?: EntitySaveOptions): Promise<GiftCardOutcome>;
+//# sourceMappingURL=GiftCardEngine.d.ts.map

package/dist/GiftCardEngine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GiftCardEngine.d.ts","sourceRoot":"","sources":["../src/GiftCardEngine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,EAEH,iBAAiB,EACjB,iBAAiB,EAGjB,QAAQ,EACX,MAAM,sBAAsB,CAAC;AAK9B,OAAO,EAQH,KAAK,kBAAkB,EAC1B,MAAM,uBAAuB,CAAC;AAU/B,gDAAgD;AAChD,MAAM,WAAW,aAAc,SAAQ,kBAAkB;IACrD,EAAE,EAAE,MAAM,CAAC;IACX,gBAAgB,EAAE,MAAM,CAAC;CAC5B;AAED,uGAAuG;AACvG,MAAM,WAAW,iBAAiB;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,mBAAmB,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,oBAAoB,EAAE,MAAM,GAAG,IAAI,CAAC;CACvC;AAED,MAAM,WAAW,eAAe;IAC5B,iGAAiG;IACjG,MAAM,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACpF,uFAAuF;IACvF,SAAS,EAAE,MAAM,CAAC;IAClB,+DAA+D;IAC/D,MAAM,EAAE,MAAM,EAAE,CAAC;CACpB;AAgBD;;;;;;;GAOG;AACH,wBAAsB,cAAc,CAChC,KAAK,EAAE,aAAa,EACpB,KAAK,EAAE,iBAAiB,EAAE,EAC1B,QAAQ,EAAE,iBAAiB,EAC3B,IAAI,EAAE,QAAQ,EACd,OAAO,CAAC,EAAE,iBAAiB,GAC5B,OAAO,CAAC,eAAe,CAAC,CAkL1B"}

package/dist/GiftCardEngine.js

@@ -0,0 +1,197 @@
+/**
+ * Turn gift-card lines into StoredValueAccount rows and their opening ledger entries.
+ *
+ * The DECISIONS live in `GiftCardBehavior` and are unit-tested without a database. What lives here
+ * is the part that needs one: finding which lines are gift cards, minting codes that survive the
+ * UNIQUE constraint, and writing the account plus its `Issue` transaction as one act.
+ *
+ * IDEMPOTENCY IS THE WHOLE GAME. `OrderEntityServer.Save` re-runs on every save of an already
+ * confirmed order, and issuing a second set of cards would hand the customer free money that
+ * reconciles perfectly — the accounts exist, the ledger balances, the order is unchanged. So
+ * issuance keys on `IssuedFromOrderLineID`: a line that has already issued issues nothing. That is
+ * checked against the DATABASE rather than a flag in memory, because the second save is a different
+ * object than the first.
+ *
+ * CONNECTS TO:
+ *   PURE: GiftCardBehavior (+ its unit tests)
+ *   CODE: OrderEntityServer.issueGiftCards (lifecycle) · StoredValuePaymentProvider (redemption)
+ *   DOC:  plans/archive/bizapps-orders-master.md D4, D27, D44
+ */
+import { RunView, } from '@memberjunction/core';
+import { FormatGiftCardCode, GIFT_CARD_ALPHABET, GiftCardLiability, IsGiftCardLine, PlanGiftCardIssuance, PlanGiftCardVoid, } from './GiftCardBehavior.js';
+const STORED_VALUE_ACCOUNT_ENTITY = 'MJ_BizApps_Orders: Stored Value Accounts';
+const STORED_VALUE_TRANSACTION_ENTITY = 'MJ_BizApps_Orders: Stored Value Transactions';
+const PRODUCT_ENTITY = 'MJ_BizApps_Orders: Products';
+const PRODUCT_TYPE_ENTITY = 'MJ_BizApps_Orders: Product Types';
+const key = (id) => (id ?? '').toLowerCase();
+const quote = (ids) => [...new Set(ids.map((i) => `'${i}'`))].join(',');
+/** A crypto-quality character picker over the unambiguous alphabet. */
+function randomChar() {
+    // Web Crypto, not node:crypto — the shared tsconfig sets "types": [], so the node typings are
+    // not visible here. Same reason PaymentProviderBehavior uses crypto.subtle.
+    const buf = new Uint8Array(1);
+    // Rejection-sample so the alphabet stays uniform: 256 is not a multiple of 30, and taking the
+    // modulo without rejecting the tail would make the first 16 characters slightly likelier.
+    const limit = 256 - (256 % GIFT_CARD_ALPHABET.length);
+    for (;;) {
+        crypto.getRandomValues(buf);
+        if (buf[0] < limit)
+            return GIFT_CARD_ALPHABET[buf[0] % GIFT_CARD_ALPHABET.length];
+    }
+}
+/**
+ * Issue every gift card this order's lines confer.
+ *
+ * Returns an outcome rather than throwing when there is nothing to do — most orders sell no gift
+ * cards, and that is not an error. A genuine failure (a save the database refused) does throw, so
+ * the enclosing confirm transaction rolls back: an order that took the money and failed to mint the
+ * card has sold nothing, and that must not be committed.
+ */
+export async function IssueGiftCards(order, lines, provider, user, options) {
+    const out = { Issued: [], Liability: 0, Voided: [] };
+    if (!lines.length)
+        return out;
+    const rv = new RunView(provider);
+    // Which of these products are gift cards? One query for the product→type join rather than one
+    // per line: an order of sixty lines should not cost sixty round trips.
+    const productIDs = [...new Set(lines.map((l) => l.ProductID))];
+    const products = await rv.RunView({
+        EntityName: PRODUCT_ENTITY,
+        ExtraFilter: `ID IN (${quote(productIDs)})`,
+        ResultType: 'simple',
+    }, user);
+    const typeIDs = [...new Set((products.Results ?? []).map((p) => p.ProductTypeID))].filter(Boolean);
+    if (!typeIDs.length)
+        return out;
+    const types = await rv.RunView({
+        EntityName: PRODUCT_TYPE_ENTITY,
+        ExtraFilter: `ID IN (${quote(typeIDs)})`,
+        ResultType: 'simple',
+    }, user);
+    const codeByTypeID = new Map((types.Results ?? []).map((t) => [key(t.ID), t.Code]));
+    const typeCodeByProductID = new Map((products.Results ?? []).map((p) => [key(p.ID), codeByTypeID.get(key(p.ProductTypeID)) ?? null]));
+    const facts = (line) => ({
+        ID: line.ID,
+        ProductID: line.ProductID,
+        ProductTypeCode: typeCodeByProductID.get(key(line.ProductID)) ?? null,
+        Quantity: Number(line.Quantity ?? 0),
+        UnitPrice: Number(line.UnitPrice ?? 0),
+        ReversesOrderLineID: line.ReversesOrderLineID,
+        ShipToPersonID: line.ShipToPersonID,
+        ShipToOrganizationID: line.ShipToOrganizationID,
+    });
+    const giftCardLines = lines.filter((l) => IsGiftCardLine(facts(l)));
+    if (!giftCardLines.length)
+        return out;
+    // WHAT HAS ALREADY BEEN ISSUED. One query across every gift-card line on the order, so a re-save
+    // costs one round trip and mints nothing. Reversal lines are included because voiding needs to
+    // find the ORIGIN line's cards.
+    const relevantLineIDs = [
+        ...giftCardLines.map((l) => l.ID),
+        ...giftCardLines.map((l) => l.ReversesOrderLineID).filter((x) => !!x),
+    ];
+    const existing = await rv.RunView({
+        EntityName: STORED_VALUE_ACCOUNT_ENTITY,
+        ExtraFilter: `IssuedFromOrderLineID IN (${quote(relevantLineIDs)})`,
+        ResultType: 'simple',
+    }, user);
+    const issuedByLine = new Map();
+    for (const row of existing.Results ?? []) {
+        const k = key(row.IssuedFromOrderLineID);
+        if (!issuedByLine.has(k))
+            issuedByLine.set(k, []);
+        issuedByLine.get(k).push({ ID: row.ID, Status: row.Status });
+    }
+    for (const line of giftCardLines) {
+        // ── A REVERSAL: void, never mint ──────────────────────────────────────────────────────────
+        if (line.ReversesOrderLineID) {
+            const originCards = (issuedByLine.get(key(line.ReversesOrderLineID)) ?? []).filter((c) => c.Status === 'Active');
+            const toVoid = PlanGiftCardVoid(Number(line.Quantity ?? 0), originCards.length);
+            for (let i = 0; i < toVoid; i++) {
+                const account = await provider.GetEntityObject(STORED_VALUE_ACCOUNT_ENTITY, user);
+                if (!(await account.Load(originCards[i].ID))) {
+                    continue;
+                }
+                // Voided, not Depleted: the card was never spent, it was un-sold. Keeping the two
+                // apart is what lets breakage reporting tell a card the customer used from one the
+                // company took back.
+                account.Status = 'Voided';
+                const balanceBefore = Number(account.CurrentBalance ?? 0);
+                account.CurrentBalance = 0;
+                if (!(await account.Save(options))) {
+                    throw new Error(`Could not void gift card ${originCards[i].ID} for returned line ${line.ID}: ` +
+                        `${account.LatestResult?.CompleteMessage ?? 'no reason given'}`);
+                }
+                // The ledger has to show the money leaving, or the account's balance and its
+                // transaction history stop agreeing.
+                if (balanceBefore > 0) {
+                    await writeTransaction(provider, user, originCards[i].ID, 'Refund', -balanceBefore, 0, order.ID, options);
+                }
+                out.Voided.push(originCards[i].ID);
+            }
+            continue;
+        }
+        // ── An ordinary gift-card line ────────────────────────────────────────────────────────────
+        // Already issued? Then this is a re-save and there is nothing to do. Checked against the
+        // database, not memory: the second save is a different object than the first.
+        if ((issuedByLine.get(key(line.ID)) ?? []).length > 0)
+            continue;
+        const plan = PlanGiftCardIssuance(facts(line), order);
+        if (!plan.Cards.length) {
+            // A gift-card product that issues nothing is worth failing over rather than shrugging
+            // at — a zero-value or fractional-quantity card line means somebody sold something that
+            // cannot exist, and letting it through books revenue against no instrument.
+            throw new Error(`Order line ${line.ID} is a gift-card product but issues no card (${plan.Refusal}). ` +
+                `A gift card needs a whole positive quantity and a face value above zero.`);
+        }
+        for (const card of plan.Cards) {
+            const account = await provider.GetEntityObject(STORED_VALUE_ACCOUNT_ENTITY, user);
+            account.NewRecord();
+            account.Code = FormatGiftCardCode(randomChar);
+            account.IssuingCompanyID = order.IssuingCompanyID;
+            account.InitialAmount = card.FaceValue;
+            account.CurrentBalance = card.FaceValue;
+            account.Status = 'Active';
+            account.IssuedFromOrderLineID = card.OrderLineID;
+            if (card.BeneficiaryPersonID)
+                account.BeneficiaryPersonID = card.BeneficiaryPersonID;
+            if (card.BeneficiaryOrganizationID) {
+                account.BeneficiaryOrganizationID = card.BeneficiaryOrganizationID;
+            }
+            // ExpiresAt stays null. Breakage and expiry are deferred (§21), and a card with an
+            // expiry nothing enforces would be worse than one with none.
+            if (!(await account.Save(options))) {
+                throw new Error(`Could not issue gift card ${card.Sequence} of ${plan.Cards.length} for line ` +
+                    `${card.OrderLineID}: ${account.LatestResult?.CompleteMessage ?? 'no reason given'}`);
+            }
+            const accountID = account.ID;
+            await writeTransaction(provider, user, accountID, 'Issue', card.FaceValue, card.FaceValue, order.ID, options);
+            out.Issued.push({
+                ID: accountID,
+                Code: account.Code,
+                FaceValue: card.FaceValue,
+                OrderLineID: card.OrderLineID,
+            });
+        }
+        out.Liability += GiftCardLiability(plan);
+    }
+    out.Liability = Math.round((out.Liability + Number.EPSILON) * 100) / 100;
+    return out;
+}
+/** One signed movement on a card's ledger. */
+async function writeTransaction(provider, user, storedValueAccountID, type, amount, balanceAfter, relatedOrderHeaderID, options) {
+    const txn = await provider.GetEntityObject(STORED_VALUE_TRANSACTION_ENTITY, user);
+    txn.NewRecord();
+    txn.StoredValueAccountID = storedValueAccountID;
+    txn.TransactionType = type;
+    txn.Amount = amount;
+    txn.BalanceAfter = balanceAfter;
+    if (relatedOrderHeaderID)
+        txn.RelatedOrderHeaderID = relatedOrderHeaderID;
+    txn.OccurredAt = new Date();
+    if (!(await txn.Save(options))) {
+        throw new Error(`Could not write the ${type} transaction for stored-value account ${storedValueAccountID}: ` +
+            `${txn.LatestResult?.CompleteMessage ?? 'no reason given'}`);
+    }
+}
+//# sourceMappingURL=GiftCardEngine.js.map

package/dist/GiftCardEngine.js.map

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

package/dist/GuestOrderClaimDriver.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @fileoverview Guest Order Claim Driver
+ *
+ * Implements the BaseIdentityClaimDriver interface for BizApps Orders guest orders.
+ * When a guest redeems an order claim token, this driver links the OrderHeader (and any
+ * associated EntitlementGrants) to the authenticated user's Person record.
+ *
+ * @module @mj-biz-apps/orders-core-entities-server/GuestOrderClaimDriver
+ */
+import { BaseIdentityClaimDriver, type ClaimContext, type ClaimRedeemContext, type ClaimResult } from './identityClaimContracts.js';
+/**
+ * Pluggable driver for GuestOrder identity claims.
+ */
+export declare class GuestOrderClaimDriver extends BaseIdentityClaimDriver {
+    /**
+     * Hook called after a guest order claim is created.
+     */
+    OnCreate(context: ClaimContext): Promise<void>;
+    /**
+     * Hook called when a guest order claim is redeemed by an authenticated user.
+     */
+    OnClaim(context: ClaimRedeemContext): Promise<ClaimResult>;
+    /**
+     * Hook called when a guest order claim is revoked.
+     */
+    OnRevoke(context: ClaimContext): Promise<void>;
+    /**
+     * Hook called when a guest order claim expires.
+     */
+    OnExpire(context: ClaimContext): Promise<void>;
+}
+/**
+ * Registration helper to ensure class factory decorator executes.
+ */
+export declare function LoadGuestOrderClaimDriver(): void;
+//# sourceMappingURL=GuestOrderClaimDriver.d.ts.map

package/dist/GuestOrderClaimDriver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GuestOrderClaimDriver.d.ts","sourceRoot":"","sources":["../src/GuestOrderClaimDriver.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAQH,OAAO,EACH,uBAAuB,EACvB,KAAK,YAAY,EACjB,KAAK,kBAAkB,EACvB,KAAK,WAAW,EACnB,MAAM,6BAA6B,CAAC;AAUrC;;GAEG;AACH,qBACa,qBAAsB,SAAQ,uBAAuB;IAC9D;;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;IAiHvE;;OAEG;IACU,QAAQ,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAI3D;;OAEG;IACU,QAAQ,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;CAG9D;AAED;;GAEG;AACH,wBAAgB,yBAAyB,IAAI,IAAI,CAEhD"}

package/dist/GuestOrderClaimDriver.js

@@ -0,0 +1,161 @@
+/**
+ * @fileoverview Guest Order Claim Driver
+ *
+ * Implements the BaseIdentityClaimDriver interface for BizApps Orders guest orders.
+ * When a guest redeems an order claim token, this driver links the OrderHeader (and any
+ * associated EntitlementGrants) to the authenticated user's Person record.
+ *
+ * @module @mj-biz-apps/orders-core-entities-server/GuestOrderClaimDriver
+ */
+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';
+// Local fallback — see sql-guards.ts. Restore to '@memberjunction/global' once published.
+import { EscapeSQLString } from './sql-guards.js';
+import { Metadata, RunView } 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 ORDER_HEADER_ENTITY = 'MJ_BizApps_Orders: Order Headers';
+const ENTITLEMENT_GRANT_ENTITY = 'MJ_BizApps_Orders: Entitlement Grants';
+/**
+ * Pluggable driver for GuestOrder identity claims.
+ */
+let GuestOrderClaimDriver = class GuestOrderClaimDriver extends BaseIdentityClaimDriver {
+    /**
+     * Hook called after a guest order claim is created.
+     */
+    async OnCreate(context) {
+        // Claim registered in pending state
+    }
+    /**
+     * Hook called when a guest order claim is redeemed by an authenticated user.
+     */
+    async OnClaim(context) {
+        const { Claim, User } = context;
+        const provider = Claim.ProviderToUse;
+        let orderID = Claim.RecordID;
+        if (!orderID && Claim.PayloadJSON) {
+            try {
+                const payload = JSON.parse(Claim.PayloadJSON);
+                if (typeof payload.OrderID === 'string') {
+                    orderID = payload.OrderID;
+                }
+                else if (typeof payload.orderId === 'string') {
+                    orderID = payload.orderId;
+                }
+            }
+            catch {
+                // Ignore payload parse errors
+            }
+        }
+        if (!orderID) {
+            return {
+                Success: false,
+                ErrorMessage: 'Claim does not reference an OrderHeader RecordID'
+            };
+        }
+        const md = new Metadata();
+        const order = await md.GetEntityObject(ORDER_HEADER_ENTITY, User);
+        const loaded = await order.Load(orderID);
+        if (!loaded) {
+            return {
+                Success: false,
+                ErrorMessage: `Order with ID ${orderID} not found`
+            };
+        }
+        const personID = await resolvePersonID(User, provider);
+        if (!personID) {
+            return {
+                Success: false,
+                ErrorMessage: `Could not resolve Person record for redeeming user ${User?.Email || 'unknown'}`
+            };
+        }
+        // Link Order Header parties to the redeeming person if unset or different
+        let orderModified = false;
+        if (!order.BillToPersonID || order.BillToPersonID !== personID) {
+            order.BillToPersonID = personID;
+            orderModified = true;
+        }
+        if (!order.ShipToPersonID || order.ShipToPersonID !== personID) {
+            order.ShipToPersonID = personID;
+            orderModified = true;
+        }
+        if (orderModified) {
+            const saved = await order.Save();
+            if (!saved) {
+                return {
+                    Success: false,
+                    ErrorMessage: `Failed to update Order with redeeming PersonID: ${order.LatestResult?.Message ?? 'Unknown save error'}`
+                };
+            }
+        }
+        // Cascade to any EntitlementGrants hanging off this order's lines
+        const updatedGrants = [];
+        try {
+            const runViewProvider = (provider && 'RunView' in provider) ? provider : null;
+            const rv = new RunView(runViewProvider);
+            const escapedOrderID = EscapeSQLString(orderID);
+            const grantResult = await rv.RunView({
+                EntityName: ENTITLEMENT_GRANT_ENTITY,
+                ExtraFilter: `OrderLineID IN (SELECT ID FROM vwOrderLines WHERE OrderID = '${escapedOrderID}')`,
+                ResultType: 'simple'
+            }, User);
+            if (grantResult.Success && grantResult.Results && grantResult.Results.length > 0) {
+                for (const row of grantResult.Results) {
+                    const grant = await md.GetEntityObject(ENTITLEMENT_GRANT_ENTITY, User);
+                    if (await grant.Load(row.ID)) {
+                        grant.BeneficiaryPersonID = personID;
+                        if (grant.Status !== 'Active') {
+                            grant.Status = 'Active';
+                            grant.ProvisionedAt = new Date();
+                        }
+                        if (await grant.Save()) {
+                            updatedGrants.push(grant.ID);
+                        }
+                    }
+                }
+            }
+        }
+        catch {
+            // Entitlement grant cascade failure should not block overall order link
+        }
+        return {
+            Success: true,
+            Data: {
+                OrderID: order.ID,
+                OrderNumber: order.OrderNumber,
+                PersonID: personID,
+                CascadedGrants: updatedGrants
+            }
+        };
+    }
+    /**
+     * Hook called when a guest order claim is revoked.
+     */
+    async OnRevoke(context) {
+        // Safe teardown / no-op
+    }
+    /**
+     * Hook called when a guest order claim expires.
+     */
+    async OnExpire(context) {
+        // Safe teardown / no-op
+    }
+};
+GuestOrderClaimDriver = __decorate([
+    RegisterClass(BaseIdentityClaimDriver, 'GuestOrderClaimDriver')
+], GuestOrderClaimDriver);
+export { GuestOrderClaimDriver };
+/**
+ * Registration helper to ensure class factory decorator executes.
+ */
+export function LoadGuestOrderClaimDriver() {
+    // Explicit trigger for bundler tree-shaking preservation
+}
+//# sourceMappingURL=GuestOrderClaimDriver.js.map

package/dist/GuestOrderClaimDriver.js.map

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