@goodsamsoftware/freshbooks-mcp 1.0.0

package/dist/tools/invoice/invoice-share-link.js

@@ -0,0 +1,89 @@
+/**
+ * invoice_share_link Tool
+ *
+ * Generate a shareable link for an invoice.
+ */
+import { InvoiceShareLinkInputSchema, InvoiceShareLinkOutputSchema } from './schemas.js';
+import { ErrorHandler } from '../../errors/error-handler.js';
+import { logger } from '../../utils/logger.js';
+/**
+ * Tool definition for invoice_share_link
+ */
+export const invoiceShareLinkTool = {
+    name: 'invoice_share_link',
+    description: `Generate a shareable link for an invoice in FreshBooks.
+
+WHEN TO USE:
+- User wants to share an invoice with a client
+- User says "share invoice", "get invoice link", "send invoice link"
+- Need a URL to send to clients for viewing/paying
+
+REQUIRED:
+- accountId: FreshBooks account ID (get from auth_status if not specified)
+- invoiceId: The invoice ID to share (numeric)
+
+HOW IT WORKS:
+- Generates a unique, secure URL for the invoice
+- Client can view and pay the invoice at this URL
+- Link remains valid until the invoice is deleted
+
+RETURNS:
+- shareLink: The URL to share with the client
+- invoiceId: The invoice this link is for
+
+EXAMPLES:
+- "Get a share link for invoice 123"
+- "Generate a payment link for invoice 456"
+- "Share invoice 789 with the client"`,
+    inputSchema: InvoiceShareLinkInputSchema,
+    outputSchema: InvoiceShareLinkOutputSchema,
+    /**
+     * Execute the tool
+     */
+    async execute(input, client) {
+        const handler = ErrorHandler.wrapHandler('invoice_share_link', async (input, _context) => {
+            const { accountId, invoiceId } = input;
+            logger.debug('Generating invoice share link', {
+                accountId,
+                invoiceId,
+            });
+            const result = await client.executeWithRetry('invoice_share_link', async (fbClient) => {
+                // Get the invoice to extract the share link
+                const response = await fbClient.invoices.single(accountId, String(invoiceId));
+                if (!response.ok) {
+                    throw response.error;
+                }
+                const invoiceData = response.data.invoice ?? response.data;
+                // Extract share link from invoice data
+                let shareLink = '';
+                if (invoiceData.v3_status?.share_link) {
+                    shareLink = invoiceData.v3_status.share_link;
+                }
+                else if (invoiceData.links?.client_view) {
+                    shareLink = invoiceData.links.client_view;
+                }
+                else if (invoiceData.shareLink) {
+                    shareLink = invoiceData.shareLink;
+                }
+                else if (invoiceData.share_link) {
+                    shareLink = invoiceData.share_link;
+                }
+                else {
+                    // Construct fallback link
+                    const invoiceNum = invoiceData.invoice_number || invoiceData.invoiceNumber || '';
+                    shareLink = `https://my.freshbooks.com/invoice/${invoiceNum}-${invoiceId}`;
+                }
+                return {
+                    shareLink,
+                    invoiceId,
+                };
+            });
+            logger.info('Invoice share link generated successfully', {
+                invoiceId,
+            });
+            return result;
+        });
+        return handler(input, { accountId: input.accountId });
+    },
+};
+//# sourceMappingURL=invoice-share-link.js.map

