wip

Author: martinsaposnic

package.json

@@ -46,6 +46,6 @@
   "dependencies": {
     "@orpc/contract": "1.3.0",
     "vitest": "^3.2.2",
-    "zod": "^3.24.4"
+    "zod": "^3.25.42"
   }
 }

pnpm-lock.yaml

@@ -3,23 +3,48 @@ import { z } from "zod";
 import { CheckoutSchema } from "../schemas/checkout";
 
 /**
- * Schema for customer metadata values.
- * Strings only, max 500 chars per value.
+ * Helper to treat empty strings as undefined (not provided).
+ * This allows clients to pass empty strings without validation errors.
  */
-const CustomerMetadataValueSchema = z.string().max(500);
+const emptyStringToUndefined = z.string().transform((val) => val.trim() === "" ? undefined : val);
 
 /**
- * Schema for customer metadata object.
- * Max 50 keys, string values only (max 500 chars each).
- * This is only accepted at create time (server-side), NOT at confirm time (browser-callable)
- * to prevent malicious payers from overwriting merchant-set metadata.
+ * Standard customer fields.
+ * - 'name' → "Name"
+ * - 'email' → "Email"
+ * - 'externalId' → "External Id"
  */
-const CustomerMetadataSchema = z
-	.record(z.string(), CustomerMetadataValueSchema)
-	.refine((obj) => Object.keys(obj).length <= 50, {
-		message: "Customer metadata cannot have more than 50 keys",
+export const StandardCustomerFieldSchema = z.enum(["email", "name", "externalId"]);
+export type StandardCustomerField = z.infer<typeof StandardCustomerFieldSchema>;
+
+/**
+ * Valid fields that can be required at checkout time.
+ * - Standard fields: 'email', 'name' (checked against customer.email/name)
+ * - Any other string is a custom field (checked against customer[field])
+ *
+ * @example ['email'] - require email
+ * @example ['email', 'name'] - require both email and name
+ * @example ['email', 'company'] - require email and company
+ */
+export const CustomerFieldSchema = z.string().min(1);
+export type CustomerField = string;
+
+/**
+ * Customer data object for checkout.
+ * Flat structure - standard fields (name, email, externalId) plus any custom string fields.
+ * Empty strings are treated as undefined (not provided).
+ *
+ * @example { name: "John", email: "john@example.com", externalId: "user_123", company: "Acme" }
+ */
+export const CustomerInputSchema = z
+	.object({
+		name: emptyStringToUndefined.optional(),
+		email: z.string().email().optional(),
+		externalId: emptyStringToUndefined.optional(),
 	})
-	.optional();
+	.catchall(z.string());
+
+export type CustomerInput = z.infer<typeof CustomerInputSchema>;
 
 export const CreateCheckoutInputSchema = z.object({
 	nodeId: z.string(),
@@ -29,25 +54,39 @@ export const CreateCheckoutInputSchema = z.object({
 	successUrl: z.string().optional(),
 	allowDiscountCodes: z.boolean().optional(),
 	metadata: z.record(z.string(), z.any()).optional(),
-	customerMetadata: CustomerMetadataSchema,
-	customerName: z.string().nonempty().optional(),
-	customerEmail: z.string().email().optional(),
-	customerIpAddress: z.string().ip().optional(),
-	customerExternalId: z.string().nonempty().optional(),
-	requireCustomerFields: z
-		.object({
-			customerName: z.boolean().optional(),
-			customerEmail: z.boolean().optional(),
-		})
-		.optional(),
+	/**
+	 * Customer data for this checkout.
+	 */
+	customer: CustomerInputSchema.optional(),
+	/**
+	 * Array of customer fields to require at checkout.
+	 * If a field is listed here and not provided, the checkout UI will prompt for it.
+	 * @example ['email'] - require email
+	 * @example ['email', 'name'] - require both
+	 */
+	requireCustomerData: z.array(CustomerFieldSchema).optional(),
 });
 
+/**
+ * Customer data for confirm.
+ * Accepts standard fields (name, email, externalId) plus any custom fields from the form.
+ * Empty strings are treated as undefined (not provided).
+ */
+export const CustomerConfirmInputSchema = z
+	.object({
+		name: emptyStringToUndefined.optional(),
+		email: z.string().email().optional(),
+		externalId: emptyStringToUndefined.optional(),
+	})
+	.catchall(z.string());
+
 export const ConfirmCheckoutInputSchema = z.object({
 	checkoutId: z.string(),
-	customerName: z.string().nonempty().optional(),
-	customerEmail: z.string().email().optional(),
-	customerIpAddress: z.string().ip().optional(),
-	customerExternalId: z.string().nonempty().optional(),
+	/**
+	 * Customer data provided at confirm time.
+	 * Note: metadata is NOT accepted here (browser-callable) to prevent tampering.
+	 */
+	customer: CustomerConfirmInputSchema.optional(),
 	products: z
 		.array(
 			z.object({

src/contracts/checkout.ts

@@ -7,6 +7,25 @@ import {
 } from "./invoice";
 import { CheckoutProductSchema } from "./product";
 
+/**
+ * Valid fields that can be required at checkout time.
+ * 'email', 'name', and 'externalId' are standard fields, anything else is a custom field.
+ */
+const CustomerFieldSchema = z.string().min(1);
+
+/**
+ * Customer data in checkout response.
+ * Flat structure - standard fields (name, email, externalId) plus custom string fields.
+ * Uses nullish() to accept both null and undefined from the database.
+ */
+const CustomerOutputSchema = z
+	.object({
+		name: z.string().nullish(),
+		email: z.string().email().nullish(),
+		externalId: z.string().nullish(),
+	})
+	.catchall(z.string());
+
 const BaseCheckoutSchema = z.object({
 	id: z.string(),
 	createdAt: z.date(),
@@ -23,21 +42,19 @@ const BaseCheckoutSchema = z.object({
 	expiresAt: z.date(),
 	userMetadata: z.record(z.any()).nullable(),
 	customFieldData: z.record(z.any()).nullable(),
-	customerMetadata: z.record(z.any()).nullable(),
 	currency: z.string(),
 	allowDiscountCodes: z.boolean(),
-	requireCustomerFields: z
-		.object({
-			customerName: z.boolean().optional(),
-			customerEmail: z.boolean().optional(),
-		})
-		.nullable(),
+	/**
+	 * Array of customer fields required at checkout.
+	 * @example ['email'] - email required
+	 * @example ['email', 'name'] - both required
+	 */
+	requireCustomerData: z.array(CustomerFieldSchema).nullable(),
 	successUrl: z.string().nullable(),
-	customerId: z.string().nullable(),
-	customerExternalId: z.string().nullable(),
-	customerName: z.string().nullable(),
-	customerEmail: z.string().email().nullable(),
-	customerIpAddress: z.string().nullable(),
+	/**
+	 * Customer data associated with this checkout.
+	 */
+	customer: CustomerOutputSchema.nullable(),
 	customerBillingAddress: z.record(z.any()).nullable(),
 	products: z.array(CheckoutProductSchema).nullable(),
 	providedAmount: z.number().nullable(),
@@ -62,7 +79,6 @@ const AmountFieldsSchema = z.object({
 
 export const ExpiredCheckoutSchema = BaseCheckoutSchema.extend({
 	status: z.literal("EXPIRED"),
-	customerId: z.string().nullable(),
 	type: z.enum(["PRODUCTS", "AMOUNT", "TOP_UP"]),
 });