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

package/dist/SpawnRenewalsOperation.js

@@ -0,0 +1,295 @@
+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;
+};
+/**
+ * Orders.SpawnRenewals — place the renewal orders that are due (plan D55).
+ *
+ * The last piece of the subscription lifecycle. `AutoRenew` and `RenewalLeadDays` were columns with
+ * no consumer: a subscription would reach the end of its term and simply stop, with nothing to
+ * continue it.
+ *
+ * THE DESIGN QUESTION THIS ANSWERS
+ * "Is a renewal an order the customer approves, or one the system places for them?" — BOTH, and
+ * `AutoRenew` is the switch. `AutoRenew = true` means the customer has already consented to
+ * recurring billing, so the system places a CONFIRMED order: it books, it invoices, and coverage
+ * continues without a gap. `AutoRenew = false` means it does not renew, full stop — this operation
+ * skips it and the term simply ends. Reminder-and-approve for the second case is a communication
+ * flow, not a booking one, and does not belong here.
+ *
+ * The order is placed at LEAD TIME, not on the expiry date, which is how subscription billing
+ * actually works: the invoice goes out before the period it covers. Revenue is not affected — the
+ * booking entry credits Deferred Revenue and the recognition entries are dated into the new term's
+ * own window (D14).
+ *
+ * IDEMPOTENCY, which a scheduled job makes non-negotiable
+ * Two independent guards, because this runs unattended and a double-spawn double-bills a customer:
+ *   1. the SELECTION only finds subscriptions whose LATEST term ends inside the window — once a
+ *      renewal is booked, term N+1 exists and the subscription no longer qualifies;
+ *   2. an explicit check for an existing order with `RenewsSubscriptionID` covering that term,
+ *      which catches the case where a prior pass booked the order but its term write failed.
+ * Running the operation twice in a row is a no-op, and that is asserted by the check suite.
+ *
+ * CONNECTS TO:
+ *   BOOKING: OrderEntityServer.Save — the renewal order goes through the ordinary confirm path,
+ *            so extension, term creation, GL resolution and recognition are all the SAME code
+ *   POLICY:  SubscriptionBehavior (IsRenewal bypasses ConcurrencyMode — a renewal is not a second
+ *            concurrent subscription, it is this one continuing)
+ *   TABLES:  __mj_BizAppsOrders.{Subscription,SubscriptionTerm,SubscriptionType,OrderHeader,OrderLine}
+ */
+import { BaseRemotableOperation, LogError, RunView, } from '@memberjunction/core';
+import { RegisterClass } from '@memberjunction/global';
+import { RequireOptionalUUID } from './sql-guards.js';
+const SUBSCRIPTION_ENTITY = 'MJ_BizApps_Orders: Subscriptions';
+const SUBSCRIPTION_TERM_ENTITY = 'MJ_BizApps_Orders: Subscription Terms';
+const SUBSCRIPTION_TYPE_ENTITY = 'MJ_BizApps_Orders: Subscription Types';
+const SUBSCRIPTION_EVENT_ENTITY = 'MJ_BizApps_Orders: Subscription Events';
+const ORDER_HEADER_ENTITY = 'MJ_BizApps_Orders: Order Headers';
+const ORDER_LINE_ENTITY = 'MJ_BizApps_Orders: Order Lines';
+let SpawnRenewalsOperation = class SpawnRenewalsOperation extends BaseRemotableOperation {
+    constructor() {
+        super(...arguments);
+        this.OperationKey = 'Orders.SpawnRenewals';
+    }
+    async InternalExecute(input, provider, user) {
+        // Caller-supplied ids reach SQL filter text downstream. Validated here,
+        // at the boundary, so every frame below this one can trust them.
+        RequireOptionalUUID(input.SubscriptionID, 'SubscriptionID');
+        const asOf = input.AsOfDate ? new Date(input.AsOfDate) : new Date();
+        const candidates = await this.findDue(provider, user, asOf, input.SubscriptionID);
+        const out = { Success: true, Candidates: [], Placed: 0, Skipped: 0 };
+        const limit = input.MaxCount ?? Number.MAX_SAFE_INTEGER;
+        for (const due of candidates) {
+            if (out.Placed >= limit)
+                break;
+            const candidate = {
+                SubscriptionID: due.SubscriptionID,
+                SubscriptionNumber: due.SubscriptionNumber,
+                ProductID: due.ProductID,
+                CurrentTermEnd: due.TermEndDate,
+                LeadDays: due.SubscriptionRenewalLeadDays ?? due.TypeRenewalLeadDays ?? 0,
+            };
+            out.Candidates.push(candidate);
+            // Second idempotency guard — see the header. Cheap, and it is the one that saves a
+            // customer from being billed twice if a prior pass half-completed.
+            if (await this.alreadyRenewed(provider, user, due)) {
+                candidate.SkippedReason = 'a renewal order already exists for this term';
+                out.Skipped++;
+                continue;
+            }
+            if (input.Preview) {
+                out.Skipped++;
+                continue;
+            }
+            try {
+                const order = await this.placeRenewal(provider, user, due);
+                candidate.OrderID = order.ID;
+                candidate.OrderNumber = order.Number;
+                out.Placed++;
+            }
+            catch (err) {
+                // One subscription's failure must not stop the batch — an unattended job that
+                // aborts on the first bad row silently stops renewing everyone behind it.
+                const message = err instanceof Error ? err.message : String(err);
+                LogError(`Orders.SpawnRenewals: ${due.SubscriptionNumber} failed: ${message}`);
+                candidate.SkippedReason = message;
+                out.Skipped++;
+            }
+        }
+        out.Message =
+            `${out.Candidates.length} subscription(s) due as of ${asOf.toISOString().slice(0, 10)}; ` +
+                `${out.Placed} renewal order(s) placed, ${out.Skipped} skipped.`;
+        return out;
+    }
+    /**
+     * Subscriptions whose latest term expires within their effective lead window.
+     *
+     * Raw SQL rather than RunView because the selection is inherently a JOIN across four tables with
+     * a "latest term per subscription" window — expressible in one statement and awkward as several
+     * round trips. `RenewalLeadDays` falls back from the subscription to its type, which is the
+     * inheritance rule the schema documents.
+     */
+    async findDue(provider, user, asOf, subscriptionID) {
+        const db = provider;
+        const asOfDate = asOf.toISOString().slice(0, 10);
+        const only = subscriptionID ? `AND s.ID = '${subscriptionID}'` : '';
+        const rows = (await db.ExecuteSQL(`
+            WITH latest AS (
+                SELECT st.*, ROW_NUMBER() OVER (PARTITION BY st.SubscriptionID ORDER BY st.TermNumber DESC) AS rn
+                FROM __mj_BizAppsOrders.SubscriptionTerm st
+            )
+            SELECT
+                s.ID                  AS SubscriptionID,
+                s.SubscriptionNumber,
+                s.CompanyID,
+                s.ProductID,
+                s.HolderOrganizationID,
+                s.BeneficiaryPersonID,
+                s.RenewalLeadDays     AS SubscriptionRenewalLeadDays,
+                t.RenewalLeadDays     AS TypeRenewalLeadDays,
+                l.ID                  AS TermID,
+                l.TermNumber,
+                l.EndDate             AS TermEndDate,
+                l.OrderLineID
+            FROM __mj_BizAppsOrders.Subscription s
+            JOIN __mj_BizAppsOrders.SubscriptionType t ON t.ID = s.SubscriptionTypeID
+            JOIN latest l ON l.SubscriptionID = s.ID AND l.rn = 1
+            WHERE s.AutoRenew = 1
+              AND s.Status IN ('Active','Trialing')
+              AND l.Status IN ('Scheduled','Active')
+              -- Due when the expiry falls inside the lead window. The lower bound keeps a long-
+              -- lapsed subscription from being silently revived months later by a routine pass.
+              AND l.EndDate >= DATEADD(DAY, -1, '${asOfDate}')
+              AND l.EndDate <= DATEADD(DAY, COALESCE(s.RenewalLeadDays, t.RenewalLeadDays, 0), '${asOfDate}')
+              ${only}
+            ORDER BY l.EndDate, s.SubscriptionNumber
+        `));
+        return Array.isArray(rows) ? rows : [];
+    }
+    /** True when an order already exists that renews this subscription past the expiring term. */
+    async alreadyRenewed(provider, user, due) {
+        const rv = new RunView(provider);
+        const result = await rv.RunView({
+            EntityName: ORDER_LINE_ENTITY,
+            ExtraFilter: `RenewsSubscriptionID='${due.SubscriptionID}'`,
+            Fields: ['ID'],
+            ResultType: 'simple',
+            BypassCache: true,
+        }, user);
+        const orders = result?.Results ?? [];
+        if (orders.length === 0)
+            return false;
+        // An order exists, but a subscription renews many times over its life — only a renewal that
+        // produced a term BEYOND the expiring one counts as this cycle's.
+        const db = provider;
+        const beyond = (await db.ExecuteSQL(`
+            SELECT TOP 1 st.ID
+            FROM __mj_BizAppsOrders.SubscriptionTerm st
+            WHERE st.SubscriptionID = '${due.SubscriptionID}' AND st.TermNumber > ${due.TermNumber}
+        `));
+        if (Array.isArray(beyond) && beyond.length > 0)
+            return true;
+        // No later term, but a renewal order exists — a prior pass booked the order and then failed
+        // before the term landed. Report rather than silently re-billing.
+        return true;
+    }
+    /**
+     * Place the renewal as an ordinary confirmed order.
+     *
+     * Deliberately NOT a special write path: routing it through `OrderEntityServer.Save` means the
+     * extension, the new term, GL resolution, the recognition schedule and the all-or-none
+     * guarantee are the same code that handles a customer purchase. A bespoke renewal writer would
+     * be a second implementation of booking, drifting from the first.
+     */
+    async placeRenewal(provider, user, due) {
+        const source = await this.loadSourceLine(provider, user, due.OrderLineID);
+        if (!source) {
+            throw new Error(`The order line that bought term ${due.TermNumber} (${due.OrderLineID}) no longer exists, ` +
+                `so there is no price to renew at.`);
+        }
+        const dbProvider = provider;
+        await dbProvider.BeginTransaction();
+        try {
+            const order = await provider.GetEntityObject(ORDER_HEADER_ENTITY, user);
+            order.NewRecord();
+            order.OrderType = 'Sale';
+            // Dated the day AFTER the expiring term, so the new term starts where the old one ends
+            // and the ledger shows the sale in the period it belongs to — not on the day the job
+            // happened to run.
+            order.OrderDate = this.dayAfter(due.TermEndDate);
+            order.CompanyID = due.CompanyID;
+            order.BillToOrganizationID = due.HolderOrganizationID;
+            order.BillToPersonID = due.BeneficiaryPersonID;
+            order.Notes = `Automatic renewal of ${due.SubscriptionNumber} (term ${due.TermNumber + 1})`;
+            const line = await provider.GetEntityObject(ORDER_LINE_ENTITY, user);
+            line.NewRecord();
+            line.ProductID = due.ProductID;
+            line.LineNumber = 1;
+            // Per-LINE (D61): renewal is a line-level act, so one order could renew several
+            // subscriptions. Naming the target also removes the guesswork from resolution — the
+            // engine renews exactly this one rather than searching by subscriber and product.
+            line.RenewsSubscriptionID = due.SubscriptionID;
+            // The subscription's own subscriber, carried onto the line's ship-to so the renewal
+            // lands on the same holder even when the order's customer differs.
+            line.ShipToOrganizationID = due.HolderOrganizationID;
+            line.ShipToPersonID = due.BeneficiaryPersonID;
+            // Renew at what they last paid. Re-pricing from the current ProductPrice is a policy
+            // decision (grandfathering, notice periods) that nobody has made yet — carrying the
+            // price forward is the choice that cannot surprise a customer.
+            line.Quantity = this.renewalQuantity(source);
+            line.UnitPrice = source.UnitPrice;
+            line.DiscountPct = source.DiscountPct ?? 0;
+            // Attached rather than assigned — see the note in CancelSubscriptionOperation.
+            order.Lines.Add(line);
+            order.Status = 'Confirmed';
+            if (!(await order.Save())) {
+                throw new Error(`Failed to book the renewal order: ${order.LatestResult?.CompleteMessage ?? 'unknown error'}`);
+            }
+            await this.logEvent(provider, user, due, order.ID);
+            await dbProvider.CommitTransaction();
+            return { ID: order.ID, Number: order.OrderNumber };
+        }
+        catch (err) {
+            try {
+                await dbProvider.RollbackTransaction();
+            }
+            catch (rollbackErr) {
+                LogError(`Rollback failed after renewal spawn error: ${rollbackErr}`);
+            }
+            throw err;
+        }
+    }
+    /**
+     * Quantity for the renewal.
+     *
+     * A PRORATED source line carries a fractional quantity — the short first period into a calendar
+     * anchor (D54). Renewing at that fraction would bill half a year forever. A renewal is always a
+     * FULL period, so the fraction is dropped and the quantity rounds up to whole units.
+     */
+    renewalQuantity(source) {
+        const quantity = Number(source.Quantity);
+        return quantity > 0 && quantity < 1 ? 1 : Math.round(quantity);
+    }
+    dayAfter(date) {
+        const d = new Date(date);
+        return new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate() + 1));
+    }
+    async loadSourceLine(provider, user, orderLineID) {
+        const rv = new RunView(provider);
+        const result = await rv.RunView({
+            EntityName: ORDER_LINE_ENTITY,
+            ExtraFilter: `ID='${orderLineID}'`,
+            Fields: ['ID', 'Quantity', 'UnitPrice', 'DiscountPct'],
+            ResultType: 'simple',
+            BypassCache: true,
+        }, user);
+        return result?.Results?.[0] ?? null;
+    }
+    async logEvent(provider, user, due, orderID) {
+        const event = await provider.GetEntityObject(SUBSCRIPTION_EVENT_ENTITY, user);
+        event.NewRecord();
+        event.SubscriptionID = due.SubscriptionID;
+        event.EventType = 'RenewalOrderSpawned';
+        event.OccurredAt = new Date();
+        event.RelatedOrderHeaderID = orderID;
+        event.Set('EventData', JSON.stringify({
+            RenewedTermNumber: due.TermNumber,
+            ExpiringTermEnd: due.TermEndDate,
+            LeadDays: due.SubscriptionRenewalLeadDays ?? due.TypeRenewalLeadDays ?? 0,
+        }));
+        if (!(await event.Save())) {
+            throw new Error(`Failed to log the renewal event: ${event.LatestResult?.CompleteMessage ?? 'unknown error'}`);
+        }
+    }
+};
+SpawnRenewalsOperation = __decorate([
+    RegisterClass(BaseRemotableOperation, 'Orders.SpawnRenewals')
+], SpawnRenewalsOperation);
+export { SpawnRenewalsOperation };
+/** Tree-shaking anchor — called from the server bootstrap so the registration is retained. */
+export function LoadSpawnRenewalsOperation() {
+    // intentionally empty
+}
+//# sourceMappingURL=SpawnRenewalsOperation.js.map

