@armor/zuora-mcp 1.0.1 → 1.2.0

package/dist/tools.js

@@ -3,6 +3,7 @@
  * Provides account, invoice, subscription, payment, and ZOQL query tools
  */
 import { z } from "zod";
+import { queryAll, escapeZoql, todayString, addDays, subtractDays, daysBetween, getString, getNumber, collectIds, queryWithBatchedIds, } from "./zoql-helpers.js";
 // ==================== Helpers ====================
 function isValidCalendarDate(dateStr) {
     const [year, month, day] = dateStr.split("-").map(Number);
@@ -217,6 +218,73 @@ export const schemas = {
             .default(20)
             .describe("Records per page (default: 20, max: 40)"),
     }),
+    // User Management Tools
+    listUsers: z.object({
+        startIndex: z
+            .number()
+            .int()
+            .min(1)
+            .default(1)
+            .describe("1-based start index for SCIM pagination (default: 1)"),
+        count: z
+            .number()
+            .int()
+            .min(1)
+            .max(100)
+            .default(100)
+            .describe("Number of users to return per page (default: 100, max: 100)"),
+        filter: z
+            .string()
+            .max(500)
+            .optional()
+            .describe("SCIM filter string (optional). " +
+            "Examples: status eq \"Active\", userName eq \"user@example.com\""),
+    }),
+    getUser: z.object({
+        userId: z
+            .string()
+            .uuid("User ID must be a valid UUID")
+            .describe("Zuora user ID (UUID format)"),
+    }),
+    // Bill Run Read Tools
+    getBillRun: z.object({
+        billRunId: z
+            .string()
+            .min(1)
+            .describe("Bill run ID (e.g., 2c92c0f8...)"),
+    }),
+    listBillRuns: 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)"),
+    }),
+    // Contact Read Tools
+    getContact: z.object({
+        contactId: z
+            .string()
+            .min(1)
+            .describe("Contact ID (e.g., 2c92c0f8...)"),
+    }),
+    // Describe API
+    describeObject: z.object({
+        objectType: z
+            .string()
+            .min(1)
+            .max(100)
+            .regex(/^[A-Z][a-zA-Z]*$/, "Object type must be PascalCase (e.g., Account, Invoice, Subscription)")
+            .describe("Zuora object type name in PascalCase (e.g., Account, Invoice, Subscription, " +
+            "Payment, RatePlan, RatePlanCharge, Product, ProductRatePlan, BillRun, Contact)"),
+    }),
     // Phase 3: Write Operations
     createPayment: z.object({
         accountId: z
@@ -596,6 +664,255 @@ export const schemas = {
             .describe("UUID to prevent duplicate refunds on retries. " +
             "Generate a new UUID v4 for each distinct refund intent."),
     }),
+    // Bill Run Write Tools
+    createBillRun: z.object({
+        targetDate: 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("Target date for the bill run in YYYY-MM-DD format. Invoices are generated for charges through this date."),
+        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")
+            .optional()
+            .describe("Invoice date in YYYY-MM-DD format (optional, defaults to targetDate)"),
+        autoPost: z
+            .boolean()
+            .default(false)
+            .describe("Automatically post invoices after generation (default: false)"),
+        autoEmail: z
+            .boolean()
+            .default(false)
+            .describe("Automatically email invoices after posting (default: false). Requires autoPost to be true."),
+        name: z
+            .string()
+            .max(255)
+            .optional()
+            .describe("Optional name/label for the bill run"),
+        idempotencyKey: z
+            .string()
+            .uuid("Idempotency key must be a valid UUID")
+            .describe("UUID to prevent duplicate bill runs on retries. " +
+            "Generate a new UUID v4 for each distinct bill run intent."),
+    }).superRefine((data, ctx) => {
+        if (data.autoEmail && !data.autoPost) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ["autoEmail"],
+                message: "autoEmail requires autoPost to be true — invoices must be posted before they can be emailed",
+            });
+        }
+    }),
+    // Contact Write Tools
+    createContact: z.object({
+        accountId: z
+            .string()
+            .min(1)
+            .describe("Zuora account UUID to create the contact for"),
+        firstName: z
+            .string()
+            .min(1)
+            .max(100)
+            .describe("Contact first name"),
+        lastName: z
+            .string()
+            .min(1)
+            .max(100)
+            .describe("Contact last name"),
+        workEmail: z
+            .string()
+            .email("Must be a valid email address")
+            .optional()
+            .describe("Work email address"),
+        personalEmail: z
+            .string()
+            .email("Must be a valid email address")
+            .optional()
+            .describe("Personal email address"),
+        workPhone: z.string().max(40).optional().describe("Work phone number"),
+        homePhone: z.string().max(40).optional().describe("Home phone number"),
+        mobilePhone: z.string().max(40).optional().describe("Mobile phone number"),
+        fax: z.string().max(40).optional().describe("Fax number"),
+        address1: z.string().max(255).optional().describe("Street address line 1"),
+        address2: z.string().max(255).optional().describe("Street address line 2"),
+        city: z.string().max(100).optional().describe("City"),
+        state: z.string().max(100).optional().describe("State or province"),
+        country: z.string().max(100).optional().describe("Country (ISO 3166 name or code)"),
+        postalCode: z.string().max(20).optional().describe("Postal/ZIP code"),
+        county: z.string().max(100).optional().describe("County"),
+        taxRegion: z.string().max(100).optional().describe("Tax region"),
+        description: z.string().max(2000).optional().describe("Contact description/notes"),
+        nickname: z.string().max(100).optional().describe("Contact nickname"),
+        idempotencyKey: z
+            .string()
+            .uuid("Idempotency key must be a valid UUID")
+            .describe("UUID to prevent duplicate contact creation on retries. " +
+            "Generate a new UUID v4 for each distinct contact intent."),
+    }),
+    updateContact: z.object({
+        contactId: z
+            .string()
+            .min(1)
+            .describe("Contact ID to update"),
+        firstName: z.string().min(1).max(100).optional().describe("Updated first name"),
+        lastName: z.string().min(1).max(100).optional().describe("Updated last name"),
+        workEmail: z.string().email("Must be a valid email address").optional().describe("Updated work email"),
+        personalEmail: z.string().email("Must be a valid email address").optional().describe("Updated personal email"),
+        workPhone: z.string().max(40).optional().describe("Updated work phone"),
+        homePhone: z.string().max(40).optional().describe("Updated home phone"),
+        mobilePhone: z.string().max(40).optional().describe("Updated mobile phone"),
+        fax: z.string().max(40).optional().describe("Updated fax number"),
+        address1: z.string().max(255).optional().describe("Updated street address line 1"),
+        address2: z.string().max(255).optional().describe("Updated street address line 2"),
+        city: z.string().max(100).optional().describe("Updated city"),
+        state: z.string().max(100).optional().describe("Updated state or province"),
+        country: z.string().max(100).optional().describe("Updated country"),
+        postalCode: z.string().max(20).optional().describe("Updated postal/ZIP code"),
+        county: z.string().max(100).optional().describe("Updated county"),
+        taxRegion: z.string().max(100).optional().describe("Updated tax region"),
+        description: z.string().max(2000).optional().describe("Updated description/notes"),
+        nickname: z.string().max(100).optional().describe("Updated nickname"),
+    }).superRefine((data, ctx) => {
+        const { contactId: _, ...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",
+            });
+        }
+    }),
+    // ==================== Composite Tool Schemas ====================
+    findAccountsByProduct: z.object({
+        productName: z
+            .string()
+            .min(1)
+            .max(255)
+            .describe("Product name to search for (partial match supported). " +
+            "Example: 'Security Analytics Log Retention 13 Months'"),
+        limit: z
+            .number()
+            .int()
+            .min(1)
+            .max(100)
+            .default(25)
+            .describe("Maximum accounts to return (default: 25, max: 100)"),
+    }),
+    getOverdueInvoices: z.object({
+        minBalance: z
+            .number()
+            .min(0)
+            .default(0)
+            .describe("Minimum invoice balance to include (default: 0)"),
+        limit: z
+            .number()
+            .int()
+            .min(1)
+            .max(200)
+            .default(50)
+            .describe("Maximum invoices to return (default: 50, max: 200)"),
+    }),
+    getExpiringSubscriptions: z.object({
+        daysAhead: z
+            .number()
+            .int()
+            .min(1)
+            .max(365)
+            .default(30)
+            .describe("Days to look ahead for expiring subscriptions (default: 30, max: 365)"),
+        limit: z
+            .number()
+            .int()
+            .min(1)
+            .max(200)
+            .default(50)
+            .describe("Maximum subscriptions to return (default: 50, max: 200)"),
+    }),
+    getAccountBillingOverview: z.object({
+        accountKey: z
+            .string()
+            .min(1)
+            .describe("Account number or ID (e.g., A00012345)"),
+    }),
+    getRevenueByProduct: z.object({
+        limit: z
+            .number()
+            .int()
+            .min(1)
+            .max(100)
+            .default(50)
+            .describe("Maximum products to return (default: 50, max: 100)"),
+    }),
+    getPaymentReconciliation: z.object({
+        startDate: 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("Start date for payment period (YYYY-MM-DD)"),
+        endDate: 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("End date for payment period (YYYY-MM-DD)"),
+        limit: z
+            .number()
+            .int()
+            .min(1)
+            .max(500)
+            .default(100)
+            .describe("Maximum payments to return (default: 100, max: 500)"),
+    }),
+    getRecentlyCancelledSubscriptions: z.object({
+        daysBack: z
+            .number()
+            .int()
+            .min(1)
+            .max(365)
+            .default(30)
+            .describe("Days to look back for cancellations (default: 30, max: 365)"),
+        limit: z
+            .number()
+            .int()
+            .min(1)
+            .max(200)
+            .default(50)
+            .describe("Maximum subscriptions to return (default: 50, max: 200)"),
+    }),
+    getInvoiceAgingReport: z.object({
+        limit: z
+            .number()
+            .int()
+            .min(1)
+            .max(500)
+            .default(200)
+            .describe("Maximum invoices to analyze (default: 200, max: 500)"),
+    }),
+    getAccountHealthScorecard: z.object({
+        limit: z
+            .number()
+            .int()
+            .min(1)
+            .max(100)
+            .default(20)
+            .describe("Maximum at-risk accounts to return (default: 20, max: 100)"),
+    }),
+    findInvoicesByProduct: z.object({
+        productName: z
+            .string()
+            .min(1)
+            .max(255)
+            .describe("Product name to search for (partial match supported). " +
+            "Example: 'Security Analytics'"),
+        limit: z
+            .number()
+            .int()
+            .min(1)
+            .max(200)
+            .default(50)
+            .describe("Maximum invoice items to return (default: 50, max: 200)"),
+    }),
 };
 // ==================== Tool Handlers ====================
 export class ToolHandlers {
@@ -902,6 +1219,115 @@ export class ToolHandlers {
             };
         }
     }
