@mj-biz-apps/sales-entities 6.4.0 → 6.6.0

package/dist/amount-freshness.d.ts

@@ -0,0 +1,69 @@
+/**
+ * @fileoverview Whether `Deal.Amount` still describes the order it was cached from.
+ *
+ * `Deal.Amount` is a CACHED ANSWER from Orders, stamped with `AmountIsComputed` / `AmountComputedAt` /
+ * `AmountSourceHash`. Sales never recomputes it. The only question a sales surface may ask is whether
+ * the cached number still matches the order — and that is a COMPARISON of two stored figures, not
+ * arithmetic. Nothing here multiplies, discounts, prorates, sums or rounds.
+ *
+ * ── WHY THIS IS NOT A TIMESTAMP COMPARE ANY MORE (bc-aidp-next-golive#230) ──────────────────────
+ *
+ * Both surfaces used to read the newest `__mj_UpdatedAt` across the order's lines and call the amount
+ * stale if it was later than `AmountComputedAt`. That asks "was a line TOUCHED", and the answer to that
+ * is yes for reasons that have nothing to do with the price: closing a deal books the order, which moves
+ * the lines' status and stamps `__mj_UpdatedAt` without a figure changing. So every Won deal warned,
+ * permanently, that its frozen amount needed repricing.
+ *
+ * It is the failure shape CLAUDE.md rule 8 names: a claim that was true when it was written -- a touched
+ * line usually DID mean a moved price -- and stayed asserted after the close flow started touching lines
+ * for its own reasons. The guard was keyed on a PROXY (the timestamp) rather than on the thing it
+ * actually cared about (the number). A proxy can be outgrown; the number cannot.
+ *
+ * So the test is now the one the question deserves: does the cached amount equal the order's current
+ * total? That is also EXACTLY the test `DealEntityServer.refreshAmountFromOrder()` uses to decide the
+ * cache is already current, so this surface and the server agree by construction rather than by
+ * coincidence — if the server would rewrite the cache, this says stale; if it would no-op, this says
+ * fresh.
+ *
+ * @module @mj-biz-apps/sales-entities
+ */
+import { type UserInfo } from '@memberjunction/core';
+/**
+ * The notice a surface shows when the cached amount no longer matches its order.
+ *
+ * golive#230: the previous wording — "A line has changed since this amount was last priced. Reprice the
+ * order to update the total." — named an action that DOES NOT EXIST. There is no reprice control
+ * anywhere in this codebase, so the sentence asked the reader to do something impossible.
+ *
+ * Saving the deal genuinely is the fix, and that is verifiable rather than hopeful:
+ * `DealEntityServer.Save()` sets `amountMayHaveMoved` when `AmountIsComputed === true`, which is
+ * precisely the state this notice appears in, and then re-reads `OrderHeader.TotalGross` into the cache.
+ */
+export declare const DEAL_AMOUNT_STALE_NOTICE = "The products on this deal changed after the amount was calculated. Save the deal to update it.";
+/** The answer, plus the notice to show. `Notice` is null whenever `IsStale` is false. */
+export interface DealAmountFreshness {
+    IsStale: boolean;
+    Notice: string | null;
+}
+/** What the caller must already know about the deal. Both surfaces hold all four. */
+export interface DealAmountFreshnessInput {
+    /**
+     * Whether the PERSISTED status locks the deal, as `ResolveDealLockState` reports it.
+     *
+     * Required rather than optional on purpose. A caller that forgot to pass it would get the old
+     * always-warns behaviour back, silently, on exactly the screen the bug was reported against.
+     */
+    IsLocked: boolean;
+    AmountIsComputed: boolean | null | undefined;
+    Amount: number | string | null | undefined;
+    OrderID: string | null | undefined;
+}
+/**
+ * Whether the deal's cached amount still matches its order's total.
+ *
+ * Returns FRESH — never warns — in every case where the question is meaningless: a locked deal (the
+ * amount is frozen and no edit could change it), a deal whose amount was typed rather than computed,
+ * a deal with no order, and an order with no usable total.
+ */
+export declare function ResolveDealAmountFreshness(input: DealAmountFreshnessInput, contextUser?: UserInfo): Promise<DealAmountFreshness>;
+//# sourceMappingURL=amount-freshness.d.ts.map

package/dist/amount-freshness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"amount-freshness.d.ts","sourceRoot":"","sources":["../src/amount-freshness.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,OAAO,EAAW,KAAK,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAI9D;;;;;;;;;;GAUG;AACH,eAAO,MAAM,wBAAwB,mGAC+D,CAAC;AAErG,yFAAyF;AACzF,MAAM,WAAW,mBAAmB;IAChC,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAED,qFAAqF;AACrF,MAAM,WAAW,wBAAwB;IACrC;;;;;OAKG;IACH,QAAQ,EAAE,OAAO,CAAC;IAClB,gBAAgB,EAAE,OAAO,GAAG,IAAI,GAAG,SAAS,CAAC;IAC7C,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IAC3C,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;CACtC;AAKD;;;;;;GAMG;AACH,wBAAsB,0BAA0B,CAC5C,KAAK,EAAE,wBAAwB,EAC/B,WAAW,CAAC,EAAE,QAAQ,GACvB,OAAO,CAAC,mBAAmB,CAAC,CAsD9B"}

