refactor: add list/listPaginated pattern and reorganize schemas

- Add list (simple) + listPaginated (cursor-based) for customer, order, checkout
- Move entity schemas from contracts/ to schemas/:
  - ProductSchema, ProductDetailSchema, ProductPriceSchema -> schemas/product.ts
  - CheckoutStatusSchema, CheckoutTypeSchema, CheckoutListItemSchema -> schemas/checkout.ts
  - OrderWithRelationsSchema -> schemas/order.ts
- Create shared PaginatedInputSchema for DRY pagination inputs
- Add externalId to CreateCustomerInput and UpdateCustomerInput

Author: martinsaposnic

src/contracts/checkout.ts

@@ -1,16 +1,30 @@
 import { oc } from "@orpc/contract";
 import { z } from "zod";
-import { CheckoutSchema } from "../schemas/checkout";
-import { CurrencySchema } from "../schemas/currency";
-import { CustomerSchema } from "../schemas/customer";
 import {
-	PaginationInputSchema,
-	PaginationOutputSchema,
-} from "../schemas/pagination";
+	CheckoutSchema,
+	CheckoutStatusSchema,
+	CheckoutTypeSchema,
+	CheckoutListItemSchema,
+	CheckoutDetailSchema,
+	type CheckoutStatus,
+	type CheckoutType,
+	type CheckoutListItem,
+	type CheckoutDetail,
+} from "../schemas/checkout";
+import { CurrencySchema } from "../schemas/currency";
+import { PaginatedInputSchema, PaginationOutputSchema } from "../schemas/pagination";
+
+// Re-export entity schemas for backwards compatibility
+export {
+	CheckoutStatusSchema,
+	CheckoutTypeSchema,
+	CheckoutListItemSchema,
+	CheckoutDetailSchema,
+};
+export type { CheckoutStatus, CheckoutType, CheckoutListItem, CheckoutDetail };
 
 /**
  * Helper to treat empty strings as undefined (not provided).
- * This allows clients to pass empty strings without validation errors.
  */
 const emptyStringToUndefined = z
 	.string()
