@goodsamsoftware/freshbooks-mcp 1.0.0

package/dist/tools/payment/index.js

@@ -0,0 +1,13 @@
+/**
+ * Payment Tools - FreshBooks payment management
+ *
+ * Exports all payment-related MCP tools for recording and tracking payments received.
+ */
+// Export schemas
+// Export tool definitions
+export { paymentListTool } from './payment-list.js';
+export { paymentSingleTool } from './payment-single.js';
+export { paymentCreateTool } from './payment-create.js';
+export { paymentUpdateTool } from './payment-update.js';
+export { paymentDeleteTool } from './payment-delete.js';
+//# sourceMappingURL=index.js.map

package/dist/tools/payment/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/tools/payment/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,iBAAiB;AAEjB,0BAA0B;AAC1B,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/tools/payment/payment-create.d.ts

@@ -0,0 +1,127 @@
+/**
+ * payment_create Tool
+ *
+ * Record a new payment against an invoice in FreshBooks.
+ */
+import { z } from 'zod';
+import { PaymentCreateInputSchema, PaymentSingleOutputSchema } from './schemas.js';
+import { FreshBooksClientWrapper } from '../../client/index.js';
+/**
+ * Tool definition for payment_create
+ */
+export declare const paymentCreateTool: {
+    name: string;
+    description: string;
+    inputSchema: z.ZodObject<{
+        accountId: z.ZodString;
+        invoiceId: z.ZodNumber;
+        amount: z.ZodObject<{
+            amount: z.ZodString;
+            code: z.ZodDefault<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            code: string;
+            amount: string;
+        }, {
+            amount: string;
+            code?: string | undefined;
+        }>;
+        date: z.ZodString;
+        type: z.ZodDefault<z.ZodEnum<["Check", "Credit", "Cash", "Bank Transfer", "Debit", "PayPal", "Credit Card", "Other", "2Checkout", "Stripe", "ACH", "Wire Transfer"]>>;
+        note: z.ZodOptional<z.ZodString>;
+        sendEmailReceipt: z.ZodOptional<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        accountId: string;
+        date: string;
+        type: "Check" | "Credit" | "Cash" | "Bank Transfer" | "Debit" | "PayPal" | "Credit Card" | "Other" | "2Checkout" | "Stripe" | "ACH" | "Wire Transfer";
+        amount: {
+            code: string;
+            amount: string;
+        };
+        invoiceId: number;
+        note?: string | undefined;
+        sendEmailReceipt?: boolean | undefined;
+    }, {
+        accountId: string;
+        date: string;
+        amount: {
+            amount: string;
+            code?: string | undefined;
+        };
+        invoiceId: number;
+        type?: "Check" | "Credit" | "Cash" | "Bank Transfer" | "Debit" | "PayPal" | "Credit Card" | "Other" | "2Checkout" | "Stripe" | "ACH" | "Wire Transfer" | undefined;
+        note?: string | undefined;
+        sendEmailReceipt?: boolean | undefined;
+    }>;
+    outputSchema: z.ZodObject<{
+        id: z.ZodNumber;
+        invoiceId: z.ZodNumber;
+        accountId: z.ZodString;
+        amount: z.ZodObject<{
+            amount: z.ZodString;
+            code: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            code: string;
+            amount: string;
+        }, {
+            code: string;
+            amount: string;
+        }>;
+        date: z.ZodString;
+        type: z.ZodEnum<["Check", "Credit", "Cash", "Bank Transfer", "Debit", "PayPal", "Credit Card", "Other", "2Checkout", "Stripe", "ACH", "Wire Transfer"]>;
+        note: z.ZodNullable<z.ZodString>;
+        clientId: z.ZodNumber;
+        visState: z.ZodOptional<z.ZodUnion<[z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>]>>;
+        logId: z.ZodOptional<z.ZodNumber>;
+        updated: z.ZodOptional<z.ZodString>;
+        creditId: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        overpaymentId: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        gateway: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        fromCredit: z.ZodOptional<z.ZodBoolean>;
+        sendEmailReceipt: z.ZodOptional<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        accountId: string;
+        date: string;
+        type: "Check" | "Credit" | "Cash" | "Bank Transfer" | "Debit" | "PayPal" | "Credit Card" | "Other" | "2Checkout" | "Stripe" | "ACH" | "Wire Transfer";
+        id: number;
+        amount: {
+            code: string;
+            amount: string;
+        };
+        clientId: number;
+        note: string | null;
+        invoiceId: number;
+        visState?: 0 | 1 | 2 | undefined;
+        updated?: string | undefined;
+        logId?: number | undefined;
+        creditId?: number | null | undefined;
+        overpaymentId?: number | null | undefined;
+        gateway?: string | null | undefined;
+        fromCredit?: boolean | undefined;
+        sendEmailReceipt?: boolean | undefined;
+    }, {
+        accountId: string;
+        date: string;
+        type: "Check" | "Credit" | "Cash" | "Bank Transfer" | "Debit" | "PayPal" | "Credit Card" | "Other" | "2Checkout" | "Stripe" | "ACH" | "Wire Transfer";
+        id: number;
+        amount: {
+            code: string;
+            amount: string;
+        };
+        clientId: number;
+        note: string | null;
+        invoiceId: number;
+        visState?: 0 | 1 | 2 | undefined;
+        updated?: string | undefined;
+        logId?: number | undefined;
+        creditId?: number | null | undefined;
+        overpaymentId?: number | null | undefined;
+        gateway?: string | null | undefined;
+        fromCredit?: boolean | undefined;
+        sendEmailReceipt?: boolean | undefined;
+    }>;
+    /**
+     * Execute the tool
+     */
+    execute(input: z.infer<typeof PaymentCreateInputSchema>, client: FreshBooksClientWrapper): Promise<z.infer<typeof PaymentSingleOutputSchema>>;
+};
+//# sourceMappingURL=payment-create.d.ts.map