package/dist/amount-freshness.js

@@ -0,0 +1,100 @@
+/**
+ * @fileoverview Whether `Deal.Amount` still describes the order it was cached from.
+ *
+ * `Deal.Amount` is a CACHED ANSWER from Orders, stamped with `AmountIsComputed` / `AmountComputedAt` /
+ * `AmountSourceHash`. Sales never recomputes it. The only question a sales surface may ask is whether
+ * the cached number still matches the order — and that is a COMPARISON of two stored figures, not
+ * arithmetic. Nothing here multiplies, discounts, prorates, sums or rounds.
+ *
+ * ── WHY THIS IS NOT A TIMESTAMP COMPARE ANY MORE (bc-aidp-next-golive#230) ──────────────────────
+ *
+ * Both surfaces used to read the newest `__mj_UpdatedAt` across the order's lines and call the amount
+ * stale if it was later than `AmountComputedAt`. That asks "was a line TOUCHED", and the answer to that
+ * is yes for reasons that have nothing to do with the price: closing a deal books the order, which moves
+ * the lines' status and stamps `__mj_UpdatedAt` without a figure changing. So every Won deal warned,
+ * permanently, that its frozen amount needed repricing.
+ *
+ * It is the failure shape CLAUDE.md rule 8 names: a claim that was true when it was written -- a touched
+ * line usually DID mean a moved price -- and stayed asserted after the close flow started touching lines
+ * for its own reasons. The guard was keyed on a PROXY (the timestamp) rather than on the thing it
+ * actually cared about (the number). A proxy can be outgrown; the number cannot.
+ *
+ * So the test is now the one the question deserves: does the cached amount equal the order's current
+ * total? That is also EXACTLY the test `DealEntityServer.refreshAmountFromOrder()` uses to decide the
+ * cache is already current, so this surface and the server agree by construction rather than by
+ * coincidence — if the server would rewrite the cache, this says stale; if it would no-op, this says
+ * fresh.
+ *
+ * @module @mj-biz-apps/sales-entities
+ */
+import { RunView } from '@memberjunction/core';
+const E_ORDER_HEADER = 'MJ_BizApps_Orders: Order Headers';
+/**
+ * The notice a surface shows when the cached amount no longer matches its order.
+ *
+ * golive#230: the previous wording — "A line has changed since this amount was last priced. Reprice the
+ * order to update the total." — named an action that DOES NOT EXIST. There is no reprice control
+ * anywhere in this codebase, so the sentence asked the reader to do something impossible.
+ *
+ * Saving the deal genuinely is the fix, and that is verifiable rather than hopeful:
+ * `DealEntityServer.Save()` sets `amountMayHaveMoved` when `AmountIsComputed === true`, which is
+ * precisely the state this notice appears in, and then re-reads `OrderHeader.TotalGross` into the cache.
+ */
+export const DEAL_AMOUNT_STALE_NOTICE = 'The products on this deal changed after the amount was calculated. Save the deal to update it.';
+const FRESH = Object.freeze({ IsStale: false, Notice: null });
+const STALE = Object.freeze({ IsStale: true, Notice: DEAL_AMOUNT_STALE_NOTICE });
+/**
+ * Whether the deal's cached amount still matches its order's total.
+ *
+ * Returns FRESH — never warns — in every case where the question is meaningless: a locked deal (the
+ * amount is frozen and no edit could change it), a deal whose amount was typed rather than computed,
+ * a deal with no order, and an order with no usable total.
+ */
+export async function ResolveDealAmountFreshness(input, contextUser) {
+    /**
+     * A CLOSED DEAL NEVER WARNS, and this is the first test rather than one of several.
+     *
+     * The amount is frozen by the close lock, so there is no edit that could resolve the notice and no
+     * reason to read it. golive#230 is precisely this case: the close books the order, the order's
+     * lines move, and the deal is simultaneously forbidden from doing anything about it. A warning
+     * nobody can act on is worse than silence — it trains the reader to ignore the flag that matters.
+     */
+    if (input.IsLocked) {
+        return FRESH;
+    }
+    // A typed amount claims nothing about the order, so it cannot disagree with one.
+    if (!input.AmountIsComputed || !input.OrderID) {
+        return FRESH;
+    }
+    const result = await new RunView().RunView({
+        EntityName: E_ORDER_HEADER,
+        ExtraFilter: `ID = '${String(input.OrderID).replace(/'/g, "''")}'`,
+        ResultType: 'simple',
+        Fields: ['TotalGross'],
+    }, contextUser);
+    if (!result?.Success) {
+        // A failed read is not evidence of staleness. Saying nothing is the honest answer.
+        return FRESH;
+    }
+    const raw = (result.Results ?? [])[0]?.TotalGross;
+    const total = raw === null || raw === undefined ? null : Number(raw);
+    if (total === null || !Number.isFinite(total)) {
+        /**
+         * `OrderHeader.TotalGross` is NULL for an order with no lines — `SUM` over no rows is NULL —
+         * so this is the empty-order case, not an error. There is no total to disagree with.
+         */
+        return FRESH;
+    }
+    const cachedRaw = input.Amount;
+    const cached = cachedRaw === null || cachedRaw === undefined ? null : Number(cachedRaw);
+    if (cached === null || !Number.isFinite(cached)) {
+        /**
+         * A deal claiming a COMPUTED amount that is not a number is the corrupt state `SD23` was written
+         * for. Reporting it stale is both true and useful: the notice's own instruction — save the deal
+         * — is exactly what repairs it, because the save re-reads the total into the cache.
+         */
+        return STALE;
+    }
+    return cached === total ? FRESH : STALE;
+}
+//# sourceMappingURL=amount-freshness.js.map

