@goodsamsoftware/freshbooks-mcp 1.0.0

package/dist/tools/timer/timer-current.d.ts

@@ -0,0 +1,170 @@
+/**
+ * Timer Current Tool
+ *
+ * Gets the currently running timer(s) using the /comments/business/.../timers endpoint.
+ * This endpoint is not supported by the SDK, so we use raw HTTP.
+ *
+ * Note: The SDK uses /timetracking/business/... but timer operations require /comments/business/...
+ */
+import { z } from "zod";
+import { TimerCurrentInputSchema, TimerCurrentOutputSchema } from "./schemas.js";
+import { ToolContext } from "../../errors/types.js";
+import { FreshBooksClientWrapper } from "../../client/freshbooks-client.js";
+/**
+ * Tool definition for timer_current
+ */
+export declare const timerCurrentTool: {
+    name: string;
+    description: string;
+    inputSchema: z.ZodObject<{
+        businessId: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        businessId: number;
+    }, {
+        businessId: number;
+    }>;
+    outputSchema: z.ZodObject<{
+        activeTimers: z.ZodArray<z.ZodObject<{
+            id: z.ZodNumber;
+            identityId: z.ZodOptional<z.ZodNumber>;
+            isLogged: z.ZodBoolean;
+            startedAt: z.ZodString;
+            createdAt: z.ZodOptional<z.ZodString>;
+            clientId: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+            projectId: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+            taskId: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+            serviceId: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+            note: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            active: z.ZodBoolean;
+            billable: z.ZodOptional<z.ZodBoolean>;
+            billed: z.ZodOptional<z.ZodBoolean>;
+            internal: z.ZodOptional<z.ZodBoolean>;
+            duration: z.ZodNumber;
+            timer: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+                id: z.ZodNumber;
+                isRunning: z.ZodNullable<z.ZodBoolean>;
+            }, "strip", z.ZodTypeAny, {
+                id: number;
+                isRunning: boolean | null;
+            }, {
+                id: number;
+                isRunning: boolean | null;
+            }>>>;
+            pendingClient: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            pendingProject: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            pendingTask: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            retainerId: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        }, "strip", z.ZodTypeAny, {
+            duration: number;
+            id: number;
+            isLogged: boolean;
+            startedAt: string;
+            active: boolean;
+            billed?: boolean | undefined;
+            taskId?: number | null | undefined;
+            createdAt?: string | undefined;
+            identityId?: number | undefined;
+            clientId?: number | null | undefined;
+            projectId?: number | null | undefined;
+            pendingClient?: string | null | undefined;
+            pendingProject?: string | null | undefined;
+            pendingTask?: string | null | undefined;
+            serviceId?: number | null | undefined;
+            note?: string | null | undefined;
+            billable?: boolean | undefined;
+            internal?: boolean | undefined;
+            retainerId?: number | null | undefined;
+            timer?: {
+                id: number;
+                isRunning: boolean | null;
+            } | null | undefined;
+        }, {
+            duration: number;
+            id: number;
+            isLogged: boolean;
+            startedAt: string;
+            active: boolean;
+            billed?: boolean | undefined;
+            taskId?: number | null | undefined;
+            createdAt?: string | undefined;
+            identityId?: number | undefined;
+            clientId?: number | null | undefined;
+            projectId?: number | null | undefined;
+            pendingClient?: string | null | undefined;
+            pendingProject?: string | null | undefined;
+            pendingTask?: string | null | undefined;
+            serviceId?: number | null | undefined;
+            note?: string | null | undefined;
+            billable?: boolean | undefined;
+            internal?: boolean | undefined;
+            retainerId?: number | null | undefined;
+            timer?: {
+                id: number;
+                isRunning: boolean | null;
+            } | null | undefined;
+        }>, "many">;
+        count: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        count: number;
+        activeTimers: {
+            duration: number;
+            id: number;
+            isLogged: boolean;
+            startedAt: string;
+            active: boolean;
+            billed?: boolean | undefined;
+            taskId?: number | null | undefined;
+            createdAt?: string | undefined;
+            identityId?: number | undefined;
+            clientId?: number | null | undefined;
+            projectId?: number | null | undefined;
+            pendingClient?: string | null | undefined;
+            pendingProject?: string | null | undefined;
+            pendingTask?: string | null | undefined;
+            serviceId?: number | null | undefined;
+            note?: string | null | undefined;
+            billable?: boolean | undefined;
+            internal?: boolean | undefined;
+            retainerId?: number | null | undefined;
+            timer?: {
+                id: number;
+                isRunning: boolean | null;
+            } | null | undefined;
+        }[];
+    }, {
+        count: number;
+        activeTimers: {
+            duration: number;
+            id: number;
+            isLogged: boolean;
+            startedAt: string;
+            active: boolean;
+            billed?: boolean | undefined;
+            taskId?: number | null | undefined;
+            createdAt?: string | undefined;
+            identityId?: number | undefined;
+            clientId?: number | null | undefined;
+            projectId?: number | null | undefined;
+            pendingClient?: string | null | undefined;
+            pendingProject?: string | null | undefined;
+            pendingTask?: string | null | undefined;
+            serviceId?: number | null | undefined;
+            note?: string | null | undefined;
+            billable?: boolean | undefined;
+            internal?: boolean | undefined;
+            retainerId?: number | null | undefined;
+            timer?: {
+                id: number;
+                isRunning: boolean | null;
+            } | null | undefined;
+        }[];
+    }>;
+    execute(input: z.infer<typeof TimerCurrentInputSchema>, client: FreshBooksClientWrapper): Promise<z.infer<typeof TimerCurrentOutputSchema>>;
+};
+/**
+ * Wrapped handler for backward compatibility with tests
+ */
+export declare function timerCurrentHandler(input: z.infer<typeof TimerCurrentInputSchema>, context: ToolContext & {
+    client: FreshBooksClientWrapper;
+}): Promise<z.infer<typeof TimerCurrentOutputSchema>>;
+//# sourceMappingURL=timer-current.d.ts.map

