@goodsamsoftware/freshbooks-mcp 1.0.0

package/dist/errors/response-formatter.js

@@ -0,0 +1,232 @@
+/**
+ * Response Formatter
+ *
+ * Formats errors for different output contexts:
+ * - JSON-RPC response format (for MCP protocol)
+ * - Claude-friendly text format (for display)
+ */
+/**
+ * Format MCPError for JSON-RPC 2.0 error response
+ *
+ * Creates a properly formatted JSON-RPC error response object
+ * that can be sent over the MCP protocol.
+ *
+ * @param error - The normalized MCP error
+ * @param requestId - Optional request ID (null for notifications)
+ * @returns JSON-RPC error response object
+ *
+ * @example
+ * ```typescript
+ * const response = formatErrorResponse(mcpError, "req-123");
+ * // Returns:
+ * // {
+ * //   jsonrpc: "2.0",
+ * //   id: "req-123",
+ * //   error: {
+ * //     code: -32005,
+ * //     message: "Resource not found",
+ * //     data: { ... }
+ * //   }
+ * // }
+ * ```
+ */
+export function formatErrorResponse(error, requestId) {
+    return {
+        jsonrpc: "2.0",
+        id: requestId ?? null,
+        error: {
+            code: error.code,
+            message: error.message,
+            data: error.data,
+        },
+    };
+}
+/**
+ * Format error for Claude-friendly display
+ *
+ * Creates a markdown-formatted, human-readable error message
+ * that Claude can present to the user with actionable guidance.
+ *
+ * @param error - The normalized MCP error
+ * @returns Formatted error message with suggestions
+ *
+ * @example
+ * ```typescript
+ * const display = formatErrorForClaude(mcpError);
+ * // Returns:
+ * // **Error:** Resource not found
+ * //
+ * // **Suggestion:** Verify the ID is correct...
+ * //
+ * // *This error cannot be recovered by retrying.*
+ * ```
+ */
+export function formatErrorForClaude(error) {
+    const parts = [`**Error:** ${error.message}`];
+    // Add suggestion if available
+    if (error.data.suggestion) {
+        parts.push(`**Suggestion:** ${error.data.suggestion}`);
+    }
+    // Add field information for validation errors
+    if (error.data.freshbooksError?.field) {
+        parts.push(`**Field:** ${error.data.freshbooksError.field}`);
+    }
+    // Add validation error details
+    if (error.data.validationErrors && error.data.validationErrors.length > 0) {
+        const validationDetails = error.data.validationErrors
+            .map((ve) => `- ${ve.path}: ${ve.message}`)
+            .join("\n");
+        parts.push(`**Validation Errors:**\n${validationDetails}`);
+    }
+    // Add retry information for rate limiting
+    if (error.data.retryAfter) {
+        parts.push(`**Retry After:** ${error.data.retryAfter} seconds`);
+    }
+    // Add auth URL for authentication errors
+    if (error.data.authUrl) {
+        parts.push(`**Authorization URL:** ${error.data.authUrl}`);
+    }
+    // Add recovery guidance
+    if (!error.data.recoverable) {
+        parts.push("*This error cannot be recovered by retrying.*");
+    }
+    else {
+        parts.push("*This error may be resolved by retrying the operation.*");
+    }
+    // Add context information for debugging (if available)
+    if (error.data.context?.tool) {
+        parts.push(`\n*Tool:* \`${error.data.context.tool}\``);
+    }
+    if (error.data.context?.requestId) {
+        parts.push(`*Request ID:* \`${error.data.context.requestId}\``);
+    }
+    return parts.join("\n\n");
+}
+/**
+ * Format error for logging
+ *
+ * Creates a structured log entry suitable for stderr logging.
+ * Omits sensitive information like tokens or PII.
+ *
+ * @param error - The normalized MCP error
+ * @returns Structured log object
+ *
+ * @example
+ * ```typescript
+ * const logEntry = formatErrorForLogging(mcpError);
+ * console.error(JSON.stringify(logEntry));
+ * ```
+ */
+export function formatErrorForLogging(error) {
+    return {
+        level: "error",
+        code: error.code,
+        message: error.message,
+        tool: error.data.context?.tool,
+        requestId: error.data.context?.requestId,
+        accountId: error.data.context?.accountId
+            ? maskAccountId(error.data.context.accountId)
+            : undefined,
+        recoverable: error.data.recoverable,
+        freshbooksCode: error.data.freshbooksError?.code,
+        freshbooksErrno: error.data.freshbooksError?.errno,
+        field: error.data.freshbooksError?.field,
+        timestamp: new Date().toISOString(),
+    };
+}
+/**
+ * Format error details for debugging
+ *
+ * Creates a comprehensive error dump including all details
+ * for debugging purposes. Should only be used in development.
+ *
+ * @param error - The normalized MCP error
+ * @returns Detailed error information
+ */
+export function formatErrorForDebug(error) {
+    return {
+        mcpError: {
+            code: error.code,
+            message: error.message,
+            name: error.name,
+            stack: error.stack,
+        },
+        data: error.data,
+        timestamp: new Date().toISOString(),
+    };
+}
+/**
+ * Get error summary
+ *
+ * Returns a brief one-line summary of the error.
+ *
+ * @param error - The normalized MCP error
+ * @returns Brief error summary
+ */
+export function getErrorSummary(error) {
+    const parts = [error.message];
+    if (error.data.freshbooksError?.field) {
+        parts.push(`(field: ${error.data.freshbooksError.field})`);
+    }
+    if (error.data.context?.tool) {
+        parts.push(`[${error.data.context.tool}]`);
+    }
+    return parts.join(" ");
+}
+/**
+ * Check if error is retryable
+ *
+ * Determines if the error can be resolved by retrying.
+ *
+ * @param error - The normalized MCP error
+ * @returns True if error is retryable
+ */
+export function isRetryable(error) {
+    return error.data.recoverable;
+}
+/**
+ * Get suggested retry delay
+ *
+ * Returns the suggested delay before retrying (in milliseconds).
+ *
+ * @param error - The normalized MCP error
+ * @returns Delay in milliseconds, or undefined if not retryable
+ */
+export function getRetryDelay(error) {
+    if (!error.data.recoverable) {
+        return undefined;
+    }
+    // If explicit retry-after is provided (in seconds), convert to ms
+    if (error.data.retryAfter) {
+        return error.data.retryAfter * 1000;
+    }
+    // Default retry delays based on error type
+    switch (error.code) {
+        case -32004: // RATE_LIMITED
+            return 60000; // 60 seconds
+        case -32008: // SERVICE_UNAVAILABLE
+            return 30000; // 30 seconds
+        case -32603: // INTERNAL_ERROR
+            return 5000; // 5 seconds
+        default:
+            return 1000; // 1 second
+    }
+}
+/**
+ * Mask account ID for logging
+ *
+ * Masks the account ID to prevent logging full account identifiers.
+ * Shows first 3 and last 3 characters only.
+ *
+ * @param accountId - Account ID to mask
+ * @returns Masked account ID
+ */
+function maskAccountId(accountId) {
+    if (accountId.length <= 6) {
+        return "***";
+    }
+    const start = accountId.substring(0, 3);
+    const end = accountId.substring(accountId.length - 3);
+    return `${start}...${end}`;
+}
+//# sourceMappingURL=response-formatter.js.map

