@goodsamsoftware/freshbooks-mcp 1.0.0

package/dist/errors/documentation.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Error Documentation
+ *
+ * Comprehensive documentation for all MCP error codes including:
+ * - Description of what the error means
+ * - Common causes
+ * - Recommended solutions
+ * - Examples
+ */
+import { MCPErrorCode } from "./types.js";
+/**
+ * Error Documentation Entry
+ */
+export interface ErrorDocumentation {
+    name: string;
+    description: string;
+    causes: string[];
+    solutions: string[];
+    examples?: string[];
+}
+/**
+ * Complete error documentation map
+ */
+export declare const ERROR_DOCUMENTATION: Record<MCPErrorCode, ErrorDocumentation>;
+/**
+ * Get documentation for an error code
+ *
+ * @param code - MCP error code
+ * @returns Documentation for the error, or undefined if not found
+ */
+export declare function getErrorDocumentation(code: MCPErrorCode): ErrorDocumentation | undefined;
+/**
+ * Get all error codes and their documentation
+ *
+ * @returns Map of all error codes to their documentation
+ */
+export declare function getAllErrorDocumentation(): Record<MCPErrorCode, ErrorDocumentation>;
+/**
+ * Search error documentation
+ *
+ * Search for errors by name, description, or causes.
+ *
+ * @param query - Search query
+ * @returns Matching error codes and documentation
+ */
+export declare function searchErrorDocumentation(query: string): Array<{
+    code: MCPErrorCode;
+    documentation: ErrorDocumentation;
+}>;
+/**
+ * Format error documentation as markdown
+ *
+ * @param code - MCP error code
+ * @returns Markdown formatted documentation
+ */
+export declare function formatErrorDocumentation(code: MCPErrorCode): string;
+//# sourceMappingURL=documentation.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"documentation.d.ts","sourceRoot":"","sources":["../../src/errors/documentation.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE1C;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CACrB;AAED;;GAEG;AACH,eAAO,MAAM,mBAAmB,EAAE,MAAM,CAAC,YAAY,EAAE,kBAAkB,CA6TxE,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,YAAY,GACjB,kBAAkB,GAAG,SAAS,CAEhC;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,IAAI,MAAM,CAChD,YAAY,EACZ,kBAAkB,CACnB,CAEA;AAED;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,MAAM,GACZ,KAAK,CAAC;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,aAAa,EAAE,kBAAkB,CAAA;CAAE,CAAC,CA0BlE;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,YAAY,GAAG,MAAM,CAuBnE"}

package/dist/errors/documentation.js

