feat: add productId for single-product selector model

Switch from cart model (buy all products) to selector model (choose one
product from available options). The productId field on checkout confirm
specifies which product the user selected, and is reflected in the
checkout response after confirmation.

Author: NatElkins

src/contracts/checkout.ts

@@ -72,6 +72,16 @@ export const ConfirmCheckoutInputSchema = z.object({
 	 * Customer data provided at confirm time.
 	 */
 	customer: CustomerInputSchema.optional(),
+	/**
+	 * The selected product ID from the checkout's available products.
+	 * In the selector model, multiple products represent options to choose from,
+	 * and the user selects ONE product at confirm time.
+	 */
+	productId: z.string().optional(),
+	/**
+	 * Products array for CUSTOM pricing amounts only.
+	 * Use productId for standard product selection.
+	 */
 	products: z
 		.array(
 			z.object({

src/schemas/checkout.ts

@@ -57,7 +57,18 @@ const BaseCheckoutSchema = z.object({
 	 */
 	customer: CustomerOutputSchema.nullable(),
 	customerBillingAddress: z.record(z.any()).nullable(),
+	/**
+	 * Available product options for this checkout.
+	 * In the selector model, these represent choices the user can pick from.
+	 * The user selects ONE product, which is then stored in productId.
+	 */
 	products: z.array(CheckoutProductSchema).nullable(),
+	/**
+	 * The selected product ID (set after confirm).
+	 * In the selector model, this indicates which product the user chose
+	 * from the available products array.
+	 */
+	productId: z.string().nullable(),
 	providedAmount: z.number().nullable(),
 	totalAmount: z.number().nullable(),
 	discountAmount: z.number().nullable(),

tests/index.test.ts

@@ -60,6 +60,7 @@ describe('API Contract Index', () => {
             currency: 'USD',
           }],
         }],
+        productId: null,
         providedAmount: null,
         totalAmount: null,
         discountAmount: null,
@@ -191,4 +192,4 @@ describe('API Contract Index', () => {
       expect(contract.checkout.paymentReceived).toBeDefined();
     });
   });
-}); 
+});

tests/schemas/checkout.test.ts

@@ -23,6 +23,7 @@ const baseCheckoutData = {
   customer: null,
   customerBillingAddress: null,
   products: null,
+  productId: null,
   providedAmount: null,
   totalAmount: null,
   discountAmount: null,
@@ -383,4 +384,4 @@ describe('CheckoutSchema', () => {
       expect(result.success).toBe(false);
     });
   });
-}); 
+});