@offerkit/sdk 0.2.2 → 0.2.4

package/dist/index.mjs

@@ -38,8 +38,9 @@ const apiKeys = {
 	revoke: oc.route({
 		method: "DELETE",
 		path: "/api-keys/{id}",
-		summary: "Disable an API key (cannot be re-enabled)"
-	}).input(z.object({ id: z.string() })).output(z.object({ ok: z.literal(true) }))
+		summary: "Disable an API key (cannot be re-enabled)",
+		inputStructure: "detailed"
+	}).input(z.object({ params: z.object({ id: z.string() }) })).output(z.object({ ok: z.literal(true) }))
 };
 //#endregion
 //#region ../contract/src/mcp.ts
@@ -140,8 +141,9 @@ const campaigns = {
 	})).route({
 		method: "GET",
 		path: "/campaigns/{id}",
-		summary: "Get campaign"
-	}).input(z.object({ id: z.string().uuid() })).output(campaignOutput),
+		summary: "Get campaign",
+		inputStructure: "detailed"
+	}).input(z.object({ params: z.object({ id: z.string().uuid() }) })).output(campaignOutput),
 	create: oc.route({
 		method: "POST",
 		path: "/campaigns",
@@ -150,16 +152,18 @@ const campaigns = {
 	update: oc.route({
 		method: "PATCH",
 		path: "/campaigns/{id}",
-		summary: "Update campaign"
+		summary: "Update campaign",
+		inputStructure: "detailed"
 	}).input(z.object({
-		id: z.string().uuid(),
-		patch: campaignUpdateInput
+		params: z.object({ id: z.string().uuid() }),
+		body: z.object({ patch: campaignUpdateInput })
 	})).output(campaignOutput),
 	delete: oc.route({
 		method: "DELETE",
 		path: "/campaigns/{id}",
-		summary: "Soft-delete campaign"
-	}).input(z.object({ id: z.string().uuid() })).output(z.object({ ok: z.literal(true) }))
+		summary: "Soft-delete campaign",
+		inputStructure: "detailed"
+	}).input(z.object({ params: z.object({ id: z.string().uuid() }) })).output(z.object({ ok: z.literal(true) }))
 };
 //#endregion
 //#region ../contract/src/schemas/customer.ts
@@ -226,16 +230,18 @@ const customers = {
 	})).route({
 		method: "GET",
 		path: "/customers/{id}",
-		summary: "Get customer"
-	}).input(z.object({ id: z.string().uuid() })).output(customerOutput),
+		summary: "Get customer",
+		inputStructure: "detailed"
+	}).input(z.object({ params: z.object({ id: z.string().uuid() }) })).output(customerOutput),
 	getByExternalId: oc.meta(mcpMeta({
 		expose: true,
 		riskLevel: "safe"
 	})).route({
 		method: "GET",
 		path: "/customers/by-external-id/{externalId}",
-		summary: "Get a customer by integrator-supplied externalId"
-	}).input(z.object({ externalId: z.string().min(1).max(256) })).output(customerOutput),
+		summary: "Get a customer by integrator-supplied externalId",
+		inputStructure: "detailed"
+	}).input(z.object({ params: z.object({ externalId: z.string().min(1).max(256) }) })).output(customerOutput),
 	create: oc.route({
 		method: "POST",
 		path: "/customers",
@@ -249,16 +255,18 @@ const customers = {
 	update: oc.route({
 		method: "PATCH",
 		path: "/customers/{id}",
-		summary: "Update customer"
+		summary: "Update customer",
+		inputStructure: "detailed"
 	}).input(z.object({
-		id: z.string().uuid(),
-		patch: customerUpdateInput
+		params: z.object({ id: z.string().uuid() }),
+		body: z.object({ patch: customerUpdateInput })
 	})).output(customerOutput),
 	delete: oc.route({
 		method: "DELETE",
 		path: "/customers/{id}",
-		summary: "Soft-delete customer"
-	}).input(z.object({ id: z.string().uuid() })).output(z.object({ ok: z.literal(true) }))
+		summary: "Soft-delete customer",
+		inputStructure: "detailed"
+	}).input(z.object({ params: z.object({ id: z.string().uuid() }) })).output(z.object({ ok: z.literal(true) }))
 };
 //#endregion
 //#region ../contract/src/schemas/loyalty.ts