package/dist/errors/response-formatter.js.map

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

package/dist/errors/types.d.ts

@@ -0,0 +1,194 @@
+/**
+ * Error Type Definitions
+ *
+ * Comprehensive type definitions for the dual-format error system.
+ * All errors are normalized to MCP format while preserving original
+ * FreshBooks error details for debugging.
+ */
+/**
+ * MCP Error Codes (JSON-RPC 2.0)
+ *
+ * Standard JSON-RPC error codes (-32768 to -32000) plus
+ * custom application errors (-32000 to -32099)
+ */
+export declare enum MCPErrorCode {
+    PARSE_ERROR = -32700,
+    INVALID_REQUEST = -32600,
+    METHOD_NOT_FOUND = -32601,
+    INVALID_PARAMS = -32602,
+    INTERNAL_ERROR = -32603,
+    NOT_AUTHENTICATED = -32001,
+    TOKEN_EXPIRED = -32002,
+    PERMISSION_DENIED = -32003,
+    RATE_LIMITED = -32004,
+    RESOURCE_NOT_FOUND = -32005,
+    VALIDATION_ERROR = -32006,
+    CONFLICT = -32007,
+    SERVICE_UNAVAILABLE = -32008,
+    NETWORK_ERROR = -32009,
+    TIMEOUT = -32010
+}
+/**
+ * FreshBooks Error Codes
+ *
+ * Error codes as returned by the FreshBooks API.
+ * These are mapped to MCP error codes for client consumption.
+ */
+export declare enum FreshBooksErrorCode {
+    UNAUTHORIZED = "UNAUTHORIZED",
+    FORBIDDEN = "FORBIDDEN",
+    NOT_FOUND = "NOT_FOUND",
+    VALIDATION_ERROR = "VALIDATION_ERROR",
+    RATE_LIMIT_EXCEEDED = "RATE_LIMIT_EXCEEDED",
+    INTERNAL_ERROR = "INTERNAL_ERROR",
+    CONFLICT = "CONFLICT",
+    BAD_REQUEST = "BAD_REQUEST",
+    SERVICE_UNAVAILABLE = "SERVICE_UNAVAILABLE",
+    UNAUTHENTICATED = "UNAUTHENTICATED",
+    TOKEN_EXPIRED = "TOKEN_EXPIRED",
+    INVALID_GRANT = "INVALID_GRANT",
+    INSUFFICIENT_PERMISSIONS = "INSUFFICIENT_PERMISSIONS"
+}
+/**
+ * Normalized MCP Error
+ *
+ * All errors are transformed into this format before being
+ * sent to the client. Follows JSON-RPC 2.0 error object spec.
+ */
+export interface MCPError extends Error {
+    code: MCPErrorCode;
+    message: string;
+    data: MCPErrorData;
+}
+/**
+ * Error Data
+ *
+ * Preserves original FreshBooks error details while adding
+ * context and recovery guidance.
+ */
+export interface MCPErrorData {
+    freshbooksError?: {
+        code: string;
+        message: string;
+        field?: string;
+        errno?: number;
+        details?: Record<string, unknown>;
+        statusCode?: number;
+        type?: string;
+    };
+    validationErrors?: Array<{
+        path: string;
+        message: string;
+        code: string;
+        expected?: string;
+        received?: unknown;
+    }>;
+    context?: ErrorContext;
+    recoverable: boolean;
+    suggestion?: string;
+    retryAfter?: number;
+    authUrl?: string;
+    statusCode?: number;
+}
+/**
+ * Error Context
+ *
+ * Contextual information about where and why the error occurred.
+ */
+export interface ErrorContext {
+    tool?: string;
+    accountId?: string;
+    entityId?: number | string;
+    requestId?: string;
+    operation?: string;
+    [key: string]: unknown;
+}
+/**
+ * FreshBooks API Error
+ *
+ * The error structure returned by the FreshBooks SDK.
+ */
+export interface FreshBooksApiError {
+    ok: false;
+    error: {
+        code: string;
+        message: string;
+        field?: string;
+        errno?: number;
+        details?: Record<string, unknown>;
+        type?: string;
+    };
+    statusCode?: number;
+    retryAfter?: number;
+}
+/**
+ * OAuth Error
+ *
+ * Errors from the OAuth flow.
+ */
+export declare class OAuthError extends Error {
+    code: string;
+    details?: Record<string, unknown> | undefined;
+    constructor(code: string, message: string, details?: Record<string, unknown> | undefined);
+}
+/**
+ * OAuth Error Response
+ *
+ * Error structure from OAuth token endpoints.
+ */
+export interface OAuthErrorResponse {
+    error: string;
+    error_description?: string;
+    error_uri?: string;
+}
+/**
+ * Error Mapping Configuration
+ *
+ * Configuration for mapping error types to MCP errors.
+ */
+export interface ErrorMapping {
+    mcpCode: MCPErrorCode;
+    recoverable: boolean;
+    getMessage: (error: FreshBooksApiError["error"]) => string;
+    getSuggestion: (error: FreshBooksApiError["error"]) => string;
+    statusCode?: number;
+}
+/**
+ * Tool Context
+ *
+ * Context passed to tool handlers.
+ */
+export interface ToolContext {
+    accountId?: string;
+    [key: string]: unknown;
+}
+/**
+ * Network Error Type
+ *
+ * Common network error codes from Node.js.
+ */
+export declare enum NetworkErrorType {
+    TIMEOUT = "ETIMEDOUT",
+    CONNECTION_REFUSED = "ECONNREFUSED",
+    NOT_FOUND = "ENOTFOUND",
+    CONNECTION_RESET = "ECONNRESET",
+    NETWORK_UNREACHABLE = "ENETUNREACH",
+    DNS_FAILURE = "EAI_AGAIN"
+}
+/**
+ * Type guard: Check if error is an MCP error
+ */
+export declare function isMCPError(error: unknown): error is MCPError;
+/**
+ * Type guard: Check if error is a FreshBooks API error
+ */
+export declare function isFreshBooksError(error: unknown): error is FreshBooksApiError;
+/**
+ * Type guard: Check if error is an OAuth error
+ */
+export declare function isOAuthError(error: unknown): error is OAuthError;
+/**
+ * Type guard: Check if error is a network error
+ */
+export declare function isNetworkError(error: unknown): error is NodeJS.ErrnoException;
+//# sourceMappingURL=types.d.ts.map