package/dist/tools/payment/payment-create.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"payment-create.d.ts","sourceRoot":"","sources":["../../../src/tools/payment/payment-create.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,wBAAwB,EAAE,yBAAyB,EAAE,MAAM,cAAc,CAAC;AACnF,OAAO,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AAKhE;;GAEG;AACH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAkC5B;;OAEG;mBAEM,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,UACvC,uBAAuB,GAC9B,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;CAsDtD,CAAC"}

package/dist/tools/payment/payment-create.js

@@ -0,0 +1,84 @@
+/**
+ * payment_create Tool
+ *
+ * Record a new payment against an invoice in FreshBooks.
+ */
+import { PaymentCreateInputSchema, PaymentSingleOutputSchema } from './schemas.js';
+import { ErrorHandler } from '../../errors/error-handler.js';
+import { logger } from '../../utils/logger.js';
+/**
+ * Tool definition for payment_create
+ */
+export const paymentCreateTool = {
+    name: 'payment_create',
+    description: `Record a new payment received against an invoice in FreshBooks.
+
+WHEN TO USE:
+- User received payment from a client
+- User says "record payment", "log payment", "client paid invoice"
+- User wants to mark an invoice as paid or partially paid
+
+REQUIRED:
+- accountId: FreshBooks account ID (get from auth_status if not specified)
+- invoiceId: Invoice being paid (required)
+- amount: Payment amount with currency code
+- date: When payment was received (ISO 8601 format)
+
+OPTIONAL BUT HELPFUL:
+- type: Payment method (Check, Credit Card, PayPal, Cash, etc.)
+- note: Payment reference number, check number, or other memo
+- sendEmailReceipt: Whether to email receipt to client (default: false)
+
+PAYMENT TYPES:
+- Check, Credit Card, Cash, Bank Transfer, PayPal, Stripe, ACH, Wire Transfer, etc.
+
+EXAMPLE PROMPTS:
+- "Record a $500 payment for invoice #12345, paid by check today"
+- "Client paid $1,200 via PayPal on Jan 15 for invoice 67890"
+- "Log cash payment of $250 for invoice #555"
+
+RETURNS:
+Created payment record with ID, applied amount, and updated invoice balance.`,
+    inputSchema: PaymentCreateInputSchema,
+    outputSchema: PaymentSingleOutputSchema,
+    /**
+     * Execute the tool
+     */
+    async execute(input, client) {
+        const handler = ErrorHandler.wrapHandler('payment_create', async (input, _context) => {
+            const { accountId, ...paymentData } = input;
+            logger.debug('Creating payment', {
+                accountId,
+                invoiceId: paymentData.invoiceId,
+                amount: paymentData.amount,
+            });
+            // Build payment object using camelCase properties
+            // The FreshBooks SDK's transformPaymentRequest() will convert to API format
+            const payment = {
+                invoiceId: paymentData.invoiceId,
+                amount: paymentData.amount,
+                date: paymentData.date,
+                type: paymentData.type || 'Cash',
+            };
+            // Add optional fields if provided
+            if (paymentData.note !== undefined)
+                payment.note = paymentData.note;
+            // Note: sendEmailReceipt is not supported by the SDK transform function
+            const result = await client.executeWithRetry('payment_create', async (fbClient) => {
+                const response = await fbClient.payments.create(payment, accountId);
+                if (!response.ok) {
+                    throw response.error;
+                }
+                return response.data;
+            });
+            // FreshBooks returns: { payment: { ... } }
+            const createdPayment = result.payment ?? result;
+            logger.info('Payment created successfully', {
+                paymentId: createdPayment.id,
+            });
+            return createdPayment;
+        });
+        return handler(input, { accountId: input.accountId });
+    },
+};
+//# sourceMappingURL=payment-create.js.map