package/dist/tools/timer/timer-current.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timer-current.d.ts","sourceRoot":"","sources":["../../../src/tools/timer/timer-current.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,uBAAuB,EAAE,wBAAwB,EAAE,MAAM,cAAc,CAAC;AAEjF,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACpD,OAAO,EAAE,uBAAuB,EAAE,MAAM,mCAAmC,CAAC;AA6B5E;;GAEG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;mBA8DlB,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,UACtC,uBAAuB,GAC9B,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;CAqErD,CAAC;AAEF;;GAEG;AACH,wBAAsB,mBAAmB,CACvC,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,EAC9C,OAAO,EAAE,WAAW,GAAG;IAAE,MAAM,EAAE,uBAAuB,CAAA;CAAE,GACzD,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC,CAEnD"}

package/dist/tools/timer/timer-current.js

@@ -0,0 +1,134 @@
+/**
+ * Timer Current Tool
+ *
+ * Gets the currently running timer(s) using the /comments/business/.../timers endpoint.
+ * This endpoint is not supported by the SDK, so we use raw HTTP.
+ *
+ * Note: The SDK uses /timetracking/business/... but timer operations require /comments/business/...
+ */
+import { TimerCurrentInputSchema, TimerCurrentOutputSchema } from "./schemas.js";
+import { ErrorHandler } from "../../errors/error-handler.js";
+/**
+ * Tool definition for timer_current
+ */
+export const timerCurrentTool = {
+    name: "timer_current",
+    description: `Get the currently running timer(s) in FreshBooks.
+
+WHEN TO USE:
+- User asks "what timer is running?", "show my current timer", "am I tracking time?"
+- Need to find timer ID before stopping it
+- Want to check if any timer is active before starting a new one
+- Need to see timer details (duration so far, project, notes)
+
+HOW IT WORKS:
+Searches for time entries with:
+- active=true (timer is currently running)
+- Returns all matching entries (typically 0 or 1)
+
+TYPICAL RESULTS:
+- 0 timers: No timer is currently running
+- 1 timer: The active timer with details
+- Multiple timers: Rare, but possible in some FreshBooks configurations
+
+REQUIRED:
+- businessId: FreshBooks business ID (get from user_me -> businessMemberships[].business.id)
+
+NO ACTIVE TIMER:
+If no timer is running, returns:
+- activeTimers: [] (empty array)
+- count: 0
+
+ACTIVE TIMER DETAILS:
+Each active timer includes:
+- id: Time entry ID (use this to stop or discard)
+- startedAt: When timer started (ISO 8601 timestamp)
+- duration: Current duration in seconds (calculated from start time)
+- projectId: Associated project (if any)
+- clientId: Associated client (if any)
+- note: Work description (if any)
+- billable: Whether time is billable
+- timer: Nested timer object with isRunning=true
+
+CALCULATING ELAPSED TIME:
+The duration field shows elapsed seconds, but it may not be real-time.
+To calculate current elapsed time:
+- Parse startedAt timestamp
+- Calculate difference from now
+- Result is current elapsed time
+
+EXAMPLE USAGE:
+- "Show my current timer"
+- "What am I tracking time for?"
+- "How long has my timer been running?"
+- "Is there a timer running?"
+
+NEXT STEPS:
+If timer is found, you can:
+- Stop it: Use timer_stop with the returned id
+- Discard it: Use timer_discard with the returned id
+- Continue running: Do nothing, timer keeps tracking`,
+    inputSchema: TimerCurrentInputSchema,
+    outputSchema: TimerCurrentOutputSchema,
+    async execute(input, client) {
+        const handler = ErrorHandler.wrapHandler('timer_current', async (input, _context) => {
+            const { businessId } = input;
+            // Use raw HTTP to access /comments/business/.../timers endpoint
+            // The SDK doesn't support this endpoint - it only has /timetracking/business/...
+            const result = await client.executeRawWithRetry('GET', `/comments/business/${businessId}/timers`, undefined, 'timer_current');
+            if (!result.ok || !result.data) {
+                throw result.error || new Error('Failed to fetch timers');
+            }
+            const timers = result.data.timers || [];
+            // Transform timers to the expected output format
+            // Each timer contains time_entries, and we want to expose the active ones
+            const activeTimers = timers.map(timer => {
+                // Get the most recent time entry for this timer
+                const timeEntries = timer.time_entries || [];
+                const activeEntry = timeEntries.find(te => te.duration === null) || timeEntries[0];
+                return {
+                    id: activeEntry?.id || timer.id,
+                    timerId: timer.id,
+                    isRunning: timer.is_running,
+                    identityId: undefined,
+                    isLogged: activeEntry?.is_logged ?? false,
+                    startedAt: activeEntry?.started_at || '',
+                    createdAt: activeEntry?.created_at,
+                    clientId: activeEntry?.client_id,
+                    projectId: activeEntry?.project_id,
+                    taskId: activeEntry?.task_id,
+                    serviceId: activeEntry?.service_id,
+                    note: activeEntry?.note,
+                    active: activeEntry?.active ?? timer.is_running,
+                    billable: activeEntry?.billable ?? false,
+                    billed: activeEntry?.billed,
+                    internal: activeEntry?.internal,
+                    duration: activeEntry?.duration ?? 0,
+                    timer: {
+                        id: timer.id,
+                        isRunning: timer.is_running,
+                    },
+                    // Include all time entries for duration calculation
+                    timeEntries: timeEntries.map(te => ({
+                        id: te.id,
+                        duration: te.duration,
+                        startedAt: te.started_at,
+                        isLogged: te.is_logged,
+                    })),
+                };
+            });
+            return {
+                activeTimers,
+                count: timers.length,
+            };
+        });
+        return handler(input, { businessId: input.businessId });
+    },
+};
+/**
+ * Wrapped handler for backward compatibility with tests
+ */
+export async function timerCurrentHandler(input, context) {
+    return timerCurrentTool.execute(input, context.client);
+}
+//# sourceMappingURL=timer-current.js.map

