@mj-biz-apps/orders-entities 5.23.0 → 5.24.0

package/dist/ProductEntity.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Shared Product subclass: a product takes its type's defaults when the type is chosen
+ * (bc-aidp-next-golive#277).
+ *
+ * `ProductType` carries `DefaultRevenueRecognitionTypeID`, `DefaultSubscriptionTypeID` and
+ * `DefaultIsTaxable`. Nothing copied them onto a new product, so `RevenueRecognitionTypeID` (NOT
+ * NULL) refused the save until it was set by hand, and `SubscriptionTypeID` / `IsTaxable` saved null.
+ *
+ * Lives here rather than in the form so every caller gets it: the form, a Remote Operation, an
+ * integration, a script.
+ */
+import { type EntitySaveOptions, type FieldValueCollection } from '@memberjunction/core';
+import { mjBizAppsOrdersProductEntity } from './generated/entity_subclasses.js';
+import { OrdersEngine } from './pricing/OrdersEngine.js';
+/** The product fields a product type supplies a default for. */
+export type ProductDefaults = {
+    RevenueRecognitionTypeID: string | null;
+    SubscriptionTypeID: string | null;
+    IsTaxable: boolean | null;
+};
+export declare const PRODUCT_DEFAULT_FIELDS: readonly ["RevenueRecognitionTypeID", "SubscriptionTypeID", "IsTaxable"];
+export type ProductDefaultField = (typeof PRODUCT_DEFAULT_FIELDS)[number];
+/** The lookups default resolution reads. `OrdersEngine` satisfies it. */
+export type ProductDefaultsLookup = Pick<OrdersEngine, 'ProductTypeByID' | 'ProductCategoryByID' | 'CategoryChain'>;
+/**
+ * The defaults a product of this type, in this category, starts with. Null when the type is unknown.
+ *
+ * Taxability is the answer the taxability walk gives a product that says nothing itself — its
+ * category chain, nearest first, then the type. The type's `DefaultIsTaxable` alone would stamp
+ * "taxable" onto a product whose category is exempt.
+ */
+export declare function ResolveProductDefaults(lookup: ProductDefaultsLookup, productTypeID: string | null | undefined, productCategoryID: string | null | undefined): ProductDefaults | null;
+/**
+ * Which default fields to write, and with what.
+ *
+ * A field takes the new default when it is empty, or when it still holds the value this record
+ * stamped earlier — i.e. it came from the previous type, not from the user. A value the user chose
+ * is never overwritten. When the new type has no default for a field it stamped, the stamp is
+ * cleared, so switching Subscription → Merchandise does not leave Annual Rolling behind.
+ */
+export declare function PlanProductDefaultWrites(current: ProductDefaults, stamped: Partial<ProductDefaults>, next: ProductDefaults): Partial<ProductDefaults>;
+export declare class ProductEntity extends mjBizAppsOrdersProductEntity {
+    /** What this instance wrote from a type default, per field — the values it may replace later. */
+    private stampedDefaults;
+    /**
+     * Applies the defaults when the type or category changes. Form fields and the typed setters
+     * both write through `Set`; loads do not (they use `SetMany`), so a loaded product is untouched.
+     */
+    Set(FieldName: string, Value: unknown): void;
+    /** A record created with `ProductTypeID` in `newValues` never passes through `Set`. */
+    NewRecord(newValues?: FieldValueCollection): boolean;
+    /**
+     * The same fill before a new product saves, after loading the engine — a caller whose engine
+     * was not loaded when the type was set still saves with the type's defaults. Existing products
+     * are not touched here: a null `IsTaxable` on a saved product is not this save's to change.
+     */
+    Save(options?: EntitySaveOptions): Promise<boolean>;
+    /** Synchronous: reads the engine only when it is already loaded. */
+    protected applyTypeDefaults(): void;
+}
+//# sourceMappingURL=ProductEntity.d.ts.map

package/dist/ProductEntity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ProductEntity.d.ts","sourceRoot":"","sources":["../src/ProductEntity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EAAc,KAAK,iBAAiB,EAAE,KAAK,oBAAoB,EAAoC,MAAM,sBAAsB,CAAC;AAEvI,OAAO,EAAE,4BAA4B,EAAE,MAAM,+BAA+B,CAAC;AAC7E,OAAO,EAAoB,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAKxE,gEAAgE;AAChE,MAAM,MAAM,eAAe,GAAG;IAC1B,wBAAwB,EAAE,MAAM,GAAG,IAAI,CAAC;IACxC,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,SAAS,EAAE,OAAO,GAAG,IAAI,CAAC;CAC7B,CAAC;AAEF,eAAO,MAAM,sBAAsB,0EAA2E,CAAC;AAC/G,MAAM,MAAM,mBAAmB,GAAG,CAAC,OAAO,sBAAsB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE1E,yEAAyE;AACzE,MAAM,MAAM,qBAAqB,GAAG,IAAI,CAAC,YAAY,EAAE,iBAAiB,GAAG,qBAAqB,GAAG,eAAe,CAAC,CAAC;AAEpH;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAClC,MAAM,EAAE,qBAAqB,EAC7B,aAAa,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACxC,iBAAiB,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAC7C,eAAe,GAAG,IAAI,CAqBxB;AAYD;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CACpC,OAAO,EAAE,eAAe,EACxB,OAAO,EAAE,OAAO,CAAC,eAAe,CAAC,EACjC,IAAI,EAAE,eAAe,GACtB,OAAO,CAAC,eAAe,CAAC,CAS1B;AAED,qBACa,aAAc,SAAQ,4BAA4B;IAC3D,iGAAiG;IACjG,OAAO,CAAC,eAAe,CAAgC;IAEvD;;;OAGG;IACa,GAAG,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI;IAS5D,uFAAuF;IACvE,SAAS,CAAC,SAAS,CAAC,EAAE,oBAAoB,GAAG,OAAO;IAMpE;;;;OAIG;IACmB,IAAI,CAAC,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,OAAO,CAAC;IAYzE,oEAAoE;IACpE,SAAS,CAAC,iBAAiB,IAAI,IAAI;CAqBtC"}

package/dist/ProductEntity.js

@@ -0,0 +1,146 @@
+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;
+};
+/**
+ * Shared Product subclass: a product takes its type's defaults when the type is chosen
+ * (bc-aidp-next-golive#277).
+ *
+ * `ProductType` carries `DefaultRevenueRecognitionTypeID`, `DefaultSubscriptionTypeID` and
+ * `DefaultIsTaxable`. Nothing copied them onto a new product, so `RevenueRecognitionTypeID` (NOT
+ * NULL) refused the save until it was set by hand, and `SubscriptionTypeID` / `IsTaxable` saved null.
+ *
+ * Lives here rather than in the form so every caller gets it: the form, a Remote Operation, an
+ * integration, a script.
+ */
+import { BaseEntity, LogError } from '@memberjunction/core';
+import { RegisterClass } from '@memberjunction/global';
+import { mjBizAppsOrdersProductEntity } from './generated/entity_subclasses.js';
+import { LoadOrdersEngine, OrdersEngine } from './pricing/OrdersEngine.js';
+import { ResolveTaxability } from './pricing/TaxResolver.js';
+const ENTITY = 'MJ_BizApps_Orders: Products';
+export const PRODUCT_DEFAULT_FIELDS = ['RevenueRecognitionTypeID', 'SubscriptionTypeID', 'IsTaxable'];
+/**
+ * The defaults a product of this type, in this category, starts with. Null when the type is unknown.
+ *
+ * Taxability is the answer the taxability walk gives a product that says nothing itself — its
+ * category chain, nearest first, then the type. The type's `DefaultIsTaxable` alone would stamp
+ * "taxable" onto a product whose category is exempt.
+ */
+export function ResolveProductDefaults(lookup, productTypeID, productCategoryID) {
+    const type = lookup.ProductTypeByID(productTypeID);
+    if (!type)
+        return null;
+    const chain = [];
+    for (const id of lookup.CategoryChain(productCategoryID)) {
+        const row = lookup.ProductCategoryByID(id);
+        if (!row)
+            break;
+        chain.push({ ID: row.ID, DefaultIsTaxable: row.DefaultIsTaxable, DefaultTaxCategory: row.DefaultTaxCategory });
+    }
+    const taxability = ResolveTaxability({ IsTaxable: null, TaxCategory: null }, chain, { DefaultIsTaxable: type.DefaultIsTaxable, DefaultTaxCategory: type.DefaultTaxCategory ?? null });
+    return {
+        RevenueRecognitionTypeID: type.DefaultRevenueRecognitionTypeID?.trim() || null,
+        SubscriptionTypeID: type.DefaultSubscriptionTypeID?.trim() || null,
+        IsTaxable: taxability.IsTaxable,
+    };
+}
+const isEmpty = (v) => v == null || (typeof v === 'string' && v.trim() === '');
+const sameValue = (a, b) => {
+    if (isEmpty(a) && isEmpty(b))
+        return true;
+    if (typeof a === 'string' && typeof b === 'string')
+        return a.trim().toLowerCase() === b.trim().toLowerCase();
+    return a === b;
+};
+/**
+ * Which default fields to write, and with what.
+ *
+ * A field takes the new default when it is empty, or when it still holds the value this record
+ * stamped earlier — i.e. it came from the previous type, not from the user. A value the user chose
+ * is never overwritten. When the new type has no default for a field it stamped, the stamp is
+ * cleared, so switching Subscription → Merchandise does not leave Annual Rolling behind.
+ */
+export function PlanProductDefaultWrites(current, stamped, next) {
+    const writes = {};
+    for (const field of PRODUCT_DEFAULT_FIELDS) {
+        const stillStamped = field in stamped && sameValue(stamped[field], current[field]);
+        if (!isEmpty(current[field]) && !stillStamped)
+            continue;
+        if (sameValue(current[field], next[field]))
+            continue;
+        writes[field] = next[field];
+    }
+    return writes;
+}
+let ProductEntity = class ProductEntity extends mjBizAppsOrdersProductEntity {
+    constructor() {
+        super(...arguments);
+        /** What this instance wrote from a type default, per field — the values it may replace later. */
+        this.stampedDefaults = {};
+    }
+    /**
+     * Applies the defaults when the type or category changes. Form fields and the typed setters
+     * both write through `Set`; loads do not (they use `SetMany`), so a loaded product is untouched.
+     */
+    Set(FieldName, Value) {
+        const watched = FieldName === 'ProductTypeID' || FieldName === 'ProductCategoryID';
+        const before = watched ? this.Get(FieldName) : undefined;
+        super.Set(FieldName, Value);
+        if (watched && !sameValue(before, this.Get(FieldName))) {
+            this.applyTypeDefaults();
+        }
+    }
+    /** A record created with `ProductTypeID` in `newValues` never passes through `Set`. */
+    NewRecord(newValues) {
+        const created = super.NewRecord(newValues);
+        if (created)
+            this.applyTypeDefaults();
+        return created;
+    }
+    /**
+     * The same fill before a new product saves, after loading the engine — a caller whose engine
+     * was not loaded when the type was set still saves with the type's defaults. Existing products
+     * are not touched here: a null `IsTaxable` on a saved product is not this save's to change.
+     */
+    async Save(options) {
+        if (!this.IsSaved) {
+            try {
+                await LoadOrdersEngine(this.ProviderToUse, this.ContextCurrentUser);
+                this.applyTypeDefaults();
+            }
+            catch (e) {
+                LogError(`Product type defaults not applied — OrdersEngine unavailable: ${e}`);
+            }
+        }
+        return super.Save(options);
+    }
+    /** Synchronous: reads the engine only when it is already loaded. */
+    applyTypeDefaults() {
+        const engine = OrdersEngine.Instance;
+        if (!engine.Loaded)
+            return;
+        const next = ResolveProductDefaults(engine, this.ProductTypeID, this.ProductCategoryID);
+        if (!next)
+            return;
+        const writes = PlanProductDefaultWrites({
+            RevenueRecognitionTypeID: this.RevenueRecognitionTypeID ?? null,
+            SubscriptionTypeID: this.SubscriptionTypeID ?? null,
+            IsTaxable: this.IsTaxable ?? null,
+        }, this.stampedDefaults, next);
+        if ('RevenueRecognitionTypeID' in writes)
+            this.RevenueRecognitionTypeID = writes.RevenueRecognitionTypeID;
+        if ('SubscriptionTypeID' in writes)
+            this.SubscriptionTypeID = writes.SubscriptionTypeID ?? null;
+        if ('IsTaxable' in writes)
+            this.IsTaxable = writes.IsTaxable ?? null;
+        this.stampedDefaults = { ...this.stampedDefaults, ...writes };
+    }
+};
+ProductEntity = __decorate([
+    RegisterClass(BaseEntity, ENTITY)
+], ProductEntity);
+export { ProductEntity };
+//# sourceMappingURL=ProductEntity.js.map

