@openlup/platform 0.17.0 → 0.19.0

package/src/promotions/adminPromotionCodesContracts.ts

@@ -0,0 +1,244 @@
+import { z } from "./validation.js";
+
+import { COMMERCE_CONTRACT_VERSION } from "../pricing/index.js";
+
+export const PROMOTION_CODE_STATUSES = ["draft", "active", "paused", "archived"] as const;
+export const PROMOTION_CODE_EFFECTIVE_STATUSES = [
+  "active",
+  "draft",
+  "paused",
+  "scheduled",
+  "expired",
+  "archived",
+] as const;
+export const PROMOTION_CODE_STATUS_FILTERS = [
+  ...PROMOTION_CODE_EFFECTIVE_STATUSES,
+  "expired_or_archived",
+] as const;
+export const PROMOTION_CODE_SCOPES = ["one_time", "subscription_initial"] as const;
+
+const nullablePositiveInteger = z.number().int().positive().nullable();
+const maximumPromotionFixedMinor = 2_147_483_647;
+const optionalDateTime = z.string().datetime({ offset: true }).nullable();
+const scopesSchema = z
+  .array(z.enum(PROMOTION_CODE_SCOPES))
+  .min(1)
+  .max(2)
+  .refine((scopes) => new Set(scopes).size === scopes.length, {
+    message: "Purchase scopes must be unique",
+  });
+
+const productTargetBenefitSchema = z.union([
+  z.object({ lane: z.literal("product"), kind: z.literal("target_percentage"), valueBps: z.number().int().min(1).max(9_999) }).strict(),
+  z.object({ lane: z.literal("product"), kind: z.literal("fixed_amount"), valueMinor: z.number().int().positive().max(maximumPromotionFixedMinor) }).strict(),
+]);
+const shippingBenefitSchema = z.union([
+  z.object({ lane: z.literal("shipping"), kind: z.literal("percentage"), valueBps: z.number().int().min(1).max(9_999) }).strict(),
+  z.object({ lane: z.literal("shipping"), kind: z.literal("fixed_amount"), valueMinor: z.number().int().positive().max(maximumPromotionFixedMinor) }).strict(),
+  z.object({ lane: z.literal("shipping"), kind: z.literal("free_shipping") }).strict(),
+]);
+export const promotionCodeBenefitSchema = z.union([
+  productTargetBenefitSchema,
+  shippingBenefitSchema,
+  z.object({ lane: z.literal("product"), kind: z.literal("percentage"), valueBps: z.number().int().min(0) }).strict(),
+  z.object({ lane: z.literal("shipping"), kind: z.literal("percentage"), valueBps: z.number().int().min(0) }).strict(),
+  z.object({ lane: z.literal("product"), kind: z.literal("fixed_amount"), valueMinor: z.number().int().nonnegative() }).strict(),
+  z.object({ lane: z.literal("shipping"), kind: z.literal("fixed_amount"), valueMinor: z.number().int().nonnegative() }).strict(),
+  z.object({
+    lane: z.enum(["product", "shipping"]),
+    kind: z.enum(["percentage", "fixed_amount"]),
+    validationState: z.literal("unsupported_legacy_value"),
+  }).strict(),
+]);
+const createBenefitSchema = z.union([productTargetBenefitSchema, shippingBenefitSchema]);
+
+const benefitsSchema = z
+  .array(promotionCodeBenefitSchema)
+  .min(1)
+  .max(2)
+  .refine((benefits) => new Set(benefits.map((benefit) => benefit.lane)).size === benefits.length, {
+    message: "Only one benefit per adjustment lane is allowed",
+  });
+const createBenefitsSchema = z
+  .array(createBenefitSchema)
+  .min(1)
+  .max(2)
+  .refine((benefits) => new Set(benefits.map((benefit) => benefit.lane)).size === benefits.length, {
+    message: "Only one benefit per adjustment lane is allowed",
+  });
+
+export const promotionCodePreviewContextSchema = z
+  .object({
+    referenceProductMinor: z.number().int().positive(),
+    oneTimeProductMinor: z.number().int().positive(),
+    subscriptionProductMinor: z.number().int().positive(),
+    shippingMinor: z.number().int().nonnegative(),
+  })
+  .strict()
+  .refine((value) => value.oneTimeProductMinor <= value.referenceProductMinor, {
+    message: "One-time product price cannot exceed the reference price",
+  })
+  .refine((value) => value.subscriptionProductMinor <= value.referenceProductMinor, {
+    message: "Subscription product price cannot exceed the reference price",
+  });
+
+export const promotionCodePreviewRequestSchema = z
+  .object({
+    benefits: benefitsSchema,
+    scopes: scopesSchema,
+    promotionEngineVersion: z.enum(["promotion-engine.v1", "promotion-engine.v2"]).default("promotion-engine.v2"),
+    minimumReferenceMinor: z.number().int().nonnegative().default(0),
+    context: promotionCodePreviewContextSchema,
+  })
+  .strict();
+
+export const promotionCodePreviewResultSchema = z.object({
+  scope: z.enum(PROMOTION_CODE_SCOPES),
+  productPayableMinor: z.number().int().nonnegative(),
+  shippingPayableMinor: z.number().int().nonnegative(),
+  effectiveProductDiscountBps: z.number().int().min(0).max(10_000),
+  winner: z.enum(["code", "automatic"]),
+  floorApplied: z.boolean(),
+  adjustments: z.array(
+    z.object({
+      lane: z.enum(["product", "shipping"]),
+      kind: z.enum(["target_percentage", "percentage", "fixed_amount", "free_shipping"]),
+      amountOffMinor: z.number().int().nonnegative(),
+      beforeMinor: z.number().int().nonnegative(),
+      afterMinor: z.number().int().nonnegative(),
+    }),
+  ),
+});
+
+export const promotionCodePreviewResponseSchema = z.object({
+  contractVersion: z.literal(COMMERCE_CONTRACT_VERSION),
+  promotionEngineVersion: z.enum(["promotion-engine.v1", "promotion-engine.v2"]),
+  previewProof: z.string().regex(/^[A-Za-z0-9_-]{43}$/),
+  results: z.array(promotionCodePreviewResultSchema).length(2),
+});
+
+export const promotionCodeCreateRequestSchema = z
+  .object({
+    name: z.string().trim().min(1).max(120),
+    description: z.string().trim().max(500).nullable().default(null),
+    code: z.discriminatedUnion("kind", [
+      z.object({ kind: z.literal("automatic") }).strict(),
+      z.object({ kind: z.literal("manual"), value: z.string().trim().min(3).max(64).regex(/^[A-Za-z0-9_-]+$/) }).strict(),
+    ]),
+    benefits: createBenefitsSchema,
+    scopes: scopesSchema,
+    validFrom: z.string().datetime({ offset: true }),
+    validTo: optionalDateTime,
+    minimumReferenceMinor: z.number().int().nonnegative().default(0),
+    redemptionLimitGlobal: nullablePositiveInteger.default(null),
+    redemptionLimitPerCustomer: nullablePositiveInteger.default(null),
+    status: z.enum(["draft", "active"]).default("draft"),
+    previewContext: promotionCodePreviewContextSchema.optional(),
+    previewProof: z.string().regex(/^[A-Za-z0-9_-]{43}$/).optional(),
+    idempotencyKey: z.string().uuid(),
+  })
+  .strict()
+  .refine((value) => value.validTo === null || Date.parse(value.validTo) > Date.parse(value.validFrom), {
+    message: "validTo must be after validFrom",
+  })
+  .refine(
+    (value) => value.status !== "active" || Boolean(value.previewContext && value.previewProof),
+    { message: "Active codes require a successful backend preview" },
+  );
+
+export const promotionCodeCreateResponseSchema = z.object({
+  contractVersion: z.literal(COMMERCE_CONTRACT_VERSION),
+  id: z.string().uuid(),
+  code: z.string().min(3).max(64),
+  status: z.enum(PROMOTION_CODE_STATUSES),
+  revision: z.number().int().positive(),
+  idempotent: z.boolean(),
+});
+
+export const promotionCodeUpdateRequestSchema = z
+  .object({
+    id: z.string().uuid(),
+    expectedRevision: z.number().int().positive(),
+    updates: z
+      .object({
+        status: z.enum(PROMOTION_CODE_STATUSES).optional(),
+        validFrom: z.string().datetime({ offset: true }).optional(),
+        validTo: optionalDateTime.optional(),
+        redemptionLimitGlobal: nullablePositiveInteger.optional(),
+        redemptionLimitPerCustomer: nullablePositiveInteger.optional(),
+      })
+      .strict()
+      .refine((updates) => Object.values(updates).some((value) => value !== undefined), {
+        message: "At least one field is required",
+      }),
+    previewContext: promotionCodePreviewContextSchema.optional(),
+    previewProof: z.string().regex(/^[A-Za-z0-9_-]{43}$/).optional(),
+    idempotencyKey: z.string().uuid(),
+  })
+  .strict()
+  ;
+
+export const promotionCodeUpdateResponseSchema = z.object({
+  contractVersion: z.literal(COMMERCE_CONTRACT_VERSION),
+  id: z.string().uuid(),
+  status: z.enum(PROMOTION_CODE_STATUSES),
+  revision: z.number().int().positive(),
+  idempotent: z.boolean(),
+});
+
+export const promotionCodesListRequestSchema = z
+  .object({
+    q: z.string().trim().min(1).max(80).optional(),
+    status: z.enum([...PROMOTION_CODE_STATUS_FILTERS, "all"]).default("active"),
+    scope: z.enum([...PROMOTION_CODE_SCOPES, "both", "shipping", "all"]).default("all"),
+    cursor: z.string().max(500).optional(),
+    limit: z.coerce.number().int().min(1).max(100).default(25),
+  })
+  .strict();
+
+export const promotionCodeSummarySchema = z.object({
+  id: z.string().uuid(),
+  code: z.string(),
+  name: z.string(),
+  description: z.string().nullable(),
+  benefits: benefitsSchema,
+  promotionEngineVersion: z.enum(["promotion-engine.v1", "promotion-engine.v2"]),
+  scopes: scopesSchema,
+  status: z.enum(PROMOTION_CODE_STATUSES),
+  effectiveStatus: z.enum(PROMOTION_CODE_EFFECTIVE_STATUSES),
+  validFrom: z.string(),
+  validTo: z.string().nullable(),
+  minimumReferenceMinor: z.number().int().nonnegative(),
+  redemptionLimitGlobal: z.number().int().positive().nullable(),
+  redemptionLimitPerCustomer: z.number().int().positive().nullable(),
+  redeemedCount: z.number().int().nonnegative(),
+  reservedCount: z.number().int().nonnegative(),
+  remainingCount: z.number().int().nonnegative().nullable(),
+  createdAt: z.string(),
+  revision: z.number().int().positive(),
+});
+
+export const promotionCodesListResponseSchema = z.object({
+  contractVersion: z.literal(COMMERCE_CONTRACT_VERSION),
+  codes: z.array(promotionCodeSummarySchema),
+  nextCursor: z.string().nullable(),
+  capabilities: z.object({
+    mutationsEnabled: z.boolean(),
+  }).strict(),
+  legacyCompatibility: z.object({
+    ready: z.boolean(),
+    unprojectedCount: z.number().int().nonnegative(),
+    collisionGroupCount: z.number().int().nonnegative(),
+  }).strict(),
+});
+
+export type PromotionCodeBenefit = z.infer<typeof promotionCodeBenefitSchema>;
+export type PromotionCodePreviewRequest = z.infer<typeof promotionCodePreviewRequestSchema>;
+export type PromotionCodePreviewResponse = z.infer<typeof promotionCodePreviewResponseSchema>;
+export type PromotionCodeCreateRequest = z.infer<typeof promotionCodeCreateRequestSchema>;
+export type PromotionCodeCreateResponse = z.infer<typeof promotionCodeCreateResponseSchema>;
+export type PromotionCodeUpdateRequest = z.infer<typeof promotionCodeUpdateRequestSchema>;
+export type PromotionCodeUpdateResponse = z.infer<typeof promotionCodeUpdateResponseSchema>;
+export type PromotionCodesListRequest = z.infer<typeof promotionCodesListRequestSchema>;
+export type PromotionCodeSummary = z.infer<typeof promotionCodeSummarySchema>;
+export type PromotionCodesListResponse = z.infer<typeof promotionCodesListResponseSchema>;

