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

package/dist/sql-guards.d.ts

@@ -0,0 +1,78 @@
+/**
+ * @fileoverview Validation for values that reach SQL text — applied at the
+ * operation boundary.
+ *
+ * THE PROBLEM. `RunView`'s `ExtraFilter` is composed as SQL, and this codebase
+ * builds filters by interpolating ids into template strings. That is safe for the
+ * overwhelming majority of sites, where the id was read out of the database a
+ * moment earlier and is a UUID by construction. It is NOT safe for the handful of
+ * values that arrive from a REMOTE CALLER: a remote operation's input is whatever
+ * the caller sent.
+ *
+ * WHY GUARD AT THE BOUNDARY RATHER THAN AT EVERY FILTER. An id from a caller is
+ * passed down through loaders and resolvers before it reaches a filter, sometimes
+ * several frames deep. Guarding each filter site would mean auditing every path a
+ * value can take and re-auditing it whenever someone adds a new one. Validating
+ * once, where untrusted data enters, makes everything downstream trusted by
+ * construction — and it is a single line per operation that a reviewer can check.
+ *
+ * WHY REJECT RATHER THAN ESCAPE. Doubling quotes would let a malformed id through
+ * to a query that then returns nothing, or worse, something. A caller that sends a
+ * non-UUID where a UUID belongs has a bug, and the useful response is to say so.
+ * Silently returning the wrong rows is the failure mode worth designing against:
+ * an injected `' OR 1=1 --` in a customer filter widens a result set rather than
+ * breaking it, so it reads as working software while disclosing other people's data.
+ *
+ * @module @mj-biz-apps/orders-core-entities-server
+ */
+/** Raised when caller-supplied input cannot safely reach a filter. */
+export declare class InvalidOperationInputError extends Error {
+    constructor(message: string);
+}
+/**
+ * Require a UUID, or throw.
+ *
+ * @param value The caller-supplied value.
+ * @param field Field name, used in the error so the caller can find their mistake.
+ * @returns The value, unchanged, once it is known to be a UUID.
+ * @throws {InvalidOperationInputError} If it is not a UUID.
+ */
+export declare function RequireUUID(value: string, field: string): string;
+/**
+ * Require a UUID when present. Absent stays absent — many id inputs are optional
+ * filters, and an omitted filter is not an invalid one.
+ */
+export declare function RequireOptionalUUID<T extends string | null | undefined>(value: T, field: string): T;
+/** Require every element of an id list to be a UUID. */
+export declare function RequireUUIDs(values: string[] | null | undefined, field: string): string[];
+/**
+ * Require an ISO date, returning just the `YYYY-MM-DD` portion.
+ *
+ * Dates are interpolated into comparisons, so they carry the same risk as ids.
+ * Truncating to the date part is deliberate: these filters compare days.
+ */
+export declare function RequireDate(value: string, field: string): string;
+/**
+ * Escape a free-text value for a SQL string literal.
+ *
+ * For the values that are legitimately text rather than ids — a provider's refund
+ * reference, a search term. Doubling the quote is the SQL Server escape.
+ */
+export declare function EscapeText(value: string): string;
+/**
+ * LOCAL FALLBACK for `EscapeSQLString` from `@memberjunction/global`.
+ *
+ * CLAUDE.md requires this function for SQL string escaping, but no published
+ * `@memberjunction/global` exports it — `6.1.0-edge.3` ships `Escape` and `EscapeHTML`
+ * and nothing else. Following the rule as written therefore broke the build. This keeps
+ * the rule followable at the call sites until MJ publishes the real one; delete it then
+ * and re-point `claimDriverHelpers.ts` and `GuestOrderClaimDriver.ts` at the package.
+ *
+ * Stricter than {@link EscapeText} on two counts, both of which CLAUDE.md calls out as
+ * the reasons to prefer `EscapeSQLString`: `null`/`undefined` become an empty string
+ * rather than the literal text `"null"`, and embedded null bytes are stripped — SQL
+ * Server truncates at `\0`, so a value carrying one can end a quoted literal early and
+ * leave the remainder of the input parsed as SQL.
+ */
+export declare function EscapeSQLString(value: string | null | undefined): string;
+//# sourceMappingURL=sql-guards.d.ts.map

package/dist/sql-guards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sql-guards.d.ts","sourceRoot":"","sources":["../src/sql-guards.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAIH,sEAAsE;AACtE,qBAAa,0BAA2B,SAAQ,KAAK;gBACrC,OAAO,EAAE,MAAM;CAI9B;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAKhE;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,SAAS,MAAM,GAAG,IAAI,GAAG,SAAS,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,GAAG,CAAC,CAInG;AAED,wDAAwD;AACxD,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,IAAI,GAAG,SAAS,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAGzF;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAYhE;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEhD;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAKxE"}

package/dist/sql-guards.js