package/dist/SpawnRenewalsOperation.js.map

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

package/dist/StoredValuePaymentProvider.d.ts

@@ -0,0 +1,52 @@
+import { BasePaymentProvider, type CaptureRequest, type CaptureResult, type CreateIntentRequest, type CreateIntentResult, type RefundRequest, type RefundResult } from './BasePaymentProvider.js';
+/**
+ * Which internal balance is being drawn down. Set by the caller from the `PaymentDetail` it is acting
+ * on, because that row is what already distinguishes the two.
+ */
+export interface StoredValueTarget {
+    /** A gift card, by its account id. */
+    StoredValueAccountID?: string | null;
+    /** An over-paid order whose negative balance is the credit. */
+    SourceOrderHeaderID?: string | null;
+}
+export declare class StoredValuePaymentProvider extends BasePaymentProvider {
+    /** Internal money. Nothing external tells us about it. */
+    get HandledEventKinds(): readonly string[];
+    /**
+     * Confirm there is enough, before anything is spent.
+     *
+     * The balance check happens HERE rather than at capture because refusing early is the difference
+     * between "this card cannot cover it" and a half-applied payment. It is deliberately NOT a
+     * reservation: nothing is locked between this call and the capture, so a genuinely concurrent spend
+     * of the same card could still overdraw it. The guard against that is the capture's own re-read plus
+     * the balance's own constraint — the same shape as the order counter, where the authoritative check
+     * is the one inside the writing transaction.
+     */
+    CreateIntent(request: CreateIntentRequest & StoredValueTarget): Promise<CreateIntentResult>;
+    /**
+     * Spend it.
+     *
+     * RE-READS THE BALANCE. The check in `CreateIntent` is a courtesy that produces a good error
+     * message; this one is the one that protects the money, because it runs inside the caller's
+     * transaction alongside the write that spends it.
+     */
+    Capture(request: CaptureRequest & StoredValueTarget): Promise<CaptureResult>;
+    /**
+     * Refunding TO an internal balance puts the money back where it came from.
+     *
+     * Always succeeds at this layer for the same reason the manual driver's does: nothing external has
+     * to agree. The row that actually restores the balance is written by the caller, in its transaction.
+     */
+    Refund(request: RefundRequest): Promise<RefundResult>;
+    /**
+     * What is actually available, from whichever of the two shapes this is.
+     *
+     * Returns a LABEL as well as a number so the refusals above can name the thing that was short —
+     * "gift card ABC-123" or "order ORD-000042" — rather than saying "the balance", which tells a
+     * person nothing about where to look.
+     */
+    private available;
+}
+/** Tree-shaking anchor — call from the server bootstrap so @RegisterClass is retained. */
+export declare function LoadStoredValuePaymentProvider(): void;
+//# sourceMappingURL=StoredValuePaymentProvider.d.ts.map

