@goodsamsoftware/freshbooks-mcp 1.0.0

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

@@ -0,0 +1,97 @@
+/**
+ * payment_single Tool
+ *
+ * Retrieve a single payment by ID.
+ */
+import { z } from 'zod';
+import { PaymentSingleInputSchema, PaymentSingleOutputSchema } from './schemas.js';
+import { FreshBooksClientWrapper } from '../../client/index.js';
+/**
+ * Tool definition for payment_single
+ */
+export declare const paymentSingleTool: {
+    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<{
+        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 PaymentSingleInputSchema>, client: FreshBooksClientWrapper): Promise<z.infer<typeof PaymentSingleOutputSchema>>;
+};
+//# sourceMappingURL=payment-single.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"payment-single.d.ts","sourceRoot":"","sources":["../../../src/tools/payment/payment-single.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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAyB5B;;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-single.js

@@ -0,0 +1,62 @@
+/**
+ * payment_single Tool
+ *
+ * Retrieve a single payment by ID.
+ */
+import { PaymentSingleInputSchema, PaymentSingleOutputSchema } from './schemas.js';
+import { ErrorHandler } from '../../errors/error-handler.js';
+import { logger } from '../../utils/logger.js';
+/**
+ * Tool definition for payment_single
+ */
+export const paymentSingleTool = {
+    name: 'payment_single',
+    description: `Retrieve a single payment by ID from FreshBooks.
+
+WHEN TO USE:
+- User asks for details about a specific payment
+- User provides a payment ID and wants full information
+- User needs to verify payment details before updating
+
+REQUIRED:
+- accountId: FreshBooks account ID (get from auth_status if not specified)
+- paymentId: The payment identifier
+
+EXAMPLE PROMPTS:
+- "Show me payment #12345"
+- "Get details for payment 67890"
+- "What are the details of payment ID 555?"
+
+RETURNS:
+Complete payment record including amount, date, payment type, invoice ID,
+client ID, notes, and all other payment properties.`,
+    inputSchema: PaymentSingleInputSchema,
+    outputSchema: PaymentSingleOutputSchema,
+    /**
+     * Execute the tool
+     */
+    async execute(input, client) {
+        const handler = ErrorHandler.wrapHandler('payment_single', async (input, _context) => {
+            const { accountId, paymentId } = input;
+            logger.debug('Retrieving payment', {
+                accountId,
+                paymentId,
+            });
+            const result = await client.executeWithRetry('payment_single', async (fbClient) => {
+                const response = await fbClient.payments.single(accountId, String(paymentId));
+                if (!response.ok) {
+                    throw response.error;
+                }
+                return response.data;
+            });
+            // FreshBooks returns: { payment: { ... } }
+            const payment = result.payment ?? result;
+            logger.info('Payment retrieved successfully', {
+                paymentId,
+            });
+            return payment;
+        });
+        return handler(input, { accountId: input.accountId });
+    },
+};
+//# sourceMappingURL=payment-single.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"payment-single.js","sourceRoot":"","sources":["../../../src/tools/payment/payment-single.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;;;;;;;;;;;;;;;;;;oDAkBqC;IAElD,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,oBAAoB,EAAE;gBACjC,SAAS;gBACT,SAAS;aACV,CAAC,CAAC;YAEH,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,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,2CAA2C;YAC3C,MAAM,OAAO,GAAI,MAAgC,CAAC,OAAO,IAAI,MAAM,CAAC;YAEpE,MAAM,CAAC,IAAI,CAAC,gCAAgC,EAAE;gBAC5C,SAAS;aACV,CAAC,CAAC;YAEH,OAAO,OAAoD,CAAC;QAC9D,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-update.d.ts

@@ -0,0 +1,124 @@
+/**
+ * payment_update Tool
+ *
+ * Update an existing payment in FreshBooks.
+ */
+import { z } from 'zod';
+import { PaymentUpdateInputSchema, PaymentSingleOutputSchema } from './schemas.js';
+import { FreshBooksClientWrapper } from '../../client/index.js';
+/**
+ * Tool definition for payment_update
+ */
+export declare const paymentUpdateTool: {
+    name: string;
+    description: string;
+    inputSchema: z.ZodObject<{
+        accountId: z.ZodString;
+        paymentId: z.ZodNumber;
+        amount: z.ZodOptional<z.ZodObject<{
+            amount: z.ZodString;
+            code: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            code: string;
+            amount: string;
+        }, {
+            code: string;
+            amount: string;
+        }>>;
+        date: z.ZodOptional<z.ZodString>;
+        type: z.ZodOptional<z.ZodEnum<["Check", "Credit", "Cash", "Bank Transfer", "Debit", "PayPal", "Credit Card", "Other", "2Checkout", "Stripe", "ACH", "Wire Transfer"]>>;
+        note: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        accountId: string;
+        paymentId: number;
+        date?: string | undefined;
+        type?: "Check" | "Credit" | "Cash" | "Bank Transfer" | "Debit" | "PayPal" | "Credit Card" | "Other" | "2Checkout" | "Stripe" | "ACH" | "Wire Transfer" | undefined;
+        amount?: {
+            code: string;
+            amount: string;
+        } | undefined;
+        note?: string | undefined;
+    }, {
+        accountId: string;
+        paymentId: number;
+        date?: string | undefined;
+        type?: "Check" | "Credit" | "Cash" | "Bank Transfer" | "Debit" | "PayPal" | "Credit Card" | "Other" | "2Checkout" | "Stripe" | "ACH" | "Wire Transfer" | undefined;
+        amount?: {
+            code: string;
+            amount: string;
+        } | undefined;
+        note?: string | 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 PaymentUpdateInputSchema>, client: FreshBooksClientWrapper): Promise<z.infer<typeof PaymentSingleOutputSchema>>;
+};
+//# sourceMappingURL=payment-update.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"payment-update.d.ts","sourceRoot":"","sources":["../../../src/tools/payment/payment-update.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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IA+B5B;;OAEG;mBAEM,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,UACvC,uBAAuB,GAC9B,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;CAiDtD,CAAC"}

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