+    // --- User Management Handlers ---
+    async listUsers(input) {
+        try {
+            const { startIndex, count, filter } = schemas.listUsers.parse(input);
+            const result = await this.client.listUsers(startIndex, count, filter);
+            const userCount = result.Resources?.length ?? 0;
+            const filterNote = filter ? ` (filter: ${filter})` : "";
+            return {
+                success: true,
+                message: `Found ${userCount} user(s) of ${result.totalResults} total${filterNote}`,
+                data: result,
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                message: `Failed to list users: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
+    async getUser(input) {
+        try {
+            const { userId } = schemas.getUser.parse(input);
+            const user = await this.client.getUser(userId);
+            return {
+                success: true,
+                message: `Retrieved user ${user.userName ?? userId}`,
+                data: user,
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                message: `Failed to get user: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
+    // --- Bill Run Handlers ---
+    async getBillRun(input) {
+        try {
+            const { billRunId } = schemas.getBillRun.parse(input);
+            const billRun = await this.client.getBillRun(billRunId);
+            return {
+                success: true,
+                message: `Retrieved bill run ${billRun.billRunNumber ?? billRunId} (status: ${billRun.status})`,
+                data: billRun,
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                message: `Failed to get bill run: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
+    async listBillRuns(input) {
+        try {
+            const { page, pageSize } = schemas.listBillRuns.parse(input);
+            const result = await this.client.listBillRuns(page, pageSize);
+            const count = result.billRuns?.length ?? 0;
+            return {
+                success: true,
+                message: `Found ${count} bill run(s)`,
+                data: result,
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                message: `Failed to list bill runs: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
+    // --- Contact Handlers ---
+    async getContact(input) {
+        try {
+            const { contactId } = schemas.getContact.parse(input);
+            const contact = await this.client.getContact(contactId);
+            return {
+                success: true,
+                message: `Retrieved contact ${contact.firstName} ${contact.lastName} (${contactId})`,
+                data: contact,
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                message: `Failed to get contact: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
+    // --- Describe API Handlers ---
+    async describeObject(input) {
+        try {
+            const { objectType } = schemas.describeObject.parse(input);
+            const result = await this.client.describeObject(objectType);
+            return {
+                success: true,
+                message: `Described ${result.objectName}: ${result.fieldCount} field(s)`,
+                data: result,
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                message: `Failed to describe object: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
     // --- Phase 3: Write Operation Handlers ---
     async createPayment(input) {
         try {
@@ -1077,6 +1503,909 @@ export class ToolHandlers {
             };
         }
     }
+    // --- Bill Run Write Handlers ---
+    async createBillRun(input) {
+        try {
+            const { idempotencyKey, ...billRunData } = schemas.createBillRun.parse(input);
+            const result = await this.client.createBillRun(billRunData, idempotencyKey);
+            return {
+                success: true,
+                message: `Created bill run ${result.billRunNumber} (status: ${result.status})`,
+                data: result,
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                message: `Failed to create bill run: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
+    // --- Contact Write Handlers ---
+    async createContact(input) {
+        try {
+            const { idempotencyKey, ...contactData } = schemas.createContact.parse(input);
+            const result = await this.client.createContact(contactData, idempotencyKey);
+            return {
+                success: true,
+                message: `Created contact (id: ${result.id}) for account ${contactData.accountId}`,
+                data: result,
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                message: `Failed to create contact: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
+    async updateContact(input) {
+        try {
+            const { contactId, ...updateData } = schemas.updateContact.parse(input);
+            const result = await this.client.updateContact(contactId, updateData);
+            return {
+                success: true,
+                message: `Updated contact ${contactId} successfully`,
+                data: result,
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                message: `Failed to update contact: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
+    // --- Composite Tool Handlers ---
+    async findAccountsByProduct(input) {
+        try {
+            const { productName, limit } = schemas.findAccountsByProduct.parse(input);
+            const safeName = escapeZoql(productName);
+            // Step 1: Find ProductRatePlan IDs matching the product name
+            const productRatePlans = await queryAll(this.client, `SELECT Id, Name FROM ProductRatePlan WHERE Name LIKE '%${safeName}%'`);
+            if (productRatePlans.length === 0) {
+                // Try searching by Product.Name instead
+                const products = await queryAll(this.client, `SELECT Id, Name FROM Product WHERE Name LIKE '%${safeName}%'`);
+                if (products.length === 0) {
+                    return {
+                        success: true,
+                        message: `No products found matching "${productName}"`,
+                        data: { accounts: [], totalFound: 0 },
+                    };
+                }
+                const productIds = collectIds(products, "Id");
+                const prpFromProduct = await queryWithBatchedIds(this.client, "Id, Name", "ProductRatePlan", "ProductId", productIds);
+                if (prpFromProduct.length === 0) {
+                    return {
+                        success: true,
+                        message: `Product found but no rate plans configured for "${productName}"`,
+                        data: { accounts: [], totalFound: 0 },
+                    };
+                }
+                productRatePlans.push(...prpFromProduct);
+            }
+            const prpIds = collectIds(productRatePlans, "Id");
+            // Step 2: Find RatePlans using those ProductRatePlanIds → get SubscriptionIds
+            const ratePlans = await queryWithBatchedIds(this.client, "Id, SubscriptionId, Name", "RatePlan", "ProductRatePlanId", prpIds);
+            if (ratePlans.length === 0) {
+                return {
+                    success: true,
+                    message: `No active subscriptions found for product "${productName}"`,
+                    data: { accounts: [], totalFound: 0 },
+                };
+            }
+            const subscriptionIds = collectIds(ratePlans, "SubscriptionId");
+            // Step 3: Get Subscriptions → AccountIds
+            const subscriptions = await queryWithBatchedIds(this.client, "Id, AccountId, SubscriptionNumber, Status, TermEndDate, ContractedMrr", "Subscription", "Id", subscriptionIds, "Status = 'Active'");
+            if (subscriptions.length === 0) {
+                return {
+                    success: true,
+                    message: `No active subscriptions found for product "${productName}"`,
+                    data: { accounts: [], totalFound: 0 },
+                };
+            }
+            const accountIds = collectIds(subscriptions, "AccountId");
+            // Step 4: Get Account details
+            const accounts = await queryWithBatchedIds(this.client, "Id, AccountNumber, Name, Status", "Account", "Id", accountIds);
+            // Build lookup maps
+            const accountMap = new Map(accounts.map((a) => [getString(a, "Id"), a]));
+            const subsByAccount = new Map();
+            for (const sub of subscriptions) {
+                const acctId = getString(sub, "AccountId") ?? "";
+                const existing = subsByAccount.get(acctId) ?? [];
+                existing.push(sub);
+                subsByAccount.set(acctId, existing);
+            }
+            // Build rate plan name lookup by subscription
+            const rpNameBySub = new Map();
+            for (const rp of ratePlans) {
+                const subId = getString(rp, "SubscriptionId") ?? "";
+                const existing = rpNameBySub.get(subId) ?? [];
+                const name = getString(rp, "Name");
+                if (name)
+                    existing.push(name);
+                rpNameBySub.set(subId, existing);
+            }
+            // Assemble results
+            const results = [];
+            for (const [acctId, acct] of accountMap) {
+                if (!acctId)
+                    continue;
+                const acctSubs = subsByAccount.get(acctId) ?? [];
+                results.push({
+                    accountId: acctId,
+                    accountNumber: getString(acct, "AccountNumber") ?? "",
+                    accountName: getString(acct, "Name") ?? "",
+                    accountStatus: getString(acct, "Status") ?? "",
+                    subscriptions: acctSubs.map((sub) => ({
+                        subscriptionId: getString(sub, "Id") ?? "",
+                        subscriptionNumber: getString(sub, "SubscriptionNumber") ?? "",
+                        status: getString(sub, "Status") ?? "",
+                        termEndDate: getString(sub, "TermEndDate"),
+                        ratePlanName: (rpNameBySub.get(getString(sub, "Id") ?? "") ?? []).join(", "),
+                    })),
+                });
+                if (results.length >= limit)
+                    break;
+            }
+            return {
+                success: true,
+                message: `Found ${results.length} account(s) with active subscriptions for "${productName}"`,
+                data: { accounts: results, totalFound: results.length },
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                message: `Failed to find accounts by product: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
+    async getOverdueInvoices(input) {
+        try {
+            const { minBalance, limit } = schemas.getOverdueInvoices.parse(input);
+            const today = todayString();
+            // Query overdue invoices: Posted, has balance, past due date
+            const invoices = await queryAll(this.client, `SELECT Id, InvoiceNumber, AccountId, InvoiceDate, DueDate, Amount, Balance ` +
+                `FROM Invoice ` +
+                `WHERE Status = 'Posted' AND Balance > ${minBalance} AND DueDate < '${today}'`, limit);
+            if (invoices.length === 0) {
+                return {
+                    success: true,
+                    message: "No overdue invoices found",
+                    data: { invoices: [], totalFound: 0, totalOverdueBalance: 0 },
+                };
+            }
+            // Get account details for the overdue invoices
+            const accountIds = collectIds(invoices, "AccountId");
+            const accounts = await queryWithBatchedIds(this.client, "Id, AccountNumber, Name", "Account", "Id", accountIds);
+            const accountMap = new Map(accounts.map((a) => [getString(a, "Id"), a]));
+            // Build results
+            const results = invoices.map((inv) => {
+                const acctId = getString(inv, "AccountId") ?? "";
+                const acct = accountMap.get(acctId);
+                const dueDate = getString(inv, "DueDate") ?? today;
+                return {
+                    invoiceId: getString(inv, "Id") ?? "",
+                    invoiceNumber: getString(inv, "InvoiceNumber") ?? "",
+                    accountId: acctId,
+                    accountNumber: getString(acct ?? {}, "AccountNumber") ?? "",
+                    accountName: getString(acct ?? {}, "Name") ?? "",
+                    invoiceDate: getString(inv, "InvoiceDate") ?? "",
+                    dueDate,
+                    amount: getNumber(inv, "Amount") ?? 0,
+                    balance: getNumber(inv, "Balance") ?? 0,
+                    daysPastDue: daysBetween(dueDate, today),
+                };
+            });
+            // Sort by days past due descending
+            results.sort((a, b) => b.daysPastDue - a.daysPastDue);
+            const totalOverdueBalance = results.reduce((sum, r) => sum + r.balance, 0);
+            return {
+                success: true,
+                message: `Found ${results.length} overdue invoice(s) totaling $${totalOverdueBalance.toFixed(2)}`,
+                data: {
+                    invoices: results.slice(0, limit),
+                    totalFound: results.length,
+                    totalOverdueBalance,
+                },
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                message: `Failed to get overdue invoices: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
+    async getExpiringSubscriptions(input) {
+        try {
+            const { daysAhead, limit } = schemas.getExpiringSubscriptions.parse(input);
+            const today = todayString();
+            const futureDate = addDays(new Date(), daysAhead);
+            // Query active subscriptions expiring within the window
+            const subscriptions = await queryAll(this.client, `SELECT Id, SubscriptionNumber, AccountId, Status, TermEndDate, AutoRenew, ContractedMrr ` +
+                `FROM Subscription ` +
+                `WHERE Status = 'Active' AND TermEndDate >= '${today}' AND TermEndDate <= '${futureDate}'`, limit * 2 // fetch extra to account for filtering
+            );
+            if (subscriptions.length === 0) {
+                return {
+                    success: true,
+                    message: `No subscriptions expiring in the next ${daysAhead} days`,
+                    data: { subscriptions: [], totalFound: 0, totalMrrAtRisk: 0 },
+                };
+            }
+            // Get account details
+            const accountIds = collectIds(subscriptions, "AccountId");
+            const accounts = await queryWithBatchedIds(this.client, "Id, AccountNumber, Name", "Account", "Id", accountIds);
+            const accountMap = new Map(accounts.map((a) => [getString(a, "Id"), a]));
+            // Get rate plan names
+            const subIds = collectIds(subscriptions, "Id");
+            const ratePlans = await queryWithBatchedIds(this.client, "Id, SubscriptionId, Name", "RatePlan", "SubscriptionId", subIds);
+            const rpNamesBySub = new Map();
+            for (const rp of ratePlans) {
+                const subId = getString(rp, "SubscriptionId") ?? "";
+                const existing = rpNamesBySub.get(subId) ?? [];
+                const name = getString(rp, "Name");
+                if (name)
+                    existing.push(name);
+                rpNamesBySub.set(subId, existing);
+            }
+            // Build results
+            const results = subscriptions.map((sub) => {
+                const acctId = getString(sub, "AccountId") ?? "";
+                const acct = accountMap.get(acctId);
+                const termEnd = getString(sub, "TermEndDate") ?? futureDate;
+                const subId = getString(sub, "Id") ?? "";
+                return {
+                    subscriptionId: subId,
+                    subscriptionNumber: getString(sub, "SubscriptionNumber") ?? "",
+                    accountId: acctId,
+                    accountNumber: getString(acct ?? {}, "AccountNumber") ?? "",
+                    accountName: getString(acct ?? {}, "Name") ?? "",
+                    status: getString(sub, "Status") ?? "",
+                    termEndDate: termEnd,
+                    autoRenew: sub.AutoRenew === true,
+                    contractedMrr: getNumber(sub, "ContractedMrr") ?? 0,
+                    ratePlanNames: rpNamesBySub.get(subId) ?? [],
+                    daysUntilExpiry: daysBetween(today, termEnd),
+                };
+            });
+            results.sort((a, b) => a.daysUntilExpiry - b.daysUntilExpiry);
+            const totalMrrAtRisk = results
+                .filter((r) => !r.autoRenew)
+                .reduce((sum, r) => sum + r.contractedMrr, 0);
+            return {
+                success: true,
+                message: `Found ${results.length} subscription(s) expiring in the next ${daysAhead} days (MRR at risk: $${totalMrrAtRisk.toFixed(2)})`,
+                data: {
+                    subscriptions: results.slice(0, limit),
+                    totalFound: results.length,
+                    totalMrrAtRisk,
+                },
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                message: `Failed to get expiring subscriptions: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
+    async getAccountBillingOverview(input) {
+        try {
+            const { accountKey } = schemas.getAccountBillingOverview.parse(input);
+            // Step 1: Get account via REST API
+            const account = await this.client.getAccount(accountKey);
+            // Step 2: Get recent invoices via ZOQL
+            const invoices = await queryAll(this.client, `SELECT Id, InvoiceNumber, InvoiceDate, DueDate, Amount, Balance, Status ` +
+                `FROM Invoice WHERE AccountId = '${escapeZoql(account.id)}' ` +
+                `ORDER BY InvoiceDate DESC`, 20);
+            // Step 3: Get recent payments via ZOQL
+            const payments = await queryAll(this.client, `SELECT Id, PaymentNumber, Amount, EffectiveDate, Status ` +
+                `FROM Payment WHERE AccountId = '${escapeZoql(account.id)}' ` +
+                `ORDER BY EffectiveDate DESC`, 10);
+            // Step 4: Get subscriptions via REST API
+            const subResult = await this.client.listSubscriptionsByAccount(accountKey);
+            const subscriptions = subResult.subscriptions ?? [];
+            // Compute invoice summary
+            const today = todayString();
+            let totalOutstanding = 0;
+            let overdueCount = 0;
+            let overdueAmount = 0;
+            for (const inv of invoices) {
+                const balance = getNumber(inv, "Balance") ?? 0;
+                const status = getString(inv, "Status");
+                if (status === "Posted" && balance > 0) {
+                    totalOutstanding += balance;
+                    const dueDate = getString(inv, "DueDate") ?? "";
+                    if (dueDate && dueDate < today) {
+                        overdueCount++;
+                        overdueAmount += balance;
+                    }
+                }
+            }
+            const activeSubscriptions = subscriptions.filter((s) => s.status === "Active");
+            const totalMrr = activeSubscriptions.reduce((sum, s) => sum + (s.contractedMrr ?? 0), 0);
+            const overview = {
+                account: {
+                    id: account.id,
+                    accountNumber: account.accountNumber,
+                    name: account.name,
+                    status: account.status,
+                    balance: account.balance,
+                    currency: account.currency,
+                    autoPay: account.autoPay,
+                    paymentTerm: account.paymentTerm,
+                },
+                invoiceSummary: {
+                    totalOutstanding,
+                    overdueCount,
+                    overdueAmount,
+                    recentInvoices: invoices.slice(0, 10).map((inv) => ({
+                        invoiceNumber: getString(inv, "InvoiceNumber") ?? "",
+                        invoiceDate: getString(inv, "InvoiceDate") ?? "",
+                        dueDate: getString(inv, "DueDate") ?? "",
+                        amount: getNumber(inv, "Amount") ?? 0,
+                        balance: getNumber(inv, "Balance") ?? 0,
+                        status: getString(inv, "Status") ?? "",
+                    })),
+                },
+                paymentSummary: {
+                    recentPayments: payments.slice(0, 5).map((p) => ({
+                        paymentNumber: getString(p, "PaymentNumber") ?? "",
+                        amount: getNumber(p, "Amount") ?? 0,
+                        effectiveDate: getString(p, "EffectiveDate") ?? "",
+                        status: getString(p, "Status") ?? "",
+                    })),
+                },
+                subscriptionSummary: {
+                    activeCount: activeSubscriptions.length,
+                    totalMrr,
+                    subscriptions: activeSubscriptions.slice(0, 10).map((s) => ({
+                        subscriptionNumber: s.subscriptionNumber,
+                        status: s.status,
+                        termEndDate: s.termEndDate,
+                        contractedMrr: s.contractedMrr,
+                        ratePlanNames: s.ratePlans?.map((rp) => rp.ratePlanName) ?? [],
+                    })),
+                },
+            };
+            return {
+                success: true,
+                message: `Billing overview for ${account.name} (${account.accountNumber}): balance $${account.balance}, ${overdueCount} overdue, ${activeSubscriptions.length} active subscriptions`,
+                data: overview,
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                message: `Failed to get billing overview: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
+    async getRevenueByProduct(input) {
+        try {
+            const { limit } = schemas.getRevenueByProduct.parse(input);
+            // Step 1: Get all active subscriptions with MRR
+            const subscriptions = await queryAll(this.client, `SELECT Id, AccountId, SubscriptionNumber, ContractedMrr, Status ` +
+                `FROM Subscription WHERE Status = 'Active'`, 5000);
+            if (subscriptions.length === 0) {
+                return {
+                    success: true,
+                    message: "No active subscriptions found",
+                    data: { products: [], totalMrr: 0 },
+                };
+            }
+            // Step 2: Get rate plans for subscriptions to resolve product names
+            const subIds = collectIds(subscriptions, "Id");
+            const ratePlans = await queryWithBatchedIds(this.client, "Id, SubscriptionId, ProductRatePlanId, Name", "RatePlan", "SubscriptionId", subIds);
+            // Step 3: Get ProductRatePlan → Product mapping
+            const prpIds = collectIds(ratePlans, "ProductRatePlanId");
+            const productRatePlans = await queryWithBatchedIds(this.client, "Id, ProductId, Name", "ProductRatePlan", "Id", prpIds);
+            const productIds = collectIds(productRatePlans, "ProductId");
+            const products = await queryWithBatchedIds(this.client, "Id, Name", "Product", "Id", productIds);
+            // Build lookup maps
+            const productNameMap = new Map(products.map((p) => [getString(p, "Id"), getString(p, "Name") ?? "Unknown"]));
+            const prpToProduct = new Map(productRatePlans.map((prp) => [
+                getString(prp, "Id"),
+                productNameMap.get(getString(prp, "ProductId") ?? "") ?? getString(prp, "Name") ?? "Unknown",
+            ]));
+            // Map subscriptions to their rate plans and product names
+            const subMap = new Map(subscriptions.map((s) => [getString(s, "Id"), s]));
+            // Get account details for all subscriptions
+            const accountIds = collectIds(subscriptions, "AccountId");
+            const accounts = await queryWithBatchedIds(this.client, "Id, AccountNumber, Name", "Account", "Id", accountIds);
+            const accountMap = new Map(accounts.map((a) => [getString(a, "Id"), a]));
+            // Group by product name
+            const productData = new Map();
+            for (const rp of ratePlans) {
+                const prpId = getString(rp, "ProductRatePlanId") ?? "";
+                const productName = prpToProduct.get(prpId) ?? getString(rp, "Name") ?? "Unknown";
+                const subId = getString(rp, "SubscriptionId") ?? "";
+                const sub = subMap.get(subId);
+                if (!sub)
+                    continue;
+                const acctId = getString(sub, "AccountId") ?? "";
+                const acct = accountMap.get(acctId);
+                const mrr = getNumber(sub, "ContractedMrr") ?? 0;
+                const existing = productData.get(productName) ?? {
+                    subscriptionCount: 0,
+                    totalMrr: 0,
+                    totalTcv: 0,
+                    subscriptions: [],
+                };
+                existing.subscriptionCount++;
+                existing.totalMrr += mrr;
+                existing.subscriptions.push({
+                    subscriptionNumber: getString(sub, "SubscriptionNumber") ?? "",
+                    accountNumber: getString(acct ?? {}, "AccountNumber") ?? "",
+                    accountName: getString(acct ?? {}, "Name") ?? "",
+                    mrr,
+                    status: getString(sub, "Status") ?? "",
+                });
+                productData.set(productName, existing);
+            }
+            // Convert to sorted array
+            const results = [...productData.entries()]
+                .map(([name, data]) => ({
+                productName: name,
+                subscriptionCount: data.subscriptionCount,
+                totalMrr: data.totalMrr,
+                totalTcv: data.totalTcv,
+                subscriptions: data.subscriptions,
+            }))
+                .sort((a, b) => b.totalMrr - a.totalMrr)
+                .slice(0, limit);
+            const totalMrr = results.reduce((sum, r) => sum + r.totalMrr, 0);
+            return {
+                success: true,
+                message: `Revenue breakdown across ${results.length} product(s), total MRR: $${totalMrr.toFixed(2)}`,
+                data: { products: results, totalMrr },
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                message: `Failed to get revenue by product: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
+    async getPaymentReconciliation(input) {
+        try {
+            const { startDate, endDate, limit } = schemas.getPaymentReconciliation.parse(input);
+            // Query payments in the date range
+            const payments = await queryAll(this.client, `SELECT Id, PaymentNumber, AccountId, Amount, EffectiveDate, Status, PaymentMethodType ` +
+                `FROM Payment ` +
+                `WHERE EffectiveDate >= '${escapeZoql(startDate)}' AND EffectiveDate <= '${escapeZoql(endDate)}'`, limit);
+            if (payments.length === 0) {
+                return {
+                    success: true,
+                    message: `No payments found between ${startDate} and ${endDate}`,
+                    data: {
+                        period: { startDate, endDate },
+                        summary: { totalPayments: 0, totalAmount: 0, byStatus: {} },
+                        payments: [],
+                    },
+                };
+            }
+            // Get account details
+            const accountIds = collectIds(payments, "AccountId");
+            const accounts = await queryWithBatchedIds(this.client, "Id, AccountNumber, Name", "Account", "Id", accountIds);
+            const accountMap = new Map(accounts.map((a) => [getString(a, "Id"), a]));
+            // Build summary
+            const byStatus = {};
+            let totalAmount = 0;
+            const paymentResults = payments.map((p) => {
+                const amount = getNumber(p, "Amount") ?? 0;
+                const status = getString(p, "Status") ?? "Unknown";
+                const acctId = getString(p, "AccountId") ?? "";
+                const acct = accountMap.get(acctId);
+                totalAmount += amount;
+                const statusBucket = byStatus[status] ?? { count: 0, amount: 0 };
+                statusBucket.count++;
+                statusBucket.amount += amount;
+                byStatus[status] = statusBucket;
+                return {
+                    paymentNumber: getString(p, "PaymentNumber") ?? "",
+                    accountNumber: getString(acct ?? {}, "AccountNumber") ?? "",
+                    accountName: getString(acct ?? {}, "Name") ?? "",
+                    amount,
+                    effectiveDate: getString(p, "EffectiveDate") ?? "",
+                    status,
+                    paymentMethodType: getString(p, "PaymentMethodType") ?? "",
+                };
+            });
+            const result = {
+                period: { startDate, endDate },
+                summary: {
+                    totalPayments: payments.length,
+                    totalAmount,
+                    byStatus,
+                },
+                payments: paymentResults,
+            };
+            return {
+                success: true,
+                message: `${payments.length} payment(s) totaling $${totalAmount.toFixed(2)} between ${startDate} and ${endDate}`,
+                data: result,
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                message: `Failed to get payment reconciliation: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
+    async getRecentlyCancelledSubscriptions(input) {
+        try {
+            const { daysBack, limit } = schemas.getRecentlyCancelledSubscriptions.parse(input);
+            const sinceDate = subtractDays(new Date(), daysBack);
+            const subscriptions = await queryAll(this.client, `SELECT Id, SubscriptionNumber, AccountId, Status, TermEndDate, UpdatedDate, ContractedMrr ` +
+                `FROM Subscription ` +
+                `WHERE Status = 'Cancelled' AND UpdatedDate >= '${sinceDate}'`, limit * 2);
+            if (subscriptions.length === 0) {
+                return {
+                    success: true,
+                    message: `No subscriptions cancelled in the last ${daysBack} days`,
+                    data: { subscriptions: [], totalFound: 0, totalLostMrr: 0 },
+                };
+            }
+            // Get account details
+            const accountIds = collectIds(subscriptions, "AccountId");
+            const accounts = await queryWithBatchedIds(this.client, "Id, AccountNumber, Name", "Account", "Id", accountIds);
+            const accountMap = new Map(accounts.map((a) => [getString(a, "Id"), a]));
+            // Get rate plan names
+            const subIds = collectIds(subscriptions, "Id");
+            const ratePlans = await queryWithBatchedIds(this.client, "Id, SubscriptionId, Name", "RatePlan", "SubscriptionId", subIds);
+            const rpNamesBySub = new Map();
+            for (const rp of ratePlans) {
+                const subId = getString(rp, "SubscriptionId") ?? "";
+                const existing = rpNamesBySub.get(subId) ?? [];
+                const name = getString(rp, "Name");
+                if (name)
+                    existing.push(name);
+                rpNamesBySub.set(subId, existing);
+            }
+            const results = subscriptions.map((sub) => {
+                const acctId = getString(sub, "AccountId") ?? "";
+                const acct = accountMap.get(acctId);
+                const subId = getString(sub, "Id") ?? "";
+                return {
+                    subscriptionId: subId,
+                    subscriptionNumber: getString(sub, "SubscriptionNumber") ?? "",
+                    accountId: acctId,
+                    accountNumber: getString(acct ?? {}, "AccountNumber") ?? "",
+                    accountName: getString(acct ?? {}, "Name") ?? "",
+                    status: getString(sub, "Status") ?? "",
+                    cancelledDate: getString(sub, "UpdatedDate") ?? "",
+                    termEndDate: getString(sub, "TermEndDate") ?? "",
+                    contractedMrr: getNumber(sub, "ContractedMrr") ?? 0,
+                    ratePlanNames: rpNamesBySub.get(subId) ?? [],
+                };
+            });
+            const totalLostMrr = results.reduce((sum, r) => sum + r.contractedMrr, 0);
+            return {
+                success: true,
+                message: `Found ${results.length} cancelled subscription(s) in the last ${daysBack} days (lost MRR: $${totalLostMrr.toFixed(2)})`,
+                data: {
+                    subscriptions: results.slice(0, limit),
+                    totalFound: results.length,
+                    totalLostMrr,
+                },
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                message: `Failed to get cancelled subscriptions: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
+    async getInvoiceAgingReport(input) {
+        try {
+            const { limit } = schemas.getInvoiceAgingReport.parse(input);
+            const today = todayString();
+            // Query all posted invoices with outstanding balance
+            const invoices = await queryAll(this.client, `SELECT Id, InvoiceNumber, AccountId, DueDate, Amount, Balance ` +
+                `FROM Invoice ` +
+                `WHERE Status = 'Posted' AND Balance > 0`, limit);
+            if (invoices.length === 0) {
+                return {
+                    success: true,
+                    message: "No outstanding invoices found",
+                    data: { buckets: [], totalOutstanding: 0 },
+                };
+            }
+            // Get account details
+            const accountIds = collectIds(invoices, "AccountId");
+            const accounts = await queryWithBatchedIds(this.client, "Id, AccountNumber, Name", "Account", "Id", accountIds);
+            const accountMap = new Map(accounts.map((a) => [getString(a, "Id"), a]));
+            // Define aging buckets
+            const bucketDefs = [
+                { label: "Current", minDays: -999999, maxDays: 0 },
+                { label: "1-30 Days", minDays: 1, maxDays: 30 },
+                { label: "31-60 Days", minDays: 31, maxDays: 60 },
+                { label: "61-90 Days", minDays: 61, maxDays: 90 },
+                { label: "90+ Days", minDays: 91, maxDays: null },
+            ];
+            const buckets = bucketDefs.map((def) => ({
+                ...def,
+                invoiceCount: 0,
+                totalBalance: 0,
+                invoices: [],
+            }));
+            let totalOutstanding = 0;
+            for (const inv of invoices) {
+                const dueDate = getString(inv, "DueDate") ?? today;
+                const balance = getNumber(inv, "Balance") ?? 0;
+                const daysPast = daysBetween(dueDate, today);
+                const acctId = getString(inv, "AccountId") ?? "";
+                const acct = accountMap.get(acctId);
+                totalOutstanding += balance;
+                const invoiceEntry = {
+                    invoiceId: getString(inv, "Id") ?? "",
+                    invoiceNumber: getString(inv, "InvoiceNumber") ?? "",
+                    accountName: getString(acct ?? {}, "Name") ?? "",
+                    accountNumber: getString(acct ?? {}, "AccountNumber") ?? "",
+                    balance,
+                    dueDate,
+                    daysPastDue: Math.max(0, daysPast),
+                };
+                for (const bucket of buckets) {
+                    const inMin = daysPast >= bucket.minDays;
+                    const inMax = bucket.maxDays === null || daysPast <= bucket.maxDays;
+                    if (inMin && inMax) {
+                        bucket.invoiceCount++;
+                        bucket.totalBalance += balance;
+                        bucket.invoices.push(invoiceEntry);
+                        break;
+                    }
+                }
+            }
+            // Sort invoices within each bucket by balance descending
+            for (const bucket of buckets) {
+                bucket.invoices.sort((a, b) => b.balance - a.balance);
+            }
+            return {
+                success: true,
+                message: `AR aging report: ${invoices.length} outstanding invoice(s), total $${totalOutstanding.toFixed(2)}`,
+                data: { buckets, totalOutstanding },
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                message: `Failed to get invoice aging report: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
+    async getAccountHealthScorecard(input) {
+        try {
+            const { limit } = schemas.getAccountHealthScorecard.parse(input);
+            const today = todayString();
+            const thirtyDaysAhead = addDays(new Date(), 30);
+            const thirtyDaysBack = subtractDays(new Date(), 30);
+            // Signal 1: Overdue invoices
+            const overdueInvoices = await queryAll(this.client, `SELECT Id, AccountId, Balance, DueDate ` +
+                `FROM Invoice ` +
+                `WHERE Status = 'Posted' AND Balance > 0 AND DueDate < '${today}'`, 2000);
+            // Signal 2: Expiring subscriptions (next 30 days, not auto-renewing)
+            const expiringSubscriptions = await queryAll(this.client, `SELECT Id, AccountId, ContractedMrr, TermEndDate ` +
+                `FROM Subscription ` +
+                `WHERE Status = 'Active' AND TermEndDate >= '${today}' AND TermEndDate <= '${thirtyDaysAhead}' AND AutoRenew = false`, 2000);
+            // Signal 3: Recent payment failures
+            const failedPayments = await queryAll(this.client, `SELECT Id, AccountId ` +
+                `FROM Payment ` +
+                `WHERE Status = 'Error' AND EffectiveDate >= '${thirtyDaysBack}'`, 2000);
+            // Aggregate by account
+            const accountScores = new Map();
+            const ensureAccount = (acctId) => {
+                if (!accountScores.has(acctId)) {
+                    accountScores.set(acctId, {
+                        overdueCount: 0,
+                        overdueBalance: 0,
+                        expiringCount: 0,
+                        expiringMrr: 0,
+                        paymentFailures: 0,
+                    });
+                }
+                return accountScores.get(acctId);
+            };
+            for (const inv of overdueInvoices) {
+                const acctId = getString(inv, "AccountId");
+                if (!acctId)
+                    continue;
+                const score = ensureAccount(acctId);
+                score.overdueCount++;
+                score.overdueBalance += getNumber(inv, "Balance") ?? 0;
+            }
+            for (const sub of expiringSubscriptions) {
+                const acctId = getString(sub, "AccountId");
+                if (!acctId)
+                    continue;
+                const score = ensureAccount(acctId);
+                score.expiringCount++;
+                score.expiringMrr += getNumber(sub, "ContractedMrr") ?? 0;
+            }
+            for (const pmt of failedPayments) {
+                const acctId = getString(pmt, "AccountId");
+                if (!acctId)
+                    continue;
+                const score = ensureAccount(acctId);
+                score.paymentFailures++;
+            }
+            // Calculate health scores (100 = healthy, 0 = critical)
+            const accountIds = [...accountScores.keys()];
+            if (accountIds.length === 0) {
+                return {
+                    success: true,
+                    message: "No at-risk accounts found",
+                    data: { accounts: [], totalAtRisk: 0 },
+                };
+            }
+            const accounts = await queryWithBatchedIds(this.client, "Id, AccountNumber, Name", "Account", "Id", accountIds);
+            const accountMap = new Map(accounts.map((a) => [getString(a, "Id"), a]));
+            const results = [];
+            for (const [acctId, scores] of accountScores) {
+                const acct = accountMap.get(acctId);
+                const riskFactors = [];
+                let healthScore = 100;
+                if (scores.overdueCount > 0) {
+                    healthScore -= Math.min(40, scores.overdueCount * 15);
+                    riskFactors.push(`${scores.overdueCount} overdue invoice(s), $${scores.overdueBalance.toFixed(2)} outstanding`);
+                }
+                if (scores.expiringCount > 0) {
+                    healthScore -= Math.min(30, scores.expiringCount * 10);
+                    riskFactors.push(`${scores.expiringCount} subscription(s) expiring soon, $${scores.expiringMrr.toFixed(2)} MRR at risk`);
+                }
+                if (scores.paymentFailures > 0) {
+                    healthScore -= Math.min(30, scores.paymentFailures * 15);
+                    riskFactors.push(`${scores.paymentFailures} recent payment failure(s)`);
+                }
+                results.push({
+                    accountId: acctId,
+                    accountNumber: getString(acct ?? {}, "AccountNumber") ?? "",
+                    accountName: getString(acct ?? {}, "Name") ?? "",
+                    healthScore: Math.max(0, healthScore),
+                    riskFactors,
+                    overdueInvoices: {
+                        count: scores.overdueCount,
+                        totalBalance: scores.overdueBalance,
+                    },
+                    expiringSubscriptions: {
+                        count: scores.expiringCount,
+                        totalMrr: scores.expiringMrr,
+                    },
+                    recentPaymentFailures: scores.paymentFailures,
+                });
+            }
+            // Sort by health score ascending (worst first)
+            results.sort((a, b) => a.healthScore - b.healthScore);
+            return {
+                success: true,
+                message: `Found ${results.length} account(s) with risk signals`,
+                data: {
+                    accounts: results.slice(0, limit),
+                    totalAtRisk: results.length,
+                },
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                message: `Failed to get account health scorecard: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
+    async findInvoicesByProduct(input) {
+        try {
+            const { productName, limit } = schemas.findInvoicesByProduct.parse(input);
+            const safeName = escapeZoql(productName);
+            // Step 1: Find ProductRatePlan IDs matching the product name
+            let productRatePlans = await queryAll(this.client, `SELECT Id, Name FROM ProductRatePlan WHERE Name LIKE '%${safeName}%'`);
+            if (productRatePlans.length === 0) {
+                // Try Product name
+                const products = await queryAll(this.client, `SELECT Id, Name FROM Product WHERE Name LIKE '%${safeName}%'`);
+                if (products.length === 0) {
+                    return {
+                        success: true,
+                        message: `No products found matching "${productName}"`,
+                        data: { invoiceItems: [], totalFound: 0 },
+                    };
+                }
+                const productIds = collectIds(products, "Id");
+                productRatePlans = await queryWithBatchedIds(this.client, "Id, Name", "ProductRatePlan", "ProductId", productIds);
+                if (productRatePlans.length === 0) {
+                    return {
+                        success: true,
+                        message: `No rate plans found for product "${productName}"`,
+                        data: { invoiceItems: [], totalFound: 0 },
+                    };
+                }
+            }
+            const prpIds = collectIds(productRatePlans, "Id");
+            // Step 2: Find RatePlans → RatePlanCharges
+            const ratePlans = await queryWithBatchedIds(this.client, "Id, SubscriptionId, Name", "RatePlan", "ProductRatePlanId", prpIds);
+            if (ratePlans.length === 0) {
+                return {
+                    success: true,
+                    message: `No subscriptions found with product "${productName}"`,
+                    data: { invoiceItems: [], totalFound: 0 },
+                };
+            }
+            const rpIds = collectIds(ratePlans, "Id");
+            const ratePlanCharges = await queryWithBatchedIds(this.client, "Id, RatePlanId, Name", "RatePlanCharge", "RatePlanId", rpIds);
+            if (ratePlanCharges.length === 0) {
+                return {
+                    success: true,
+                    message: `No charges found for product "${productName}"`,
+                    data: { invoiceItems: [], totalFound: 0 },
+                };
+            }
+            const rpcIds = collectIds(ratePlanCharges, "Id");
+            // Step 3: Find InvoiceItems by RatePlanChargeId
+            const invoiceItems = await queryWithBatchedIds(this.client, "Id, InvoiceId, ChargeAmount, ChargeName, ServiceStartDate, ServiceEndDate, SubscriptionId", "InvoiceItem", "RatePlanChargeId", rpcIds, undefined, limit);
+            if (invoiceItems.length === 0) {
+                return {
+                    success: true,
+                    message: `No invoice items found for product "${productName}"`,
+                    data: { invoiceItems: [], totalFound: 0 },
+                };
+            }
+            // Step 4: Get Invoice details
+            const invoiceIds = collectIds(invoiceItems, "InvoiceId");
+            const invoices = await queryWithBatchedIds(this.client, "Id, InvoiceNumber, InvoiceDate, AccountId", "Invoice", "Id", invoiceIds);
+            const invoiceMap = new Map(invoices.map((i) => [getString(i, "Id"), i]));
+            // Step 5: Get Account details
+            const accountIds = collectIds(invoices, "AccountId");
+            const accounts = await queryWithBatchedIds(this.client, "Id, AccountNumber, Name", "Account", "Id", accountIds);
+            const accountMap = new Map(accounts.map((a) => [getString(a, "Id"), a]));
+            // Build rate plan name lookup
+            const rpNameMap = new Map(ratePlans.map((rp) => [getString(rp, "Id"), getString(rp, "Name") ?? ""]));
+            const rpcToRp = new Map(ratePlanCharges.map((rpc) => [getString(rpc, "Id"), getString(rpc, "RatePlanId") ?? ""]));
+            // Get subscription number lookup
+            const subIds = collectIds(invoiceItems, "SubscriptionId");
+            const subs = await queryWithBatchedIds(this.client, "Id, SubscriptionNumber", "Subscription", "Id", subIds);
+            const subNumberMap = new Map(subs.map((s) => [getString(s, "Id"), getString(s, "SubscriptionNumber") ?? ""]));
+            // Assemble results
+            const results = invoiceItems.map((item) => {
+                const invId = getString(item, "InvoiceId") ?? "";
+                const inv = invoiceMap.get(invId);
+                const acctId = getString(inv ?? {}, "AccountId") ?? "";
+                const acct = accountMap.get(acctId);
+                const subId = getString(item, "SubscriptionId") ?? "";
+                return {
+                    invoiceId: invId,
+                    invoiceNumber: getString(inv ?? {}, "InvoiceNumber") ?? "",
+                    invoiceDate: getString(inv ?? {}, "InvoiceDate") ?? "",
+                    accountNumber: getString(acct ?? {}, "AccountNumber") ?? "",
+                    accountName: getString(acct ?? {}, "Name") ?? "",
+                    chargeAmount: getNumber(item, "ChargeAmount") ?? 0,
+                    chargeName: getString(item, "ChargeName") ?? "",
+                    ratePlanName: rpNameMap.get(rpcToRp.get(getString(item, "RatePlanChargeId") ?? "") ?? "") ?? "",
+                    subscriptionNumber: subNumberMap.get(subId) ?? "",
+                };
+            });
+            const totalChargeAmount = results.reduce((sum, r) => sum + r.chargeAmount, 0);
+            return {
+                success: true,
+                message: `Found ${results.length} invoice item(s) for "${productName}", total charges: $${totalChargeAmount.toFixed(2)}`,
+                data: {
+                    invoiceItems: results.slice(0, limit),
+                    totalFound: results.length,
+                    totalChargeAmount,
+                },
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                message: `Failed to find invoices by product: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
 }
 export const toolRegistrations = [
     // Account Tools
@@ -1211,6 +2540,59 @@ export const toolRegistrations = [
         inputSchema: schemas.listUsage,
         invoke: (handlers, args) => handlers.listUsage(args),
     },
+    // User Management
+    {
+        name: "list_users",
+        description: "List Zuora platform users with optional SCIM filter (e.g., status eq 'Active'). " +
+            "Uses REST API, not ZOQL — the User object is not ZOQL-queryable. " +
+            "Supports pagination via startIndex/count. " +
+            "Returns user names, emails, statuses, roles, and last login times.",
+        inputSchema: schemas.listUsers,
+        invoke: (handlers, args) => handlers.listUsers(args),
+    },
+    {
+        name: "get_user",
+        description: "Get details of a specific Zuora platform user by their user ID (UUID). " +
+            "Returns user name, email, status, role, profile, and last login time.",
+        inputSchema: schemas.getUser,
+        invoke: (handlers, args) => handlers.getUser(args),
+    },
+    // Bill Run Tools
+    {
+        name: "get_bill_run",
+        description: "Get details and status of a Zuora bill run by bill run ID. " +
+            "Returns bill run number, status (Pending/Processing/Completed/Error/Canceled/Posted), " +
+            "target date, invoice date, and auto-post/email settings.",
+        inputSchema: schemas.getBillRun,
+        invoke: (handlers, args) => handlers.getBillRun(args),
+    },
+    {
+        name: "list_bill_runs",
+        description: "List bill runs in Zuora with pagination. " +
+            "Returns bill run numbers, statuses, target dates, and settings.",
+        inputSchema: schemas.listBillRuns,
+        invoke: (handlers, args) => handlers.listBillRuns(args),
+    },
+    // Contact Tools
+    {
+        name: "get_contact",
+        description: "Get full details of a Zuora contact by contact ID. " +
+            "Returns name, emails, phone numbers, address, tax region, and timestamps. " +
+            "Use ZOQL to find contact IDs: SELECT Id, FirstName, LastName FROM Contact WHERE AccountId = '...'",
+        inputSchema: schemas.getContact,
+        invoke: (handlers, args) => handlers.getContact(args),
+    },
+    // Describe API
+    {
+        name: "describe_object",
+        description: "Get field metadata for any Zuora object type. Returns all fields with names, types, " +
+            "and properties (selectable, createable, updateable, filterable, required). " +
+            "Essential for building correct ZOQL queries — use this to discover available fields " +
+            "before writing SELECT statements. Object type must be PascalCase (e.g., Account, " +
+            "Invoice, Subscription, Payment, RatePlan, RatePlanCharge, BillRun, Contact).",
+        inputSchema: schemas.describeObject,
+        invoke: (handlers, args) => handlers.describeObject(args),
+    },
     // Phase 3: Write Operations (require confirmation before calling)
     // Payment Creation (HIGH risk)
     {
@@ -1332,5 +2714,127 @@ export const toolRegistrations = [
         inputSchema: schemas.createRefund,
         invoke: (handlers, args) => handlers.createRefund(args),
     },
+    // Bill Run Creation (MEDIUM risk)
+    {
+        name: "create_bill_run",
+        description: "FINANCIAL WRITE OPERATION (MEDIUM RISK): Create a bill run to generate invoices for a billing cycle. " +
+            "Bill runs process all eligible charges through the target date and generate draft invoices. " +
+            "Confirm the target date with the user before calling. " +
+            "Set autoPost=true to automatically post generated invoices. " +
+            "Set autoEmail=true (requires autoPost) to email invoices to customers. " +
+            "Requires a UUID idempotency key to prevent duplicate bill runs. " +
+            "The bill run starts in Pending status and progresses through Processing to Completed.",
+        inputSchema: schemas.createBillRun,
+        invoke: (handlers, args) => handlers.createBillRun(args),
+    },
+    // Contact Creation (LOW risk)
+    {
+        name: "create_contact",
+        description: "WRITE OPERATION (LOW RISK): Create a new contact for a Zuora account. " +
+            "Requires account ID, first name, and last name. " +
+            "Contacts can be used as bill-to or sold-to addresses via update_account. " +
+            "Requires a UUID idempotency key to prevent duplicate contacts.",
+        inputSchema: schemas.createContact,
+        invoke: (handlers, args) => handlers.createContact(args),
+    },
+    // Contact Update (LOW risk)
+    {
+        name: "update_contact",
+        description: "WRITE OPERATION (LOW RISK): Update an existing Zuora contact's information. " +
+            "Only include fields that need to change. " +
+            "ALWAYS use get_contact to review current details before updating.",
+        inputSchema: schemas.updateContact,
+        invoke: (handlers, args) => handlers.updateContact(args),
+    },
+    // ==================== Composite Tools (Read-Only) ====================
+    {
+        name: "find_accounts_by_product",
+        description: "Find accounts with active subscriptions for a specific product. " +
+            "Answers questions like 'Which accounts have Security Analytics?' " +
+            "Internally chains: ProductRatePlan → RatePlan → Subscription → Account. " +
+            "Returns account details with subscription info and rate plan names.",
+        inputSchema: schemas.findAccountsByProduct,
+        invoke: (handlers, args) => handlers.findAccountsByProduct(args),
+    },
+    {
+        name: "get_overdue_invoices",
+        description: "List all overdue invoices across all accounts, sorted by days past due. " +
+            "Answers 'Show overdue invoices' or 'What invoices are past due?' " +
+            "Filters: Posted invoices with balance > 0 and due date in the past. " +
+            "Returns invoice details with account info and days past due.",
+        inputSchema: schemas.getOverdueInvoices,
+        invoke: (handlers, args) => handlers.getOverdueInvoices(args),
+    },
+    {
+        name: "get_expiring_subscriptions",
+        description: "Find subscriptions expiring within a time window. " +
+            "Answers 'What subscriptions expire this month?' or 'Renewal pipeline for Q1.' " +
+            "Shows MRR at risk (non-auto-renewing subscriptions). " +
+            "Returns subscription details with account info and days until expiry.",
+        inputSchema: schemas.getExpiringSubscriptions,
+        invoke: (handlers, args) => handlers.getExpiringSubscriptions(args),
+    },
+    {
+        name: "get_account_billing_overview",
+        description: "Comprehensive billing summary for a single account in one call. " +
+            "Answers 'What's the billing status for account X?' " +
+            "Combines: account details + recent invoices + payments + active subscriptions. " +
+            "Shows outstanding balance, overdue amounts, MRR, and recent activity.",
+        inputSchema: schemas.getAccountBillingOverview,
+        invoke: (handlers, args) => handlers.getAccountBillingOverview(args),
+    },
+    {
+        name: "get_revenue_by_product",
+        description: "MRR breakdown by product across all active subscriptions. " +
+            "Answers 'What's our revenue by product?' or 'MRR breakdown.' " +
+            "Chains: Subscription → RatePlan → ProductRatePlan → Product. " +
+            "Returns products sorted by MRR with subscription details.",
+        inputSchema: schemas.getRevenueByProduct,
+        invoke: (handlers, args) => handlers.getRevenueByProduct(args),
+    },
+    {
+        name: "get_payment_reconciliation",
+        description: "Payment reconciliation report for a date range. " +
+            "Answers 'What payments were received this month?' " +
+            "Returns payment list with account details, summary stats, and status breakdown.",
+        inputSchema: schemas.getPaymentReconciliation,
+        invoke: (handlers, args) => handlers.getPaymentReconciliation(args),
+    },
+    {
+        name: "get_recently_cancelled_subscriptions",
+        description: "Find subscriptions cancelled within a recent time window. " +
+            "Answers 'What churned last month?' or 'Recent cancellations.' " +
+            "Shows lost MRR and affected products. " +
+            "Returns cancelled subscription details with account info.",
+        inputSchema: schemas.getRecentlyCancelledSubscriptions,
+        invoke: (handlers, args) => handlers.getRecentlyCancelledSubscriptions(args),
+    },
+    {
+        name: "get_invoice_aging_report",
+        description: "AR aging report: all outstanding invoices bucketed by days past due. " +
+            "Answers 'Give me an AR aging report' or 'What does our accounts receivable look like?' " +
+            "Buckets: Current, 1-30, 31-60, 61-90, 90+ days. " +
+            "Returns aging buckets with invoice and account details.",
+        inputSchema: schemas.getInvoiceAgingReport,
+        invoke: (handlers, args) => handlers.getInvoiceAgingReport(args),
+    },
+    {
+        name: "get_account_health_scorecard",
+        description: "Identify at-risk accounts using multiple signals: overdue invoices, " +
+            "expiring subscriptions (non-auto-renewing), and recent payment failures. " +
+            "Answers 'Which accounts are at risk?' " +
+            "Returns accounts sorted by health score (0=critical, 100=healthy) with risk factors.",
+        inputSchema: schemas.getAccountHealthScorecard,
+        invoke: (handlers, args) => handlers.getAccountHealthScorecard(args),
+    },
+    {
+        name: "find_invoices_by_product",
+        description: "Find invoice line items for a specific product. " +
+            "Answers 'Show invoices for Security Analytics' or 'What was billed for product X?' " +
+            "Chains: ProductRatePlan → RatePlan → RatePlanCharge → InvoiceItem → Invoice → Account. " +
+            "Returns invoice items with charge amounts, dates, and account details.",
+        inputSchema: schemas.findInvoicesByProduct,
+        invoke: (handlers, args) => handlers.findInvoicesByProduct(args),
+    },
 ];
 //# sourceMappingURL=tools.js.map