package/dist/amount-freshness.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"amount-freshness.js","sourceRoot":"","sources":["../src/amount-freshness.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,OAAO,EAAE,OAAO,EAAiB,MAAM,sBAAsB,CAAC;AAE9D,MAAM,cAAc,GAAG,kCAAkC,CAAC;AAE1D;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,wBAAwB,GACjC,gGAAgG,CAAC;AAsBrG,MAAM,KAAK,GAAwB,MAAM,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;AACnF,MAAM,KAAK,GAAwB,MAAM,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,wBAAwB,EAAE,CAAC,CAAC;AAEtG;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,0BAA0B,CAC5C,KAA+B,EAC/B,WAAsB;IAEtB;;;;;;;OAOG;IACH,IAAI,KAAK,CAAC,QAAQ,EAAE,CAAC;QACjB,OAAO,KAAK,CAAC;IACjB,CAAC;IAED,iFAAiF;IACjF,IAAI,CAAC,KAAK,CAAC,gBAAgB,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC;QAC5C,OAAO,KAAK,CAAC;IACjB,CAAC;IAED,MAAM,MAAM,GAAG,MAAM,IAAI,OAAO,EAAE,CAAC,OAAO,CACtC;QACI,UAAU,EAAE,cAAc;QAC1B,WAAW,EAAE,SAAS,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,GAAG;QAClE,UAAU,EAAE,QAAQ;QACpB,MAAM,EAAE,CAAC,YAAY,CAAC;KACzB,EACD,WAAW,CACd,CAAC;IACF,IAAI,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC;QACnB,mFAAmF;QACnF,OAAO,KAAK,CAAC;IACjB,CAAC;IAED,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,UAAU,CAAC;IAClD,MAAM,KAAK,GAAG,GAAG,KAAK,IAAI,IAAI,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACrE,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QAC5C;;;WAGG;QACH,OAAO,KAAK,CAAC;IACjB,CAAC;IAED,MAAM,SAAS,GAAG,KAAK,CAAC,MAAM,CAAC;IAC/B,MAAM,MAAM,GAAG,SAAS,KAAK,IAAI,IAAI,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IACxF,IAAI,MAAM,KAAK,IAAI,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;QAC9C;;;;WAIG;QACH,OAAO,KAAK,CAAC;IACjB,CAAC;IAED,OAAO,MAAM,KAAK,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC;AAC5C,CAAC"}

package/dist/close-lock.d.ts

@@ -28,25 +28,81 @@
  */
 import { type UserInfo } from '@memberjunction/core';
 /**
- * The deal fields that stay editable while the deal is locked.
+ * Every field a locked deal still accepts, given its outcome.
  *
- * Pinned by integration check CD14, which closes a deal and then proves each of these is genuinely
- * accepted and that a field outside the set is genuinely refused — so this constant cannot quietly
- * stop describing what the server does.
+ * Takes the flag rather than exposing a flat set, so a caller cannot read the list and forget the
+ * condition. That is not hypothetical: four call sites used to read the flat constant directly.
+ *
+ * @param isLost - whether the deal's PERSISTED status carries `IsLost`. When it cannot be determined,
+ *                 pass `false`: refusing an edit to a closed deal is the cheaper mistake.
+ */
+export declare function DealFieldsEditableWhileLocked(isLost: boolean): ReadonlySet<string>;
+/**
+ * Whether `fieldName` may still be edited on a locked deal with this outcome.
+ *
+ * Callers should prefer this to reaching into the sets, so the membership test stays in one place.
+ */
+export declare function IsDealFieldEditableWhileLocked(fieldName: string, isLost: boolean): boolean;
+/** The on-screen label for a deal field: the override if there is one, else the field name split into words. */
+export declare function DealFieldLabel(fieldName: string): string;
+/**
+ * What the lock notice lists as still editable.
+ *
+ * DEAL STATUS IS IN HERE AND NOT IN `DealFieldsEditableWhileLocked`, which looks like a
+ * contradiction and is not. That set is what the SERVER accepts in a bare save, and golive#205 asks
+ * for a bare status write to be refused on every path — the status moves through `Sales.CloseDeal`
+ * and `Sales.ReopenDeal`, which the form's status control routes to. So the field IS editable to a
+ * person and IS NOT writable by a raw save, and one set cannot say both.
+ *
+ * The notice describes what a PERSON can do, so it is the one that carries Deal Status.
+ *
+ * It takes `isLost` because the set it wraps does: golive#206 keeps Loss Notes editable on a lost
+ * deal and frozen on a won one, so the notice must name it on one and not the other.
  */
