@goodsamsoftware/freshbooks-mcp 1.0.0

package/dist/tools/report/report-profit-loss.js

@@ -0,0 +1,98 @@
+/**
+ * Profit & Loss Report Tool
+ *
+ * Generate a profit and loss (P&L) statement for a date range.
+ */
+import { ProfitLossReportInputSchema, ProfitLossReportOutputSchema } from "./schemas.js";
+import { ErrorHandler } from "../../errors/error-handler.js";
+import { SearchQueryBuilder } from "@freshbooks/api/dist/models/builders/SearchQueryBuilder.js";
+/**
+ * Tool definition for report_profit_loss
+ */
+export const profitLossReportTool = {
+    name: "report_profit_loss",
+    description: `Generate a profit and loss (P&L) statement for a date range.
+
+WHEN TO USE:
+- User wants to see profitability for a period
+- User asks "show P&L", "profit and loss", "income statement"
+- Need to analyze revenue vs expenses
+- Preparing financial statements or tax returns
+
+REQUIRED INFO:
+- Start date (YYYY-MM-DD format)
+- End date (YYYY-MM-DD format)
+- Account ID
+
+WHAT IT RETURNS:
+Complete P&L statement including:
+- Total revenue for the period
+- Total expenses for the period
+- Net income (profit/loss)
+- Detailed breakdown by category (optional)
+
+P&L FORMULA:
+Net Income = Revenue - Expenses
+
+COMMON DATE RANGES:
+- This month: Start of current month to today
+- Last month: First to last day of previous month
+- This quarter: Start of quarter to today
+- This year: January 1 to today
+- Fiscal year: Based on your fiscal year start
+
+EXAMPLE PROMPTS:
+- "Show me P&L for January 2024"
+- "What was our profit last quarter?"
+- "Profit and loss from 2024-01-01 to 2024-03-31"
+- "Generate income statement for 2024"
+
+USE CASES:
+- Financial performance analysis
+- Budget vs actual comparison
+- Tax preparation
+- Investor reporting
+- Business health monitoring
+- Strategic planning
+
+POSITIVE NET INCOME = Profit
+NEGATIVE NET INCOME = Loss
+
+RETURNS:
+Profit and loss statement with revenue, expenses, and net income.`,
+    inputSchema: ProfitLossReportInputSchema,
+    outputSchema: ProfitLossReportOutputSchema,
+    async execute(input, client) {
+        const handler = ErrorHandler.wrapHandler('report_profit_loss', async (input, _context) => {
+            const { accountId, startDate, endDate } = input;
+            // Validate date range
+            if (new Date(startDate) > new Date(endDate)) {
+                throw ErrorHandler.createValidationError('Start date must be before or equal to end date', { tool: 'report_profit_loss', accountId });
+            }
+            // Execute the API call
+            const result = await client.executeWithRetry("report_profit_loss", async (fbClient) => {
+                // Build query with date range
+                const search = new SearchQueryBuilder()
+                    .equals('start_date', startDate)
+                    .equals('end_date', endDate);
+                const response = await fbClient.reports.profitLoss(accountId, [search]);
+                if (!response.ok) {
+                    throw response.error;
+                }
+                return response.data;
+            });
+            // Extract report data
+            const reportData = result;
+            return {
+                startDate,
+                endDate,
+                revenue: reportData.revenue || { amount: "0", code: "USD" },
+                expenses: reportData.expenses || { amount: "0", code: "USD" },
+                netIncome: reportData.netIncome || reportData.net_income || { amount: "0", code: "USD" },
+                lines: reportData.lines || reportData.categories || undefined,
+            };
+        });
+        return handler(input, { accountId: input.accountId });
+    },
+};
+//# sourceMappingURL=report-profit-loss.js.map