@@ -0,0 +1,390 @@
+/**
+ * Error Documentation
+ *
+ * Comprehensive documentation for all MCP error codes including:
+ * - Description of what the error means
+ * - Common causes
+ * - Recommended solutions
+ * - Examples
+ */
+import { MCPErrorCode } from "./types.js";
+/**
+ * Complete error documentation map
+ */
+export const ERROR_DOCUMENTATION = {
+    // Standard JSON-RPC 2.0 Errors
+    [MCPErrorCode.PARSE_ERROR]: {
+        name: "Parse Error",
+        description: "Invalid JSON was received by the server",
+        causes: [
+            "Malformed JSON in request",
+            "Invalid character encoding",
+            "Incomplete JSON structure",
+        ],
+        solutions: [
+            "Verify the request is valid JSON",
+            "Check for proper escaping of special characters",
+            "Ensure complete JSON structure with matching braces",
+        ],
+        examples: [
+            "Missing closing brace in JSON object",
+            "Unescaped quotes in string values",
+        ],
+    },
+    [MCPErrorCode.INVALID_REQUEST]: {
+        name: "Invalid Request",
+        description: "The JSON sent is not a valid Request object",
+        causes: [
+            "Missing required fields (jsonrpc, method)",
+            "Invalid jsonrpc version",
+            "Invalid method name format",
+        ],
+        solutions: [
+            "Include 'jsonrpc': '2.0' in request",
+            "Provide valid 'method' field",
+            "Ensure request structure matches JSON-RPC 2.0 spec",
+        ],
+        examples: [
+            "Request missing 'method' field",
+            "jsonrpc field set to '1.0' instead of '2.0'",
+        ],
+    },
+    [MCPErrorCode.METHOD_NOT_FOUND]: {
+        name: "Method Not Found",
+        description: "The requested method does not exist or is not available",
+        causes: [
+            "Misspelled tool name",
+            "Tool not registered",
+            "Tool disabled or deprecated",
+        ],
+        solutions: [
+            "Check the tool name spelling",
+            "List available tools to verify the tool exists",
+            "Update to use the current tool name if deprecated",
+        ],
+        examples: [
+            "Called 'timeentry_creates' instead of 'timeentry_create'",
+            "Attempting to use a deprecated tool",
+        ],
+    },
+    [MCPErrorCode.INVALID_PARAMS]: {
+        name: "Invalid Parameters",
+        description: "Invalid method parameters provided",
+        causes: [
+            "Missing required parameters",
+            "Invalid parameter types",
+            "Parameters outside valid ranges",
+            "Malformed parameter structure",
+        ],
+        solutions: [
+            "Check all required parameters are provided",
+            "Verify parameter types match the schema",
+            "Ensure values are within valid ranges",
+            "Review parameter format requirements",
+        ],
+        examples: [
+            "Missing required 'account_id' parameter",
+            "Provided string instead of number for 'duration'",
+            "Date in wrong format (use ISO 8601)",
+        ],
+    },
+    [MCPErrorCode.INTERNAL_ERROR]: {
+        name: "Internal Error",
+        description: "Internal server error occurred",
+        causes: [
+            "Unexpected exception in server code",
+            "Unhandled error condition",
+            "System resource issues",
+        ],
+        solutions: [
+            "Retry the operation",
+            "Check server logs for details",
+            "Report the issue if it persists",
+        ],
+        examples: [
+            "Unexpected null pointer",
+            "Database connection failed",
+        ],
+    },
+    // Custom Application Errors
+    [MCPErrorCode.NOT_AUTHENTICATED]: {
+        name: "Not Authenticated",
+        description: "No valid authentication found or session expired",
+        causes: [
+            "Never authenticated with FreshBooks",
+            "Access token expired (typically after 12 hours)",
+            "Tokens were revoked by user",
+            "Invalid or corrupted token storage",
+        ],
+        solutions: [
+            "Call auth_get_url to start authentication flow",
+            "Visit the authorization URL and approve access",
+            "Exchange the authorization code using auth_exchange_code",
+            "Call auth_refresh if you have a valid refresh token",
+        ],
+        examples: [
+            "First time using the server - need to authenticate",
+            "Access token expired after 12 hours",
+            "User revoked access in FreshBooks settings",
+        ],
+    },
+    [MCPErrorCode.TOKEN_EXPIRED]: {
+        name: "Token Expired",
+        description: "The access token has expired and needs to be refreshed",
+        causes: [
+            "Token lifetime exceeded (usually 12 hours for FreshBooks)",
+            "Server clock skew",
+            "Server invalidated the token",
+        ],
+        solutions: [
+            "Call auth_refresh to get a new access token",
+            "Re-authenticate if refresh fails",
+            "Check system clock is accurate",
+        ],
+        examples: [
+            "Token issued 13 hours ago",
+            "Token manually invalidated by FreshBooks",
+        ],
+    },
+    [MCPErrorCode.PERMISSION_DENIED]: {
+        name: "Permission Denied",
+        description: "You don't have permission to access this resource",
+        causes: [
+            "Insufficient role/permissions in FreshBooks account",
+            "Resource belongs to another account",
+            "Feature not enabled for your FreshBooks plan",
+            "Attempting to modify read-only resource",
+        ],
+        solutions: [
+            "Verify you're using the correct account",
+            "Contact your FreshBooks administrator for access",
+            "Upgrade your FreshBooks plan if needed",
+            "Check the resource belongs to your account",
+        ],
+        examples: [
+            "Regular user trying to delete someone else's time entry",
+            "Accessing feature not included in current plan",
+            "Trying to modify archived/locked resource",
+        ],
+    },
+    [MCPErrorCode.RATE_LIMITED]: {
+        name: "Rate Limited",
+        description: "Too many requests in a short period",
+        causes: [
+            "Exceeded API rate limits (varies by endpoint)",
+            "Burst of requests sent too quickly",
+            "Shared IP address limit reached",
+        ],
+        solutions: [
+            "Wait before making more requests (check retryAfter)",
+            "Implement exponential backoff for retries",
+            "Reduce request frequency",
+            "Batch operations when possible",
+        ],
+        examples: [
+            "Sent 100 requests in 1 second",
+            "Multiple users on same IP hitting limits",
+        ],
+    },
+    [MCPErrorCode.RESOURCE_NOT_FOUND]: {
+        name: "Resource Not Found",
+        description: "The requested resource doesn't exist",
+        causes: [
+            "Invalid ID provided",
+            "Resource was deleted",
+            "Resource is in a different account",
+            "Typo in resource identifier",
+        ],
+        solutions: [
+            "Verify the ID is correct",
+            "List resources to find valid IDs",
+            "Check you're using the correct account",
+            "Confirm resource wasn't deleted",
+        ],
+        examples: [
+            "TimeEntry with id 99999 not found",
+            "Project deleted before update attempted",
+            "Looking for resource in wrong account",
+        ],
+    },
+    [MCPErrorCode.VALIDATION_ERROR]: {
+        name: "Validation Error",
+        description: "The input data failed validation",
+        causes: [
+            "Missing required fields",
+            "Invalid field values",
+            "Format errors (dates, emails, numbers)",
+            "Business rule violations",
+            "Field value out of acceptable range",
+        ],
+        solutions: [
+            "Check all required fields are provided",
+            "Verify field formats (dates in ISO 8601, etc.)",
+            "Review validation error details for specific field",
+            "Ensure values meet business rules",
+        ],
+        examples: [
+            "Missing required 'description' field",
+            "Date format is MM/DD/YYYY instead of ISO 8601",
+            "Duration is negative",
+            "Email address format invalid",
+        ],
+    },
+    [MCPErrorCode.CONFLICT]: {
+        name: "Conflict",
+        description: "The operation conflicts with existing data",
+        causes: [
+            "Duplicate entry (unique constraint violation)",
+            "Concurrent modification detected",
+            "Business rule violation",
+            "Resource state incompatible with operation",
+        ],
+        solutions: [
+            "Check for existing similar resources",
+            "Use update instead of create",
+            "Resolve the conflict manually",
+            "Fetch latest version and retry",
+        ],
+        examples: [
+            "Client with same email already exists",
+            "Invoice number already used",
+            "Resource modified by another user",
+            "Trying to delete resource with dependencies",
+        ],
+    },
+    [MCPErrorCode.SERVICE_UNAVAILABLE]: {
+        name: "Service Unavailable",
+        description: "The FreshBooks service is temporarily unavailable",
+        causes: [
+            "FreshBooks API is down for maintenance",
+            "Network connectivity issues",
+            "Request timeout",
+            "Service overloaded",
+        ],
+        solutions: [
+            "Wait and retry the operation",
+            "Check FreshBooks status page",
+            "Verify internet connection",
+            "Implement exponential backoff",
+        ],
+        examples: [
+            "Scheduled maintenance window",
+            "Network timeout after 30 seconds",
+            "FreshBooks experiencing high load",
+        ],
+    },
+    [MCPErrorCode.NETWORK_ERROR]: {
+        name: "Network Error",
+        description: "A network communication error occurred",
+        causes: [
+            "No internet connection",
+            "DNS resolution failed",
+            "Connection refused by server",
+            "Network unreachable",
+        ],
+        solutions: [
+            "Check your internet connection",
+            "Verify DNS settings",
+            "Try again later",
+            "Check if FreshBooks is accessible from your network",
+        ],
+        examples: [
+            "ECONNREFUSED when server is down",
+            "ENOTFOUND for DNS issues",
+            "ENETUNREACH for network problems",
+        ],
+    },
+    [MCPErrorCode.TIMEOUT]: {
+        name: "Timeout",
+        description: "The request timed out before receiving a response",
+        causes: [
+            "Server took too long to respond",
+            "Network latency issues",
+            "Large request payload",
+            "Server under heavy load",
+        ],
+        solutions: [
+            "Retry the request",
+            "Check network connectivity",
+            "Try with smaller request payload",
+            "Wait and try again later",
+        ],
+        examples: [
+            "Request exceeded 30 second timeout",
+            "Connection established but response never received",
+        ],
+    },
+};
+/**
+ * Get documentation for an error code
+ *
+ * @param code - MCP error code
+ * @returns Documentation for the error, or undefined if not found
+ */
+export function getErrorDocumentation(code) {
+    return ERROR_DOCUMENTATION[code];
+}
+/**
+ * Get all error codes and their documentation
+ *
+ * @returns Map of all error codes to their documentation
+ */
+export function getAllErrorDocumentation() {
+    return ERROR_DOCUMENTATION;
+}
+/**
+ * Search error documentation
+ *
+ * Search for errors by name, description, or causes.
+ *
+ * @param query - Search query
+ * @returns Matching error codes and documentation
+ */
+export function searchErrorDocumentation(query) {
+    const results = [];
+    const lowerQuery = query.toLowerCase();
+    for (const [codeStr, doc] of Object.entries(ERROR_DOCUMENTATION)) {
+        const code = parseInt(codeStr);
+        // Search in name, description, causes, and solutions
+        const searchText = [
+            doc.name,
+            doc.description,
+            ...doc.causes,
+            ...doc.solutions,
+        ]
+            .join(" ")
+            .toLowerCase();
+        if (searchText.includes(lowerQuery)) {
+            results.push({ code, documentation: doc });
+        }
+    }
+    return results;
+}
+/**
+ * Format error documentation as markdown
+ *
+ * @param code - MCP error code
+ * @returns Markdown formatted documentation
+ */
+export function formatErrorDocumentation(code) {
+    const doc = ERROR_DOCUMENTATION[code];
+    if (!doc) {
+        return `No documentation available for error code ${code}`;
+    }
+    const parts = [
+        `# ${doc.name} (${code})`,
+        "",
+        doc.description,
+        "",
+        "## Common Causes",
+        ...doc.causes.map((cause) => `- ${cause}`),
+        "",
+        "## Solutions",
+        ...doc.solutions.map((solution) => `- ${solution}`),
+    ];
+    if (doc.examples && doc.examples.length > 0) {
+        parts.push("", "## Examples", ...doc.examples.map((ex) => `- ${ex}`));
+    }
+    return parts.join("\n");
+}
+//# sourceMappingURL=documentation.js.map

