Free Gift Module

Authorization: Bearer <session-token>

{
  "data": <payload>,
  "message": "Success",
  "statusCode": 200,
  "metadata": { /* optional, e.g. pagination */ }
}

{
  "data": null,
  "message": "Human-readable summary",
  "statusCode": 400,
  "errorCode": "BAD_REQUEST",
  "errors": [ /* zod issues, when validation fails */ ],
  "debug": { /* dev-only: error + stack */ }
}

type Platform = "APP" | "WEB" | "BOTH";
type FreeGiftRuleType = "AUTOMATIC" | "BUYXGETY" | "COUPON_BASED";
type FreeGiftBuyScope = "VARIANT" | "BRAND" | "CATEGORY" | "TAG" | "INGREDIENT" | "VENDOR";
type FreeGiftProductMode = "SAME" | "DIFFERENT";
type FreeGiftCriteriaScope =
  | "CART_SUBTOTAL"
  | "ORDER_TOTAL"
  | "CATEGORY_TOTAL"
  | "BRAND_TOTAL"
  | "TAG_TOTAL"
  | "INGREDIENT_TOTAL"
  | "VENDOR_TOTAL";
type CustomerScope = "ALL" | "ONLY_LISTED" | "EXCEPT_LISTED";
type PurchaseHistoryMode = "DISABLED" | "ZERO_ORDERS" | "MIN_ORDERS";
type FreeGiftFilterMode = "INCLUDE" | "EXCLUDE";

type FreeGiftFilterEntry = {
  id: string;            // UUID of the referenced entity
  mode: FreeGiftFilterMode;
};

type AutomaticConfig = {
  quantity: number;       // free units of EACH listed variant
  variantIds: string[];   // ≥ 1 variants to gift on every applicable order
};

type BuyXGetYConfig = {
  buyScope: FreeGiftBuyScope;
  buyScopeIds: string[];          // ≥ 1; entity IDs of `buyScope` kind
  buyQuantity: number;            // ≥ 1 — units the customer must purchase per group
  getQuantity: number;            // ≥ 1 — free units per group
  giftProductMode: FreeGiftProductMode;
  giftVariantIds: string[];       // ≥ 1 when giftProductMode = DIFFERENT; empty when SAME
  repeatGift: boolean;            // false → at most one group regardless of basket size
  repeatLimit: number | null;     // null when repeatGift=true ⇒ unlimited groups
};

type CouponConfig = {
  couponCode: string;     // /^[A-Z0-9_-]+$/, length 2..50
  couponQuantity: number; // ≥ 1
  variantIds: string[];   // ≥ 1 variants gifted, each at couponQuantity
};

type FreeGiftResponse = {
  id: string;
  name: string;
  description: string | null;
  isActive: boolean;
  archivedAt: string | null;                       // ISO

  platform: Platform;
  type: FreeGiftRuleType;

  automaticConfig: AutomaticConfig | null;
  buyXGetYConfig: BuyXGetYConfig | null;
  couponConfig: CouponConfig | null;

  criteriaScope: FreeGiftCriteriaScope;
  criteriaScopeIds: string[];                      // empty for CART_SUBTOTAL / ORDER_TOTAL
  minAmount: number | null;                        // rupees
  maxAmount: number | null;                        // rupees
  minQuantity: number | null;
  maxQuantity: number | null;
  minProductCount: number | null;
  maxProductCount: number | null;

  startsAt: string | null;                         // ISO
  endsAt: string | null;                           // ISO
  totalUsageLimit: number | null;
  usageLimitPerCustomer: number | null;
  requireCustomerLogin: boolean;
  purchaseHistoryMode: PurchaseHistoryMode;
  minOrderCount: number | null;
  individualUsageOnly: boolean;

  customerScope: CustomerScope;
  customerUserIds: string[];                       // populated only when scope != ALL

  variants: FreeGiftFilterEntry[];
  categories: FreeGiftFilterEntry[];
  brands: FreeGiftFilterEntry[];
  tags: FreeGiftFilterEntry[];
  ingredients: FreeGiftFilterEntry[];
  vendors: FreeGiftFilterEntry[];

  showOnCart: boolean;

  createdAt: string;                               // ISO
  updatedAt: string;                               // ISO
  deletedAt: string | null;                        // ISO
};