package/dist/errors/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/errors/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;GAKG;AACH,oBAAY,YAAY;IAEtB,WAAW,SAAS;IACpB,eAAe,SAAS;IACxB,gBAAgB,SAAS;IACzB,cAAc,SAAS;IACvB,cAAc,SAAS;IAGvB,iBAAiB,SAAS;IAC1B,aAAa,SAAS;IACtB,iBAAiB,SAAS;IAC1B,YAAY,SAAS;IACrB,kBAAkB,SAAS;IAC3B,gBAAgB,SAAS;IACzB,QAAQ,SAAS;IACjB,mBAAmB,SAAS;IAC5B,aAAa,SAAS;IACtB,OAAO,SAAS;CACjB;AAED;;;;;GAKG;AACH,oBAAY,mBAAmB;IAC7B,YAAY,iBAAiB;IAC7B,SAAS,cAAc;IACvB,SAAS,cAAc;IACvB,gBAAgB,qBAAqB;IACrC,mBAAmB,wBAAwB;IAC3C,cAAc,mBAAmB;IACjC,QAAQ,aAAa;IACrB,WAAW,gBAAgB;IAC3B,mBAAmB,wBAAwB;IAC3C,eAAe,oBAAoB;IACnC,aAAa,kBAAkB;IAC/B,aAAa,kBAAkB;IAC/B,wBAAwB,6BAA6B;CACtD;AAED;;;;;GAKG;AACH,MAAM,WAAW,QAAS,SAAQ,KAAK;IACrC,IAAI,EAAE,YAAY,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,YAAY,CAAC;CACpB;AAED;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAE3B,eAAe,CAAC,EAAE;QAChB,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;QAChB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAClC,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,IAAI,CAAC,EAAE,MAAM,CAAC;KACf,CAAC;IAGF,gBAAgB,CAAC,EAAE,KAAK,CAAC;QACvB,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;QAChB,IAAI,EAAE,MAAM,CAAC;QACb,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,QAAQ,CAAC,EAAE,OAAO,CAAC;KACpB,CAAC,CAAC;IAGH,OAAO,CAAC,EAAE,YAAY,CAAC;IAGvB,WAAW,EAAE,OAAO,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC3B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,KAAK,CAAC;IACV,KAAK,EAAE;QACL,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;QAChB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAClC,IAAI,CAAC,EAAE,MAAM,CAAC;KACf,CAAC;IACF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;GAIG;AACH,qBAAa,UAAW,SAAQ,KAAK;IAE1B,IAAI,EAAE,MAAM;IAEZ,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;gBAFjC,IAAI,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,EACR,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,YAAA;CAK3C;AAED;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,YAAY,CAAC;IACtB,WAAW,EAAE,OAAO,CAAC;IACrB,UAAU,EAAE,CAAC,KAAK,EAAE,kBAAkB,CAAC,OAAO,CAAC,KAAK,MAAM,CAAC;IAC3D,aAAa,EAAE,CAAC,KAAK,EAAE,kBAAkB,CAAC,OAAO,CAAC,KAAK,MAAM,CAAC;IAC9D,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;;;GAIG;AACH,oBAAY,gBAAgB;IAC1B,OAAO,cAAc;IACrB,kBAAkB,iBAAiB;IACnC,SAAS,cAAc;IACvB,gBAAgB,eAAe;IAC/B,mBAAmB,gBAAgB;IACnC,WAAW,cAAc;CAC1B;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,QAAQ,CAU5D;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,kBAAkB,CAS7E;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,UAAU,CAEhE;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAAC,cAAc,CAoB7E"}