package/dist/tools/timer/timer-current.js.map

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

package/dist/tools/timer/timer-discard.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Timer Discard Tool
+ *
+ * Discards a running timer without logging the time using DELETE /comments/business/.../timers.
+ * This endpoint is not supported by the SDK, so we use raw HTTP.
+ *
+ * Note: The SDK uses /timetracking/business/... but timer operations require /comments/business/...
+ */
+import { z } from "zod";
+import { TimerDiscardInputSchema, TimerDiscardOutputSchema } from "./schemas.js";
+import { ToolContext } from "../../errors/types.js";
+import { FreshBooksClientWrapper } from "../../client/freshbooks-client.js";
+/**
+ * Tool definition for timer_discard
+ */
+export declare const timerDiscardTool: {
+    name: string;
+    description: string;
+    inputSchema: z.ZodObject<{
+        businessId: z.ZodNumber;
+    } & {
+        timerId: z.ZodOptional<z.ZodNumber>;
+        timeEntryId: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        businessId: number;
+        timeEntryId?: number | undefined;
+        timerId?: number | undefined;
+    }, {
+        businessId: number;
+        timeEntryId?: number | undefined;
+        timerId?: number | undefined;
+    }>;
+    outputSchema: z.ZodObject<{
+        success: z.ZodBoolean;
+        timeEntryId: z.ZodNumber;
+        message: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        message: string;
+        success: boolean;
+        timeEntryId: number;
+    }, {
+        message: string;
+        success: boolean;
+        timeEntryId: number;
+    }>;
+    execute(input: z.infer<typeof TimerDiscardInputSchema>, client: FreshBooksClientWrapper): Promise<z.infer<typeof TimerDiscardOutputSchema>>;
+};
+/**
+ * Wrapped handler for backward compatibility with tests
+ */
+export declare function timerDiscardHandler(input: z.infer<typeof TimerDiscardInputSchema>, context: ToolContext & {
+    client: FreshBooksClientWrapper;
+}): Promise<z.infer<typeof TimerDiscardOutputSchema>>;
+//# sourceMappingURL=timer-discard.d.ts.map