package/dist/tools/payment/payment-create.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"payment-create.js","sourceRoot":"","sources":["../../../src/tools/payment/payment-create.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,wBAAwB,EAAE,yBAAyB,EAAE,MAAM,cAAc,CAAC;AAEnF,OAAO,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAE7D,OAAO,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAE/C;;GAEG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAC/B,IAAI,EAAE,gBAAgB;IACtB,WAAW,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;6EA2B8D;IAE3E,WAAW,EAAE,wBAAwB;IACrC,YAAY,EAAE,yBAAyB;IAEvC;;OAEG;IACH,KAAK,CAAC,OAAO,CACX,KAA+C,EAC/C,MAA+B;QAE/B,MAAM,OAAO,GAAG,YAAY,CAAC,WAAW,CACtC,gBAAgB,EAChB,KAAK,EACH,KAA+C,EAC/C,QAAqB,EACrB,EAAE;YACF,MAAM,EAAE,SAAS,EAAE,GAAG,WAAW,EAAE,GAAG,KAAK,CAAC;YAE5C,MAAM,CAAC,KAAK,CAAC,kBAAkB,EAAE;gBAC/B,SAAS;gBACT,SAAS,EAAE,WAAW,CAAC,SAAS;gBAChC,MAAM,EAAE,WAAW,CAAC,MAAM;aAC3B,CAAC,CAAC;YAEH,kDAAkD;YAClD,4EAA4E;YAC5E,MAAM,OAAO,GAA4B;gBACvC,SAAS,EAAE,WAAW,CAAC,SAAS;gBAChC,MAAM,EAAE,WAAW,CAAC,MAAM;gBAC1B,IAAI,EAAE,WAAW,CAAC,IAAI;gBACtB,IAAI,EAAE,WAAW,CAAC,IAAI,IAAI,MAAM;aACjC,CAAC;YAEF,kCAAkC;YAClC,IAAI,WAAW,CAAC,IAAI,KAAK,SAAS;gBAAE,OAAO,CAAC,IAAI,GAAG,WAAW,CAAC,IAAI,CAAC;YACpE,wEAAwE;YAExE,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,gBAAgB,CAC1C,gBAAgB,EAChB,KAAK,EAAE,QAAQ,EAAE,EAAE;gBACjB,MAAM,QAAQ,GAAG,MAAM,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC,OAAc,EAAE,SAAS,CAAC,CAAC;gBAE3E,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;oBACjB,MAAM,QAAQ,CAAC,KAAK,CAAC;gBACvB,CAAC;gBAED,OAAO,QAAQ,CAAC,IAAI,CAAC;YACvB,CAAC,CACF,CAAC;YAEF,2CAA2C;YAC3C,MAAM,cAAc,GAAI,MAAgC,CAAC,OAAO,IAAI,MAAM,CAAC;YAE3E,MAAM,CAAC,IAAI,CAAC,8BAA8B,EAAE;gBAC1C,SAAS,EAAG,cAAkC,CAAC,EAAE;aAClD,CAAC,CAAC;YAEH,OAAO,cAA2D,CAAC;QACrE,CAAC,CACF,CAAC;QAEF,OAAO,OAAO,CAAC,KAAK,EAAE,EAAE,SAAS,EAAE,KAAK,CAAC,SAAS,EAAE,CAAC,CAAC;IACxD,CAAC;CACF,CAAC"}

package/dist/tools/payment/payment-delete.d.ts

