hvp-shared 3.2.1 → 3.3.0

package/dist/types/api-response.types.d.ts

@@ -153,7 +153,14 @@ export interface ApiCreatedSuccessResponse<T> extends ApiSuccessResponseBase<T>
  */
 export interface ApiErrorDetail {
     /**
-     * Error type (machine-readable)
+     * Domain-specific error code (machine-readable)
+     * Examples: "COLLABORATOR_NOT_FOUND", "INVALID_ACCESS_CODE", "DUPLICATE_EMAIL"
+     * Frontend uses this to react programmatically to specific errors
+     * See: ErrorCodes in error-codes.types.ts
+     */
+    code?: string;
+    /**
+     * Error type (machine-readable category)
      * Examples:
      * - "ValidationError" - Input validation failed
      * - "BusinessRuleError" - Domain rule violated

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

@@ -0,0 +1,124 @@
+/**
+ * Error Codes - Shared Types
+ *
+ * These error codes are used by both frontend and backend to handle
+ * domain-specific errors programmatically.
+ *
+ * Design Pattern: Error Codes + Factory Methods (Modern Pattern)
+ * - Frontend can react to specific error codes
+ * - Backend throws domain errors with these codes
+ * - Reduces boilerplate by 90% compared to one-class-per-error
+ *
+ * See: resources/learning/20260107-error-handling-architecture-complete-analysis.md
+ */
+/**
+ * HTTP Status Codes for error responses
+ */
+export declare enum HttpStatus {
+    BAD_REQUEST = 400,
+    UNAUTHORIZED = 401,
+    FORBIDDEN = 403,
+    NOT_FOUND = 404,
+    CONFLICT = 409,
+    UNPROCESSABLE_ENTITY = 422,
+    INTERNAL_SERVER_ERROR = 500
+}
+/**
+ * Domain-specific error codes
+ * Format: RESOURCE_ERROR_TYPE
+ */
+export declare const ErrorCodes: {
+    readonly COLLABORATOR_NOT_FOUND: {
+        readonly code: "COLLABORATOR_NOT_FOUND";
+        readonly status: HttpStatus.NOT_FOUND;
+        readonly defaultMessage: "Collaborator not found";
+    };
+    readonly COLLABORATOR_ALREADY_REGISTERED: {
+        readonly code: "COLLABORATOR_ALREADY_REGISTERED";
+        readonly status: HttpStatus.CONFLICT;
+        readonly defaultMessage: "Collaborator is already registered";
+    };
+    readonly COLLABORATOR_INACTIVE: {
+        readonly code: "COLLABORATOR_INACTIVE";
+        readonly status: HttpStatus.FORBIDDEN;
+        readonly defaultMessage: "Collaborator is inactive";
+    };
+    readonly CANNOT_DELETE_ACTIVE_COLLABORATOR: {
+        readonly code: "CANNOT_DELETE_ACTIVE_COLLABORATOR";
+        readonly status: HttpStatus.CONFLICT;
+        readonly defaultMessage: "Cannot delete active collaborator";
+    };
+    readonly DUPLICATE_COLLABORATOR_CODE: {
+        readonly code: "DUPLICATE_COLLABORATOR_CODE";
+        readonly status: HttpStatus.CONFLICT;
+        readonly defaultMessage: "Collaborator code already exists";
+    };
+    readonly DUPLICATE_COLLABORATOR_EMAIL: {
+        readonly code: "DUPLICATE_COLLABORATOR_EMAIL";
+        readonly status: HttpStatus.CONFLICT;
+        readonly defaultMessage: "Email is already registered";
+    };
+    readonly INVALID_ACCESS_CODE: {
+        readonly code: "INVALID_ACCESS_CODE";
+        readonly status: HttpStatus.UNAUTHORIZED;
+        readonly defaultMessage: "Invalid access code";
+    };
+    readonly ACCESS_CODE_NOT_SET: {
+        readonly code: "ACCESS_CODE_NOT_SET";
+        readonly status: HttpStatus.UNPROCESSABLE_ENTITY;
+        readonly defaultMessage: "Access code not set for collaborator";
+    };
+    readonly INVALID_FISCAL_DATA: {
+        readonly code: "INVALID_FISCAL_DATA";
+        readonly status: HttpStatus.BAD_REQUEST;
+        readonly defaultMessage: "Invalid fiscal data";
+    };
+    readonly INVALID_CREDENTIALS: {
+        readonly code: "INVALID_CREDENTIALS";
+        readonly status: HttpStatus.UNAUTHORIZED;
+        readonly defaultMessage: "Invalid credentials";
+    };
+    readonly TOKEN_EXPIRED: {
+        readonly code: "TOKEN_EXPIRED";
+        readonly status: HttpStatus.UNAUTHORIZED;
+        readonly defaultMessage: "Token has expired";
+    };
+    readonly TOKEN_INVALID: {
+        readonly code: "TOKEN_INVALID";
+        readonly status: HttpStatus.UNAUTHORIZED;
+        readonly defaultMessage: "Invalid token";
+    };
+    readonly VALIDATION_ERROR: {
+        readonly code: "VALIDATION_ERROR";
+        readonly status: HttpStatus.BAD_REQUEST;
+        readonly defaultMessage: "Validation error";
+    };
+    readonly INTERNAL_ERROR: {
+        readonly code: "INTERNAL_ERROR";
+        readonly status: HttpStatus.INTERNAL_SERVER_ERROR;
+        readonly defaultMessage: "Internal server error";
+    };
+    readonly NOT_FOUND: {
+        readonly code: "NOT_FOUND";
+        readonly status: HttpStatus.NOT_FOUND;
+        readonly defaultMessage: "Resource not found";
+    };
+    readonly UNAUTHORIZED: {
+        readonly code: "UNAUTHORIZED";
+        readonly status: HttpStatus.UNAUTHORIZED;
+        readonly defaultMessage: "Unauthorized";
+    };
+    readonly FORBIDDEN: {
+        readonly code: "FORBIDDEN";
+        readonly status: HttpStatus.FORBIDDEN;
+        readonly defaultMessage: "Forbidden";
+    };
+};
+/**
+ * Error code type (union of all error code strings)
+ */
+export type ErrorCode = (typeof ErrorCodes)[keyof typeof ErrorCodes]['code'];
+/**
+ * Error definition type
+ */
+export type ErrorDefinition = (typeof ErrorCodes)[keyof typeof ErrorCodes];

package/dist/types/error-codes.types.js

@@ -0,0 +1,132 @@
+"use strict";
+/**
+ * Error Codes - Shared Types
+ *
+ * These error codes are used by both frontend and backend to handle
+ * domain-specific errors programmatically.
+ *
+ * Design Pattern: Error Codes + Factory Methods (Modern Pattern)
+ * - Frontend can react to specific error codes
+ * - Backend throws domain errors with these codes
+ * - Reduces boilerplate by 90% compared to one-class-per-error
+ *
+ * See: resources/learning/20260107-error-handling-architecture-complete-analysis.md
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ErrorCodes = exports.HttpStatus = void 0;
+/**
+ * HTTP Status Codes for error responses
+ */
+var HttpStatus;
+(function (HttpStatus) {
+    HttpStatus[HttpStatus["BAD_REQUEST"] = 400] = "BAD_REQUEST";
+    HttpStatus[HttpStatus["UNAUTHORIZED"] = 401] = "UNAUTHORIZED";
+    HttpStatus[HttpStatus["FORBIDDEN"] = 403] = "FORBIDDEN";
+    HttpStatus[HttpStatus["NOT_FOUND"] = 404] = "NOT_FOUND";
+    HttpStatus[HttpStatus["CONFLICT"] = 409] = "CONFLICT";
+    HttpStatus[HttpStatus["UNPROCESSABLE_ENTITY"] = 422] = "UNPROCESSABLE_ENTITY";
+    HttpStatus[HttpStatus["INTERNAL_SERVER_ERROR"] = 500] = "INTERNAL_SERVER_ERROR";
+})(HttpStatus || (exports.HttpStatus = HttpStatus = {}));
+/**
+ * Domain-specific error codes
+ * Format: RESOURCE_ERROR_TYPE
+ */
+exports.ErrorCodes = {
+    // ====================================
+    // Collaborator Errors
+    // ====================================
+    COLLABORATOR_NOT_FOUND: {
+        code: 'COLLABORATOR_NOT_FOUND',
+        status: HttpStatus.NOT_FOUND,
+        defaultMessage: 'Collaborator not found',
+    },
+    COLLABORATOR_ALREADY_REGISTERED: {
+        code: 'COLLABORATOR_ALREADY_REGISTERED',
+        status: HttpStatus.CONFLICT,
+        defaultMessage: 'Collaborator is already registered',
+    },
+    COLLABORATOR_INACTIVE: {
+        code: 'COLLABORATOR_INACTIVE',
+        status: HttpStatus.FORBIDDEN,
+        defaultMessage: 'Collaborator is inactive',
+    },
+    CANNOT_DELETE_ACTIVE_COLLABORATOR: {
+        code: 'CANNOT_DELETE_ACTIVE_COLLABORATOR',
+        status: HttpStatus.CONFLICT,
+        defaultMessage: 'Cannot delete active collaborator',
+    },
+    DUPLICATE_COLLABORATOR_CODE: {
+        code: 'DUPLICATE_COLLABORATOR_CODE',
+        status: HttpStatus.CONFLICT,
+        defaultMessage: 'Collaborator code already exists',
+    },
+    DUPLICATE_COLLABORATOR_EMAIL: {
+        code: 'DUPLICATE_COLLABORATOR_EMAIL',
+        status: HttpStatus.CONFLICT,
+        defaultMessage: 'Email is already registered',
+    },
+    INVALID_ACCESS_CODE: {
+        code: 'INVALID_ACCESS_CODE',
+        status: HttpStatus.UNAUTHORIZED,
+        defaultMessage: 'Invalid access code',
+    },
+    ACCESS_CODE_NOT_SET: {
+        code: 'ACCESS_CODE_NOT_SET',
+        status: HttpStatus.UNPROCESSABLE_ENTITY,
+        defaultMessage: 'Access code not set for collaborator',
+    },
+    INVALID_FISCAL_DATA: {
+        code: 'INVALID_FISCAL_DATA',
+        status: HttpStatus.BAD_REQUEST,
+        defaultMessage: 'Invalid fiscal data',
+    },
+    // ====================================
+    // Authentication Errors
+    // ====================================
+    INVALID_CREDENTIALS: {
+        code: 'INVALID_CREDENTIALS',
+        status: HttpStatus.UNAUTHORIZED,
+        defaultMessage: 'Invalid credentials',
+    },
+    TOKEN_EXPIRED: {
+        code: 'TOKEN_EXPIRED',
+        status: HttpStatus.UNAUTHORIZED,
+        defaultMessage: 'Token has expired',
+    },
+    TOKEN_INVALID: {
+        code: 'TOKEN_INVALID',
+        status: HttpStatus.UNAUTHORIZED,
+        defaultMessage: 'Invalid token',
+    },
+    // ====================================
+    // Validation Errors
+    // ====================================
+    VALIDATION_ERROR: {
+        code: 'VALIDATION_ERROR',
+        status: HttpStatus.BAD_REQUEST,
+        defaultMessage: 'Validation error',
+    },
+    // ====================================
+    // Generic Errors
+    // ====================================
+    INTERNAL_ERROR: {
+        code: 'INTERNAL_ERROR',
+        status: HttpStatus.INTERNAL_SERVER_ERROR,
+        defaultMessage: 'Internal server error',
+    },
+    NOT_FOUND: {
+        code: 'NOT_FOUND',
+        status: HttpStatus.NOT_FOUND,
+        defaultMessage: 'Resource not found',
+    },
+    UNAUTHORIZED: {
+        code: 'UNAUTHORIZED',
+        status: HttpStatus.UNAUTHORIZED,
+        defaultMessage: 'Unauthorized',
+    },
+    FORBIDDEN: {
+        code: 'FORBIDDEN',
+        status: HttpStatus.FORBIDDEN,
+        defaultMessage: 'Forbidden',
+    },
+};

package/dist/types/error-codes.types.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/error-codes.types.test.js

@@ -0,0 +1,144 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const error_codes_types_1 = require("./error-codes.types");
+describe('ErrorCodes', () => {
+    describe('Structure', () => {
+        it('should have code, status, and defaultMessage for each error', () => {
+            Object.values(error_codes_types_1.ErrorCodes).forEach((errorDef) => {
+                expect(errorDef).toHaveProperty('code');
+                expect(errorDef).toHaveProperty('status');
+                expect(errorDef).toHaveProperty('defaultMessage');
+                expect(typeof errorDef.code).toBe('string');
+                expect(typeof errorDef.status).toBe('number');
+                expect(typeof errorDef.defaultMessage).toBe('string');
+            });
+        });
+        it('should have unique error codes', () => {
+            const codes = Object.values(error_codes_types_1.ErrorCodes).map(e => e.code);
+            const uniqueCodes = new Set(codes);
+            expect(codes.length).toBe(uniqueCodes.size);
+        });
+        it('should have valid HTTP status codes', () => {
+            Object.values(error_codes_types_1.ErrorCodes).forEach((errorDef) => {
+                expect(errorDef.status).toBeGreaterThanOrEqual(400);
+                expect(errorDef.status).toBeLessThan(600);
+            });
+        });
+    });
+    describe('Collaborator Errors', () => {
+        it('should have COLLABORATOR_NOT_FOUND with 404 status', () => {
+            expect(error_codes_types_1.ErrorCodes.COLLABORATOR_NOT_FOUND.code).toBe('COLLABORATOR_NOT_FOUND');
+            expect(error_codes_types_1.ErrorCodes.COLLABORATOR_NOT_FOUND.status).toBe(error_codes_types_1.HttpStatus.NOT_FOUND);
+            expect(error_codes_types_1.ErrorCodes.COLLABORATOR_NOT_FOUND.defaultMessage).toBeTruthy();
+        });
+        it('should have COLLABORATOR_ALREADY_REGISTERED with 409 status', () => {
+            expect(error_codes_types_1.ErrorCodes.COLLABORATOR_ALREADY_REGISTERED.code).toBe('COLLABORATOR_ALREADY_REGISTERED');
+            expect(error_codes_types_1.ErrorCodes.COLLABORATOR_ALREADY_REGISTERED.status).toBe(error_codes_types_1.HttpStatus.CONFLICT);
+        });
+        it('should have INVALID_ACCESS_CODE with 401 status', () => {
+            expect(error_codes_types_1.ErrorCodes.INVALID_ACCESS_CODE.code).toBe('INVALID_ACCESS_CODE');
+            expect(error_codes_types_1.ErrorCodes.INVALID_ACCESS_CODE.status).toBe(error_codes_types_1.HttpStatus.UNAUTHORIZED);
+        });
+        it('should have DUPLICATE_COLLABORATOR_CODE with 409 status', () => {
+            expect(error_codes_types_1.ErrorCodes.DUPLICATE_COLLABORATOR_CODE.code).toBe('DUPLICATE_COLLABORATOR_CODE');
+            expect(error_codes_types_1.ErrorCodes.DUPLICATE_COLLABORATOR_CODE.status).toBe(error_codes_types_1.HttpStatus.CONFLICT);
+        });
+        it('should have DUPLICATE_COLLABORATOR_EMAIL with 409 status', () => {
+            expect(error_codes_types_1.ErrorCodes.DUPLICATE_COLLABORATOR_EMAIL.code).toBe('DUPLICATE_COLLABORATOR_EMAIL');
+            expect(error_codes_types_1.ErrorCodes.DUPLICATE_COLLABORATOR_EMAIL.status).toBe(error_codes_types_1.HttpStatus.CONFLICT);
+        });
+        it('should have INVALID_FISCAL_DATA with 400 status', () => {
+            expect(error_codes_types_1.ErrorCodes.INVALID_FISCAL_DATA.code).toBe('INVALID_FISCAL_DATA');
+            expect(error_codes_types_1.ErrorCodes.INVALID_FISCAL_DATA.status).toBe(error_codes_types_1.HttpStatus.BAD_REQUEST);
+        });
+    });
+    describe('Authentication Errors', () => {
+        it('should have INVALID_CREDENTIALS with 401 status', () => {
+            expect(error_codes_types_1.ErrorCodes.INVALID_CREDENTIALS.code).toBe('INVALID_CREDENTIALS');
+            expect(error_codes_types_1.ErrorCodes.INVALID_CREDENTIALS.status).toBe(error_codes_types_1.HttpStatus.UNAUTHORIZED);
+        });
+        it('should have TOKEN_EXPIRED with 401 status', () => {
+            expect(error_codes_types_1.ErrorCodes.TOKEN_EXPIRED.code).toBe('TOKEN_EXPIRED');
+            expect(error_codes_types_1.ErrorCodes.TOKEN_EXPIRED.status).toBe(error_codes_types_1.HttpStatus.UNAUTHORIZED);
+        });
+    });
+    describe('Generic Errors', () => {
+        it('should have NOT_FOUND with 404 status', () => {
+            expect(error_codes_types_1.ErrorCodes.NOT_FOUND.code).toBe('NOT_FOUND');
+            expect(error_codes_types_1.ErrorCodes.NOT_FOUND.status).toBe(error_codes_types_1.HttpStatus.NOT_FOUND);
+        });
+        it('should have INTERNAL_ERROR with 500 status', () => {
+            expect(error_codes_types_1.ErrorCodes.INTERNAL_ERROR.code).toBe('INTERNAL_ERROR');
+            expect(error_codes_types_1.ErrorCodes.INTERNAL_ERROR.status).toBe(error_codes_types_1.HttpStatus.INTERNAL_SERVER_ERROR);
+        });
+    });
+});
+describe('ErrorCode Type', () => {
+    it('should allow valid error code strings', () => {
+        const validCode = 'COLLABORATOR_NOT_FOUND';
+        expect(validCode).toBe('COLLABORATOR_NOT_FOUND');
+    });
+    it('should be a union of all error code strings', () => {
+        // Type test - this compiles if ErrorCode includes these
+        const codes = [
+            'COLLABORATOR_NOT_FOUND',
+            'INVALID_ACCESS_CODE',
+            'DUPLICATE_COLLABORATOR_EMAIL',
+            'INVALID_CREDENTIALS',
+            'NOT_FOUND',
+        ];
+        expect(codes.length).toBe(5);
+    });
+});
+describe('ErrorDefinition Type', () => {
+    it('should match the structure of error definitions', () => {
+        const errorDef = {
+            code: 'COLLABORATOR_NOT_FOUND',
+            status: 404,
+            defaultMessage: 'Collaborator not found',
+        };
+        expect(errorDef.code).toBe('COLLABORATOR_NOT_FOUND');
+        expect(errorDef.status).toBe(404);
+        expect(errorDef.defaultMessage).toBe('Collaborator not found');
+    });
+});
+describe('HttpStatus Enum', () => {
+    it('should have correct HTTP status code values', () => {
+        expect(error_codes_types_1.HttpStatus.BAD_REQUEST).toBe(400);
+        expect(error_codes_types_1.HttpStatus.UNAUTHORIZED).toBe(401);
+        expect(error_codes_types_1.HttpStatus.FORBIDDEN).toBe(403);
+        expect(error_codes_types_1.HttpStatus.NOT_FOUND).toBe(404);
+        expect(error_codes_types_1.HttpStatus.CONFLICT).toBe(409);
+        expect(error_codes_types_1.HttpStatus.UNPROCESSABLE_ENTITY).toBe(422);
+        expect(error_codes_types_1.HttpStatus.INTERNAL_SERVER_ERROR).toBe(500);
+    });
+});
+describe('Usage Examples', () => {
+    it('should be usable for error handling', () => {
+        // Simulate backend usage
+        const errorDefinition = error_codes_types_1.ErrorCodes.COLLABORATOR_NOT_FOUND;
+        const response = {
+            ok: false,
+            status_code: errorDefinition.status,
+            error: {
+                code: errorDefinition.code,
+                message: errorDefinition.defaultMessage,
+            },
+        };
+        expect(response.status_code).toBe(404);
+        expect(response.error.code).toBe('COLLABORATOR_NOT_FOUND');
+    });
+    it('should be usable for frontend error detection', () => {
+        // Simulate frontend usage
+        const apiResponse = {
+            ok: false,
+            error: {
+                code: 'COLLABORATOR_NOT_FOUND',
+            },
+        };
+        if (apiResponse.error.code === error_codes_types_1.ErrorCodes.COLLABORATOR_NOT_FOUND.code) {
+            // Frontend can react specifically to this error
+            expect(true).toBe(true);
+        }
+    });
+});

package/dist/types/index.d.ts

@@ -5,3 +5,4 @@
 export * from './api-response.types';
 export * from './company-settings.types';
 export * from './collaborator-fiscal.types';
+export * from './error-codes.types';

package/dist/types/index.js

@@ -21,3 +21,4 @@ Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./api-response.types"), exports);
 __exportStar(require("./company-settings.types"), exports);
 __exportStar(require("./collaborator-fiscal.types"), exports);
+__exportStar(require("./error-codes.types"), exports);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hvp-shared",
-  "version": "3.2.1",
+  "version": "3.3.0",
   "description": "Shared types and utilities for HVP backend and frontend",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",