@@ -416,8 +424,9 @@ const loyalty = {
 		get: oc.route({
 			method: "GET",
 			path: "/loyalty/programs/{id}",
-			summary: "Get loyalty program"
-		}).input(z.object({ id: z.string().uuid() })).output(loyaltyProgramOutput),
+			summary: "Get loyalty program",
+			inputStructure: "detailed"
+		}).input(z.object({ params: z.object({ id: z.string().uuid() }) })).output(loyaltyProgramOutput),
 		create: oc.route({
 			method: "POST",
 			path: "/loyalty/programs",
@@ -426,23 +435,26 @@ const loyalty = {
 		update: oc.route({
 			method: "PATCH",
 			path: "/loyalty/programs/{id}",
-			summary: "Update loyalty program"
+			summary: "Update loyalty program",
+			inputStructure: "detailed"
 		}).input(z.object({
-			id: z.string().uuid(),
-			patch: loyaltyProgramUpdateInput
+			params: z.object({ id: z.string().uuid() }),
+			body: z.object({ patch: loyaltyProgramUpdateInput })
 		})).output(loyaltyProgramOutput),
 		delete: oc.route({
 			method: "DELETE",
 			path: "/loyalty/programs/{id}",
-			summary: "Soft-delete program"
-		}).input(z.object({ id: z.string().uuid() })).output(z.object({ ok: z.literal(true) }))
+			summary: "Soft-delete program",
+			inputStructure: "detailed"
+		}).input(z.object({ params: z.object({ id: z.string().uuid() }) })).output(z.object({ ok: z.literal(true) }))
 	},
 	tiers: {
 		list: oc.route({
 			method: "GET",
 			path: "/loyalty/programs/{programId}/tiers",
-			summary: "List tiers"
-		}).input(z.object({ programId: z.string().uuid() })).output(z.object({ data: z.array(loyaltyTierOutput) })),
+			summary: "List tiers",
+			inputStructure: "detailed"
+		}).input(z.object({ params: z.object({ programId: z.string().uuid() }) })).output(z.object({ data: z.array(loyaltyTierOutput) })),
 		create: oc.route({
 			method: "POST",
 			path: "/loyalty/tiers",
@@ -451,23 +463,26 @@ const loyalty = {
 		update: oc.route({
 			method: "PATCH",
 			path: "/loyalty/tiers/{id}",
-			summary: "Update tier"
+			summary: "Update tier",
+			inputStructure: "detailed"
 		}).input(z.object({
-			id: z.string().uuid(),
-			patch: loyaltyTierUpdateInput
+			params: z.object({ id: z.string().uuid() }),
+			body: z.object({ patch: loyaltyTierUpdateInput })
 		})).output(loyaltyTierOutput),
 		delete: oc.route({
 			method: "DELETE",
 			path: "/loyalty/tiers/{id}",
-			summary: "Delete tier"
-		}).input(z.object({ id: z.string().uuid() })).output(z.object({ ok: z.literal(true) }))
+			summary: "Delete tier",
+			inputStructure: "detailed"
+		}).input(z.object({ params: z.object({ id: z.string().uuid() }) })).output(z.object({ ok: z.literal(true) }))
 	},
 	earningRules: {
 		list: oc.route({
 			method: "GET",
 			path: "/loyalty/programs/{programId}/earning-rules",
-			summary: "List earning rules"
-		}).input(z.object({ programId: z.string().uuid() })).output(z.object({ data: z.array(loyaltyEarningRuleOutput) })),
+			summary: "List earning rules",
+			inputStructure: "detailed"
+		}).input(z.object({ params: z.object({ programId: z.string().uuid() }) })).output(z.object({ data: z.array(loyaltyEarningRuleOutput) })),
 		create: oc.route({
 			method: "POST",
 			path: "/loyalty/earning-rules",
@@ -476,23 +491,26 @@ const loyalty = {
 		update: oc.route({
 			method: "PATCH",
 			path: "/loyalty/earning-rules/{id}",
-			summary: "Update earning rule"
+			summary: "Update earning rule",
+			inputStructure: "detailed"
 		}).input(z.object({
-			id: z.string().uuid(),
-			patch: loyaltyEarningRuleUpdateInput
+			params: z.object({ id: z.string().uuid() }),
+			body: z.object({ patch: loyaltyEarningRuleUpdateInput })
 		})).output(loyaltyEarningRuleOutput),
 		delete: oc.route({
 			method: "DELETE",
 			path: "/loyalty/earning-rules/{id}",
-			summary: "Delete earning rule"
-		}).input(z.object({ id: z.string().uuid() })).output(z.object({ ok: z.literal(true) }))
+			summary: "Delete earning rule",
+			inputStructure: "detailed"
+		}).input(z.object({ params: z.object({ id: z.string().uuid() }) })).output(z.object({ ok: z.literal(true) }))
 	},
 	rewards: {
 		list: oc.route({
 			method: "GET",
 			path: "/loyalty/programs/{programId}/rewards",
-			summary: "List rewards"
-		}).input(z.object({ programId: z.string().uuid() })).output(z.object({ data: z.array(loyaltyRewardOutput) })),
+			summary: "List rewards",
+			inputStructure: "detailed"
+		}).input(z.object({ params: z.object({ programId: z.string().uuid() }) })).output(z.object({ data: z.array(loyaltyRewardOutput) })),
 		create: oc.route({
 			method: "POST",
 			path: "/loyalty/rewards",
@@ -501,28 +519,35 @@ const loyalty = {
 		update: oc.route({
 			method: "PATCH",
 			path: "/loyalty/rewards/{id}",
-			summary: "Update reward"
+			summary: "Update reward",
+			inputStructure: "detailed"
 		}).input(z.object({
-			id: z.string().uuid(),
-			patch: loyaltyRewardUpdateInput
+			params: z.object({ id: z.string().uuid() }),
+			body: z.object({ patch: loyaltyRewardUpdateInput })
 		})).output(loyaltyRewardOutput),
 		delete: oc.route({
 			method: "DELETE",
 			path: "/loyalty/rewards/{id}",
-			summary: "Soft-delete reward"
-		}).input(z.object({ id: z.string().uuid() })).output(z.object({ ok: z.literal(true) }))
+			summary: "Soft-delete reward",
+			inputStructure: "detailed"
+		}).input(z.object({ params: z.object({ id: z.string().uuid() }) })).output(z.object({ ok: z.literal(true) }))
 	},
 	members: {
 		list: oc.route({
 			method: "GET",
 			path: "/loyalty/programs/{programId}/members",
-			summary: "List members of a program"
-		}).input(paginationInput.extend({ programId: z.string().uuid() })).output(paginatedOutput(loyaltyMemberOutput)),
+			summary: "List members of a program",
+			inputStructure: "detailed"
+		}).input(z.object({
+			params: z.object({ programId: z.string().uuid() }),
+			query: paginationInput
+		})).output(paginatedOutput(loyaltyMemberOutput)),
 		get: oc.route({
 			method: "GET",
 			path: "/loyalty/members/{id}",
-			summary: "Get member"
-		}).input(z.object({ id: z.string().uuid() })).output(loyaltyMemberOutput),
+			summary: "Get member",
+			inputStructure: "detailed"
+		}).input(z.object({ params: z.object({ id: z.string().uuid() }) })).output(loyaltyMemberOutput),
 		enroll: oc.route({
 			method: "POST",
 			path: "/loyalty/members",
@@ -574,8 +599,9 @@ const loyalty = {
 		})).route({
 			method: "GET",
 			path: "/loyalty/members/{id}/transactions",
-			summary: "Member transaction ledger"
-		}).input(z.object({ id: z.string().uuid() })).output(z.object({ data: z.array(loyaltyTransactionOutput) }))
+			summary: "Member transaction ledger",
+			inputStructure: "detailed"
+		}).input(z.object({ params: z.object({ id: z.string().uuid() }) })).output(z.object({ data: z.array(loyaltyTransactionOutput) }))
 	}
 };
 //#endregion
