@classytic/promo 0.1.0 → 0.2.0

package/dist/index.d.mts

@@ -1,20 +1,773 @@
-import { a as BalanceLedgerEntry, c as Rule, l as Reward, o as Voucher, s as VoucherRedemption, u as Program } from "./voucher.port-yxfb3MHJ.mjs";
-import { t as EventEmitterPort } from "./event-emitter.port-DaodlJSG.mjs";
-import { o as PromoEvents } from "./index-C52zSBkI.mjs";
-import { i as PromoConfig, o as ResolvedConfig, s as ResolvedTenant } from "./config-iZjn_8pp.mjs";
-import { t as PromoModels } from "./index-B7lLH19a.mjs";
-import { t as PromoRepositories } from "./index-l09KqnlE.mjs";
-import { C as UpdateRuleInput, S as UpdateRewardInput, _ as GiftCardTopUpInput, a as GiftCardBalance, b as RedeemVoucherInput, c as VoucherValidation, d as CreateRewardInput, f as CreateRuleInput, g as GiftCardSpendInput, h as GenerateSingleCodeInput, i as FreeProductLine, l as CartItem, m as GenerateCodesInput, n as DiscountLine, o as PaginatedResult, p as EvaluateInput, r as EvaluationResult, s as RejectedCode, t as CommitResult, u as CreateProgramInput, v as ListQuery, x as UpdateProgramInput, y as PromoContext } from "./results-Ca5ZCNbN.mjs";
-import { i as FullProgram, t as PromoServices } from "./index-Cu9iwy4v.mjs";
+import { c as ProgramType, f as StackingMode, g as VoucherStatus, i as DiscountScope, m as TriggerMode, r as DiscountMode, s as ProgramStatus, u as RewardType } from "./constants-CrbSSQG5.mjs";
+import { ResolvedTenantConfig, TenantConfig } from "@classytic/primitives/tenant";
+import { DomainEvent, DomainEvent as DomainEvent$1, EventHandler, EventTransport, EventTransport as EventTransport$1 } from "@classytic/primitives/events";
+import { ClientSession, Connection, Model } from "mongoose";
+import { PluginType, Repository } from "@classytic/mongokit";
+import { z } from "zod";
+import { OutboxStore } from "@classytic/primitives/outbox";
+import { OperationContext } from "@classytic/primitives/context";
 