package/src/promotions/adminPromotionCodesDataPort.ts

@@ -0,0 +1,56 @@
+import type {
+  PromotionCodeCreateRequest,
+  PromotionCodeSummary,
+  PromotionCodesListRequest,
+  PromotionCodeUpdateRequest,
+} from "./contracts/index.js";
+
+export interface PromotionCodesListResult {
+  codes: PromotionCodeSummary[];
+  nextCursor: string | null;
+  legacyCompatibility: {
+    ready: boolean;
+    unprojectedCount: number;
+    collisionGroupCount: number;
+  };
+}
+
+export interface PromotionCodeCreateResult {
+  id: string;
+  code: string;
+  status: "draft" | "active" | "paused" | "archived";
+  idempotent: boolean;
+  revision: number;
+}
+
+export interface PromotionCodeUpdateResult {
+  id: string;
+  status: "draft" | "active" | "paused" | "archived";
+  idempotent: boolean;
+  revision: number;
+}
+
+export interface AdminPromotionCodesDataPort {
+  list(actorId: string, input: PromotionCodesListRequest): Promise<PromotionCodesListResult>;
+  definition(actorId: string, id: string): Promise<{
+    benefits: PromotionCodeSummary["benefits"];
+    scopes: PromotionCodeCreateRequest["scopes"];
+    minimumReferenceMinor: number;
+    revision: number;
+    status: "draft" | "active" | "paused" | "archived";
+    validFrom: string;
+    validTo: string | null;
+    promotionEngineVersion: "promotion-engine.v1" | "promotion-engine.v2";
+  }>;
+  create(input: {
+    actorId: string;
+    request: PromotionCodeCreateRequest;
+    resolvedCode: string;
+    requestFingerprint: string;
+  }): Promise<PromotionCodeCreateResult>;
+  update(input: {
+    actorId: string;
+    request: PromotionCodeUpdateRequest;
+    requestFingerprint: string;
+  }): Promise<PromotionCodeUpdateResult>;
+}