-export declare const DEAL_FIELDS_EDITABLE_WHILE_LOCKED: ReadonlySet<string>;
+export declare function DealFieldsListedAsEditable(isLost: boolean): readonly string[];
 /**
- * Whether `fieldName` may still be edited on a locked deal.
+ * Join labels the way a sentence does: "A, B and C".
  *
- * Callers should prefer this to reaching into the set, so the membership test stays in one place if the
- * rule ever grows a condition beyond simple membership.
+ * Oxford-comma-free and with "and" before the last, because this lands mid-sentence in prose a tester
+ * wrote, not in a bulleted list.
  */
-export declare function IsDealFieldEditableWhileLocked(fieldName: string): boolean;
+export declare function JoinLabels(labels: readonly string[]): string;
 /** What a surface needs to know to render the lock: whether it is on, and what to say about it. */
 export interface DealLockState {
     IsLocked: boolean;
     /** The status' display name, for the notice. Null when not locked. */
     StatusName: string | null;
+    /**
+     * Whether the locking status carries `IsLost`, which decides one field: golive#206 keeps Loss
+     * Notes editable on a lost deal and frozen on a won one.
+     *
+     * Resolved HERE rather than by each surface, for the same reason `IsLocked` is: it is read off the
+     * status ROW by flag, from the PERSISTED status, and a second implementation gets one of those
+     * quietly wrong. `false` on an open deal and on a status that cannot be read — refusing an edit to
+     * a closed deal is the cheaper mistake.
+     */
+    IsLost: boolean;
+    /**
+     * Whether the PERSISTED status carries `IsWon` — the outcome, not the lock.
+     *
+     * UNLIKE EVERY OTHER MEMBER HERE, THIS IS NOT GATED ON `LocksDeal`, and the difference is the
+     * whole reason it exists. The rest of this shape answers "what may still be edited", a question
+     * only a locked deal has. `IsWon` answers "did we win", which an OPEN deal can also answer, and
+     * golive#226 asks the Deal header for chips that appear on a won deal and on no other. Gating it
+     * on the lock would tie a header decision to a field-editing one, so a deployment whose winning
+     * status does not freeze the deal would lose its Order and Contract chips with nothing on screen
+     * to explain it.
+     *
+     * Read off the status ROW by FLAG, like its siblings. Nothing anywhere compares a status name —
+     * a deployment may call its winning status "Signed" (§3), and `test:vocabulary-gate` enforces it.
+     *
+     * `false` when the status cannot be read: a chip that is missing costs a click, and one that
+     * should not be there says a deal was won when it was not.
+     *
+     * golive#231's outcome tiles read it too, and are unaffected by the ungating: every one of those
+     * getters tests the CLOSE STAMPS first, so an open won-status deal still reads "Closes".
+     */
+    IsWon: boolean;
     /** A ready-to-render explanation, or null when the deal is open. */
     Notice: string | null;
 }
