@offerkit/sdk 0.2.0 → 0.2.3

package/dist/index.mjs

@@ -738,6 +738,331 @@ 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"
+		}).input(z.object({
+			id: z.string().uuid(),
+			patch: promotionTierUpdateInput
+		})).output(promotionTierOutput),
+		delete: oc.route({
+			method: "DELETE",
+			path: "/promotions/tiers/{id}",
+			summary: "Soft-delete promotion tier"
+		}).input(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(),
@@ -908,152 +1233,6 @@ const validationRules = {
 	}).input(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({
@@ -1112,6 +1291,14 @@ const vouchers = {
 		path: "/vouchers/{code}/validate",
 		summary: "Validate a voucher against an optional order context"
 	}).input(validateInput).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",
@@ -1556,6 +1743,7 @@ const contract = {
 	customers,
 	segments,
 	campaigns,
+	promotions,
 	vouchers,
 	validationRules,
 	rewardTypes,