@openlup/platform 0.26.0 → 0.28.0

package/src/commerce/checkoutSchemas.ts

@@ -0,0 +1,182 @@
+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",
+] as const;
+export type AsyncCheckoutStatus = (typeof ASYNC_CHECKOUT_STATUSES)[number];
+
+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<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;
+}) {
+  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<Money extends z.ZodType, Policy extends z.ZodType, Terms extends z.ZodType>(input: {
+  moneySchema: Money; pricingPolicySchema: Policy; acquisitionTermsExpectationSchema: Terms;
+}) {
+  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/src/commerce/commerceReturnsPort.ts

@@ -0,0 +1,67 @@
+// 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<const Reasons extends readonly [string, ...string[]]>(reasonCodes: Reasons) {
+  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(),
+});
+
+/** 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/src/commerce/configuratorIntentPersistenceSchemas.ts

@@ -0,0 +1,26 @@
+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();

package/src/commerce/configuratorIntentSchemas.ts

@@ -0,0 +1,47 @@
+import { z } from "zod";
+import { commerceIdempotencyKeySchema, commerceMinimumUnits, commerceMinimumUnitsSchema, commerceOfferVersionSchema } from "./contractPrimitives.js";
+export const CONFIGURATOR_INTENT_VERSION = "commerce.configurator_intent.v1";
+export const configuratorModeSchema = z.enum(["one_time", "subscription"]);
+export const configuratorContactSchema = z.object({
+  firstName: z.string().trim().min(1).max(80), lastName: z.string().trim().min(1).max(80),
+  email: z.string().trim().email().max(160), phone: z.string().trim().min(6).max(32),
+}).strict();
+export const configuratorAddressCoreSchema = z.object({
+  street: z.string().trim().min(3).max(160), postalCode: z.string().trim().min(3).max(16),
+  city: z.string().trim().min(2).max(120), country: z.string().regex(/^[A-Z]{2}$/),
+}).strict();
+export function createConfiguratorIntentSchemas(skuSchema: z.ZodType<string, string>) {
+  const configuratorVariantCoreSchema = z.object({
+    variantId: z.string().trim().min(1).max(120),
+    sku: skuSchema,
+    qty: z.number().int().positive().max(99),
+  }).strict();
+  const configuratorIntentCoreSchema = z.object({
+    version: z.literal(CONFIGURATOR_INTENT_VERSION),
+    idempotencyKey: commerceIdempotencyKeySchema,
+    mode: configuratorModeSchema,
+    cadenceDays: z.number().int().positive().max(120).nullable().default(null),
+    promoCodes: z.array(z.string().trim().min(1).max(80)).max(20).default([]),
+    visitorId: z.string().trim().min(1).max(120).optional(),
+    contact: configuratorContactSchema,
+    address: configuratorAddressCoreSchema,
+    selectedVariants: z.array(configuratorVariantCoreSchema).min(1).max(50),
+    offerVersion: commerceOfferVersionSchema.optional(),
+    minimumUnits: commerceMinimumUnitsSchema.optional(),
+  }).strict();
+  return { configuratorVariantCoreSchema, configuratorIntentCoreSchema };
+}
+
+export function validateConfiguratorIntentCore(intent: {
+  mode: "one_time" | "subscription"; cadenceDays: number | null; minimumUnits?: number;
+  selectedVariants: readonly { qty: number }[];
+}, ctx: z.RefinementCtx, defaultMinimumUnits: number): void {
+  if (intent.mode === "subscription" && !intent.cadenceDays) {
+    ctx.addIssue({ code: z.ZodIssueCode.custom, message: "subscription intent requires cadenceDays", path: ["cadenceDays"] });
+  }
+  const selectedUnitCount = intent.selectedVariants.reduce((total, variant) => total + variant.qty, 0);
+  const minimumUnits = commerceMinimumUnits(intent, defaultMinimumUnits);
+  if (selectedUnitCount < minimumUnits) {
+    ctx.addIssue({ code: z.ZodIssueCode.custom, message: `selected variants require at least ${minimumUnits} total units`, path: ["selectedVariants"] });
+  }
+}

package/src/commerce/contractPrimitives.ts

@@ -0,0 +1,30 @@
+import { z } from "zod";
+import { CART_STATUSES, CHECKOUT_STATUSES, ORDER_DRAFT_STATUSES, ORDER_STATUSES, PAYMENT_STATUSES } from "./contracts/state.js";
+
+export const cartStatusSchema = z.enum(CART_STATUSES);
+export const checkoutStatusSchema = z.enum(CHECKOUT_STATUSES);
+export const orderDraftStatusSchema = z.enum(ORDER_DRAFT_STATUSES);
+export const orderStatusSchema = z.enum(ORDER_STATUSES);
+export const paymentStatusSchema = z.enum(PAYMENT_STATUSES);
+export const commerceIdempotencyKeySchema = z
+  .string()
+  .trim()
+  .min(8)
+  .max(120)
+  .regex(/^[a-zA-Z0-9._:-]+$/);
+
+
+/** Hosts add their own sizing kinds and profile fields. */
+export const commerceSizeConstraintCoreSchema = z.object({
+  kind: z.enum(["unit_count", "total_weight_g"]),
+  value: z.number().int().positive(),
+}).strict();
+
+/** Opaque offer tokens are transported, never interpreted by commerce. */
+export const commerceOfferVersionSchema = z.string().max(40).regex(/^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)*$/);
+export const commerceMinimumUnitsSchema = z.number().int().min(1).max(99);
+
+/** Client asks do not establish trusted checkout admission. */
+export function commerceMinimumUnits(input: { minimumUnits?: number | null }, defaultMinimumUnits: number): number {
+  return input.minimumUnits ?? defaultMinimumUnits;
+}