package/dist/tools/timer/timer-discard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timer-discard.d.ts","sourceRoot":"","sources":["../../../src/tools/timer/timer-discard.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,uBAAuB,EAAE,wBAAwB,EAAE,MAAM,cAAc,CAAC;AAEjF,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACpD,OAAO,EAAE,uBAAuB,EAAE,MAAM,mCAAmC,CAAC;AAe5E;;GAEG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;mBAiDlB,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,UACtC,uBAAuB,GAC9B,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;CA0ErD,CAAC;AAEF;;GAEG;AACH,wBAAsB,mBAAmB,CACvC,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,EAC9C,OAAO,EAAE,WAAW,GAAG;IAAE,MAAM,EAAE,uBAAuB,CAAA;CAAE,GACzD,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC,CAEnD"}

package/dist/tools/timer/timer-discard.js

@@ -0,0 +1,115 @@
+/**
+ * Timer Discard Tool
+ *
+ * Discards a running timer without logging the time using DELETE /comments/business/.../timers.
+ * This endpoint is not supported by the SDK, so we use raw HTTP.
+ *
+ * Note: The SDK uses /timetracking/business/... but timer operations require /comments/business/...
+ */
+import { TimerDiscardInputSchema, TimerDiscardOutputSchema } from "./schemas.js";
+import { ErrorHandler } from "../../errors/error-handler.js";
+/**
+ * Tool definition for timer_discard
+ */
+export const timerDiscardTool = {
+    name: "timer_discard",
+    description: `Discard a running timer without logging the time in FreshBooks.
+
+WHEN TO USE:
+- User says "discard timer", "delete timer", "cancel tracking"
+- Timer was started by mistake
+- Work was not actually performed
+- Want to abandon tracked time without saving
+
+IMPORTANT DIFFERENCE: Discard vs Stop
+- timer_stop: Logs the time, saves the time entry with calculated duration
+- timer_discard: DELETES the timer completely, no record is kept
+
+USE WITH CAUTION:
+- This permanently deletes the timer and all its time entries
+- The tracked time CANNOT be recovered after discarding
+- Use timer_stop if you want to keep and log the time entry
+
+HOW IT WORKS:
+Deletes the timer completely:
+- Timer and all time entries are removed from FreshBooks
+- No duration is logged
+- No record remains
+
+REQUIRED:
+- businessId: FreshBooks business ID (get from user_me -> businessMemberships[].business.id)
+
+OPTIONAL:
+- timerId: ID of the timer to discard (from timer_current). If not provided, discards the current timer.
+
+WHAT IF NO TIMER EXISTS:
+- Returns error if no timer found
+
+EXAMPLE USAGE:
+- "Discard my current timer" (auto-detects current timer)
+- "Delete timer - I didn't actually work on it"
+- "Cancel time tracking"
+
+RETURNS:
+Confirmation object with:
+- success: true if deletion succeeded
+- timeEntryId: The first time entry ID that was deleted
+- message: Confirmation message`,
+    inputSchema: TimerDiscardInputSchema,
+    outputSchema: TimerDiscardOutputSchema,
+    async execute(input, client) {
+        const handler = ErrorHandler.wrapHandler('timer_discard', async (input, _context) => {
+            const { businessId, timerId, timeEntryId } = input;
+            // First, get current timers to find the one to discard
+            const timersResult = await client.executeRawWithRetry('GET', `/comments/business/${businessId}/timers`, undefined, 'timer_discard_get_timers');
+            if (!timersResult.ok || !timersResult.data) {
+                throw timersResult.error || new Error('Failed to fetch timers');
+            }
+            const timers = timersResult.data.timers || [];
+            if (timers.length === 0) {
+                throw new Error('No timer found to discard');
+            }
+            // Find the timer to discard
+            let targetTimer = timers[0]; // Default to first timer
+            if (timerId) {
+                const found = timers.find(t => t.id === timerId);
+                if (!found) {
+                    throw new Error(`Timer with ID ${timerId} not found`);
+                }
+                targetTimer = found;
+            }
+            else if (timeEntryId) {
+                // Legacy: find timer containing this time entry
+                const found = timers.find(t => t.time_entries?.some(te => te.id === timeEntryId));
+                if (found) {
+                    targetTimer = found;
+                }
+            }
+            if (!targetTimer) {
+                throw new Error('No timer found to discard');
+            }
+            const targetTimerId = targetTimer.id;
+            const firstTimeEntryId = targetTimer.time_entries?.[0]?.id ?? targetTimerId;
+            // DELETE /timers/{id} to discard
+            const result = await client.executeRawWithRetry('DELETE', `/comments/business/${businessId}/timers/${targetTimerId}`, undefined, 'timer_discard');
+            // Successful delete returns 204 No Content
+            if (!result.ok && result.status !== 204) {
+                throw result.error || new Error('Failed to discard timer');
+            }
+            // Return success confirmation
+            return {
+                success: true,
+                timeEntryId: firstTimeEntryId,
+                message: `Timer ${targetTimerId} has been discarded successfully. The time entry was deleted and no time was logged.`,
+            };
+        });
+        return handler(input, { businessId: input.businessId });
+    },
+};
+/**
+ * Wrapped handler for backward compatibility with tests
+ */
+export async function timerDiscardHandler(input, context) {
+    return timerDiscardTool.execute(input, context.client);
+}
+//# sourceMappingURL=timer-discard.js.map

