@mj-biz-apps/contracts-core-entities-server 0.1.0

package/dist/delete-guard.js

@@ -0,0 +1,107 @@
+/**
+ * @fileoverview R-8 — turning a foreign-key violation into a sentence.
+ *
+ * Every FK in this schema is `NO_ACTION`, which is the correct behaviour: a delete that would orphan
+ * data is refused. The problem is only that it reaches the user as a constraint name. Four entities
+ * need the same treatment and differ ONLY in which rows to count, so this is one guard parameterised
+ * by the dependencies rather than four copies of the same shape drifting apart — the review test from
+ * ORCHESTRATION.md ("if I had to change this logic, how many places would I have to find?").
+ *
+ * ## Why `Delete()` and not a validation hook
+ *
+ * `BaseEntity` has no delete-side counterpart to `Validate()` — no `ValidateDelete`, no `BeforeDelete`,
+ * no vetoable event. Verified by reading `_InnerDelete`, which runs no validation at all where
+ * `_InnerSave` runs `Validate()`/`ValidateAsync()` first. So the only seam is overriding `Delete()`.
+ * Filed upstream as [MJ#3971](https://github.com/MemberJunction/MJ/issues/3971), and a fix is already
+ * authored there; when it lands, these overrides become `ValidateDeleteAsync()` bodies and this file
+ * shrinks rather than disappears.
+ *
+ * ## Why it REGISTERS A RESULT and returns false, instead of throwing
+ *
+ * `bizapps-accounting`'s two precedents (`JournalEntryTypeEntityServer`, `JournalEntryLineEntityServer`)
+ * **throw**. That works, and it is not what this does, deliberately:
+ *
+ *   · `Delete()` is declared `Promise<boolean>`. A caller written against that signature does
+ *     `if (!await entity.Delete())` and gets an exception instead of `false`.
+ *   · `LatestResult` is how MJ carries the reason for a refused write — it is what `ResolverBase`
+ *     reads to build the GraphQL error, and what a refused `Save()` already populates. Throwing routes
+ *     around the one channel built for this.
+ *   · `RegisterResultHistoryEntry` is public precisely so a subclass can do this.
+ *
+ * ⚠ **This depends on an MJ fix to be VISIBLE.** `ResolverBase.DeleteRecord` read
+ * `LatestResult?.Message` rather than `CompleteMessage`, so a registered refusal reached the API as
+ * the literal string "Unknown error". Measured on this instance; the one-word fix is applied locally
+ * in `instances/contracts-mj6/mj` and was commented onto MJ#3973. **On an unpatched MJ these messages
+ * are correct and invisible** — the delete is still refused, so this is a message-quality dependency,
+ * not a correctness one.
+ *
+ * @module @mj-biz-apps/contracts-core-entities-server
+ */
+import { BaseEntityResult } from '@memberjunction/core';
+/**
+ * Count each dependency and return the refusal text, or null when nothing blocks the delete.
+ *
+ * COUNTS, NOT EXISTENCE. `count_only` costs the same as `TOP 1` on an indexed FK (MJ auto-indexes
+ * every FK), and the number is most of the value of the message.
+ *
+ * ALL dependencies are checked, not just the first. Deleting a template usually trips both its
+ * provisions and its contracts, and being told about one, fixing it, and then being refused again for
+ * the other is the worst version of this interaction.
+ *
+ * A FAILED COUNT ABORTS rather than defaulting to zero. Reading "could not verify" as "nothing
+ * references it" would let this guard wave through exactly the delete it exists to stop; the FK is
+ * still the floor, but a guard that fails open is worse than no guard because it looks like one.
+ */
+export async function DescribeDeleteBlockers(entity, dependencies) {
+    const blockers = [];
+    for (const dependency of dependencies) {
+        const result = await entity.RunViewProviderToUse.RunView({
+            EntityName: dependency.EntityName,
+            ExtraFilter: dependency.Filter,
+            ResultType: 'count_only',
+        }, entity.ContextCurrentUser);
+        if (!result?.Success) {
+            throw new Error(`Could not check whether ${dependency.EntityName} still references this record: ` +
+                `${result?.ErrorMessage ?? 'unknown error'}. The delete was not attempted.`);
+        }
+        const count = result.TotalRowCount ?? 0;
+        if (count > 0)
+            blockers.push(dependency.Describe(count));
+    }
+    return blockers.length > 0 ? blockers.join(' ') : null;
+}
+/**
+ * Record a delete refusal on the entity so `LatestResult` carries the reason, and return false.
+ *
+ * Registered BEFORE `super.Delete()` is ever called, so nothing else has written a result — `Message`
+ * is what `CompleteMessage` reads first, so the sentence survives without needing an `Errors` entry.
+ * There is no field to name: a delete refusal is about the record, not about one of its columns, which
+ * is part of why `ValidationErrorInfo` is the wrong vehicle here and MJ#3971 asks for a delete-shaped
+ * one.
+ */
+export function RefuseDelete(entity, message) {
+    const result = new BaseEntityResult();
+    result.Success = false;
+    result.Type = 'delete';
+    result.Message = message;
+    result.EndedAt = new Date();
+    entity.RegisterResultHistoryEntry(result);
+    return false;
+}
+/**
+ * The whole guard: count the blockers, refuse with an explanation if there are any, otherwise delete.
+ *
+ * Every subclass override is one call to this, which is the point — the only thing that varies between
+ * the four is the dependency list and the leading sentence.
+ */
+export async function GuardedDelete(entity, options, lead, dependencies, superDelete) {
+    const blockers = await DescribeDeleteBlockers(entity, dependencies);
+    if (blockers)
+        return RefuseDelete(entity, `${lead} ${blockers}`);
+    return superDelete(options);
+}
+/** `'1 contract'` / `'3 contracts'` — so a message never reads "1 contracts". */
+export function plural(count, singular, pluralForm) {
+    return `${count} ${count === 1 ? singular : (pluralForm ?? `${singular}s`)}`;
+}
+//# sourceMappingURL=delete-guard.js.map