+//#region src/types/config.d.ts
+type TenantConfig$1 = false | TenantConfig;
+interface IndexDefinition {
+  fields: Record<string, 1 | -1>;
+  options?: Record<string, unknown> | undefined;
+}
+type ModelName = 'program' | 'rule' | 'reward' | 'voucher';
+interface RepositoryPlugins {
+  program?: PluginType[] | undefined;
+  rule?: PluginType[] | undefined;
+  reward?: PluginType[] | undefined;
+  voucher?: PluginType[] | undefined;
+}
+interface PromoConfig {
+  mongoose: Connection;
+  tenant?: TenantConfig$1 | undefined;
+  evaluation?: {
+    maxStackablePromotions?: number | undefined;
+    allowExclusiveAndStackable?: boolean | undefined;
+  } | undefined;
+  voucher?: {
+    codeLength?: number | undefined;
+    codePrefix?: string | undefined;
+    defaultExpiryDays?: number | undefined;
+  } | undefined;
+  giftCard?: {
+    allowNegativeBalance?: boolean | undefined;
+    maxBalance?: number | undefined;
+  } | undefined;
+  indexes?: Partial<Record<ModelName, IndexDefinition[]>> | undefined;
+  autoIndex?: boolean | Partial<Record<ModelName, boolean>> | undefined;
+  events?: {
+    transport?: EventTransport$1 | undefined;
+  } | undefined;
+  /**
+   * Host-provided outbox store (PACKAGE_RULES §5.5 + §P8). When wired, every
+   * domain event is persisted to the outbox inside the caller's `ctx.session`
+   * BEFORE being published to the transport — giving at-least-once delivery
+   * via the host-side relay. Absent → transport-only best-effort.
+   *
+   * Explicit `| undefined` per `exactOptionalPropertyTypes` convention.
+   */
+  outbox?: OutboxStore | undefined;
+  /**
+   * Optional logger for dispatch-layer errors. Used by the shared
+   * `dispatch()` helper to surface outbox/transport failures without
+   * aborting the domain mutation. Defaults to `console`.
+   */
+  logger?: {
+    error(message: string, ...args: unknown[]): void;
+  } | undefined;
+  plugins?: RepositoryPlugins | undefined;
+}
+type ResolvedTenant = ResolvedTenantConfig;
+interface ResolvedConfig {
+  evaluation: {
+    maxStackablePromotions: number;
+    allowExclusiveAndStackable: boolean;
+  };
+  voucher: {
+    codeLength: number;
+    codePrefix: string;
+    defaultExpiryDays: number | null;
+  };
+  giftCard: {
+    allowNegativeBalance: boolean;
+    maxBalance: number | null;
+  };
+  tenant: ResolvedTenant;
+}
+//#endregion
+//#region src/models/create-models.d.ts
+interface PromoModels {
+  Program: Model<unknown>;
+  Rule: Model<unknown>;
+  Reward: Model<unknown>;
+  Voucher: Model<unknown>;
+}
+//#endregion
+//#region src/types/inputs.d.ts
+/**
+ * Extends `@classytic/primitives`' {@link OperationContext}. The
+ * `[key: string]: unknown` fall-through lets hosts pass dynamic tenant keys
+ * when they've configured a custom `contextKey` on `TenantConfig`.
+ */
+interface PromoContext extends OperationContext {
+  /** Narrowed from primitives' `IdLike` to string. */
+  actorId?: string;
+  /** Narrowed from primitives' `IdLike` to string. */
+  organizationId?: string;
+  /** Narrows primitives' `session: unknown` to the concrete Mongoose type so
+   *  this context flows directly into mongokit repository calls. */
+  session?: ClientSession;
+  [key: string]: unknown;
+}
+interface CreateProgramInput {
+  name: string;
+  description?: string;
+  programType: ProgramType;
+  triggerMode: TriggerMode;
+  stackingMode?: StackingMode;
+  priority?: number;
+  startsAt?: Date;
+  endsAt?: Date;
+  maxUsageTotal?: number;
+  maxUsagePerCustomer?: number;
+  applicableCustomerIds?: string[];
+  applicableCustomerTags?: string[];
+  metadata?: Record<string, unknown>;
+}
+interface UpdateProgramInput {
+  name?: string;
+  description?: string;
+  stackingMode?: StackingMode;
+  priority?: number;
+  startsAt?: Date;
+  endsAt?: Date;
+  maxUsageTotal?: number;
+  maxUsagePerCustomer?: number;
+  applicableCustomerIds?: string[];
+  applicableCustomerTags?: string[];
+  metadata?: Record<string, unknown>;
+}
+interface CreateRuleInput {
+  name?: string;
+  minimumAmount?: number;
+  minimumQuantity?: number;
+  applicableProductIds?: string[];
+  applicableCategories?: string[];
+  applicableSkus?: string[];
+  buyQuantity?: number;
+  code?: string;
+  startsAt?: Date;
+  endsAt?: Date;
+  metadata?: Record<string, unknown>;
+}
+interface UpdateRuleInput {
+  name?: string;
+  minimumAmount?: number;
+  minimumQuantity?: number;
+  applicableProductIds?: string[];
+  applicableCategories?: string[];
+  applicableSkus?: string[];
+  buyQuantity?: number;
+  code?: string;
+  startsAt?: Date;
+  endsAt?: Date;
+  metadata?: Record<string, unknown>;
+}
+interface CreateRewardInput {
+  ruleId?: string;
+  rewardType: RewardType;
+  discountMode?: DiscountMode;
+  discountAmount?: number;
+  maxDiscountAmount?: number;
+  discountScope?: DiscountScope;
+  applicableProductIds?: string[];
+  freeProductId?: string;
+  freeProductSku?: string;
+  freeQuantity?: number;
+  giftCardAmount?: number;
+  metadata?: Record<string, unknown>;
+}
+interface UpdateRewardInput {
+  discountMode?: DiscountMode;
+  discountAmount?: number;
+  maxDiscountAmount?: number;
+  discountScope?: DiscountScope;
+  applicableProductIds?: string[];
+  freeProductId?: string;
+  freeProductSku?: string;
+  freeQuantity?: number;
+  giftCardAmount?: number;
+  metadata?: Record<string, unknown>;
+}
+interface GenerateCodesInput {
+  programId: string;
+  count: number;
+  customerId?: string;
+  expiresAt?: Date;
+  metadata?: Record<string, unknown>;
+}
+interface GenerateSingleCodeInput {
+  programId: string;
+  code?: string;
+  customerId?: string;
+  expiresAt?: Date;
+  initialBalance?: number;
+  metadata?: Record<string, unknown>;
+}
+interface RedeemVoucherInput {
+  code: string;
+  orderId: string;
+  customerId?: string;
+  discountAmount: number;
+  idempotencyKey?: string;
+}
+interface GiftCardSpendInput {
+  code: string;
+  amount: number;
+  orderId: string;
+  description?: string;
+  idempotencyKey?: string;
+}
+interface GiftCardTopUpInput {
+  code: string;
+  amount: number;
+  description?: string;
+  idempotencyKey?: string;
+}
+interface CartItem {
+  productId: string;
+  sku?: string;
+  categoryId?: string;
+  quantity: number;
+  unitPrice: number;
+  lineTotal?: number;
+}
+interface EvaluateInput {
+  items: CartItem[];
+  subtotal: number;
+  codes?: string[];
+  customerId?: string;
+  customerTags?: string[];
+}
+interface ListQuery {
+  page?: number;
+  limit?: number;
+  sort?: string;
+  filters?: Record<string, unknown>;
+}
+//#endregion
+//#region src/events/dispatch.d.ts
+interface DispatchLogger {
+  error(message: string, ...args: unknown[]): void;
+}
+interface DispatchDeps {
+  events?: EventTransport$1 | undefined;
+  outbox?: OutboxStore | undefined;
+  logger?: DispatchLogger | undefined;
+}
+//#endregion
+//#region src/domain/entities/program.d.ts
+interface Program {
+  _id: string;
+  name: string;
+  description?: string;
+  programType: ProgramType;
+  triggerMode: TriggerMode;
+  status: ProgramStatus;
+  stackingMode: StackingMode;
+  priority: number;
+  startsAt?: Date;
+  endsAt?: Date;
+  maxUsageTotal?: number;
+  usedCount: number;
+  maxUsagePerCustomer?: number;
+  applicableCustomerIds: string[];
+  applicableCustomerTags: string[];
+  customerUsageCounts?: Record<string, number>;
+  metadata?: Record<string, unknown>;
+  createdAt: Date;
+  updatedAt: Date;
+}
+//#endregion
+//#region src/repositories/program.repository.d.ts
+declare class ProgramRepository extends Repository<Program> {
+  private dispatchDeps;
+  constructor(model: Model<Program>, plugins?: PluginType[], dispatchDeps?: DispatchDeps);
+  activate(id: string, ctx: PromoContext): Promise<Program>;
+  pause(id: string, ctx: PromoContext): Promise<Program>;
+  archive(id: string, ctx: PromoContext): Promise<Program>;
+  private _transition;
+  incrementUsage(id: string, ctx?: Record<string, unknown>): Promise<Program>;
+  decrementUsage(id: string, ctx?: Record<string, unknown>): Promise<Program>;
+  getCustomerUsage(id: string, customerId: string, ctx?: Record<string, unknown>): Promise<number>;
+  incrementCustomerUsage(id: string, customerId: string, ctx?: Record<string, unknown>): Promise<Program>;
+  findActive(now?: Date, ctx?: Record<string, unknown>): Promise<Program[]>;
+}
+//#endregion
+//#region src/domain/entities/reward.d.ts
+interface Reward {
+  _id: string;
+  programId: string;
+  ruleId?: string;
+  rewardType: RewardType;
+  discountMode?: DiscountMode;
+  discountAmount?: number;
+  maxDiscountAmount?: number;
+  discountScope: DiscountScope;
+  applicableProductIds: string[];
+  freeProductId?: string;
+  freeProductSku?: string;
+  freeQuantity: number;
+  giftCardAmount?: number;
+  metadata?: Record<string, unknown>;
+  createdAt: Date;
+  updatedAt: Date;
+}
+//#endregion
+//#region src/repositories/reward.repository.d.ts
+declare class RewardRepository extends Repository<Reward> {
+  constructor(model: Model<Reward>, plugins?: PluginType[]);
+}
+//#endregion
+//#region src/domain/entities/rule.d.ts
+interface Rule {
+  _id: string;
+  programId: string;
+  name?: string;
+  minimumAmount: number;
+  minimumQuantity: number;
+  applicableProductIds: string[];
+  applicableCategories: string[];
+  applicableSkus: string[];
+  buyQuantity?: number;
+  code?: string;
+  startsAt?: Date;
+  endsAt?: Date;
+  metadata?: Record<string, unknown>;
+  createdAt: Date;
+  updatedAt: Date;
+}
+//#endregion
+//#region src/repositories/rule.repository.d.ts
+declare class RuleRepository extends Repository<Rule> {
+  constructor(model: Model<Rule>, plugins?: PluginType[]);
+}
+//#endregion
+//#region src/domain/entities/voucher.d.ts
+interface BalanceLedgerEntry {
+  amount: number;
+  orderId?: string;
+  description?: string;
+  createdAt: Date;
+  idempotencyKey?: string;
+}
+interface VoucherRedemption {
+  orderId: string;
+  customerId?: string;
+  discountAmount: number;
+  redeemedAt: Date;
+  idempotencyKey?: string;
+}
+interface Voucher {
+  _id: string;
+  programId: string;
+  code: string;
+  status: VoucherStatus;
+  customerId?: string;
+  usageLimit: number;
+  usedCount: number;
+  initialBalance?: number;
+  currentBalance?: number;
+  balanceLedger: BalanceLedgerEntry[];
+  expiresAt?: Date;
+  redemptions: VoucherRedemption[];
+  metadata?: Record<string, unknown>;
+  createdAt: Date;
+  updatedAt: Date;
+}
+//#endregion
+//#region src/repositories/voucher.repository.d.ts
+declare class VoucherRepository extends Repository<Voucher> {
+  private dispatchDeps;
+  private tenantField;
+  constructor(model: Model<Voucher>, plugins?: PluginType[], dispatchDeps?: DispatchDeps, tenantField?: string);
+  /**
+   * Copy the tenant id from `ctx` onto the write payload so the doc persists
+   * with the correct `organizationId` even when the host has opted OUT of the
+   * auto-wired `multiTenantPlugin` (e.g. arc hosts that scope at the
+   * framework layer — see `@classytic/order` CLAUDE.md: "Child repos set
+   * `organizationId` explicitly on the doc"). No-op when `ctx` omits the
+   * tenant id or the payload already carries it.
+   */
+  private _injectTenant;
+  create(data: Parameters<Repository<Voucher>['create']>[0], options?: Parameters<Repository<Voucher>['create']>[1]): Promise<Voucher>;
+  createMany(docs: Parameters<Repository<Voucher>['createMany']>[0], options?: Parameters<Repository<Voucher>['createMany']>[1]): Promise<Voucher[]>;
+  /** Domain verb: cancel a voucher (status transition + event). */
+  cancel(id: string, ctx: PromoContext): Promise<Voucher>;
+  /** Atomic usage increment + push redemption record. */
+  incrementUsage(id: string, redemption: Record<string, unknown>, ctx?: Record<string, unknown>): Promise<Voucher>;
+  /** Atomic balance delta + push ledger entry. */
+  addLedgerEntry(id: string, entry: Record<string, unknown>, balanceDelta: number, ctx?: Record<string, unknown>): Promise<Voucher>;
+  /**
+   * Batch expire by date.
+   *
+   * Routes through `findAll` + per-doc `update` instead of a raw
+   * `this.Model.updateMany`. Rationale:
+   *  1. `findAll` casts the filter through the schema (so an ObjectId
+   *     tenant field on a write-time String context doesn't silently
+   *     return 0 rows the way a raw `$match` would).
+   *  2. `update` fires the full hook pipeline (multi-tenant, audit,
+   *     soft-delete) on every expiration — a bulk `updateMany` at the
+   *     Model layer bypasses all of them.
+   * Volume is bounded per tenant (active + past-expiry vouchers), so an
+   * N+1 loop is acceptable for correctness.
+   */
+  expireByDate(before: Date, ctx?: Record<string, unknown>): Promise<number>;
+  /**
+   * Lookup voucher by unique code, scoped to the tenant in `ctx` when
+   * tenant scoping is configured.
+   *
+   * Manual tenant injection mirrors `expireByDate` and `ProgramRepository.findActive`
+   * — it makes the method work whether the host opts into the auto-wired
+   * `multiTenantPlugin` or enforces scoping at its own framework layer
+   * (e.g. arc's preset + `BaseController`). Without this, a host that
+   * runs the plugin off would leak vouchers across branches at
+   * validate/redeem/spend/topUp call sites.
+   */
+  getByCode(code: string, ctx?: Record<string, unknown>): Promise<Voucher | null>;
+  /**
+   * Idempotency check on nested arrays. Routes through mongokit's `count`
+   * so `multiTenantPlugin` injects the configured tenant field from
+   * `ctx` — a non-tenant-scoped check would cross organization boundaries.
+   */
+  hasIdempotencyKey(id: string, key: string, ctx?: Record<string, unknown>): Promise<boolean>;
+}
+//#endregion
+//#region src/repositories/create-repositories.d.ts
+interface PromoRepositories {
+  program: ProgramRepository;
+  rule: RuleRepository;
+  reward: RewardRepository;
+  voucher: VoucherRepository;
+}
+//#endregion
+//#region src/domain/ports/unit-of-work.port.d.ts
+type TransactionSession = ClientSession;
+interface UnitOfWork {
+  withTransaction<T>(cb: (session: TransactionSession) => Promise<T>): Promise<T>;
+}
+//#endregion
+//#region src/types/results.d.ts
+interface DiscountLine {
+  programId: string;
+  programName: string;
+  rewardId: string;
+  type: 'percentage' | 'fixed';
+  scope: 'order' | 'cheapest' | 'specific_products';
+  amount: number;
+  description: string;
+  voucherCode?: string;
+}
+interface FreeProductLine {
+  programId: string;
+  programName: string;
+  rewardId: string;
+  productId?: string;
+  productSku?: string;
+  quantity: number;
+  description: string;
+}
+interface RejectedCode {
+  code: string;
+  reason: string;
+}
+interface EvaluationResult {
+  evaluationId: string;
+  /**
+   * Deterministic hash of the evaluated cart (items + subtotal + codes +
+   * customerId). Hosts that want tamper-proof commits pass this hash back
+   * to `EvaluationService.commit(evaluationId, orderId, ctx, { cartHash })`;
+   * the engine throws `CartHashMismatchError` when the caller's hash does
+   * not match what was evaluated. Omitting the hash at commit keeps the
+   * legacy "trusted host" behaviour.
+   */
+  cartHash: string;
+  appliedDiscounts: DiscountLine[];
+  freeProducts: FreeProductLine[];
+  totalDiscount: number;
+  subtotalAfterDiscount: number;
+  appliedCodes: string[];
+  rejectedCodes: RejectedCode[];
+  warnings: string[];
+  isPreview: boolean;
+  programsApplied: string[];
+}
+interface CommitResult {
+  evaluationId: string;
+  orderId: string;
+  totalDiscount: number;
+  programsCommitted: number;
+  vouchersUsed: number;
+}
+interface VoucherValidation {
+  valid: boolean;
+  voucher?: {
+    code: string;
+    programId: string;
+    programType: string;
+    status: string;
+    remainingUses: number;
+    currentBalance?: number;
+    expiresAt?: Date;
+  };
+  error?: string;
+}
+interface GiftCardBalance {
+  code: string;
+  initialBalance: number;
+  currentBalance: number;
+  spent: number;
+  voucherId: string;
+}
+interface PaginatedResult<T> {
+  docs: T[];
+  page: number;
+  limit: number;
+  total: number;
+  pages: number;
+  hasNext: boolean;
+  hasPrev: boolean;
+}
+//#endregion
+//#region src/services/evaluation.service.d.ts
+interface CommitOptions {
+  /**
+   * The `cartHash` returned from `evaluate`. When provided, the engine
+   * verifies it matches the hash computed at evaluation time and throws
+   * `CartHashMismatchError` on mismatch. Guards against cart-tampering
+   * between evaluate and commit (e.g. user previews a big discount on a
+   * heavy cart, swaps the cart for a cheaper one, then commits the stale
+   * discount). Hosts that trust their own commit pipeline end-to-end may
+   * omit it for the legacy behaviour.
+   */
+  cartHash?: string;
+}
+declare class EvaluationService {
+  private programRepo;
+  private ruleRepo;
+  private rewardRepo;
+  private voucherRepo;
+  private unitOfWork;
+  private dispatchDeps;
+  private config;
+  private pendingEvaluations;
+  constructor(programRepo: ProgramRepository, ruleRepo: RuleRepository, rewardRepo: RewardRepository, voucherRepo: VoucherRepository, unitOfWork: UnitOfWork, dispatchDeps: DispatchDeps, config: ResolvedConfig);
+  evaluate(input: EvaluateInput, ctx: PromoContext): Promise<EvaluationResult>;
+  preview(input: EvaluateInput, ctx: PromoContext): Promise<EvaluationResult>;
+  commit(evaluationId: string, orderId: string, ctx: PromoContext, options?: CommitOptions): Promise<CommitResult>;
+  rollback(evaluationId: string, ctx: PromoContext): Promise<void>;
+  private doEvaluate;
+  private isCustomerEligible;
+  private matchBestRule;
+  private matchSingleRule;
+  private filterRewardsByRule;
+  private computeDiscount;
+  private getEligibleItems;
+  private describeDiscount;
+}
+//#endregion
+//#region src/services/voucher.service.d.ts
+/**
+ * VoucherService — multi-repo domain orchestration only.
+ *
+ * Code generation, redemption (transactional + idempotency), gift card
+ * spend/topUp, and validation live here because they need programRepo +
+ * voucherRepo + config + transactions.
+ *
+ * Simple lookups (getById, getByCode, getAll) and the cancel domain verb
+ * live on VoucherRepository directly — callers use the repo. §2/§3.
+ */
+declare class VoucherService {
+  private voucherRepo;
+  private programRepo;
+  private unitOfWork;
+  private dispatchDeps;
+  private config;
+  constructor(voucherRepo: VoucherRepository, programRepo: ProgramRepository, unitOfWork: UnitOfWork, dispatchDeps: DispatchDeps, config: ResolvedConfig);
+  generateCodes(input: GenerateCodesInput, ctx: PromoContext): Promise<Voucher[]>;
+  generateSingleCode(input: GenerateSingleCodeInput, ctx: PromoContext): Promise<Voucher>;
+  validateCode(code: string, ctx: PromoContext): Promise<VoucherValidation>;
+  redeem(input: RedeemVoucherInput, ctx: PromoContext): Promise<Voucher>;
+  getBalance(code: string, ctx: PromoContext): Promise<GiftCardBalance>;
+  spend(input: GiftCardSpendInput, ctx: PromoContext): Promise<GiftCardBalance>;
+  private spendInTransaction;
+  topUp(input: GiftCardTopUpInput, ctx: PromoContext): Promise<GiftCardBalance>;
+  private assertVoucherUsable;
+}
+//#endregion
+//#region src/services/create-services.d.ts
+interface PromoServices {
+  voucher: VoucherService;
+  evaluation: EvaluationService;
+}
+//#endregion
+//#region src/events/event-constants.d.ts
+declare const PromoEvents: {
+  readonly PROGRAM_CREATED: "promo.program.created";
+  readonly PROGRAM_ACTIVATED: "promo.program.activated";
+  readonly PROGRAM_PAUSED: "promo.program.paused";
+  readonly PROGRAM_ARCHIVED: "promo.program.archived";
+  readonly RULE_ADDED: "promo.rule.added";
+  readonly RULE_UPDATED: "promo.rule.updated";
+  readonly RULE_REMOVED: "promo.rule.removed";
+  readonly REWARD_ADDED: "promo.reward.added";
+  readonly REWARD_UPDATED: "promo.reward.updated";
+  readonly REWARD_REMOVED: "promo.reward.removed";
+  readonly VOUCHER_GENERATED: "promo.voucher.generated";
+  readonly VOUCHER_REDEEMED: "promo.voucher.redeemed";
+  readonly VOUCHER_CANCELLED: "promo.voucher.cancelled";
+  readonly VOUCHER_EXPIRED: "promo.voucher.expired";
+  readonly GIFT_CARD_SPENT: "promo.gift_card.spent";
+  readonly GIFT_CARD_TOPPED_UP: "promo.gift_card.topped_up";
+  readonly GIFT_CARD_EXHAUSTED: "promo.gift_card.exhausted";
+  readonly EVALUATION_COMPLETED: "promo.evaluation.completed";
+  readonly EVALUATION_COMMITTED: "promo.evaluation.committed";
+  readonly EVALUATION_ROLLED_BACK: "promo.evaluation.rolled_back";
+};
+type PromoEventName = (typeof PromoEvents)[keyof typeof PromoEvents];
+//#endregion
+//#region src/events/promo-event-catalog.d.ts
+interface PromoEventSchema {
+  type: 'object';
+  properties?: Record<string, {
+    type?: string;
+    format?: string;
+    [key: string]: unknown;
+  }>;
+  required?: string[];
+  [key: string]: unknown;
+}
+interface PromoEventDefinition<TSchema extends z.ZodType = z.ZodType> {
+  readonly name: string;
+  readonly version: number;
+  readonly description?: string;
+  readonly schema: PromoEventSchema;
+  readonly zodSchema: TSchema;
+  create(payload: z.infer<TSchema>, meta?: Partial<DomainEvent$1['meta']>): DomainEvent$1<z.infer<TSchema>>;
+  readonly __payload?: z.infer<TSchema>;
+}
+type PromoEventPayloadOf<D> = D extends PromoEventDefinition<infer S> ? z.infer<S> : never;
+declare const ProgramCreated: PromoEventDefinition<z.ZodObject<{
+  programId: z.ZodString;
+  programType: z.ZodString;
+  status: z.ZodString;
+  actorId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>>;
+declare const ProgramActivated: PromoEventDefinition<z.ZodObject<{
+  programId: z.ZodString;
+  programType: z.ZodString;
+  status: z.ZodString;
+  actorId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>>;
+declare const ProgramPaused: PromoEventDefinition<z.ZodObject<{
+  programId: z.ZodString;
+  programType: z.ZodString;
+  status: z.ZodString;
+  actorId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>>;
+declare const ProgramArchived: PromoEventDefinition<z.ZodObject<{
+  programId: z.ZodString;
+  programType: z.ZodString;
+  status: z.ZodString;
+  actorId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>>;
+declare const RuleAdded: PromoEventDefinition<z.ZodObject<{
+  programId: z.ZodString;
+  ruleId: z.ZodString;
+  actorId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>>;
+declare const RuleUpdated: PromoEventDefinition<z.ZodObject<{
+  programId: z.ZodString;
+  ruleId: z.ZodString;
+  actorId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>>;
+declare const RuleRemoved: PromoEventDefinition<z.ZodObject<{
+  programId: z.ZodString;
+  ruleId: z.ZodString;
+  actorId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>>;
+declare const RewardAdded: PromoEventDefinition<z.ZodObject<{
+  programId: z.ZodString;
+  rewardId: z.ZodString;
+  actorId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>>;
+declare const RewardUpdated: PromoEventDefinition<z.ZodObject<{
+  programId: z.ZodString;
+  rewardId: z.ZodString;
+  actorId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>>;
+declare const RewardRemoved: PromoEventDefinition<z.ZodObject<{
+  programId: z.ZodString;
+  rewardId: z.ZodString;
+  actorId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>>;
+declare const VoucherGenerated: PromoEventDefinition<z.ZodObject<{
+  programId: z.ZodString;
+  voucherIds: z.ZodArray<z.ZodString>;
+  codes: z.ZodArray<z.ZodString>;
+  count: z.ZodNumber;
+  actorId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>>;
+declare const VoucherRedeemed: PromoEventDefinition<z.ZodObject<{
+  voucherId: z.ZodString;
+  code: z.ZodString;
+  orderId: z.ZodString;
+  discountAmount: z.ZodNumber;
+  customerId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>>;
+declare const VoucherCancelled: PromoEventDefinition<z.ZodObject<{
+  voucherId: z.ZodString;
+  code: z.ZodString;
+  status: z.ZodString;
+}, z.core.$strip>>;
+declare const VoucherExpired: PromoEventDefinition<z.ZodObject<{
+  voucherId: z.ZodString;
+  code: z.ZodString;
+  status: z.ZodString;
+}, z.core.$strip>>;
+declare const GiftCardSpent: PromoEventDefinition<z.ZodObject<{
+  voucherId: z.ZodString;
+  code: z.ZodString;
+  amount: z.ZodNumber;
+  remainingBalance: z.ZodNumber;
+  orderId: z.ZodString;
+}, z.core.$strip>>;
+declare const GiftCardToppedUp: PromoEventDefinition<z.ZodObject<{
+  voucherId: z.ZodString;
+  code: z.ZodString;
+  amount: z.ZodNumber;
+  newBalance: z.ZodNumber;
+}, z.core.$strip>>;
+declare const GiftCardExhausted: PromoEventDefinition<z.ZodObject<{
+  voucherId: z.ZodString;
+  code: z.ZodString;
+  status: z.ZodString;
+}, z.core.$strip>>;
+declare const EvaluationCompleted: PromoEventDefinition<z.ZodObject<{
+  evaluationId: z.ZodString;
+  totalDiscount: z.ZodNumber;
+  programsApplied: z.ZodNumber;
+  codesUsed: z.ZodArray<z.ZodString>;
+  isPreview: z.ZodBoolean;
+}, z.core.$strip>>;
+declare const EvaluationCommitted: PromoEventDefinition<z.ZodObject<{
+  evaluationId: z.ZodString;
+  orderId: z.ZodString;
+  totalDiscount: z.ZodNumber;
+}, z.core.$strip>>;
+declare const EvaluationRolledBack: PromoEventDefinition<z.ZodObject<{
+  evaluationId: z.ZodString;
+}, z.core.$strip>>;
+/**
+ * Every promo event defined in the package — pass to Arc's
+ * `EventRegistry`. Hosts wire ONE array; the whole `promo.*` namespace
+ * becomes introspectable via OpenAPI and auto-validated at publish time
+ * when `eventPlugin({ validateMode: 'reject' })` is set.
+ */
+declare const promoEventDefinitions: ReadonlyArray<PromoEventDefinition>;
+//#endregion
 //#region src/index.d.ts
 declare function resolveConfig(config: PromoConfig): ResolvedConfig;
 interface PromoEngine {
   models: PromoModels;
   repositories: PromoRepositories;
   services: PromoServices;
-  events: EventEmitterPort;
+  events: EventTransport$1;
+  syncIndexes(): Promise<void>;
 }
 declare function createPromoEngine(config: PromoConfig): PromoEngine;
 //#endregion
-export { type BalanceLedgerEntry, type CartItem, type CommitResult, type CreateProgramInput, type CreateRewardInput, type CreateRuleInput, type DiscountLine, type EvaluateInput, type EvaluationResult, type EventEmitterPort, type FreeProductLine, type FullProgram, type GenerateCodesInput, type GenerateSingleCodeInput, type GiftCardBalance, type GiftCardSpendInput, type GiftCardTopUpInput, type ListQuery, type PaginatedResult, type Program, type PromoConfig, type PromoContext, PromoEngine, PromoEvents, type PromoModels, type PromoRepositories, type PromoServices, type RedeemVoucherInput, type RejectedCode, type ResolvedConfig, type ResolvedTenant, type Reward, type Rule, type UpdateProgramInput, type UpdateRewardInput, type UpdateRuleInput, type Voucher, type VoucherRedemption, type VoucherValidation, createPromoEngine, resolveConfig };
+export { type BalanceLedgerEntry, type CartItem, type CommitResult, type CreateProgramInput, type CreateRewardInput, type CreateRuleInput, type DiscountLine, type DomainEvent, type EvaluateInput, EvaluationCommitted, EvaluationCompleted, type EvaluationResult, EvaluationRolledBack, type EventHandler, type EventTransport, type FreeProductLine, type GenerateCodesInput, type GenerateSingleCodeInput, type GiftCardBalance, GiftCardExhausted, type GiftCardSpendInput, GiftCardSpent, type GiftCardTopUpInput, GiftCardToppedUp, type ListQuery, type PaginatedResult, type Program, ProgramActivated, ProgramArchived, ProgramCreated, ProgramPaused, ProgramRepository, type PromoConfig, type PromoContext, PromoEngine, type PromoEventDefinition, type PromoEventName, type PromoEventPayloadOf, type PromoEventSchema, PromoEvents, type PromoModels, type PromoRepositories, type PromoServices, type RedeemVoucherInput, type RejectedCode, type ResolvedConfig, type ResolvedTenant, type Reward, RewardAdded, RewardRemoved, RewardRepository, RewardUpdated, type Rule, RuleAdded, RuleRemoved, RuleRepository, RuleUpdated, type UpdateProgramInput, type UpdateRewardInput, type UpdateRuleInput, type Voucher, VoucherCancelled, VoucherExpired, VoucherGenerated, VoucherRedeemed, type VoucherRedemption, VoucherRepository, type VoucherValidation, createPromoEngine, promoEventDefinitions, resolveConfig };