@openlup/platform 0.16.0 → 0.18.0

package/dist/promotions/adminPromotionsContracts.d.ts

@@ -0,0 +1,235 @@
+import { z } from "./validation.js";
+/** Admin promotion schemas; raw adapter rows never cross this boundary. */
+export declare function createAdminPromotionSchemas({ currencySchema: platformCurrencySchema }: {
+    currencySchema: z.ZodType<string>;
+}): {
+    PROMOTION_STATUSES: readonly ["draft", "active", "paused", "archived"];
+    adminPromotionSemanticBenefitSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"target_percentage">;
+        valueBps: z.ZodNumber;
+        reference: z.ZodLiteral<"catalog_list_price">;
+        unitTargets: z.ZodArray<z.ZodObject<{
+            variantId: z.ZodString;
+            sku: z.ZodNullable<z.ZodString>;
+            referenceMinor: z.ZodNumber;
+            targetMinor: z.ZodNumber;
+            currency: z.ZodType<string, unknown, z.core.$ZodTypeInternals<string, unknown>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"percentage">;
+        valuePercent: z.ZodNumber;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"fixed_amount">;
+        valueMinor: z.ZodNumber;
+        currency: z.ZodType<string, unknown, z.core.$ZodTypeInternals<string, unknown>>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"free_shipping">;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"unavailable">;
+        reason: z.ZodLiteral<"system_managed_metadata_incomplete">;
+    }, z.core.$strip>], "kind">;
+    adminPromotionV2MirrorSchema: z.ZodObject<{
+        id: z.ZodString;
+        status: z.ZodEnum<{
+            draft: "draft";
+            active: "active";
+            archived: "archived";
+            paused: "paused";
+        }>;
+    }, z.core.$strip>;
+    adminPromotionSchema: z.ZodObject<{
+        id: z.ZodString;
+        code: z.ZodNullable<z.ZodString>;
+        name: z.ZodString;
+        triggerType: z.ZodEnum<{
+            automatic: "automatic";
+            coupon_code: "coupon_code";
+            referral: "referral";
+        }>;
+        discountType: z.ZodEnum<{
+            percentage: "percentage";
+            fixed_amount: "fixed_amount";
+            free_shipping: "free_shipping";
+        }>;
+        semanticBenefit: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"target_percentage">;
+            valueBps: z.ZodNumber;
+            reference: z.ZodLiteral<"catalog_list_price">;
+            unitTargets: z.ZodArray<z.ZodObject<{
+                variantId: z.ZodString;
+                sku: z.ZodNullable<z.ZodString>;
+                referenceMinor: z.ZodNumber;
+                targetMinor: z.ZodNumber;
+                currency: z.ZodType<string, unknown, z.core.$ZodTypeInternals<string, unknown>>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"percentage">;
+            valuePercent: z.ZodNumber;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"fixed_amount">;
+            valueMinor: z.ZodNumber;
+            currency: z.ZodType<string, unknown, z.core.$ZodTypeInternals<string, unknown>>;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"free_shipping">;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"unavailable">;
+            reason: z.ZodLiteral<"system_managed_metadata_incomplete">;
+        }, z.core.$strip>], "kind">;
+        systemManaged: z.ZodBoolean;
+        readOnly: z.ZodBoolean;
+        v2Mirror: z.ZodNullable<z.ZodObject<{
+            id: z.ZodString;
+            status: z.ZodEnum<{
+                draft: "draft";
+                active: "active";
+                archived: "archived";
+                paused: "paused";
+            }>;
+        }, z.core.$strip>>;
+        appliesToKind: z.ZodEnum<{
+            order_total: "order_total";
+            line_with_variant: "line_with_variant";
+            line_with_category: "line_with_category";
+        }>;
+        stackingRule: z.ZodEnum<{
+            exclusive: "exclusive";
+            stackable_with_any: "stackable_with_any";
+            stackable_with_loyalty: "stackable_with_loyalty";
+        }>;
+        eligibility: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        validFrom: z.ZodString;
+        validTo: z.ZodNullable<z.ZodString>;
+        status: z.ZodEnum<{
+            draft: "draft";
+            active: "active";
+            archived: "archived";
+            paused: "paused";
+        }>;
+        regionAvailability: z.ZodArray<z.ZodString>;
+        redemptionLimitGlobal: z.ZodNullable<z.ZodNumber>;
+        redemptionLimitPerCustomer: z.ZodNullable<z.ZodNumber>;
+    }, z.core.$strip>;
+    adminPromotionsListResponseSchema: z.ZodObject<{
+        contractVersion: z.ZodLiteral<"commerce.v0">;
+        promotions: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            code: z.ZodNullable<z.ZodString>;
+            name: z.ZodString;
+            triggerType: z.ZodEnum<{
+                automatic: "automatic";
+                coupon_code: "coupon_code";
+                referral: "referral";
+            }>;
+            discountType: z.ZodEnum<{
+                percentage: "percentage";
+                fixed_amount: "fixed_amount";
+                free_shipping: "free_shipping";
+            }>;
+            semanticBenefit: z.ZodDiscriminatedUnion<[z.ZodObject<{
+                kind: z.ZodLiteral<"target_percentage">;
+                valueBps: z.ZodNumber;
+                reference: z.ZodLiteral<"catalog_list_price">;
+                unitTargets: z.ZodArray<z.ZodObject<{
+                    variantId: z.ZodString;
+                    sku: z.ZodNullable<z.ZodString>;
+                    referenceMinor: z.ZodNumber;
+                    targetMinor: z.ZodNumber;
+                    currency: z.ZodType<string, unknown, z.core.$ZodTypeInternals<string, unknown>>;
+                }, z.core.$strip>>;
+            }, z.core.$strip>, z.ZodObject<{
+                kind: z.ZodLiteral<"percentage">;
+                valuePercent: z.ZodNumber;
+            }, z.core.$strip>, z.ZodObject<{
+                kind: z.ZodLiteral<"fixed_amount">;
+                valueMinor: z.ZodNumber;
+                currency: z.ZodType<string, unknown, z.core.$ZodTypeInternals<string, unknown>>;
+            }, z.core.$strip>, z.ZodObject<{
+                kind: z.ZodLiteral<"free_shipping">;
+            }, z.core.$strip>, z.ZodObject<{
+                kind: z.ZodLiteral<"unavailable">;
+                reason: z.ZodLiteral<"system_managed_metadata_incomplete">;
+            }, z.core.$strip>], "kind">;
+            systemManaged: z.ZodBoolean;
+            readOnly: z.ZodBoolean;
+            v2Mirror: z.ZodNullable<z.ZodObject<{
+                id: z.ZodString;
+                status: z.ZodEnum<{
+                    draft: "draft";
+                    active: "active";
+                    archived: "archived";
+                    paused: "paused";
+                }>;
+            }, z.core.$strip>>;
+            appliesToKind: z.ZodEnum<{
+                order_total: "order_total";
+                line_with_variant: "line_with_variant";
+                line_with_category: "line_with_category";
+            }>;
+            stackingRule: z.ZodEnum<{
+                exclusive: "exclusive";
+                stackable_with_any: "stackable_with_any";
+                stackable_with_loyalty: "stackable_with_loyalty";
+            }>;
+            eligibility: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+            validFrom: z.ZodString;
+            validTo: z.ZodNullable<z.ZodString>;
+            status: z.ZodEnum<{
+                draft: "draft";
+                active: "active";
+                archived: "archived";
+                paused: "paused";
+            }>;
+            regionAvailability: z.ZodArray<z.ZodString>;
+            redemptionLimitGlobal: z.ZodNullable<z.ZodNumber>;
+            redemptionLimitPerCustomer: z.ZodNullable<z.ZodNumber>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+    adminPromotionUpdatePayloadSchema: z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+        discountValue: z.ZodOptional<z.ZodNumber>;
+        stackingRule: z.ZodOptional<z.ZodEnum<{
+            exclusive: "exclusive";
+            stackable_with_any: "stackable_with_any";
+            stackable_with_loyalty: "stackable_with_loyalty";
+        }>>;
+        status: z.ZodOptional<z.ZodEnum<{
+            draft: "draft";
+            active: "active";
+            archived: "archived";
+            paused: "paused";
+        }>>;
+        eligibility: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        validFrom: z.ZodOptional<z.ZodString>;
+        validTo: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        redemptionLimitGlobal: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        redemptionLimitPerCustomer: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    }, z.core.$strict>;
+    adminPromotionUpdateRequestSchema: z.ZodObject<{
+        id: z.ZodString;
+        updates: z.ZodObject<{
+            name: z.ZodOptional<z.ZodString>;
+            discountValue: z.ZodOptional<z.ZodNumber>;
+            stackingRule: z.ZodOptional<z.ZodEnum<{
+                exclusive: "exclusive";
+                stackable_with_any: "stackable_with_any";
+                stackable_with_loyalty: "stackable_with_loyalty";
+            }>>;
+            status: z.ZodOptional<z.ZodEnum<{
+                draft: "draft";
+                active: "active";
+                archived: "archived";
+                paused: "paused";
+            }>>;
+            eligibility: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+            validFrom: z.ZodOptional<z.ZodString>;
+            validTo: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            redemptionLimitGlobal: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+            redemptionLimitPerCustomer: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        }, z.core.$strict>;
+    }, z.core.$strict>;
+    adminPromotionUpdateResponseSchema: z.ZodObject<{
+        contractVersion: z.ZodLiteral<"commerce.v0">;
+        updated: z.ZodLiteral<true>;
+        id: z.ZodString;
+    }, z.core.$strip>;
+};