@@ -0,0 +1,40 @@
+/**
+ * payment_delete Tool
+ *
+ * Delete a payment from FreshBooks.
+ */
+import { z } from 'zod';
+import { PaymentDeleteInputSchema, PaymentDeleteOutputSchema } from './schemas.js';
+import { FreshBooksClientWrapper } from '../../client/index.js';
+/**
+ * Tool definition for payment_delete
+ */
+export declare const paymentDeleteTool: {
+    name: string;
+    description: string;
+    inputSchema: z.ZodObject<{
+        accountId: z.ZodString;
+        paymentId: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        accountId: string;
+        paymentId: number;
+    }, {
+        accountId: string;
+        paymentId: number;
+    }>;
+    outputSchema: z.ZodObject<{
+        success: z.ZodBoolean;
+        paymentId: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        success: boolean;
+        paymentId: number;
+    }, {
+        success: boolean;
+        paymentId: number;
+    }>;
+    /**
+     * Execute the tool
+     */
+    execute(input: z.infer<typeof PaymentDeleteInputSchema>, client: FreshBooksClientWrapper): Promise<z.infer<typeof PaymentDeleteOutputSchema>>;
+};
+//# sourceMappingURL=payment-delete.d.ts.map

package/dist/tools/payment/payment-delete.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"payment-delete.d.ts","sourceRoot":"","sources":["../../../src/tools/payment/payment-delete.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,wBAAwB,EAAE,yBAAyB,EAAE,MAAM,cAAc,CAAC;AACnF,OAAO,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AAKhE;;GAEG;AACH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;IA6B5B;;OAEG;mBAEM,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,UACvC,uBAAuB,GAC9B,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;CAwCtD,CAAC"}

package/dist/tools/payment/payment-delete.js

@@ -0,0 +1,67 @@
+/**
+ * payment_delete Tool
+ *
+ * Delete a payment from FreshBooks.
+ */
+import { PaymentDeleteInputSchema, PaymentDeleteOutputSchema } from './schemas.js';
+import { ErrorHandler } from '../../errors/error-handler.js';
+import { logger } from '../../utils/logger.js';
+/**
+ * Tool definition for payment_delete
+ */
+export const paymentDeleteTool = {
+    name: 'payment_delete',
+    description: `Delete a payment from FreshBooks.
+
+WHEN TO USE:
+- User recorded payment in error
+- User says "delete payment", "remove payment", "cancel payment"
+- User needs to undo a payment entry
+
+REQUIRED:
+- accountId: FreshBooks account ID (get from auth_status if not specified)
+- paymentId: Payment to delete
+
+IMPORTANT NOTES:
+- Deleting a payment will adjust the invoice balance back
+- This cannot be undone - use with caution
+- Consider updating instead of deleting if just correcting details
+
+EXAMPLE PROMPTS:
+- "Delete payment #12345"
+- "Remove payment 67890 - it was entered twice"
+- "Cancel payment ID 555"
+
+RETURNS:
+Confirmation of deletion with the deleted payment ID.`,
+    inputSchema: PaymentDeleteInputSchema,
+    outputSchema: PaymentDeleteOutputSchema,
+    /**
+     * Execute the tool
+     */
+    async execute(input, client) {
+        const handler = ErrorHandler.wrapHandler('payment_delete', async (input, _context) => {
+            const { accountId, paymentId } = input;
+            logger.debug('Deleting payment', {
+                accountId,
+                paymentId,
+            });
+            await client.executeWithRetry('payment_delete', async (fbClient) => {
+                const response = await fbClient.payments.delete(accountId, String(paymentId));
+                if (!response.ok) {
+                    throw response.error;
+                }
+                return response.data;
+            });
+            logger.info('Payment deleted successfully', {
+                paymentId,
+            });
+            return {
+                success: true,
+                paymentId,
+            };
+        });
+        return handler(input, { accountId: input.accountId });
+    },
+};
+//# sourceMappingURL=payment-delete.js.map

