@openlup/platform 0.26.0 → 0.28.0

package/dist/commerce/checkoutResumeSchemas.js

@@ -0,0 +1,145 @@
+import { z } from "zod";
+import { commerceIdempotencyKeySchema } from "./contractPrimitives.js";
+export const CHECKOUT_RESUME_CONTRACT_VERSION = "commerce.checkout_resume.v1";
+export const checkoutResumeTokenSchema = z.string().trim().min(43).max(128).regex(/^[A-Za-z0-9_-]+$/);
+export const checkoutResumeModeSchema = z.enum(["one_time", "subscription"]);
+export const checkoutResumeCompletionCoreSchema = z
+    .object({
+    productSelection: z.boolean().default(false),
+    cadence: z.boolean().default(false),
+    account: z.boolean().default(false),
+    shipping: z.boolean().default(false),
+    billing: z.boolean().default(false),
+    payment: z.boolean().default(false),
+    review: z.boolean().default(false),
+})
+    .strict();
+export function createCheckoutResumeSchemas(input) {
+    const checkoutResumeSectionIdSchema = input.sectionSchema;
+    const checkoutResumeRedactedFieldSchema = input.redactedFieldSchema;
+    const commerceProductSlugSchema = input.productSlugSchema;
+    const commerceSkuSchema = input.skuSchema;
+    const forbiddenKeys = new Set([...FORBIDDEN_RESUME_STATE_KEYS, ...(input.additionalForbiddenKeys ?? [])]);
+    const checkoutResumeDraftStateSchema = z
+        .object({
+        version: z.literal(CHECKOUT_RESUME_CONTRACT_VERSION),
+        mode: checkoutResumeModeSchema.nullable().default(null),
+        cadenceDays: z.number().int().positive().max(120).nullable().default(null),
+        cart: z
+            .object({
+            items: z
+                .array(z
+                .object({
+                sku: commerceSkuSchema,
+                productSlug: commerceProductSlugSchema.nullable().default(null),
+                variantId: z.string().trim().min(1).max(120).nullable().default(null),
+                quantity: z.number().int().positive().max(99),
+            })
+                .strict())
+                .max(50)
+                .default([]),
+        })
+            .strict()
+            .default({ items: [] }),
+        completion: input.completionSchema,
+        redactedFields: z.array(checkoutResumeRedactedFieldSchema).max(20).default([]),
+    })
+        .strict()
+        .superRefine((state, ctx) => {
+        if (state.mode !== "subscription" && state.cadenceDays !== null) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: "cadenceDays can only be set for subscription resume state",
+                path: ["cadenceDays"],
+            });
+        }
+        const piiPath = findForbiddenResumeStatePath(state, [], forbiddenKeys);
+        if (piiPath) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: "checkout resume draft state cannot include raw PII, address or payment fields",
+                path: piiPath,
+            });
+        }
+    });
+    const checkoutResumeUpsertRequestSchema = z
+        .object({
+        resumeToken: checkoutResumeTokenSchema.optional(),
+        idempotencyKey: commerceIdempotencyKeySchema.optional(),
+        lastSectionId: checkoutResumeSectionIdSchema,
+        draftState: checkoutResumeDraftStateSchema,
+        ttlMinutes: z.number().int().positive().max(10_080).default(120),
+    })
+        .strict();
+    const checkoutResumeReadRequestSchema = z
+        .object({
+        resumeToken: checkoutResumeTokenSchema,
+    })
+        .strict();
+    const checkoutResumeDraftSchema = z
+        .object({
+        id: z.guid(),
+        contractVersion: z.literal(CHECKOUT_RESUME_CONTRACT_VERSION),
+        lastSectionId: checkoutResumeSectionIdSchema,
+        draftState: checkoutResumeDraftStateSchema,
+        expiresAt: z.string().datetime({ offset: true }),
+        createdAt: z.string().datetime({ offset: true }),
+        updatedAt: z.string().datetime({ offset: true }),
+        replayed: z.boolean(),
+    })
+        .strict();
+    const checkoutResumeUpsertResponseSchema = z
+        .object({
+        contractVersion: z.literal(CHECKOUT_RESUME_CONTRACT_VERSION),
+        resumeToken: checkoutResumeTokenSchema,
+        draft: checkoutResumeDraftSchema,
+    })
+        .strict();
+    const checkoutResumeReadResponseSchema = z
+        .object({
+        contractVersion: z.literal(CHECKOUT_RESUME_CONTRACT_VERSION),
+        draft: checkoutResumeDraftSchema,
+    })
+        .strict();
+    return { checkoutResumeDraftStateSchema, checkoutResumeUpsertRequestSchema, checkoutResumeReadRequestSchema, checkoutResumeDraftSchema, checkoutResumeUpsertResponseSchema, checkoutResumeReadResponseSchema };
+}
+const FORBIDDEN_RESUME_STATE_KEYS = new Set([
+    "name",
+    "firstName",
+    "lastName",
+    "email",
+    "phone",
+    "street",
+    "postalCode",
+    "city",
+    "address",
+    "shippingAddress",
+    "billingAddress",
+    "deliveryNotes",
+    "courierInstructions",
+    "providerPayload",
+    "pspReference",
+    "paymentProvider",
+    "card",
+    "rawFormPayload",
+]);
+function findForbiddenResumeStatePath(value, path = [], forbiddenKeys = FORBIDDEN_RESUME_STATE_KEYS) {
+    if (!value || typeof value !== "object")
+        return null;
+    if (Array.isArray(value)) {
+        for (const [index, item] of value.entries()) {
+            const result = findForbiddenResumeStatePath(item, [...path, index], forbiddenKeys);
+            if (result)
+                return result;
+        }
+        return null;
+    }
+    for (const [key, nestedValue] of Object.entries(value)) {
+        if (forbiddenKeys.has(key))
+            return [...path, key];
+        const result = findForbiddenResumeStatePath(nestedValue, [...path, key], forbiddenKeys);
+        if (result)
+            return result;
+    }
+    return null;
+}

