hvp-shared 2.0.0

package/README.md

@@ -0,0 +1,36 @@
+# hvp2021-shared
+
+Shared types, constants, and utilities for HVP2021 backend and frontend.
+
+## Installation
+
+```bash
+npm install hvp2021-shared
+```
+
+## Usage
+
+```typescript
+import { ApiResponse, SimplePayroll, APP_NAME, UMA_2024_DAILY } from 'hvp2021-shared';
+
+const response: ApiResponse<SimplePayroll> = {
+  ok: true,
+  data: {
+    id: '123',
+    employeeId: '456',
+    amount: UMA_2024_DAILY * 15
+  }
+};
+
+console.log(APP_NAME); // 'HVP2021'
+```
+
+## Development
+
+```bash
+# Build
+npm run build
+
+# Publish
+npm publish
+```

package/dist/constants/mexican-states.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Mexican States - Official INEGI codes
+ * Used for address validation
+ */
+export declare const MEXICAN_STATES: {
+    readonly AGS: "Aguascalientes";
+    readonly BC: "Baja California";
+    readonly BCS: "Baja California Sur";
+    readonly CAMP: "Campeche";
+    readonly CHIS: "Chiapas";
+    readonly CHIH: "Chihuahua";
+    readonly COAH: "Coahuila";
+    readonly COL: "Colima";
+    readonly CDMX: "Ciudad de México";
+    readonly DGO: "Durango";
+    readonly GTO: "Guanajuato";
+    readonly GRO: "Guerrero";
+    readonly HGO: "Hidalgo";
+    readonly JAL: "Jalisco";
+    readonly MEX: "Estado de México";
+    readonly MICH: "Michoacán";
+    readonly MOR: "Morelos";
+    readonly NAY: "Nayarit";
+    readonly NL: "Nuevo León";
+    readonly OAX: "Oaxaca";
+    readonly PUE: "Puebla";
+    readonly QRO: "Querétaro";
+    readonly QROO: "Quintana Roo";
+    readonly SLP: "San Luis Potosí";
+    readonly SIN: "Sinaloa";
+    readonly SON: "Sonora";
+    readonly TAB: "Tabasco";
+    readonly TAMPS: "Tamaulipas";
+    readonly TLAX: "Tlaxcala";
+    readonly VER: "Veracruz";
+    readonly YUC: "Yucatán";
+    readonly ZAC: "Zacatecas";
+};
+export type MexicanStateCode = keyof typeof MEXICAN_STATES;
+export declare const MEXICAN_STATES_ARRAY: {
+    code: MexicanStateCode;
+    name: "Aguascalientes" | "Baja California" | "Baja California Sur" | "Campeche" | "Chiapas" | "Chihuahua" | "Coahuila" | "Colima" | "Ciudad de México" | "Durango" | "Guanajuato" | "Guerrero" | "Hidalgo" | "Jalisco" | "Estado de México" | "Michoacán" | "Morelos" | "Nayarit" | "Nuevo León" | "Oaxaca" | "Puebla" | "Querétaro" | "Quintana Roo" | "San Luis Potosí" | "Sinaloa" | "Sonora" | "Tabasco" | "Tamaulipas" | "Tlaxcala" | "Veracruz" | "Yucatán" | "Zacatecas";
+}[];

package/dist/constants/mexican-states.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MEXICAN_STATES_ARRAY = exports.MEXICAN_STATES = void 0;
+/**
+ * Mexican States - Official INEGI codes
+ * Used for address validation
+ */
+exports.MEXICAN_STATES = {
+    AGS: 'Aguascalientes',
+    BC: 'Baja California',
+    BCS: 'Baja California Sur',
+    CAMP: 'Campeche',
+    CHIS: 'Chiapas',
+    CHIH: 'Chihuahua',
+    COAH: 'Coahuila',
+    COL: 'Colima',
+    CDMX: 'Ciudad de México',
+    DGO: 'Durango',
+    GTO: 'Guanajuato',
+    GRO: 'Guerrero',
+    HGO: 'Hidalgo',
+    JAL: 'Jalisco',
+    MEX: 'Estado de México',
+    MICH: 'Michoacán',
+    MOR: 'Morelos',
+    NAY: 'Nayarit',
+    NL: 'Nuevo León',
+    OAX: 'Oaxaca',
+    PUE: 'Puebla',
+    QRO: 'Querétaro',
+    QROO: 'Quintana Roo',
+    SLP: 'San Luis Potosí',
+    SIN: 'Sinaloa',
+    SON: 'Sonora',
+    TAB: 'Tabasco',
+    TAMPS: 'Tamaulipas',
+    TLAX: 'Tlaxcala',
+    VER: 'Veracruz',
+    YUC: 'Yucatán',
+    ZAC: 'Zacatecas'
+};
+// Helper array for frontend dropdowns
+exports.MEXICAN_STATES_ARRAY = Object.entries(exports.MEXICAN_STATES).map(([code, name]) => ({
+    code: code,
+    name
+}));