@@ -69,41 +125,31 @@ export interface DealLockState {
  * @param contextUser - Server callers must pass one; the browser omits it.
  */
 export declare function ResolveDealLockState(persistedStatusID: string | null | undefined, contextUser?: UserInfo): Promise<DealLockState>;
-/**
- * What a save knows about a status change, before deciding whether it is a bare close.
- *
- * Resolved by the caller because two of these need a database read; the decision itself does not, and
- * that is the point of separating them.
- */
-export interface StatusTransitionFacts {
-    /** False on creation — a deal born closed has no transition to have run. */
-    IsSaved: boolean;
-    /** True when `Sales.CloseDeal` (or a reopen) announced itself via `DeclareTransition`. */
-    HasDeclaredTransition: boolean;
-    /** True when the caller set `DealStatusTypeID` on this save. */
-    StatusIsDirty: boolean;
-    /** Whether the status being moved INTO carries `LocksDeal`. */
-    TargetLocks: boolean;
-    /** Whether the status being moved OUT OF carries it. Null when there was none. */
-    PriorLocks: boolean | null;
+/** One row of the deal-status list, with the flag that decides whether it may be picked. */
+export interface DealStatusOption {
+    ID: string;
+    Name: string;
+    /** Entering this status closes and freezes the deal. Enforced server-side. */
+    LocksDeal: boolean;
+    /**
+     * The OUTCOME flags, carried so a close action can find the status to close INTO by flag rather
+     * than by name. A deployment may call its winning status "Signed"; nothing may match on the word.
+     */
+    IsWon: boolean;
+    IsLost: boolean;
 }
 /**
- * Is this save about to lock a deal without the close having run? (bc-aidp-next-golive#205)
- *
- * THE DEFECT IT NAMES. The close lock reads the PERSISTED status, so Open -> Won is a save on an
- * unlocked deal and passes straight through it. The deal ends up locked with none of the close having
- * happened — no stage event, no contract, no finance tasks, no loss reason, an order still live — and
- * the lock then refuses `DealStatusTypeID` on every later save, so it cannot be undone either.
- *
- * WHAT MAKES A CLOSE LEGITIMATE is the declared transition. `Sales.CloseDeal` calls `stampClose`
- * immediately before saving, and that declares one; a form writing a field has no way to. So this
- * needs no new flag on the entity, and it cannot be spoofed by a caller that does not know about it.
+ * Every active deal status, with its lock flag, for a surface that has to offer a choice.
  *
- * LEAVING a locking status is deliberately NOT this function's business. That is a reopen, and the
- * close lock already refuses a bare one with a message that names `Sales.ReopenDeal` — two refusals
- * for the same edit would be one too many, and the other one is better worded for it.
+ * RETURNS ALL OF THEM AND LETS THE CALLER FILTER, deliberately. A closed deal still has to SHOW the
+ * status it is in — a control that simply dropped the locking ones would render a won deal as blank
+ * or "— choose —", which reads as data loss. The workspace already solves it this way: it offers the
+ * non-locking ones and adds the deal's own status back as a display-only option.
  *
- * Pure, so the decision can be pinned without a deal, a status table or a save.
+ * `LocksDeal` rather than `IsWon || IsLost`, because that is the flag the server's refusal reads.
+ * They coincide on today's data — Won, Lost and Abandoned carry both — but a surface filtering on a
+ * different flag would eventually offer a status the server then refuses, which is the drift this
+ * module exists to prevent.
  */
-export declare function IsBareCloseWrite(facts: StatusTransitionFacts): boolean;
+export declare function LoadDealStatusOptions(contextUser?: UserInfo): Promise<DealStatusOption[]>;
 //# sourceMappingURL=close-lock.d.ts.map

package/dist/close-lock.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"close-lock.d.ts","sourceRoot":"","sources":["../src/close-lock.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,OAAO,EAAW,KAAK,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAE9D;;;;;;GAMG;AACH,eAAO,MAAM,iCAAiC,EAAE,WAAW,CAAC,MAAM,CAGhE,CAAC;AAEH;;;;;GAKG;AACH,wBAAgB,8BAA8B,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAEzE;AAKD,mGAAmG;AACnG,MAAM,WAAW,aAAa;IAC1B,QAAQ,EAAE,OAAO,CAAC;IAClB,sEAAsE;IACtE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,oEAAoE;IACpE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,oBAAoB,CACtC,iBAAiB,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAC5C,WAAW,CAAC,EAAE,QAAQ,GACvB,OAAO,CAAC,aAAa,CAAC,CA6BxB;AAED;;;;;GAKG;AACH,MAAM,WAAW,qBAAqB;IAClC,4EAA4E;IAC5E,OAAO,EAAE,OAAO,CAAC;IACjB,0FAA0F;IAC1F,qBAAqB,EAAE,OAAO,CAAC;IAC/B,gEAAgE;IAChE,aAAa,EAAE,OAAO,CAAC;IACvB,+DAA+D;IAC/D,WAAW,EAAE,OAAO,CAAC;IACrB,kFAAkF;IAClF,UAAU,EAAE,OAAO,GAAG,IAAI,CAAC;CAC9B;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,qBAAqB,GAAG,OAAO,CAQtE"}
+{"version":3,"file":"close-lock.d.ts","sourceRoot":"","sources":["../src/close-lock.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,OAAO,EAAW,KAAK,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AA0C9D;;;;;;;;GAQG;AACH,wBAAgB,6BAA6B,CAAC,MAAM,EAAE,OAAO,GAAG,WAAW,CAAC,MAAM,CAAC,CAKlF;AAED;;;;GAIG;AACH,wBAAgB,8BAA8B,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,OAAO,CAE1F;AAkDD,gHAAgH;AAChH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAExD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,OAAO,GAAG,SAAS,MAAM,EAAE,CAE7E;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAI5D;AAKD,mGAAmG;AACnG,MAAM,WAAW,aAAa;IAC1B,QAAQ,EAAE,OAAO,CAAC;IAClB,sEAAsE;IACtE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B;;;;;;;;OAQG;IACH,MAAM,EAAE,OAAO,CAAC;IAChB;;;;;;;;;;;;;;;;;;;OAmBG;IACH,KAAK,EAAE,OAAO,CAAC;IACf,oEAAoE;IACpE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,oBAAoB,CACtC,iBAAiB,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAC5C,WAAW,CAAC,EAAE,QAAQ,GACvB,OAAO,CAAC,aAAa,CAAC,CAqDxB;AAED,4FAA4F;AAC5F,MAAM,WAAW,gBAAgB;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,8EAA8E;IAC9E,SAAS,EAAE,OAAO,CAAC;IACnB;;;OAGG;IACH,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,OAAO,CAAC;CACnB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,qBAAqB,CAAC,WAAW,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAiC/F"}

package/dist/close-lock.js

@@ -28,24 +28,145 @@
  */
 import { RunView } from '@memberjunction/core';
 /**
- * The deal fields that stay editable while the deal is locked.
+ * The deal fields that stay editable while the deal is locked, on ANY locked deal.
  *
  * Pinned by integration check CD14, which closes a deal and then proves each of these is genuinely
- * accepted and that a field outside the set is genuinely refused — so this constant cannot quietly
- * stop describing what the server does.
+ * accepted and that a field outside the set is genuinely refused — so this cannot quietly stop
+ * describing what the server does.
  */
-export const DEAL_FIELDS_EDITABLE_WHILE_LOCKED = new Set([
+const EDITABLE_ON_ANY_LOCKED_DEAL = new Set([
+    // Commentary. A closed deal still gets notes, and forcing a reopen to add one would corrupt the
+    // reopen record with administrative noise.
     'Description',
+    // Follow-up. NextStepDate is here because leaving one of the pair open and the other frozen makes
+    // no sense -- a next step nobody may date is half a field.
     'NextStep',
+    'NextStepDate',
+    // Attribution and bookkeeping. Nothing downstream reads these, and they are routinely corrected
+    // after the fact: the contract takes the PRIMARY contact, not the billing one, and Lead Source and
+    // Campaign exist for reporting.
+    'BillingContactID',
+    'LeadSourceTypeID',
+    'CampaignID',
 ]);
 /**
- * Whether `fieldName` may still be edited on a locked deal.
+ * The fields that stay editable only on a LOST deal.
  *
- * Callers should prefer this to reaching into the set, so the membership test stays in one place if the
- * rule ever grows a condition beyond simple membership.
+ * golive#206's field table says "Loss Notes (Lost deals only)", and item 3 asks that the server's
+ * list "match this list exactly". An earlier version of this module put `LossNotes` in the flat set
+ * above and said so out loud: a conditional member would need the form and the server to evaluate the
+ * same condition, which is the drift this module exists to prevent.
+ *
+ * That reasoning was weaker than it read. THIS module is exactly where such a condition belongs --
+ * the same place that already owns "how you decide a deal is locked at all". Both sides now pass a
+ * flag they already hold, from the same resolver, and the condition itself lives here once.
+ *
+ * `LossReasonID` stays frozen on every deal, lost included: the close event records which reason was
+ * chosen, and rewriting it would make that event dishonest. Notes are the channel for corrections.
+ */
+const EDITABLE_ON_A_LOST_DEAL = new Set(['LossNotes']);
+/**
+ * Every field a locked deal still accepts, given its outcome.
+ *
+ * Takes the flag rather than exposing a flat set, so a caller cannot read the list and forget the
+ * condition. That is not hypothetical: four call sites used to read the flat constant directly.
+ *
+ * @param isLost - whether the deal's PERSISTED status carries `IsLost`. When it cannot be determined,
+ *                 pass `false`: refusing an edit to a closed deal is the cheaper mistake.
+ */
+export function DealFieldsEditableWhileLocked(isLost) {
+    if (!isLost) {
+        return EDITABLE_ON_ANY_LOCKED_DEAL;
+    }
+    return new Set([...EDITABLE_ON_ANY_LOCKED_DEAL, ...EDITABLE_ON_A_LOST_DEAL]);
+}
+/**
+ * Whether `fieldName` may still be edited on a locked deal with this outcome.
+ *
+ * Callers should prefer this to reaching into the sets, so the membership test stays in one place.
+ */
+export function IsDealFieldEditableWhileLocked(fieldName, isLost) {
+    return EDITABLE_ON_ANY_LOCKED_DEAL.has(fieldName) || (isLost && EDITABLE_ON_A_LOST_DEAL.has(fieldName));
+}
+/**
+ * What each editable-while-locked field is CALLED on screen.
+ *
+ * The lock notice used to interpolate the raw field names, so a user read "only Description and
+ * NextStep can still be changed" — `NextStep` being a column name that appears nowhere on the form.
+ * golive#207 asks for the labels a salesperson sees.
+ *
+ * Falling back to the field name is deliberate rather than throwing: a field added to the set without
+ * a label here should read slightly wrong, not take the whole notice down. `DealFieldLabel` is
+ * exported so a test can prove every member of the set has one.
+ */
+const DEAL_FIELD_LABELS = {
+    Description: 'Description',
+    NextStep: 'Next Step',
+    NextStepDate: 'Next Step Date',
+    BillingContactID: 'Billing Contact',
+    LeadSourceTypeID: 'Lead Source',
+    CampaignID: 'Campaign',
+    LossNotes: 'Loss Notes',
+    DealStatusTypeID: 'Deal Status',
+};
+/**
+ * Splits a column name into words and drops a trailing `ID`: `ExpectedCloseDate` -> `Expected Close
+ * Date`, `BillingContactID` -> `Billing Contact`.
+ *
+ * THIS EXISTS BECAUSE THE MAP ABOVE COVERS THE WRONG HALF OF THE RULE. It holds the fields the lock
+ * leaves EDITABLE -- what row 16 lists. Row 18 names the FROZEN fields, and there are far more of
+ * those, none of them in the map: `Amount`, `ExpectedCloseDate`, `AnnualIncreasePctOverride` and every
+ * other column a form or an importer can set. Falling back to the raw field name meant row 18 read
+ * "ExpectedCloseDate, AnnualIncreasePctOverride cannot be changed" -- the exact "NextStep being a
+ * column name that appears nowhere on the form" complaint the map was added to answer, on the message
+ * a user is far more likely to see.
+ *
+ * Deriving rather than hand-listing the frozen set, because a hand list would have to be extended
+ * every time a column is added and would read correctly right up until somebody forgot -- the same
+ * shape as the gap it is replacing. The map stays for the two labels a split cannot produce
+ * (`LeadSourceTypeID` -> "Lead Source", not "Lead Source Type") and is now an override rather than
+ * the only source of a label.
  */
-export function IsDealFieldEditableWhileLocked(fieldName) {
-    return DEAL_FIELDS_EDITABLE_WHILE_LOCKED.has(fieldName);
+function SplitFieldName(fieldName) {
+    return fieldName
+        .replace(/ID$/, '')
+        .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+        .replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2')
+        .trim();
+}
+/** The on-screen label for a deal field: the override if there is one, else the field name split into words. */
+export function DealFieldLabel(fieldName) {
+    return DEAL_FIELD_LABELS[fieldName] ?? SplitFieldName(fieldName);
+}
+/**
+ * What the lock notice lists as still editable.
+ *
+ * DEAL STATUS IS IN HERE AND NOT IN `DealFieldsEditableWhileLocked`, which looks like a
+ * contradiction and is not. That set is what the SERVER accepts in a bare save, and golive#205 asks
+ * for a bare status write to be refused on every path — the status moves through `Sales.CloseDeal`
+ * and `Sales.ReopenDeal`, which the form's status control routes to. So the field IS editable to a
+ * person and IS NOT writable by a raw save, and one set cannot say both.
+ *
+ * The notice describes what a PERSON can do, so it is the one that carries Deal Status.
+ *
+ * It takes `isLost` because the set it wraps does: golive#206 keeps Loss Notes editable on a lost
+ * deal and frozen on a won one, so the notice must name it on one and not the other.
+ */
+export function DealFieldsListedAsEditable(isLost) {
+    return ['DealStatusTypeID', ...DealFieldsEditableWhileLocked(isLost)];
+}
+/**
+ * Join labels the way a sentence does: "A, B and C".
+ *
+ * Oxford-comma-free and with "and" before the last, because this lands mid-sentence in prose a tester
+ * wrote, not in a bulleted list.
+ */
+export function JoinLabels(labels) {
+    if (labels.length === 0)
+        return '';
+    if (labels.length === 1)
+        return labels[0];
+    return `${labels.slice(0, -1).join(', ')} and ${labels[labels.length - 1]}`;
 }
 /** Sales' deal-status type table. Named here so the lock lookup below has one spelling of it. */
 const E_DEAL_STATUS_TYPE = 'MJ_BizApps_Sales: Deal Status Types';
@@ -68,7 +189,7 @@ const E_DEAL_STATUS_TYPE = 'MJ_BizApps_Sales: Deal Status Types';
  * @param contextUser - Server callers must pass one; the browser omits it.
  */
 export async function ResolveDealLockState(persistedStatusID, contextUser) {
-    const open = { IsLocked: false, StatusName: null, Notice: null };
+    const open = { IsLocked: false, StatusName: null, IsLost: false, IsWon: false, Notice: null };
     if (!persistedStatusID) {
         return open;
     }
@@ -76,46 +197,80 @@ export async function ResolveDealLockState(persistedStatusID, contextUser) {
         EntityName: E_DEAL_STATUS_TYPE,
         ExtraFilter: `ID = '${String(persistedStatusID).replace(/'/g, "''")}'`,
         ResultType: 'simple',
-        Fields: ['LocksDeal', 'Name'],
+        Fields: ['LocksDeal', 'Name', 'IsLost', 'IsWon'],
     }, contextUser);
     const row = result?.Success ? (result.Results ?? [])[0] : undefined;
+    /**
+     * THE OUTCOME SURVIVES THE EARLY RETURN, THE LOCK DOES NOT.
+     *
+     * `IsWon` is a fact about the status itself, so it is carried out of every exit below rather than
+     * being reset to `false` by the unlocked one. The cost of getting this backwards is silent: the
+     * header would simply draw no chips on a won-but-unlocked deal, which looks exactly like a deal
+     * with no order and no contract.
+     */
+    const isWon = row?.IsWon === true;
     if (!row?.LocksDeal) {
-        return open;
+        return { ...open, IsWon: isWon };
     }
-    const editable = [...DEAL_FIELDS_EDITABLE_WHILE_LOCKED].join(' and ');
+    /**
+     * golive#207 row 16, in the tester's words: "This deal is closed (Won). Only Deal Status,
+     * Description and Next Step can be edited. To change anything else, set the status back to Open."
+     *
+     * DERIVED rather than hardcoded to those three. The tester wrote that list when the editable set
+     * held two fields; golive#206 item 3 expands it. A hardcoded sentence would have started lying the
+     * moment that landed, and the lie would be invisible — it reads perfectly either way.
+     *
+     * What went, and why it is no loss: the old notice explained WHY the deal is frozen ("a contract or
+     * an order was derived from it"). A person who has just been stopped wants to know what they can do,
+     * not the provenance argument, and the reason is one click away in the close history.
+     */
+    const isLost = row.IsLost === true;
+    const editable = JoinLabels(DealFieldsListedAsEditable(isLost).map(DealFieldLabel));
     return {
         IsLocked: true,
         StatusName: row.Name,
-        Notice: `This deal is closed (${row.Name}) and locked. A contract or an order was derived from it, so ` +
-            `its terms are frozen — only ${editable} can still be changed. To change anything else, reopen ` +
-            'the deal, which records a reason.',
+        IsLost: isLost,
+        IsWon: isWon,
+        Notice: `This deal is closed (${row.Name}). Only ${editable} can be edited. ` +
+            'To change anything else, set the status back to Open.',
     };
 }
 /**
- * Is this save about to lock a deal without the close having run? (bc-aidp-next-golive#205)
- *
- * THE DEFECT IT NAMES. The close lock reads the PERSISTED status, so Open -> Won is a save on an
- * unlocked deal and passes straight through it. The deal ends up locked with none of the close having
- * happened — no stage event, no contract, no finance tasks, no loss reason, an order still live — and
- * the lock then refuses `DealStatusTypeID` on every later save, so it cannot be undone either.
+ * Every active deal status, with its lock flag, for a surface that has to offer a choice.
  *
- * WHAT MAKES A CLOSE LEGITIMATE is the declared transition. `Sales.CloseDeal` calls `stampClose`
- * immediately before saving, and that declares one; a form writing a field has no way to. So this
- * needs no new flag on the entity, and it cannot be spoofed by a caller that does not know about it.
+ * RETURNS ALL OF THEM AND LETS THE CALLER FILTER, deliberately. A closed deal still has to SHOW the
+ * status it is in — a control that simply dropped the locking ones would render a won deal as blank
+ * or "— choose —", which reads as data loss. The workspace already solves it this way: it offers the
+ * non-locking ones and adds the deal's own status back as a display-only option.
  *
- * LEAVING a locking status is deliberately NOT this function's business. That is a reopen, and the
- * close lock already refuses a bare one with a message that names `Sales.ReopenDeal` — two refusals
- * for the same edit would be one too many, and the other one is better worded for it.
- *
- * Pure, so the decision can be pinned without a deal, a status table or a save.
+ * `LocksDeal` rather than `IsWon || IsLost`, because that is the flag the server's refusal reads.
+ * They coincide on today's data — Won, Lost and Abandoned carry both — but a surface filtering on a
+ * different flag would eventually offer a status the server then refuses, which is the drift this
+ * module exists to prevent.
  */
-export function IsBareCloseWrite(facts) {
-    if (!facts.IsSaved || facts.HasDeclaredTransition || !facts.StatusIsDirty) {
-        return false;
-    }
-    if (facts.PriorLocks === true) {
-        return false; // a reopen attempt; the close lock owns that refusal
+export async function LoadDealStatusOptions(contextUser) {
+    const result = await new RunView().RunView({
+        EntityName: E_DEAL_STATUS_TYPE,
+        ExtraFilter: 'IsActive = 1',
+        OrderBy: 'DisplayRank',
+        ResultType: 'simple',
+        // Every field read below must be listed here. A field declared on the row type and left
+        // out of this list arrives `undefined`, and a flag check against it quietly never fires --
+        // which is how ActivitySyncProviderType.IsActive did nothing for a release.
+        Fields: ['ID', 'Name', 'LocksDeal', 'IsWon', 'IsLost'],
+    }, contextUser);
+    if (!result?.Success) {
+        // An empty list leaves the control with nothing to offer, which is visibly wrong and therefore
+        // reportable. Inventing a list from somewhere else would hide a failed lookup behind a control
+        // that looks like it is working.
+        return [];
     }
-    return facts.TargetLocks;
+    return (result.Results ?? []).map((r) => ({
+        ID: String(r.ID),
+        Name: String(r.Name),
+        LocksDeal: r.LocksDeal === true,
+        IsWon: r.IsWon === true,
+        IsLost: r.IsLost === true,
+    }));
 }
 //# sourceMappingURL=close-lock.js.map