package/dist/errors/documentation.js.map

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

package/dist/errors/error-codes.d.ts

@@ -0,0 +1,45 @@
+/**
+ * MCP and FreshBooks error code definitions
+ */
+/**
+ * Standard JSON-RPC error codes used by MCP
+ */
+export declare const MCP_ERROR_CODES: {
+    readonly PARSE_ERROR: -32700;
+    readonly INVALID_REQUEST: -32600;
+    readonly METHOD_NOT_FOUND: -32601;
+    readonly INVALID_PARAMS: -32602;
+    readonly INTERNAL_ERROR: -32603;
+};
+/**
+ * Custom error codes for FreshBooks MCP server
+ * Range: -32000 to -32099 (reserved for implementation-defined server errors)
+ */
+export declare const FRESHBOOKS_ERROR_CODES: {
+    readonly AUTH_REQUIRED: -32000;
+    readonly AUTH_INVALID: -32001;
+    readonly AUTH_EXPIRED: -32002;
+    readonly AUTH_REFRESH_FAILED: -32003;
+    readonly API_ERROR: -32010;
+    readonly API_RATE_LIMIT: -32011;
+    readonly API_NOT_FOUND: -32012;
+    readonly API_VALIDATION: -32013;
+    readonly RESOURCE_NOT_FOUND: -32020;
+    readonly RESOURCE_CONFLICT: -32021;
+    readonly RESOURCE_INVALID: -32022;
+    readonly NETWORK_ERROR: -32030;
+    readonly TIMEOUT: -32031;
+};
+/**
+ * Error code to human-readable message mapping
+ */
+export declare const ERROR_MESSAGES: Record<number, string>;
+/**
+ * Determine if an error is recoverable (user can retry)
+ */
+export declare function isRecoverable(code: number): boolean;
+/**
+ * Get suggestion for error resolution
+ */
+export declare function getSuggestion(code: number): string | undefined;
+//# sourceMappingURL=error-codes.d.ts.map

