@armor/zuora-mcp 1.0.1

package/dist/tools.js

@@ -0,0 +1,1336 @@
+/**
+ * MCP Tool Definitions for Zuora Billing Operations
+ * Provides account, invoice, subscription, payment, and ZOQL query tools
+ */
+import { z } from "zod";
+// ==================== Helpers ====================
+function isValidCalendarDate(dateStr) {
+    const [year, month, day] = dateStr.split("-").map(Number);
+    const date = new Date(year, month - 1, day);
+    return (date.getFullYear() === year &&
+        date.getMonth() === month - 1 &&
+        date.getDate() === day);
+}
+// ==================== Shared Schemas ====================
+/** Contact fields for account creation (name + email required) */
+const contactSchema = z.object({
+    firstName: z.string().min(1).max(100).describe("First name"),
+    lastName: z.string().min(1).max(100).describe("Last name"),
+    workEmail: z.string().email("Must be a valid email address").describe("Work email address"),
+    address1: z.string().max(255).optional().describe("Street address line 1"),
+    city: z.string().max(100).optional().describe("City"),
+    state: z.string().max(100).optional().describe("State or province"),
+    postalCode: z.string().max(20).optional().describe("Postal/ZIP code"),
+    country: z.string().max(100).optional().describe("Country (ISO 3166 name or code)"),
+});
+/** Contact fields for account updates (all fields optional for partial updates) */
+const partialContactSchema = contactSchema.partial();
+// ==================== Input Schemas ====================
+export const schemas = {
+    // Account Tools
+    getAccount: z.object({
+        accountKey: z
+            .string()
+            .min(1)
+            .describe("Account ID or account number (e.g., 2c92c0f8..., or A00000001)"),
+    }),
+    getAccountSummary: z.object({
+        accountKey: z
+            .string()
+            .min(1)
+            .describe("Account ID or account number"),
+    }),
+    // Invoice Tools
+    getInvoice: z.object({
+        invoiceId: z
+            .string()
+            .min(1)
+            .describe("Invoice ID (e.g., 2c92c0f8...)"),
+    }),
+    listInvoices: z.object({
+        accountKey: z
+            .string()
+            .min(1)
+            .describe("Account ID or account number to list invoices for"),
+        page: z
+            .number()
+            .int()
+            .min(1)
+            .default(1)
+            .describe("Page number (default: 1)"),
+        pageSize: z
+            .number()
+            .int()
+            .min(1)
+            .max(40)
+            .default(20)
+            .describe("Records per page (default: 20, max: 40)"),
+    }),
+    // Subscription Tools
+    getSubscription: z.object({
+        subscriptionKey: z
+            .string()
+            .min(1)
+            .describe("Subscription key or ID (e.g., A-S00000001)"),
+    }),
+    listSubscriptions: z.object({
+        accountKey: z
+            .string()
+            .min(1)
+            .describe("Account ID or account number"),
+    }),
+    // Payment Tools
+    getPayment: z.object({
+        paymentId: z.string().min(1).describe("Payment ID"),
+    }),
+    listPayments: z.object({
+        accountKey: z
+            .string()
+            .optional()
+            .describe("Account key to filter payments (optional, lists all if omitted)"),
+        page: z
+            .number()
+            .int()
+            .min(1)
+            .default(1)
+            .describe("Page number (default: 1)"),
+        pageSize: z
+            .number()
+            .int()
+            .min(1)
+            .max(40)
+            .default(20)
+            .describe("Records per page (default: 20, max: 40)"),
+    }),
+    // ZOQL Query Tools
+    executeZoqlQuery: z.object({
+        zoqlQuery: z
+            .string()
+            .min(1)
+            .max(10000)
+            .refine((q) => /^\s*SELECT\s+/i.test(q), {
+            message: "ZOQL query must begin with SELECT",
+        })
+            .describe("ZOQL (Zuora Object Query Language) query string. " +
+            "Syntax: SELECT field1, field2 FROM ObjectName WHERE condition. " +
+            "Key objects: Account, Invoice, Payment, Subscription, RatePlan, " +
+            "RatePlanCharge, Product, ProductRatePlan, Contact. " +
+            "Limitations: No JOINs. Max 2000 records per call. " +
+            "Use continue_zoql_query with queryLocator for pagination. " +
+            "Example: SELECT Id, AccountNumber, Balance FROM Account WHERE Status = 'Active'"),
+    }),
+    continueZoqlQuery: z.object({
+        queryLocator: z
+            .string()
+            .min(1)
+            .describe("Query locator from a previous ZOQL query result for pagination"),
+    }),
+    // Product Catalog Tools
+    listProducts: z.object({
+        page: z
+            .number()
+            .int()
+            .min(1)
+            .default(1)
+            .describe("Page number (default: 1)"),
+        pageSize: z
+            .number()
+            .int()
+            .min(1)
+            .max(40)
+            .default(20)
+            .describe("Records per page (default: 20, max: 40)"),
+    }),
+    // Phase 2: Extended Read Tools
+    getInvoiceFiles: z.object({
+        invoiceId: z
+            .string()
+            .min(1)
+            .describe("Invoice ID to retrieve associated PDF files for"),
+    }),
+    getCreditMemo: z.object({
+        creditMemoId: z
+            .string()
+            .min(1)
+            .describe("Credit memo ID (e.g., 2c92c0f8...)"),
+    }),
+    listCreditMemos: z.object({
+        accountId: z
+            .string()
+            .optional()
+            .describe("Zuora account UUID (e.g., 2c92c0f8...) to filter credit memos. " +
+            "Use get_account to retrieve the account ID from an account number. " +
+            "Optional; lists all if omitted."),
+        page: z
+            .number()
+            .int()
+            .min(1)
+            .default(1)
+            .describe("Page number (default: 1)"),
+        pageSize: z
+            .number()
+            .int()
+            .min(1)
+            .max(40)
+            .default(20)
+            .describe("Records per page (default: 20, max: 40)"),
+    }),
+    searchAccounts: z.object({
+        field: z
+            .enum([
+            "Name",
+            "AccountNumber",
+            "Status",
+            "Currency",
+            "Balance",
+        ])
+            .describe("Account field to search by (Name, AccountNumber, Status, Currency, Balance)"),
+        value: z
+            .string()
+            .min(1)
+            .max(255)
+            .refine((v) => /[^%_]/.test(v), {
+            message: "Value must contain at least one non-wildcard character",
+        })
+            .describe("Value to search for"),
+        operator: z
+            .enum(["=", "!=", "LIKE", ">", "<", ">=", "<="])
+            .default("=")
+            .describe("Comparison operator (default: =). Use LIKE for partial name matches with % wildcard."),
+    }),
+    listUsage: z.object({
+        accountKey: z
+            .string()
+            .min(1)
+            .describe("Account ID or account number to retrieve usage records for"),
+        page: z
+            .number()
+            .int()
+            .min(1)
+            .default(1)
+            .describe("Page number (default: 1)"),
+        pageSize: z
+            .number()
+            .int()
+            .min(1)
+            .max(40)
+            .default(20)
+            .describe("Records per page (default: 20, max: 40)"),
+    }),
+    // Phase 3: Write Operations
+    createPayment: z.object({
+        accountId: z
+            .string()
+            .min(1)
+            .describe("Zuora account UUID to create the payment for"),
+        amount: z
+            .number()
+            .positive()
+            .max(1_000_000)
+            .refine((n) => Math.round(n * 100) === n * 100, "Amount must have at most 2 decimal places")
+            .describe("Payment amount (positive, max 1,000,000, up to 2 decimal places)"),
+        effectiveDate: z
+            .string()
+            .regex(/^\d{4}-\d{2}-\d{2}$/, "Date must be YYYY-MM-DD format")
+            .refine(isValidCalendarDate, "Must be a valid calendar date")
+            .describe("Payment effective date in YYYY-MM-DD format"),
+        type: z
+            .enum(["Electronic", "External"])
+            .describe("Payment type: Electronic (gateway) or External (check, wire, etc.)"),
+        paymentMethodId: z
+            .string()
+            .optional()
+            .describe("Payment method ID. Required for Electronic type. " +
+            "Use get_account to find available payment methods."),
+        comment: z
+            .string()
+            .max(1000)
+            .optional()
+            .describe("Optional comment for the payment record"),
+        idempotencyKey: z
+            .string()
+            .uuid("Idempotency key must be a valid UUID")
+            .describe("UUID to prevent duplicate payments on retries. " +
+            "Generate a new UUID v4 for each distinct payment intent."),
+    }).superRefine((data, ctx) => {
+        if (data.type === "Electronic" && !data.paymentMethodId) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ["paymentMethodId"],
+                message: "paymentMethodId is required when type is Electronic",
+            });
+        }
+    }),
+    applyPayment: z.object({
+        paymentId: z
+            .string()
+            .min(1)
+            .describe("ID of the unapplied payment to apply to invoices"),
+        invoices: z
+            .array(z.object({
+            invoiceId: z.string().min(1).describe("Invoice ID to apply payment to"),
+            amount: z
+                .number()
+                .positive()
+                .max(1_000_000)
+                .refine((n) => Math.round(n * 100) === n * 100, "Amount must have at most 2 decimal places")
+                .describe("Amount to apply to this invoice"),
+        }))
+            .min(1)
+            .max(50)
+            .describe("Invoice allocations: which invoices to apply the payment to and how much. " +
+            "Max 50 per call; split larger batches into multiple calls."),
+        effectiveDate: z
+            .string()
+            .regex(/^\d{4}-\d{2}-\d{2}$/, "Date must be YYYY-MM-DD format")
+            .refine(isValidCalendarDate, "Must be a valid calendar date")
+            .optional()
+            .describe("Effective date for the application in YYYY-MM-DD format (optional)"),
+    }),
+    createInvoice: z.object({
+        accountId: z
+            .string()
+            .min(1)
+            .describe("Zuora account UUID to create the invoice for"),
+        invoiceDate: z
+            .string()
+            .regex(/^\d{4}-\d{2}-\d{2}$/, "Date must be YYYY-MM-DD format")
+            .refine(isValidCalendarDate, "Must be a valid calendar date")
+            .describe("Invoice date in YYYY-MM-DD format"),
+        dueDate: z
+            .string()
+            .regex(/^\d{4}-\d{2}-\d{2}$/, "Date must be YYYY-MM-DD format")
+            .refine(isValidCalendarDate, "Must be a valid calendar date")
+            .optional()
+            .describe("Due date in YYYY-MM-DD format (optional, uses payment terms if omitted)"),
+        idempotencyKey: z
+            .string()
+            .uuid("Idempotency key must be a valid UUID")
+            .describe("UUID to prevent duplicate invoice creation on retries. " +
+            "Generate a new UUID v4 for each distinct invoice intent."),
+    }),
+    postInvoice: z.object({
+        invoiceId: z
+            .string()
+            .min(1)
+            .describe("ID of the draft invoice to post. " +
+            "Once posted, the invoice is immutable and affects account balance."),
+    }),
+    cancelSubscription: z.object({
+        subscriptionKey: z
+            .string()
+            .min(1)
+            .describe("Subscription key or ID (e.g., A-S00000001) to cancel"),
+        cancellationPolicy: z
+            .enum(["EndOfCurrentTerm", "EndOfLastInvoicePeriod", "SpecificDate"])
+            .describe("When the cancellation takes effect: " +
+            "EndOfCurrentTerm (cancel at term end), " +
+            "EndOfLastInvoicePeriod (cancel at end of last billed period), " +
+            "SpecificDate (cancel on a specific date, requires cancellationEffectiveDate)"),
+        cancellationEffectiveDate: z
+            .string()
+            .regex(/^\d{4}-\d{2}-\d{2}$/, "Date must be YYYY-MM-DD format")
+            .refine(isValidCalendarDate, "Must be a valid calendar date")
+            .optional()
+            .describe("Required when cancellationPolicy is SpecificDate. The date cancellation takes effect."),
+        invoiceCollect: z
+            .boolean()
+            .default(false)
+            .describe("Whether to generate and collect an invoice for the cancellation charges (default: false)"),
+    }).superRefine((data, ctx) => {
+        if (data.cancellationPolicy === "SpecificDate" && !data.cancellationEffectiveDate) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ["cancellationEffectiveDate"],
+                message: "cancellationEffectiveDate is required when cancellationPolicy is SpecificDate",
+            });
+        }
+    }),
+    // Phase 4: Advanced Operations
+    createSubscription: z.object({
+        accountKey: z
+            .string()
+            .min(1)
+            .describe("Account ID or account number to create the subscription for"),
+        contractEffectiveDate: z
+            .string()
+            .regex(/^\d{4}-\d{2}-\d{2}$/, "Date must be YYYY-MM-DD format")
+            .refine(isValidCalendarDate, "Must be a valid calendar date")
+            .describe("Date the subscription contract takes effect in YYYY-MM-DD format"),
+        serviceActivationDate: z
+            .string()
+            .regex(/^\d{4}-\d{2}-\d{2}$/, "Date must be YYYY-MM-DD format")
+            .refine(isValidCalendarDate, "Must be a valid calendar date")
+            .optional()
+            .describe("Date the subscription service is activated (optional). " +
+            "Required if the Zuora tenant has 'Require Service Activation' enabled."),
+        customerAcceptanceDate: z
+            .string()
+            .regex(/^\d{4}-\d{2}-\d{2}$/, "Date must be YYYY-MM-DD format")
+            .refine(isValidCalendarDate, "Must be a valid calendar date")
+            .optional()
+            .describe("Date the customer accepted the subscription (optional). " +
+            "Required if the Zuora tenant has 'Require Customer Acceptance' enabled."),
+        termType: z
+            .enum(["TERMED", "EVERGREEN"])
+            .describe("Subscription term type: TERMED (fixed duration) or EVERGREEN (no end date)"),
+        initialTerm: z
+            .number()
+            .int()
+            .positive()
+            .max(1200)
+            .optional()
+            .describe("Initial term length (required for TERMED). Max 1200."),
+        initialTermPeriodType: z
+            .enum(["Month", "Year", "Day", "Week"])
+            .optional()
+            .describe("Period type for the initial term (required for TERMED)"),
+        renewalTerm: z
+            .number()
+            .int()
+            .positive()
+            .max(1200)
+            .optional()
+            .describe("Renewal term length (optional)"),
+        renewalTermPeriodType: z
+            .enum(["Month", "Year", "Day", "Week"])
+            .optional()
+            .describe("Period type for the renewal term"),
+        autoRenew: z
+            .boolean()
+            .default(false)
+            .describe("Whether the subscription auto-renews at term end (default: false)"),
+        subscribeToRatePlans: z
+            .array(z.object({
+            productRatePlanId: z
+                .string()
+                .min(1)
+                .describe("Product rate plan ID from the product catalog"),
+        }))
+            .min(1)
+            .max(50)
+            .describe("Rate plans to subscribe to. Use list_products to find productRatePlanIds. " +
+            "At least 1, max 50 per call."),
+        notes: z
+            .string()
+            .max(2000)
+            .optional()
+            .describe("Optional notes for the subscription"),
+        idempotencyKey: z
+            .string()
+            .uuid("Idempotency key must be a valid UUID")
+            .describe("UUID to prevent duplicate subscriptions on retries. " +
+            "Generate a new UUID v4 for each distinct subscription intent."),
+    }).superRefine((data, ctx) => {
+        if (data.termType === "TERMED" && !data.initialTerm) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ["initialTerm"],
+                message: "initialTerm is required when termType is TERMED",
+            });
+        }
+        if (data.termType === "TERMED" && !data.initialTermPeriodType) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ["initialTermPeriodType"],
+                message: "initialTermPeriodType is required when termType is TERMED",
+            });
+        }
+        if ((data.renewalTerm !== undefined) !== (data.renewalTermPeriodType !== undefined)) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: [data.renewalTerm !== undefined ? "renewalTermPeriodType" : "renewalTerm"],
+                message: "renewalTerm and renewalTermPeriodType must be provided together",
+            });
+        }
+    }),
+    updateSubscription: z.object({
+        subscriptionKey: z
+            .string()
+            .min(1)
+            .describe("Subscription key or ID to update (e.g., A-S00000001)"),
+        autoRenew: z
+            .boolean()
+            .optional()
+            .describe("Whether the subscription auto-renews at term end"),
+        renewalTerm: z
+            .number()
+            .int()
+            .positive()
+            .max(1200)
+            .optional()
+            .describe("Renewal term length"),
+        renewalTermPeriodType: z
+            .enum(["Month", "Year", "Day", "Week"])
+            .optional()
+            .describe("Period type for the renewal term"),
+        notes: z
+            .string()
+            .max(2000)
+            .optional()
+            .describe("Notes for the subscription"),
+    }).superRefine((data, ctx) => {
+        const { subscriptionKey: _, ...updateFields } = data;
+        const hasUpdate = Object.values(updateFields).some((v) => v !== undefined);
+        if (!hasUpdate) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: [],
+                message: "At least one field to update must be provided (autoRenew, renewalTerm, renewalTermPeriodType, or notes)",
+            });
+        }
+        if ((data.renewalTerm !== undefined) !== (data.renewalTermPeriodType !== undefined)) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: [data.renewalTerm !== undefined ? "renewalTermPeriodType" : "renewalTerm"],
+                message: "renewalTerm and renewalTermPeriodType must be provided together",
+            });
+        }
+    }),
+    createAccount: z.object({
+        name: z
+            .string()
+            .min(1)
+            .max(255)
+            .describe("Account name"),
+        currency: z
+            .string()
+            .regex(/^[A-Z]{3}$/, "Currency must be a 3-letter ISO 4217 code (e.g., USD, EUR)")
+            .describe("ISO 4217 currency code (e.g., USD, EUR, GBP)"),
+        billCycleDay: z
+            .number()
+            .int()
+            .min(1)
+            .max(31)
+            .describe("Day of month for billing cycle (1-31). Zuora normalizes values beyond a month's last day."),
+        billToContact: contactSchema
+            .describe("Bill-to contact information (required)"),
+        soldToContact: contactSchema
+            .optional()
+            .describe("Sold-to contact information (optional, defaults to bill-to if omitted)"),
+        paymentTerm: z
+            .string()
+            .max(100)
+            .optional()
+            .describe("Payment terms (e.g., 'Net 30', 'Due Upon Receipt')"),
+        autoPay: z
+            .boolean()
+            .default(false)
+            .describe("Whether to auto-collect payments (default: false)"),
+        notes: z
+            .string()
+            .max(2000)
+            .optional()
+            .describe("Optional account notes"),
+        idempotencyKey: z
+            .string()
+            .uuid("Idempotency key must be a valid UUID")
+            .describe("UUID to prevent duplicate account creation on retries. " +
+            "Generate a new UUID v4 for each distinct account intent."),
+    }),
+    updateAccount: z.object({
+        accountKey: z
+            .string()
+            .min(1)
+            .describe("Account ID or account number to update"),
+        name: z
+            .string()
+            .min(1)
+            .max(255)
+            .optional()
+            .describe("Updated account name"),
+        notes: z
+            .string()
+            .max(2000)
+            .optional()
+            .describe("Updated account notes"),
+        autoPay: z
+            .boolean()
+            .optional()
+            .describe("Whether to auto-collect payments"),
+        paymentTerm: z
+            .string()
+            .max(100)
+            .optional()
+            .describe("Updated payment terms (e.g., 'Net 30')"),
+        billToContact: partialContactSchema
+            .optional()
+            .describe("Updated bill-to contact fields (only include fields to change)"),
+        soldToContact: partialContactSchema
+            .optional()
+            .describe("Updated sold-to contact fields (only include fields to change)"),
+    }).superRefine((data, ctx) => {
+        const { accountKey: _, ...updateFields } = data;
+        const hasUpdate = Object.values(updateFields).some((v) => v !== undefined);
+        if (!hasUpdate) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: [],
+                message: "At least one field to update must be provided",
+            });
+        }
+    }),
+    createRefund: z.object({
+        paymentId: z
+            .string()
+            .min(1)
+            .describe("ID of the original payment to refund. " +
+            "Use get_payment to verify the payment exists and has sufficient applied amount."),
+        amount: z
+            .number()
+            .positive()
+            .max(1_000_000)
+            .refine((n) => Math.round(n * 100) === n * 100, "Amount must have at most 2 decimal places")
+            .describe("Refund amount (positive, max 1,000,000, up to 2 decimal places)"),
+        type: z
+            .enum(["Electronic", "External"])
+            .describe("Refund type: Electronic (refund via payment gateway) or External (manual refund record)"),
+        comment: z
+            .string()
+            .max(1000)
+            .optional()
+            .describe("Optional reason/comment for the refund"),
+        idempotencyKey: z
+            .string()
+            .uuid("Idempotency key must be a valid UUID")
+            .describe("UUID to prevent duplicate refunds on retries. " +
+            "Generate a new UUID v4 for each distinct refund intent."),
+    }),
+};
+// ==================== Tool Handlers ====================
+export class ToolHandlers {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    // --- Account Handlers ---
+    async getAccount(input) {
+        try {
+            const { accountKey } = schemas.getAccount.parse(input);
+            const account = await this.client.getAccount(accountKey);
+            return {
+                success: true,
+                message: `Retrieved account ${accountKey}`,
+                data: account,
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                message: `Failed to get account: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
+    async getAccountSummary(input) {
+        try {
+            const { accountKey } = schemas.getAccountSummary.parse(input);
+            const summary = await this.client.getAccountSummary(accountKey);
+            return {
+                success: true,
+                message: `Retrieved account summary for ${accountKey}`,
+                data: summary,
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                message: `Failed to get account summary: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
+    // --- Invoice Handlers ---
+    async getInvoice(input) {
+        try {
+            const { invoiceId } = schemas.getInvoice.parse(input);
+            const invoice = await this.client.getInvoice(invoiceId);
+            return {
+                success: true,
+                message: `Retrieved invoice ${invoice.invoiceNumber ?? invoiceId}`,
+                data: invoice,
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                message: `Failed to get invoice: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
+    async listInvoices(input) {
+        try {
+            const { accountKey, page, pageSize } = schemas.listInvoices.parse(input);
+            const result = await this.client.listInvoices(accountKey, page, pageSize);
+            const count = result.invoices?.length ?? 0;
+            return {
+                success: true,
+                message: `Found ${count} invoice(s) for account ${accountKey}`,
+                data: result,
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                message: `Failed to list invoices: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
+    // --- Subscription Handlers ---
+    async getSubscription(input) {
+        try {
+            const { subscriptionKey } = schemas.getSubscription.parse(input);
+            const subscription = await this.client.getSubscription(subscriptionKey);
+            return {
+                success: true,
+                message: `Retrieved subscription ${subscription.subscriptionNumber ?? subscriptionKey}`,
+                data: subscription,
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                message: `Failed to get subscription: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
+    async listSubscriptions(input) {
+        try {
+            const { accountKey } = schemas.listSubscriptions.parse(input);
+            const result = await this.client.listSubscriptionsByAccount(accountKey);
+            const count = result.subscriptions?.length ?? 0;
+            return {
+                success: true,
+                message: `Found ${count} subscription(s) for account ${accountKey}`,
+                data: result,
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                message: `Failed to list subscriptions: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
+    // --- Payment Handlers ---
+    async getPayment(input) {
+        try {
+            const { paymentId } = schemas.getPayment.parse(input);
+            const payment = await this.client.getPayment(paymentId);
+            return {
+                success: true,
+                message: `Retrieved payment ${payment.paymentNumber ?? paymentId}`,
+                data: payment,
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                message: `Failed to get payment: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
+    async listPayments(input) {
+        try {
+            const { accountKey, page, pageSize } = schemas.listPayments.parse(input);
+            const result = accountKey
+                ? await this.client.listPaymentsByAccount(accountKey, page, pageSize)
+                : await this.client.listPayments(page, pageSize);
+            const count = result.payments?.length ?? 0;
+            const scope = accountKey
+                ? ` for account ${accountKey}`
+                : "";
+            return {
+                success: true,
+                message: `Found ${count} payment(s)${scope}`,
+                data: result,
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                message: `Failed to list payments: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
+    // --- ZOQL Query Handlers ---
+    async executeZoqlQuery(input) {
+        try {
+            const { zoqlQuery } = schemas.executeZoqlQuery.parse(input);
+            const result = await this.client.executeQuery(zoqlQuery);
+            const moreAvailable = result.queryLocator
+                ? " (more available via continue_zoql_query)"
+                : "";
+            return {
+                success: true,
+                message: `Query returned ${result.records?.length ?? 0} record(s)${moreAvailable}`,
+                data: result,
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                message: `ZOQL query failed: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
+    async continueZoqlQuery(input) {
+        try {
+            const { queryLocator } = schemas.continueZoqlQuery.parse(input);
+            const result = await this.client.queryMore(queryLocator);
+            const moreAvailable = result.queryLocator
+                ? " (more available)"
+                : "";
+            return {
+                success: true,
+                message: `Continuation returned ${result.records?.length ?? 0} record(s)${moreAvailable}`,
+                data: result,
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                message: `ZOQL continuation failed: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
+    // --- Product Catalog Handlers ---
+    async listProducts(input) {
+        try {
+            const { page, pageSize } = schemas.listProducts.parse(input);
+            const result = await this.client.listProducts(page, pageSize);
+            const count = result.products?.length ?? 0;
+            return {
+                success: true,
+                message: `Found ${count} product(s)`,
+                data: result,
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                message: `Failed to list products: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
+    // --- Phase 2: Extended Read Handlers ---
+    async getInvoiceFiles(input) {
+        try {
+            const { invoiceId } = schemas.getInvoiceFiles.parse(input);
+            const result = await this.client.getInvoiceFiles(invoiceId);
+            const count = result.invoiceFiles?.length ?? 0;
+            return {
+                success: true,
+                message: `Found ${count} file(s) for invoice ${invoiceId}`,
+                data: result,
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                message: `Failed to get invoice files: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
+    async getCreditMemo(input) {
+        try {
+            const { creditMemoId } = schemas.getCreditMemo.parse(input);
+            const creditMemo = await this.client.getCreditMemo(creditMemoId);
+            return {
+                success: true,
+                message: `Retrieved credit memo ${creditMemo.number ?? creditMemoId}`,
+                data: creditMemo,
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                message: `Failed to get credit memo: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
+    async listCreditMemos(input) {
+        try {
+            const { accountId, page, pageSize } = schemas.listCreditMemos.parse(input);
+            const result = await this.client.listCreditMemos(accountId, page, pageSize);
+            const count = result.creditMemos?.length ?? 0;
+            const scope = accountId ? ` for account ${accountId}` : "";
+            return {
+                success: true,
+                message: `Found ${count} credit memo(s)${scope}`,
+                data: result,
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                message: `Failed to list credit memos: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
+    async searchAccounts(input) {
+        try {
+            const { field, value, operator } = schemas.searchAccounts.parse(input);
+            const result = await this.client.searchAccounts(field, value, operator);
+            const count = result.records?.length ?? 0;
+            return {
+                success: true,
+                message: `Found ${count} account(s) matching search criteria`,
+                data: result,
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                message: `Failed to search accounts: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
+    async listUsage(input) {
+        try {
+            const { accountKey, page, pageSize } = schemas.listUsage.parse(input);
+            const result = await this.client.listUsage(accountKey, page, pageSize);
+            const count = result.usage?.length ?? 0;
+            return {
+                success: true,
+                message: `Found ${count} usage record(s) for account ${accountKey}`,
+                data: result,
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                message: `Failed to get usage: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
+    // --- Phase 3: Write Operation Handlers ---
+    async createPayment(input) {
+        try {
+            const { idempotencyKey, ...paymentData } = schemas.createPayment.parse(input);
+            const result = await this.client.createPayment(paymentData, idempotencyKey);
+            return {
+                success: true,
+                message: `Created payment ${result.paymentNumber} successfully`,
+                data: result,
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                message: `Failed to create payment: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
+    async applyPayment(input) {
+        try {
+            const { paymentId, invoices, effectiveDate } = schemas.applyPayment.parse(input);
+            const result = await this.client.applyPayment(paymentId, {
+                invoices,
+                effectiveDate,
+            });
+            return {
+                success: true,
+                message: `Applied payment ${result.paymentNumber} successfully`,
+                data: result,
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                message: `Failed to apply payment: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
+    async createInvoice(input) {
+        try {
+            const { idempotencyKey, ...invoiceData } = schemas.createInvoice.parse(input);
+            const result = await this.client.createInvoice(invoiceData, idempotencyKey);
+            return {
+                success: true,
+                message: `Created draft invoice ${result.invoiceNumber} for account ${invoiceData.accountId}`,
+                data: result,
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                message: `Failed to create invoice: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
+    async postInvoice(input) {
+        try {
+            const { invoiceId } = schemas.postInvoice.parse(input);
+            const result = await this.client.postInvoice(invoiceId);
+            return {
+                success: true,
+                message: `Posted invoice ${result.invoiceNumber} (status: ${result.status})`,
+                data: result,
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                message: `Failed to post invoice: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
+    async cancelSubscription(input) {
+        try {
+            const { subscriptionKey, ...cancellationData } = schemas.cancelSubscription.parse(input);
+            const result = await this.client.cancelSubscription(subscriptionKey, cancellationData);
+            return {
+                success: true,
+                message: `Cancelled subscription ${subscriptionKey} (id: ${result.subscriptionId}) effective ${result.cancelledDate}`,
+                data: result,
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                message: `Failed to cancel subscription: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
+    // --- Phase 4: Advanced Operation Handlers ---
+    async createSubscription(input) {
+        try {
+            const { idempotencyKey, ...subscriptionData } = schemas.createSubscription.parse(input);
+            const result = await this.client.createSubscription(subscriptionData, idempotencyKey);
+            return {
+                success: true,
+                message: `Created subscription ${result.subscriptionNumber} for account ${subscriptionData.accountKey}`,
+                data: result,
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                message: `Failed to create subscription: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
+    async updateSubscription(input) {
+        try {
+            const { subscriptionKey, ...updateData } = schemas.updateSubscription.parse(input);
+            const result = await this.client.updateSubscription(subscriptionKey, updateData);
+            return {
+                success: true,
+                message: `Updated subscription ${subscriptionKey} (id: ${result.subscriptionId})`,
+                data: result,
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                message: `Failed to update subscription: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
+    async createAccount(input) {
+        try {
+            const { idempotencyKey, ...accountData } = schemas.createAccount.parse(input);
+            const result = await this.client.createAccount(accountData, idempotencyKey);
+            return {
+                success: true,
+                message: `Created account ${result.accountNumber} (id: ${result.accountId})`,
+                data: result,
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                message: `Failed to create account: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
+    async updateAccount(input) {
+        try {
+            const { accountKey, ...updateData } = schemas.updateAccount.parse(input);
+            const result = await this.client.updateAccount(accountKey, updateData);
+            return {
+                success: true,
+                message: `Updated account ${accountKey} successfully`,
+                data: result,
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                message: `Failed to update account: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
+    async createRefund(input) {
+        try {
+            const { idempotencyKey, paymentId, ...refundData } = schemas.createRefund.parse(input);
+            const result = await this.client.createRefund(paymentId, refundData, idempotencyKey);
+            return {
+                success: true,
+                message: `Created refund ${result.number} (status: ${result.status})`,
+                data: result,
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                message: `Failed to create refund: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
+}
+export const toolRegistrations = [
+    // Account Tools
+    {
+        name: "get_account",
+        description: "Get Zuora account details by account key (ID or account number). " +
+            "Returns name, status, currency, balance, and billing info.",
+        inputSchema: schemas.getAccount,
+        invoke: (handlers, args) => handlers.getAccount(args),
+    },
+    {
+        name: "get_account_summary",
+        description: "Get a comprehensive summary of a Zuora account including balances, " +
+            "active subscriptions, recent invoices, and payments in a single call.",
+        inputSchema: schemas.getAccountSummary,
+        invoke: (handlers, args) => handlers.getAccountSummary(args),
+    },
+    // Invoice Tools
+    {
+        name: "get_invoice",
+        description: "Get full details of a Zuora invoice including line items, amount, " +
+            "due date, status, and payment status.",
+        inputSchema: schemas.getInvoice,
+        invoke: (handlers, args) => handlers.getInvoice(args),
+    },
+    {
+        name: "list_invoices",
+        description: "List invoices for a specific Zuora account with pagination. " +
+            "Returns invoice numbers, amounts, dates, and statuses.",
+        inputSchema: schemas.listInvoices,
+        invoke: (handlers, args) => handlers.listInvoices(args),
+    },
+    // Subscription Tools
+    {
+        name: "get_subscription",
+        description: "Get details of a Zuora subscription by subscription key or ID. " +
+            "Returns plan info, status, term dates, and rate plan charges.",
+        inputSchema: schemas.getSubscription,
+        invoke: (handlers, args) => handlers.getSubscription(args),
+    },
+    {
+        name: "list_subscriptions",
+        description: "List all subscriptions for a Zuora account. " +
+            "Returns subscription names, statuses, and term dates.",
+        inputSchema: schemas.listSubscriptions,
+        invoke: (handlers, args) => handlers.listSubscriptions(args),
+    },
+    // Payment Tools
+    {
+        name: "get_payment",
+        description: "Get details of a specific Zuora payment including amount, date, " +
+            "status, and which invoices it was applied to.",
+        inputSchema: schemas.getPayment,
+        invoke: (handlers, args) => handlers.getPayment(args),
+    },
+    {
+        name: "list_payments",
+        description: "List payments with optional account filter and pagination. " +
+            "Returns payment amounts, dates, methods, and statuses.",
+        inputSchema: schemas.listPayments,
+        invoke: (handlers, args) => handlers.listPayments(args),
+    },
+    // ZOQL Query Tools
+    {
+        name: "execute_zoql_query",
+        description: "Execute a ZOQL (Zuora Object Query Language) query for ad-hoc data retrieval. " +
+            "Syntax: SELECT field1, field2 FROM ObjectName WHERE condition. " +
+            "Key objects: Account, Invoice, Payment, Subscription, RatePlan, " +
+            "RatePlanCharge, Product, ProductRatePlan, Contact. " +
+            "Limitations: No JOINs supported. Max 2000 records per call. " +
+            "Use continue_zoql_query with queryLocator for pagination. " +
+            "Example: SELECT Id, AccountNumber, Name, Balance FROM Account WHERE Status = 'Active'",
+        inputSchema: schemas.executeZoqlQuery,
+        invoke: (handlers, args) => handlers.executeZoqlQuery(args),
+    },
+    {
+        name: "continue_zoql_query",
+        description: "Continue a previous ZOQL query that returned a queryLocator " +
+            "(indicates more records available). Returns the next batch of up to 2000 records.",
+        inputSchema: schemas.continueZoqlQuery,
+        invoke: (handlers, args) => handlers.continueZoqlQuery(args),
+    },
+    // Product Catalog
+    {
+        name: "list_products",
+        description: "List products from the Zuora product catalog with rate plans and charges. " +
+            "Useful for understanding available products and pricing.",
+        inputSchema: schemas.listProducts,
+        invoke: (handlers, args) => handlers.listProducts(args),
+    },
+    // Phase 2: Extended Read Tools
+    // Invoice Files
+    {
+        name: "get_invoice_files",
+        description: "Get PDF file references for a specific Zuora invoice. " +
+            "Returns file IDs and authenticated URLs for invoice PDFs. " +
+            "Note: URLs require a valid Bearer token to access.",
+        inputSchema: schemas.getInvoiceFiles,
+        invoke: (handlers, args) => handlers.getInvoiceFiles(args),
+    },
+    // Credit Memo Tools
+    {
+        name: "get_credit_memo",
+        description: "Get full details of a Zuora credit memo including amount, status, " +
+            "applied/unapplied amounts, and line items.",
+        inputSchema: schemas.getCreditMemo,
+        invoke: (handlers, args) => handlers.getCreditMemo(args),
+    },
+    {
+        name: "list_credit_memos",
+        description: "List credit memos with optional account filter and pagination. " +
+            "Returns credit memo numbers, amounts, statuses, and dates.",
+        inputSchema: schemas.listCreditMemos,
+        invoke: (handlers, args) => handlers.listCreditMemos(args),
+    },
+    // Account Search
+    {
+        name: "search_accounts",
+        description: "Search Zuora accounts by field value. Supports searching by Name, " +
+            "AccountNumber, Status, Currency, or Balance. Use LIKE operator with % " +
+            "wildcard for partial name matching (e.g., field='Name', operator='LIKE', " +
+            "value='Acme%'). Returns Id, AccountNumber, Name, Status, Balance, Currency. " +
+            "For additional fields, use execute_zoql_query directly.",
+        inputSchema: schemas.searchAccounts,
+        invoke: (handlers, args) => handlers.searchAccounts(args),
+    },
+    // Usage
+    {
+        name: "list_usage",
+        description: "List usage records for a Zuora account with pagination. " +
+            "Returns usage quantities, units of measure, dates, and status.",
+        inputSchema: schemas.listUsage,
+        invoke: (handlers, args) => handlers.listUsage(args),
+    },
+    // Phase 3: Write Operations (require confirmation before calling)
+    // Payment Creation (HIGH risk)
+    {
+        name: "create_payment",
+        description: "FINANCIAL WRITE OPERATION (HIGH RISK): Create a payment record in Zuora. " +
+            "This charges the customer or records an external payment. " +
+            "IMPORTANT: Confirm the account ID, amount, and effective date with the user before calling. " +
+            "Requires a UUID idempotency key to prevent duplicate payments. " +
+            "Electronic payments require a paymentMethodId and process through the payment gateway. " +
+            "External payments are manual records (check, wire, etc.). " +
+            "This action cannot be easily undone - refunds require a separate operation.",
+        inputSchema: schemas.createPayment,
+        invoke: (handlers, args) => handlers.createPayment(args),
+    },
+    // Payment Application (HIGH risk)
+    {
+        name: "apply_payment",
+        description: "FINANCIAL WRITE OPERATION (HIGH RISK): Apply an unapplied payment to one or more invoices. " +
+            "This reduces invoice balances and allocates payment funds. " +
+            "IMPORTANT: Confirm the payment ID, invoice IDs, and amounts with the user before calling. " +
+            "The total applied amount across all invoices must not exceed the payment's unapplied amount. " +
+            "ALWAYS use get_payment first to verify the unapplied balance before applying.",
+        inputSchema: schemas.applyPayment,
+        invoke: (handlers, args) => handlers.applyPayment(args),
+    },
+    // Invoice Creation (MEDIUM risk)
+    {
+        name: "create_invoice",
+        description: "FINANCIAL WRITE OPERATION (MEDIUM RISK): Create a draft invoice for a Zuora account. " +
+            "The invoice is created in Draft status and must be posted separately using post_invoice. " +
+            "Requires a UUID idempotency key to prevent duplicate invoices. " +
+            "Confirm the account ID and dates with the user before calling.",
+        inputSchema: schemas.createInvoice,
+        invoke: (handlers, args) => handlers.createInvoice(args),
+    },
+    // Invoice Posting (MEDIUM risk)
+    {
+        name: "post_invoice",
+        description: "FINANCIAL WRITE OPERATION (MEDIUM RISK): Post a draft invoice, changing its status to Posted. " +
+            "IMPORTANT: Once posted, the invoice is IMMUTABLE - it cannot be edited or deleted. " +
+            "Posted invoices affect the account balance and are visible to the customer. " +
+            "ALWAYS use get_invoice to review the draft invoice before posting. " +
+            "To reverse a posted invoice, you must create a credit memo.",
+        inputSchema: schemas.postInvoice,
+        invoke: (handlers, args) => handlers.postInvoice(args),
+    },
+    // Subscription Cancellation (HIGH risk)
+    {
+        name: "cancel_subscription",
+        description: "DESTRUCTIVE FINANCIAL OPERATION (HIGH RISK): Cancel a Zuora subscription. " +
+            "IMPORTANT: This action may be irreversible depending on the cancellation policy. " +
+            "Confirm the subscription key and cancellation policy with the user before calling. " +
+            "EndOfCurrentTerm: Cancels at the end of the current billing term. " +
+            "EndOfLastInvoicePeriod: Cancels at the end of the last invoiced period. " +
+            "SpecificDate: Cancels on a specific date (requires cancellationEffectiveDate). " +
+            "ALWAYS use get_subscription to review the subscription details before cancelling.",
+        inputSchema: schemas.cancelSubscription,
+        invoke: (handlers, args) => handlers.cancelSubscription(args),
+    },
+    // Phase 4: Advanced Operations
+    // Subscription Creation (HIGH risk)
+    {
+        name: "create_subscription",
+        description: "FINANCIAL WRITE OPERATION (HIGH RISK): Create a new subscription for a Zuora account. " +
+            "IMPORTANT: Confirm the account, rate plans, term type, and effective date with the user before calling. " +
+            "Requires a UUID idempotency key to prevent duplicate subscriptions. " +
+            "Use list_products to find available productRatePlanIds before creating. " +
+            "TERMED subscriptions require initialTerm and initialTermPeriodType. " +
+            "EVERGREEN subscriptions have no fixed end date. " +
+            "This creates a binding billing relationship that affects invoicing.",
+        inputSchema: schemas.createSubscription,
+        invoke: (handlers, args) => handlers.createSubscription(args),
+    },
+    // Subscription Update (MEDIUM risk)
+    {
+        name: "update_subscription",
+        description: "FINANCIAL WRITE OPERATION (MEDIUM RISK): Update a Zuora subscription's renewal terms or settings. " +
+            "Can modify autoRenew, renewalTerm, renewalTermPeriodType, and notes. " +
+            "Confirm the subscription key and changes with the user before calling. " +
+            "ALWAYS use get_subscription to review current settings before updating. " +
+            "Changes to renewal terms take effect at the next renewal.",
+        inputSchema: schemas.updateSubscription,
+        invoke: (handlers, args) => handlers.updateSubscription(args),
+    },
+    // Account Creation (MEDIUM risk)
+    {
+        name: "create_account",
+        description: "FINANCIAL WRITE OPERATION (MEDIUM RISK): Create a new billing account in Zuora. " +
+            "Requires account name, currency, bill cycle day, and bill-to contact information. " +
+            "Confirm all details with the user before calling. " +
+            "Requires a UUID idempotency key to prevent duplicate accounts. " +
+            "The account is created in Active status and can receive subscriptions immediately. " +
+            "Currency cannot be changed after account creation.",
+        inputSchema: schemas.createAccount,
+        invoke: (handlers, args) => handlers.createAccount(args),
+    },
+    // Account Update (LOW risk)
+    {
+        name: "update_account",
+        description: "WRITE OPERATION (LOW RISK): Update a Zuora account's name, notes, payment terms, " +
+            "auto-pay setting, or contact information. " +
+            "Confirm the account key and changes with the user before calling. " +
+            "ALWAYS use get_account to review current settings before updating. " +
+            "Only include fields that need to change.",
+        inputSchema: schemas.updateAccount,
+        invoke: (handlers, args) => handlers.updateAccount(args),
+    },
+    // Refund Creation (HIGH risk)
+    {
+        name: "create_refund",
+        description: "FINANCIAL WRITE OPERATION (HIGH RISK): Create a refund against a specific payment in Zuora. " +
+            "IMPORTANT: Confirm the payment ID, amount, and refund type with the user before calling. " +
+            "ALWAYS use get_payment to verify the payment exists and has sufficient applied amount. " +
+            "The refund amount must not exceed the original payment's applied amount. " +
+            "Electronic refunds are processed through the payment gateway and may take days to settle. " +
+            "External refunds are manual records (check, wire, etc.). " +
+            "Requires a UUID idempotency key to prevent duplicate refunds. " +
+            "This action cannot be easily undone.",
+        inputSchema: schemas.createRefund,
+        invoke: (handlers, args) => handlers.createRefund(args),
+    },
+];
+//# sourceMappingURL=tools.js.map