package/dist/errors/types.js

@@ -0,0 +1,134 @@
+/**
+ * Error Type Definitions
+ *
+ * Comprehensive type definitions for the dual-format error system.
+ * All errors are normalized to MCP format while preserving original
+ * FreshBooks error details for debugging.
+ */
+/**
+ * MCP Error Codes (JSON-RPC 2.0)
+ *
+ * Standard JSON-RPC error codes (-32768 to -32000) plus
+ * custom application errors (-32000 to -32099)
+ */
+export var MCPErrorCode;
+(function (MCPErrorCode) {
+    // Standard JSON-RPC 2.0 errors
+    MCPErrorCode[MCPErrorCode["PARSE_ERROR"] = -32700] = "PARSE_ERROR";
+    MCPErrorCode[MCPErrorCode["INVALID_REQUEST"] = -32600] = "INVALID_REQUEST";
+    MCPErrorCode[MCPErrorCode["METHOD_NOT_FOUND"] = -32601] = "METHOD_NOT_FOUND";
+    MCPErrorCode[MCPErrorCode["INVALID_PARAMS"] = -32602] = "INVALID_PARAMS";
+    MCPErrorCode[MCPErrorCode["INTERNAL_ERROR"] = -32603] = "INTERNAL_ERROR";
+    // Custom application errors (range: -32000 to -32099)
+    MCPErrorCode[MCPErrorCode["NOT_AUTHENTICATED"] = -32001] = "NOT_AUTHENTICATED";
+    MCPErrorCode[MCPErrorCode["TOKEN_EXPIRED"] = -32002] = "TOKEN_EXPIRED";
+    MCPErrorCode[MCPErrorCode["PERMISSION_DENIED"] = -32003] = "PERMISSION_DENIED";
+    MCPErrorCode[MCPErrorCode["RATE_LIMITED"] = -32004] = "RATE_LIMITED";
+    MCPErrorCode[MCPErrorCode["RESOURCE_NOT_FOUND"] = -32005] = "RESOURCE_NOT_FOUND";
+    MCPErrorCode[MCPErrorCode["VALIDATION_ERROR"] = -32006] = "VALIDATION_ERROR";
+    MCPErrorCode[MCPErrorCode["CONFLICT"] = -32007] = "CONFLICT";
+    MCPErrorCode[MCPErrorCode["SERVICE_UNAVAILABLE"] = -32008] = "SERVICE_UNAVAILABLE";
+    MCPErrorCode[MCPErrorCode["NETWORK_ERROR"] = -32009] = "NETWORK_ERROR";
+    MCPErrorCode[MCPErrorCode["TIMEOUT"] = -32010] = "TIMEOUT";
+})(MCPErrorCode || (MCPErrorCode = {}));
+/**
+ * FreshBooks Error Codes
+ *
+ * Error codes as returned by the FreshBooks API.
+ * These are mapped to MCP error codes for client consumption.
+ */
+export var FreshBooksErrorCode;
+(function (FreshBooksErrorCode) {
+    FreshBooksErrorCode["UNAUTHORIZED"] = "UNAUTHORIZED";
+    FreshBooksErrorCode["FORBIDDEN"] = "FORBIDDEN";
+    FreshBooksErrorCode["NOT_FOUND"] = "NOT_FOUND";
+    FreshBooksErrorCode["VALIDATION_ERROR"] = "VALIDATION_ERROR";
+    FreshBooksErrorCode["RATE_LIMIT_EXCEEDED"] = "RATE_LIMIT_EXCEEDED";
+    FreshBooksErrorCode["INTERNAL_ERROR"] = "INTERNAL_ERROR";
+    FreshBooksErrorCode["CONFLICT"] = "CONFLICT";
+    FreshBooksErrorCode["BAD_REQUEST"] = "BAD_REQUEST";
+    FreshBooksErrorCode["SERVICE_UNAVAILABLE"] = "SERVICE_UNAVAILABLE";
+    FreshBooksErrorCode["UNAUTHENTICATED"] = "UNAUTHENTICATED";
+    FreshBooksErrorCode["TOKEN_EXPIRED"] = "TOKEN_EXPIRED";
+    FreshBooksErrorCode["INVALID_GRANT"] = "INVALID_GRANT";
+    FreshBooksErrorCode["INSUFFICIENT_PERMISSIONS"] = "INSUFFICIENT_PERMISSIONS";
+})(FreshBooksErrorCode || (FreshBooksErrorCode = {}));
+/**
+ * OAuth Error
+ *
+ * Errors from the OAuth flow.
+ */
+export class OAuthError extends Error {
+    code;
+    details;
+    constructor(code, message, details) {
+        super(message);
+        this.code = code;
+        this.details = details;
+        this.name = "OAuthError";
+    }
+}
+/**
+ * Network Error Type
+ *
+ * Common network error codes from Node.js.
+ */
+export var NetworkErrorType;
+(function (NetworkErrorType) {
+    NetworkErrorType["TIMEOUT"] = "ETIMEDOUT";
+    NetworkErrorType["CONNECTION_REFUSED"] = "ECONNREFUSED";
+    NetworkErrorType["NOT_FOUND"] = "ENOTFOUND";
+    NetworkErrorType["CONNECTION_RESET"] = "ECONNRESET";
+    NetworkErrorType["NETWORK_UNREACHABLE"] = "ENETUNREACH";
+    NetworkErrorType["DNS_FAILURE"] = "EAI_AGAIN";
+})(NetworkErrorType || (NetworkErrorType = {}));
+/**
+ * Type guard: Check if error is an MCP error
+ */
+export function isMCPError(error) {
+    return (typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        "message" in error &&
+        "data" in error &&
+        typeof error.code === "number" &&
+        typeof error.message === "string");
+}
+/**
+ * Type guard: Check if error is a FreshBooks API error
+ */
+export function isFreshBooksError(error) {
+    return (typeof error === "object" &&
+        error !== null &&
+        "ok" in error &&
+        error.ok === false &&
+        "error" in error &&
+        typeof error.error === "object");
+}
+/**
+ * Type guard: Check if error is an OAuth error
+ */
+export function isOAuthError(error) {
+    return error instanceof OAuthError;
+}
+/**
+ * Type guard: Check if error is a network error
+ */
+export function isNetworkError(error) {
+    if (!(error instanceof Error)) {
+        return false;
+    }
+    const networkIndicators = [
+        "ETIMEDOUT",
+        "ECONNREFUSED",
+        "ENOTFOUND",
+        "ECONNRESET",
+        "ENETUNREACH",
+        "EAI_AGAIN",
+        "socket hang up",
+        "network",
+        "timeout",
+    ];
+    return networkIndicators.some((indicator) => error.message.toLowerCase().includes(indicator.toLowerCase()));
+}
+//# sourceMappingURL=types.js.map

package/dist/errors/types.js.map

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

package/dist/server.d.ts

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+/**
+ * FreshBooks MCP Server
+ *
+ * Main entry point for the FreshBooks Model Context Protocol server.
+ * Provides Claude with access to FreshBooks time tracking, invoicing,
+ * expense management, and more through MCP tools.
+ */
+export {};
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":";AAEA;;;;;;GAMG"}