@@ -23,22 +37,12 @@ const emailOrEmpty = z.string().email().optional().or(z.literal(""));
 
 /**
  * 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" }
+ * Customer data object for checkout input.
  */
 export const CustomerInputSchema = z
 	.object({
@@ -50,6 +54,7 @@ export const CustomerInputSchema = z
 
 export type CustomerInput = z.infer<typeof CustomerInputSchema>;
 
+// Input schemas
 export const CreateCheckoutInputSchema = z.object({
 	nodeId: z.string(),
 	amount: z.number().optional(),
@@ -58,33 +63,13 @@ export const CreateCheckoutInputSchema = z.object({
 	successUrl: z.string().optional(),
 	allowDiscountCodes: z.boolean().optional(),
 	metadata: z.record(z.string(), z.any()).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(),
 });
 
 export const ConfirmCheckoutInputSchema = z.object({
 	checkoutId: z.string(),
-	/**
-	 * 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({
@@ -120,25 +105,54 @@ export const PaymentReceivedInputSchema = z.object({
 	),
 });
 
-export const GetCheckoutInputSchema = z.object({ id: z.string() });
+export const GetCheckoutInputSchema = z.object({
+	id: z.string().describe("The checkout ID"),
+});
+export type GetCheckoutInput = z.infer<typeof GetCheckoutInputSchema>;
 
 export type CreateCheckout = z.infer<typeof CreateCheckoutInputSchema>;
 export type ConfirmCheckout = z.infer<typeof ConfirmCheckoutInputSchema>;
 export type RegisterInvoice = z.infer<typeof RegisterInvoiceInputSchema>;
 export type PaymentReceived = z.infer<typeof PaymentReceivedInputSchema>;
 
+// List output schemas
+export const ListCheckoutsOutputSchema = z.object({
+	checkouts: z.array(CheckoutSchema),
+});
+export type ListCheckoutsOutput = z.infer<typeof ListCheckoutsOutputSchema>;
+
+export const ListCheckoutsPaginatedInputSchema = PaginatedInputSchema.extend({
+	status: CheckoutStatusSchema.optional().describe("Filter by status: UNCONFIRMED, CONFIRMED, PENDING_PAYMENT, PAYMENT_RECEIVED, or EXPIRED"),
+});
+export type ListCheckoutsPaginatedInput = z.infer<typeof ListCheckoutsPaginatedInputSchema>;
+
+export const ListCheckoutsPaginatedOutputSchema = PaginationOutputSchema.extend({
+	checkouts: z.array(CheckoutSchema),
+});
+export type ListCheckoutsPaginatedOutput = z.infer<typeof ListCheckoutsPaginatedOutputSchema>;
+
+export const ListCheckoutsSummaryOutputSchema = PaginationOutputSchema.extend({
+	checkouts: z.array(CheckoutListItemSchema),
+});
+export type ListCheckoutsSummaryOutput = z.infer<typeof ListCheckoutsSummaryOutputSchema>;
+
+// Contracts
 export const createCheckoutContract = oc
 	.input(CreateCheckoutInputSchema)
 	.output(CheckoutSchema);
+
 export const applyDiscountCodeContract = oc
 	.input(ApplyDiscountCodeInputSchema)
 	.output(CheckoutSchema);
+
 export const confirmCheckoutContract = oc
 	.input(ConfirmCheckoutInputSchema)
 	.output(CheckoutSchema);
+
 export const registerInvoiceContract = oc
 	.input(RegisterInvoiceInputSchema)
 	.output(CheckoutSchema);
+
 export const getCheckoutContract = oc
 	.input(GetCheckoutInputSchema)
 	.output(CheckoutSchema);
@@ -147,67 +161,19 @@ export const paymentReceivedContract = oc
 	.input(PaymentReceivedInputSchema)
 	.output(z.object({ ok: z.boolean() }));
 
-// List checkouts schemas
-export const CheckoutStatusSchema = z.enum([
-	"UNCONFIRMED",
-	"CONFIRMED",
-	"PENDING_PAYMENT",
-	"PAYMENT_RECEIVED",
-	"EXPIRED",
-]);
-export type CheckoutStatus = z.infer<typeof CheckoutStatusSchema>;
-
-export const CheckoutTypeSchema = z.enum(["PRODUCTS", "AMOUNT", "TOP_UP"]);
-export type CheckoutType = z.infer<typeof CheckoutTypeSchema>;
-
-const ListCheckoutsInputSchema = PaginationInputSchema.extend({
-	status: CheckoutStatusSchema.optional(),
-});
-
-const ListCheckoutsOutputSchema = PaginationOutputSchema.extend({
-	checkouts: z.array(CheckoutSchema),
-});
-
 export const listCheckoutsContract = oc
-	.input(ListCheckoutsInputSchema)
+	.input(z.object({}))
 	.output(ListCheckoutsOutputSchema);
 
-const CheckoutCustomerSchema = CustomerSchema.nullable();
-
-// MCP-specific summary schema for list (simpler than full CheckoutSchema)
-const CheckoutListItemSchema = z.object({
-	id: z.string(),
-	status: CheckoutStatusSchema,
-	type: CheckoutTypeSchema,
-	currency: CurrencySchema,
-	totalAmount: z.number().nullable(),
-	customerId: z.string().nullable(),
-	customer: CheckoutCustomerSchema,
-	productId: z.string().nullable(),
-	organizationId: z.string(),
-	expiresAt: z.date(),
-	createdAt: z.date(),
-	modifiedAt: z.date().nullable(),
-});
-
-// MCP-specific detailed schema for get (includes additional fields)
-const CheckoutDetailSchema = CheckoutListItemSchema.extend({
-	userMetadata: z.record(z.unknown()).nullable(),
-	successUrl: z.string().nullable(),
-	discountAmount: z.number().nullable(),
-	netAmount: z.number().nullable(),
-	taxAmount: z.number().nullable(),
-});
-
-const ListCheckoutsSummaryOutputSchema = PaginationOutputSchema.extend({
-	checkouts: z.array(CheckoutListItemSchema),
-});
+export const listCheckoutsPaginatedContract = oc
+	.input(ListCheckoutsPaginatedInputSchema)
+	.output(ListCheckoutsPaginatedOutputSchema);
 
-export const listCheckoutsSummaryContract = oc
-	.input(ListCheckoutsInputSchema)
+export const listCheckoutsSummaryPaginatedContract = oc
+	.input(ListCheckoutsPaginatedInputSchema)
 	.output(ListCheckoutsSummaryOutputSchema);
 
-export const getCheckoutSummaryContract = oc
+export const getCheckoutDetailContract = oc
 	.input(GetCheckoutInputSchema)
 	.output(CheckoutDetailSchema);
 
@@ -218,6 +184,8 @@ export const checkout = {
 	registerInvoice: registerInvoiceContract,
 	paymentReceived: paymentReceivedContract,
 	list: listCheckoutsContract,
-	listSummary: listCheckoutsSummaryContract,
-	getSummary: getCheckoutSummaryContract,
+	listPaginated: listCheckoutsPaginatedContract,
+	// Original names preserved
+	listSummary: listCheckoutsSummaryPaginatedContract,
+	getSummary: getCheckoutDetailContract,
 };

src/contracts/customer.ts

@@ -5,45 +5,78 @@ import {
 	CustomerWithSubscriptionsSchema,
 	GetCustomerInputSchema as SdkGetCustomerInputSchema,
 } from "../schemas/customer";
-import {
-	PaginationInputSchema,
-	PaginationOutputSchema,
-} from "../schemas/pagination";
+import { PaginatedInputSchema, PaginationOutputSchema } from "../schemas/pagination";
+
+// Simple list (no pagination)
+export const ListCustomersOutputSchema = z.object({
+	customers: z.array(CustomerSchema),
+});
+export type ListCustomersOutput = z.infer<typeof ListCustomersOutputSchema>;
+
+// Paginated list (no additional filters for customers)
+export const ListCustomersPaginatedInputSchema = PaginatedInputSchema;
+export type ListCustomersPaginatedInput = z.infer<typeof ListCustomersPaginatedInputSchema>;
 
-// MCP-specific schemas
-const ListCustomersInputSchema = PaginationInputSchema;
-const ListCustomersOutputSchema = PaginationOutputSchema.extend({
+export const ListCustomersPaginatedOutputSchema = PaginationOutputSchema.extend({
 	customers: z.array(CustomerSchema),
 });
+export type ListCustomersPaginatedOutput = z.infer<typeof ListCustomersPaginatedOutputSchema>;
 
-const McpGetCustomerInputSchema = z.object({ id: z.string() });
+// Flexible customer lookup - exactly one of id, email, or externalId
+// Base shape without refinement (for MCP tool schemas)
+export const CustomerLookupBaseSchema = z.object({
+	id: z.string().optional().describe("The customer ID"),
+	email: z.string().optional().describe("The customer email address"),
+	externalId: z.string().optional().describe("The external ID from your system"),
+});
+
+// With refinement for runtime validation
+export const CustomerLookupInputSchema = CustomerLookupBaseSchema.refine(
+	(data) => [data.id, data.email, data.externalId].filter(Boolean).length === 1,
+	{ message: "Exactly one of id, email, or externalId must be provided" },
+);
+export type CustomerLookupInput = z.infer<typeof CustomerLookupInputSchema>;
+
+// Aliases for specific operations
+export const GetCustomerInputSchema = CustomerLookupBaseSchema;
+export type GetCustomerInput = z.infer<typeof GetCustomerInputSchema>;
 
-const CreateCustomerInputSchema = z.object({
-	name: z.string().min(1),
-	email: z.string().email(),
+export const DeleteCustomerInputSchema = CustomerLookupBaseSchema;
+export type DeleteCustomerInput = z.infer<typeof DeleteCustomerInputSchema>;
+
+export const CreateCustomerInputSchema = z.object({
+	name: z.string().min(1).describe("Customer name"),
+	email: z.string().email().describe("Customer email address"),
+	externalId: z.string().optional().describe("External ID from your system for linking"),
 });
 
-const UpdateCustomerInputSchema = z.object({
-	id: z.string(),
-	name: z.string().optional(),
-	email: z.string().email().optional(),
-	userMetadata: z.record(z.string(), z.string()).optional(),
+export const UpdateCustomerInputSchema = z.object({
+	id: z.string().describe("The customer ID to update"),
+	name: z.string().optional().describe("New customer name"),
+	email: z.string().email().optional().describe("New customer email address"),
+	externalId: z.string().optional().describe("External ID from your system for linking"),
+	userMetadata: z.record(z.string(), z.string()).optional().describe("Custom metadata key-value pairs"),
 });
 
-const DeleteCustomerInputSchema = z.object({ id: z.string() });
+export type CreateCustomerInput = z.infer<typeof CreateCustomerInputSchema>;
+export type UpdateCustomerInput = z.infer<typeof UpdateCustomerInputSchema>;
 
 // SDK contract - uses flexible lookup (externalId/email/customerId)
 export const getSdkCustomerContract = oc
 	.input(SdkGetCustomerInputSchema)
 	.output(CustomerWithSubscriptionsSchema);
 
-// MCP contracts
+// Contracts
 export const listCustomersContract = oc
-	.input(ListCustomersInputSchema)
+	.input(z.object({}))
 	.output(ListCustomersOutputSchema);
 
+export const listCustomersPaginatedContract = oc
+	.input(ListCustomersPaginatedInputSchema)
+	.output(ListCustomersPaginatedOutputSchema);
+
 export const getCustomerContract = oc
-	.input(McpGetCustomerInputSchema)
+	.input(GetCustomerInputSchema)
 	.output(CustomerSchema);
 
 export const createCustomerContract = oc
@@ -56,10 +89,11 @@ export const updateCustomerContract = oc
 
 export const deleteCustomerContract = oc
 	.input(DeleteCustomerInputSchema)
-	.output(z.object({ ok: z.literal(true) }));
+	.output(z.void());
 
 export const customer = {
 	list: listCustomersContract,
+	listPaginated: listCustomersPaginatedContract,
 	get: getCustomerContract,
 	getSdk: getSdkCustomerContract,
 	create: createCustomerContract,