@endora-commerce/mod-promotions 0.100.0

package/dist/backend/services/promotion-service.d.ts

@@ -0,0 +1,312 @@
+import type { EntityManager } from '@mikro-orm/postgresql';
+import { type AttributeValueType, type CartSnapshot, type CatalogProductReadPort, type DictionaryValidator, type PromotionAction, type PromotionApplication, type PromotionCriterion, type PromotionRule } from '@endora-commerce/contracts';
+import type { AuditPort, SalesChannelMembershipPort } from '@endora-commerce/platform/kernel';
+import { Promotion } from '../entities/promotion.entity.js';
+import { type PromotionActionRegistry } from './promotion-action-registry.js';
+import { type FinalizeAppliedPromotion, type UsageContext } from './promotion-usage-service.js';
+/**
+ * The one question this service asks about promotion-rule attribute metadata.
+ * `catalog`'s `CatalogPromoAttributePort` (feature 075, Phase P) satisfies it,
+ * and `backend.ts` resolves that port by its published contract type; the
+ * narrower shape stays here because a rule evaluation never needs the port's
+ * other method.
+ */
+export interface PromotionRuleCatalogPort {
+    getAttributeWithOptions(key: string): Promise<{
+        id: string;
+        key: string;
+        valueType: AttributeValueType;
+        isPromoRule: boolean;
+        options: Array<{
+            value: string;
+            label: Record<string, string>;
+            labelDefault: string;
+        }>;
+    } | null>;
+}
+/** Audit-log sink for FR-039 skip events. Defaults to `console.info`. */
+export interface PromotionAuditLogger {
+    info(message: string, fields?: Record<string, unknown>): void;
+}
+/**
+ * PromotionService (T132 / FR-052).
+ *
+ * `applyToCart(snapshot)` walks every active, in-window promotion and
+ * applies the ones the cart is eligible for, returning the adjusted
+ * subtotal / discountTotal / deliveryTotal / total + a per-promotion
+ * audit list.
+ *
+ * Application order: code-presented promotions first (so a coupon
+ * always trumps an automatic), then automatic ones in `value` desc.
+ * Discounts never push the subtotal below zero or delivery below zero.
+ */
+export declare class PromotionService {
+    #private;
+    private readonly emFactory;
+    /**
+     * Feature 012 / US8 — `catalogPromoAttributePort`, owned by `catalog`: the
+     * attribute metadata a rule criterion is validated and evaluated against.
+     *
+     * **Required** (issue #164). It used to be optional "so legacy tests /
+     * composition setups that don't wire this stay green", and production
+     * always passed it — an optional dependency nobody omits is a lie in the
+     * type: it tells every reader that absence is supported, and it makes the
+     * absent branch untested by construction. Both consequences were real.
+     * `validateCriteria` opened by returning early, so a composition without
+     * the port **accepted a promotion naming an attribute that does not
+     * exist**; and no test covered that, because the ten call sites that
+     * omitted the port were the ones that never exercised attributes.
+     *
+     * There is no degrade left to express. Absence is not a state the platform
+     * can be in: the container resolves this port for every composition, and
+     * `catalog` being switched off makes the call **throw**
+     * `ModuleDisabledError` at the resolution seam — which is the explicit
+     * answer, and it is the owner's to give. What remains is
+     * `getAttributeWithOptions` answering `null`, already explicit in its
+     * return type and meaning what it says: no such attribute.
+     */
+    private readonly catalogPort;
+    /**
+     * Feature 075 Phase C — `catalogProductReadPort`, owned by `catalog`. It
+     * replaced an `em.find(Product, …)` this module wrote against `catalog`'s
+     * table to hydrate a cart line's attribute values, and it is required for
+     * the reason above: a composition that could not read products evaluated
+     * every attribute criterion against a line with no attribute values, which
+     * is not a degrade an operator would recognise as one.
+     */
+    private readonly productReadPort;
+    /**
+     * Feature 005 / T027b — the sanctioned bridge accessor for
+     * `sales_channel_promotions`: it auto-binds a newly-created Promotion to
+     * the system-default channel, and it answers which promotions a channel
+     * holds when a cart is evaluated.
+     *
+     * **Required** (issue #251), and of the four this is the one whose absent
+     * form was a Principle XII hole rather than a quiet one. Omitting it did
+     * two things at once: a new promotion bound to **no** channel, and
+     * `applyToCart` skipped channel filtering altogether — so a promotion an
+     * operator scoped to one channel applied in every one of them. Both roots
+     * passed the service, so nothing was live; every service built by
+     * `test/helpers/promotion-service.ts` was not, which is ten suites
+     * asserting against a promotion engine with no channel scope.
+     *
+     * There is no degrade to express in a return type. `sales_channels` is
+     * `nonDeactivatable` and `salesChannelMembershipPort` is a
+     * platform-owned container name besides, so absence is not a state a
+     * composition can reach.
+     */
+    private readonly salesChannelMembership;
+    /**
+     * Feature 037 — the dictionary reference validator, owned by
+     * `dictionaries`: it is what makes a promotion's `currency` a code the
+     * platform actually knows.
+     *
+     * **Required** (issue #251). `validateCurrency` opened with "no validator,
+     * no validation" and returned, so a composition without it stored a
+     * promotion denominated in a currency that does not exist — and the
+     * failure surfaced far downstream, at the cart, as a discount in a
+     * currency nothing could price. `dictionaries` is a declared dependency
+     * and is `nonDeactivatable`, so absence is not a state a composition can
+     * reach; an unknown or withdrawn code is already explicit, as the 409 this
+     * method raises.
+     */
+    private readonly dictionaryValidator;
+    /**
+     * Feature 026 US5 — the Organization status gate: an org-targeted
+     * promotion only applies while its Organization is `active`.
+     *
+     * **Required** (issue #251), and the one `backend.ts` already named in its
+     * own comment as *"a gate whose absent form is open"*. Omitted, the check
+     * was skipped entirely, so a `blocked` (formerly `suspended`) or
+     * `pending_verification` customer kept collecting its negotiated
+     * discounts — the exact thing US5 exists to stop.
+     *
+     * The degrade that **is** real stays in the return type, the way
+     * `allowedIdsFor(): Promise<string[] | null>` does: `null` means the
+     * Organization could not be read (missing or soft-deleted), and a status
+     * that is not `active` — `null` included — skips the org-targeted
+     * promotion. That is a closed answer, and it is the only absence this
+     * argument has.
+     */
+    private readonly resolveOrganizationStatus;
+    /**
+     * Feature 054 — co-transactional audit sink (`audit_log_entries`),
+     * Principle XIII.
+     *
+     * **Required** (issue #251). Without it every promotion create, update and
+     * delete committed with no audit row, which is not a degrade — it is the
+     * write happening unrecorded. `auditLogService` is a platform-owned
+     * container name that every composition supplies, so there was never a
+     * composition the absent branch described.
+     */
+    private readonly auditLog;
+    /** Feature 012 / US8 — audit sink for FR-039 skip-on-toggle events. */
+    private readonly auditLogger;
+    /** Feature 045 — pluggable action catalogue. Defaults to the built-ins. */
+    private readonly actionRegistry;
+    constructor(emFactory: () => EntityManager, 
+    /**
+     * Feature 012 / US8 — `catalogPromoAttributePort`, owned by `catalog`: the
+     * attribute metadata a rule criterion is validated and evaluated against.
+     *
+     * **Required** (issue #164). It used to be optional "so legacy tests /
+     * composition setups that don't wire this stay green", and production
+     * always passed it — an optional dependency nobody omits is a lie in the
+     * type: it tells every reader that absence is supported, and it makes the
+     * absent branch untested by construction. Both consequences were real.
+     * `validateCriteria` opened by returning early, so a composition without
+     * the port **accepted a promotion naming an attribute that does not
+     * exist**; and no test covered that, because the ten call sites that
+     * omitted the port were the ones that never exercised attributes.
+     *
+     * There is no degrade left to express. Absence is not a state the platform
+     * can be in: the container resolves this port for every composition, and
+     * `catalog` being switched off makes the call **throw**
+     * `ModuleDisabledError` at the resolution seam — which is the explicit
+     * answer, and it is the owner's to give. What remains is
+     * `getAttributeWithOptions` answering `null`, already explicit in its
+     * return type and meaning what it says: no such attribute.
+     */
+    catalogPort: PromotionRuleCatalogPort, 
+    /**
+     * Feature 075 Phase C — `catalogProductReadPort`, owned by `catalog`. It
+     * replaced an `em.find(Product, …)` this module wrote against `catalog`'s
+     * table to hydrate a cart line's attribute values, and it is required for
+     * the reason above: a composition that could not read products evaluated
+     * every attribute criterion against a line with no attribute values, which
+     * is not a degrade an operator would recognise as one.
+     */
+    productReadPort: CatalogProductReadPort, 
+    /**
+     * Feature 005 / T027b — the sanctioned bridge accessor for
+     * `sales_channel_promotions`: it auto-binds a newly-created Promotion to
+     * the system-default channel, and it answers which promotions a channel
+     * holds when a cart is evaluated.
+     *
+     * **Required** (issue #251), and of the four this is the one whose absent
+     * form was a Principle XII hole rather than a quiet one. Omitting it did
+     * two things at once: a new promotion bound to **no** channel, and
+     * `applyToCart` skipped channel filtering altogether — so a promotion an
+     * operator scoped to one channel applied in every one of them. Both roots
+     * passed the service, so nothing was live; every service built by
+     * `test/helpers/promotion-service.ts` was not, which is ten suites
+     * asserting against a promotion engine with no channel scope.
+     *
+     * There is no degrade to express in a return type. `sales_channels` is
+     * `nonDeactivatable` and `salesChannelMembershipPort` is a
+     * platform-owned container name besides, so absence is not a state a
+     * composition can reach.
+     */
+    salesChannelMembership: SalesChannelMembershipPort, 
+    /**
+     * Feature 037 — the dictionary reference validator, owned by
+     * `dictionaries`: it is what makes a promotion's `currency` a code the
+     * platform actually knows.
+     *
+     * **Required** (issue #251). `validateCurrency` opened with "no validator,
+     * no validation" and returned, so a composition without it stored a
+     * promotion denominated in a currency that does not exist — and the
+     * failure surfaced far downstream, at the cart, as a discount in a
+     * currency nothing could price. `dictionaries` is a declared dependency
+     * and is `nonDeactivatable`, so absence is not a state a composition can
+     * reach; an unknown or withdrawn code is already explicit, as the 409 this
+     * method raises.
+     */
+    dictionaryValidator: DictionaryValidator, 
+    /**
+     * Feature 026 US5 — the Organization status gate: an org-targeted
+     * promotion only applies while its Organization is `active`.
+     *
+     * **Required** (issue #251), and the one `backend.ts` already named in its
+     * own comment as *"a gate whose absent form is open"*. Omitted, the check
+     * was skipped entirely, so a `blocked` (formerly `suspended`) or
+     * `pending_verification` customer kept collecting its negotiated
+     * discounts — the exact thing US5 exists to stop.
+     *
+     * The degrade that **is** real stays in the return type, the way
+     * `allowedIdsFor(): Promise<string[] | null>` does: `null` means the
+     * Organization could not be read (missing or soft-deleted), and a status
+     * that is not `active` — `null` included — skips the org-targeted
+     * promotion. That is a closed answer, and it is the only absence this
+     * argument has.
+     */
+    resolveOrganizationStatus: (orgId: string) => Promise<string | null>, 
+    /**
+     * Feature 054 — co-transactional audit sink (`audit_log_entries`),
+     * Principle XIII.
+     *
+     * **Required** (issue #251). Without it every promotion create, update and
+     * delete committed with no audit row, which is not a degrade — it is the
+     * write happening unrecorded. `auditLogService` is a platform-owned
+     * container name that every composition supplies, so there was never a
+     * composition the absent branch described.
+     */
+    auditLog: AuditPort, 
+    /** Feature 012 / US8 — audit sink for FR-039 skip-on-toggle events. */
+    auditLogger?: PromotionAuditLogger, 
+    /** Feature 045 — pluggable action catalogue. Defaults to the built-ins. */
+    actionRegistry?: PromotionActionRegistry);
+    private readonly usageService;
+    /**
+     * Feature 045 (US5) — finalize usage for a placed order. MUST run inside the
+     * order-placement transaction (the passed `em` is that tx). Throws 409 if a
+     * usage cap is hit at the last moment so the transaction rolls back.
+     */
+    finalizeUsage(em: EntityManager, input: {
+        orderId: string;
+        currency: string;
+        ctx: UsageContext;
+        applied: FinalizeAppliedPromotion[];
+    }): Promise<void>;
+    /** Expose the action catalogue for the admin `action-types` endpoint. */
+    listActionTypes(): Array<{
+        type: string;
+        labelKey: string;
+    }>;
+    list(): Promise<Promotion[]>;
+    getById(id: string): Promise<Promotion>;
+    upsert(input: UpsertPromotionInput): Promise<Promotion>;
+    /** Feature 045 — update an existing promotion by id (admin edit path). */
+    updateById(id: string, input: UpsertPromotionInput): Promise<Promotion>;
+    private validateUpsertInput;
+    remove(id: string): Promise<void>;
+    private validateCurrency;
+    applyToCart(snapshot: CartSnapshot): Promise<PromotionApplication>;
+    /**
+     * Feature 012 / US8 — validate a criteria array against the catalog
+     * port. Throws `HttpError(400, ...)` for the documented error codes
+     * (`attribute_not_found`, `attribute_not_promo_eligible`,
+     * `invalid_criterion_op`, `invalid_criterion_values`,
+     * `invalid_option_value`).
+     */
+    private validateCriteria;
+    private buildAttributeLookup;
+    private hydrateLineAttributeValues;
+    private computeLineBase;
+}
+export interface UpsertPromotionInput {
+    code?: string | null;
+    name: string;
+    kind?: 'percentage_off' | 'amount_off' | 'free_delivery';
+    value?: number;
+    currency?: string | null;
+    minCartSubtotal?: number | null;
+    validFrom?: string | null;
+    validUntil?: string | null;
+    organizationId?: string | null;
+    customerGroupId?: string | null;
+    categoryId?: string | null;
+    productId?: string | null;
+    criteria?: PromotionCriterion[];
+    isActive?: boolean;
+    description?: string | null;
+    priority?: number;
+    stopFurther?: boolean;
+    action?: PromotionAction;
+    ruleId?: string | null;
+    rule?: PromotionRule | null;
+    usageLimitGlobal?: number | null;
+    usageLimitPerOrganization?: number | null;
+    usageLimitPerCustomer?: number | null;
+}
+//# sourceMappingURL=promotion-service.d.ts.map

package/dist/backend/services/promotion-service.d.ts.map

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