attio-mcp 0.1.0

package/dist/cli/discover.js

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+/**
+ * CLI tool for discovering Attio attributes and generating mapping files
+ */
+import yargs from 'yargs';
+import { hideBin } from 'yargs/helpers';
+import { discoverAttributes } from './commands/attributes.js';
+import dotenv from 'dotenv';
+// Load environment variables from .env file
+dotenv.config();
+/**
+ * Main CLI entrypoint
+ */
+yargs(hideBin(process.argv))
+    .scriptName('attio-discover')
+    .usage('$0 <cmd> [args]')
+    .command('attributes', 'Discover Attio attribute mappings', (yargs) => {
+    return yargs
+        .option('object', {
+        alias: 'o',
+        description: 'Object type to discover attributes for (e.g., companies, people)',
+        type: 'string',
+    })
+        .option('all', {
+        alias: 'a',
+        description: 'Discover attributes for all objects',
+        type: 'boolean',
+        default: false,
+    })
+        .option('output', {
+        alias: 'f',
+        description: 'Output file path',
+        default: 'config/mappings/user.json',
+        type: 'string',
+    })
+        .option('reset', {
+        alias: 'r',
+        description: 'Reset existing mappings instead of merging',
+        type: 'boolean',
+        default: false,
+    })
+        .option('api-key', {
+        alias: 'k',
+        description: 'Attio API key (defaults to ATTIO_API_KEY env var)',
+        type: 'string',
+    })
+        .conflicts('object', 'all')
+        .check((argv) => {
+        if (!argv.object && !argv.all) {
+            throw new Error('You must specify either --object or --all');
+        }
+        return true;
+    });
+}, discoverAttributes)
+    /*
+    // These commands will be implemented in future phases
+    .command('objects', 'Discover object mappings', (yargs) => {
+      // ... object discovery options
+    }, discoverObjects)
+    .command('lists', 'Discover list mappings', (yargs) => {
+      // ... list discovery options
+    }, discoverLists)
+    .command('all', 'Discover all mappings', (yargs) => {
+      // ... options for discovering everything
+    }, discoverAll)
+    */
+    .demandCommand(1, 'You must specify a discovery command')
+    .help()
+    .alias('help', 'h')
+    .epilog('For more information, visit https://github.com/hmk/attio-mcp-server')
+    .parse();
+//# sourceMappingURL=discover.js.map

package/dist/cli/discover.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"discover.js","sourceRoot":"","sources":["../../src/cli/discover.ts"],"names":[],"mappings":";AACA;;GAEG;AACH,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AACxC,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAC9D,OAAO,MAAM,MAAM,QAAQ,CAAC;AAE5B,4CAA4C;AAC5C,MAAM,CAAC,MAAM,EAAE,CAAC;AAEhB;;GAEG;AACH,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;KACzB,UAAU,CAAC,gBAAgB,CAAC;KAC5B,KAAK,CAAC,iBAAiB,CAAC;KACxB,OAAO,CACN,YAAY,EACZ,mCAAmC,EACnC,CAAC,KAAK,EAAE,EAAE;IACR,OAAO,KAAK;SACT,MAAM,CAAC,QAAQ,EAAE;QAChB,KAAK,EAAE,GAAG;QACV,WAAW,EACT,kEAAkE;QACpE,IAAI,EAAE,QAAQ;KACf,CAAC;SACD,MAAM,CAAC,KAAK,EAAE;QACb,KAAK,EAAE,GAAG;QACV,WAAW,EAAE,qCAAqC;QAClD,IAAI,EAAE,SAAS;QACf,OAAO,EAAE,KAAK;KACf,CAAC;SACD,MAAM,CAAC,QAAQ,EAAE;QAChB,KAAK,EAAE,GAAG;QACV,WAAW,EAAE,kBAAkB;QAC/B,OAAO,EAAE,2BAA2B;QACpC,IAAI,EAAE,QAAQ;KACf,CAAC;SACD,MAAM,CAAC,OAAO,EAAE;QACf,KAAK,EAAE,GAAG;QACV,WAAW,EAAE,4CAA4C;QACzD,IAAI,EAAE,SAAS;QACf,OAAO,EAAE,KAAK;KACf,CAAC;SACD,MAAM,CAAC,SAAS,EAAE;QACjB,KAAK,EAAE,GAAG;QACV,WAAW,EAAE,mDAAmD;QAChE,IAAI,EAAE,QAAQ;KACf,CAAC;SACD,SAAS,CAAC,QAAQ,EAAE,KAAK,CAAC;SAC1B,KAAK,CAAC,CAAC,IAAI,EAAE,EAAE;QACd,IAAI,CAAC,IAAI,CAAC,MAAM,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC;YAC9B,MAAM,IAAI,KAAK,CAAC,2CAA2C,CAAC,CAAC;QAC/D,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC,CAAC,CAAC;AACP,CAAC,EACD,kBAAkB,CACnB;IACD;;;;;;;;;;;MAWE;KACD,aAAa,CAAC,CAAC,EAAE,sCAAsC,CAAC;KACxD,IAAI,EAAE;KACN,KAAK,CAAC,MAAM,EAAE,GAAG,CAAC;KAClB,MAAM,CAAC,qEAAqE,CAAC;KAC7E,KAAK,EAAE,CAAC"}

