@openlup/platform 0.17.0 → 0.18.0

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 };
+}

package/src/promotions/adminPromotionsDataPort.ts

@@ -0,0 +1,48 @@
+import type {
+  AdminPromotion,
+  AdminPromotionUpdatePayload,
+  AdminSubscriptionBandEntry,
+} from "./contracts/index.js";
+
+/**
+ * @agent-domain-anti-reference
+ * NOT THE REFERENCE — Promotions back-compat harness port (see
+ * `adminPromotionsHandler.ts`); copy the catalog `@agent-domain-reference` port.
+ *
+ * Server-side data access for the admin discounts editor. The
+ * host must provide promotion updates and atomic subscription-band writes.
+ * Promotion-edit audit recording is required: an audit failure must surface
+ * rather than silently turn into a successful unaudited edit.
+ */
+
+export interface AdminPromotionsAuditEntry {
+  actorId: string;
+  actorEmail: string | null;
+  action: "promo_update" | "promo_status_change" | "shipping_rate_change";
+  promotionId: string;
+  newValue: Record<string, unknown>;
+}
+
+export interface AdminPromotionsDataPort {
+  listPromotions(): Promise<AdminPromotion[]>;
+  updatePromotion(id: string, updates: AdminPromotionUpdatePayload): Promise<void>;
+  listSubscriptionBand(): Promise<AdminSubscriptionBandEntry[]>;
+  setSubscriptionBandPercent(
+    percent: number,
+  ): Promise<{ updatedSkuCount: number; appliedPercent: number }>;
+  /** Flat shipping rate (gross minor units) from host settings; 0 when unset. */
+  getShippingFlatMinor(): Promise<number>;
+  /** Upsert the flat shipping rate (gross minor units). */
+  setShippingFlatMinor(minor: number): Promise<void>;
+  /**
+   * Set a SKU's one-time (list) price across the active price list via the
+   * host's append-only atomic writer. Subscription prices are untouched
+   * (re-apply the band to recompute them). The writer records its own audit row.
+   */
+  setCatalogPrice(input: {
+    actorId: string;
+    sku: string;
+    unitPriceMinor: number;
+  }): Promise<void>;
+  recordPromotionAudit(entry: AdminPromotionsAuditEntry): Promise<void>;
+}

package/src/promotions/adminPromotionsHandler.ts

@@ -0,0 +1,72 @@
+/** @agent-domain-anti-reference Promotion compatibility harness; use the catalog reference for new admin domains. */
+import { COMMERCE_CONTRACT_VERSION } from "../pricing/index.js";
+import type { createAdminPromotionSchemas } from "./adminPromotionsContracts.js";
+import type { AdminPromotionUpdateRequest } from "./contracts/index.js";
+import type { AgentDomainMutationSpec } from "./adminBindings.js";
+import type { AuthorizeAdmin, PromotionAdminBindings } from "./adminBindings.js";
+import type { AdminPromotionsDataPort } from "./adminPromotionsDataPort.js";
+/** Human-admin promotion edits retain the required audit and the existing non-atomic update boundary. */
+
+export interface AdminPromotionsListHandlerDeps {
+  dataPort: AdminPromotionsDataPort;
+  authorizeAdmin: AuthorizeAdmin;
+}
+export interface AdminPromotionUpdateHandlerDeps {
+  dataPort: AdminPromotionsDataPort;
+  authorizeAdmin: AuthorizeAdmin;
+}
+
+export function createAdminPromotionsHandlers({ createAdminMutationHandler, createAdminReadHandler, mapRpcError }: Pick<PromotionAdminBindings, "createAdminMutationHandler" | "createAdminReadHandler" | "mapRpcError">, { adminPromotionUpdateRequestSchema, adminPromotionUpdateResponseSchema, adminPromotionsListResponseSchema }: Pick<ReturnType<typeof createAdminPromotionSchemas>, "adminPromotionUpdateRequestSchema" | "adminPromotionUpdateResponseSchema" | "adminPromotionsListResponseSchema">) {
+function createAdminPromotionsListHandler({
+  dataPort,
+  authorizeAdmin,
+}: AdminPromotionsListHandlerDeps) {
+  return createAdminReadHandler({
+    authorizeAdmin,
+    load: () => dataPort.listPromotions(),
+    toResponse: (promotions) => ({ contractVersion: COMMERCE_CONTRACT_VERSION, promotions }),
+    responseSchema: adminPromotionsListResponseSchema,
+    invalidResponseMessage: "Admin promotions list returned invalid response",
+    failureMessage: "Admin promotions list failed",
+  });
+}
+
+const promotionUpdateMutation: AgentDomainMutationSpec<AdminPromotionUpdateRequest> = {
+  key: "update",
+  requestSchema: adminPromotionUpdateRequestSchema,
+  gate: "mutation",
+  allowedActorKinds: ["human"],
+  lifecycleMarkers: [],
+};
+
+function createAdminPromotionUpdateHandler({
+  dataPort,
+  authorizeAdmin,
+}: AdminPromotionUpdateHandlerDeps) {
+  return createAdminMutationHandler<AdminPromotionUpdateRequest, { id: string }>({
+    mutation: promotionUpdateMutation,
+    authorizeAdmin,
+    invoke: async (actorId, input) => {
+      await dataPort.updatePromotion(input.id, input.updates);
+      const action =
+        input.updates.status !== undefined ? "promo_status_change" : "promo_update";
+      // Required, non-repudiable audit via the fn — no longer best-effort/swallowed.
+      await dataPort.recordPromotionAudit({
+        actorId,
+        actorEmail: null,
+        action,
+        promotionId: input.id,
+        newValue: input.updates as Record<string, unknown>,
+      });
+      return { id: input.id };
+    },
+    toResponse: ({ id }) => ({ contractVersion: COMMERCE_CONTRACT_VERSION, updated: true, id }),
+    responseSchema: adminPromotionUpdateResponseSchema,
+    invalidResponseMessage: "Admin promotion update returned invalid response",
+    invalidRequestMessage: "Invalid promotion update request",
+    failureMessage: "Admin promotion update failed",
+    mapError: mapRpcError,
+  });
+}
+return { createAdminPromotionsListHandler, createAdminPromotionUpdateHandler };
+}