package/dist/tools/report/report-profit-loss.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"report-profit-loss.js","sourceRoot":"","sources":["../../../src/tools/report/report-profit-loss.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,2BAA2B,EAAE,4BAA4B,EAAE,MAAM,cAAc,CAAC;AACzF,OAAO,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAG7D,OAAO,EAAE,kBAAkB,EAAE,MAAM,4DAA4D,CAAC;AAEhG;;GAEG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAClC,IAAI,EAAE,oBAAoB;IAC1B,WAAW,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kEAgDmD;IAEhE,WAAW,EAAE,2BAA2B;IACxC,YAAY,EAAE,4BAA4B;IAE1C,KAAK,CAAC,OAAO,CACX,KAAkD,EAClD,MAA+B;QAE/B,MAAM,OAAO,GAAG,YAAY,CAAC,WAAW,CACtC,oBAAoB,EACpB,KAAK,EAAE,KAAkD,EAAE,QAAqB,EAAE,EAAE;YAClF,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,OAAO,EAAE,GAAG,KAAK,CAAC;YAEhD,sBAAsB;YACtB,IAAI,IAAI,IAAI,CAAC,SAAS,CAAC,GAAG,IAAI,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;gBAC5C,MAAM,YAAY,CAAC,qBAAqB,CACtC,gDAAgD,EAChD,EAAE,IAAI,EAAE,oBAAoB,EAAE,SAAS,EAAE,CAC1C,CAAC;YACJ,CAAC;YAED,uBAAuB;YACvB,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,gBAAgB,CAC1C,oBAAoB,EACpB,KAAK,EAAE,QAAQ,EAAE,EAAE;gBACjB,8BAA8B;gBAC9B,MAAM,MAAM,GAAG,IAAI,kBAAkB,EAAE;qBACpC,MAAM,CAAC,YAAY,EAAE,SAAS,CAAC;qBAC/B,MAAM,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;gBAE/B,MAAM,QAAQ,GAAG,MAAM,QAAQ,CAAC,OAAO,CAAC,UAAU,CAAC,SAAS,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC;gBAExE,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,sBAAsB;YACtB,MAAM,UAAU,GAAG,MAAa,CAAC;YAEjC,OAAO;gBACL,SAAS;gBACT,OAAO;gBACP,OAAO,EAAE,UAAU,CAAC,OAAO,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,KAAK,EAAE;gBAC3D,QAAQ,EAAE,UAAU,CAAC,QAAQ,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,KAAK,EAAE;gBAC7D,SAAS,EAAE,UAAU,CAAC,SAAS,IAAI,UAAU,CAAC,UAAU,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,KAAK,EAAE;gBACxF,KAAK,EAAE,UAAU,CAAC,KAAK,IAAI,UAAU,CAAC,UAAU,IAAI,SAAS;aAC9D,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/report/report-tax-summary.d.ts

@@ -0,0 +1,155 @@
+/**
+ * Tax Summary Report Tool
+ *
+ * Generate a tax summary report for a date range.
+ */
+import { z } from "zod";
+import { TaxSummaryReportInputSchema, TaxSummaryReportOutputSchema } from "./schemas.js";
+import { FreshBooksClientWrapper } from "../../client/index.js";
+/**
+ * Tool definition for report_tax_summary
+ */
+export declare const taxSummaryReportTool: {
+    name: string;
+    description: string;
+    inputSchema: z.ZodObject<{
+        startDate: z.ZodString;
+        endDate: z.ZodString;
+    } & {
+        accountId: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        accountId: string;
+        startDate: string;
+        endDate: string;
+    }, {
+        accountId: string;
+        startDate: string;
+        endDate: string;
+    }>;
+    outputSchema: z.ZodObject<{
+        startDate: z.ZodString;
+        endDate: z.ZodString;
+        taxes: z.ZodArray<z.ZodObject<{
+            taxName: z.ZodString;
+            taxRate: z.ZodString;
+            taxableAmount: z.ZodObject<{
+                amount: z.ZodString;
+                code: z.ZodString;
+            }, "strip", z.ZodTypeAny, {
+                code: string;
+                amount: string;
+            }, {
+                code: string;
+                amount: string;
+            }>;
+            taxCollected: z.ZodObject<{
+                amount: z.ZodString;
+                code: z.ZodString;
+            }, "strip", z.ZodTypeAny, {
+                code: string;
+                amount: string;
+            }, {
+                code: string;
+                amount: string;
+            }>;
+            taxPaid: z.ZodOptional<z.ZodObject<{
+                amount: z.ZodString;
+                code: z.ZodString;
+            }, "strip", z.ZodTypeAny, {
+                code: string;
+                amount: string;
+            }, {
+                code: string;
+                amount: string;
+            }>>;
+        }, "strip", z.ZodTypeAny, {
+            taxName: string;
+            taxRate: string;
+            taxableAmount: {
+                code: string;
+                amount: string;
+            };
+            taxCollected: {
+                code: string;
+                amount: string;
+            };
+            taxPaid?: {
+                code: string;
+                amount: string;
+            } | undefined;
+        }, {
+            taxName: string;
+            taxRate: string;
+            taxableAmount: {
+                code: string;
+                amount: string;
+            };
+            taxCollected: {
+                code: string;
+                amount: string;
+            };
+            taxPaid?: {
+                code: string;
+                amount: string;
+            } | undefined;
+        }>, "many">;
+        totalTaxCollected: z.ZodObject<{
+            amount: z.ZodString;
+            code: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            code: string;
+            amount: string;
+        }, {
+            code: string;
+            amount: string;
+        }>;
+    }, "strip", z.ZodTypeAny, {
+        startDate: string;
+        endDate: string;
+        taxes: {
+            taxName: string;
+            taxRate: string;
+            taxableAmount: {
+                code: string;
+                amount: string;
+            };
+            taxCollected: {
+                code: string;
+                amount: string;
+            };
+            taxPaid?: {
+                code: string;
+                amount: string;
+            } | undefined;
+        }[];
+        totalTaxCollected: {
+            code: string;
+            amount: string;
+        };
+    }, {
+        startDate: string;
+        endDate: string;
+        taxes: {
+            taxName: string;
+            taxRate: string;
+            taxableAmount: {
+                code: string;
+                amount: string;
+            };
+            taxCollected: {
+                code: string;
+                amount: string;
+            };
+            taxPaid?: {
+                code: string;
+                amount: string;
+            } | undefined;
+        }[];
+        totalTaxCollected: {
+            code: string;
+            amount: string;
+        };
+    }>;
+    execute(input: z.infer<typeof TaxSummaryReportInputSchema>, client: FreshBooksClientWrapper): Promise<z.infer<typeof TaxSummaryReportOutputSchema>>;
+};
+//# sourceMappingURL=report-tax-summary.d.ts.map

package/dist/tools/report/report-tax-summary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"report-tax-summary.d.ts","sourceRoot":"","sources":["../../../src/tools/report/report-tax-summary.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,2BAA2B,EAAE,4BAA4B,EAAE,MAAM,cAAc,CAAC;AAGzF,OAAO,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AAGhE;;GAEG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;mBA4DtB,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,UAC1C,uBAAuB,GAC9B,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,4BAA4B,CAAC,CAAC;CA+CzD,CAAC"}

package/dist/tools/report/report-tax-summary.js

@@ -0,0 +1,100 @@
+/**
+ * Tax Summary Report Tool
+ *
+ * Generate a tax summary report for a date range.
+ */
+import { TaxSummaryReportInputSchema, TaxSummaryReportOutputSchema } from "./schemas.js";
+import { ErrorHandler } from "../../errors/error-handler.js";
+import { SearchQueryBuilder } from "@freshbooks/api/dist/models/builders/SearchQueryBuilder.js";
+/**
+ * Tool definition for report_tax_summary
+ */
+export const taxSummaryReportTool = {
+    name: "report_tax_summary",
+    description: `Generate a tax summary report for a date range.
+
+WHEN TO USE:
+- User needs to prepare tax returns
+- User asks "show tax summary", "how much tax collected"
+- Need to calculate tax liabilities
+- Preparing for tax filing or audit
+
+REQUIRED INFO:
+- Start date (YYYY-MM-DD format)
+- End date (YYYY-MM-DD format)
+- Account ID
+
+WHAT IT RETURNS:
+Tax summary including:
+- Tax collected by tax type (e.g., Sales Tax, VAT, GST)
+- Tax rates and taxable amounts
+- Total tax collected in the period
+- Tax paid (if applicable)
+
+TAX INFORMATION INCLUDES:
+- Tax name (e.g., "Sales Tax", "VAT", "GST")
+- Tax rate percentage
+- Taxable amount (total sales subject to this tax)
+- Tax collected (amount of tax on invoices)
+- Tax paid on expenses (if tracked)
+
+COMMON DATE RANGES:
+- Tax quarter: Q1 (Jan-Mar), Q2 (Apr-Jun), Q3 (Jul-Sep), Q4 (Oct-Dec)
+- Tax year: Full calendar or fiscal year
+- Monthly: For monthly tax filing
+- Custom: Any reporting period
+
+EXAMPLE PROMPTS:
+- "Show tax summary for Q1 2024"
+- "How much sales tax did I collect last month?"
+- "Tax report from 2024-01-01 to 2024-03-31"
+- "Generate tax summary for 2024"
+
+USE CASES:
+- Sales tax filing
+- VAT/GST returns
+- Tax liability calculation
+- Audit preparation
+- Financial reporting
+- Tax planning
+
+IMPORTANT:
+This report shows taxes on invoices and bills.
+Consult with a tax professional for filing requirements.
+
+RETURNS:
+Tax summary with breakdown by tax type and total tax collected.`,
+    inputSchema: TaxSummaryReportInputSchema,
+    outputSchema: TaxSummaryReportOutputSchema,
+    async execute(input, client) {
+        const handler = ErrorHandler.wrapHandler('report_tax_summary', async (input, _context) => {
+            const { accountId, startDate, endDate } = input;
+            // Validate date range
+            if (new Date(startDate) > new Date(endDate)) {
+                throw ErrorHandler.createValidationError('Start date must be before or equal to end date', { tool: 'report_tax_summary', accountId });
+            }
+            // Execute the API call
+            const result = await client.executeWithRetry("report_tax_summary", async (fbClient) => {
+                // Build query with date range
+                const search = new SearchQueryBuilder()
+                    .equals('start_date', startDate)
+                    .equals('end_date', endDate);
+                const response = await fbClient.reports.taxSummary(accountId, [search]);
+                if (!response.ok) {
+                    throw response.error;
+                }
+                return response.data;
+            });
+            // Extract report data
+            const reportData = result;
+            return {
+                startDate,
+                endDate,
+                taxes: reportData.taxes || reportData.taxSummaries || [],
+                totalTaxCollected: reportData.totalTaxCollected || reportData.total || { amount: "0", code: "USD" },
+            };
+        });
+        return handler(input, { accountId: input.accountId });
+    },
+};
+//# sourceMappingURL=report-tax-summary.js.map

package/dist/tools/report/report-tax-summary.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"report-tax-summary.js","sourceRoot":"","sources":["../../../src/tools/report/report-tax-summary.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,2BAA2B,EAAE,4BAA4B,EAAE,MAAM,cAAc,CAAC;AACzF,OAAO,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAG7D,OAAO,EAAE,kBAAkB,EAAE,MAAM,4DAA4D,CAAC;AAEhG;;GAEG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAClC,IAAI,EAAE,oBAAoB;IAC1B,WAAW,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;gEAoDiD;IAE9D,WAAW,EAAE,2BAA2B;IACxC,YAAY,EAAE,4BAA4B;IAE1C,KAAK,CAAC,OAAO,CACX,KAAkD,EAClD,MAA+B;QAE/B,MAAM,OAAO,GAAG,YAAY,CAAC,WAAW,CACtC,oBAAoB,EACpB,KAAK,EAAE,KAAkD,EAAE,QAAqB,EAAE,EAAE;YAClF,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,OAAO,EAAE,GAAG,KAAK,CAAC;YAEhD,sBAAsB;YACtB,IAAI,IAAI,IAAI,CAAC,SAAS,CAAC,GAAG,IAAI,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;gBAC5C,MAAM,YAAY,CAAC,qBAAqB,CACtC,gDAAgD,EAChD,EAAE,IAAI,EAAE,oBAAoB,EAAE,SAAS,EAAE,CAC1C,CAAC;YACJ,CAAC;YAED,uBAAuB;YACvB,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,gBAAgB,CAC1C,oBAAoB,EACpB,KAAK,EAAE,QAAQ,EAAE,EAAE;gBACjB,8BAA8B;gBAC9B,MAAM,MAAM,GAAG,IAAI,kBAAkB,EAAE;qBACpC,MAAM,CAAC,YAAY,EAAE,SAAS,CAAC;qBAC/B,MAAM,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;gBAE/B,MAAM,QAAQ,GAAG,MAAM,QAAQ,CAAC,OAAO,CAAC,UAAU,CAAC,SAAS,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC;gBAExE,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,sBAAsB;YACtB,MAAM,UAAU,GAAG,MAAa,CAAC;YAEjC,OAAO;gBACL,SAAS;gBACT,OAAO;gBACP,KAAK,EAAE,UAAU,CAAC,KAAK,IAAI,UAAU,CAAC,YAAY,IAAI,EAAE;gBACxD,iBAAiB,EAAE,UAAU,CAAC,iBAAiB,IAAI,UAAU,CAAC,KAAK,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,KAAK,EAAE;aACpG,CAAC;QACJ,CAAC,CACF,CAAC;QAEF,OAAO,OAAO,CAAC,KAAK,EAAE,EAAE,SAAS,EAAE,KAAK,CAAC,SAAS,EAAE,CAAC,CAAC;IACxD,CAAC;CACF,CAAC"}