feat(checkout): add product selection fields to schema

Add productId, productPriceId, customAmount, and product fields
to BaseCheckoutSchema for the Polar-style selector architecture.
Update tests and contract input validation.

Author: NatElkins

src/contracts/checkout.ts

@@ -72,13 +72,22 @@ export const ConfirmCheckoutInputSchema = z.object({
 	 * Customer data provided at confirm time.
 	 */
 	customer: CustomerInputSchema.optional(),
+	/**
+	 * Product selection at confirm time.
+	 * - undefined or [] = keep current selection
+	 * - [{ productId }] = change selection to this product
+	 * - priceAmount required if selected price has amountType: CUSTOM
+	 *
+	 * Currently limited to single selection (max 1 item).
+	 */
 	products: z
 		.array(
 			z.object({
 				productId: z.string(),
 				priceAmount: z.number().optional(),
 			}),
 		)
+		.max(1)
 		.optional(),
 });
 

src/schemas/checkout.ts

@@ -58,6 +58,29 @@ const BaseCheckoutSchema = z.object({
 	customer: CustomerOutputSchema.nullable(),
 	customerBillingAddress: z.record(z.any()).nullable(),
 	products: z.array(CheckoutProductSchema).nullable(),
+	/**
+	 * The selected product ID (from the products array).
+	 * For PRODUCTS checkouts, this is the product the customer has chosen.
+	 * null for AMOUNT/TOP_UP checkouts.
+	 */
+	productId: z.string().nullable(),
+	/**
+	 * The selected product price ID.
+	 * References a price from the selected product's prices array.
+	 * null for AMOUNT/TOP_UP checkouts.
+	 */
+	productPriceId: z.string().nullable(),
+	/**
+	 * User-provided amount for CUSTOM price products.
+	 * Only set when the selected price has amountType: CUSTOM.
+	 */
+	customAmount: z.number().nullable(),
+	/**
+	 * The selected product with full details (convenience field).
+	 * Same shape as items in the products array.
+	 * null if no product is selected.
+	 */
+	product: CheckoutProductSchema.nullable(),
 	providedAmount: z.number().nullable(),
 	totalAmount: z.number().nullable(),
 	discountAmount: z.number().nullable(),

tests/contracts/checkout.test.ts

@@ -205,9 +205,6 @@ describe('Checkout Contracts', () => {
             productId: 'product_1',
             priceAmount: 500,
           },
-          {
-            productId: 'product_2',
-          },
         ],
       };
 
@@ -230,15 +227,27 @@ describe('Checkout Contracts', () => {
       const input = {
         checkoutId: 'checkout_123',
         products: [
-          { productId: 'product_1' },
-          { productId: 'product_2', priceAmount: 1000 },
+          { productId: 'product_1', priceAmount: 1000 },
         ],
       };
 
       const result = ConfirmCheckoutInputSchema.safeParse(input);
       expect(result.success).toBe(true);
     });
 
+    test('should reject products array with more than 1 item', () => {
+      const input = {
+        checkoutId: 'checkout_123',
+        products: [
+          { productId: 'product_1' },
+          { productId: 'product_2' },
+        ],
+      };
+
+      const result = ConfirmCheckoutInputSchema.safeParse(input);
+      expect(result.success).toBe(false);
+    });
+
     test('should accept custom fields from confirm input (form fields)', () => {
       // Custom fields are accepted at confirm time - they come from the form
       const input = {

tests/index.test.ts

@@ -60,6 +60,10 @@ describe('API Contract Index', () => {
             currency: 'USD',
           }],
         }],
+        productId: null,
+        productPriceId: null,
+        customAmount: null,
+        product: null,
         providedAmount: null,
         totalAmount: null,
         discountAmount: null,

tests/schemas/checkout.test.ts

@@ -23,6 +23,10 @@ const baseCheckoutData = {
   customer: null,
   customerBillingAddress: null,
   products: null,
+  productId: null,
+  productPriceId: null,
+  customAmount: null,
+  product: null,
   providedAmount: null,
   totalAmount: null,
   discountAmount: null,