package/dist/StoredValuePaymentProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"StoredValuePaymentProvider.d.ts","sourceRoot":"","sources":["../src/StoredValuePaymentProvider.ts"],"names":[],"mappings":"AAsCA,OAAO,EACH,mBAAmB,EACnB,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,EACvB,KAAK,aAAa,EAClB,KAAK,YAAY,EACpB,MAAM,0BAA0B,CAAC;AAKlC;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAC9B,sCAAsC;IACtC,oBAAoB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,+DAA+D;IAC/D,mBAAmB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACvC;AAED,qBACa,0BAA2B,SAAQ,mBAAmB;IAC/D,0DAA0D;IAC1D,IAAoB,iBAAiB,IAAI,SAAS,MAAM,EAAE,CAEzD;IAED;;;;;;;;;OASG;IACmB,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,iBAAiB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAyBjH;;;;;;OAMG;IACmB,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,iBAAiB,GAAG,OAAO,CAAC,aAAa,CAAC;IA2BlG;;;;;OAKG;IACmB,MAAM,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC;IAQ3E;;;;;;OAMG;YACW,SAAS;CAgF1B;AAED,0FAA0F;AAC1F,wBAAgB,8BAA8B,IAAI,IAAI,CAErD"}

package/dist/StoredValuePaymentProvider.js