package/dist/tools/invoice/invoice-share-link.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"invoice-share-link.js","sourceRoot":"","sources":["../../../src/tools/invoice/invoice-share-link.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,2BAA2B,EAAE,4BAA4B,EAAE,MAAM,cAAc,CAAC;AAEzF,OAAO,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAE7D,OAAO,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAE/C;;GAEG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAClC,IAAI,EAAE,oBAAoB;IAC1B,WAAW,EAAE;;;;;;;;;;;;;;;;;;;;;;;sCAuBuB;IAEpC,WAAW,EAAE,2BAA2B;IACxC,YAAY,EAAE,4BAA4B;IAE1C;;OAEG;IACH,KAAK,CAAC,OAAO,CACX,KAAkD,EAClD,MAA+B;QAE/B,MAAM,OAAO,GAAG,YAAY,CAAC,WAAW,CACtC,oBAAoB,EACpB,KAAK,EACH,KAAkD,EAClD,QAAqB,EACrB,EAAE;YACF,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,GAAG,KAAK,CAAC;YAEvC,MAAM,CAAC,KAAK,CAAC,+BAA+B,EAAE;gBAC5C,SAAS;gBACT,SAAS;aACV,CAAC,CAAC;YAEH,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,gBAAgB,CAC1C,oBAAoB,EACpB,KAAK,EAAE,QAAQ,EAAE,EAAE;gBACjB,4CAA4C;gBAC5C,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,MAAM,WAAW,GAAI,QAAQ,CAAC,IAA0B,CAAC,OAAO,IAAI,QAAQ,CAAC,IAAI,CAAC;gBAElF,uCAAuC;gBACvC,IAAI,SAAS,GAAG,EAAE,CAAC;gBAEnB,IAAI,WAAW,CAAC,SAAS,EAAE,UAAU,EAAE,CAAC;oBACtC,SAAS,GAAG,WAAW,CAAC,SAAS,CAAC,UAAU,CAAC;gBAC/C,CAAC;qBAAM,IAAI,WAAW,CAAC,KAAK,EAAE,WAAW,EAAE,CAAC;oBAC1C,SAAS,GAAG,WAAW,CAAC,KAAK,CAAC,WAAW,CAAC;gBAC5C,CAAC;qBAAM,IAAI,WAAW,CAAC,SAAS,EAAE,CAAC;oBACjC,SAAS,GAAG,WAAW,CAAC,SAAS,CAAC;gBACpC,CAAC;qBAAM,IAAI,WAAW,CAAC,UAAU,EAAE,CAAC;oBAClC,SAAS,GAAG,WAAW,CAAC,UAAU,CAAC;gBACrC,CAAC;qBAAM,CAAC;oBACN,0BAA0B;oBAC1B,MAAM,UAAU,GAAG,WAAW,CAAC,cAAc,IAAI,WAAW,CAAC,aAAa,IAAI,EAAE,CAAC;oBACjF,SAAS,GAAG,qCAAqC,UAAU,IAAI,SAAS,EAAE,CAAC;gBAC7E,CAAC;gBAED,OAAO;oBACL,SAAS;oBACT,SAAS;iBACV,CAAC;YACJ,CAAC,CACF,CAAC;YAEF,MAAM,CAAC,IAAI,CAAC,2CAA2C,EAAE;gBACvD,SAAS;aACV,CAAC,CAAC;YAEH,OAAO,MAAM,CAAC;QAChB,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/invoice/invoice-single.d.ts

@@ -0,0 +1,265 @@
+/**
+ * invoice_single Tool
+ *
+ * Retrieve a single invoice by ID.
+ */
+import { z } from 'zod';
+import { InvoiceSingleInputSchema, InvoiceSingleOutputSchema } from './schemas.js';
+import { FreshBooksClientWrapper } from '../../client/index.js';
+/**
+ * Tool definition for invoice_single
+ */
+export declare const invoiceSingleTool: {
+    name: string;
+    description: string;
+    inputSchema: z.ZodObject<{
+        accountId: z.ZodString;
+        invoiceId: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        accountId: string;
+        invoiceId: number;
+    }, {
+        accountId: string;
+        invoiceId: number;
+    }>;
+    outputSchema: z.ZodObject<{
+        id: z.ZodNumber;
+        invoiceNumber: z.ZodString;
+        customerId: z.ZodNumber;
+        createDate: z.ZodString;
+        dueDate: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        amount: z.ZodObject<{
+            amount: z.ZodString;
+            code: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            code: string;
+            amount: string;
+        }, {
+            code: string;
+            amount: string;
+        }>;
+        outstanding: z.ZodObject<{
+            amount: z.ZodString;
+            code: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            code: string;
+            amount: string;
+        }, {
+            code: string;
+            amount: string;
+        }>;
+        paid: z.ZodObject<{
+            amount: z.ZodString;
+            code: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            code: string;
+            amount: string;
+        }, {
+            code: string;
+            amount: string;
+        }>;
+        status: z.ZodEnum<["draft", "sent", "viewed", "partial", "paid", "auto_paid", "retry", "failed", "overdue", "disputed"]>;
+        paymentStatus: z.ZodEnum<["unpaid", "partial", "paid", "auto_paid"]>;
+        currencyCode: z.ZodString;
+        lines: z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            description: z.ZodOptional<z.ZodString>;
+            qty: z.ZodNumber;
+            amount: z.ZodObject<{
+                amount: z.ZodString;
+                code: z.ZodString;
+            }, "strip", z.ZodTypeAny, {
+                code: string;
+                amount: string;
+            }, {
+                code: string;
+                amount: string;
+            }>;
+            taxName1: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            taxAmount1: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+                amount: z.ZodString;
+                code: z.ZodString;
+            }, "strip", z.ZodTypeAny, {
+                code: string;
+                amount: string;
+            }, {
+                code: string;
+                amount: string;
+            }>>>;
+            taxName2: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            taxAmount2: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+                amount: z.ZodString;
+                code: z.ZodString;
+            }, "strip", z.ZodTypeAny, {
+                code: string;
+                amount: string;
+            }, {
+                code: string;
+                amount: string;
+            }>>>;
+        }, "strip", z.ZodTypeAny, {
+            name: string;
+            amount: {
+                code: string;
+                amount: string;
+            };
+            qty: number;
+            description?: string | undefined;
+            taxName1?: string | null | undefined;
+            taxAmount1?: {
+                code: string;
+                amount: string;
+            } | null | undefined;
+            taxName2?: string | null | undefined;
+            taxAmount2?: {
+                code: string;
+                amount: string;
+            } | null | undefined;
+        }, {
+            name: string;
+            amount: {
+                code: string;
+                amount: string;
+            };
+            qty: number;
+            description?: string | undefined;
+            taxName1?: string | null | undefined;
+            taxAmount1?: {
+                code: string;
+                amount: string;
+            } | null | undefined;
+            taxName2?: string | null | undefined;
+            taxAmount2?: {
+                code: string;
+                amount: string;
+            } | null | undefined;
+        }>, "many">;
+        notes: z.ZodOptional<z.ZodString>;
+        terms: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        organization: z.ZodOptional<z.ZodString>;
+        fName: z.ZodOptional<z.ZodString>;
+        lName: z.ZodOptional<z.ZodString>;
+        email: z.ZodOptional<z.ZodString>;
+        address: z.ZodOptional<z.ZodString>;
+        city: z.ZodOptional<z.ZodString>;
+        province: z.ZodOptional<z.ZodString>;
+        code: z.ZodOptional<z.ZodString>;
+        country: z.ZodOptional<z.ZodString>;
+        visState: z.ZodOptional<z.ZodUnion<[z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>]>>;
+        createdAt: z.ZodOptional<z.ZodString>;
+        updated: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, "strip", z.ZodTypeAny, {
+        status: "partial" | "failed" | "draft" | "sent" | "viewed" | "paid" | "auto_paid" | "retry" | "overdue" | "disputed";
+        id: number;
+        amount: {
+            code: string;
+            amount: string;
+        };
+        currencyCode: string;
+        outstanding: {
+            code: string;
+            amount: string;
+        };
+        lines: {
+            name: string;
+            amount: {
+                code: string;
+                amount: string;
+            };
+            qty: number;
+            description?: string | undefined;
+            taxName1?: string | null | undefined;
+            taxAmount1?: {
+                code: string;
+                amount: string;
+            } | null | undefined;
+            taxName2?: string | null | undefined;
+            taxAmount2?: {
+                code: string;
+                amount: string;
+            } | null | undefined;
+        }[];
+        paid: {
+            code: string;
+            amount: string;
+        };
+        invoiceNumber: string;
+        customerId: number;
+        createDate: string;
+        paymentStatus: "partial" | "paid" | "auto_paid" | "unpaid";
+        code?: string | undefined;
+        email?: string | undefined;
+        createdAt?: string | undefined;
+        dueDate?: string | null | undefined;
+        visState?: 0 | 1 | 2 | undefined;
+        updated?: string | null | undefined;
+        organization?: string | undefined;
+        fName?: string | undefined;
+        lName?: string | undefined;
+        notes?: string | undefined;
+        terms?: string | null | undefined;
+        address?: string | undefined;
+        city?: string | undefined;
+        province?: string | undefined;
+        country?: string | undefined;
+    }, {
+        status: "partial" | "failed" | "draft" | "sent" | "viewed" | "paid" | "auto_paid" | "retry" | "overdue" | "disputed";
+        id: number;
+        amount: {
+            code: string;
+            amount: string;
+        };
+        currencyCode: string;
+        outstanding: {
+            code: string;
+            amount: string;
+        };
+        lines: {
+            name: string;
+            amount: {
+                code: string;
+                amount: string;
+            };
+            qty: number;
+            description?: string | undefined;
+            taxName1?: string | null | undefined;
+            taxAmount1?: {
+                code: string;
+                amount: string;
+            } | null | undefined;
+            taxName2?: string | null | undefined;
+            taxAmount2?: {
+                code: string;
+                amount: string;
+            } | null | undefined;
+        }[];
+        paid: {
+            code: string;
+            amount: string;
+        };
+        invoiceNumber: string;
+        customerId: number;
+        createDate: string;
+        paymentStatus: "partial" | "paid" | "auto_paid" | "unpaid";
+        code?: string | undefined;
+        email?: string | undefined;
+        createdAt?: string | undefined;
+        dueDate?: string | null | undefined;
+        visState?: 0 | 1 | 2 | undefined;
+        updated?: string | null | undefined;
+        organization?: string | undefined;
+        fName?: string | undefined;
+        lName?: string | undefined;
+        notes?: string | undefined;
+        terms?: string | null | undefined;
+        address?: string | undefined;
+        city?: string | undefined;
+        province?: string | undefined;
+        country?: string | undefined;
+    }>;
+    /**
+     * Execute the tool
+     */
+    execute(input: z.infer<typeof InvoiceSingleInputSchema>, client: FreshBooksClientWrapper): Promise<z.infer<typeof InvoiceSingleOutputSchema>>;
+};
+//# sourceMappingURL=invoice-single.d.ts.map

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

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