package/dist/ProductEntity.js.map

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

package/dist/billing-location.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Billing location — the facts a sale needs to be placed in a taxing jurisdiction.
+ *
+ * A card sale taken with no location can never be assigned to a state or country afterwards, so
+ * the self-serve checkout refuses to take payment without one. Country is ISO 3166-1 alpha-2;
+ * the region is the ISO 3166-2 subdivision code WITHOUT its country prefix (`IL`, not `US-IL`),
+ * because that is the form `TaxJurisdiction.RegionCode` holds and jurisdiction matching compares
+ * the two directly.
+ *
+ * The lists live here, beside the entities, so the widget's pickers and the server's check read
+ * the same data and cannot disagree about what a valid location is.
+ *
+ * @module @mj-biz-apps/orders-entities/billing-location
+ */
+/** A country or subdivision as a picker shows it. */
+export interface LocationOption {
+    Code: string;
+    Name: string;
+}
+/** A location that passed {@link CheckBillingLocation}, normalised to upper-case codes. */
+export interface BillingLocation {
+    Country: string;
+    StateProvince: string | null;
+    PostalCode: string | null;
+}
+export type BillingLocationCheck = {
+    Valid: true;
+    Location: BillingLocation;
+} | {
+    Valid: false;
+    Reason: string;
+};
+/** ISO 3166-1 alpha-2, by English short name. */
+export declare const BILLING_COUNTRIES: ReadonlyArray<LocationOption>;
+/** ISO 3166-2 subdivisions, country prefix removed. Only the countries that require one are listed. */
+export declare const BILLING_SUBDIVISIONS: Readonly<Record<string, ReadonlyArray<LocationOption>>>;
+/** The subdivisions to offer for a country — empty when the country does not require one. */
+export declare function BillingSubdivisionsFor(countryCode: string | null | undefined): ReadonlyArray<LocationOption>;
+/** True when the country's sales cannot be placed without a state or province. */
+export declare function BillingSubdivisionRequired(countryCode: string | null | undefined): boolean;
+/** True when the country's postal code is required, and so shape-checked. */
+export declare function BillingPostalCodeRequired(countryCode: string | null | undefined): boolean;
+/**
+ * Check a caller-supplied location and normalise it.
+ *
+ * Accepts only codes from the lists above: a free-text region such as "Illinois" is refused,
+ * because a name cannot be matched to a jurisdiction and a mistyped one would silently match none.
+ */
+export declare function CheckBillingLocation(input: unknown): BillingLocationCheck;
+//# sourceMappingURL=billing-location.d.ts.map

package/dist/billing-location.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"billing-location.d.ts","sourceRoot":"","sources":["../src/billing-location.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,qDAAqD;AACrD,MAAM,WAAW,cAAc;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CAChB;AAED,2FAA2F;AAC3F,MAAM,WAAW,eAAe;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAED,MAAM,MAAM,oBAAoB,GAC1B;IAAE,KAAK,EAAE,IAAI,CAAC;IAAC,QAAQ,EAAE,eAAe,CAAA;CAAE,GAC1C;IAAE,KAAK,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEvC,iDAAiD;AACjD,eAAO,MAAM,iBAAiB,EAAE,aAAa,CAAC,cAAc,CA0P3D,CAAC;AAEF,uGAAuG;AACvG,eAAO,MAAM,oBAAoB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,cAAc,CAAC,CAAC,CAqFxF,CAAC;AAcF,6FAA6F;AAC7F,wBAAgB,sBAAsB,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,aAAa,CAAC,cAAc,CAAC,CAE5G;AAED,kFAAkF;AAClF,wBAAgB,0BAA0B,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAE1F;AAED,6EAA6E;AAC7E,wBAAgB,yBAAyB,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAEzF;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,oBAAoB,CAoBzE"}