{"id":51530994,"url":"https://github.com/rodmarzavala/gt-utils-js","last_synced_at":"2026-07-09T02:30:37.679Z","repository":{"id":355002323,"uuid":"1226372054","full_name":"rodmarzavala/gt-utils-js","owner":"rodmarzavala","description":null,"archived":false,"fork":false,"pushed_at":"2026-05-01T10:56:55.000Z","size":147,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-01T12:22:18.551Z","etag":null,"topics":["cui","departamentos","departamentos-guatemala","dpi","finance","geo","guatemala","municipios","municipios-guatemala","municipios-guatemaltecos","nit","sat"],"latest_commit_sha":null,"homepage":"https://rodmarzavala.github.io/gt-utils-js/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rodmarzavala.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-01T10:05:10.000Z","updated_at":"2026-05-01T10:56:58.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/rodmarzavala/gt-utils-js","commit_stats":null,"previous_names":["rodmarzavala/gt-utils-js"],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/rodmarzavala/gt-utils-js","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rodmarzavala%2Fgt-utils-js","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rodmarzavala%2Fgt-utils-js/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rodmarzavala%2Fgt-utils-js/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rodmarzavala%2Fgt-utils-js/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rodmarzavala","download_url":"https://codeload.github.com/rodmarzavala/gt-utils-js/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rodmarzavala%2Fgt-utils-js/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35284875,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-09T02:00:07.329Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cui","departamentos","departamentos-guatemala","dpi","finance","geo","guatemala","municipios","municipios-guatemala","municipios-guatemaltecos","nit","sat"],"created_at":"2026-07-09T02:30:37.591Z","updated_at":"2026-07-09T02:30:37.661Z","avatar_url":"https://github.com/rodmarzavala.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# gt-utils-js \n\nBiblioteca estándar sin dependencias (Zero-Dependency) y con tipado estricto (TypeScript) para validaciones y utilidades específicas de Guatemala.\n\nOptimizada para entornos Edge (Cloudflare Workers, Vercel Edge), Deno, Bun y Node.js. El código, nombres de variables y API se mantienen en inglés bajo principios de Clean Code, pero la lógica responde a la legislación y cultura de Guatemala.\n\n## Instalación\n\n```bash\nnpm install @rodmarzavala/gt-utils-js\n# o usando yarn\nyarn add @rodmarzavala/gt-utils-js\n# o usando pnpm\npnpm add @rodmarzavala/gt-utils-js\n```\n\n## Características Principales\n\nEsta biblioteca provee 7 submódulos especializados:\n\n-  **Identidad:** Validación rigurosa de NIT y CUI/DPI (Módulo 11 oficial de SAT y RENAP). Incluye la nueva disposición SAT 2025 donde los CUI válidos operan como NIT. Retorna el departamento y código de municipio emisor.\n-  **Finanzas:** Conversión de números a letras para Facturación Electrónica (FEL) y detección de bancos por número de cuenta (G\u0026T, Banrural, BI, BAM, Promerica, etc).\n-  **Vehículos:** Analizador y validador de Placas Vehiculares (comerciales, particulares, motos, y reglas estrictas del reglamento de tránsito, como exclusiones de vocales O, I, Q, Ñ).\n-  **Geografía:** Resolución Inversa Nacional: pasa coordenadas (Lat, Lng) y te dice en qué municipio y departamento de Guatemala caen (Ray-Casting algorithm ligero).\n-  **Impuestos:** Retenciones de IVA y escalonadas de ISR (Régimen General \u003e Q2,500) redondeadas al centavo contable exacto.\n-  **Feriados y Calendario:** Algoritmo astronómico para cálculo de Semana Santa, listado de asuetos, y traslados de feriados largos de acuerdo a la Ley de Promoción de Turismo Interno (Decreto 19-2018 y CC).\n-  **Laboral:** Calculadora de Liquidaciones al centavo. Determina fechas de corte y pagos proporcionales de Aguinaldo, Bono 14, Vacaciones y cálculo de indemnización por despido injustificado (regla de 14 salarios / 12 meses).\n\n## Uso Rápido\n\nLa librería expone todas sus utilidades desde el punto de entrada principal.\n\n```typescript\nimport { \n  isValidNit, \n  isValidCui, \n  getCuiInformation,\n  calculateTaxes,\n  calculateSeverance,\n  getLicensePlateInfo,\n  getHolidays,\n  findMunicipalityByLatLng,\n  amountToWords\n} from 'gt-utils-js';\n\n// 1. Identidad\nconsole.log(isValidNit('123456-0')); // true\nconsole.log(isValidCui('1234567890101')); // true\nconsole.log(getCuiInformation('1234567890101')); \n// { isValid: true, department: 'Guatemala', municipalityId: 1 }\n\n// 2. Impuestos y Facturación\nconsole.log(amountToWords(150.50)); // \"CIENTO CINCUENTA QUETZALES CON 50/100 CENTAVOS\"\nconsole.log(calculateTaxes({\n  amount: 3000,\n  regime: 'GENERAL',\n  isRetentionAgent: true,\n  currency: 'GTQ'\n})); \n// { subtotal: 2678.57, iva: 321.43, retentionIsr: 133.93, retentionIva: 48.21, totalToReceive: 2817.86 }\n\n// 3. Vehículos\nconsole.log(parseLicensePlate('P-123BCD'));\n// { isValid: true, type: 'P', number: '123', letters: 'BCD' }\n\n// 4. Laboral\nconsole.log(calculateSeverance({\n  startDate: new Date('2022-01-01'),\n  endDate: new Date('2023-12-31'),\n  monthlySalary: 6000,\n  reason: 'UNJUSTIFIED_FIRING'\n}));\n// { aguinaldo, bono14, vacations, indemnizacion: 14000, totalToReceive: 20501.37, ... }\n\n// 5. Geografía (Coordenadas -\u003e Municipio)\n// Palacio Nacional\nconsole.log(findMunicipalityByLatLng(14.643445, -90.513222));\n// { name: 'Guatemala', department: 'Guatemala' }\n\n// 6. Feriados\nconst holidays2024 = getHolidays(2024);\n// Retorna todos los asuetos incluyendo fechas móviles (ej. 30 de junio movido a lunes)\n```\n\n## Documentación Detallada\n\n- [Docs Oficiales](https://rodmarzavala.github.io/gt-utils-js) (Próximamente vía GitHub Pages)\n\n## Tests\n\nEl paquete tiene una cobertura de pruebas exhaustiva. Para ejecutar las pruebas tú mismo:\n\n```bash\npnpm install\npnpm test\n```\n\nTambién incluimos un archivo `playground.ts` que demuestra cada funcionalidad. Para correrlo:\n\n```bash\nnpx tsx src/playground.ts\n```\n\n## Licencia\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frodmarzavala%2Fgt-utils-js","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frodmarzavala%2Fgt-utils-js","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frodmarzavala%2Fgt-utils-js/lists"}