@@ -0,0 +1,115 @@
+/**
+ * @fileoverview Validation for values that reach SQL text — applied at the
+ * operation boundary.
+ *
+ * THE PROBLEM. `RunView`'s `ExtraFilter` is composed as SQL, and this codebase
+ * builds filters by interpolating ids into template strings. That is safe for the
+ * overwhelming majority of sites, where the id was read out of the database a
+ * moment earlier and is a UUID by construction. It is NOT safe for the handful of
+ * values that arrive from a REMOTE CALLER: a remote operation's input is whatever
+ * the caller sent.
+ *
+ * WHY GUARD AT THE BOUNDARY RATHER THAN AT EVERY FILTER. An id from a caller is
+ * passed down through loaders and resolvers before it reaches a filter, sometimes
+ * several frames deep. Guarding each filter site would mean auditing every path a
+ * value can take and re-auditing it whenever someone adds a new one. Validating
+ * once, where untrusted data enters, makes everything downstream trusted by
+ * construction — and it is a single line per operation that a reviewer can check.
+ *
+ * WHY REJECT RATHER THAN ESCAPE. Doubling quotes would let a malformed id through
+ * to a query that then returns nothing, or worse, something. A caller that sends a
+ * non-UUID where a UUID belongs has a bug, and the useful response is to say so.
+ * Silently returning the wrong rows is the failure mode worth designing against:
+ * an injected `' OR 1=1 --` in a customer filter widens a result set rather than
+ * breaking it, so it reads as working software while disclosing other people's data.
+ *
+ * @module @mj-biz-apps/orders-core-entities-server
+ */
+const UUID = /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/;
+/** Raised when caller-supplied input cannot safely reach a filter. */
+export class InvalidOperationInputError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'InvalidOperationInputError';
+    }
+}
+/**
+ * Require a UUID, or throw.
+ *
+ * @param value The caller-supplied value.
+ * @param field Field name, used in the error so the caller can find their mistake.
+ * @returns The value, unchanged, once it is known to be a UUID.
+ * @throws {InvalidOperationInputError} If it is not a UUID.
+ */
+export function RequireUUID(value, field) {
+    if (typeof value !== 'string' || !UUID.test(value)) {
+        throw new InvalidOperationInputError(`${field} must be a UUID.`);
+    }
+    return value;
+}
+/**
+ * Require a UUID when present. Absent stays absent — many id inputs are optional
+ * filters, and an omitted filter is not an invalid one.
+ */
+export function RequireOptionalUUID(value, field) {
+    if (value === undefined || value === null || value === '')
+        return value;
+    RequireUUID(value, field);
+    return value;
+}
+/** Require every element of an id list to be a UUID. */
+export function RequireUUIDs(values, field) {
+    if (!values?.length)
+        return [];
+    return values.map((v) => RequireUUID(v, field));
+}
+/**
+ * Require an ISO date, returning just the `YYYY-MM-DD` portion.
+ *
+ * Dates are interpolated into comparisons, so they carry the same risk as ids.
+ * Truncating to the date part is deliberate: these filters compare days.
+ */
+export function RequireDate(value, field) {
+    // Validate the WHOLE string before truncating. Truncating first would accept
+    // `2026-03-04' OR '1'='1` by silently discarding the payload — safe by
+    // accident, and exactly the sanitise-don't-reject behaviour this module
+    // argues against: the caller never learns their input was wrong.
+    const whole = String(value);
+    const isDateOnly = /^\d{4}-\d{2}-\d{2}$/.test(whole);
+    const isDateTime = /^\d{4}-\d{2}-\d{2}[T ][\d:.]+(Z|[+-]\d{2}:?\d{2})?$/.test(whole);
+    if ((!isDateOnly && !isDateTime) || Number.isNaN(Date.parse(whole))) {
+        throw new InvalidOperationInputError(`${field} must be an ISO date (YYYY-MM-DD).`);
+    }
+    return whole.slice(0, 10);
+}
+/**
+ * Escape a free-text value for a SQL string literal.
+ *
+ * For the values that are legitimately text rather than ids — a provider's refund
+ * reference, a search term. Doubling the quote is the SQL Server escape.
+ */
+export function EscapeText(value) {
+    return String(value).replace(/'/g, "''");
+}
+/**
+ * LOCAL FALLBACK for `EscapeSQLString` from `@memberjunction/global`.
+ *
+ * CLAUDE.md requires this function for SQL string escaping, but no published
+ * `@memberjunction/global` exports it — `6.1.0-edge.3` ships `Escape` and `EscapeHTML`
+ * and nothing else. Following the rule as written therefore broke the build. This keeps
+ * the rule followable at the call sites until MJ publishes the real one; delete it then
+ * and re-point `claimDriverHelpers.ts` and `GuestOrderClaimDriver.ts` at the package.
+ *
+ * Stricter than {@link EscapeText} on two counts, both of which CLAUDE.md calls out as
+ * the reasons to prefer `EscapeSQLString`: `null`/`undefined` become an empty string
+ * rather than the literal text `"null"`, and embedded null bytes are stripped — SQL
+ * Server truncates at `\0`, so a value carrying one can end a quoted literal early and
+ * leave the remainder of the input parsed as SQL.
+ */
+export function EscapeSQLString(value) {
+    if (value === null || value === undefined) {
+        return '';
+    }
+    return String(value).replace(/\0/g, '').replace(/'/g, "''");
+}
+//# sourceMappingURL=sql-guards.js.map

package/dist/sql-guards.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sql-guards.js","sourceRoot":"","sources":["../src/sql-guards.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,MAAM,IAAI,GAAG,+EAA+E,CAAC;AAE7F,sEAAsE;AACtE,MAAM,OAAO,0BAA2B,SAAQ,KAAK;IACjD,YAAY,OAAe;QACvB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,4BAA4B,CAAC;IAC7C,CAAC;CACJ;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,WAAW,CAAC,KAAa,EAAE,KAAa;IACpD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QACjD,MAAM,IAAI,0BAA0B,CAAC,GAAG,KAAK,kBAAkB,CAAC,CAAC;IACrE,CAAC;IACD,OAAO,KAAK,CAAC;AACjB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CAAsC,KAAQ,EAAE,KAAa;IAC5F,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,EAAE;QAAE,OAAO,KAAK,CAAC;IACxE,WAAW,CAAC,KAAe,EAAE,KAAK,CAAC,CAAC;IACpC,OAAO,KAAK,CAAC;AACjB,CAAC;AAED,wDAAwD;AACxD,MAAM,UAAU,YAAY,CAAC,MAAmC,EAAE,KAAa;IAC3E,IAAI,CAAC,MAAM,EAAE,MAAM;QAAE,OAAO,EAAE,CAAC;IAC/B,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,WAAW,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC;AACpD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAC,KAAa,EAAE,KAAa;IACpD,6EAA6E;IAC7E,uEAAuE;IACvE,wEAAwE;IACxE,iEAAiE;IACjE,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;IAC5B,MAAM,UAAU,GAAG,qBAAqB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACrD,MAAM,UAAU,GAAG,qDAAqD,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACrF,IAAI,CAAC,CAAC,UAAU,IAAI,CAAC,UAAU,CAAC,IAAI,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC;QAClE,MAAM,IAAI,0BAA0B,CAAC,GAAG,KAAK,oCAAoC,CAAC,CAAC;IACvF,CAAC;IACD,OAAO,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AAC9B,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,UAAU,CAAC,KAAa;IACpC,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;AAC7C,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,eAAe,CAAC,KAAgC;IAC5D,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxC,OAAO,EAAE,CAAC;IACd,CAAC;IACD,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;AAChE,CAAC"}

package/package.json

@@ -1,8 +1,53 @@
 {
   "name": "@mj-biz-apps/orders-core-entities-server",
-  "version": "0.0.1",
-  "description": "Placeholder. Real releases come from https://github.com/MemberJunction/bizapps-orders",
+  "type": "module",
+  "version": "5.2.0",
+  "description": "Server-side entity subclasses for BizApps Orders — order booking (one JE per line), line computation, and lifecycle hooks.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "/dist"
+  ],
+  "author": "MemberJunction.com",
   "license": "BUSL-1.1",
-  "repository": { "type": "git", "url": "https://github.com/MemberJunction/bizapps-orders" },
-  "publishConfig": { "access": "public" }
-}
+  "devDependencies": {
+    "@mj-biz-apps/accounting-core-entities-server": ">=0.1.0",
+    "@mj-biz-apps/accounting-engine-base": ">=0.1.0",
+    "@mj-biz-apps/tasks-entities": "1.2.3",
+    "typescript": "^5.9.3",
+    "vite": "^7.1.5",
+    "vitest": "^4.0.18"
+  },
+  "dependencies": {
+    "@mj-biz-apps/orders-entities": "5.2.0"
+  },
+  "peerDependencies": {
+    "@memberjunction/communication-engine": "^6.1.0-edge.4",
+    "@memberjunction/communication-types": "^6.1.0-edge.4",
+    "@memberjunction/core": "^6.1.0-edge.4",
+    "@memberjunction/core-entities": "^6.1.0-edge.4",
+    "@memberjunction/core-entities-server": "^6.1.0-edge.4",
+    "@memberjunction/global": "^6.1.0-edge.4",
+    "@memberjunction/sqlserver-dataprovider": "^6.1.0-edge.4",
+    "@mj-biz-apps/accounting-core-entities-server": ">=0.1.0",
+    "@mj-biz-apps/accounting-engine-base": ">=0.1.0",
+    "@mj-biz-apps/tasks-entities": "^1.2.3"
+  },
+  "peerDependenciesMeta": {
+    "@mj-biz-apps/tasks-entities": {
+      "optional": true
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/MemberJunction/bizapps-orders"
+  },
+  "scripts": {
+    "build": "tsc && tsc-alias -f",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}