package/dist/delete-guard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"delete-guard.js","sourceRoot":"","sources":["../src/delete-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,OAAO,EAAc,gBAAgB,EAA4B,MAAM,sBAAsB,CAAC;AAiB9F;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAAC,MAAkB,EAAE,YAAyC;IACtG,MAAM,QAAQ,GAAa,EAAE,CAAC;IAE9B,KAAK,MAAM,UAAU,IAAI,YAAY,EAAE,CAAC;QACpC,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,oBAAoB,CAAC,OAAO,CACpD;YACI,UAAU,EAAE,UAAU,CAAC,UAAU;YACjC,WAAW,EAAE,UAAU,CAAC,MAAM;YAC9B,UAAU,EAAE,YAAY;SAC3B,EACD,MAAM,CAAC,kBAAkB,CAC5B,CAAC;QACF,IAAI,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC;YACnB,MAAM,IAAI,KAAK,CACX,2BAA2B,UAAU,CAAC,UAAU,iCAAiC;gBAC7E,GAAG,MAAM,EAAE,YAAY,IAAI,eAAe,iCAAiC,CAClF,CAAC;QACN,CAAC;QACD,MAAM,KAAK,GAAG,MAAM,CAAC,aAAa,IAAI,CAAC,CAAC;QACxC,IAAI,KAAK,GAAG,CAAC;YAAE,QAAQ,CAAC,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC;IAC7D,CAAC;IAED,OAAO,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AAC3D,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,YAAY,CAAC,MAAkB,EAAE,OAAe;IAC5D,MAAM,MAAM,GAAG,IAAI,gBAAgB,EAAE,CAAC;IACtC,MAAM,CAAC,OAAO,GAAG,KAAK,CAAC;IACvB,MAAM,CAAC,IAAI,GAAG,QAAQ,CAAC;IACvB,MAAM,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,MAAM,CAAC,OAAO,GAAG,IAAI,IAAI,EAAE,CAAC;IAC5B,MAAM,CAAC,0BAA0B,CAAC,MAAM,CAAC,CAAC;IAC1C,OAAO,KAAK,CAAC;AACjB,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAC/B,MAAkB,EAClB,OAAwC,EACxC,IAAY,EACZ,YAAyC,EACzC,WAAgE;IAEhE,MAAM,QAAQ,GAAG,MAAM,sBAAsB,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IACpE,IAAI,QAAQ;QAAE,OAAO,YAAY,CAAC,MAAM,EAAE,GAAG,IAAI,IAAI,QAAQ,EAAE,CAAC,CAAC;IACjE,OAAO,WAAW,CAAC,OAAO,CAAC,CAAC;AAChC,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,MAAM,CAAC,KAAa,EAAE,QAAgB,EAAE,UAAmB;IACvE,OAAO,GAAG,KAAK,IAAI,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,UAAU,IAAI,GAAG,QAAQ,GAAG,CAAC,EAAE,CAAC;AACjF,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+export { ContractEntityServer, IsNewlySelected, LoadContractEntityServer } from './ContractEntityServer.js';
+export { ContractTemplateModificationEntityServer, LoadContractTemplateModificationEntityServer, } from './ContractTemplateModificationEntityServer.js';
+export { ContractTemplateEntityServer, LoadContractTemplateEntityServer } from './ContractTemplateEntityServer.js';
+export { ContractTemplateProvisionEntityServer, LoadContractTemplateProvisionEntityServer, } from './ContractTemplateProvisionEntityServer.js';
+export { ContractTemplateTypeEntityServer, ContractTypeEntityServer, LoadContractTypeEntityServers, } from './ContractTypeEntityServers.js';
+export * from './delete-guard.js';
+/**
+ * Called by the server bootstrap. The imports above are what fire @RegisterClass; these calls are
+ * anti-tree-shake anchors — without a live reference a production build can drop the import and the
+ * subclasses silently never register, so every invariant in them stops existing with no error.
+ */
+export declare function LoadMjBizappsContractsEntitiesServer(): void;
+export { SupersedeOperation, LoadSupersedeOperation } from './SupersedeOperation.js';
+export type { SupersedeInput, SupersedeOutput } from './SupersedeOperation.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AA2BA,OAAO,EAAE,oBAAoB,EAAE,eAAe,EAAE,wBAAwB,EAAE,MAAM,2BAA2B,CAAC;AAC5G,OAAO,EACH,wCAAwC,EACxC,4CAA4C,GAC/C,MAAM,+CAA+C,CAAC;AACvD,OAAO,EAAE,4BAA4B,EAAE,gCAAgC,EAAE,MAAM,mCAAmC,CAAC;AACnH,OAAO,EACH,qCAAqC,EACrC,yCAAyC,GAC5C,MAAM,4CAA4C,CAAC;AACpD,OAAO,EACH,gCAAgC,EAChC,wBAAwB,EACxB,6BAA6B,GAChC,MAAM,gCAAgC,CAAC;AACxC,cAAc,mBAAmB,CAAC;AAElC;;;;GAIG;AACH,wBAAgB,oCAAoC,IAAI,IAAI,CAS3D;AAGD,OAAO,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,MAAM,yBAAyB,CAAC;AACrF,YAAY,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC"}

package/dist/index.js

@@ -0,0 +1,49 @@
+/**
+ * @mj-biz-apps/contracts-core-entities-server — SERVER-ONLY entity subclasses. This package must
+ * NEVER be imported by client code; it is a dependency of the Server package only.
+ *
+ * WHAT BELONGS HERE, AND WHAT DOES NOT (plan §6.3). A rule lives here only when it CANNOT run in the
+ * browser — it needs a transaction, a lock, or a cross-entity read the client has no business doing.
+ * Everything the browser should be able to preflight lives on the SHARED subclass in
+ * @mj-biz-apps/contracts-entities instead, so the user sees the error before the round trip.
+ *
+ * Dependency shape in package.json: the sibling app package (@mj-biz-apps/contracts-entities) is a
+ * HARD dependency pinned to the same version (all app packages version together via changesets
+ * `fixed`); every @memberjunction/* package is a PEER (^X.Y.Z).
+ *
+ * TWO SUBCLASSES, and that is the whole server surface. v1 had nine of these plus ContractsEngine,
+ * ChildCollection, BillingDraft and seven remote operations — the billing engine wholesale. v2 is a
+ * record-keeping app and MJ 6's graph save replaced the composition machinery, so what is left is
+ * the contract number (needs a lock) and two modification invariants (need cross-entity reads).
+ * **Zero remote operations.**
+ */
+import { LoadContractEntityServer } from './ContractEntityServer.js';
+import { LoadContractTemplateEntityServer } from './ContractTemplateEntityServer.js';
+import { LoadContractTemplateProvisionEntityServer } from './ContractTemplateProvisionEntityServer.js';
+import { LoadContractTypeEntityServers } from './ContractTypeEntityServers.js';
+import { LoadContractTemplateModificationEntityServer } from './ContractTemplateModificationEntityServer.js';
+import { LoadSupersedeOperation } from './SupersedeOperation.js';
+export { ContractEntityServer, IsNewlySelected, LoadContractEntityServer } from './ContractEntityServer.js';
+export { ContractTemplateModificationEntityServer, LoadContractTemplateModificationEntityServer, } from './ContractTemplateModificationEntityServer.js';
+export { ContractTemplateEntityServer, LoadContractTemplateEntityServer } from './ContractTemplateEntityServer.js';
+export { ContractTemplateProvisionEntityServer, LoadContractTemplateProvisionEntityServer, } from './ContractTemplateProvisionEntityServer.js';
+export { ContractTemplateTypeEntityServer, ContractTypeEntityServer, LoadContractTypeEntityServers, } from './ContractTypeEntityServers.js';
+export * from './delete-guard.js';
+/**
+ * Called by the server bootstrap. The imports above are what fire @RegisterClass; these calls are
+ * anti-tree-shake anchors — without a live reference a production build can drop the import and the
+ * subclasses silently never register, so every invariant in them stops existing with no error.
+ */
+export function LoadMjBizappsContractsEntitiesServer() {
+    LoadContractEntityServer();
+    LoadSupersedeOperation();
+    LoadContractTemplateModificationEntityServer();
+    // R-8's delete guards. These have NO Validate/Save rules at all, so a dropped registration is
+    // completely silent: deletes keep being refused by the FK, just with a constraint name again.
+    LoadContractTemplateEntityServer();
+    LoadContractTemplateProvisionEntityServer();
+    LoadContractTypeEntityServers();
+}
+// Re-papering: the cross-record write the browser must not do itself (see the file header, and MJ#4002).
+export { SupersedeOperation, LoadSupersedeOperation } from './SupersedeOperation.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,EAAE,wBAAwB,EAAE,MAAM,2BAA2B,CAAC;AACrE,OAAO,EAAE,gCAAgC,EAAE,MAAM,mCAAmC,CAAC;AACrF,OAAO,EAAE,yCAAyC,EAAE,MAAM,4CAA4C,CAAC;AACvG,OAAO,EAAE,6BAA6B,EAAE,MAAM,gCAAgC,CAAC;AAC/E,OAAO,EAAE,4CAA4C,EAAE,MAAM,+CAA+C,CAAC;AAE7G,OAAO,EAAE,sBAAsB,EAAE,MAAM,yBAAyB,CAAC;AAEjE,OAAO,EAAE,oBAAoB,EAAE,eAAe,EAAE,wBAAwB,EAAE,MAAM,2BAA2B,CAAC;AAC5G,OAAO,EACH,wCAAwC,EACxC,4CAA4C,GAC/C,MAAM,+CAA+C,CAAC;AACvD,OAAO,EAAE,4BAA4B,EAAE,gCAAgC,EAAE,MAAM,mCAAmC,CAAC;AACnH,OAAO,EACH,qCAAqC,EACrC,yCAAyC,GAC5C,MAAM,4CAA4C,CAAC;AACpD,OAAO,EACH,gCAAgC,EAChC,wBAAwB,EACxB,6BAA6B,GAChC,MAAM,gCAAgC,CAAC;AACxC,cAAc,mBAAmB,CAAC;AAElC;;;;GAIG;AACH,MAAM,UAAU,oCAAoC;IAChD,wBAAwB,EAAE,CAAC;IAC3B,sBAAsB,EAAE,CAAC;IACzB,4CAA4C,EAAE,CAAC;IAC/C,8FAA8F;IAC9F,8FAA8F;IAC9F,gCAAgC,EAAE,CAAC;IACnC,yCAAyC,EAAE,CAAC;IAC5C,6BAA6B,EAAE,CAAC;AACpC,CAAC;AAED,yGAAyG;AACzG,OAAO,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,MAAM,yBAAyB,CAAC"}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "mjdevManaged": "MJDEV-MANAGED: mjdev owns parts of this file — the \"packages/dev-apps/*\" workspaces glob, any dev-linked open-app dependencies (e.g. \"@mj-biz-apps/*\"), and the Angular \"overrides\" pin set. Do not hand-edit those; the tool wires and reverts them. They are left visible in git status, but the git-tree guard blocks committing them. See .mjdev-docs/MANAGED-FILES.md; revert with `mjdev git:stage-clean <slug> package.json`.",
+  "name": "@mj-biz-apps/contracts-core-entities-server",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Server-side entity subclass overrides (validation, computed fields, save hooks). TODO(template): rename.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/MemberJunction/bizapps-contracts"
+  },
+  "license": "BUSL-1.1",
+  "dependencies": {
+    "@mj-biz-apps/contracts-entities": "^0.1.0"
+  },
+  "peerDependencies": {
+    "@memberjunction/core": "^6.1.0-edge.3",
+    "@memberjunction/core-entities": "^6.1.0-edge.3",
+    "@memberjunction/global": "^6.1.0-edge.3",
+    "@memberjunction/sqlserver-dataprovider": "^6.1.0-edge.3"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  },
+  "files": [
+    "/dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc && tsc-alias -f",
+    "test": "echo \"No tests configured yet\""
+  }
+}