package/dist/tools/invoice/invoice-single.js

@@ -0,0 +1,66 @@
+/**
+ * invoice_single Tool
+ *
+ * Retrieve a single invoice by ID.
+ */
+import { InvoiceSingleInputSchema, InvoiceSingleOutputSchema } from './schemas.js';
+import { ErrorHandler } from '../../errors/error-handler.js';
+import { logger } from '../../utils/logger.js';
+/**
+ * Tool definition for invoice_single
+ */
+export const invoiceSingleTool = {
+    name: 'invoice_single',
+    description: `Retrieve a single invoice's full details from FreshBooks.
+
+WHEN TO USE:
+- User asks for details about a specific invoice
+- User says "show me invoice #123", "get invoice details for ID 456"
+- Need complete invoice information including line items
+- Checking invoice status, amounts, or payment history
+
+REQUIRED:
+- accountId: FreshBooks account ID (get from auth_status if not specified)
+- invoiceId: The FreshBooks invoice ID (numeric)
+
+RETURNS:
+Complete invoice record including:
+- Invoice number, dates, status
+- Customer/client information
+- Line items with quantities and amounts
+- Outstanding and paid amounts
+- Notes and terms
+
+EXAMPLES:
+- "Show me invoice 12345"
+- "Get details for invoice ID 789"
+- "What's the status of invoice 456?"`,
+    inputSchema: InvoiceSingleInputSchema,
+    outputSchema: InvoiceSingleOutputSchema,
+    /**
+     * Execute the tool
+     */
+    async execute(input, client) {
+        const handler = ErrorHandler.wrapHandler('invoice_single', async (input, _context) => {
+            logger.debug('Getting invoice', {
+                accountId: input.accountId,
+                invoiceId: input.invoiceId,
+            });
+            const result = await client.executeWithRetry('invoice_single', async (fbClient) => {
+                const response = await fbClient.invoices.single(input.accountId, String(input.invoiceId));
+                if (!response.ok) {
+                    throw response.error;
+                }
+                return response.data;
+            });
+            // FreshBooks returns: { invoice: { ... } }
+            const invoiceData = result.invoice ?? result;
+            logger.info('Invoice retrieved successfully', {
+                invoiceId: input.invoiceId,
+            });
+            return invoiceData;
+        });
+        return handler(input, { accountId: input.accountId });
+    },
+};
+//# sourceMappingURL=invoice-single.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"invoice-single.js","sourceRoot":"","sources":["../../../src/tools/invoice/invoice-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;;;;;;;;;;;;;;;;;;;;;;;sCAuBuB;IAEpC,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,CAAC,KAAK,CAAC,iBAAiB,EAAE;gBAC9B,SAAS,EAAE,KAAK,CAAC,SAAS;gBAC1B,SAAS,EAAE,KAAK,CAAC,SAAS;aAC3B,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,CAC7C,KAAK,CAAC,SAAS,EACf,MAAM,CAAC,KAAK,CAAC,SAAS,CAAC,CACxB,CAAC;gBAEF,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,WAAW,GAAI,MAAgC,CAAC,OAAO,IAAI,MAAM,CAAC;YAExE,MAAM,CAAC,IAAI,CAAC,gCAAgC,EAAE;gBAC5C,SAAS,EAAE,KAAK,CAAC,SAAS;aAC3B,CAAC,CAAC;YAEH,OAAO,WAAwD,CAAC;QAClE,CAAC,CACF,CAAC;QAEF,OAAO,OAAO,CAAC,KAAK,EAAE,EAAE,SAAS,EAAE,KAAK,CAAC,SAAS,EAAE,CAAC,CAAC;IACxD,CAAC;CACF,CAAC"}