@@ -0,0 +1,205 @@
+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;
+};
+/**
+ * StoredValuePaymentProvider — money we already hold, in the two forms it takes.
+ *
+ * ONE DRIVER, TWO INSTRUMENT SHAPES, and that was a deliberate call (Amith 2026-07-30). A gift card and
+ * an over-payment are genuinely different things:
+ *
+ *   GIFT CARD        a `StoredValueAccount` with a redeemable `Code`, a stored balance and a
+ *                    transaction ledger. A BEARER instrument — transferable, possibly to somebody who
+ *                    was never a customer — which is exactly why it cannot be modelled as an order's
+ *                    negative balance: an order belongs to the party who placed it. Selling one is
+ *                    DEFERRED REVENUE; you took cash and owe goods.
+ *
+ *   ACCOUNT CREDIT   an over-paid order's negative balance (D68). No separate record, because the
+ *                    balance already has a home and a second copy could disagree with it. Not revenue
+ *                    at all — a customer deposit.
+ *
+ * They differ in ownership, transferability, expiry and accounting treatment. What they do NOT differ in
+ * is the MECHANICS of spending them: check a balance we control, decrement it, record the movement, no
+ * network. That shared half is why they are one driver rather than two — and why the split lives in
+ * `PaymentDetail` (`StoredValueAccountID` versus `SourceOrderHeaderID`), which is where an instrument's
+ * identity belongs.
+ *
+ * THIS DRIVER REFUSES MORE THAN IT MOVES, and every refusal is a case where the alternative silently
+ * creates money: spending an expired card, spending past a balance, spending a credit that belongs to
+ * somebody else. A gateway can afford to be optimistic because a real institution will decline; here we
+ * ARE the institution.
+ *
+ * WHAT IT DOES NOT DO. It never writes the journal entry — `PaymentHeaderEntityServer` owns that, as for
+ * every other tender. Nor does it ISSUE a gift card; that happens when one is sold, on the ordinary
+ * order path, because a gift card is a product.
+ *
+ * CONNECTS TO:
+ *   BASE:  ./BasePaymentProvider.ts
+ *   AKIN:  ./ApplyAccountCreditOperation.ts — the operation that spends a credit across orders (D68)
+ *   DOC:   plans/archive/bizapps-orders-master.md D19, D38, D68
+ */
+import { RegisterClass } from '@memberjunction/global';
+import { RunView } from '@memberjunction/core';
+import { BasePaymentProvider, } from './BasePaymentProvider.js';
+const STORED_VALUE_ACCOUNT_ENTITY = 'MJ_BizApps_Orders: Stored Value Accounts';
+const ORDER_ENTITY = 'MJ_BizApps_Orders: Order Headers';
+let StoredValuePaymentProvider = class StoredValuePaymentProvider extends BasePaymentProvider {
+    /** Internal money. Nothing external tells us about it. */
+    get HandledEventKinds() {
+        return [];
+    }
+    /**
+     * Confirm there is enough, before anything is spent.
+     *
+     * The balance check happens HERE rather than at capture because refusing early is the difference
+     * between "this card cannot cover it" and a half-applied payment. It is deliberately NOT a
+     * reservation: nothing is locked between this call and the capture, so a genuinely concurrent spend
+     * of the same card could still overdraw it. The guard against that is the capture's own re-read plus
+     * the balance's own constraint — the same shape as the order counter, where the authoritative check
+     * is the one inside the writing transaction.
+     */
+    async CreateIntent(request) {
+        if (request.Amount <= 0) {
+            return { Success: false, Reason: `Cannot draw ${request.Amount} from an internal balance.` };
+        }
+        const available = await this.available(request);
+        if (!available.Found)
+            return { Success: false, Reason: available.Reason };
+        if (available.Balance < request.Amount) {
+            return {
+                Success: false,
+                Reason: `${available.Label} holds ${available.Balance.toFixed(2)}, which does not cover ` +
+                    `${request.Amount.toFixed(2)}. Apply what is there and settle the remainder with ` +
+                    `another tender rather than over-drawing it.`,
+            };
+        }
+        return {
+            Success: true,
+            ProviderIntentID: `sv_${crypto.randomUUID()}`,
+            // Immediately payable: the money is ours to move, and there is no third party to wait for.
+            Status: 'RequiresPayment',
+        };
+    }
+    /**
+     * Spend it.
+     *
+     * RE-READS THE BALANCE. The check in `CreateIntent` is a courtesy that produces a good error
+     * message; this one is the one that protects the money, because it runs inside the caller's
+     * transaction alongside the write that spends it.
+     */
+    async Capture(request) {
+        const amount = request.Amount ?? 0;
+        if (amount <= 0) {
+            return { Success: false, Reason: 'An internal-tender capture needs the amount being drawn.' };
+        }
+        const available = await this.available(request);
+        if (!available.Found)
+            return { Success: false, Reason: available.Reason };
+        if (available.Balance < amount) {
+            return {
+                Success: false,
+                Reason: `${available.Label} now holds only ${available.Balance.toFixed(2)} against a ` +
+                    `${amount.toFixed(2)} draw — it changed after the intent was opened. Nothing was spent.`,
+            };
+        }
+        return {
+            Success: true,
+            Amount: amount,
+            // We are the institution, so there is no cut. Genuinely zero, not unknown.
+            FeeAmount: 0,
+            ProviderChargeID: request.ProviderIntentID,
+            Status: 'Succeeded',
+        };
+    }
+    /**
+     * Refunding TO an internal balance puts the money back where it came from.
+     *
+     * Always succeeds at this layer for the same reason the manual driver's does: nothing external has
+     * to agree. The row that actually restores the balance is written by the caller, in its transaction.
+     */
+    async Refund(request) {
+        const amount = request.Amount;
+        if (amount == null || amount <= 0) {
+            return { Success: false, Reason: 'An internal-tender refund needs the amount being restored.' };
+        }
+        return { Success: true, Amount: amount, ProviderRefundID: `sv_refund_${crypto.randomUUID()}` };
+    }
+    /**
+     * What is actually available, from whichever of the two shapes this is.
+     *
+     * Returns a LABEL as well as a number so the refusals above can name the thing that was short —
+     * "gift card ABC-123" or "order ORD-000042" — rather than saying "the balance", which tells a
+     * person nothing about where to look.
+     */
+    async available(target) {
+        const none = { Found: false, Balance: 0, Label: '' };
+        if (!this.Provider || !this.User) {
+            return { ...none, Reason: 'The stored-value driver was not given a provider to read balances with.' };
+        }
+        const rv = new RunView(this.Provider);
+        if (target.StoredValueAccountID) {
+            const result = await rv.RunView({
+                EntityName: STORED_VALUE_ACCOUNT_ENTITY,
+                ExtraFilter: `ID = '${target.StoredValueAccountID}'`,
+                ResultType: 'simple',
+            }, this.User);
+            const account = result?.Results?.[0];
+            if (!account) {
+                return { ...none, Reason: `No stored-value account ${target.StoredValueAccountID} exists.` };
+            }
+            const label = `Gift card ${account.Code}`;
+            if (account.Status !== 'Active') {
+                return { ...none, Reason: `${label} is ${account.Status}, so it cannot be spent.` };
+            }
+            // Expiry is checked HERE rather than left to a nightly sweep, because a card that expired
+            // this morning must not be spendable this afternoon just because nothing has run yet.
+            if (account.ExpiresAt && new Date(account.ExpiresAt).getTime() < Date.now()) {
+                return {
+                    ...none,
+                    Reason: `${label} expired on ${new Date(account.ExpiresAt).toISOString().slice(0, 10)}.`,
+                };
+            }
+            return { Found: true, Balance: Number(account.CurrentBalance ?? 0), Label: label };
+        }
+        if (target.SourceOrderHeaderID) {
+            const result = await rv.RunView({
+                EntityName: ORDER_ENTITY,
+                ExtraFilter: `ID = '${target.SourceOrderHeaderID}'`,
+                ResultType: 'simple',
+            }, this.User);
+            const order = result?.Results?.[0];
+            if (!order) {
+                return { ...none, Reason: `No order ${target.SourceOrderHeaderID} exists to draw credit from.` };
+            }
+            const balance = Number(order.Balance ?? 0);
+            const label = `Order ${order.OrderNumber}`;
+            if (balance >= 0) {
+                // A credit IS a negative balance (D68). A zero or positive balance means there is
+                // nothing owed to the customer — and saying so beats reporting "0.00 available", which
+                // reads as an empty wallet rather than as the wrong order.
+                return {
+                    ...none,
+                    Reason: `${label} has a balance of ${balance.toFixed(2)}, so it holds no credit. ` +
+                        `Account credit is an OVER-payment — a negative balance.`,
+                };
+            }
+            return { Found: true, Balance: Math.abs(balance), Label: `${label}'s credit` };
+        }
+        return {
+            ...none,
+            Reason: 'An internal-tender payment must name either a stored-value account or the over-paid ' +
+                'order whose credit is being spent.',
+        };
+    }
+};
+StoredValuePaymentProvider = __decorate([
+    RegisterClass(BasePaymentProvider, 'StoredValue')
+], StoredValuePaymentProvider);
+export { StoredValuePaymentProvider };
+/** Tree-shaking anchor — call from the server bootstrap so @RegisterClass is retained. */
+export function LoadStoredValuePaymentProvider() {
+    // intentionally empty
+}
+//# sourceMappingURL=StoredValuePaymentProvider.js.map

