@goodsamsoftware/freshbooks-mcp 1.0.0

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

@@ -0,0 +1,264 @@
+/**
+ * client_list Tool
+ *
+ * List clients from FreshBooks with filtering and pagination.
+ */
+import { z } from 'zod';
+import { ClientListInputSchema, ClientListOutputSchema } from './schemas.js';
+import { FreshBooksClientWrapper } from '../../client/index.js';
+/**
+ * Tool definition for client_list
+ */
+export declare const clientListTool: {
+    name: string;
+    description: string;
+    inputSchema: z.ZodObject<{
+        accountId: z.ZodString;
+        page: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
+        perPage: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
+        email: z.ZodOptional<z.ZodString>;
+        organization: z.ZodOptional<z.ZodString>;
+        fName: z.ZodOptional<z.ZodString>;
+        lName: z.ZodOptional<z.ZodString>;
+        visState: z.ZodOptional<z.ZodUnion<[z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>]>>;
+    } & {
+        sortBy: z.ZodOptional<z.ZodEnum<["email" | "updated" | "organization" | "fname" | "lname", ...("email" | "updated" | "organization" | "fname" | "lname")[]]>>;
+        sortOrder: z.ZodOptional<z.ZodDefault<z.ZodEnum<["asc", "desc"]>>>;
+    } & {
+        include: z.ZodOptional<z.ZodArray<z.ZodEnum<["outstanding_balance" | "credit_balance", ...("outstanding_balance" | "credit_balance")[]]>, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        accountId: string;
+        email?: string | undefined;
+        page?: number | undefined;
+        perPage?: number | undefined;
+        sortBy?: "email" | "updated" | "organization" | "fname" | "lname" | undefined;
+        sortOrder?: "asc" | "desc" | undefined;
+        include?: ("outstanding_balance" | "credit_balance")[] | undefined;
+        visState?: 0 | 1 | 2 | undefined;
+        organization?: string | undefined;
+        fName?: string | undefined;
+        lName?: string | undefined;
+    }, {
+        accountId: string;
+        email?: string | undefined;
+        page?: number | undefined;
+        perPage?: number | undefined;
+        sortBy?: "email" | "updated" | "organization" | "fname" | "lname" | undefined;
+        sortOrder?: "asc" | "desc" | undefined;
+        include?: ("outstanding_balance" | "credit_balance")[] | undefined;
+        visState?: 0 | 1 | 2 | undefined;
+        organization?: string | undefined;
+        fName?: string | undefined;
+        lName?: string | undefined;
+    }>;
+    outputSchema: z.ZodObject<{
+        clients: z.ZodArray<z.ZodObject<{
+            id: z.ZodNumber;
+            fName: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            lName: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            organization: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            email: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            busPhone: z.ZodOptional<z.ZodString>;
+            homePhone: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            mobPhone: z.ZodOptional<z.ZodString>;
+            fax: z.ZodOptional<z.ZodString>;
+            note: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            pStreet: z.ZodOptional<z.ZodString>;
+            pStreet2: z.ZodOptional<z.ZodString>;
+            pCity: z.ZodOptional<z.ZodString>;
+            pProvince: z.ZodOptional<z.ZodString>;
+            pCode: z.ZodOptional<z.ZodString>;
+            pCountry: z.ZodOptional<z.ZodString>;
+            sStreet: z.ZodOptional<z.ZodString>;
+            sStreet2: z.ZodOptional<z.ZodString>;
+            sCity: z.ZodOptional<z.ZodString>;
+            sProvince: z.ZodOptional<z.ZodString>;
+            sCode: z.ZodOptional<z.ZodString>;
+            sCountry: z.ZodOptional<z.ZodString>;
+            currencyCode: z.ZodOptional<z.ZodString>;
+            language: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            vatNumber: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            vatName: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            visState: z.ZodOptional<z.ZodUnion<[z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>]>>;
+            signupDate: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            updated: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            allowLateFees: z.ZodOptional<z.ZodBoolean>;
+            allowLateNotifications: z.ZodOptional<z.ZodBoolean>;
+            hasRetainer: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+            retainerId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+            id: z.ZodNumber;
+            fName: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            lName: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            organization: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            email: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            busPhone: z.ZodOptional<z.ZodString>;
+            homePhone: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            mobPhone: z.ZodOptional<z.ZodString>;
+            fax: z.ZodOptional<z.ZodString>;
+            note: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            pStreet: z.ZodOptional<z.ZodString>;
+            pStreet2: z.ZodOptional<z.ZodString>;
+            pCity: z.ZodOptional<z.ZodString>;
+            pProvince: z.ZodOptional<z.ZodString>;
+            pCode: z.ZodOptional<z.ZodString>;
+            pCountry: z.ZodOptional<z.ZodString>;
+            sStreet: z.ZodOptional<z.ZodString>;
+            sStreet2: z.ZodOptional<z.ZodString>;
+            sCity: z.ZodOptional<z.ZodString>;
+            sProvince: z.ZodOptional<z.ZodString>;
+            sCode: z.ZodOptional<z.ZodString>;
+            sCountry: z.ZodOptional<z.ZodString>;
+            currencyCode: z.ZodOptional<z.ZodString>;
+            language: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            vatNumber: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            vatName: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            visState: z.ZodOptional<z.ZodUnion<[z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>]>>;
+            signupDate: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            updated: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            allowLateFees: z.ZodOptional<z.ZodBoolean>;
+            allowLateNotifications: z.ZodOptional<z.ZodBoolean>;
+            hasRetainer: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+            retainerId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+            id: z.ZodNumber;
+            fName: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            lName: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            organization: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            email: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            busPhone: z.ZodOptional<z.ZodString>;
+            homePhone: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            mobPhone: z.ZodOptional<z.ZodString>;
+            fax: z.ZodOptional<z.ZodString>;
+            note: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            pStreet: z.ZodOptional<z.ZodString>;
+            pStreet2: z.ZodOptional<z.ZodString>;
+            pCity: z.ZodOptional<z.ZodString>;
+            pProvince: z.ZodOptional<z.ZodString>;
+            pCode: z.ZodOptional<z.ZodString>;
+            pCountry: z.ZodOptional<z.ZodString>;
+            sStreet: z.ZodOptional<z.ZodString>;
+            sStreet2: z.ZodOptional<z.ZodString>;
+            sCity: z.ZodOptional<z.ZodString>;
+            sProvince: z.ZodOptional<z.ZodString>;
+            sCode: z.ZodOptional<z.ZodString>;
+            sCountry: z.ZodOptional<z.ZodString>;
+            currencyCode: z.ZodOptional<z.ZodString>;
+            language: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            vatNumber: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            vatName: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            visState: z.ZodOptional<z.ZodUnion<[z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>]>>;
+            signupDate: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            updated: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            allowLateFees: z.ZodOptional<z.ZodBoolean>;
+            allowLateNotifications: z.ZodOptional<z.ZodBoolean>;
+            hasRetainer: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+            retainerId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        }, z.ZodTypeAny, "passthrough">>, "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;
+        };
+        clients: z.objectOutputType<{
+            id: z.ZodNumber;
+            fName: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            lName: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            organization: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            email: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            busPhone: z.ZodOptional<z.ZodString>;
+            homePhone: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            mobPhone: z.ZodOptional<z.ZodString>;
+            fax: z.ZodOptional<z.ZodString>;
+            note: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            pStreet: z.ZodOptional<z.ZodString>;
+            pStreet2: z.ZodOptional<z.ZodString>;
+            pCity: z.ZodOptional<z.ZodString>;
+            pProvince: z.ZodOptional<z.ZodString>;
+            pCode: z.ZodOptional<z.ZodString>;
+            pCountry: z.ZodOptional<z.ZodString>;
+            sStreet: z.ZodOptional<z.ZodString>;
+            sStreet2: z.ZodOptional<z.ZodString>;
+            sCity: z.ZodOptional<z.ZodString>;
+            sProvince: z.ZodOptional<z.ZodString>;
+            sCode: z.ZodOptional<z.ZodString>;
+            sCountry: z.ZodOptional<z.ZodString>;
+            currencyCode: z.ZodOptional<z.ZodString>;
+            language: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            vatNumber: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            vatName: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            visState: z.ZodOptional<z.ZodUnion<[z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>]>>;
+            signupDate: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            updated: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            allowLateFees: z.ZodOptional<z.ZodBoolean>;
+            allowLateNotifications: z.ZodOptional<z.ZodBoolean>;
+            hasRetainer: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+            retainerId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        }, z.ZodTypeAny, "passthrough">[];
+    }, {
+        pagination: {
+            total: number;
+            page: number;
+            perPage: number;
+            pages: number;
+        };
+        clients: z.objectInputType<{
+            id: z.ZodNumber;
+            fName: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            lName: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            organization: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            email: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            busPhone: z.ZodOptional<z.ZodString>;
+            homePhone: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            mobPhone: z.ZodOptional<z.ZodString>;
+            fax: z.ZodOptional<z.ZodString>;
+            note: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            pStreet: z.ZodOptional<z.ZodString>;
+            pStreet2: z.ZodOptional<z.ZodString>;
+            pCity: z.ZodOptional<z.ZodString>;
+            pProvince: z.ZodOptional<z.ZodString>;
+            pCode: z.ZodOptional<z.ZodString>;
+            pCountry: z.ZodOptional<z.ZodString>;
+            sStreet: z.ZodOptional<z.ZodString>;
+            sStreet2: z.ZodOptional<z.ZodString>;
+            sCity: z.ZodOptional<z.ZodString>;
+            sProvince: z.ZodOptional<z.ZodString>;
+            sCode: z.ZodOptional<z.ZodString>;
+            sCountry: z.ZodOptional<z.ZodString>;
+            currencyCode: z.ZodOptional<z.ZodString>;
+            language: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            vatNumber: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            vatName: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            visState: z.ZodOptional<z.ZodUnion<[z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>]>>;
+            signupDate: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            updated: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            allowLateFees: z.ZodOptional<z.ZodBoolean>;
+            allowLateNotifications: z.ZodOptional<z.ZodBoolean>;
+            hasRetainer: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+            retainerId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        }, z.ZodTypeAny, "passthrough">[];
+    }>;
+    /**
+     * Execute the tool
+     */
+    execute(input: z.infer<typeof ClientListInputSchema>, client: FreshBooksClientWrapper): Promise<z.infer<typeof ClientListOutputSchema>>;
+};
+//# sourceMappingURL=client-list.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"client-list.d.ts","sourceRoot":"","sources":["../../../src/tools/client/client-list.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,qBAAqB,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AAC7E,OAAO,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AAMhE;;GAEG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAsDzB;;OAEG;mBAEM,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,UACpC,uBAAuB,GAC9B,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;CAkFnD,CAAC"}

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

