Support rebate offers in MCP

[robert-moore]

Review companion — currency-specific rebate caps (re-review) · Derive

What changed

• Add REBATE as an editable offer type in the MCP blueprint tool.
• Support fixed/percentage mode, currency-specific fixed amounts, guarantee windows, and invoice scope.
• Validate three-letter currency codes, non-negative minor-unit amounts, and unique currencies.

Why

The MCP schema previously could not create or update rebate offers. Currency-aware validation keeps MCP writes aligned with the API and admin builder.

Validation

• Full workspace typecheck and pre-push build
• Full SDK test suite, including all 228 MCP tests
• Biome pre-commit check

[hookdump]

Quick context: rebate MCP support was one of a few things that existed in the original feature branches but silently never made it to main when the @churnkey/mcp overhaul got re-sliced into stacked PRs (the reslices were validated against the combined overhaul branch, not the feature branches). So this PR isn't a duplicate — the schema really is missing from main. I opened #38 to restore the other casualties (create_blueprint, create_segment_flow, archive_segment, list_segment_attributes, confirmLiveChange) but deliberately left rebate out, deferring to this PR — your currency-specific fixedAmounts is strictly better than the original single-customAmount. (Full write-up.)

A few things worth a quick confirm before merge:

1. Stacking on churnkey-api#953. Just confirming this lands after it — API master still only accepts the old customAmount, not fixedAmounts. (Assume you're already on it.)

2. MCP docs. The MCP reference page (churnkey-docs → content/6.data-integrations/5.mcp.md:163) still documented rebate with the old customAmount schema (your churnkey-docs#120 updates the cancel-flow feature page, not this one). I've stacked churnkey-docs#121 on top of #120 to update it to the currency-specific fixedAmounts schema, so the whole rebate-caps doc set lands together — it'll retarget to master cleanly if #120 merges first.

3. Minor overlap with #38. It also touches blueprints.ts but a different region (adds a create_blueprint block vs. your offerConfig/offerType), so whoever lands second gets a clean little rebase. No action needed.

[hookdump]

Schema's clean and forward-correct — the zod rebate config matches the API's new contract exactly: amountType FIXED|PERCENT, fixedAmounts: [{ currency, amountMinor }], percentAmount 0–100, mbgWindowDays, invoiceScope FIRST_PAID|LATEST_PAID. Currency handling (/^[A-Za-z]{3}$/ + lowercase) matches the API's lowercase expectation, the uniqueness refine and .strict() mirror the server checks, and REBATE slots into the offerType enum without touching the existing DISCOUNT/customAmount path. 👍

The one that matters (you know this — it's the whole point of the stack): this sends fixedAmounts, which API master rejects until churnkey-api#953 deploys — so ship this after that, or every fixed-currency rebate 422s. Ordering, not a code issue.

Nits, non-blocking:

• Tests are fully mocked, so they can't catch that contract drift and skip the failure modes (negative amountMinor, percentAmount > 100, empty fixedAmounts) — worth a couple of schema-rejection cases.
• amountMinor uses .int() vs the API's safe-integer check — only matters above 2^53, so negligible.

Approving 🚀 (ship after the API PR deploys)