@@ -690,8 +716,9 @@ const referrals = {
 		get: oc.route({
 			method: "GET",
 			path: "/referral-programs/{id}",
-			summary: "Get referral program"
-		}).input(z.object({ id: z.string().uuid() })).output(referralProgramOutput),
+			summary: "Get referral program",
+			inputStructure: "detailed"
+		}).input(z.object({ params: z.object({ id: z.string().uuid() }) })).output(referralProgramOutput),
 		create: oc.route({
 			method: "POST",
 			path: "/referral-programs",
@@ -700,32 +727,43 @@ const referrals = {
 		update: oc.route({
 			method: "PATCH",
 			path: "/referral-programs/{id}",
-			summary: "Update referral program"
+			summary: "Update referral program",
+			inputStructure: "detailed"
 		}).input(z.object({
-			id: z.string().uuid(),
-			patch: referralProgramUpdateInput
+			params: z.object({ id: z.string().uuid() }),
+			body: z.object({ patch: referralProgramUpdateInput })
 		})).output(referralProgramOutput),
 		delete: oc.route({
 			method: "DELETE",
 			path: "/referral-programs/{id}",
-			summary: "Soft-delete referral program"
-		}).input(z.object({ id: z.string().uuid() })).output(z.object({ ok: z.literal(true) }))
+			summary: "Soft-delete referral program",
+			inputStructure: "detailed"
+		}).input(z.object({ params: z.object({ id: z.string().uuid() }) })).output(z.object({ ok: z.literal(true) }))
 	},
 	listCodes: oc.route({
 		method: "GET",
 		path: "/referral-programs/{programId}/codes",
-		summary: "List referral codes in a program"
-	}).input(paginationInput.extend({ programId: z.string().uuid() })).output(paginatedOutput(referralCodeOutput)),
+		summary: "List referral codes in a program",
+		inputStructure: "detailed"
+	}).input(z.object({
+		params: z.object({ programId: z.string().uuid() }),
+		query: paginationInput
+	})).output(paginatedOutput(referralCodeOutput)),
 	listConversions: oc.route({
 		method: "GET",
 		path: "/referral-codes/{codeId}/conversions",
-		summary: "List conversions for a referral code"
-	}).input(paginationInput.extend({ codeId: z.string().uuid() })).output(paginatedOutput(referralConversionOutput)),
+		summary: "List conversions for a referral code",
+		inputStructure: "detailed"
+	}).input(z.object({
+		params: z.object({ codeId: z.string().uuid() }),
+		query: paginationInput
+	})).output(paginatedOutput(referralConversionOutput)),
 	getByCode: oc.route({
 		method: "GET",
 		path: "/referrals/{code}",
-		summary: "Look up a referral code"
-	}).input(z.object({ code: z.string() })).output(referralCodeOutput),
+		summary: "Look up a referral code",
+		inputStructure: "detailed"
+	}).input(z.object({ params: z.object({ code: z.string() }) })).output(referralCodeOutput),
 	issue: oc.route({
 		method: "POST",
 		path: "/referrals/issue",
@@ -738,6 +776,333 @@ const referrals = {
 	}).input(referralConvertInput).output(referralConvertOutput)
 };
 //#endregion