package/dist/errors/api-errors.d.ts

@@ -0,0 +1,191 @@
+/**
+ * Error class hierarchy for Attio API errors
+ * Includes specialized error types for API interactions and validation
+ */
+/**
+ * Base class for all Attio API errors
+ */
+export declare class AttioApiError extends Error {
+    readonly statusCode: number;
+    readonly endpoint: string;
+    readonly method: string;
+    readonly details?: any | undefined;
+    /**
+     * Create an AttioApiError
+     *
+     * @param message - Error message
+     * @param statusCode - HTTP status code
+     * @param endpoint - API endpoint that was called
+     * @param details - Additional error details
+     */
+    constructor(message: string, statusCode: number, endpoint: string, method: string, details?: any | undefined);
+    /**
+     * Get a formatted representation of the error for logging
+     */
+    toFormattedString(): string;
+}
+/**
+ * Error for authentication issues (401)
+ */
+export declare class AuthenticationError extends AttioApiError {
+    constructor(message: string | undefined, endpoint: string, method: string, details?: any);
+}
+/**
+ * Error for authorization issues (403)
+ */
+export declare class AuthorizationError extends AttioApiError {
+    constructor(message: string | undefined, endpoint: string, method: string, details?: any);
+}
+/**
+ * Error for resource not found issues (404)
+ */
+export declare class ResourceNotFoundError extends AttioApiError {
+    constructor(resourceType: string, resourceId: string, endpoint: string, method: string, details?: any);
+}
+/**
+ * Error for invalid request issues (400)
+ */
+export declare class InvalidRequestError extends AttioApiError {
+    constructor(message: string, endpoint: string, method: string, details?: any);
+}
+/**
+ * Error for rate limit issues (429)
+ */
+export declare class RateLimitError extends AttioApiError {
+    constructor(message: string | undefined, endpoint: string, method: string, details?: any);
+}
+/**
+ * Error for server-side issues (500, 502, 503, 504)
+ */
+export declare class ServerError extends AttioApiError {
+    constructor(statusCode: number, message: string | undefined, endpoint: string, method: string, details?: any);
+}
+/**
+ * Factory function to create the appropriate error type based on status code
+ *
+ * @param statusCode - HTTP status code
+ * @param message - Error message
+ * @param endpoint - API endpoint that was called
+ * @param method - HTTP method used
+ * @param details - Additional error details
+ * @returns The appropriate error instance
+ */
+export declare function createApiErrorFromStatus(statusCode: number, message: string, endpoint: string, method: string, details?: any): AttioApiError;
+/**
+ * Create an appropriate error from Axios error response
+ *
+ * @param error - The caught error
+ * @param endpoint - API endpoint that was called
+ * @param method - HTTP method used
+ * @returns The appropriate error instance
+ */
+export declare function createApiErrorFromAxiosError(error: any, endpoint: string, method: string): AttioApiError;
+/**
+ * Filter error categories for more targeted error handling
+ */
+export declare enum FilterErrorCategory {
+    STRUCTURE = "structure",// Basic structure issues (missing filters array)
+    ATTRIBUTE = "attribute",// Attribute-related issues
+    CONDITION = "condition",// Condition-related issues
+    VALUE = "value",// Value-related issues
+    TRANSFORMATION = "transformation"
+}
+/**
+ * Error class for filter validation issues
+ *
+ * Used when validating filter conditions and structures to ensure they meet
+ * the requirements of the Attio API format.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   // Validate filter conditions
+ *   if (!isValidFilterCondition(condition)) {
+ *     throw new FilterValidationError(
+ *       `Invalid filter condition: ${condition}`,
+ *       FilterErrorCategory.CONDITION
+ *     );
+ *   }
+ * } catch (error) {
+ *   if (error instanceof FilterValidationError) {
+ *     // Handle filter validation error based on category
+ *     if (error.category === FilterErrorCategory.CONDITION) {
+ *       // Handle condition-specific error
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export declare class FilterValidationError extends Error {
+    readonly category: FilterErrorCategory;
+    /**
+     * Create a new FilterValidationError
+     *
+     * @param message - Detailed error message explaining the validation issue
+     * @param category - Error category for targeted handling (default: STRUCTURE)
+     */
+    constructor(message: string, category?: FilterErrorCategory);
+}
+/**
+ * Error for relationship filter validation issues
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   if (!isValidRelationshipType(type)) {
+ *     throw new RelationshipFilterError(
+ *       `Invalid relationship type: ${type}`,
+ *       'people',
+ *       'companies'
+ *     );
+ *   }
+ * } catch (error) {
+ *   if (error instanceof RelationshipFilterError) {
+ *     // Handle relationship filter error
+ *     console.log(`Relationship error between ${error.sourceType} and ${error.targetType}`);
+ *   }
+ * }
+ * ```
+ */
+export declare class RelationshipFilterError extends FilterValidationError {
+    readonly sourceType?: string | undefined;
+    readonly targetType?: string | undefined;
+    readonly relationshipType?: string | undefined;
+    /**
+     * Create a RelationshipFilterError
+     *
+     * @param message - Error message
+     * @param sourceType - The source entity type (e.g., 'people', 'companies')
+     * @param targetType - The target entity type (e.g., 'companies', 'lists')
+     * @param relationshipType - The type of relationship that failed validation
+     */
+    constructor(message: string, sourceType?: string | undefined, targetType?: string | undefined, relationshipType?: string | undefined);
+}
+/**
+ * Error specifically for list relationship issues
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   if (!isValidListId(listId)) {
+ *     throw new ListRelationshipError(`Invalid list ID: ${listId}`, 'people', listId);
+ *   }
+ * } catch (error) {
+ *   if (error instanceof ListRelationshipError) {
+ *     // Handle list relationship error
+ *   }
+ * }
+ * ```
+ */
+export declare class ListRelationshipError extends RelationshipFilterError {
+    readonly listId?: string | undefined;
+    /**
+     * Create a ListRelationshipError
+     *
+     * @param message - Error message
+     * @param sourceType - The source entity type (e.g., 'people', 'companies')
+     * @param listId - The list ID that caused the error
+     */
+    constructor(message: string, sourceType?: string, listId?: string | undefined);
+}
+//# sourceMappingURL=api-errors.d.ts.map