package/src/promotions/adminPromotionCodesHandler.ts

@@ -0,0 +1,254 @@
+import { createHash } from "node:crypto";
+import {
+  promotionCodeCreateRequestSchema,
+  promotionCodeCreateResponseSchema,
+  promotionCodePreviewRequestSchema,
+  promotionCodePreviewResponseSchema,
+  promotionCodesListRequestSchema,
+  promotionCodesListResponseSchema,
+  promotionCodeUpdateRequestSchema,
+  promotionCodeUpdateResponseSchema,
+  type PromotionCodeCreateRequest,
+  type PromotionCodePreviewRequest,
+  type PromotionCodesListRequest,
+  type PromotionCodeUpdateRequest,
+} from "./adminPromotionCodesContracts.js";
+import { COMMERCE_CONTRACT_VERSION } from "../pricing/index.js";
+import type {
+  AgentDomainMutationSpec,
+  AgentDomainQuerySpec,
+} from "./adminBindings.js";
+import type { AuthorizeAdmin, PromotionAdminBindings } from "./adminBindings.js";
+import type { HttpRequest as VercelRequest, HttpResponse as VercelResponse } from "../http/index.js";
+import type { AdminPromotionCodesDataPort } from "./adminPromotionCodesDataPort.js";
+export interface AdminPromotionCodesHandlerDeps {
+  dataPort: AdminPromotionCodesDataPort;
+  authorizeAdmin: AuthorizeAdmin;
+  previewSecret: string;
+}
+
+export function createAdminPromotionCodesHandlers({ createAdminMutationHandler, createAdminParameterizedReadHandler, mapRpcError, DomainRpcError, resolveAdmin, sendBffError, sendBffSuccess, sendMethodNotAllowed, generatePromotionCode, normalizePromotionCode, previewPromotionCode, verifyPromotionPreviewProof }: Omit<PromotionAdminBindings, "createAdminReadHandler">) {
+/**
+ * The Promotion Code Center is a permanent part of the service, so these handlers are unconditional: the
+ * `enabled` / `flagName` / `disabledMessage` options of the admin-domain kit are
+ * omitted, which the kit reads as "always run the handler". The human-actor gate
+ * on create/update below is a security control, not rollout gating, and stays.
+ */
+const listSpec: AgentDomainQuerySpec<PromotionCodesListRequest> = {
+  key: "list",
+  requestSchema: promotionCodesListRequestSchema,
+  gate: "read",
+  allowedActorKinds: ["human", "machine"],
+};
+
+const createSpec: AgentDomainMutationSpec<PromotionCodeCreateRequest> = {
+  key: "create",
+  requestSchema: promotionCodeCreateRequestSchema,
+  gate: "mutation",
+  allowedActorKinds: ["human"],
+  lifecycleMarkers: [],
+};
+
+const updateSpec: AgentDomainMutationSpec<PromotionCodeUpdateRequest> = {
+  key: "update",
+  requestSchema: promotionCodeUpdateRequestSchema,
+  gate: "mutation",
+  allowedActorKinds: ["human"],
+  lifecycleMarkers: [],
+};
+
+function createAdminPromotionCodesListHandler(deps: AdminPromotionCodesHandlerDeps) {
+  return createAdminParameterizedReadHandler({
+    query: listSpec,
+    authorizeAdmin: deps.authorizeAdmin,
+    load: (actorId, input) => deps.dataPort.list(actorId, input),
+    toResponse: (result) => ({
+      contractVersion: COMMERCE_CONTRACT_VERSION,
+      ...result,
+      // Kept on the wire (constant `true`) so a browser bundle built before the
+      // rollout flags were retired still parses this response unchanged.
+      capabilities: { mutationsEnabled: true },
+    }),
+    responseSchema: promotionCodesListResponseSchema,
+    invalidRequestMessage: "Invalid promotion code list request",
+    invalidResponseMessage: "Invalid promotion code list response",
+    failureMessage: "Promotion code list failed",
+    mapError: mapPromotionCodeError,
+  });
+}
+
+function createAdminPromotionCodePreviewHandler(
+  deps: Pick<AdminPromotionCodesHandlerDeps, "authorizeAdmin" | "previewSecret">,
+) {
+  return async (req: VercelRequest, res: VercelResponse): Promise<void> => {
+    if (req.method !== "POST") return sendMethodNotAllowed(res, ["POST"]);
+    if (!(await resolveAdmin(deps.authorizeAdmin, res))) return;
+    const parsed = promotionCodePreviewRequestSchema.safeParse(req.body);
+    if (!parsed.success) {
+      sendBffError(res, "BAD_REQUEST", "Invalid promotion code preview request", {
+        details: parsed.error.flatten(),
+      });
+      return;
+    }
+    try {
+      const result = promotionCodePreviewResponseSchema.parse(
+        previewPromotionCode(parsed.data, deps.previewSecret),
+      );
+      sendBffSuccess(res, result);
+    } catch (error) {
+      mapPromotionCodeError(res, error, "Promotion code preview failed");
+    }
+  };
+}
+
+function createAdminPromotionCodeCreateHandler(deps: AdminPromotionCodesHandlerDeps) {
+  return createAdminMutationHandler({
+    mutation: createSpec,
+    authorizeAdmin: deps.authorizeAdmin,
+    invoke: async (actorId, request) => {
+      verifyActivationPreview(request, deps.previewSecret);
+      const resolvedCode = normalizePromotionCode(
+        request.code.kind === "automatic" ? generatePromotionCode() : request.code.value,
+      );
+      return deps.dataPort.create({
+        actorId,
+        request,
+        resolvedCode,
+        requestFingerprint: mutationFingerprint(request),
+      });
+    },
+    toResponse: (result) => ({ contractVersion: COMMERCE_CONTRACT_VERSION, ...result }),
+    responseSchema: promotionCodeCreateResponseSchema,
+    invalidRequestMessage: "Invalid promotion code create request",
+    invalidResponseMessage: "Invalid promotion code create response",
+    failureMessage: "Promotion code create failed",
+    mapError: mapPromotionCodeError,
+  });
+}
+
+function createAdminPromotionCodeUpdateHandler(deps: AdminPromotionCodesHandlerDeps) {
+  return createAdminMutationHandler({
+    mutation: updateSpec,
+    authorizeAdmin: deps.authorizeAdmin,
+    invoke: async (actorId, request) => {
+      await verifyUpdateLifecycle(deps.dataPort, actorId, request, deps.previewSecret);
+      return deps.dataPort.update({
+        actorId,
+        request,
+        requestFingerprint: mutationFingerprint(request),
+      });
+    },
+    toResponse: (result) => ({ contractVersion: COMMERCE_CONTRACT_VERSION, ...result }),
+    responseSchema: promotionCodeUpdateResponseSchema,
+    invalidRequestMessage: "Invalid promotion code update request",
+    invalidResponseMessage: "Invalid promotion code update response",
+    failureMessage: "Promotion code update failed",
+    mapError: mapPromotionCodeError,
+  });
+}
+
+function verifyActivationPreview(request: PromotionCodeCreateRequest, secret: string): void {
+  if (request.status !== "active") return;
+  if (!request.previewContext || !request.previewProof) {
+    throw new DomainRpcError("22023", "promotion_preview_required");
+  }
+  const previewInput: PromotionCodePreviewRequest = {
+    benefits: request.benefits,
+    scopes: request.scopes,
+    promotionEngineVersion: "promotion-engine.v2",
+    minimumReferenceMinor: request.minimumReferenceMinor,
+    context: request.previewContext,
+  };
+  previewPromotionCode(previewInput, secret);
+  if (!verifyPromotionPreviewProof(previewInput, request.previewProof, secret)) {
+    throw new DomainRpcError("22023", "promotion_preview_proof_mismatch");
+  }
+}
+
+async function verifyUpdateLifecycle(
+  dataPort: AdminPromotionCodesDataPort,
+  actorId: string,
+  request: PromotionCodeUpdateRequest,
+  secret: string,
+): Promise<void> {
+  const definition = await dataPort.definition(actorId, request.id);
+  if (definition.revision !== request.expectedRevision) {
+    // Let the transactional RPC decide between an idempotent replay (whose
+    // original revision is now stale by definition) and a genuine 409.
+    return;
+  }
+  const resultingValidFrom = request.updates.validFrom ?? definition.validFrom;
+  const resultingValidTo = request.updates.validTo === undefined
+    ? definition.validTo
+    : request.updates.validTo;
+  if (resultingValidTo !== null && Date.parse(resultingValidTo) <= Date.parse(resultingValidFrom)) {
+    throw new DomainRpcError("22023", "promotion_code_invalid_validity_window");
+  }
+  const beforeEffective = isEffectivelyActive(
+    definition.status,
+    definition.validFrom,
+    definition.validTo,
+  );
+  const afterEffective = isEffectivelyActive(
+    request.updates.status ?? definition.status,
+    resultingValidFrom,
+    resultingValidTo,
+  );
+  const transitionsToActiveStatus = definition.status !== "active"
+    && (request.updates.status ?? definition.status) === "active";
+  if (!transitionsToActiveStatus && (beforeEffective || !afterEffective)) return;
+  if (!request.previewContext || !request.previewProof) {
+    throw new DomainRpcError("22023", "promotion_preview_required");
+  }
+  const actualPreview = {
+    benefits: definition.benefits,
+    scopes: definition.scopes,
+    promotionEngineVersion: definition.promotionEngineVersion,
+    minimumReferenceMinor: definition.minimumReferenceMinor,
+    context: request.previewContext,
+  };
+  previewPromotionCode(actualPreview, secret);
+  if (!verifyPromotionPreviewProof(actualPreview, request.previewProof, secret)) {
+    throw new DomainRpcError("22023", "promotion_preview_proof_mismatch");
+  }
+}
+
+function isEffectivelyActive(
+  status: "draft" | "active" | "paused" | "archived",
+  validFrom: string,
+  validTo: string | null,
+  now = Date.now(),
+): boolean {
+  return status === "active"
+    && Date.parse(validFrom) <= now
+    && (validTo === null || Date.parse(validTo) > now);
+}
+
+function mapPromotionCodeError(
+  res: VercelResponse,
+  error: unknown,
+  failureMessage: string,
+): void {
+  if (error instanceof DomainRpcError && error.sqlstate === "22023") {
+    sendBffError(res, "BAD_REQUEST", error.pgMessage, {
+      details: { reason: error.pgMessage },
+    });
+    return;
+  }
+  if (error instanceof RangeError) {
+    sendBffError(res, "BAD_REQUEST", error.message, {
+      details: { reason: error.message },
+    });
+    return;
+  }
+  mapRpcError(res, error, failureMessage);
+}
+
+function mutationFingerprint(request: PromotionCodeCreateRequest | PromotionCodeUpdateRequest): string {
+  const sanitized = "code" in request && request.code.kind === "automatic"
+    ? { ...request, code: { kind: "automatic" } }
+    : request;
+  return createHash("sha256").update(JSON.stringify(sanitized)).digest("hex");
+}
+return { createAdminPromotionCodesListHandler, createAdminPromotionCodePreviewHandler, createAdminPromotionCodeCreateHandler, createAdminPromotionCodeUpdateHandler };
+}