package/dist/tools/payment/payment-delete.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"payment-delete.js","sourceRoot":"","sources":["../../../src/tools/payment/payment-delete.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,wBAAwB,EAAE,yBAAyB,EAAE,MAAM,cAAc,CAAC;AAEnF,OAAO,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAE7D,OAAO,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAE/C;;GAEG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAC/B,IAAI,EAAE,gBAAgB;IACtB,WAAW,EAAE;;;;;;;;;;;;;;;;;;;;;;sDAsBuC;IAEpD,WAAW,EAAE,wBAAwB;IACrC,YAAY,EAAE,yBAAyB;IAEvC;;OAEG;IACH,KAAK,CAAC,OAAO,CACX,KAA+C,EAC/C,MAA+B;QAE/B,MAAM,OAAO,GAAG,YAAY,CAAC,WAAW,CACtC,gBAAgB,EAChB,KAAK,EACH,KAA+C,EAC/C,QAAqB,EACrB,EAAE;YACF,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,GAAG,KAAK,CAAC;YAEvC,MAAM,CAAC,KAAK,CAAC,kBAAkB,EAAE;gBAC/B,SAAS;gBACT,SAAS;aACV,CAAC,CAAC;YAEH,MAAM,MAAM,CAAC,gBAAgB,CAC3B,gBAAgB,EAChB,KAAK,EAAE,QAAQ,EAAE,EAAE;gBACjB,MAAM,QAAQ,GAAG,MAAM,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC;gBAE9E,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;oBACjB,MAAM,QAAQ,CAAC,KAAK,CAAC;gBACvB,CAAC;gBAED,OAAO,QAAQ,CAAC,IAAI,CAAC;YACvB,CAAC,CACF,CAAC;YAEF,MAAM,CAAC,IAAI,CAAC,8BAA8B,EAAE;gBAC1C,SAAS;aACV,CAAC,CAAC;YAEH,OAAO;gBACL,OAAO,EAAE,IAAI;gBACb,SAAS;aACV,CAAC;QACJ,CAAC,CACF,CAAC;QAEF,OAAO,OAAO,CAAC,KAAK,EAAE,EAAE,SAAS,EAAE,KAAK,CAAC,SAAS,EAAE,CAAC,CAAC;IACxD,CAAC;CACF,CAAC"}

package/dist/tools/payment/payment-list.d.ts