package/dist/StoredValuePaymentProvider.js.map

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

package/dist/StripeACHPaymentProvider.d.ts

@@ -0,0 +1,50 @@
+import { type CaptureRequest, type CaptureResult, type CreateIntentRequest, type WebhookEvent } from './BasePaymentProvider.js';
+import { StripePaymentProvider } from './StripePaymentProvider.js';
+import { type IntentStatus } from './PaymentProviderBehavior.js';
+export declare class StripeACHPaymentProvider extends StripePaymentProvider {
+    /**
+     * The declaration that changes who books the cash. See `BasePaymentProvider.SettlesAsynchronously` —
+     * with this true, a caller leaves the payment `Pending` and the webhook promotes it.
+     */
+    get SettlesAsynchronously(): boolean;
+    get HandledEventKinds(): readonly string[];
+    /** A submitted debit is already in flight; it never waits for an instrument the way a card does. */
+    protected get StubIntentStatus(): IntentStatus;
+    /** 0.8% capped at $5 — see `AchFeeEstimate` for why the stub reports a fee at all. */
+    protected StubFeeFor(amount: number, currencyCode: string): number;
+    /**
+     * Pin the intent to the bank-debit rail.
+     *
+     * EXPLICIT RATHER THAN `automatic_payment_methods`. Letting Stripe choose would make the rail a
+     * property of the account's dashboard settings, so the same code could open a card intent on one
+     * deployment and a bank debit on another — with a fee, a settlement delay and a reversal risk that
+     * differ by a factor of four and several days. The provider row says which rail this is; the
+     * request should say the same thing.
+     */
+    protected DecorateIntentBody(body: Record<string, string>, _request: CreateIntentRequest): void;
+    /**
+     * Ask the bank what happened. Nothing is captured here — see the header.
+     *
+     * REFUSES ON ANYTHING BUT `succeeded`, and the two refusals say different things on purpose.
+     * "Still processing" is the ordinary case — somebody captured too early, and they should wait for
+     * the webhook — while a failure means the debit will not clear and waiting is pointless. Both come
+     * back as refusals rather than exceptions, because neither is a fault: the gateway answered.
+     */
+    Capture(request: CaptureRequest): Promise<CaptureResult>;
+    /**
+     * Read a `charge.failed`, which the base driver has no reason to know about.
+     *
+     * THIS IS THE RETURN, and it is the event this whole rail exists to survive. It can arrive after
+     * the payment has been booked, in which case `charge.failed` is the only notice that money which
+     * appeared to arrive has gone back out. The base handles `payment_intent.*` and `charge.refunded`
+     * correctly, so everything else defers to it.
+     *
+     * The failure MESSAGE is carried through verbatim. Stripe writes it for a human ("insufficient
+     * funds", "no account"), and it ends up on the reversing payment's reason — which is the only place
+     * anyone reconciling next month will look.
+     */
+    ParseWebhookEvent(rawBody: string): WebhookEvent | null;
+}
+/** Tree-shaking anchor — call from the server bootstrap so @RegisterClass is retained. */
+export declare function LoadStripeACHPaymentProvider(): void;
+//# sourceMappingURL=StripeACHPaymentProvider.d.ts.map

