feat: add list_customers tool with metadata filtering

[ignaciomendeznole]

Summary

• Adds list_customers MCP tool — search/filter customers by metadata fields and standard fields (name, email, source_id, created_at) with pagination
• Adds list_vouchers MCP tool — search/filter vouchers by holder_id, campaign_id, is_referral_code, type, active, and metadata fields with pagination
• Adds list_voucher_redemptions MCP tool — list all redemptions for a voucher code, returning the customer who redeemed it for each entry
• All three tools are read-only, consistent with all other tools

Motivation

• find_customer only supports lookup by email or ID — no way to search/filter by metadata
• No way to list vouchers for a customer — the qualifications API doesn't surface referral codes owned by the customer as a referrer
• No way to see who redeemed a specific voucher code — needed to trace redemption activity

New Tools

list_customers

Paginated customer search with flexible metadata filtering. Mirrors list_products filter structure.

# Find customers by metadata
list_customers(filters={
    "metadata.club": {"conditions": {"$is": "VIP-Warsaw"}}
})

# Multiple metadata filters
list_customers(filters={
    "metadata.foo": {"conditions": {"$is": "bar"}},
    "metadata.club": {"conditions": {"$is": "Katowice"}}
})

list_vouchers

Paginated voucher search with filtering by holder, campaign, type, referral status, and metadata.

# Find all vouchers held by a customer
list_vouchers(filters={
    "holder_id": {"conditions": {"$is": "cust_abc123"}}
})

# Find referral codes for a customer
list_vouchers(filters={
    "holder_id": {"conditions": {"$is": "cust_abc123"}},
    "is_referral_code": {"conditions": {"$is": true}}
})

# Find vouchers in a campaign
list_vouchers(filters={
    "campaign_id": {"conditions": {"$is": "camp_abc123"}}
})

list_voucher_redemptions

Paginated redemption history for a voucher code. Each redemption includes the customer who redeemed it.

list_voucher_redemptions(code="WELCOME10")

Implementation

• All three tools reuse existing dict_to_querystring() and async_make_voucherify_request() infrastructure
• list_customers calls GET /v1/customers with filter query parameters
• list_vouchers calls GET /v1/vouchers with filter query parameters
• list_voucher_redemptions calls GET /v1/vouchers/{code}/redemptions

Test Plan

• scenario_7_list_customers.py — single metadata filter + multiple metadata filters
• scenario_8_list_vouchers.py — filter by holder_id + filter by campaign_id
• Manual verification of list_voucher_redemptions against sandbox

🤖 Generated with Claude Code