@openlup/platform 0.17.0 → 0.18.0

package/dist/promotions/adminPromotionCodesContracts.js

@@ -0,0 +1,211 @@
+import { z } from "./validation.js";
+import { COMMERCE_CONTRACT_VERSION } from "../pricing/index.js";
+export const PROMOTION_CODE_STATUSES = ["draft", "active", "paused", "archived"];
+export const PROMOTION_CODE_EFFECTIVE_STATUSES = [
+    "active",
+    "draft",
+    "paused",
+    "scheduled",
+    "expired",
+    "archived",
+];
+export const PROMOTION_CODE_STATUS_FILTERS = [
+    ...PROMOTION_CODE_EFFECTIVE_STATUSES,
+    "expired_or_archived",
+];
+export const PROMOTION_CODE_SCOPES = ["one_time", "subscription_initial"];
+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(),
+});

package/dist/promotions/adminPromotionCodesDataPort.d.ts

@@ -0,0 +1,47 @@
+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/dist/promotions/adminPromotionCodesDataPort.js

@@ -0,0 +1 @@
+export {};

package/dist/promotions/adminPromotionCodesHandler.d.ts

@@ -0,0 +1,14 @@
+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 declare function createAdminPromotionCodesHandlers({ createAdminMutationHandler, createAdminParameterizedReadHandler, mapRpcError, DomainRpcError, resolveAdmin, sendBffError, sendBffSuccess, sendMethodNotAllowed, generatePromotionCode, normalizePromotionCode, previewPromotionCode, verifyPromotionPreviewProof }: Omit<PromotionAdminBindings, "createAdminReadHandler">): {
+    createAdminPromotionCodesListHandler: (deps: AdminPromotionCodesHandlerDeps) => (req: VercelRequest, res: VercelResponse) => Promise<void>;
+    createAdminPromotionCodePreviewHandler: (deps: Pick<AdminPromotionCodesHandlerDeps, "authorizeAdmin" | "previewSecret">) => (req: VercelRequest, res: VercelResponse) => Promise<void>;
+    createAdminPromotionCodeCreateHandler: (deps: AdminPromotionCodesHandlerDeps) => (req: VercelRequest, res: VercelResponse) => Promise<void>;
+    createAdminPromotionCodeUpdateHandler: (deps: AdminPromotionCodesHandlerDeps) => (req: VercelRequest, res: VercelResponse) => Promise<void>;
+};

package/dist/promotions/adminPromotionCodesHandler.js

@@ -0,0 +1,194 @@
+import { createHash } from "node:crypto";
+import { promotionCodeCreateRequestSchema, promotionCodeCreateResponseSchema, promotionCodePreviewRequestSchema, promotionCodePreviewResponseSchema, promotionCodesListRequestSchema, promotionCodesListResponseSchema, promotionCodeUpdateRequestSchema, promotionCodeUpdateResponseSchema, } from "./adminPromotionCodesContracts.js";
+import { COMMERCE_CONTRACT_VERSION } from "../pricing/index.js";
+export function createAdminPromotionCodesHandlers({ createAdminMutationHandler, createAdminParameterizedReadHandler, mapRpcError, DomainRpcError, resolveAdmin, sendBffError, sendBffSuccess, sendMethodNotAllowed, generatePromotionCode, normalizePromotionCode, previewPromotionCode, verifyPromotionPreviewProof }) {
+    /**
+     * 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 = {
+        key: "list",
+        requestSchema: promotionCodesListRequestSchema,
+        gate: "read",
+        allowedActorKinds: ["human", "machine"],
+    };
+    const createSpec = {
+        key: "create",
+        requestSchema: promotionCodeCreateRequestSchema,
+        gate: "mutation",
+        allowedActorKinds: ["human"],
+        lifecycleMarkers: [],
+    };
+    const updateSpec = {
+        key: "update",
+        requestSchema: promotionCodeUpdateRequestSchema,
+        gate: "mutation",
+        allowedActorKinds: ["human"],
+        lifecycleMarkers: [],
+    };
+    function createAdminPromotionCodesListHandler(deps) {
+        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) {
+        return async (req, res) => {
+            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) {
+        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) {
+        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, secret) {
+        if (request.status !== "active")
+            return;
+        if (!request.previewContext || !request.previewProof) {
+            throw new DomainRpcError("22023", "promotion_preview_required");
+        }
+        const previewInput = {
+            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, actorId, request, secret) {
+        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, validFrom, validTo, now = Date.now()) {
+        return status === "active"
+            && Date.parse(validFrom) <= now
+            && (validTo === null || Date.parse(validTo) > now);
+    }
+    function mapPromotionCodeError(res, error, failureMessage) {
+        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) {
+        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 };
+}