package/dist/StripeACHPaymentProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"StripeACHPaymentProvider.d.ts","sourceRoot":"","sources":["../src/StripeACHPaymentProvider.ts"],"names":[],"mappings":"AAgDA,OAAO,EAAuB,KAAK,cAAc,EAAE,KAAK,aAAa,EAAE,KAAK,mBAAmB,EAAE,KAAK,YAAY,EAAE,MAAM,0BAA0B,CAAC;AACrJ,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AACnE,OAAO,EAAkC,KAAK,YAAY,EAAE,MAAM,8BAA8B,CAAC;AAiCjG,qBACa,wBAAyB,SAAQ,qBAAqB;IAC/D;;;OAGG;IACH,IAAoB,qBAAqB,IAAI,OAAO,CAEnD;IAED,IAAoB,iBAAiB,IAAI,SAAS,MAAM,EAAE,CAEzD;IAED,oGAAoG;IACpG,cAAuB,gBAAgB,IAAI,YAAY,CAEtD;IAED,sFAAsF;cACnE,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM;IAI3E;;;;;;;;OAQG;cACgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,QAAQ,EAAE,mBAAmB,GAAG,IAAI;IAIxG;;;;;;;OAOG;IACmB,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC;IA6C9E;;;;;;;;;;;OAWG;IACa,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI;CAyB1E;AAED,0FAA0F;AAC1F,wBAAgB,4BAA4B,IAAI,IAAI,CAEnD"}