package/dist/constants.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Shared constants for HVP2021
+ */
+export declare const APP_NAME = "HVP2021";
+export declare const VERSION = "1.0.0";
+export declare const UMA_2024_DAILY = 108.57;
+export * from './constants/mexican-states';

package/dist/constants.js

@@ -0,0 +1,33 @@
+"use strict";
+/**
+ * Shared constants for HVP2021
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UMA_2024_DAILY = exports.VERSION = exports.APP_NAME = void 0;
+// ============================================================================
+// Application Constants
+// ============================================================================
+exports.APP_NAME = 'HVP2021';
+exports.VERSION = '1.0.0';
+// ============================================================================
+// Mexican Tax Constants (updated annually)
+// ============================================================================
+exports.UMA_2024_DAILY = 108.57;
+// ============================================================================
+// Mexican Geographic Data
+// ============================================================================
+__exportStar(require("./constants/mexican-states"), exports);

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * HVP2021 Shared Library
+ * Shared types and constants between backend and frontend
+ */
+export * from './types';
+export * from './constants';
+export * from './validation';

package/dist/index.js

@@ -0,0 +1,23 @@
+"use strict";
+/**
+ * HVP2021 Shared Library
+ * Shared types and constants between backend and frontend
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./types"), exports);
+__exportStar(require("./constants"), exports);
+__exportStar(require("./validation"), exports);

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

@@ -0,0 +1,322 @@
+/**
+ * API Response Types - Industry Best Practices
+ *
+ * LEARNING POINTS:
+ *
+ * 1. **Discriminated Unions**:
+ *    - TypeScript can narrow types based on discriminant field (`ok`)
+ *    - if (response.ok) → TypeScript knows it's ApiSuccessResponse
+ *    - if (!response.ok) → TypeScript knows it's ApiErrorResponse
+ *
+ * 2. **Base Types + Extensions**:
+ *    - Common fields in base interface
+ *    - Specific fields in extended interfaces
+ *    - Keeps code DRY and maintainable
+ *
+ * 3. **Type Safety**:
+ *    - No runtime checks needed for type narrowing
+ *    - Compiler prevents accessing wrong fields
+ *    - Example: Can't access response.data on error response
+ *
+ * 4. **Industry Standards**:
+ *    - Based on JSON:API, REST best practices
+ *    - Similar to what Google, Stripe, GitHub use
+ *    - Extensible for future needs (versioning, etc.)
+ */
+/**
+ * Base interface for ALL API responses
+ * Contains fields that are ALWAYS present regardless of success/error
+ */
+interface ApiResponseBase {
+    /**
+     * HTTP status code (200, 201, 400, 404, 500, etc.)
+     * Mirrors the HTTP response status for consistency
+     */
+    status_code: number;
+    /**
+     * Human-readable status string
+     * Examples: "OK", "CREATED", "BAD_REQUEST", "NOT_FOUND", "INTERNAL_ERROR"
+     */
+    status: string;
+    /**
+     * Resource being operated on
+     * Examples: "company-settings", "collaborator", "payroll"
+     * Useful for logging, debugging, and client-side routing
+     */
+    resource: string;
+    /**
+     * Operation being performed
+     * Examples: "get", "list", "create", "update", "delete"
+     */
+    operation: string;
+    /**
+     * Timestamp when response was generated (ISO 8601)
+     * Useful for debugging, caching, and audit logs
+     */
+    timestamp: string;
+}
+/**
+ * Base success response
+ * Used when operation succeeds
+ */
+interface ApiSuccessResponseBase<T> extends ApiResponseBase {
+    /**
+     * Discriminant field - indicates success
+     * TypeScript uses this for type narrowing
+     */
+    ok: true;
+    /**
+     * The actual data returned by the API
+     * Type T is the domain data (e.g., CompanySettingsResponse)
+     */
+    data: T;
+    /**
+     * Optional message for user feedback
+     * Examples: "Settings updated successfully", "Collaborator created"
+     */
+    message?: string;
+}
+/**
+ * Success response for SINGLE resource (GET /resource/:id, PUT, PATCH)
+ *
+ * Used for:
+ * - GET /api/company-settings (singleton)
+ * - GET /api/collaborators/:id
+ * - PUT /api/company-settings
+ *
+ * No pagination metadata needed
+ */
+export interface ApiSingleSuccessResponse<T> extends ApiSuccessResponseBase<T> {
+}
+/**
+ * Success response for LIST of resources (GET /resources)
+ *
+ * Used for:
+ * - GET /api/collaborators
+ * - GET /api/payrolls
+ *
+ * Includes pagination metadata and navigation links
+ */
+export interface ApiListSuccessResponse<T> extends ApiSuccessResponseBase<T[]> {
+    /**
+     * Pagination metadata
+     * Helps frontend build pagination UI
+     */
+    meta: {
+        /** Total number of items across all pages */
+        total: number;
+        /** Number of items in current response */
+        itemsOnPage: number;
+        /** Current page number (1-indexed) */
+        page: number;
+        /** Items per page limit */
+        limit: number;
+        /** Total number of pages */
+        totalPages: number;
+    };
+    /**
+     * HATEOAS-style navigation links
+     * Makes API self-documenting and easier to navigate
+     */
+    links: {
+        /** URL to current page (for reference/caching) */
+        current: string;
+        /** URL to first page (optional - only if not on first page) */
+        first?: string;
+        /** URL to previous page (optional - only if not on first page) */
+        prev?: string;
+        /** URL to next page (optional - only if not on last page) */
+        next?: string;
+        /** URL to last page (optional - only if not on last page) */
+        last?: string;
+    };
+}
+/**
+ * Success response for resource CREATION (POST)
+ *
+ * Used for:
+ * - POST /api/collaborators
+ * - POST /api/payrolls
+ *
+ * Returns 201 status and location header info
+ */
+export interface ApiCreatedSuccessResponse<T> extends ApiSuccessResponseBase<T> {
+    /**
+     * URL to the newly created resource
+     * Follows REST convention of returning location
+     */
+    location: string;
+}
+/**
+ * Error detail object
+ * Provides structured information about what went wrong
+ */
+export interface ApiErrorDetail {
+    /**
+     * Error type (machine-readable)
+     * Examples:
+     * - "ValidationError" - Input validation failed
+     * - "BusinessRuleError" - Domain rule violated
+     * - "NotFoundError" - Resource doesn't exist
+     * - "UnauthorizedError" - Authentication required
+     * - "ForbiddenError" - Insufficient permissions
+     * - "ConflictError" - Resource state conflict
+     * - "InternalError" - Server error
+     */
+    type: string;
+    /**
+     * Error message (human-readable, in Spanish for UI)
+     * Example: "El RFC es inválido. Debe tener 12 o 13 caracteres."
+     */
+    message: string;
+    /**
+     * Additional error details (optional)
+     *
+     * For ValidationError:
+     * {
+     *   field: "rfc",
+     *   constraint: "matches",
+     *   expected: "XXX######XXX",
+     *   received: "invalid"
+     * }
+     *
+     * For BusinessRuleError:
+     * {
+     *   rule: "cannot_delete_active_employment",
+     *   reason: "Employment is currently active"
+     * }
+     *
+     * Type: unknown (requires type checking before use)
+     * Frontend must validate/cast before accessing properties
+     */
+    details?: unknown;
+    /**
+     * Reference ID for tracking/logging (optional)
+     * Useful for debugging - user can provide this to support
+     * Example: "err_2024_01_02_a3f5k9"
+     */
+    ref?: string;
+    /**
+     * Stack trace (only in development mode, never in production)
+     */
+    stack?: string;
+}
+/**
+ * Error response
+ * Used when operation fails
+ */
+export interface ApiErrorResponse extends ApiResponseBase {
+    /**
+     * Discriminant field - indicates error
+     * TypeScript uses this for type narrowing
+     */
+    ok: false;
+    /**
+     * Structured error information
+     */
+    error: ApiErrorDetail;
+}
+/**
+ * Main API Response type - Discriminated Union
+ *
+ * This is what you should use in your code:
+ *
+ * ```typescript
+ * const response: ApiResponse<CompanySettingsResponse> = await fetch(...);
+ *
+ * if (response.ok) {
+ *   // TypeScript knows: response is ApiSingleSuccessResponse<CompanySettingsResponse>
+ *   console.log(response.data.rfc);
+ * } else {
+ *   // TypeScript knows: response is ApiErrorResponse
+ *   console.error(response.error.message);
+ * }
+ * ```
+ *
+ * For lists:
+ * ```typescript
+ * const response: ApiListResponse<Collaborator> = await fetch(...);
+ *
+ * if (response.ok) {
+ *   // TypeScript knows: response is ApiListSuccessResponse<Collaborator>
+ *   console.log(response.meta.total);
+ *   console.log(response.data.length);
+ * }
+ * ```
+ */
+export type ApiResponse<T> = ApiSingleSuccessResponse<T> | ApiErrorResponse;
+/**
+ * Convenience type for list responses
+ */
+export type ApiListResponse<T> = ApiListSuccessResponse<T> | ApiErrorResponse;
+/**
+ * Convenience type for creation responses
+ */
+export type ApiCreatedResponse<T> = ApiCreatedSuccessResponse<T> | ApiErrorResponse;
+/**
+ * Helper for building success responses
+ * Used in controllers/services to construct consistent responses
+ */
+export type ApiSuccessResponseParams<T> = {
+    status_code: number;
+    status: string;
+    resource: string;
+    operation: string;
+    data: T;
+    message?: string;
+};
+/**
+ * Helper for building list success responses
+ */
+export type ApiListSuccessResponseParams<T> = ApiSuccessResponseParams<T[]> & {
+    meta: ApiListSuccessResponse<T>['meta'];
+    links: ApiListSuccessResponse<T>['links'];
+};
+/**
+ * Helper for building created responses
+ */
+export type ApiCreatedSuccessResponseParams<T> = ApiSuccessResponseParams<T> & {
+    location: string;
+};
+/**
+ * Helper for building error responses
+ */
+export type ApiErrorResponseParams = {
+    status_code: number;
+    status: string;
+    resource: string;
+    operation: string;
+    error: ApiErrorDetail;
+};
+/**
+ * Standard HTTP status strings
+ * Use these for consistency across the API
+ */
+export declare const API_STATUS: {
+    readonly OK: "OK";
+    readonly CREATED: "CREATED";
+    readonly ACCEPTED: "ACCEPTED";
+    readonly NO_CONTENT: "NO_CONTENT";
+    readonly BAD_REQUEST: "BAD_REQUEST";
+    readonly UNAUTHORIZED: "UNAUTHORIZED";
+    readonly FORBIDDEN: "FORBIDDEN";
+    readonly NOT_FOUND: "NOT_FOUND";
+    readonly CONFLICT: "CONFLICT";
+    readonly UNPROCESSABLE_ENTITY: "UNPROCESSABLE_ENTITY";
+    readonly INTERNAL_ERROR: "INTERNAL_ERROR";
+    readonly SERVICE_UNAVAILABLE: "SERVICE_UNAVAILABLE";
+};
+/**
+ * Standard error types
+ * Use these for consistency in error handling
+ */
+export declare const ERROR_TYPES: {
+    readonly VALIDATION_ERROR: "ValidationError";
+    readonly BUSINESS_RULE_ERROR: "BusinessRuleError";
+    readonly NOT_FOUND_ERROR: "NotFoundError";
+    readonly UNAUTHORIZED_ERROR: "UnauthorizedError";
+    readonly FORBIDDEN_ERROR: "ForbiddenError";
+    readonly CONFLICT_ERROR: "ConflictError";
+    readonly INTERNAL_ERROR: "InternalError";
+};
+export {};