package/dist/errors/error-codes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-codes.d.ts","sourceRoot":"","sources":["../../src/errors/error-codes.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;GAEG;AACH,eAAO,MAAM,eAAe;;;;;;CAMlB,CAAC;AAEX;;;GAGG;AACH,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;CAqBzB,CAAC;AAEX;;GAEG;AACH,eAAO,MAAM,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CA4BjD,CAAC;AAEF;;GAEG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CASnD;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAc9D"}

package/dist/errors/error-codes.js

@@ -0,0 +1,94 @@
+/**
+ * MCP and FreshBooks error code definitions
+ */
+/**
+ * Standard JSON-RPC error codes used by MCP
+ */
+export const MCP_ERROR_CODES = {
+    PARSE_ERROR: -32700,
+    INVALID_REQUEST: -32600,
+    METHOD_NOT_FOUND: -32601,
+    INVALID_PARAMS: -32602,
+    INTERNAL_ERROR: -32603,
+};
+/**
+ * Custom error codes for FreshBooks MCP server
+ * Range: -32000 to -32099 (reserved for implementation-defined server errors)
+ */
+export const FRESHBOOKS_ERROR_CODES = {
+    // Authentication errors (-32000 to -32009)
+    AUTH_REQUIRED: -32000,
+    AUTH_INVALID: -32001,
+    AUTH_EXPIRED: -32002,
+    AUTH_REFRESH_FAILED: -32003,
+    // API errors (-32010 to -32019)
+    API_ERROR: -32010,
+    API_RATE_LIMIT: -32011,
+    API_NOT_FOUND: -32012,
+    API_VALIDATION: -32013,
+    // Resource errors (-32020 to -32029)
+    RESOURCE_NOT_FOUND: -32020,
+    RESOURCE_CONFLICT: -32021,
+    RESOURCE_INVALID: -32022,
+    // Network errors (-32030 to -32039)
+    NETWORK_ERROR: -32030,
+    TIMEOUT: -32031,
+};
+/**
+ * Error code to human-readable message mapping
+ */
+export const ERROR_MESSAGES = {
+    // Standard JSON-RPC
+    [MCP_ERROR_CODES.PARSE_ERROR]: 'Invalid JSON was received',
+    [MCP_ERROR_CODES.INVALID_REQUEST]: 'The JSON sent is not a valid request',
+    [MCP_ERROR_CODES.METHOD_NOT_FOUND]: 'The method does not exist or is not available',
+    [MCP_ERROR_CODES.INVALID_PARAMS]: 'Invalid method parameters',
+    [MCP_ERROR_CODES.INTERNAL_ERROR]: 'Internal server error',
+    // Authentication
+    [FRESHBOOKS_ERROR_CODES.AUTH_REQUIRED]: 'Authentication required',
+    [FRESHBOOKS_ERROR_CODES.AUTH_INVALID]: 'Invalid authentication credentials',
+    [FRESHBOOKS_ERROR_CODES.AUTH_EXPIRED]: 'Authentication token expired',
+    [FRESHBOOKS_ERROR_CODES.AUTH_REFRESH_FAILED]: 'Failed to refresh authentication token',
+    // API
+    [FRESHBOOKS_ERROR_CODES.API_ERROR]: 'FreshBooks API error',
+    [FRESHBOOKS_ERROR_CODES.API_RATE_LIMIT]: 'API rate limit exceeded',
+    [FRESHBOOKS_ERROR_CODES.API_NOT_FOUND]: 'Resource not found in FreshBooks',
+    [FRESHBOOKS_ERROR_CODES.API_VALIDATION]: 'Validation error from FreshBooks API',
+    // Resources
+    [FRESHBOOKS_ERROR_CODES.RESOURCE_NOT_FOUND]: 'Requested resource not found',
+    [FRESHBOOKS_ERROR_CODES.RESOURCE_CONFLICT]: 'Resource conflict',
+    [FRESHBOOKS_ERROR_CODES.RESOURCE_INVALID]: 'Invalid resource data',
+    // Network
+    [FRESHBOOKS_ERROR_CODES.NETWORK_ERROR]: 'Network communication error',
+    [FRESHBOOKS_ERROR_CODES.TIMEOUT]: 'Request timeout',
+};
+/**
+ * Determine if an error is recoverable (user can retry)
+ */
+export function isRecoverable(code) {
+    const recoverableCodes = [
+        FRESHBOOKS_ERROR_CODES.AUTH_EXPIRED,
+        FRESHBOOKS_ERROR_CODES.API_RATE_LIMIT,
+        FRESHBOOKS_ERROR_CODES.NETWORK_ERROR,
+        FRESHBOOKS_ERROR_CODES.TIMEOUT,
+    ];
+    return recoverableCodes.includes(code);
+}
+/**
+ * Get suggestion for error resolution
+ */
+export function getSuggestion(code) {
+    const suggestions = {
+        [FRESHBOOKS_ERROR_CODES.AUTH_REQUIRED]: 'Call auth_get_url to start authentication',
+        [FRESHBOOKS_ERROR_CODES.AUTH_INVALID]: 'Re-authenticate using auth_get_url',
+        [FRESHBOOKS_ERROR_CODES.AUTH_EXPIRED]: 'Token will be automatically refreshed, please retry',
+        [FRESHBOOKS_ERROR_CODES.AUTH_REFRESH_FAILED]: 'Re-authenticate using auth_get_url',
+        [FRESHBOOKS_ERROR_CODES.API_RATE_LIMIT]: 'Wait a moment and retry the request',
+        [FRESHBOOKS_ERROR_CODES.API_NOT_FOUND]: 'Verify the resource ID and account ID are correct',
+        [FRESHBOOKS_ERROR_CODES.API_VALIDATION]: 'Check the input parameters and try again',
+        [FRESHBOOKS_ERROR_CODES.NETWORK_ERROR]: 'Check network connection and retry',
+        [FRESHBOOKS_ERROR_CODES.TIMEOUT]: 'Retry the request',
+    };
+    return suggestions[code];
+}
+//# sourceMappingURL=error-codes.js.map