{
  "data": [
    {
      "id": "01J9...",
      "name": "Buy 2 chocolates, get 1 free",
      "description": null,
      "isActive": true,
      "archivedAt": null,
      "platform": "BOTH",
      "type": "BUYXGETY",
      // ...all parent columns
      "createdAt": "2026-04-30T10:00:00.000Z",
      "updatedAt": "2026-04-30T10:00:00.000Z",
      "deletedAt": null
    }
  ],
  "message": "Success",
  "statusCode": 200,
  "metadata": { "total": 8, "limit": 100, "offset": 0, "hasMore": false }
}

{
  "name": "Buy 2 Choco, get 1 free",
  "description": "Festive season promo",          // optional
  "isActive": true,                                // default true
  "platform": "BOTH",                              // default "BOTH"

  "type": "BUYXGETY",                              // AUTOMATIC | BUYXGETY | COUPON_BASED

  // Type-specific configs (exactly one populated, per `type`):
  "automaticConfig":  null | { /* see AutomaticConfig */ },
  "buyXGetYConfig":   null | { /* see BuyXGetYConfig  */ },
  "couponConfig":     null | { /* see CouponConfig    */ },

  // Criteria
  "criteriaScope": "CART_SUBTOTAL",
  "criteriaScopeIds": [],                          // required for per-entity totals
  "minAmount": 1000,                               // rupees, nullable
  "maxAmount": null,                               // rupees, nullable
  "minQuantity": null,
  "maxQuantity": null,
  "minProductCount": null,
  "maxProductCount": null,

  // Restrictions
  "startsAt": "2026-04-30T00:00:00.000Z",          // ISO; nullable
  "endsAt": "2026-12-31T23:59:59.000Z",            // ISO; nullable
  "totalUsageLimit": 1000,                         // nullable
  "usageLimitPerCustomer": 1,                      // nullable
  "requireCustomerLogin": false,
  "purchaseHistoryMode": "DISABLED",               // DISABLED | ZERO_ORDERS | MIN_ORDERS
  "minOrderCount": null,                           // required when MIN_ORDERS
  "individualUsageOnly": false,

  // Customer scope
  "customerScope": "ALL",
  "customerUserIds": [],                           // required when scope != ALL

  // Rule-wide INCLUDE/EXCLUDE filters (variant-level for the variants array)
  "variants":    [{ "id": "01J9...", "mode": "INCLUDE" }],
  "categories":  [{ "id": "01J9...", "mode": "EXCLUDE" }],
  "brands":      [{ "id": "01J9...", "mode": "INCLUDE" }],
  "tags":        [{ "id": "01J9...", "mode": "INCLUDE" }],
  "ingredients": [{ "id": "01J9...", "mode": "EXCLUDE" }],
  "vendors":     [{ "id": "01J9...", "mode": "INCLUDE" }],

  "showOnCart": false
}

{
  "type": "AUTOMATIC",
  "automaticConfig": {
    "quantity": 1,
    "variantIds": ["01J9...sample"]
  },
  "buyXGetYConfig": null,
  "couponConfig": null
}

{
  "type": "BUYXGETY",
  "automaticConfig": null,
  "buyXGetYConfig": {
    "buyScope": "BRAND",
    "buyScopeIds": ["01J9...brandA"],
    "buyQuantity": 2,
    "getQuantity": 1,
    "giftProductMode": "SAME",
    "giftVariantIds": [],
    "repeatGift": true,
    "repeatLimit": 3
  },
  "couponConfig": null
}

{
  "type": "COUPON_BASED",
  "automaticConfig": null,
  "buyXGetYConfig": null,
  "couponConfig": {
    "couponCode": "SUMMER25",
    "couponQuantity": 1,
    "variantIds": ["01J9...A", "01J9...B"]
  }
}

import { FREE_GIFT_PORT, type FreeGiftPort } from "@sc/free-gift";

@Inject(FREE_GIFT_PORT) private readonly freeGiftPort: FreeGiftPort

type FreeGiftEvaluationContext = {
  userId: string | null;
  cartSubtotal: number;        // rupees
  cartItems: Array<{
    productId: string; variantId: string; quantity: number;
    unitPrice: number; specialPrice: number | null;
    categoryIds: string[]; brandId: string | null;
    tagIds: string[]; ingredientIds: string[]; vendorId: string;
  }>;
  platform: "APP" | "WEB";
  appliedCouponCodes: string[];
};

type FreeGiftEvaluationItem = {
  ruleId: string;
  productId: string;
  variantId: string;
  quantity: number;
  reason: string;              // "AUTOMATIC" | "BUYXGETY" | "COUPON_BASED:<code>"
};

type FreeGiftEvaluationResult = {
  rulesFired: string[];
  items: FreeGiftEvaluationItem[];
};