@@ -0,0 +1,131 @@
+/**
+ * client_list Tool
+ *
+ * List clients from FreshBooks with filtering and pagination.
+ */
+import { ClientListInputSchema, ClientListOutputSchema } from './schemas.js';
+import { ErrorHandler } from '../../errors/error-handler.js';
+import { logger } from '../../utils/logger.js';
+import { buildQueryBuilders } from '../base-tool.js';
+/**
+ * Tool definition for client_list
+ */
+export const clientListTool = {
+    name: 'client_list',
+    description: `List clients from FreshBooks with optional filtering and pagination.
+
+WHEN TO USE:
+- User asks to "see clients", "list clients", "show all customers"
+- User wants to find a client by name, email, or organization
+- User needs to select a client for invoicing or project setup
+- Getting client information for time tracking context
+
+REQUIRED:
+- accountId: FreshBooks account ID (get from auth_status if not specified)
+
+OPTIONAL FILTERS:
+- email: Find client by exact email address
+- organization: Search by company name (partial match)
+- fName: Search by first name (partial match)
+- lName: Search by last name (partial match)
+- visState: Filter by status (0=active, 1=deleted, 2=archived)
+
+SORTING:
+- sortBy: Field to sort by (organization, fname, lname, email, updated)
+- sortOrder: Sort direction (asc or desc, default: desc)
+
+INCLUDES:
+- include: Related data to fetch (outstanding_balance, credit_balance)
+  - outstanding_balance: Total unpaid amount across all invoices
+  - credit_balance: Available credit for the client
+
+PAGINATION:
+- page: Page number (default: 1)
+- perPage: Results per page (default: 30, max: 100)
+
+RETURNS:
+Array of clients with:
+- id: Client ID
+- fName, lName: Contact name
+- organization: Company name
+- email: Email address
+- Phone numbers, addresses
+- currencyCode: Billing currency
+- visState: Status
+Plus pagination metadata (page, pages, total)
+
+EXAMPLES:
+- "Show me all active clients"
+- "List clients with 'Acme' in their organization name"
+- "Find the client with email john@example.com"
+- "Show all archived clients sorted by organization"
+- "Get clients with their outstanding balances"`,
+    inputSchema: ClientListInputSchema,
+    outputSchema: ClientListOutputSchema,
+    /**
+     * Execute the tool
+     */
+    async execute(input, client) {
+        const handler = ErrorHandler.wrapHandler('client_list', async (input, _context) => {
+            logger.debug('Listing clients', {
+                accountId: input.accountId,
+                filters: {
+                    email: input.email,
+                    organization: input.organization,
+                    visState: input.visState,
+                },
+            });
+            const result = await client.executeWithRetry('client_list', async (fbClient) => {
+                // Build query builders using the helper
+                const queryBuilders = await buildQueryBuilders({
+                    page: input.page,
+                    perPage: input.perPage,
+                    sortBy: input.sortBy,
+                    sortOrder: input.sortOrder,
+                    include: input.include,
+                    searchFilters: (search) => {
+                        if (input.email) {
+                            search.equals('email', input.email);
+                        }
+                        if (input.organization) {
+                            search.like('organization', input.organization);
+                        }
+                        if (input.fName) {
+                            search.like('fname', input.fName);
+                        }
+                        if (input.lName) {
+                            search.like('lname', input.lName);
+                        }
+                        if (input.visState !== undefined) {
+                            search.equals('vis_state', input.visState);
+                        }
+                    },
+                });
+                // Call FreshBooks API
+                const response = await fbClient.clients.list(input.accountId, queryBuilders);
+                if (!response.ok) {
+                    throw response.error;
+                }
+                const clients = response.data?.clients || [];
+                const pagesData = response.data?.pages;
+                const pagination = {
+                    total: pagesData?.total || 0,
+                    page: pagesData?.page || 1,
+                    perPage: pagesData?.perPage || pagesData?.per_page || pagesData?.size || 30,
+                    pages: pagesData?.pages || 1,
+                };
+                return {
+                    pagination,
+                    clients,
+                };
+            });
+            logger.info('Clients listed successfully', {
+                count: result.clients.length,
+                total: result.pagination.total,
+            });
+            return result;
+        });
+        return handler(input, { accountId: input.accountId });
+    },
+};
+//# sourceMappingURL=client-list.js.map

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

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

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