package/dist/types/api-response.types.js

@@ -0,0 +1,65 @@
+"use strict";
+/**
+ * API Response Types - Industry Best Practices
+ *
+ * LEARNING POINTS:
+ *
+ * 1. **Discriminated Unions**:
+ *    - TypeScript can narrow types based on discriminant field (`ok`)
+ *    - if (response.ok) → TypeScript knows it's ApiSuccessResponse
+ *    - if (!response.ok) → TypeScript knows it's ApiErrorResponse
+ *
+ * 2. **Base Types + Extensions**:
+ *    - Common fields in base interface
+ *    - Specific fields in extended interfaces
+ *    - Keeps code DRY and maintainable
+ *
+ * 3. **Type Safety**:
+ *    - No runtime checks needed for type narrowing
+ *    - Compiler prevents accessing wrong fields
+ *    - Example: Can't access response.data on error response
+ *
+ * 4. **Industry Standards**:
+ *    - Based on JSON:API, REST best practices
+ *    - Similar to what Google, Stripe, GitHub use
+ *    - Extensible for future needs (versioning, etc.)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ERROR_TYPES = exports.API_STATUS = void 0;
+// ============================================================================
+// COMMON STATUS STRINGS (Optional - for consistency)
+// ============================================================================
+/**
+ * Standard HTTP status strings
+ * Use these for consistency across the API
+ */
+exports.API_STATUS = {
+    // 2xx Success
+    OK: 'OK',
+    CREATED: 'CREATED',
+    ACCEPTED: 'ACCEPTED',
+    NO_CONTENT: 'NO_CONTENT',
+    // 4xx Client Errors
+    BAD_REQUEST: 'BAD_REQUEST',
+    UNAUTHORIZED: 'UNAUTHORIZED',
+    FORBIDDEN: 'FORBIDDEN',
+    NOT_FOUND: 'NOT_FOUND',
+    CONFLICT: 'CONFLICT',
+    UNPROCESSABLE_ENTITY: 'UNPROCESSABLE_ENTITY',
+    // 5xx Server Errors
+    INTERNAL_ERROR: 'INTERNAL_ERROR',
+    SERVICE_UNAVAILABLE: 'SERVICE_UNAVAILABLE'
+};
+/**
+ * Standard error types
+ * Use these for consistency in error handling
+ */
+exports.ERROR_TYPES = {
+    VALIDATION_ERROR: 'ValidationError',
+    BUSINESS_RULE_ERROR: 'BusinessRuleError',
+    NOT_FOUND_ERROR: 'NotFoundError',
+    UNAUTHORIZED_ERROR: 'UnauthorizedError',
+    FORBIDDEN_ERROR: 'ForbiddenError',
+    CONFLICT_ERROR: 'ConflictError',
+    INTERNAL_ERROR: 'InternalError'
+};