package/dist/errors/api-errors.d.ts.map

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

package/dist/errors/api-errors.js

@@ -0,0 +1,305 @@
+/**
+ * Error class hierarchy for Attio API errors
+ * Includes specialized error types for API interactions and validation
+ */
+/**
+ * Base class for all Attio API errors
+ */
+export class AttioApiError extends Error {
+    statusCode;
+    endpoint;
+    method;
+    details;
+    /**
+     * Create an AttioApiError
+     *
+     * @param message - Error message
+     * @param statusCode - HTTP status code
+     * @param endpoint - API endpoint that was called
+     * @param details - Additional error details
+     */
+    constructor(message, statusCode, endpoint, method, details) {
+        super(message);
+        this.statusCode = statusCode;
+        this.endpoint = endpoint;
+        this.method = method;
+        this.details = details;
+        this.name = 'AttioApiError';
+        // This line is needed to properly capture the stack trace in derived classes
+        Object.setPrototypeOf(this, AttioApiError.prototype);
+    }
+    /**
+     * Get a formatted representation of the error for logging
+     */
+    toFormattedString() {
+        return (`${this.name} (${this.statusCode}): ${this.message}\n` +
+            `Endpoint: ${this.method} ${this.endpoint}\n` +
+            `Details: ${JSON.stringify(this.details || {}, null, 2)}`);
+    }
+}
+/**
+ * Error for authentication issues (401)
+ */
+export class AuthenticationError extends AttioApiError {
+    constructor(message = 'Authentication failed. Please check your API key.', endpoint, method, details) {
+        super(message, 401, endpoint, method, details);
+        this.name = 'AuthenticationError';
+        // This line is needed to properly capture the stack trace
+        Object.setPrototypeOf(this, AuthenticationError.prototype);
+    }
+}
+/**
+ * Error for authorization issues (403)
+ */
+export class AuthorizationError extends AttioApiError {
+    constructor(message = 'Authorization failed. Your API key lacks the necessary permissions.', endpoint, method, details) {
+        super(message, 403, endpoint, method, details);
+        this.name = 'AuthorizationError';
+        // This line is needed to properly capture the stack trace
+        Object.setPrototypeOf(this, AuthorizationError.prototype);
+    }
+}
+/**
+ * Error for resource not found issues (404)
+ */
+export class ResourceNotFoundError extends AttioApiError {
+    constructor(resourceType, resourceId, endpoint, method, details) {
+        super(`${resourceType} with ID '${resourceId}' not found`, 404, endpoint, method, details);
+        this.name = 'ResourceNotFoundError';
+        // This line is needed to properly capture the stack trace
+        Object.setPrototypeOf(this, ResourceNotFoundError.prototype);
+    }
+}
+/**
+ * Error for invalid request issues (400)
+ */
+export class InvalidRequestError extends AttioApiError {
+    constructor(message, endpoint, method, details) {
+        super(message, 400, endpoint, method, details);
+        this.name = 'InvalidRequestError';
+        // This line is needed to properly capture the stack trace
+        Object.setPrototypeOf(this, InvalidRequestError.prototype);
+    }
+}
+/**
+ * Error for rate limit issues (429)
+ */
+export class RateLimitError extends AttioApiError {
+    constructor(message = 'Rate limit exceeded. Please try again later.', endpoint, method, details) {
+        super(message, 429, endpoint, method, details);
+        this.name = 'RateLimitError';
+        // This line is needed to properly capture the stack trace
+        Object.setPrototypeOf(this, RateLimitError.prototype);
+    }
+}
+/**
+ * Error for server-side issues (500, 502, 503, 504)
+ */
+export class ServerError extends AttioApiError {
+    constructor(statusCode, message = 'Server error occurred', endpoint, method, details) {
+        super(`Server error (${statusCode}): ${message}`, statusCode, endpoint, method, details);
+        this.name = 'ServerError';
+        // This line is needed to properly capture the stack trace
+        Object.setPrototypeOf(this, ServerError.prototype);
+    }
+}
+/**
+ * Factory function to create the appropriate error type based on status code
+ *
+ * @param statusCode - HTTP status code
+ * @param message - Error message
+ * @param endpoint - API endpoint that was called
+ * @param method - HTTP method used
+ * @param details - Additional error details
+ * @returns The appropriate error instance
+ */
+export function createApiErrorFromStatus(statusCode, message, endpoint, method, details) {
+    switch (statusCode) {
+        case 400:
+            return new InvalidRequestError(message, endpoint, method, details);
+        case 401:
+            return new AuthenticationError(message, endpoint, method, details);
+        case 403:
+            return new AuthorizationError(message, endpoint, method, details);
+        case 404:
+            // This is a generic case - for specific resources, use ResourceNotFoundError constructor directly
+            return new ResourceNotFoundError('Resource', 'unknown', endpoint, method, details);
+        case 429:
+            return new RateLimitError(message, endpoint, method, details);
+        case 500:
+        case 502:
+        case 503:
+        case 504:
+            return new ServerError(statusCode, message, endpoint, method, details);
+        default:
+            return new AttioApiError(message, statusCode, endpoint, method, details);
+    }
+}
+/**
+ * Create an appropriate error from Axios error response
+ *
+ * @param error - The caught error
+ * @param endpoint - API endpoint that was called
+ * @param method - HTTP method used
+ * @returns The appropriate error instance
+ */
+export function createApiErrorFromAxiosError(error, endpoint, method) {
+    const statusCode = error.response?.status || 500;
+    const message = error.response?.data?.message || error.message || 'Unknown API error';
+    const details = error.response?.data || {};
+    // Special case for ResourceNotFoundError with object types
+    if (statusCode === 404 && endpoint.includes('/objects/')) {
+        // Extract resource type and ID from endpoint
+        // Assuming endpoint format like /objects/{type}/records/{id}
+        const matches = endpoint.match(/\/objects\/([^\/]+)\/records\/([^\/]+)/);
+        if (matches && matches.length >= 3) {
+            const [, resourceType, resourceId] = matches;
+            // Format resource type properly: 'people' -> 'Person', 'companies' -> 'Company'
+            let formattedType;
+            if (resourceType === 'people') {
+                formattedType = 'Person';
+            }
+            else if (resourceType === 'companies') {
+                formattedType = 'Company';
+            }
+            else {
+                // Default formatting for other types
+                formattedType =
+                    resourceType.charAt(0).toUpperCase() + resourceType.slice(1, -1);
+            }
+            return new ResourceNotFoundError(formattedType, resourceId, endpoint, method, details);
+        }
+    }
+    return createApiErrorFromStatus(statusCode, message, endpoint, method, details);
+}
+/**
+ * Filter error categories for more targeted error handling
+ */
+export var FilterErrorCategory;
+(function (FilterErrorCategory) {
+    FilterErrorCategory["STRUCTURE"] = "structure";
+    FilterErrorCategory["ATTRIBUTE"] = "attribute";
+    FilterErrorCategory["CONDITION"] = "condition";
+    FilterErrorCategory["VALUE"] = "value";
+    FilterErrorCategory["TRANSFORMATION"] = "transformation";
+})(FilterErrorCategory || (FilterErrorCategory = {}));
+/**
+ * Error class for filter validation issues
+ *
+ * Used when validating filter conditions and structures to ensure they meet
+ * the requirements of the Attio API format.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   // Validate filter conditions
+ *   if (!isValidFilterCondition(condition)) {
+ *     throw new FilterValidationError(
+ *       `Invalid filter condition: ${condition}`,
+ *       FilterErrorCategory.CONDITION
+ *     );
+ *   }
+ * } catch (error) {
+ *   if (error instanceof FilterValidationError) {
+ *     // Handle filter validation error based on category
+ *     if (error.category === FilterErrorCategory.CONDITION) {
+ *       // Handle condition-specific error
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export class FilterValidationError extends Error {
+    category;
+    /**
+     * Create a new FilterValidationError
+     *
+     * @param message - Detailed error message explaining the validation issue
+     * @param category - Error category for targeted handling (default: STRUCTURE)
+     */
+    constructor(message, category = FilterErrorCategory.STRUCTURE) {
+        super(message);
+        this.category = category;
+        this.name = 'FilterValidationError';
+        // This line is needed to properly capture the stack trace
+        Object.setPrototypeOf(this, FilterValidationError.prototype);
+    }
+}
+/**
+ * Error for relationship filter validation issues
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   if (!isValidRelationshipType(type)) {
+ *     throw new RelationshipFilterError(
+ *       `Invalid relationship type: ${type}`,
+ *       'people',
+ *       'companies'
+ *     );
+ *   }
+ * } catch (error) {
+ *   if (error instanceof RelationshipFilterError) {
+ *     // Handle relationship filter error
+ *     console.log(`Relationship error between ${error.sourceType} and ${error.targetType}`);
+ *   }
+ * }
+ * ```
+ */
+export class RelationshipFilterError extends FilterValidationError {
+    sourceType;
+    targetType;
+    relationshipType;
+    /**
+     * Create a RelationshipFilterError
+     *
+     * @param message - Error message
+     * @param sourceType - The source entity type (e.g., 'people', 'companies')
+     * @param targetType - The target entity type (e.g., 'companies', 'lists')
+     * @param relationshipType - The type of relationship that failed validation
+     */
+    constructor(message, sourceType, targetType, relationshipType) {
+        // Relationships are a special type of filter condition
+        super(message, FilterErrorCategory.CONDITION);
+        this.sourceType = sourceType;
+        this.targetType = targetType;
+        this.relationshipType = relationshipType;
+        this.name = 'RelationshipFilterError';
+        // This line is needed to properly capture the stack trace in derived classes
+        Object.setPrototypeOf(this, RelationshipFilterError.prototype);
+    }
+}
+/**
+ * Error specifically for list relationship issues
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   if (!isValidListId(listId)) {
+ *     throw new ListRelationshipError(`Invalid list ID: ${listId}`, 'people', listId);
+ *   }
+ * } catch (error) {
+ *   if (error instanceof ListRelationshipError) {
+ *     // Handle list relationship error
+ *   }
+ * }
+ * ```
+ */
+export class ListRelationshipError extends RelationshipFilterError {
+    listId;
+    /**
+     * Create a ListRelationshipError
+     *
+     * @param message - Error message
+     * @param sourceType - The source entity type (e.g., 'people', 'companies')
+     * @param listId - The list ID that caused the error
+     */
+    constructor(message, sourceType, listId) {
+        super(message, sourceType, 'lists', 'in_list');
+        this.listId = listId;
+        this.name = 'ListRelationshipError';
+        // This line is needed to properly capture the stack trace
+        Object.setPrototypeOf(this, ListRelationshipError.prototype);
+    }
+}
+//# sourceMappingURL=api-errors.js.map