package/dist/commerce/checkoutSchemas.d.ts

@@ -0,0 +1,158 @@
+import { z } from "zod";
+export declare const CHECKOUT_CONTRACT_VERSION = "commerce.checkout.v2";
+export declare const checkoutKindSchema: z.ZodEnum<{
+    one_time: "one_time";
+    subscription_initial: "subscription_initial";
+}>;
+export declare const checkoutActivationStatusSchema: z.ZodEnum<{
+    not_applicable: "not_applicable";
+    pending_payment_success: "pending_payment_success";
+    activated: "activated";
+    blocked_missing_payment_method: "blocked_missing_payment_method";
+}>;
+export declare const ASYNC_CHECKOUT_STATUSES: readonly ["pending_provider_action", "requires_action", "processing", "paid", "failed", "expired"];
+export type AsyncCheckoutStatus = (typeof ASYNC_CHECKOUT_STATUSES)[number];
+export declare const asyncCheckoutStatusSchema: z.ZodEnum<{
+    requires_action: "requires_action";
+    failed: "failed";
+    paid: "paid";
+    expired: "expired";
+    processing: "processing";
+    pending_provider_action: "pending_provider_action";
+}>;
+export declare const subscriptionActivationStatusSchema: z.ZodEnum<{
+    active: "active";
+    action_required: "action_required";
+    not_applicable: "not_applicable";
+    waiting_for_mandate: "waiting_for_mandate";
+}>;
+export declare const invoiceBuyerSnapshotAddressCoreSchema: z.ZodObject<{
+    line1: z.ZodString;
+    line2: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    city: z.ZodString;
+    postalCode: z.ZodString;
+    country: z.ZodString;
+    source: z.ZodString;
+}, z.core.$strict>;
+export declare const checkoutRequestCoreSchema: z.ZodObject<{
+    paymentAttemptSequence: z.ZodOptional<z.ZodNumber>;
+    returnContext: z.ZodDefault<z.ZodEnum<{
+        account: "account";
+        public: "public";
+    }>>;
+}, z.core.$strict>;
+/** Host composes fiscal, action and acquisition schemas over neutral checkout fields. */
+export declare function createCheckoutResponseSchemas<Quote extends z.ZodType, Expectation extends z.ZodType, Action extends z.ZodType, IntentStatus extends z.ZodType<string>, AttemptStatus extends z.ZodType<string>, Display extends z.ZodType>(input: {
+    quoteSchema: Quote;
+    quoteExpectationSchema: Expectation;
+    clientActionSchema: Action;
+    paymentIntentStatusSchema: IntentStatus;
+    paymentAttemptStatusSchema: AttemptStatus;
+    failureDisplaySchema: Display;
+}): {
+    checkoutResponseSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        contractVersion: z.ZodLiteral<"commerce.checkout.v2">;
+        checkoutKind: z.ZodEnum<{
+            one_time: "one_time";
+            subscription_initial: "subscription_initial";
+        }>;
+        orderRef: z.ZodString;
+        orderId: z.ZodGUID;
+        status: z.ZodEnum<{
+            requires_action: "requires_action";
+            failed: "failed";
+            paid: "paid";
+            expired: "expired";
+            processing: "processing";
+            pending_provider_action: "pending_provider_action";
+        }>;
+        paymentIntentId: z.ZodOptional<z.ZodGUID>;
+        paymentAttemptId: z.ZodOptional<z.ZodNullable<z.ZodGUID>>;
+        providerPaymentId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        clientId: z.ZodOptional<z.ZodGUID>;
+        clientAction: z.ZodOptional<Action>;
+        returnUrl: z.ZodOptional<z.ZodString>;
+        statusUrl: z.ZodOptional<z.ZodString>;
+        subscription: z.ZodOptional<z.ZodObject<{
+            requested: z.ZodBoolean;
+            cadenceDays: z.ZodNullable<z.ZodNumber>;
+            activationStatus: z.ZodEnum<{
+                not_applicable: "not_applicable";
+                pending_payment_success: "pending_payment_success";
+                activated: "activated";
+                blocked_missing_payment_method: "blocked_missing_payment_method";
+            }>;
+        }, z.core.$strict>>;
+        payment: z.ZodOptional<z.ZodObject<{
+            requiresReusablePaymentMethod: z.ZodBoolean;
+        }, z.core.$strict>>;
+        authoritativeQuote: z.ZodOptional<Quote>;
+    }, z.core.$strict>, z.ZodObject<{
+        contractVersion: z.ZodLiteral<"commerce.checkout.v2">;
+        checkoutKind: z.ZodEnum<{
+            one_time: "one_time";
+            subscription_initial: "subscription_initial";
+        }>;
+        status: z.ZodLiteral<"price_changed">;
+        priceChanged: z.ZodLiteral<true>;
+        expectedQuote: Expectation;
+        authoritativeQuote: Quote;
+    }, z.core.$strict>], "status">;
+    paymentStatusRequestSchema: z.ZodObject<{
+        orderId: z.ZodGUID;
+        paymentIntentId: z.ZodGUID;
+        clientId: z.ZodGUID;
+    }, z.core.$strict>;
+    paymentStatusResponseSchema: z.ZodObject<{
+        contractVersion: z.ZodLiteral<"commerce.checkout.v2">;
+        orderId: z.ZodGUID;
+        paymentIntentId: z.ZodGUID;
+        status: z.ZodEnum<{
+            requires_action: "requires_action";
+            failed: "failed";
+            paid: "paid";
+            expired: "expired";
+            processing: "processing";
+            pending_provider_action: "pending_provider_action";
+        }>;
+        orderStatus: z.ZodString;
+        payment: z.ZodObject<{
+            intentStatus: IntentStatus;
+            attemptStatus: z.ZodNullable<AttemptStatus>;
+            paymentAttemptId: z.ZodNullable<z.ZodGUID>;
+            provider: z.ZodNullable<z.ZodString>;
+            providerPaymentId: z.ZodNullable<z.ZodString>;
+            updatedAt: z.ZodString;
+        }, z.core.$strict>;
+        failureReason: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        failureDisplay: z.ZodOptional<z.ZodNullable<Display>>;
+        subscriptionActivation: z.ZodObject<{
+            status: z.ZodEnum<{
+                active: "active";
+                action_required: "action_required";
+                not_applicable: "not_applicable";
+                waiting_for_mandate: "waiting_for_mandate";
+            }>;
+            subscriptionId: z.ZodNullable<z.ZodGUID>;
+        }, z.core.$strict>;
+        nextAction: z.ZodNullable<Action>;
+    }, z.core.$strict>;
+};
+/** Acquisition promises are compared independently of money. M05 owns their schemas. */
+export declare function createCheckoutQuoteSchemas<Money extends z.ZodType, Policy extends z.ZodType, Terms extends z.ZodType>(input: {
+    moneySchema: Money;
+    pricingPolicySchema: Policy;
+    acquisitionTermsExpectationSchema: Terms;
+}): {
+    checkoutQuoteExpectationSchema: z.ZodObject<{
+        totalGross: Money;
+        pricingPolicy: z.ZodOptional<Policy>;
+        acquisitionTerms: z.ZodOptional<Terms>;
+    }, z.core.$strict>;
+    checkoutQuoteAcceptanceSchema: z.ZodObject<{
+        totalGross: Money;
+        pricingPolicy: z.ZodOptional<Policy>;
+        acquisitionTerms: z.ZodOptional<Terms>;
+        promotionAcceptanceToken: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+};

package/dist/commerce/checkoutSchemas.js

@@ -0,0 +1,161 @@
+import { z } from "zod";
+export const CHECKOUT_CONTRACT_VERSION = "commerce.checkout.v2";
+const uuidSchema = z.guid();
+const datetimeSchema = z.string().datetime({ offset: true });
+export const checkoutKindSchema = z.enum(["one_time", "subscription_initial"]);
+export const checkoutActivationStatusSchema = z.enum([
+    "not_applicable",
+    "pending_payment_success",
+    "activated",
+    "blocked_missing_payment_method",
+]);
+export const ASYNC_CHECKOUT_STATUSES = [
+    "pending_provider_action",
+    "requires_action",
+    "processing",
+    "paid",
+    "failed",
+    "expired",
+];
+export const asyncCheckoutStatusSchema = z.enum(ASYNC_CHECKOUT_STATUSES);
+export const subscriptionActivationStatusSchema = z.enum(["not_applicable", "waiting_for_mandate", "active", "action_required"]);
+export const invoiceBuyerSnapshotAddressCoreSchema = z
+    .object({
+    line1: z.string().trim().min(3).max(160),
+    line2: z.string().trim().min(1).max(160).nullable().default(null),
+    city: z.string().trim().min(2).max(120),
+    postalCode: z.string().trim().min(3).max(16),
+    country: z.string().regex(/^[A-Z]{2}$/),
+    source: z.string().trim().min(1).max(120),
+})
+    .strict();
+export const checkoutRequestCoreSchema = z.object({
+    paymentAttemptSequence: z.number().int().min(0).max(50).optional(),
+    returnContext: z.enum(["public", "account"]).default("public"),
+}).strict();
+/** Host composes fiscal, action and acquisition schemas over neutral checkout fields. */
+export function createCheckoutResponseSchemas(input) {
+    const createQuoteResponseSchema = input.quoteSchema;
+    const checkoutClientActionSchema = input.clientActionSchema;
+    const paymentFailureDisplayReasonSchema = input.failureDisplaySchema;
+    const checkoutSuccessResponseSchema = z
+        .object({
+        contractVersion: z.literal(CHECKOUT_CONTRACT_VERSION),
+        checkoutKind: checkoutKindSchema,
+        orderRef: z.string().regex(/^order_[a-z0-9-]+$/),
+        orderId: uuidSchema,
+        status: asyncCheckoutStatusSchema,
+        paymentIntentId: uuidSchema.optional(),
+        paymentAttemptId: uuidSchema.nullable().optional(),
+        providerPaymentId: z.string().trim().min(1).nullable().optional(),
+        // Server-resolved customer identity used by owned payment and order reads.
+        clientId: uuidSchema.optional(),
+        clientAction: checkoutClientActionSchema.optional(),
+        returnUrl: z.string().url().optional(),
+        statusUrl: z.string().min(1).optional(),
+        subscription: z
+            .object({
+            requested: z.boolean(),
+            cadenceDays: z.number().int().positive().max(120).nullable(),
+            activationStatus: checkoutActivationStatusSchema,
+        })
+            .strict()
+            .optional(),
+        payment: z
+            .object({
+            requiresReusablePaymentMethod: z.boolean(),
+        })
+            .strict()
+            .optional(),
+        authoritativeQuote: createQuoteResponseSchema.optional(),
+    })
+        .strict()
+        .superRefine((response, ctx) => {
+        const subscription = response.subscription;
+        if (response.checkoutKind === "one_time") {
+            if (subscription && (subscription.requested || subscription.cadenceDays !== null || subscription.activationStatus !== "not_applicable")) {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    message: "one-time checkout cannot report requested subscription activation",
+                    path: ["subscription"],
+                });
+            }
+            return;
+        }
+        if (!subscription?.requested || !subscription.cadenceDays) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: "subscription checkout requires subscription response details",
+                path: ["subscription"],
+            });
+        }
+        if (response.payment?.requiresReusablePaymentMethod !== true) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: "subscription checkout requires reusable payment method",
+                path: ["payment", "requiresReusablePaymentMethod"],
+            });
+        }
+    });
+    const checkoutPriceChangedResponseSchema = z
+        .object({
+        contractVersion: z.literal(CHECKOUT_CONTRACT_VERSION),
+        checkoutKind: checkoutKindSchema,
+        status: z.literal("price_changed"),
+        priceChanged: z.literal(true),
+        expectedQuote: input.quoteExpectationSchema,
+        authoritativeQuote: createQuoteResponseSchema,
+    })
+        .strict();
+    const checkoutResponseSchema = z.discriminatedUnion("status", [
+        checkoutSuccessResponseSchema,
+        checkoutPriceChangedResponseSchema,
+    ]);
+    const paymentStatusRequestSchema = z
+        .object({
+        orderId: uuidSchema,
+        paymentIntentId: uuidSchema,
+        clientId: uuidSchema,
+    })
+        .strict();
+    const paymentStatusResponseSchema = z
+        .object({
+        contractVersion: z.literal(CHECKOUT_CONTRACT_VERSION),
+        orderId: uuidSchema,
+        paymentIntentId: uuidSchema,
+        status: asyncCheckoutStatusSchema,
+        orderStatus: z.string().trim().min(1),
+        payment: z
+            .object({
+            intentStatus: input.paymentIntentStatusSchema,
+            attemptStatus: input.paymentAttemptStatusSchema.nullable(),
+            paymentAttemptId: uuidSchema.nullable(),
+            provider: z.string().trim().min(1).nullable(),
+            providerPaymentId: z.string().trim().min(1).nullable(),
+            updatedAt: datetimeSchema,
+        })
+            .strict(),
+        /**
+         * Why the payment failed, as a stable code. Travels BESIDE `status`, never
+         * inside it: collapsing a reason into the status enum is what left every
+         * decline indistinguishable from every other in the first place.
+         */
+        failureReason: z.string().trim().min(1).max(240).nullable().default(null),
+        failureDisplay: paymentFailureDisplayReasonSchema.nullable().optional(),
+        subscriptionActivation: z.object({ status: subscriptionActivationStatusSchema, subscriptionId: uuidSchema.nullable() }).strict(),
+        nextAction: checkoutClientActionSchema.nullable(),
+    })
+        .strict();
+    return { checkoutResponseSchema, paymentStatusRequestSchema, paymentStatusResponseSchema };
+}
+/** Acquisition promises are compared independently of money. M05 owns their schemas. */
+export function createCheckoutQuoteSchemas(input) {
+    const checkoutQuoteExpectationSchema = z.object({
+        totalGross: input.moneySchema, pricingPolicy: input.pricingPolicySchema.optional(),
+        acquisitionTerms: input.acquisitionTermsExpectationSchema.optional(),
+    }).strict();
+    const checkoutQuoteAcceptanceSchema = checkoutQuoteExpectationSchema.extend({
+        promotionAcceptanceToken: z.string().min(1).max(8_300).optional(),
+    });
+    return { checkoutQuoteExpectationSchema, checkoutQuoteAcceptanceSchema };
+}