package/dist/tools/timer/timer-discard.js.map

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

package/dist/tools/timer/timer-start.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Timer Start Tool
+ *
+ * Starts a new timer using the /comments/business/.../time_entries endpoint.
+ * This endpoint is not supported by the SDK, so we use raw HTTP.
+ *
+ * Note: The SDK uses /timetracking/business/... but timer operations require /comments/business/...
+ */
+import { z } from "zod";
+import { TimerStartInputSchema, TimerStartOutputSchema } from "./schemas.js";
+import { ToolContext } from "../../errors/types.js";
+import { FreshBooksClientWrapper } from "../../client/freshbooks-client.js";
+/**
+ * Tool definition for timer_start
+ */
+export declare const timerStartTool: {
+    name: string;
+    description: string;
+    inputSchema: z.ZodObject<{
+        businessId: z.ZodNumber;
+    } & {
+        projectId: z.ZodOptional<z.ZodNumber>;
+        clientId: z.ZodOptional<z.ZodNumber>;
+        serviceId: z.ZodOptional<z.ZodNumber>;
+        taskId: z.ZodOptional<z.ZodNumber>;
+        note: z.ZodOptional<z.ZodString>;
+        billable: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+        internal: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    }, "strip", z.ZodTypeAny, {
+        businessId: number;
+        billable: boolean;
+        internal: boolean;
+        taskId?: number | undefined;
+        clientId?: number | undefined;
+        projectId?: number | undefined;
+        serviceId?: number | undefined;
+        note?: string | undefined;
+    }, {
+        businessId: number;
+        taskId?: number | undefined;
+        clientId?: number | undefined;
+        projectId?: number | undefined;
+        serviceId?: number | undefined;
+        note?: string | undefined;
+        billable?: boolean | undefined;
+        internal?: boolean | undefined;
+    }>;
+    outputSchema: z.ZodObject<{
+        id: z.ZodNumber;
+        identityId: z.ZodOptional<z.ZodNumber>;
+        isLogged: z.ZodBoolean;
+        startedAt: z.ZodString;
+        createdAt: z.ZodOptional<z.ZodString>;
+        clientId: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        projectId: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        taskId: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        serviceId: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        note: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        active: z.ZodBoolean;
+        billable: z.ZodOptional<z.ZodBoolean>;
+        billed: z.ZodOptional<z.ZodBoolean>;
+        internal: z.ZodOptional<z.ZodBoolean>;
+        duration: z.ZodNumber;
+        timer: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+            id: z.ZodNumber;
+            isRunning: z.ZodNullable<z.ZodBoolean>;
+        }, "strip", z.ZodTypeAny, {
+            id: number;
+            isRunning: boolean | null;
+        }, {
+            id: number;
+            isRunning: boolean | null;
+        }>>>;
+        pendingClient: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        pendingProject: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        pendingTask: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        retainerId: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    }, "strip", z.ZodTypeAny, {
+        duration: number;
+        id: number;
+        isLogged: boolean;
+        startedAt: string;
+        active: boolean;
+        billed?: boolean | undefined;
+        taskId?: number | null | undefined;
+        createdAt?: string | undefined;
+        identityId?: number | undefined;
+        clientId?: number | null | undefined;
+        projectId?: number | null | undefined;
+        pendingClient?: string | null | undefined;
+        pendingProject?: string | null | undefined;
+        pendingTask?: string | null | undefined;
+        serviceId?: number | null | undefined;
+        note?: string | null | undefined;
+        billable?: boolean | undefined;
+        internal?: boolean | undefined;
+        retainerId?: number | null | undefined;
+        timer?: {
+            id: number;
+            isRunning: boolean | null;
+        } | null | undefined;
+    }, {
+        duration: number;
+        id: number;
+        isLogged: boolean;
+        startedAt: string;
+        active: boolean;
+        billed?: boolean | undefined;
+        taskId?: number | null | undefined;
+        createdAt?: string | undefined;
+        identityId?: number | undefined;
+        clientId?: number | null | undefined;
+        projectId?: number | null | undefined;
+        pendingClient?: string | null | undefined;
+        pendingProject?: string | null | undefined;
+        pendingTask?: string | null | undefined;
+        serviceId?: number | null | undefined;
+        note?: string | null | undefined;
+        billable?: boolean | undefined;
+        internal?: boolean | undefined;
+        retainerId?: number | null | undefined;
+        timer?: {
+            id: number;
+            isRunning: boolean | null;
+        } | null | undefined;
+    }>;
+    execute(input: z.infer<typeof TimerStartInputSchema>, client: FreshBooksClientWrapper): Promise<z.infer<typeof TimerStartOutputSchema>>;
+};
+/**
+ * Wrapped handler for backward compatibility with tests
+ */
+export declare function timerStartHandler(input: z.infer<typeof TimerStartInputSchema>, context: ToolContext & {
+    client: FreshBooksClientWrapper;
+}): Promise<z.infer<typeof TimerStartOutputSchema>>;
+//# sourceMappingURL=timer-start.d.ts.map

package/dist/tools/timer/timer-start.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timer-start.d.ts","sourceRoot":"","sources":["../../../src/tools/timer/timer-start.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,qBAAqB,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AAE7E,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACpD,OAAO,EAAE,uBAAuB,EAAE,MAAM,mCAAmC,CAAC;AA0B5E;;GAEG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;mBAmDhB,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,UACpC,uBAAuB,GAC9B,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;CA0EnD,CAAC;AAEF;;GAEG;AACH,wBAAsB,iBAAiB,CACrC,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,EAC5C,OAAO,EAAE,WAAW,GAAG;IAAE,MAAM,EAAE,uBAAuB,CAAA;CAAE,GACzD,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC,CAEjD"}