@@ -0,0 +1,186 @@
+/**
+ * payment_list Tool
+ *
+ * List payments received with pagination and optional filtering.
+ */
+import { z } from 'zod';
+import { PaymentListInputSchema, PaymentListOutputSchema } from './schemas.js';
+import { FreshBooksClientWrapper } from '../../client/index.js';
+/**
+ * Tool definition for payment_list
+ */
+export declare const paymentListTool: {
+    name: string;
+    description: string;
+    inputSchema: z.ZodObject<{
+        accountId: z.ZodString;
+        page: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
+        perPage: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
+        invoiceId: z.ZodOptional<z.ZodNumber>;
+        clientId: z.ZodOptional<z.ZodNumber>;
+        dateFrom: z.ZodOptional<z.ZodString>;
+        dateTo: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        accountId: string;
+        page?: number | undefined;
+        perPage?: number | undefined;
+        clientId?: number | undefined;
+        invoiceId?: number | undefined;
+        dateFrom?: string | undefined;
+        dateTo?: string | undefined;
+    }, {
+        accountId: string;
+        page?: number | undefined;
+        perPage?: number | undefined;
+        clientId?: number | undefined;
+        invoiceId?: number | undefined;
+        dateFrom?: string | undefined;
+        dateTo?: string | undefined;
+    }>;
+    outputSchema: z.ZodObject<{
+        payments: z.ZodArray<z.ZodObject<{
+            id: z.ZodNumber;
+            invoiceId: z.ZodNumber;
+            accountId: z.ZodString;
+            amount: z.ZodObject<{
+                amount: z.ZodString;
+                code: z.ZodString;
+            }, "strip", z.ZodTypeAny, {
+                code: string;
+                amount: string;
+            }, {
+                code: string;
+                amount: string;
+            }>;
+            date: z.ZodString;
+            type: z.ZodEnum<["Check", "Credit", "Cash", "Bank Transfer", "Debit", "PayPal", "Credit Card", "Other", "2Checkout", "Stripe", "ACH", "Wire Transfer"]>;
+            note: z.ZodNullable<z.ZodString>;
+            clientId: z.ZodNumber;
+            visState: z.ZodOptional<z.ZodUnion<[z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>]>>;
+            logId: z.ZodOptional<z.ZodNumber>;
+            updated: z.ZodOptional<z.ZodString>;
+            creditId: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+            overpaymentId: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+            gateway: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            fromCredit: z.ZodOptional<z.ZodBoolean>;
+            sendEmailReceipt: z.ZodOptional<z.ZodBoolean>;
+        }, "strip", z.ZodTypeAny, {
+            accountId: string;
+            date: string;
+            type: "Check" | "Credit" | "Cash" | "Bank Transfer" | "Debit" | "PayPal" | "Credit Card" | "Other" | "2Checkout" | "Stripe" | "ACH" | "Wire Transfer";
+            id: number;
+            amount: {
+                code: string;
+                amount: string;
+            };
+            clientId: number;
+            note: string | null;
+            invoiceId: number;
+            visState?: 0 | 1 | 2 | undefined;
+            updated?: string | undefined;
+            logId?: number | undefined;
+            creditId?: number | null | undefined;
+            overpaymentId?: number | null | undefined;
+            gateway?: string | null | undefined;
+            fromCredit?: boolean | undefined;
+            sendEmailReceipt?: boolean | undefined;
+        }, {
+            accountId: string;
+            date: string;
+            type: "Check" | "Credit" | "Cash" | "Bank Transfer" | "Debit" | "PayPal" | "Credit Card" | "Other" | "2Checkout" | "Stripe" | "ACH" | "Wire Transfer";
+            id: number;
+            amount: {
+                code: string;
+                amount: string;
+            };
+            clientId: number;
+            note: string | null;
+            invoiceId: number;
+            visState?: 0 | 1 | 2 | undefined;
+            updated?: string | undefined;
+            logId?: number | undefined;
+            creditId?: number | null | undefined;
+            overpaymentId?: number | null | undefined;
+            gateway?: string | null | undefined;
+            fromCredit?: boolean | undefined;
+            sendEmailReceipt?: boolean | undefined;
+        }>, "many">;
+        pagination: z.ZodObject<{
+            page: z.ZodNumber;
+            pages: z.ZodNumber;
+            perPage: z.ZodNumber;
+            total: z.ZodNumber;
+        }, "strip", z.ZodTypeAny, {
+            total: number;
+            page: number;
+            perPage: number;
+            pages: number;
+        }, {
+            total: number;
+            page: number;
+            perPage: number;
+            pages: number;
+        }>;
+    }, "strip", z.ZodTypeAny, {
+        pagination: {
+            total: number;
+            page: number;
+            perPage: number;
+            pages: number;
+        };
+        payments: {
+            accountId: string;
+            date: string;
+            type: "Check" | "Credit" | "Cash" | "Bank Transfer" | "Debit" | "PayPal" | "Credit Card" | "Other" | "2Checkout" | "Stripe" | "ACH" | "Wire Transfer";
+            id: number;
+            amount: {
+                code: string;
+                amount: string;
+            };
+            clientId: number;
+            note: string | null;
+            invoiceId: number;
+            visState?: 0 | 1 | 2 | undefined;
+            updated?: string | undefined;
+            logId?: number | undefined;
+            creditId?: number | null | undefined;
+            overpaymentId?: number | null | undefined;
+            gateway?: string | null | undefined;
+            fromCredit?: boolean | undefined;
+            sendEmailReceipt?: boolean | undefined;
+        }[];
+    }, {
+        pagination: {
+            total: number;
+            page: number;
+            perPage: number;
+            pages: number;
+        };
+        payments: {
+            accountId: string;
+            date: string;
+            type: "Check" | "Credit" | "Cash" | "Bank Transfer" | "Debit" | "PayPal" | "Credit Card" | "Other" | "2Checkout" | "Stripe" | "ACH" | "Wire Transfer";
+            id: number;
+            amount: {
+                code: string;
+                amount: string;
+            };
+            clientId: number;
+            note: string | null;
+            invoiceId: number;
+            visState?: 0 | 1 | 2 | undefined;
+            updated?: string | undefined;
+            logId?: number | undefined;
+            creditId?: number | null | undefined;
+            overpaymentId?: number | null | undefined;
+            gateway?: string | null | undefined;
+            fromCredit?: boolean | undefined;
+            sendEmailReceipt?: boolean | undefined;
+        }[];
+    }>;
+    /**
+     * Execute the tool
+     */
+    execute(input: z.infer<typeof PaymentListInputSchema>, client: FreshBooksClientWrapper): Promise<z.infer<typeof PaymentListOutputSchema>>;
+};
+//# sourceMappingURL=payment-list.d.ts.map

package/dist/tools/payment/payment-list.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"payment-list.d.ts","sourceRoot":"","sources":["../../../src/tools/payment/payment-list.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,sBAAsB,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAC;AAC/E,OAAO,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AAKhE;;GAEG;AACH,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAkC1B;;OAEG;mBAEM,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,UACrC,uBAAuB,GAC9B,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;CA6FpD,CAAC"}