package/src/commerce/contracts/availability.ts

@@ -0,0 +1,21 @@
+export type CommerceOfferAvailabilityStatus = "available" | "low_stock" | "out_of_stock" | "unknown";
+export interface CommerceOfferAvailabilityRequestItem {
+  sku: string;
+  productSlug: string;
+  variantId: string;
+  requestedQuantity: number;
+  checkoutMode: "one_time" | "subscription";
+}
+export interface CommerceOfferAvailability {
+  sku: string;
+  productSlug: string;
+  variantId: string;
+  status: CommerceOfferAvailabilityStatus;
+  visibleInConfigurator: boolean;
+  sellableNow: number | null;
+  reasonCode: string;
+  source: string;
+}
+export interface CommerceOfferAvailabilityPort {
+  getAvailability(input: { items: readonly CommerceOfferAvailabilityRequestItem[] }): Promise<CommerceOfferAvailability[]>;
+}

package/src/commerce/contracts/fulfillmentRecovery.ts

@@ -0,0 +1,26 @@
+// Commerce fulfillment recovery evidence shared by OMS reads and host projections.
+export type TimedFulfillmentSignal = {
+    id?: undefined | null | string;
+    token: undefined | null | string;
+    occurredAt: undefined | null | string;
+};
+export type ReleasedProviderExceptionHold = {
+    orderId: undefined | null | string;
+    status: undefined | null | string;
+    reason: undefined | null | string;
+    createdBy: undefined | null | string;
+    releasedBy: undefined | null | string;
+    metadata: unknown;
+};
+export type ProviderStatusEvidence = {
+    fulfillmentOrderId: undefined | null | string;
+    providerStatus: undefined | null | string;
+    localStatus: undefined | null | string;
+    id?: undefined | null | string;
+    token: undefined | null | string;
+    occurredAt: undefined | null | string;
+};
+export type ResolvedProviderExceptionRecovery = {
+    clearedExceptionEvidenceIds: ReadonlySet<string>;
+    recoveryEvidenceIds: ReadonlySet<string>;
+};

package/src/commerce/contracts/index.ts