+//#region ../contract/src/schemas/voucher.ts
+const voucherType = z.enum(["DISCOUNT", "GIFT_CARD"]);
+const voucherDiscount = z.object({
+	type: z.enum(["AMOUNT", "PERCENTAGE"]),
+	amount: z.number().int().min(0).optional(),
+	percent: z.number().int().min(0).max(1e4).optional(),
+	maxDiscountAmount: z.number().int().min(0).optional(),
+	appliesTo: z.object({
+		productIds: z.array(z.string()).optional(),
+		collectionIds: z.array(z.string()).optional()
+	}).optional()
+});
+const customReward = z.object({
+	typeKey: z.string().min(1),
+	payload: z.record(z.string(), z.unknown())
+});
+const voucherOutput = z.object({
+	id: z.string().uuid(),
+	code: z.string(),
+	campaignId: z.string().uuid().nullable(),
+	type: voucherType,
+	discount: voucherDiscount.nullable(),
+	customRewards: z.array(customReward),
+	giftBalance: z.number().int().nullable(),
+	redemptionLimit: z.number().int().nullable(),
+	redemptionCount: z.number().int(),
+	priority: z.number().int(),
+	exclusive: z.boolean(),
+	active: z.boolean(),
+	startDate: z.string().datetime().nullable(),
+	endDate: z.string().datetime().nullable(),
+	customerId: z.string().uuid().nullable(),
+	metadata: z.record(z.string(), z.unknown()),
+	createdAt: z.string().datetime(),
+	updatedAt: z.string().datetime()
+});
+const voucherCreateInput = z.object({
+	code: z.string().min(1).optional(),
+	campaignId: z.string().uuid().optional(),
+	type: voucherType,
+	discount: voucherDiscount.optional(),
+	customRewards: z.array(customReward).optional(),
+	giftBalance: z.number().int().min(0).optional(),
+	redemptionLimit: z.number().int().min(1).optional(),
+	priority: z.number().int().optional(),
+	exclusive: z.boolean().optional(),
+	startDate: z.string().datetime().optional(),
+	endDate: z.string().datetime().optional(),
+	customerId: z.string().uuid().optional(),
+	metadata: z.record(z.string(), z.unknown()).optional()
+});
+const voucherUpdateInput = voucherCreateInput.omit({
+	type: true,
+	code: true
+}).partial().extend({ active: z.boolean().optional() });
+const voucherBulkCreateInput = z.object({
+	campaignId: z.string().uuid(),
+	count: z.number().int().min(1).max(1e5)
+});
+//#endregion
+//#region ../contract/src/schemas/redemption.ts
+const orderItem$1 = z.object({
+	productId: z.string(),
+	collectionId: z.string().optional(),
+	quantity: z.number().int().min(1),
+	unitPrice: z.number().int().min(0)
+});
+const orderInput = z.object({
+	amount: z.number().int().min(0),
+	currency: z.string().length(3),
+	items: z.array(orderItem$1).optional()
+});
+const validateInput = z.object({
+	code: z.string().min(1),
+	customerId: z.string().uuid().optional(),
+	order: orderInput.optional()
+});
+const redeemInput = validateInput.extend({
+	/** uuid of an `order` row created via the orders API. */
+	orderId: z.string().uuid().optional(),
+	/** Free-form integrator order reference (Shopify id, etc). */
+	externalOrderId: z.string().min(1).max(120).optional(),
+	idempotencyKey: z.string().min(1).max(128).optional()
+});
+const breakdownEntry = z.object({
+	voucherId: z.string().uuid(),
+	code: z.string(),
+	amount: z.number().int(),
+	type: z.enum(["AMOUNT", "PERCENTAGE"]).optional(),
+	reason: z.enum(["exclusivity_lost", "zero_after_running_total"]).optional()
+});
+const redemptionExplanation = z.object({
+	code: z.enum([
+		"voucher_not_found",
+		"voucher_disabled",
+		"voucher_expired",
+		"redemption_limit_reached",
+		"currency_mismatch",
+		"gift_balance_zero",
+		"order_required",
+		"exclusivity_lost",
+		"zero_after_running_total",
+		"gift_card_stacking_unsupported"
+	]),
+	message: z.string(),
+	voucherId: z.string().uuid().optional(),
+	voucherCode: z.string().optional(),
+	details: z.record(z.string(), z.union([
+		z.string(),
+		z.number(),
+		z.boolean(),
+		z.null()
+	])).optional()
+});
+const validateOutput = z.object({
+	valid: z.boolean(),
+	code: z.string().optional(),
+	message: z.string().optional(),
+	explanations: z.array(redemptionExplanation).optional(),
+	preview: z.object({
+		amount: z.number().int(),
+		finalOrder: z.object({
+			amount: z.number().int(),
+			currency: z.string()
+		}),
+		breakdown: z.array(breakdownEntry)
+	}).optional()
+});
+const qualifyInput = z.object({
+	customerId: z.string().uuid(),
+	order: orderInput,
+	filters: z.object({
+		campaignIds: z.array(z.string().uuid()).max(100).optional(),
+		includeSkipped: z.boolean().optional()
+	}).optional()
+});
+const qualifyOutput = z.object({
+	eligible: z.array(z.object({
+		code: z.string(),
+		campaignId: z.string().uuid().nullable(),
+		discount: voucherDiscount.omit({ appliesTo: true }).nullable(),
+		endDate: z.string().datetime().nullable(),
+		preview: z.object({
+			amount: z.number().int(),
+			finalOrder: z.object({
+				amount: z.number().int(),
+				currency: z.string()
+			}),
+			breakdown: z.array(breakdownEntry)
+		}).optional()
+	})),
+	skipped: z.array(z.object({
+		code: z.string(),
+		campaignId: z.string().uuid().nullable(),
+		reason: z.string(),
+		message: z.string()
+	}))
+});
+const redeemOutput = z.object({
+	ok: z.boolean(),
+	redemptionId: z.string().uuid().optional(),
+	amount: z.number().int().optional(),
+	finalOrder: z.object({
+		amount: z.number().int(),
+		currency: z.string()
+	}).optional(),
+	breakdown: z.array(breakdownEntry).optional(),
+	idempotent: z.boolean().optional(),
+	code: z.string().optional(),
+	message: z.string().optional(),
+	explanations: z.array(redemptionExplanation).optional()
+});
+const stackRedeemInput = z.object({
+	codes: z.array(z.string().min(1)).min(1).max(20),
+	customerId: z.string().uuid().optional(),
+	orderId: z.string().uuid().optional(),
+	externalOrderId: z.string().min(1).max(120).optional(),
+	order: orderInput,
+	idempotencyKey: z.string().min(1).max(128).optional()
+});
+const stackEntry = z.object({
+	voucherCode: z.string(),
+	voucherId: z.string().uuid(),
+	redemptionId: z.string().uuid(),
+	amount: z.number().int()
+});
+const stackRedeemOutput = z.object({
+	ok: z.boolean(),
+	batchId: z.string().uuid().optional(),
+	amount: z.number().int().optional(),
+	finalOrder: z.object({
+		amount: z.number().int(),
+		currency: z.string()
+	}).optional(),
+	breakdown: z.array(breakdownEntry).optional(),
+	entries: z.array(stackEntry).optional(),
+	idempotent: z.boolean().optional(),
+	code: z.string().optional(),
+	message: z.string().optional(),
+	explanations: z.array(redemptionExplanation).optional()
+});
+//#endregion
+//#region ../contract/src/schemas/promotion.ts
+const promotionTierOutput = z.object({
+	id: z.string().uuid(),
+	campaignId: z.string().uuid(),
+	name: z.string(),
+	description: z.string().nullable(),
+	effect: voucherDiscount,
+	customRewards: z.array(customReward),
+	validationRuleId: z.string().uuid().nullable(),
+	active: z.boolean(),
+	priority: z.number().int(),
+	exclusive: z.boolean(),
+	startDate: z.string().datetime().nullable(),
+	endDate: z.string().datetime().nullable(),
+	metadata: z.record(z.string(), z.unknown()),
+	createdAt: z.string().datetime(),
+	updatedAt: z.string().datetime()
+});
+const promotionTierCreateInput = z.object({
+	campaignId: z.string().uuid(),
+	name: z.string().min(1),
+	description: z.string().optional(),
+	effect: voucherDiscount,
+	customRewards: z.array(customReward).optional(),
+	validationRuleId: z.string().uuid().optional(),
+	active: z.boolean().optional(),
+	priority: z.number().int().optional(),
+	exclusive: z.boolean().optional(),
+	startDate: z.string().datetime().optional(),
+	endDate: z.string().datetime().optional(),
+	metadata: z.record(z.string(), z.unknown()).optional()
+});
+const promotionTierUpdateInput = promotionTierCreateInput.omit({ campaignId: true }).partial();
+const qualificationInput = z.object({
+	customerId: z.string().uuid().optional(),
+	order: orderInput,
+	metadata: z.record(z.string(), z.unknown()).optional(),
+	filters: z.object({
+		campaignIds: z.array(z.string().uuid()).optional(),
+		includeSkipped: z.boolean().optional()
+	}).optional()
+});
+const qualificationReason = z.enum([
+	"campaign_inactive",
+	"campaign_not_active",
+	"promotion_inactive",
+	"promotion_not_active",
+	"currency_mismatch",
+	"rule_failed",
+	"rule_error",
+	"no_discount_effect",
+	"exclusivity_lost",
+	"zero_after_running_total"
+]);
+const qualifiedPromotion = z.object({
+	source: z.literal("promotion"),
+	campaignId: z.string().uuid(),
+	promotionTierId: z.string().uuid(),
+	name: z.string(),
+	discount: voucherDiscount,
+	customRewards: z.array(customReward),
+	priority: z.number().int(),
+	exclusive: z.boolean(),
+	metadata: z.record(z.string(), z.unknown())
+});
+const skippedPromotion = qualifiedPromotion.extend({
+	reason: qualificationReason,
+	message: z.string(),
+	trace: z.unknown().optional()
+});
+const qualificationOutput = z.object({
+	eligible: z.array(qualifiedPromotion),
+	skipped: z.array(skippedPromotion),
+	preview: z.object({
+		amount: z.number().int(),
+		finalOrder: z.object({
+			amount: z.number().int(),
+			currency: z.string()
+		}),
+		breakdown: z.array(breakdownEntry)
+	})
+});
+//#endregion
+//#region ../contract/src/routes/promotions.ts
+const promotions = {
+	tiers: {
+		list: oc.route({
+			method: "GET",
+			path: "/promotions/tiers",
+			summary: "List promotion tiers"
+		}).input(paginationInput.extend({
+			campaignId: z.string().uuid().optional(),
+			active: z.boolean().optional()
+		})).output(paginatedOutput(promotionTierOutput)),
+		create: oc.route({
+			method: "POST",
+			path: "/promotions/tiers",
+			summary: "Create promotion tier"
+		}).input(promotionTierCreateInput).output(promotionTierOutput),
+		update: oc.route({
+			method: "PATCH",
+			path: "/promotions/tiers/{id}",
+			summary: "Update promotion tier",
+			inputStructure: "detailed"
+		}).input(z.object({
+			params: z.object({ id: z.string().uuid() }),
+			body: z.object({ patch: promotionTierUpdateInput })
+		})).output(promotionTierOutput),
+		delete: oc.route({
+			method: "DELETE",
+			path: "/promotions/tiers/{id}",
+			summary: "Soft-delete promotion tier",
+			inputStructure: "detailed"
+		}).input(z.object({ params: z.object({ id: z.string().uuid() }) })).output(z.object({ ok: z.literal(true) }))
+	},
+	qualify: oc.meta(mcpMeta({
+		expose: true,
+		riskLevel: "safe"
+	})).route({
+		method: "POST",
+		path: "/promotions/qualify",
+		summary: "Return auto-applied promotions a cart qualifies for"
+	}).input(qualificationInput).output(qualificationOutput)
+};
+//#endregion
 //#region ../contract/src/schemas/reward-type.ts
 const rewardTypeOutput = z.object({
 	id: z.string().uuid(),
@@ -766,8 +1131,9 @@ const rewardTypes = {
 	get: oc.route({
 		method: "GET",
 		path: "/reward-types/{id}",
-		summary: "Get reward type"
-	}).input(z.object({ id: z.string().uuid() })).output(rewardTypeOutput),
+		summary: "Get reward type",
+		inputStructure: "detailed"
+	}).input(z.object({ params: z.object({ id: z.string().uuid() }) })).output(rewardTypeOutput),
 	create: oc.route({
 		method: "POST",
 		path: "/reward-types",
@@ -776,16 +1142,18 @@ const rewardTypes = {
 	update: oc.route({
 		method: "PATCH",
 		path: "/reward-types/{id}",
-		summary: "Update reward type"
+		summary: "Update reward type",
+		inputStructure: "detailed"
 	}).input(z.object({
-		id: z.string().uuid(),
-		patch: rewardTypeUpdateInput
+		params: z.object({ id: z.string().uuid() }),
+		body: z.object({ patch: rewardTypeUpdateInput })
 	})).output(rewardTypeOutput),
 	delete: oc.route({
 		method: "DELETE",
 		path: "/reward-types/{id}",
-		summary: "Soft-delete reward type"
-	}).input(z.object({ id: z.string().uuid() })).output(z.object({ ok: z.literal(true) }))
+		summary: "Soft-delete reward type",
+		inputStructure: "detailed"
+	}).input(z.object({ params: z.object({ id: z.string().uuid() }) })).output(z.object({ ok: z.literal(true) }))
 };
 //#endregion
 //#region ../contract/src/schemas/segment.ts
@@ -815,8 +1183,9 @@ const segments = {
 	get: oc.route({
 		method: "GET",
 		path: "/segments/{id}",
-		summary: "Get segment"
-	}).input(z.object({ id: z.string().uuid() })).output(segmentOutput),
+		summary: "Get segment",
+		inputStructure: "detailed"
+	}).input(z.object({ params: z.object({ id: z.string().uuid() }) })).output(segmentOutput),
 	create: oc.route({
 		method: "POST",
 		path: "/segments",
@@ -825,16 +1194,18 @@ const segments = {
 	update: oc.route({
 		method: "PATCH",
 		path: "/segments/{id}",
-		summary: "Update segment"
+		summary: "Update segment",
+		inputStructure: "detailed"
 	}).input(z.object({
-		id: z.string().uuid(),
-		patch: segmentUpdateInput
+		params: z.object({ id: z.string().uuid() }),
+		body: z.object({ patch: segmentUpdateInput })
 	})).output(segmentOutput),
 	delete: oc.route({
 		method: "DELETE",
 		path: "/segments/{id}",
-		summary: "Soft-delete segment"
-	}).input(z.object({ id: z.string().uuid() })).output(z.object({ ok: z.literal(true) })),
+		summary: "Soft-delete segment",
+		inputStructure: "detailed"
+	}).input(z.object({ params: z.object({ id: z.string().uuid() }) })).output(z.object({ ok: z.literal(true) })),
 	preview: oc.meta(mcpMeta({
 		expose: true,
 		riskLevel: "safe",
@@ -886,8 +1257,9 @@ const validationRules = {
 	get: oc.route({
 		method: "GET",
 		path: "/validation-rules/{id}",
-		summary: "Get validation rule"
-	}).input(z.object({ id: z.string().uuid() })).output(validationRuleOutput),
+		summary: "Get validation rule",
+		inputStructure: "detailed"
+	}).input(z.object({ params: z.object({ id: z.string().uuid() }) })).output(validationRuleOutput),
 	create: oc.route({
 		method: "POST",
 		path: "/validation-rules",
@@ -896,164 +1268,20 @@ const validationRules = {
 	update: oc.route({
 		method: "PATCH",
 		path: "/validation-rules/{id}",
-		summary: "Update validation rule"
+		summary: "Update validation rule",
+		inputStructure: "detailed"
 	}).input(z.object({
-		id: z.string().uuid(),
-		patch: validationRuleUpdateInput
+		params: z.object({ id: z.string().uuid() }),
+		body: z.object({ patch: validationRuleUpdateInput })
 	})).output(validationRuleOutput),
 	delete: oc.route({
 		method: "DELETE",
 		path: "/validation-rules/{id}",
-		summary: "Soft-delete validation rule"
-	}).input(z.object({ id: z.string().uuid() })).output(z.object({ ok: z.literal(true) }))
+		summary: "Soft-delete validation rule",
+		inputStructure: "detailed"
+	}).input(z.object({ params: z.object({ id: z.string().uuid() }) })).output(z.object({ ok: z.literal(true) }))
 };
 //#endregion
-//#region ../contract/src/schemas/voucher.ts
-const voucherType = z.enum(["DISCOUNT", "GIFT_CARD"]);
-const voucherDiscount = z.object({
-	type: z.enum(["AMOUNT", "PERCENTAGE"]),
-	amount: z.number().int().min(0).optional(),
-	percent: z.number().int().min(0).max(1e4).optional(),
-	maxDiscountAmount: z.number().int().min(0).optional(),
-	appliesTo: z.object({
-		productIds: z.array(z.string()).optional(),
-		collectionIds: z.array(z.string()).optional()
-	}).optional()
-});
-const customReward = z.object({
-	typeKey: z.string().min(1),
-	payload: z.record(z.string(), z.unknown())
-});
-const voucherOutput = z.object({
-	id: z.string().uuid(),
-	code: z.string(),
-	campaignId: z.string().uuid().nullable(),
-	type: voucherType,
-	discount: voucherDiscount.nullable(),
-	customRewards: z.array(customReward),
-	giftBalance: z.number().int().nullable(),
-	redemptionLimit: z.number().int().nullable(),
-	redemptionCount: z.number().int(),
-	priority: z.number().int(),
-	exclusive: z.boolean(),
-	active: z.boolean(),
-	startDate: z.string().datetime().nullable(),
-	endDate: z.string().datetime().nullable(),
-	customerId: z.string().uuid().nullable(),
-	metadata: z.record(z.string(), z.unknown()),
-	createdAt: z.string().datetime(),
-	updatedAt: z.string().datetime()
-});
-const voucherCreateInput = z.object({
-	code: z.string().min(1).optional(),
-	campaignId: z.string().uuid().optional(),
-	type: voucherType,
-	discount: voucherDiscount.optional(),
-	customRewards: z.array(customReward).optional(),
-	giftBalance: z.number().int().min(0).optional(),
-	redemptionLimit: z.number().int().min(1).optional(),
-	priority: z.number().int().optional(),
-	exclusive: z.boolean().optional(),
-	startDate: z.string().datetime().optional(),
-	endDate: z.string().datetime().optional(),
-	customerId: z.string().uuid().optional(),
-	metadata: z.record(z.string(), z.unknown()).optional()
-});
-const voucherUpdateInput = voucherCreateInput.omit({
-	type: true,
-	code: true
-}).partial().extend({ active: z.boolean().optional() });
-const voucherBulkCreateInput = z.object({
-	campaignId: z.string().uuid(),
-	count: z.number().int().min(1).max(1e5)
-});
-//#endregion
-//#region ../contract/src/schemas/redemption.ts
-const orderItem$1 = z.object({
-	productId: z.string(),
-	collectionId: z.string().optional(),
-	quantity: z.number().int().min(1),
-	unitPrice: z.number().int().min(0)
-});
-const orderInput = z.object({
-	amount: z.number().int().min(0),
-	currency: z.string().length(3),
-	items: z.array(orderItem$1).optional()
-});
-const validateInput = z.object({
-	code: z.string().min(1),
-	customerId: z.string().uuid().optional(),
-	order: orderInput.optional()
-});
-const redeemInput = validateInput.extend({
-	/** uuid of an `order` row created via the orders API. */
-	orderId: z.string().uuid().optional(),
-	/** Free-form integrator order reference (Shopify id, etc). */
-	externalOrderId: z.string().min(1).max(120).optional(),
-	idempotencyKey: z.string().min(1).max(128).optional()
-});
-const breakdownEntry = z.object({
-	voucherId: z.string().uuid(),
-	code: z.string(),
-	amount: z.number().int(),
-	type: z.enum(["AMOUNT", "PERCENTAGE"]).optional(),
-	reason: z.enum(["exclusivity_lost", "zero_after_running_total"]).optional()
-});
-const validateOutput = z.object({
-	valid: z.boolean(),
-	code: z.string().optional(),
-	message: z.string().optional(),
-	preview: z.object({
-		amount: z.number().int(),
-		finalOrder: z.object({
-			amount: z.number().int(),
-			currency: z.string()
-		}),
-		breakdown: z.array(breakdownEntry)
-	}).optional()
-});
-const redeemOutput = z.object({
-	ok: z.boolean(),
-	redemptionId: z.string().uuid().optional(),
-	amount: z.number().int().optional(),
-	finalOrder: z.object({
-		amount: z.number().int(),
-		currency: z.string()
-	}).optional(),
-	breakdown: z.array(breakdownEntry).optional(),
-	idempotent: z.boolean().optional(),
-	code: z.string().optional(),
-	message: z.string().optional()
-});
-const stackRedeemInput = z.object({
-	codes: z.array(z.string().min(1)).min(1).max(20),
-	customerId: z.string().uuid().optional(),
-	orderId: z.string().uuid().optional(),
-	externalOrderId: z.string().min(1).max(120).optional(),
-	order: orderInput,
-	idempotencyKey: z.string().min(1).max(128).optional()
-});
-const stackEntry = z.object({
-	voucherCode: z.string(),
-	voucherId: z.string().uuid(),
-	redemptionId: z.string().uuid(),
-	amount: z.number().int()
-});
-const stackRedeemOutput = z.object({
-	ok: z.boolean(),
-	batchId: z.string().uuid().optional(),
-	amount: z.number().int().optional(),
-	finalOrder: z.object({
-		amount: z.number().int(),
-		currency: z.string()
-	}).optional(),
-	breakdown: z.array(breakdownEntry).optional(),
-	entries: z.array(stackEntry).optional(),
-	idempotent: z.boolean().optional(),
-	code: z.string().optional(),
-	message: z.string().optional()
-});
-//#endregion
 //#region ../contract/src/routes/vouchers.ts
 const vouchers = {
 	list: oc.meta(mcpMeta({
@@ -1075,8 +1303,9 @@ const vouchers = {
 	})).route({
 		method: "GET",
 		path: "/vouchers/{code}",
-		summary: "Get voucher by code"
-	}).input(z.object({ code: z.string() })).output(voucherOutput),
+		summary: "Get voucher by code",
+		inputStructure: "detailed"
+	}).input(z.object({ params: z.object({ code: z.string() }) })).output(voucherOutput),
 	create: oc.route({
 		method: "POST",
 		path: "/vouchers",
@@ -1085,16 +1314,18 @@ const vouchers = {
 	update: oc.route({
 		method: "PATCH",
 		path: "/vouchers/{code}",
-		summary: "Update voucher"
+		summary: "Update voucher",
+		inputStructure: "detailed"
 	}).input(z.object({
-		code: z.string(),
-		patch: voucherUpdateInput
+		params: z.object({ code: z.string() }),
+		body: z.object({ patch: voucherUpdateInput })
 	})).output(voucherOutput),
 	delete: oc.route({
 		method: "DELETE",
 		path: "/vouchers/{code}",
-		summary: "Soft-delete voucher"
-	}).input(z.object({ code: z.string() })).output(z.object({ ok: z.literal(true) })),
+		summary: "Soft-delete voucher",
+		inputStructure: "detailed"
+	}).input(z.object({ params: z.object({ code: z.string() }) })).output(z.object({ ok: z.literal(true) })),
 	bulk: oc.route({
 		method: "POST",
 		path: "/vouchers/bulk",
@@ -1110,8 +1341,20 @@ const vouchers = {
 	})).route({
 		method: "POST",
 		path: "/vouchers/{code}/validate",
-		summary: "Validate a voucher against an optional order context"
-	}).input(validateInput).output(validateOutput),
+		summary: "Validate a voucher against an optional order context",
+		inputStructure: "detailed"
+	}).input(z.object({
+		params: z.object({ code: z.string().min(1) }),
+		body: validateInput.omit({ code: true }).optional()
+	})).output(validateOutput),
+	qualify: oc.meta(mcpMeta({
+		expose: true,
+		riskLevel: "safe"
+	})).route({
+		method: "POST",
+		path: "/vouchers/qualify",
+		summary: "Batch-qualify customer-held voucher codes for an order"
+	}).input(qualifyInput).output(qualifyOutput),
 	redeem: oc.meta(mcpMeta({
 		expose: true,
 		riskLevel: "mutating",
@@ -1119,8 +1362,12 @@ const vouchers = {
 	})).route({
 		method: "POST",
 		path: "/vouchers/{code}/redemption",
-		summary: "Redeem a voucher"
-	}).input(redeemInput).output(redeemOutput),
+		summary: "Redeem a voucher",
+		inputStructure: "detailed"
+	}).input(z.object({
+		params: z.object({ code: z.string().min(1) }),
+		body: redeemInput.omit({ code: true }).optional()
+	})).output(redeemOutput),
 	stackRedeem: oc.meta(mcpMeta({
 		expose: true,
 		riskLevel: "mutating",
@@ -1133,8 +1380,9 @@ const vouchers = {
 	transactions: oc.route({
 		method: "GET",
 		path: "/vouchers/{code}/transactions",
-		summary: "Gift card balance ledger"
-	}).input(z.object({ code: z.string() })).output(z.object({ data: z.array(z.object({
+		summary: "Gift card balance ledger",
+		inputStructure: "detailed"
+	}).input(z.object({ params: z.object({ code: z.string() }) })).output(z.object({ data: z.array(z.object({
 		id: z.string().uuid(),
 		redemptionId: z.string().uuid().nullable(),
 		delta: z.number().int(),
@@ -1212,8 +1460,9 @@ const webhooks$1 = {
 	get: oc.route({
 		method: "GET",
 		path: "/webhooks/{id}",
-		summary: "Get webhook"
-	}).input(z.object({ id: z.string().uuid() })).output(webhookOutput),
+		summary: "Get webhook",
+		inputStructure: "detailed"
+	}).input(z.object({ params: z.object({ id: z.string().uuid() }) })).output(webhookOutput),
 	create: oc.route({
 		method: "POST",
 		path: "/webhooks",
@@ -1222,29 +1471,33 @@ const webhooks$1 = {
 	update: oc.route({
 		method: "PATCH",
 		path: "/webhooks/{id}",
-		summary: "Update webhook"
+		summary: "Update webhook",
+		inputStructure: "detailed"
 	}).input(z.object({
-		id: z.string().uuid(),
-		patch: webhookUpdateInput
+		params: z.object({ id: z.string().uuid() }),
+		body: z.object({ patch: webhookUpdateInput })
 	})).output(webhookOutput),
 	delete: oc.route({
 		method: "DELETE",
 		path: "/webhooks/{id}",
-		summary: "Soft-delete webhook"
-	}).input(z.object({ id: z.string().uuid() })).output(z.object({ ok: z.literal(true) })),
+		summary: "Soft-delete webhook",
+		inputStructure: "detailed"
+	}).input(z.object({ params: z.object({ id: z.string().uuid() }) })).output(z.object({ ok: z.literal(true) })),
 	deliveries: oc.route({
 		method: "GET",
 		path: "/webhooks/{id}/deliveries",
-		summary: "Recent deliveries for a webhook"
+		summary: "Recent deliveries for a webhook",
+		inputStructure: "detailed"
 	}).input(z.object({
-		id: z.string().uuid(),
-		limit: z.number().int().min(1).max(100).default(50)
+		params: z.object({ id: z.string().uuid() }),
+		query: z.object({ limit: z.number().int().min(1).max(100).default(50) })
 	})).output(z.object({ data: z.array(webhookDeliveryOutput) })),
 	replay: oc.route({
 		method: "POST",
 		path: "/webhooks/deliveries/{id}/replay",
-		summary: "Re-enqueue a delivery (succeeded or otherwise)"
-	}).input(z.object({ id: z.string().uuid() })).output(z.object({ ok: z.literal(true) }))
+		summary: "Re-enqueue a delivery (succeeded or otherwise)",
+		inputStructure: "detailed"
+	}).input(z.object({ params: z.object({ id: z.string().uuid() }) })).output(z.object({ ok: z.literal(true) }))
 };
 const events = {
 	list: oc.route({
@@ -1255,8 +1508,9 @@ const events = {
 	get: oc.route({
 		method: "GET",
 		path: "/events/{id}",
-		summary: "Get event"
-	}).input(z.object({ id: z.string().uuid() })).output(eventOutput)
+		summary: "Get event",
+		inputStructure: "detailed"
+	}).input(z.object({ params: z.object({ id: z.string().uuid() }) })).output(eventOutput)
 };
 //#endregion
 //#region ../contract/src/routes/insights.ts
@@ -1335,26 +1589,30 @@ const users = {
 	resetPassword: oc.route({
 		method: "POST",
 		path: "/users/{id}/reset-password",
-		summary: "Reset a staff user's password (admin)"
-	}).input(z.object({ id: z.string() })).output(userCreateOutput),
+		summary: "Reset a staff user's password (admin)",
+		inputStructure: "detailed"
+	}).input(z.object({ params: z.object({ id: z.string() }) })).output(userCreateOutput),
 	setRole: oc.route({
 		method: "PATCH",
 		path: "/users/{id}/role",
-		summary: "Change a staff user's role (admin)"
+		summary: "Change a staff user's role (admin)",
+		inputStructure: "detailed"
 	}).input(z.object({
-		id: z.string(),
-		role: userRole
+		params: z.object({ id: z.string() }),
+		body: z.object({ role: userRole })
 	})).output(userOutput),
 	disable: oc.route({
 		method: "POST",
 		path: "/users/{id}/disable",
-		summary: "Disable a staff user (admin)"
-	}).input(z.object({ id: z.string() })).output(userOutput),
+		summary: "Disable a staff user (admin)",
+		inputStructure: "detailed"
+	}).input(z.object({ params: z.object({ id: z.string() }) })).output(userOutput),
 	enable: oc.route({
 		method: "POST",
 		path: "/users/{id}/enable",
-		summary: "Re-enable a staff user (admin)"
-	}).input(z.object({ id: z.string() })).output(userOutput)
+		summary: "Re-enable a staff user (admin)",
+		inputStructure: "detailed"
+	}).input(z.object({ params: z.object({ id: z.string() }) })).output(userOutput)
 };
 //#endregion
 //#region ../contract/src/schemas/order.ts
@@ -1420,8 +1678,9 @@ const orders = {
 	get: oc.route({
 		method: "GET",
 		path: "/orders/{id}",
-		summary: "Fetch one order"
-	}).input(z.object({ id: z.string().uuid() })).output(orderOutput),
+		summary: "Fetch one order",
+		inputStructure: "detailed"
+	}).input(z.object({ params: z.object({ id: z.string().uuid() }) })).output(orderOutput),
 	create: oc.route({
 		method: "POST",
 		path: "/orders",
@@ -1430,28 +1689,36 @@ const orders = {
 	update: oc.route({
 		method: "PATCH",
 		path: "/orders/{id}",
-		summary: "Update an order"
-	}).input(orderUpdateInput).output(orderOutput),
+		summary: "Update an order",
+		inputStructure: "detailed"
+	}).input(z.object({
+		params: z.object({ id: z.string().uuid() }),
+		body: orderUpdateInput.omit({ id: true })
+	})).output(orderOutput),
 	cancel: oc.route({
 		method: "POST",
 		path: "/orders/{id}/cancel",
-		summary: "Cancel an order"
-	}).input(z.object({ id: z.string().uuid() })).output(orderOutput),
+		summary: "Cancel an order",
+		inputStructure: "detailed"
+	}).input(z.object({ params: z.object({ id: z.string().uuid() }) })).output(orderOutput),
 	fulfill: oc.route({
 		method: "POST",
 		path: "/orders/{id}/fulfill",
-		summary: "Mark order fulfilled"
-	}).input(z.object({ id: z.string().uuid() })).output(orderOutput),
+		summary: "Mark order fulfilled",
+		inputStructure: "detailed"
+	}).input(z.object({ params: z.object({ id: z.string().uuid() }) })).output(orderOutput),
 	delete: oc.route({
 		method: "DELETE",
 		path: "/orders/{id}",
-		summary: "Soft-delete an order"
-	}).input(z.object({ id: z.string().uuid() })).output(z.object({ ok: z.literal(true) })),
+		summary: "Soft-delete an order",
+		inputStructure: "detailed"
+	}).input(z.object({ params: z.object({ id: z.string().uuid() }) })).output(z.object({ ok: z.literal(true) })),
 	redemptions: oc.route({
 		method: "GET",
 		path: "/orders/{id}/redemptions",
-		summary: "List redemptions attached to an order"
-	}).input(z.object({ id: z.string().uuid() })).output(z.object({ data: z.array(z.object({
+		summary: "List redemptions attached to an order",
+		inputStructure: "detailed"
+	}).input(z.object({ params: z.object({ id: z.string().uuid() }) })).output(z.object({ data: z.array(z.object({
 		id: z.string().uuid(),
 		voucherCode: z.string(),
 		voucherId: z.string().uuid(),
@@ -1556,6 +1823,7 @@ const contract = {
 	customers,
 	segments,
 	campaigns,
+	promotions,
 	vouchers,
 	validationRules,
 	rewardTypes,