package/dist/errors/error-codes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-codes.js","sourceRoot":"","sources":["../../src/errors/error-codes.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;GAEG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,WAAW,EAAE,CAAC,KAAK;IACnB,eAAe,EAAE,CAAC,KAAK;IACvB,gBAAgB,EAAE,CAAC,KAAK;IACxB,cAAc,EAAE,CAAC,KAAK;IACtB,cAAc,EAAE,CAAC,KAAK;CACd,CAAC;AAEX;;;GAGG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG;IACpC,2CAA2C;IAC3C,aAAa,EAAE,CAAC,KAAK;IACrB,YAAY,EAAE,CAAC,KAAK;IACpB,YAAY,EAAE,CAAC,KAAK;IACpB,mBAAmB,EAAE,CAAC,KAAK;IAE3B,gCAAgC;IAChC,SAAS,EAAE,CAAC,KAAK;IACjB,cAAc,EAAE,CAAC,KAAK;IACtB,aAAa,EAAE,CAAC,KAAK;IACrB,cAAc,EAAE,CAAC,KAAK;IAEtB,qCAAqC;IACrC,kBAAkB,EAAE,CAAC,KAAK;IAC1B,iBAAiB,EAAE,CAAC,KAAK;IACzB,gBAAgB,EAAE,CAAC,KAAK;IAExB,oCAAoC;IACpC,aAAa,EAAE,CAAC,KAAK;IACrB,OAAO,EAAE,CAAC,KAAK;CACP,CAAC;AAEX;;GAEG;AACH,MAAM,CAAC,MAAM,cAAc,GAA2B;IACpD,oBAAoB;IACpB,CAAC,eAAe,CAAC,WAAW,CAAC,EAAE,2BAA2B;IAC1D,CAAC,eAAe,CAAC,eAAe,CAAC,EAAE,sCAAsC;IACzE,CAAC,eAAe,CAAC,gBAAgB,CAAC,EAAE,+CAA+C;IACnF,CAAC,eAAe,CAAC,cAAc,CAAC,EAAE,2BAA2B;IAC7D,CAAC,eAAe,CAAC,cAAc,CAAC,EAAE,uBAAuB;IAEzD,iBAAiB;IACjB,CAAC,sBAAsB,CAAC,aAAa,CAAC,EAAE,yBAAyB;IACjE,CAAC,sBAAsB,CAAC,YAAY,CAAC,EAAE,oCAAoC;IAC3E,CAAC,sBAAsB,CAAC,YAAY,CAAC,EAAE,8BAA8B;IACrE,CAAC,sBAAsB,CAAC,mBAAmB,CAAC,EAAE,wCAAwC;IAEtF,MAAM;IACN,CAAC,sBAAsB,CAAC,SAAS,CAAC,EAAE,sBAAsB;IAC1D,CAAC,sBAAsB,CAAC,cAAc,CAAC,EAAE,yBAAyB;IAClE,CAAC,sBAAsB,CAAC,aAAa,CAAC,EAAE,kCAAkC;IAC1E,CAAC,sBAAsB,CAAC,cAAc,CAAC,EAAE,sCAAsC;IAE/E,YAAY;IACZ,CAAC,sBAAsB,CAAC,kBAAkB,CAAC,EAAE,8BAA8B;IAC3E,CAAC,sBAAsB,CAAC,iBAAiB,CAAC,EAAE,mBAAmB;IAC/D,CAAC,sBAAsB,CAAC,gBAAgB,CAAC,EAAE,uBAAuB;IAElE,UAAU;IACV,CAAC,sBAAsB,CAAC,aAAa,CAAC,EAAE,6BAA6B;IACrE,CAAC,sBAAsB,CAAC,OAAO,CAAC,EAAE,iBAAiB;CACpD,CAAC;AAEF;;GAEG;AACH,MAAM,UAAU,aAAa,CAAC,IAAY;IACxC,MAAM,gBAAgB,GAAa;QACjC,sBAAsB,CAAC,YAAY;QACnC,sBAAsB,CAAC,cAAc;QACrC,sBAAsB,CAAC,aAAa;QACpC,sBAAsB,CAAC,OAAO;KAC/B,CAAC;IAEF,OAAO,gBAAgB,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;AACzC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,aAAa,CAAC,IAAY;IACxC,MAAM,WAAW,GAAoC;QACnD,CAAC,sBAAsB,CAAC,aAAa,CAAC,EAAE,2CAA2C;QACnF,CAAC,sBAAsB,CAAC,YAAY,CAAC,EAAE,oCAAoC;QAC3E,CAAC,sBAAsB,CAAC,YAAY,CAAC,EAAE,qDAAqD;QAC5F,CAAC,sBAAsB,CAAC,mBAAmB,CAAC,EAAE,oCAAoC;QAClF,CAAC,sBAAsB,CAAC,cAAc,CAAC,EAAE,qCAAqC;QAC9E,CAAC,sBAAsB,CAAC,aAAa,CAAC,EAAE,mDAAmD;QAC3F,CAAC,sBAAsB,CAAC,cAAc,CAAC,EAAE,0CAA0C;QACnF,CAAC,sBAAsB,CAAC,aAAa,CAAC,EAAE,oCAAoC;QAC5E,CAAC,sBAAsB,CAAC,OAAO,CAAC,EAAE,mBAAmB;KACtD,CAAC;IAEF,OAAO,WAAW,CAAC,IAAI,CAAC,CAAC;AAC3B,CAAC"}