package/dist/commerce/commerceReturnsPort.d.ts

@@ -0,0 +1,97 @@
+import { z } from "zod";
+/** Returns request/approve/reject only. Restock and refund fields record intent; no receive, restock or refund execution. */
+export declare const returnRequestLineSchema: z.ZodObject<{
+    orderItemId: z.ZodGUID;
+    sku: z.ZodOptional<z.ZodString>;
+    quantity: z.ZodNumber;
+    restockDisposition: z.ZodOptional<z.ZodEnum<{
+        restock: "restock";
+        quarantine: "quarantine";
+        scrap: "scrap";
+    }>>;
+}, z.core.$strip>;
+/** Bind host reason codes for request/approve/reject only; restock/refund fields record intent, without execution. */
+export declare function createCommerceReturnsSchemas<const Reasons extends readonly [string, ...string[]]>(reasonCodes: Reasons): {
+    returnRequestCreateSchema: z.ZodObject<{
+        idempotencyKey: z.ZodString;
+        orderId: z.ZodGUID;
+        reasonCode: z.ZodEnum<{ [k_1 in Reasons[number]]: k_1; } extends infer T ? { [k in keyof T]: T[k]; } : never>;
+        lines: z.ZodArray<z.ZodObject<{
+            orderItemId: z.ZodGUID;
+            sku: z.ZodOptional<z.ZodString>;
+            quantity: z.ZodNumber;
+            restockDisposition: z.ZodOptional<z.ZodEnum<{
+                restock: "restock";
+                quarantine: "quarantine";
+                scrap: "scrap";
+            }>>;
+        }, z.core.$strip>>;
+        customerNote: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+};
+/** Neutral default reasons for request/approve/reject only; restock/refund fields record intent, without execution. */
+export declare const returnRequestCreateSchema: z.ZodObject<{
+    idempotencyKey: z.ZodString;
+    orderId: z.ZodGUID;
+    reasonCode: z.ZodEnum<{
+        damaged: "damaged";
+        other: "other";
+        wrong_item: "wrong_item";
+        not_as_described: "not_as_described";
+        changed_mind: "changed_mind";
+    }>;
+    lines: z.ZodArray<z.ZodObject<{
+        orderItemId: z.ZodGUID;
+        sku: z.ZodOptional<z.ZodString>;
+        quantity: z.ZodNumber;
+        restockDisposition: z.ZodOptional<z.ZodEnum<{
+            restock: "restock";
+            quarantine: "quarantine";
+            scrap: "scrap";
+        }>>;
+    }, z.core.$strip>>;
+    customerNote: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/** Returns request/approve/reject only. Restock and refund fields record intent; no receive, restock or refund execution. */
+export declare const returnApproveSchema: z.ZodObject<{
+    idempotencyKey: z.ZodString;
+    returnRequestId: z.ZodGUID;
+    refundMode: z.ZodDefault<z.ZodEnum<{
+        none: "none";
+        partial: "partial";
+        full: "full";
+    }>>;
+    refundAmountCents: z.ZodOptional<z.ZodNumber>;
+    adminNote: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/** Returns request/approve/reject only. Restock and refund fields record intent; no receive, restock or refund execution. */
+export declare const returnRejectSchema: z.ZodObject<{
+    idempotencyKey: z.ZodString;
+    returnRequestId: z.ZodGUID;
+    adminNote: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/** Returns request/approve/reject only. Restock and refund fields record intent; no receive, restock or refund execution. */
+export type ReturnRequestCreateInput<Reason extends string = z.infer<typeof returnRequestCreateSchema>["reasonCode"]> = Omit<z.infer<typeof returnRequestCreateSchema>, "reasonCode"> & {
+    reasonCode: Reason;
+    requestedBy?: string | null;
+};
+/** Returns request/approve/reject only. Restock and refund fields record intent; no receive, restock or refund execution. */
+export type ReturnApproveInput = z.infer<typeof returnApproveSchema> & {
+    actorUserId?: string | null;
+};
+/** Returns request/approve/reject only. Restock and refund fields record intent; no receive, restock or refund execution. */
+export type ReturnRejectInput = z.infer<typeof returnRejectSchema> & {
+    actorUserId?: string | null;
+};
+/** Returns request/approve/reject only. Restock and refund fields record intent; no receive, restock or refund execution. */
+export interface ReturnLifecycleResult {
+    returnRequestId: string;
+    status: string;
+    replayed: boolean;
+}
+/** Returns request/approve/reject only. Restock and refund fields record intent; no receive, restock or refund execution. */
+export interface CommerceReturnsPort<Reason extends string = ReturnRequestCreateInput["reasonCode"]> {
+    createRequest(input: ReturnRequestCreateInput<Reason>): Promise<ReturnLifecycleResult>;
+    approve(input: ReturnApproveInput): Promise<ReturnLifecycleResult>;
+    reject(input: ReturnRejectInput): Promise<ReturnLifecycleResult>;
+}

package/dist/commerce/commerceReturnsPort.js

@@ -0,0 +1,39 @@
+// Provider-neutral Commerce Returns contracts and validation.
+import { z } from "zod";
+/** Returns request/approve/reject only. Restock and refund fields record intent; no receive, restock or refund execution. */
+export const returnRequestLineSchema = z.object({
+    orderItemId: z.guid(),
+    sku: z.string().trim().min(1).max(120).optional(),
+    quantity: z.number().int().positive(),
+    restockDisposition: z.enum(["restock", "quarantine", "scrap"]).optional(),
+});
+/** Bind host reason codes for request/approve/reject only; restock/refund fields record intent, without execution. */
+export function createCommerceReturnsSchemas(reasonCodes) {
+    return {
+        returnRequestCreateSchema: z.object({
+            idempotencyKey: z.string().trim().min(8).max(200),
+            orderId: z.guid(),
+            reasonCode: z.enum(reasonCodes),
+            lines: z.array(returnRequestLineSchema).min(1),
+            customerNote: z.string().trim().max(2000).optional(),
+        }),
+    };
+}
+/** Neutral default reasons for request/approve/reject only; restock/refund fields record intent, without execution. */
+export const { returnRequestCreateSchema } = createCommerceReturnsSchemas([
+    "damaged", "wrong_item", "not_as_described", "changed_mind", "other",
+]);
+/** Returns request/approve/reject only. Restock and refund fields record intent; no receive, restock or refund execution. */
+export const returnApproveSchema = z.object({
+    idempotencyKey: z.string().trim().min(8).max(200),
+    returnRequestId: z.guid(),
+    refundMode: z.enum(["full", "partial", "none"]).default("full"),
+    refundAmountCents: z.number().int().nonnegative().optional(),
+    adminNote: z.string().trim().max(2000).optional(),
+});
+/** Returns request/approve/reject only. Restock and refund fields record intent; no receive, restock or refund execution. */
+export const returnRejectSchema = z.object({
+    idempotencyKey: z.string().trim().min(8).max(200),
+    returnRequestId: z.guid(),
+    adminNote: z.string().trim().max(2000).optional(),
+});

package/dist/commerce/configuratorIntentPersistenceSchemas.d.ts

@@ -0,0 +1,20 @@
+import { z } from "zod";
+export declare const CONFIGURATOR_INTENT_PERSISTENCE_CONTRACT_VERSION = "commerce.configurator_intent_persistence.v1";
+export declare const configuratorIntentClientMatchReasonSchema: z.ZodEnum<{
+    client_created: "client_created";
+    client_match_exact_email: "client_match_exact_email";
+    client_match_plus_normalized_fallback: "client_match_plus_normalized_fallback";
+}>;
+export declare const configuratorIntentPersistenceResponseCoreSchema: z.ZodObject<{
+    contractVersion: z.ZodLiteral<"commerce.configurator_intent_persistence.v1">;
+    intentVersion: z.ZodLiteral<"commerce.configurator_intent.v1">;
+    idempotencyKey: z.ZodString;
+    clientId: z.ZodGUID;
+    addressId: z.ZodGUID;
+    clientMatchReason: z.ZodOptional<z.ZodEnum<{
+        client_created: "client_created";
+        client_match_exact_email: "client_match_exact_email";
+        client_match_plus_normalized_fallback: "client_match_plus_normalized_fallback";
+    }>>;
+    replayed: z.ZodBoolean;
+}, z.core.$strict>;

package/dist/commerce/configuratorIntentPersistenceSchemas.js

@@ -0,0 +1,21 @@
+import { z } from "zod";
+import { CONFIGURATOR_INTENT_VERSION } from "./configuratorIntentSchemas.js";
+export const CONFIGURATOR_INTENT_PERSISTENCE_CONTRACT_VERSION = "commerce.configurator_intent_persistence.v1";
+const uuidSchema = z.guid();
+export const configuratorIntentClientMatchReasonSchema = z.enum([
+    "client_created",
+    "client_match_exact_email",
+    // Historical replay value; current writers need not emit it.
+    "client_match_plus_normalized_fallback",
+]);
+export const configuratorIntentPersistenceResponseCoreSchema = z
+    .object({
+    contractVersion: z.literal(CONFIGURATOR_INTENT_PERSISTENCE_CONTRACT_VERSION),
+    intentVersion: z.literal(CONFIGURATOR_INTENT_VERSION),
+    idempotencyKey: z.string().trim().min(8).max(120),
+    clientId: uuidSchema,
+    addressId: uuidSchema,
+    clientMatchReason: configuratorIntentClientMatchReasonSchema.optional(),
+    replayed: z.boolean(),
+})
+    .strict();