package/src/promotions/adminPromotionsContracts.ts

@@ -0,0 +1,121 @@
+
+import { z } from "./validation.js";
+
+import {
+  PROMOTION_APPLIES_TO_KINDS,
+  PROMOTION_DISCOUNT_TYPES,
+  PROMOTION_STACKING_RULES,
+  PROMOTION_TRIGGER_TYPES,
+} from "@openlup/core/promo";
+
+import { COMMERCE_CONTRACT_VERSION } from "../pricing/index.js";
+
+/** Admin promotion schemas; raw adapter rows never cross this boundary. */
+
+
+export function createAdminPromotionSchemas({ currencySchema: platformCurrencySchema }: { currencySchema: z.ZodType<string> }) {
+const PROMOTION_STATUSES = ["draft", "active", "paused", "archived"] as const;
+
+const jsonObjectSchema = z.record(z.string(), z.unknown());
+
+const adminPromotionUnitTargetSchema = z.object({
+  variantId: z.string().min(1),
+  sku: z.string().nullable(),
+  referenceMinor: z.number().int().positive(),
+  targetMinor: z.number().int().nonnegative(),
+  currency: platformCurrencySchema,
+});
+
+const adminPromotionSemanticBenefitSchema = z.discriminatedUnion("kind", [
+  z.object({
+    kind: z.literal("target_percentage"),
+    valueBps: z.number().int().min(1).max(9_999),
+    reference: z.literal("catalog_list_price"),
+    unitTargets: z.array(adminPromotionUnitTargetSchema),
+  }),
+  z.object({
+    kind: z.literal("percentage"),
+    valuePercent: z.number().nonnegative(),
+  }),
+  z.object({
+    kind: z.literal("fixed_amount"),
+    valueMinor: z.number().nonnegative(),
+    currency: platformCurrencySchema,
+  }),
+  z.object({ kind: z.literal("free_shipping") }),
+  z.object({
+    kind: z.literal("unavailable"),
+    reason: z.literal("system_managed_metadata_incomplete"),
+  }),
+]);
+
+/**
+ * Engine-v2 mirror paired to a system-managed legacy row. Exposes only what the
+ * deliberate human-operator activation/pause control needs; mirror semantics stay read-only.
+ */
+const adminPromotionV2MirrorSchema = z.object({
+  id: z.string().min(1),
+  status: z.enum(PROMOTION_STATUSES),
+});
+
+/** One promotion as shown in the admin editor. */
+const adminPromotionSchema = z.object({
+  id: z.string().min(1),
+  code: z.string().nullable(),
+  name: z.string(),
+  triggerType: z.enum(PROMOTION_TRIGGER_TYPES),
+  discountType: z.enum(PROMOTION_DISCOUNT_TYPES),
+  semanticBenefit: adminPromotionSemanticBenefitSchema,
+  systemManaged: z.boolean(),
+  readOnly: z.boolean(),
+  v2Mirror: adminPromotionV2MirrorSchema.nullable(),
+  appliesToKind: z.enum(PROMOTION_APPLIES_TO_KINDS),
+  stackingRule: z.enum(PROMOTION_STACKING_RULES),
+  eligibility: jsonObjectSchema,
+  validFrom: z.string(),
+  validTo: z.string().nullable(),
+  status: z.enum(PROMOTION_STATUSES),
+  regionAvailability: z.array(z.string()),
+  redemptionLimitGlobal: z.number().nullable(),
+  redemptionLimitPerCustomer: z.number().nullable(),
+});
+
+const adminPromotionsListResponseSchema = z.object({
+  contractVersion: z.literal(COMMERCE_CONTRACT_VERSION),
+  promotions: z.array(adminPromotionSchema),
+});
+
+/** Editable fields. Trigger/discount type and code are fixed in v1 (edit, not recreate). */
+const adminPromotionUpdatePayloadSchema = z
+  .object({
+    name: z.string().trim().min(1).optional(),
+    discountValue: z.number().min(0).optional(),
+    stackingRule: z.enum(PROMOTION_STACKING_RULES).optional(),
+    status: z.enum(PROMOTION_STATUSES).optional(),
+    eligibility: jsonObjectSchema.optional(),
+    validFrom: z.string().optional(),
+    validTo: z.string().nullable().optional(),
+    redemptionLimitGlobal: z.number().int().positive().nullable().optional(),
+    redemptionLimitPerCustomer: z.number().int().positive().nullable().optional(),
+  })
+  .strict()
+  .refine((updates) => Object.values(updates).some((value) => value !== undefined), {
+    message: "At least one promotion field is required",
+  });
+
+const adminPromotionUpdateRequestSchema = z
+  .object({
+    id: z.string().trim().min(1),
+    updates: adminPromotionUpdatePayloadSchema,
+  })
+  .strict();
+
+const adminPromotionUpdateResponseSchema = z.object({
+  contractVersion: z.literal(COMMERCE_CONTRACT_VERSION),
+  updated: z.literal(true),
+  id: z.string().min(1),
+});
+
+
+return { PROMOTION_STATUSES, adminPromotionSemanticBenefitSchema, adminPromotionV2MirrorSchema, adminPromotionSchema, adminPromotionsListResponseSchema, adminPromotionUpdatePayloadSchema, adminPromotionUpdateRequestSchema, adminPromotionUpdateResponseSchema };
+}