package/dist/types/company-settings.types.d.ts

@@ -0,0 +1,51 @@
+import { MexicanStateCode } from '../constants/mexican-states';
+/**
+ * API Contract: GET /api/company-settings
+ *
+ * This is the shape of data that travels over HTTP.
+ * NOT a domain entity - just a data transfer contract.
+ */
+export interface CompanySettingsResponse {
+    rfc: string;
+    businessName: string;
+    taxRegime: string;
+    street: string;
+    exteriorNumber: string;
+    interiorNumber?: string;
+    neighborhood: string;
+    city: string;
+    state: MexicanStateCode;
+    zipCode: string;
+    country: string;
+    email: string;
+    phone?: string;
+    facturamaApiKey?: string;
+    facturamaApiSecret?: string;
+    facturamaUseSandbox: boolean;
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * API Contract: PUT /api/company-settings
+ *
+ * Request body for updating company settings.
+ * Similar to Response but without metadata fields.
+ */
+export interface UpdateCompanySettingsRequest {
+    rfc: string;
+    businessName: string;
+    taxRegime: string;
+    street: string;
+    exteriorNumber: string;
+    interiorNumber?: string;
+    neighborhood: string;
+    city: string;
+    state: MexicanStateCode;
+    zipCode: string;
+    country: string;
+    email: string;
+    phone?: string;
+    facturamaApiKey?: string;
+    facturamaApiSecret?: string;
+    facturamaUseSandbox: boolean;
+}

package/dist/types/company-settings.types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/types.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Shared types for HVP2021
+ * Used by both backend and frontend for type consistency
+ */
+export * from './types/api-response.types';
+export * from './types/company-settings.types';

package/dist/types.js

@@ -0,0 +1,28 @@
+"use strict";
+/**
+ * Shared types for HVP2021
+ * Used by both backend and frontend for type consistency
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+// ============================================================================
+// API Response Types - Standardized format for all endpoints
+// ============================================================================
+__exportStar(require("./types/api-response.types"), exports);
+// ============================================================================
+// Domain Types - Business entities and DTOs
+// ============================================================================
+__exportStar(require("./types/company-settings.types"), exports);

package/dist/validation/__tests__/address.validation.test.d.ts

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