@endora-commerce/contracts 0.100.0

package/dist/promotions.d.ts

@@ -0,0 +1,678 @@
+import { z } from 'zod';
+/**
+ * Promotion contracts (T129, T132 / FR-052).
+ *
+ * Three kinds shipped in this slice:
+ *   - `percentage_off` — `value` is 0..100
+ *   - `amount_off`     — `value` is money in `currency`
+ *   - `free_delivery`  — `value` is ignored; the cart's delivery cost is zeroed
+ *
+ * Eligibility rules:
+ *   - `code` (optional) — when present, only carts that present the code apply;
+ *                          when null, the promotion applies automatically to
+ *                          every eligible cart.
+ *   - `minCartSubtotal`  — cart subtotal threshold (in promotion currency).
+ *   - `validFrom` / `validUntil` — clock-bound validity window.
+ *   - `organizationId` / `customerGroupId` — restrict to a single Customer / group.
+ *   - `categoryId` / `productId` — restrict effect to lines in the chosen scope.
+ *   - `criteria[]` (feature 012 / US8) — line-level discriminated criteria.
+ *     Today only the `attribute` variant is meaningful; the union is shaped
+ *     so the existing flat `categoryId`/`productId`/etc. fields can migrate
+ *     into it incrementally without breaking the wire format.
+ */
+/**
+ * Attribute-key syntax: lowercase, must start with a letter, then letters,
+ * digits, or underscore. Mirrors the attribute-key regex on the catalog
+ * create-attribute schema so the picker and the schema reject the same
+ * invalid keys.
+ */
+export declare const attributeKeyRegex: RegExp;
+declare const attributeCriterionSchema: z.ZodObject<{
+    type: z.ZodLiteral<"attribute">;
+    attributeKey: z.ZodString;
+    op: z.ZodEnum<{
+        in: "in";
+        equals: "equals";
+        range: "range";
+    }>;
+    values: z.ZodArray<z.ZodUnknown>;
+}, z.core.$strip>;
+export declare const promotionCriterionSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"attribute">;
+    attributeKey: z.ZodString;
+    op: z.ZodEnum<{
+        in: "in";
+        equals: "equals";
+        range: "range";
+    }>;
+    values: z.ZodArray<z.ZodUnknown>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"category">;
+    categoryIds: z.ZodArray<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"product">;
+    productIds: z.ZodArray<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"customerGroup">;
+    customerGroupIds: z.ZodArray<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"organization">;
+    organizationIds: z.ZodArray<z.ZodString>;
+}, z.core.$strip>], "type">;
+export type PromotionCriterion = z.infer<typeof promotionCriterionSchema>;
+export type AttributePromotionCriterion = z.infer<typeof attributeCriterionSchema>;
+/**
+ * Operator vocabulary for a promotion rule condition. The admissible set
+ * per field/value-type is enforced by the evaluator + write-time validation;
+ * the schema accepts the full vocabulary structurally.
+ */
+export declare const promotionRuleOpSchema: z.ZodEnum<{
+    in: "in";
+    startsWith: "startsWith";
+    eq: "eq";
+    gt: "gt";
+    gte: "gte";
+    lt: "lt";
+    lte: "lte";
+    contains: "contains";
+    neq: "neq";
+    between: "between";
+    notIn: "notIn";
+}>;
+export type PromotionRuleOp = z.infer<typeof promotionRuleOpSchema>;
+/** Built-in cart-context / relationship fields available to the Rule Builder. */
+export declare const promotionRuleBuiltinFieldSchema: z.ZodEnum<{
+    paymentMethod: "paymentMethod";
+    category: "category";
+    organization: "organization";
+    deliveryMethod: "deliveryMethod";
+    customerGroup: "customerGroup";
+    cartTotal: "cartTotal";
+    deliveryCountry: "deliveryCountry";
+    deliveryPostalCode: "deliveryPostalCode";
+}>;
+export type PromotionRuleBuiltinField = z.infer<typeof promotionRuleBuiltinFieldSchema>;
+/** A rule field is either a built-in key or a promo-eligible product attribute. */
+export declare const promotionRuleFieldSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"builtin">;
+    key: z.ZodEnum<{
+        paymentMethod: "paymentMethod";
+        category: "category";
+        organization: "organization";
+        deliveryMethod: "deliveryMethod";
+        customerGroup: "customerGroup";
+        cartTotal: "cartTotal";
+        deliveryCountry: "deliveryCountry";
+        deliveryPostalCode: "deliveryPostalCode";
+    }>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"attribute">;
+    attributeKey: z.ZodString;
+}, z.core.$strip>], "kind">;
+export type PromotionRuleField = z.infer<typeof promotionRuleFieldSchema>;
+export declare const promotionRuleValueSchema: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>;
+export type PromotionRuleValue = z.infer<typeof promotionRuleValueSchema>;
+export type PromotionRuleAll = {
+    kind: 'all';
+};
+export type PromotionRuleCondition = {
+    kind: 'condition';
+    field: PromotionRuleField;
+    op: PromotionRuleOp;
+    values: PromotionRuleValue[];
+};
+export type PromotionRuleGroup = {
+    kind: 'group';
+    op: 'AND' | 'OR';
+    children: PromotionRule[];
+};
+export type PromotionRule = PromotionRuleAll | PromotionRuleCondition | PromotionRuleGroup;
+/** Maximum nesting depth of a rule tree (mirrors the price-list guard). */
+export declare function promotionRuleDepth(node: PromotionRule): number;
+export declare const promotionRuleSchema: z.ZodType<PromotionRule, unknown, z.core.$ZodTypeInternals<PromotionRule, unknown>>;
+export declare const promotionGiftTargetSchema: z.ZodEnum<{
+    cheapest: "cheapest";
+    most_expensive: "most_expensive";
+}>;
+export type PromotionGiftTarget = z.infer<typeof promotionGiftTargetSchema>;
+export declare const promotionActionSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"free_delivery">;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"percentage_off_cart">;
+    percent: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"amount_off_cart">;
+    amount: z.ZodNumber;
+    currency: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"buy_x_get_y_free">;
+    buyQuantity: z.ZodNumber;
+    freeQuantity: z.ZodNumber;
+    target: z.ZodEnum<{
+        cheapest: "cheapest";
+        most_expensive: "most_expensive";
+    }>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"spend_x_percent_off">;
+    spendStep: z.ZodNumber;
+    percent: z.ZodNumber;
+    currency: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"spend_x_amount_off">;
+    spendStep: z.ZodNumber;
+    amount: z.ZodNumber;
+    currency: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"every_nth_product_percent_off">;
+    nth: z.ZodNumber;
+    percent: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"buy_x_units_y_free">;
+    productId: z.ZodString;
+    buyUnits: z.ZodNumber;
+    freeUnits: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"buy_x_units_percent_off">;
+    productId: z.ZodString;
+    buyUnits: z.ZodNumber;
+    percent: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"buy_x_units_amount_off">;
+    productId: z.ZodString;
+    buyUnits: z.ZodNumber;
+    amount: z.ZodNumber;
+    currency: z.ZodString;
+}, z.core.$strip>], "type">;
+export type PromotionAction = z.infer<typeof promotionActionSchema>;
+export declare const promotionActionTypeSchema: z.ZodEnum<{
+    free_delivery: "free_delivery";
+    percentage_off_cart: "percentage_off_cart";
+    amount_off_cart: "amount_off_cart";
+    buy_x_get_y_free: "buy_x_get_y_free";
+    spend_x_percent_off: "spend_x_percent_off";
+    spend_x_amount_off: "spend_x_amount_off";
+    every_nth_product_percent_off: "every_nth_product_percent_off";
+    buy_x_units_y_free: "buy_x_units_y_free";
+    buy_x_units_percent_off: "buy_x_units_percent_off";
+    buy_x_units_amount_off: "buy_x_units_amount_off";
+}>;
+export type PromotionActionType = z.infer<typeof promotionActionTypeSchema>;
+export declare const promotionKindSchema: z.ZodEnum<{
+    free_delivery: "free_delivery";
+    percentage_off: "percentage_off";
+    amount_off: "amount_off";
+}>;
+export type PromotionKind = z.infer<typeof promotionKindSchema>;
+export declare const promotionSchema: z.ZodObject<{
+    id: z.ZodString;
+    code: z.ZodNullable<z.ZodString>;
+    name: z.ZodString;
+    kind: z.ZodNullable<z.ZodEnum<{
+        free_delivery: "free_delivery";
+        percentage_off: "percentage_off";
+        amount_off: "amount_off";
+    }>>;
+    value: z.ZodNullable<z.ZodNumber>;
+    currency: z.ZodNullable<z.ZodString>;
+    minCartSubtotal: z.ZodNullable<z.ZodNumber>;
+    validFrom: z.ZodNullable<z.ZodString>;
+    validUntil: z.ZodNullable<z.ZodString>;
+    organizationId: z.ZodNullable<z.ZodString>;
+    customerGroupId: z.ZodNullable<z.ZodString>;
+    categoryId: z.ZodNullable<z.ZodString>;
+    productId: z.ZodNullable<z.ZodString>;
+    criteria: z.ZodDefault<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"attribute">;
+        attributeKey: z.ZodString;
+        op: z.ZodEnum<{
+            in: "in";
+            equals: "equals";
+            range: "range";
+        }>;
+        values: z.ZodArray<z.ZodUnknown>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"category">;
+        categoryIds: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"product">;
+        productIds: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"customerGroup">;
+        customerGroupIds: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"organization">;
+        organizationIds: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>], "type">>>;
+    isActive: z.ZodBoolean;
+    description: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    priority: z.ZodDefault<z.ZodNumber>;
+    stopFurther: z.ZodDefault<z.ZodBoolean>;
+    action: z.ZodDefault<z.ZodNullable<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"free_delivery">;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"percentage_off_cart">;
+        percent: z.ZodNumber;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"amount_off_cart">;
+        amount: z.ZodNumber;
+        currency: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"buy_x_get_y_free">;
+        buyQuantity: z.ZodNumber;
+        freeQuantity: z.ZodNumber;
+        target: z.ZodEnum<{
+            cheapest: "cheapest";
+            most_expensive: "most_expensive";
+        }>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"spend_x_percent_off">;
+        spendStep: z.ZodNumber;
+        percent: z.ZodNumber;
+        currency: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"spend_x_amount_off">;
+        spendStep: z.ZodNumber;
+        amount: z.ZodNumber;
+        currency: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"every_nth_product_percent_off">;
+        nth: z.ZodNumber;
+        percent: z.ZodNumber;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"buy_x_units_y_free">;
+        productId: z.ZodString;
+        buyUnits: z.ZodNumber;
+        freeUnits: z.ZodNumber;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"buy_x_units_percent_off">;
+        productId: z.ZodString;
+        buyUnits: z.ZodNumber;
+        percent: z.ZodNumber;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"buy_x_units_amount_off">;
+        productId: z.ZodString;
+        buyUnits: z.ZodNumber;
+        amount: z.ZodNumber;
+        currency: z.ZodString;
+    }, z.core.$strip>], "type">>>;
+    ruleId: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    rule: z.ZodDefault<z.ZodNullable<z.ZodType<PromotionRule, unknown, z.core.$ZodTypeInternals<PromotionRule, unknown>>>>;
+    usageLimitGlobal: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
+    usageLimitPerOrganization: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
+    usageLimitPerCustomer: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
+    createdAt: z.ZodString;
+    updatedAt: z.ZodString;
+}, z.core.$strip>;
+export type Promotion = z.infer<typeof promotionSchema>;
+export declare const upsertPromotionRequestSchema: z.ZodObject<{
+    code: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    name: z.ZodString;
+    kind: z.ZodOptional<z.ZodEnum<{
+        free_delivery: "free_delivery";
+        percentage_off: "percentage_off";
+        amount_off: "amount_off";
+    }>>;
+    value: z.ZodOptional<z.ZodNumber>;
+    currency: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    minCartSubtotal: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    validFrom: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    validUntil: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    organizationId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    customerGroupId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    categoryId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    productId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    criteria: z.ZodOptional<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"attribute">;
+        attributeKey: z.ZodString;
+        op: z.ZodEnum<{
+            in: "in";
+            equals: "equals";
+            range: "range";
+        }>;
+        values: z.ZodArray<z.ZodUnknown>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"category">;
+        categoryIds: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"product">;
+        productIds: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"customerGroup">;
+        customerGroupIds: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"organization">;
+        organizationIds: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>], "type">>>;
+    isActive: z.ZodOptional<z.ZodBoolean>;
+    description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    priority: z.ZodOptional<z.ZodNumber>;
+    stopFurther: z.ZodOptional<z.ZodBoolean>;
+    action: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"free_delivery">;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"percentage_off_cart">;
+        percent: z.ZodNumber;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"amount_off_cart">;
+        amount: z.ZodNumber;
+        currency: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"buy_x_get_y_free">;
+        buyQuantity: z.ZodNumber;
+        freeQuantity: z.ZodNumber;
+        target: z.ZodEnum<{
+            cheapest: "cheapest";
+            most_expensive: "most_expensive";
+        }>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"spend_x_percent_off">;
+        spendStep: z.ZodNumber;
+        percent: z.ZodNumber;
+        currency: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"spend_x_amount_off">;
+        spendStep: z.ZodNumber;
+        amount: z.ZodNumber;
+        currency: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"every_nth_product_percent_off">;
+        nth: z.ZodNumber;
+        percent: z.ZodNumber;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"buy_x_units_y_free">;
+        productId: z.ZodString;
+        buyUnits: z.ZodNumber;
+        freeUnits: z.ZodNumber;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"buy_x_units_percent_off">;
+        productId: z.ZodString;
+        buyUnits: z.ZodNumber;
+        percent: z.ZodNumber;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"buy_x_units_amount_off">;
+        productId: z.ZodString;
+        buyUnits: z.ZodNumber;
+        amount: z.ZodNumber;
+        currency: z.ZodString;
+    }, z.core.$strip>], "type">>;
+    ruleId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    rule: z.ZodOptional<z.ZodNullable<z.ZodType<PromotionRule, unknown, z.core.$ZodTypeInternals<PromotionRule, unknown>>>>;
+    usageLimitGlobal: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    usageLimitPerOrganization: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    usageLimitPerCustomer: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    salesChannelIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export declare const promotionStatsGroupBySchema: z.ZodEnum<{
+    customer: "customer";
+    organization: "organization";
+    salesChannel: "salesChannel";
+    customerGroup: "customerGroup";
+}>;
+export type PromotionStatsGroupBy = z.infer<typeof promotionStatsGroupBySchema>;
+export declare const promotionUsageStatsSchema: z.ZodObject<{
+    totalUses: z.ZodNumber;
+    totalDiscount: z.ZodNumber;
+    currency: z.ZodNullable<z.ZodString>;
+    groupBy: z.ZodNullable<z.ZodEnum<{
+        customer: "customer";
+        organization: "organization";
+        salesChannel: "salesChannel";
+        customerGroup: "customerGroup";
+    }>>;
+    breakdown: z.ZodArray<z.ZodObject<{
+        key: z.ZodNullable<z.ZodString>;
+        uses: z.ZodNumber;
+        discount: z.ZodNumber;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type PromotionUsageStats = z.infer<typeof promotionUsageStatsSchema>;
+export declare const promotionRuleRecordSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    description: z.ZodNullable<z.ZodString>;
+    definition: z.ZodType<PromotionRule, unknown, z.core.$ZodTypeInternals<PromotionRule, unknown>>;
+    createdAt: z.ZodString;
+    updatedAt: z.ZodString;
+}, z.core.$strip>;
+export type PromotionRuleRecord = z.infer<typeof promotionRuleRecordSchema>;
+export declare const upsertPromotionRuleRequestSchema: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    definition: z.ZodType<PromotionRule, unknown, z.core.$ZodTypeInternals<PromotionRule, unknown>>;
+}, z.core.$strip>;
+export type UpsertPromotionRuleRequest = z.infer<typeof upsertPromotionRuleRequestSchema>;
+export declare const couponFormatSchema: z.ZodEnum<{
+    alnum: "alnum";
+    digits: "digits";
+    letters: "letters";
+}>;
+export type CouponFormat = z.infer<typeof couponFormatSchema>;
+export declare const couponLimitScopeSchema: z.ZodEnum<{
+    per_coupon: "per_coupon";
+    shared_batch: "shared_batch";
+}>;
+export type CouponLimitScope = z.infer<typeof couponLimitScopeSchema>;
+export declare const promotionCouponSchema: z.ZodObject<{
+    id: z.ZodString;
+    promotionId: z.ZodString;
+    batchId: z.ZodNullable<z.ZodString>;
+    code: z.ZodString;
+    limitScope: z.ZodEnum<{
+        per_coupon: "per_coupon";
+        shared_batch: "shared_batch";
+    }>;
+    isActive: z.ZodBoolean;
+    createdAt: z.ZodString;
+}, z.core.$strip>;
+export type PromotionCouponDto = z.infer<typeof promotionCouponSchema>;
+export declare const generateCouponsRequestSchema: z.ZodObject<{
+    count: z.ZodNumber;
+    length: z.ZodNumber;
+    format: z.ZodEnum<{
+        alnum: "alnum";
+        digits: "digits";
+        letters: "letters";
+    }>;
+    prefix: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    suffix: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    dashEvery: z.ZodOptional<z.ZodNumber>;
+    limitScope: z.ZodDefault<z.ZodEnum<{
+        per_coupon: "per_coupon";
+        shared_batch: "shared_batch";
+    }>>;
+}, z.core.$strip>;
+export type GenerateCouponsRequest = z.infer<typeof generateCouponsRequestSchema>;
+/** Bulk activate/deactivate coupons of a promotion by id. */
+export declare const bulkCouponActiveRequestSchema: z.ZodObject<{
+    couponIds: z.ZodArray<z.ZodString>;
+    isActive: z.ZodBoolean;
+}, z.core.$strip>;
+export type BulkCouponActiveRequest = z.infer<typeof bulkCouponActiveRequestSchema>;
+export declare const cartLineSchema: z.ZodObject<{
+    productId: z.ZodString;
+    variantId: z.ZodNullable<z.ZodString>;
+    categoryIds: z.ZodArray<z.ZodString>;
+    quantity: z.ZodNumber;
+    unitPrice: z.ZodObject<{
+        amount: z.ZodNumber;
+        currency: z.ZodString;
+    }, z.core.$strip>;
+    attributeValues: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+export type CartLine = z.infer<typeof cartLineSchema>;
+export declare const cartSnapshotSchema: z.ZodObject<{
+    organizationId: z.ZodNullable<z.ZodString>;
+    customerGroupId: z.ZodNullable<z.ZodString>;
+    currency: z.ZodString;
+    lines: z.ZodArray<z.ZodObject<{
+        productId: z.ZodString;
+        variantId: z.ZodNullable<z.ZodString>;
+        categoryIds: z.ZodArray<z.ZodString>;
+        quantity: z.ZodNumber;
+        unitPrice: z.ZodObject<{
+            amount: z.ZodNumber;
+            currency: z.ZodString;
+        }, z.core.$strip>;
+        attributeValues: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>>;
+    deliveryTotal: z.ZodNumber;
+    promotionCode: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    salesChannelId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    customerAccountId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    paymentMethodCode: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    deliveryMethodCode: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    deliveryCountry: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    deliveryPostalCode: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+export type CartSnapshot = z.infer<typeof cartSnapshotSchema>;
+export declare const promotionApplicationSchema: z.ZodObject<{
+    subtotal: z.ZodNumber;
+    discountTotal: z.ZodNumber;
+    deliveryTotal: z.ZodNumber;
+    total: z.ZodNumber;
+    appliedPromotions: z.ZodArray<z.ZodObject<{
+        promotionId: z.ZodString;
+        kind: z.ZodNullable<z.ZodEnum<{
+            free_delivery: "free_delivery";
+            percentage_off: "percentage_off";
+            amount_off: "amount_off";
+        }>>;
+        actionType: z.ZodDefault<z.ZodNullable<z.ZodEnum<{
+            free_delivery: "free_delivery";
+            percentage_off_cart: "percentage_off_cart";
+            amount_off_cart: "amount_off_cart";
+            buy_x_get_y_free: "buy_x_get_y_free";
+            spend_x_percent_off: "spend_x_percent_off";
+            spend_x_amount_off: "spend_x_amount_off";
+            every_nth_product_percent_off: "every_nth_product_percent_off";
+            buy_x_units_y_free: "buy_x_units_y_free";
+            buy_x_units_percent_off: "buy_x_units_percent_off";
+            buy_x_units_amount_off: "buy_x_units_amount_off";
+        }>>>;
+        couponId: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        amount: z.ZodNumber;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type PromotionApplication = z.infer<typeof promotionApplicationSchema>;
+/**
+ * Picker payload returned by `GET /api/v1/admin/promotions/rule-targets/attributes`.
+ * Lists every attribute carrying `isPromoRule = true`, with the option list
+ * inline for select-style types so the editor can render the value picker
+ * without an additional round-trip.
+ */
+export declare const promotionRuleAttributeOptionSchema: z.ZodObject<{
+    value: z.ZodString;
+    label: z.ZodRecord<z.ZodString, z.ZodString>;
+    labelDefault: z.ZodString;
+}, z.core.$strip>;
+export type PromotionRuleAttributeOption = z.infer<typeof promotionRuleAttributeOptionSchema>;
+export declare const promotionRuleAttributeSchema: z.ZodObject<{
+    id: z.ZodString;
+    key: z.ZodString;
+    label: z.ZodRecord<z.ZodString, z.ZodString>;
+    labelDefault: z.ZodString;
+    valueType: z.ZodEnum<{
+        string: "string";
+        number: "number";
+        boolean: "boolean";
+        date: "date";
+        enum: "enum";
+        select: "select";
+        price: "price";
+        multiselect: "multiselect";
+    }>;
+    options: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        value: z.ZodString;
+        label: z.ZodRecord<z.ZodString, z.ZodString>;
+        labelDefault: z.ZodString;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type PromotionRuleAttribute = z.infer<typeof promotionRuleAttributeSchema>;
+export declare const promotionRuleAttributesResponseSchema: z.ZodObject<{
+    data: z.ZodObject<{
+        items: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            key: z.ZodString;
+            label: z.ZodRecord<z.ZodString, z.ZodString>;
+            labelDefault: z.ZodString;
+            valueType: z.ZodEnum<{
+                string: "string";
+                number: "number";
+                boolean: "boolean";
+                date: "date";
+                enum: "enum";
+                select: "select";
+                price: "price";
+                multiselect: "multiselect";
+            }>;
+            options: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                value: z.ZodString;
+                label: z.ZodRecord<z.ZodString, z.ZodString>;
+                labelDefault: z.ZodString;
+            }, z.core.$strip>>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type PromotionRuleAttributesResponse = z.infer<typeof promotionRuleAttributesResponseSchema>;
+/**
+ * What a presented coupon code resolved to.
+ *
+ * Deliberately **not** the `Promotion` row. `carts` reaches both entities for
+ * one question in two parts — "is this code live, and if the buyer cannot use
+ * it, *why* not?" — across a three-step lookup: the legacy `promotions.code`
+ * column first, then the `promotion_coupons` table, then the promotion behind
+ * the coupon, each filtered on `isActive`. Publishing the row would publish
+ * thirty columns to answer a question about eight.
+ *
+ * The four eligibility fields were missing when this shape was first published
+ * and were added in `carts`' cut. Its coupon service does not merely accept or
+ * reject a code: it answers `expired`, `wrong_organization` or
+ * `below_min_spend`, and the storefront renders that sentence. Without them the
+ * cut would have collapsed three explanations into `invalid_code`, which is a
+ * product change wearing a refactor.
+ */
+export interface ResolvedPromotionCode {
+    promotionId: string;
+    /** The coupon row the code came from, or `null` for a legacy inline code. */
+    couponId: string | null;
+    name: string;
+    isActive: boolean;
+    /** Window bounds; `null` means unbounded on that side. */
+    validFrom: Date | null;
+    validUntil: Date | null;
+    /** When set, only carts of that organisation may use the code. */
+    organizationId: string | null;
+    /** Decimal string, or `null` for no minimum. Compared against the subtotal. */
+    minCartSubtotal: string | null;
+}
+/**
+ * Container name: `promotionCodePort`. Owner: `promotions`.
+ *
+ * When `promotions` is off the lookup fails closed, and that is right: a cart
+ * that cannot resolve a coupon must refuse it rather than silently accept the
+ * code and price the order without the discount, which is the failure a buyer
+ * only notices on the invoice.
+ */
+export interface PromotionCodePort {
+    /** `null` when no live promotion answers to the code. */
+    resolveByCode(code: string): Promise<ResolvedPromotionCode | null>;
+}
+/**
+ * Container name: `promotionService`. Owner: `promotions`.
+ *
+ * The evaluation seam: a cart snapshot in, the applicable discounts out.
+ * `carts` and `orders` both call it, and both already pass and receive
+ * contract-typed shapes — so this port names what they were importing the
+ * class to get.
+ *
+ * **Owner off:** the seam fails closed — resolving this port throws
+ * `ModuleDisabledError` and the call answers 503 `MODULE_DISABLED`, so nothing
+ * half-executes. Whether `promotions` has an off state at all is its manifest's
+ * `activation` to say, not this line's: a module declaring
+ * `nonDeactivatable` never enters one.
+ */
+export interface PromotionApplyPort {
+    applyToCart(snapshot: CartSnapshot): Promise<PromotionApplication>;
+}
+export {};
+//# sourceMappingURL=promotions.d.ts.map

package/dist/promotions.d.ts.map

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