@@ -0,0 +1,17 @@
+export type { CommerceOfferAvailabilityStatus, CommerceOfferAvailabilityRequestItem, CommerceOfferAvailability, CommerceOfferAvailabilityPort } from "./availability.js";
+export type { RecoveryDestinationIntent, RecoveryDestinationPolicyInput, RecoveryDestinationSource, RecoveryDestinationState } from "./recovery.js";
+export type { CommerceFulfillmentEligibilityInput, CartStatus, CheckoutStatus, OrderDraftStatus, OrderStatus, PaymentStatus, OmsFulfillmentBlockReason, OmsInventoryStatus } from "./state.js";
+export type { CartDraft, CheckoutSessionPlaceholder, OrderDraftSummary, OrderSummary, PaymentSummary } from "./order.js";
+export type AsyncCheckoutStatus = "pending_provider_action" | "requires_action" | "processing" | "paid" | "failed" | "expired";
+export type CheckoutKind = "one_time" | "subscription_initial";
+export type * from "./ports.js";
+export type * from "./runtimePorts.js";
+export type { ConfiguratorIntent, ConfiguratorIntentPersistenceResponse, CheckoutResumeDraftState, CheckoutResumeDraft, CommerceCustomerDefaultsSnapshot } from "./intent.js";
+export type * from "./orderMoney.js";
+export type { OmsPaymentStatus } from "./state.js";
+
+// Shared fulfillment recovery DTOs.
+export type * from "./fulfillmentRecovery.js";
+
+// M11 K3a OMS browser-safe DTOs and ports; no imports from runtime schema modules.
+export type * from "./omsTypes.js";

package/src/commerce/contracts/intent.ts

@@ -0,0 +1,58 @@
+/** Neutral configurator state. Profiles, sizing policy and provider evidence are host extensions. */
+export interface ConfiguratorIntent {
+  version: "commerce.configurator_intent.v1";
+  idempotencyKey: string;
+  mode: "one_time" | "subscription";
+  cadenceDays: number | null;
+  promoCodes: string[];
+  visitorId?: string;
+  contact: { firstName: string; lastName: string; email: string; phone: string };
+  address: { street: string; postalCode: string; city: string; country: string };
+  selectedVariants: Array<{ variantId: string; sku: string; qty: number }>;
+  offerVersion?: string;
+  minimumUnits?: number;
+}
+
+export interface ConfiguratorIntentPersistenceResponse {
+  contractVersion: "commerce.configurator_intent_persistence.v1";
+  intentVersion: "commerce.configurator_intent.v1";
+  idempotencyKey: string;
+  clientId: string;
+  addressId: string;
+  clientMatchReason?: "client_created" | "client_match_exact_email" | "client_match_plus_normalized_fallback";
+  replayed: boolean;
+}
+
+export interface CheckoutResumeDraftState<Completion, RedactedField extends string> {
+  version: "commerce.checkout_resume.v1";
+  mode: "one_time" | "subscription" | null;
+  cadenceDays: number | null;
+  cart: { items: Array<{ sku: string; productSlug: string | null; variantId: string | null; quantity: number }> };
+  completion: Completion;
+  redactedFields: RedactedField[];
+}
+
+export interface CheckoutResumeDraft<Section extends string, State> {
+  id: string;
+  contractVersion: "commerce.checkout_resume.v1";
+  lastSectionId: Section;
+  draftState: State;
+  expiresAt: string;
+  createdAt: string;
+  updatedAt: string;
+  replayed: boolean;
+}
+
+export interface CommerceCustomerDefaultsSnapshot<Scope, Method> {
+  version: "commerce.customer_defaults_snapshot.v1";
+  clientId: string;
+  payment: { available: boolean; scope: Scope | null; methodKind: Method | null; source: "customer_payment_preferences"; applied: false };
+  addresses: {
+    hasDefaultShippingAddress: boolean; defaultShippingAddressId: string | null;
+    hasDefaultBillingAddress: boolean; defaultBillingAddressId: string | null;
+    hasDefaultOrdererProfile: boolean; defaultOrdererProfileId: string | null;
+    hasDeliveryNotes: boolean; hasCourierInstructions: boolean;
+    source: "customer_address_profiles"; applied: false;
+  };
+  redactedFields: Array<"contact" | "orderer_profile" | "shipping_address" | "billing_address" | "delivery_notes" | "courier_instructions" | "payment_provider" | "payment_secret">;
+}