@@ -0,0 +1,79 @@
+/**
+ * payment_update Tool
+ *
+ * Update an existing payment in FreshBooks.
+ */
+import { PaymentUpdateInputSchema, PaymentSingleOutputSchema } from './schemas.js';
+import { ErrorHandler } from '../../errors/error-handler.js';
+import { logger } from '../../utils/logger.js';
+/**
+ * Tool definition for payment_update
+ */
+export const paymentUpdateTool = {
+    name: 'payment_update',
+    description: `Update an existing payment in FreshBooks.
+
+WHEN TO USE:
+- User needs to correct payment details
+- User says "update payment", "fix payment", "change payment amount"
+- User wants to update payment date, amount, type, or notes
+
+REQUIRED:
+- accountId: FreshBooks account ID (get from auth_status if not specified)
+- paymentId: Payment to update
+
+UPDATABLE FIELDS:
+- amount: Correct the payment amount
+- date: Adjust payment date
+- type: Change payment method
+- note: Update payment memo/reference
+
+EXAMPLE PROMPTS:
+- "Update payment #12345 to $600"
+- "Change payment 67890 date to January 15"
+- "Fix payment 555 - it was actually a check, not cash"
+- "Update payment note to include check number"
+
+RETURNS:
+Updated payment record with modified fields.`,
+    inputSchema: PaymentUpdateInputSchema,
+    outputSchema: PaymentSingleOutputSchema,
+    /**
+     * Execute the tool
+     */
+    async execute(input, client) {
+        const handler = ErrorHandler.wrapHandler('payment_update', async (input, _context) => {
+            const { accountId, paymentId, ...updates } = input;
+            logger.debug('Updating payment', {
+                accountId,
+                paymentId,
+                fields: Object.keys(updates),
+            });
+            // Build update object for API
+            const payment = {};
+            if (updates.amount !== undefined)
+                payment.amount = updates.amount;
+            if (updates.date !== undefined)
+                payment.date = updates.date;
+            if (updates.type !== undefined)
+                payment.type = updates.type;
+            if (updates.note !== undefined)
+                payment.note = updates.note;
+            const result = await client.executeWithRetry('payment_update', async (fbClient) => {
+                const response = await fbClient.payments.update(accountId, String(paymentId), payment);
+                if (!response.ok) {
+                    throw response.error;
+                }
+                return response.data;
+            });
+            // FreshBooks returns: { payment: { ... } }
+            const updatedPayment = result.payment ?? result;
+            logger.info('Payment updated successfully', {
+                paymentId,
+            });
+            return updatedPayment;
+        });
+        return handler(input, { accountId: input.accountId });
+    },
+};
+//# sourceMappingURL=payment-update.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"payment-update.js","sourceRoot":"","sources":["../../../src/tools/payment/payment-update.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;;;;;;;;;;;;;;;;;;;;;;;;6CAwB8B;IAE3C,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,OAAO,EAAE,GAAG,KAAK,CAAC;YAEnD,MAAM,CAAC,KAAK,CAAC,kBAAkB,EAAE;gBAC/B,SAAS;gBACT,SAAS;gBACT,MAAM,EAAE,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC;aAC7B,CAAC,CAAC;YAEH,8BAA8B;YAC9B,MAAM,OAAO,GAA4B,EAAE,CAAC;YAE5C,IAAI,OAAO,CAAC,MAAM,KAAK,SAAS;gBAAE,OAAO,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;YAClE,IAAI,OAAO,CAAC,IAAI,KAAK,SAAS;gBAAE,OAAO,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;YAC5D,IAAI,OAAO,CAAC,IAAI,KAAK,SAAS;gBAAE,OAAO,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;YAC5D,IAAI,OAAO,CAAC,IAAI,KAAK,SAAS;gBAAE,OAAO,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;YAE5D,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,SAAS,EAAE,MAAM,CAAC,SAAS,CAAC,EAAE,OAAc,CAAC,CAAC;gBAE9F,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;aACV,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"}