package/dist/tools/payment/payment-list.js

@@ -0,0 +1,113 @@
+/**
+ * payment_list Tool
+ *
+ * List payments received with pagination and optional filtering.
+ */
+import { PaymentListInputSchema, PaymentListOutputSchema } from './schemas.js';
+import { ErrorHandler } from '../../errors/error-handler.js';
+import { logger } from '../../utils/logger.js';
+/**
+ * Tool definition for payment_list
+ */
+export const paymentListTool = {
+    name: 'payment_list',
+    description: `List payments received from FreshBooks with optional filtering and pagination.
+
+WHEN TO USE:
+- User asks to "see payments", "list payments", "show received payments"
+- User wants to review payment history
+- User needs to find a specific payment or check invoice payment status
+
+REQUIRED:
+- accountId: FreshBooks account ID (get from auth_status if not specified)
+
+OPTIONAL FILTERS:
+- invoiceId: Show payments for a specific invoice
+- clientId: Show payments from a specific client
+- dateFrom/dateTo: Filter by payment date range (ISO 8601)
+
+PAGINATION:
+- page: Page number (default: 1)
+- perPage: Results per page (default: 30, max: 100)
+
+EXAMPLE PROMPTS:
+- "Show me all payments received this month"
+- "List payments for invoice #12345"
+- "Show payments from client ABC"
+- "What payments did we receive between Jan 1 and Jan 31?"
+
+RETURNS:
+Array of payments with amounts, dates, payment types, and associated invoice/client info.
+Includes pagination metadata for navigating large result sets.`,
+    inputSchema: PaymentListInputSchema,
+    outputSchema: PaymentListOutputSchema,
+    /**
+     * Execute the tool
+     */
+    async execute(input, client) {
+        const handler = ErrorHandler.wrapHandler('payment_list', async (input, _context) => {
+            logger.debug('Listing payments', {
+                accountId: input.accountId,
+                filters: {
+                    invoiceId: input.invoiceId,
+                    clientId: input.clientId,
+                },
+            });
+            const result = await client.executeWithRetry('payment_list', async (fbClient) => {
+                // Import query builders from SDK
+                const { SearchQueryBuilder, PaginationQueryBuilder } = await import('@freshbooks/api/dist/models/builders/index.js');
+                // Build query builders
+                const queryBuilders = [];
+                // Add pagination
+                if (input.page || input.perPage) {
+                    const pagination = new PaginationQueryBuilder()
+                        .page(input.page || 1)
+                        .perPage(input.perPage || 30);
+                    queryBuilders.push(pagination);
+                }
+                // Add search filters
+                const hasFilters = input.invoiceId ||
+                    input.clientId ||
+                    input.dateFrom ||
+                    input.dateTo;
+                if (hasFilters) {
+                    const search = new SearchQueryBuilder();
+                    if (input.invoiceId) {
+                        search.equals('invoiceid', input.invoiceId);
+                    }
+                    if (input.clientId) {
+                        search.equals('clientid', input.clientId);
+                    }
+                    if (input.dateFrom || input.dateTo) {
+                        const minDate = input.dateFrom ?? '1970-01-01T00:00:00Z';
+                        const maxDate = input.dateTo ?? new Date().toISOString();
+                        search.between('date', { min: minDate, max: maxDate });
+                    }
+                    queryBuilders.push(search);
+                }
+                // Call FreshBooks API
+                const response = await fbClient.payments.list(input.accountId, queryBuilders);
+                if (!response.ok) {
+                    throw response.error;
+                }
+                const data = response.data;
+                return {
+                    payments: data.payments || [],
+                    pagination: {
+                        page: data.pages?.page || 1,
+                        pages: data.pages?.pages || 1,
+                        perPage: data.pages?.perPage || data.pages?.per_page || 30,
+                        total: data.pages?.total || 0,
+                    },
+                };
+            });
+            logger.info('Payments listed successfully', {
+                count: result.payments.length,
+                total: result.pagination.total,
+            });
+            return result;
+        });
+        return handler(input, { accountId: input.accountId });
+    },
+};
+//# sourceMappingURL=payment-list.js.map

package/dist/tools/payment/payment-list.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"payment-list.js","sourceRoot":"","sources":["../../../src/tools/payment/payment-list.ts"],"names":[],"mappings":"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"}