package/dist/promotions/adminPromotionsContracts.js

@@ -0,0 +1,99 @@
+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 }) {
+    const PROMOTION_STATUSES = ["draft", "active", "paused", "archived"];
+    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/dist/promotions/adminPromotionsDataPort.d.ts

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

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

package/dist/promotions/adminPromotionsHandler.d.ts

@@ -0,0 +1,16 @@
+import type { createAdminPromotionSchemas } from "./adminPromotionsContracts.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 declare function createAdminPromotionsHandlers({ createAdminMutationHandler, createAdminReadHandler, mapRpcError }: Pick<PromotionAdminBindings, "createAdminMutationHandler" | "createAdminReadHandler" | "mapRpcError">, { adminPromotionUpdateRequestSchema, adminPromotionUpdateResponseSchema, adminPromotionsListResponseSchema }: Pick<ReturnType<typeof createAdminPromotionSchemas>, "adminPromotionUpdateRequestSchema" | "adminPromotionUpdateResponseSchema" | "adminPromotionsListResponseSchema">): {
+    createAdminPromotionsListHandler: ({ dataPort, authorizeAdmin, }: AdminPromotionsListHandlerDeps) => (req: import("../http/types.js").HttpRequest, res: import("../http/types.js").HttpResponse) => Promise<void>;
+    createAdminPromotionUpdateHandler: ({ dataPort, authorizeAdmin, }: AdminPromotionUpdateHandlerDeps) => (req: import("../http/types.js").HttpRequest, res: import("../http/types.js").HttpResponse) => Promise<void>;
+};

package/dist/promotions/adminPromotionsHandler.js

@@ -0,0 +1,47 @@
+/** @agent-domain-anti-reference Promotion compatibility harness; use the catalog reference for new admin domains. */
+import { COMMERCE_CONTRACT_VERSION } from "../pricing/index.js";
+export function createAdminPromotionsHandlers({ createAdminMutationHandler, createAdminReadHandler, mapRpcError }, { adminPromotionUpdateRequestSchema, adminPromotionUpdateResponseSchema, adminPromotionsListResponseSchema }) {
+    function createAdminPromotionsListHandler({ dataPort, authorizeAdmin, }) {
+        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 = {
+        key: "update",
+        requestSchema: adminPromotionUpdateRequestSchema,
+        gate: "mutation",
+        allowedActorKinds: ["human"],
+        lifecycleMarkers: [],
+    };
+    function createAdminPromotionUpdateHandler({ dataPort, authorizeAdmin, }) {
+        return createAdminMutationHandler({
+            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,
+                });
+                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 };
+}