@mj-biz-apps/sales-core-entities-server 5.1.0

package/LICENSE

@@ -0,0 +1,183 @@
+Business Source License 1.1
+
+License text copyright (c) 2024 MariaDB plc, All Rights Reserved.
+"Business Source License" is a trademark of MariaDB plc.
+
+-----------------------------------------------------------------------------
+
+Parameters
+
+Licensor:             Blue Cypress, Inc.
+
+Licensed Work:        MemberJunction.
+                      The Licensed Work is (c) 2023-2026 Blue Cypress, Inc.
+
+Additional Use Grant: Subject to the terms of this License, Licensor grants
+                      you the following additional rights to make Production
+                      Use of the Licensed Work.
+
+                      1. Internal Use
+
+                      You may make production use of the Licensed Work for
+                      your own internal business or organizational operations.
+
+                      2. Nonprofit Use
+
+                      If you are a Nonprofit, you may make production use of
+                      the Licensed Work for the operations and activities of
+                      your Organizational Family.
+
+                      3. MemberJunction Certified Program Use
+
+                      If you are authorized by Licensor under the
+                      MemberJunction Certified Program to provide professional
+                      services using the Licensed Work, you may make
+                      production use of the Licensed Work in providing such
+                      professional services to a client, provided that:
+
+                      (a) the Licensed Work is deployed in, and the applicable
+                      production use occurs within, an environment owned,
+                      leased, licensed, subscribed to, or otherwise controlled
+                      by that client; and
+
+                      (b) the production use is for that client's own internal
+                      business or organizational operations or is otherwise
+                      independently permitted to that client under this
+                      Additional Use Grant.
+
+                      4. Definitions Applicable to the Additional Use Grant
+
+                      "Affiliate" means, with respect to a specified Person,
+                      any other Person that directly or indirectly Controls,
+                      is Controlled by, or is under common Control with such
+                      specified Person.
+
+                      "Control" (including the terms "Controls," "Controlled
+                      by," and "under common Control with") means the direct
+                      or indirect possession of the power to direct or cause
+                      the direction of the management and policies of a
+                      Person, whether through ownership of voting interests,
+                      by contract, or otherwise.
+
+                      "Organizational Family" means, with respect to a Person,
+                      (a) such Person and its Affiliates, and (b) any
+                      nonprofit organization, governmental entity, chapter,
+                      division, local affiliate, regional affiliate, state
+                      affiliate, national affiliate, or other entity that is
+                      formally affiliated with such Person through governing
+                      documents, a charter, bylaws, a membership agreement, or
+                      another written organizational instrument, and is
+                      recognized under such documents as part of the same
+                      organizational structure.
+
+                      "Nonprofit" means a Person recognized by the Internal
+                      Revenue Service as exempt from federal income taxation
+                      under Section 501(c)(3), 501(c)(4), 501(c)(5), or
+                      501(c)(6) of the Internal Revenue Code, or a foreign
+                      organization recognized under substantially equivalent
+                      laws.
+
+                      A Person claiming eligibility as a Nonprofit shall, upon
+                      Licensor's reasonable request, provide documentation
+                      reasonably sufficient to demonstrate that it qualifies
+                      as a Nonprofit. If such Person materially misrepresents,
+                      or is unable to demonstrate, its qualification as a
+                      Nonprofit, the rights granted to such Person under
+                      Section 2 of this Additional Use Grant shall terminate.
+
+                      "MemberJunction Certified Program" means Licensor's
+                      then-current program for certifying and authorizing a
+                      Person to provide professional services using the
+                      Licensed Work.
+
+                      "Person" means any individual, corporation, limited
+                      liability company, partnership, association, nonprofit
+                      organization, governmental entity, or other legal or
+                      organizational entity.
+
+Change Date:          Four (4) years from the date the Licensed Work is first
+                      made available.
+
+Change License:       MIT License.
+
+For information about alternative licensing arrangements for the Licensed
+Work, please contact Blue Cypress, Inc.
+
+-----------------------------------------------------------------------------
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative
+works, redistribute, and make non-production use of the Licensed Work. The
+Licensor may make an Additional Use Grant, above, permitting limited
+production use.
+
+Effective on the Change Date, or the fourth anniversary of the first publicly
+available distribution of a specific version of the Licensed Work under this
+License, whichever comes first, the Licensor hereby grants you rights under
+the terms of the Change License, and the rights granted in the paragraph
+above terminate.
+
+If your use of the Licensed Work does not comply with the requirements
+currently in effect as described in this License, you must purchase a
+commercial license from the Licensor, its affiliated entities, or authorized
+resellers, or you must refrain from using the Licensed Work.
+
+All copies of the original and modified Licensed Work, and derivative works
+of the Licensed Work, are subject to this License. This License applies
+separately for each version of the Licensed Work and the Change Date may vary
+for each version of the Licensed Work released by Licensor.
+
+You must conspicuously display this License on each original or modified copy
+of the Licensed Work. If you receive the Licensed Work in original or
+modified form from a third party, the terms and conditions set forth in this
+License apply to your use of that work.
+
+Any use of the Licensed Work in violation of this License will automatically
+terminate your rights under this License for the current and all other
+versions of the Licensed Work.
+
+This License does not grant you any right in any trademark or logo of
+Licensor or its affiliates (provided that you may use a trademark or logo of
+Licensor as expressly required by this License).
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
+AN "AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
+EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND
+TITLE.
+
+MariaDB hereby grants you permission to use this License's text to license
+your works, and to refer to it using the trademark "Business Source License",
+as long as you comply with the Covenants of Licensor below.
+
+-----------------------------------------------------------------------------
+
+Covenants of Licensor
+
+In consideration of the right to use this License's text and the "Business
+Source License" name and trademark, Licensor covenants to MariaDB, and to all
+other recipients of the licensed work to be provided by Licensor:
+
+1. To specify as the Change License the GPL Version 2.0 or any later version,
+   or a license that is compatible with GPL Version 2.0 or a later version,
+   where "compatible" means that software provided under the Change License
+   can be included in a program with software provided under GPL Version 2.0
+   or a later version. Licensor may specify additional Change Licenses without
+   limitation.
+
+2. To either: (a) specify an additional grant of rights to use that does not
+   impose any additional restriction on the right granted in this License, as
+   the Additional Use Grant; or (b) insert the text "None".
+
+3. To specify a Change Date.
+
+4. Not to modify this License in any other way.
+
+-----------------------------------------------------------------------------
+
+Notice
+
+The Business Source License (this document, or the "License") is not an Open
+Source license. However, the Licensed Work will eventually be made available
+under an Open Source License, as stated in this License.

package/dist/CloseDealOperation.d.ts

@@ -0,0 +1,176 @@
+/**
+ * @fileoverview `Sales.CloseDeal` and `Sales.ReopenDeal` — master plan §7.
+ *
+ * ONE TRANSACTION, ALL-OR-NONE. A partial close — contract created, order missing, lock applied — is
+ * the exact failure the transaction exists to prevent (§7.2). Everything below happens inside a single
+ * provider transaction, and any throw rolls the whole thing back.
+ *
+ * ── THE PATH IS RESOLVED FROM FLAGS, NEVER NAMES ────────────────────────────────────────────────
+ *
+ * The operation is called `CloseDeal`, not `WinDeal`, on purpose. It reads `IsWon` / `IsLost` /
+ * `LocksDeal` off the target `DealStatusType` row and branches on those. Nothing here compares a
+ * status name, a pipeline name, or the strings "B2B" / "D2C" — a deployment renames those freely and a
+ * rename must not change what a close does. Routing comes from `Pipeline.CloseWonPolicy`, which is
+ * config-as-data, and from nowhere else. The CI vocabulary grep enforces this.
+ *
+ * ── SALES STILL COMPUTES NO MONEY ───────────────────────────────────────────────────────────────
+ *
+ * The close routes lines and passes intent. It does not price them, total them, or apply a discount.
+ * Every figure comes back from orders, and while the downstream is stubbed no figure exists at all —
+ * which is honest rather than convenient.
+ *
+ * @module @mj-biz-apps/sales-core-entities-server
+ */
+import { IMetadataProvider, UserInfo } from '@memberjunction/core';
+import { SalesCloseDealOperation as SalesCloseDealOperationBase, SalesReopenDealOperation as SalesReopenDealOperationBase, type IDownstreamSeam, type SalesCloseDealInput, type SalesCloseDealOutput, type SalesReopenDealInput, type SalesReopenDealOutput } from '@mj-biz-apps/sales-entities';
+/** Swap the downstream implementation. Returns the previous one so a test can restore it. */
+export declare function SetDownstreamSeam(seam: IDownstreamSeam): IDownstreamSeam;
+export declare function GetDownstreamSeam(): IDownstreamSeam;
+/**
+ * Undo {@link SetDownstreamSeam} and return to DEPLOYMENT-BASED selection.
+ *
+ * Needed because `SetDownstreamSeam` latches: it records that a caller took control, so auto-selection
+ * stops second-guessing them. A test that installs a fake and then merely sets the old value back would
+ * leave that latch on, and every later check in the process would keep using whatever it restored —
+ * silently, and only on hosts where the live seam would otherwise have been chosen.
+ */
+export declare function ResetDownstreamSeam(): void;
+export declare class CloseDealOperation extends SalesCloseDealOperationBase {
+    protected InternalExecute(input: SalesCloseDealInput, provider: IMetadataProvider, user: UserInfo): Promise<SalesCloseDealOutput>;
+    /**
+     * What this close requires before it may proceed.
+     *
+     * The loss-reason rule is the app's ONLY mandatory field and the friction is deliberate: loss
+     * reasons are the highest-value and most consistently-skipped data in any CRM (§7.2).
+     */
+    private validate;
+    /**
+     * Pipeline default, with the caller's overrides merged over it (§7.1, D-CF6).
+     *
+     * A malformed policy is a WARNING-shaped failure that falls back to defaults rather than throwing:
+     * a pipeline with unparseable JSON should not make its deals uncloseable, and the effective policy
+     * is returned to the caller so the fallback is visible rather than silent.
+     */
+    private resolvePolicy;
+    /**
+     * What the policy says should happen, before anything is attempted.
+     *
+     * ── THERE IS NO LONGER AN ORDER ROUTE, AND THAT IS THE POINT ──
+     *
+     * Close-won used to create the order. It no longer does: the order is an EMBEDDED RECORD created
+     * with the deal and carrying its lines from the start (S-US4), so by the time a deal closes the
+     * order already exists. S-US5 is explicit that Closed Won leaves its status ALONE and editable, so
+     * finance can review and correct before the Confirm that locks it and triggers invoicing.
+     *
+     * So close-won no longer counts lines at all — there are none on the deal to count. What it plans
+     * is the CONTRACT (B2B only), and the still-unbuilt Subscription materialization.
+     */
+    private planRouting;
+    /** Attempt one planned route through the seam, recording honestly whether it executed. */
+    private execute;
+    /**
+     * The stage a close should land in, when the caller did not name one.
+     *
+     * ── THE MIRROR OF `priorStageFromCloseEvent`, AND THE OTHER HALF OF DN-18 ───────────────────────
+     *
+     * `CD18` proves a reopen restores the stage the deal came from. It could not help a deal closed
+     * through the browser, because `DealWorkspaceComponent.ConfirmClose()` sends no `ClosingStageID` — so
+     * no browser-driven close ever moved the stage, every close event recorded
+     * `FromStageID === ToStageID`, and the reopen correctly derived the stage the deal was already in.
+     * The mechanism was right and the UI could not reach it. `71-lost-and-reopen` is the spec that names
+     * this.
+     *
+     * Fixed in the OPERATION rather than in `ConfirmClose`, for the fourth time and the same reason: an
+     * agent, an importer and an API caller all close deals too, and a rule the app owns belongs on the
+     * write path. `input.ClosingStageID` stays an override.
+     *
+     * ── CHOSEN BY FLAG, WHICH IS THE ONLY WAY THIS CAN WORK ────────────────────────────────────────
+     *
+     * The stage on the deal's OWN pipeline whose declared `DealStatusType` matches the outcome being
+     * recorded — `IsWon` for a won close, `IsLost` for a lost one. Never a name: a pipeline is free to
+     * call its winning stage "Signed", "Booked" or anything else, and §3 is what makes that a label.
+     *
+     * Returns null rather than guessing when the pipeline declares no such stage. A deal on a pipeline
+     * with no losing stage closes as lost without moving, exactly as it did before this existed — the
+     * close is never blocked by the absence of somewhere to put it.
+     *
+     * ── AND IT LEANS ON TWO GUARDS THAT ARE NOW LOAD-BEARING ───────────────────────────────────────
+     *
+     * Moving into a stage that declares a LOCKING status is only safe because `applyStageDefaults` refuses
+     * to derive a locking status (`SD35`), so the stage cannot close the deal a second time; and the
+     * closing status stays authoritative because a declared transition suppresses stage defaults entirely
+     * (`CD17`). Both are mutant-proven. Without them this change would double-close every deal it touched.
+     */
+    private closingStageForOutcome;
+    /**
+     * Append the provenance row and stamp the deal.
+     *
+     * `DealStageEvent` is APPEND-ONLY and stamps `AmountAtTransition` / `ProbabilityAtTransition`,
+     * because "what did we think this was worth when we closed it" is unanswerable later once amounts
+     * change. The routing outcome goes into `Notes` — which is what preserves the intent of a close
+     * whose downstream was stubbed (D-CF1).
+     *
+     * §7 also calls for writing an `Activity` here. The Activity spine does not exist in common or MJ
+     * core, so that step is skipped and recorded in CLOSE-FLOW-DECISIONS.md D-CF5 rather than faked.
+     */
+    private stampClose;
+    /** A human-readable record of what the policy routed, and what actually happened. */
+    private routingNote;
+    private loadStatusFlags;
+    /** Split by the type's `IsRecurring` FLAG. A join, so one read rather than one per line. */
+    private dealTypeRequiresRenewalSource;
+    private buildContractInput;
+}
+/**
+ * `Sales.ReopenDeal` — the only sanctioned exit from the close lock (§7.3).
+ *
+ * Writes its own `DealStageEvent` first, so the fact that a close HAPPENED survives the close being
+ * undone. Provenance is append-only: reopening adds to the record rather than erasing it.
+ */
+export declare class ReopenDealOperation extends SalesReopenDealOperationBase {
+    protected InternalExecute(input: SalesReopenDealInput, provider: IMetadataProvider, user: UserInfo): Promise<SalesReopenDealOutput>;
+    private resolveTarget;
+    /**
+     * The stage a deal was in before it was closed, from the append-only log.
+     *
+     * ── WHY THE OPERATION DERIVES THIS AND THE WORKSPACE DOES NOT SUPPLY IT ─────────────────────────
+     *
+     * DN-18. The story says a reopened deal returns to its prior stage; `DealStageEvent.FromStageID`
+     * records exactly that, and `input.StageID` already existed. The only missing piece was that nobody
+     * sent it — so nothing ever re-entered a stage, `OrderStatusOnEntry` never fired, and a reopened deal
+     * sat pointing at a `Voided` order with nothing on screen saying so.
+     *
+     * Deriving it HERE rather than in the workspace keeps `input.StageID` an override instead of a
+     * requirement, and means an agent, an importer and an API caller get the same restoration a rep does.
+     * That is the same write-path principle as the deal number, the company stamp, the owner stamp and the
+     * embedded order: if the rule is the app's, the server owns it.
+     *
+     * ── WHICH EVENT, AND BY FLAG RATHER THAN BY NAME ────────────────────────────────────────────────
+     *
+     * The most recent event whose `ToDealStatusTypeID` carries `LocksDeal` — the closing transition. Read
+     * as a set of status ids first because `RunView` cannot join, and selected by the flag so a pipeline
+     * calling its winning stage "Signed" and its status "Booked" is unaffected (§3).
+     *
+     * A deal closed more than once has several such events; `ChangedAt DESC` takes the last one, which is
+     * the close being undone.
+     *
+     * ── THE TWO CASES THAT MAKE THIS CORRECT RATHER THAN CONVENIENT ─────────────────────────────────
+     *
+     *   · **A stage-moving close** stamped `FromStageID` = the stage before the close and `ToStageID` = the
+     *     closing stage. Restoring `FromStageID` moves the stage back, so the order-status writer fires
+     *     through the existing mechanism and the order follows — or refuses, and says so.
+     *   · **A status-only close** (no `ClosingStageID`) never moved the stage, so the event holds
+     *     `FromStageID === ToStageID`. Restoring it assigns the stage the deal is already in, the writer's
+     *     own comparison finds no move, and NOTHING fires. There is nothing to restore and nothing
+     *     happens — which is the behaviour that has to hold for this to be safe, and it holds without a
+     *     special case.
+     *
+     * Returns null when there is no close event to read — a deal closed by SQL, an import that wrote no
+     * provenance, or a log that was never written. The reopen then leaves the stage alone rather than
+     * guessing, which is the same answer as "the caller sent no StageID" and needs no extra branch.
+     */
+    private priorStageFromCloseEvent;
+    /** The default landing status — chosen by the `IsOpen` FLAG, never by a status name. */
+    private firstOpenStatus;
+}
+//# sourceMappingURL=CloseDealOperation.d.ts.map

package/dist/CloseDealOperation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CloseDealOperation.d.ts","sourceRoot":"","sources":["../src/CloseDealOperation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,OAAO,EAGH,iBAAiB,EAIjB,QAAQ,EACX,MAAM,sBAAsB,CAAC;AAa9B,OAAO,EACH,uBAAuB,IAAI,2BAA2B,EACtD,wBAAwB,IAAI,4BAA4B,EAKxD,KAAK,eAAe,EACpB,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EAIzB,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,EAC7B,MAAM,6BAA6B,CAAC;AAsJrC,6FAA6F;AAC7F,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,eAAe,GAAG,eAAe,CAKxE;AAED,wBAAgB,iBAAiB,IAAI,eAAe,CAEnD;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,IAAI,IAAI,CAG1C;AAyCD,qBACa,kBAAmB,SAAQ,2BAA2B;cAC/C,eAAe,CAC3B,KAAK,EAAE,mBAAmB,EAC1B,QAAQ,EAAE,iBAAiB,EAC3B,IAAI,EAAE,QAAQ,GACf,OAAO,CAAC,oBAAoB,CAAC;IAmRhC;;;;;OAKG;YACW,QAAQ;IA0CtB;;;;;;OAMG;YACW,aAAa;IAgC3B;;;;;;;;;;;;OAYG;YACW,WAAW;IA4BzB,0FAA0F;YAC5E,OAAO;IAoCrB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgCG;YACW,sBAAsB;IAgDpC;;;;;;;;;;OAUG;IACH,OAAO,CAAC,UAAU;IAkDlB,qFAAqF;IACrF,OAAO,CAAC,WAAW;YAqBL,eAAe;IA+B7B,4FAA4F;YAC9E,6BAA6B;YAsB7B,kBAAkB;CAgDnC;AAED;;;;;GAKG;AACH,qBACa,mBAAoB,SAAQ,4BAA4B;cACjD,eAAe,CAC3B,KAAK,EAAE,oBAAoB,EAC3B,QAAQ,EAAE,iBAAiB,EAC3B,IAAI,EAAE,QAAQ,GACf,OAAO,CAAC,qBAAqB,CAAC;YA8MnB,aAAa;IAmB3B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAsCG;YACW,wBAAwB;IA6CtC,wFAAwF;YAC1E,eAAe;CAkBhC"}