package/dist/errors/api-errors.js.map

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

package/dist/errors/company-errors.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Domain-specific error classes for company operations
+ */
+/**
+ * Base error class for company-related errors
+ */
+export declare class CompanyError extends Error {
+    constructor(message: string);
+}
+/**
+ * Error thrown when a company is not found
+ */
+export declare class CompanyNotFoundError extends CompanyError {
+    constructor(companyId: string);
+}
+/**
+ * Error thrown when company data is invalid
+ */
+export declare class InvalidCompanyDataError extends CompanyError {
+    constructor(message: string);
+}
+/**
+ * Error thrown when a company operation fails
+ */
+export declare class CompanyOperationError extends CompanyError {
+    constructor(operation: string, companyId?: string, details?: string);
+}
+/**
+ * Error thrown when a required company field is missing
+ */
+export declare class MissingCompanyFieldError extends InvalidCompanyDataError {
+    constructor(fieldName: string);
+}
+/**
+ * Error thrown when a company field has an invalid type
+ */
+export declare class InvalidCompanyFieldTypeError extends InvalidCompanyDataError {
+    constructor(fieldName: string, expectedType: string, actualType: string);
+}
+//# sourceMappingURL=company-errors.d.ts.map

package/dist/errors/company-errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"company-errors.d.ts","sourceRoot":"","sources":["../../src/errors/company-errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;GAEG;AACH,qBAAa,YAAa,SAAQ,KAAK;gBACzB,OAAO,EAAE,MAAM;CAI5B;AAED;;GAEG;AACH,qBAAa,oBAAqB,SAAQ,YAAY;gBACxC,SAAS,EAAE,MAAM;CAI9B;AAED;;GAEG;AACH,qBAAa,uBAAwB,SAAQ,YAAY;gBAC3C,OAAO,EAAE,MAAM;CAI5B;AAED;;GAEG;AACH,qBAAa,qBAAsB,SAAQ,YAAY;gBACzC,SAAS,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM;CAUpE;AAED;;GAEG;AACH,qBAAa,wBAAyB,SAAQ,uBAAuB;gBACvD,SAAS,EAAE,MAAM;CAI9B;AAED;;GAEG;AACH,qBAAa,4BAA6B,SAAQ,uBAAuB;gBAC3D,SAAS,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM;CAMxE"}