@@ -0,0 +1,133 @@
+/**
+ * client_single Tool
+ *
+ * Retrieve a single client by ID.
+ */
+import { z } from 'zod';
+import { ClientSingleInputSchema, ClientSingleOutputSchema } from './schemas.js';
+import { FreshBooksClientWrapper } from '../../client/index.js';
+/**
+ * Tool definition for client_single
+ */
+export declare const clientSingleTool: {
+    name: string;
+    description: string;
+    inputSchema: z.ZodObject<{
+        accountId: z.ZodString;
+        clientId: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        accountId: string;
+        clientId: number;
+    }, {
+        accountId: string;
+        clientId: number;
+    }>;
+    outputSchema: z.ZodObject<{
+        id: z.ZodNumber;
+        fName: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        lName: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        organization: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        email: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        busPhone: z.ZodOptional<z.ZodString>;
+        homePhone: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        mobPhone: z.ZodOptional<z.ZodString>;
+        fax: z.ZodOptional<z.ZodString>;
+        note: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        pStreet: z.ZodOptional<z.ZodString>;
+        pStreet2: z.ZodOptional<z.ZodString>;
+        pCity: z.ZodOptional<z.ZodString>;
+        pProvince: z.ZodOptional<z.ZodString>;
+        pCode: z.ZodOptional<z.ZodString>;
+        pCountry: z.ZodOptional<z.ZodString>;
+        sStreet: z.ZodOptional<z.ZodString>;
+        sStreet2: z.ZodOptional<z.ZodString>;
+        sCity: z.ZodOptional<z.ZodString>;
+        sProvince: z.ZodOptional<z.ZodString>;
+        sCode: z.ZodOptional<z.ZodString>;
+        sCountry: z.ZodOptional<z.ZodString>;
+        currencyCode: z.ZodOptional<z.ZodString>;
+        language: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        vatNumber: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        vatName: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        visState: z.ZodOptional<z.ZodUnion<[z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>]>>;
+        signupDate: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        updated: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        allowLateFees: z.ZodOptional<z.ZodBoolean>;
+        allowLateNotifications: z.ZodOptional<z.ZodBoolean>;
+        hasRetainer: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+        retainerId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        id: z.ZodNumber;
+        fName: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        lName: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        organization: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        email: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        busPhone: z.ZodOptional<z.ZodString>;
+        homePhone: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        mobPhone: z.ZodOptional<z.ZodString>;
+        fax: z.ZodOptional<z.ZodString>;
+        note: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        pStreet: z.ZodOptional<z.ZodString>;
+        pStreet2: z.ZodOptional<z.ZodString>;
+        pCity: z.ZodOptional<z.ZodString>;
+        pProvince: z.ZodOptional<z.ZodString>;
+        pCode: z.ZodOptional<z.ZodString>;
+        pCountry: z.ZodOptional<z.ZodString>;
+        sStreet: z.ZodOptional<z.ZodString>;
+        sStreet2: z.ZodOptional<z.ZodString>;
+        sCity: z.ZodOptional<z.ZodString>;
+        sProvince: z.ZodOptional<z.ZodString>;
+        sCode: z.ZodOptional<z.ZodString>;
+        sCountry: z.ZodOptional<z.ZodString>;
+        currencyCode: z.ZodOptional<z.ZodString>;
+        language: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        vatNumber: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        vatName: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        visState: z.ZodOptional<z.ZodUnion<[z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>]>>;
+        signupDate: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        updated: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        allowLateFees: z.ZodOptional<z.ZodBoolean>;
+        allowLateNotifications: z.ZodOptional<z.ZodBoolean>;
+        hasRetainer: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+        retainerId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        id: z.ZodNumber;
+        fName: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        lName: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        organization: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        email: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        busPhone: z.ZodOptional<z.ZodString>;
+        homePhone: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        mobPhone: z.ZodOptional<z.ZodString>;
+        fax: z.ZodOptional<z.ZodString>;
+        note: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        pStreet: z.ZodOptional<z.ZodString>;
+        pStreet2: z.ZodOptional<z.ZodString>;
+        pCity: z.ZodOptional<z.ZodString>;
+        pProvince: z.ZodOptional<z.ZodString>;
+        pCode: z.ZodOptional<z.ZodString>;
+        pCountry: z.ZodOptional<z.ZodString>;
+        sStreet: z.ZodOptional<z.ZodString>;
+        sStreet2: z.ZodOptional<z.ZodString>;
+        sCity: z.ZodOptional<z.ZodString>;
+        sProvince: z.ZodOptional<z.ZodString>;
+        sCode: z.ZodOptional<z.ZodString>;
+        sCountry: z.ZodOptional<z.ZodString>;
+        currencyCode: z.ZodOptional<z.ZodString>;
+        language: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        vatNumber: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        vatName: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        visState: z.ZodOptional<z.ZodUnion<[z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>]>>;
+        signupDate: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        updated: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        allowLateFees: z.ZodOptional<z.ZodBoolean>;
+        allowLateNotifications: z.ZodOptional<z.ZodBoolean>;
+        hasRetainer: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+        retainerId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.ZodTypeAny, "passthrough">>;
+    /**
+     * Execute the tool
+     */
+    execute(input: z.infer<typeof ClientSingleInputSchema>, client: FreshBooksClientWrapper): Promise<z.infer<typeof ClientSingleOutputSchema>>;
+};
+//# sourceMappingURL=client-single.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"client-single.d.ts","sourceRoot":"","sources":["../../../src/tools/client/client-single.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,uBAAuB,EAAE,wBAAwB,EAAE,MAAM,cAAc,CAAC;AACjF,OAAO,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AAKhE;;GAEG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IA+B3B;;OAEG;mBAEM,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,UACtC,uBAAuB,GAC9B,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;CAyCrD,CAAC"}

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

@@ -0,0 +1,67 @@
+/**
+ * client_single Tool
+ *
+ * Retrieve a single client by ID.
+ */
+import { ClientSingleInputSchema, ClientSingleOutputSchema } from './schemas.js';
+import { ErrorHandler } from '../../errors/error-handler.js';
+import { logger } from '../../utils/logger.js';
+/**
+ * Tool definition for client_single
+ */
+export const clientSingleTool = {
+    name: 'client_single',
+    description: `Retrieve a single client's full details from FreshBooks.
+
+WHEN TO USE:
+- User asks for details about a specific client
+- User says "show me client #123", "get client info for ID 456"
+- Need complete client information including addresses and preferences
+- Looking up client details before creating invoice or project
+
+REQUIRED:
+- accountId: FreshBooks account ID (get from auth_status if not specified)
+- clientId: The FreshBooks client ID (numeric)
+
+RETURNS:
+Complete client record including:
+- Contact information (name, email, phones)
+- Primary and secondary addresses
+- Billing preferences and currency settings
+- VAT/tax information
+- Retainer status
+- Last update timestamp
+
+EXAMPLES:
+- "Show me details for client 12345"
+- "Get full information for client ID 789"
+- "What's the address for client 456?"`,
+    inputSchema: ClientSingleInputSchema,
+    outputSchema: ClientSingleOutputSchema,
+    /**
+     * Execute the tool
+     */
+    async execute(input, client) {
+        const handler = ErrorHandler.wrapHandler('client_single', async (input, _context) => {
+            logger.debug('Getting client', {
+                accountId: input.accountId,
+                clientId: input.clientId,
+            });
+            const result = await client.executeWithRetry('client_single', async (fbClient) => {
+                const response = await fbClient.clients.single(input.accountId, String(input.clientId));
+                if (!response.ok) {
+                    throw response.error;
+                }
+                return response.data;
+            });
+            // FreshBooks returns: { client: { ... } }
+            const clientData = result.client ?? result;
+            logger.info('Client retrieved successfully', {
+                clientId: input.clientId,
+            });
+            return clientData;
+        });
+        return handler(input, { accountId: input.accountId });
+    },
+};
+//# sourceMappingURL=client-single.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"client-single.js","sourceRoot":"","sources":["../../../src/tools/client/client-single.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,uBAAuB,EAAE,wBAAwB,EAAE,MAAM,cAAc,CAAC;AAEjF,OAAO,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAE7D,OAAO,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAE/C;;GAEG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,IAAI,EAAE,eAAe;IACrB,WAAW,EAAE;;;;;;;;;;;;;;;;;;;;;;;;uCAwBwB;IAErC,WAAW,EAAE,uBAAuB;IACpC,YAAY,EAAE,wBAAwB;IAEtC;;OAEG;IACH,KAAK,CAAC,OAAO,CACX,KAA8C,EAC9C,MAA+B;QAE/B,MAAM,OAAO,GAAG,YAAY,CAAC,WAAW,CACtC,eAAe,EACf,KAAK,EACH,KAA8C,EAC9C,QAAqB,EACrB,EAAE;YACF,MAAM,CAAC,KAAK,CAAC,gBAAgB,EAAE;gBAC7B,SAAS,EAAE,KAAK,CAAC,SAAS;gBAC1B,QAAQ,EAAE,KAAK,CAAC,QAAQ;aACzB,CAAC,CAAC;YAEH,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,gBAAgB,CAC1C,eAAe,EACf,KAAK,EAAE,QAAQ,EAAE,EAAE;gBACjB,MAAM,QAAQ,GAAG,MAAM,QAAQ,CAAC,OAAO,CAAC,MAAM,CAC5C,KAAK,CAAC,SAAS,EACf,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,CACvB,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,0CAA0C;YAC1C,MAAM,UAAU,GAAI,MAA+B,CAAC,MAAM,IAAI,MAAM,CAAC;YAErE,MAAM,CAAC,IAAI,CAAC,+BAA+B,EAAE;gBAC3C,QAAQ,EAAE,KAAK,CAAC,QAAQ;aACzB,CAAC,CAAC;YAEH,OAAO,UAAsD,CAAC;QAChE,CAAC,CACF,CAAC;QAEF,OAAO,OAAO,CAAC,KAAK,EAAE,EAAE,SAAS,EAAE,KAAK,CAAC,SAAS,EAAE,CAAC,CAAC;IACxD,CAAC;CACF,CAAC"}