{"id":47257340,"url":"https://github.com/emisso-ai/emisso-payroll","last_synced_at":"2026-04-01T19:09:02.138Z","repository":{"id":344087505,"uuid":"1180375769","full_name":"emisso-ai/emisso-payroll","owner":"emisso-ai","description":"Chilean payroll calculation engine — AFP, health, tax, unemployment, Previred, finiquito","archived":false,"fork":false,"pushed_at":"2026-03-17T02:59:09.000Z","size":275,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-17T14:20:09.964Z","etag":null,"topics":["afp","chile","latam","open-source","payroll","previred","remuneraciones","sdk","typescript"],"latest_commit_sha":null,"homepage":null,"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/emisso-ai.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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-03-13T01:24:39.000Z","updated_at":"2026-03-17T02:57:55.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/emisso-ai/emisso-payroll","commit_stats":null,"previous_names":["emisso-ai/emisso-payroll"],"tags_count":26,"template":false,"template_full_name":null,"purl":"pkg:github/emisso-ai/emisso-payroll","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emisso-ai%2Femisso-payroll","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emisso-ai%2Femisso-payroll/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emisso-ai%2Femisso-payroll/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emisso-ai%2Femisso-payroll/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/emisso-ai","download_url":"https://codeload.github.com/emisso-ai/emisso-payroll/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emisso-ai%2Femisso-payroll/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31291088,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T13:12:26.723Z","status":"ssl_error","status_checked_at":"2026-04-01T13:12:25.102Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["afp","chile","latam","open-source","payroll","previred","remuneraciones","sdk","typescript"],"created_at":"2026-03-14T19:59:40.957Z","updated_at":"2026-04-01T19:09:02.131Z","avatar_url":"https://github.com/emisso-ai.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# @emisso/payroll-cl\n\nChilean payroll calculation engine — AFP, health insurance, income tax, unemployment, gratification, family allowance, pension reform (Law 21.720), finiquito, and Previred DDJJ file generation.\n\n## When to Use This\n\n- You need to **calculate Chilean payroll** (sueldos, remuneraciones) in a TypeScript/Node.js application\n- You want to **generate Previred DDJJ files** for monthly social security declarations\n- You need **finiquito (severance) calculations** including indemnización por años de servicio and unused vacation\n- You want a **net-to-gross reverse solver** — \"I want to pay 1.2M líquido, what's the gross?\"\n- You're building an **HR/payroll SaaS** for Chilean companies and need a calculation engine with a self-hosted API\n- You need to handle **AFP, Fonasa/Isapre, income tax, unemployment insurance, gratification**, and all Chilean payroll rules in code\n\n## Packages\n\n| Package | Description | Install |\n|---------|-------------|---------|\n| `@emisso/payroll-cl` | Pure calculation engine (zero I/O) | `npm install @emisso/payroll-cl` |\n| `@emisso/payroll-api` | Full-stack API layer (Drizzle + Effect) | `npm install @emisso/payroll-api` |\n| `@emisso/payroll-cli` | Command-line interface | `npm install -g @emisso/payroll-cli` |\n\n## Quick Start — Engine\n\n```bash\nnpm install @emisso/payroll-cl\n```\n\n```typescript\nimport {\n  calculateEmployeePayroll,\n  DEFAULT_REFERENCE_DATA,\n} from \"@emisso/payroll-cl\";\n\nconst result = calculateEmployeePayroll(\n  {\n    employeeId: \"1\",\n    rut: \"12.345.678-9\",\n    firstName: \"Juan\",\n    lastName: \"Pérez\",\n    baseSalary: 1_500_000,\n    gratificationType: \"legal\",\n    colacion: 50_000,\n    movilizacion: 30_000,\n    afpCode: \"habitat\",\n    afpFund: \"b\",\n    healthPlan: \"fonasa\",\n    familyAllowanceLoads: 2,\n    contractType: \"indefinido\",\n    earnings: [],\n    deductions: [],\n  },\n  DEFAULT_REFERENCE_DATA\n);\n\nconsole.log(result.netPay);          // Líquido a pagar\nconsole.log(result.deductions.afp);  // AFP deduction\nconsole.log(result.employerCosts);   // Employer cost breakdown\n```\n\n\u003e `DEFAULT_REFERENCE_DATA` uses Feb 2026 values. For production, fetch live indicators:\n\u003e\n\u003e ```typescript\n\u003e import { fetchCurrentIndicators } from \"@emisso/payroll-cl/providers\";\n\u003e const indicators = await fetchCurrentIndicators();\n\u003e ```\n\n### Batch Payroll\n\n```typescript\nimport { calculatePayroll, DEFAULT_REFERENCE_DATA } from \"@emisso/payroll-cl\";\n\nconst results = await calculatePayroll({\n  employees: [employee1, employee2, employee3],\n  referenceData: DEFAULT_REFERENCE_DATA,\n  periodYear: 2026,\n  periodMonth: 3,\n});\n```\n\n### Previred File\n\n```typescript\nimport { generatePreviredFile, validatePreviredData } from \"@emisso/payroll-cl\";\n\nconst errors = validatePreviredData(previredData);\nif (errors.length === 0) {\n  const fileContent = generatePreviredFile(previredData);\n  // Write to .txt for upload to previred.com\n}\n```\n\n### Net-to-Gross\n\n```typescript\nimport { calculateNetToGross, DEFAULT_REFERENCE_DATA } from \"@emisso/payroll-cl\";\n\n// \"I want to pay 1.2M líquido — what's the gross?\"\nconst gross = calculateNetToGross(1_200_000, {\n  afpCode: \"habitat\",\n  healthPlan: \"fonasa\",\n  referenceData: DEFAULT_REFERENCE_DATA,\n});\n```\n\n### Finiquito\n\n```typescript\nimport { calculateFiniquito } from \"@emisso/payroll-cl\";\n\nconst finiquito = calculateFiniquito({\n  baseSalary: 1_500_000,\n  startDate: new Date(\"2020-01-15\"),\n  endDate: new Date(\"2026-03-13\"),\n  terminationType: \"employer_needs\",\n  unusedVacationDays: 12,\n  referenceData: DEFAULT_REFERENCE_DATA,\n});\n```\n\n## Quick Start — Self-Hosted API\n\nFor teams that need a REST API with persistence, multi-tenant, and employee management.\n\n```bash\nnpm install @emisso/payroll-api\n```\n\n**1. Set environment variables:**\n\n```bash\n# .env.local\nEMISSO_DATABASE_URL=postgresql://user:pass@localhost:5432/mydb\n```\n\n**2. Run migrations:**\n\n```bash\nnpx @emisso/payroll-api migrate\n```\n\n**3. Mount in your Next.js app:**\n\n```typescript\n// app/api/payroll/[...path]/route.ts\nimport { createPayrollRouter } from \"@emisso/payroll-api/next\";\n\nexport const { GET, POST, PUT, DELETE } = createPayrollRouter({\n  databaseUrl: process.env.EMISSO_DATABASE_URL!,\n  basePath: \"/api/payroll\",\n  resolveTenantId: async (req) =\u003e {\n    const session = await getSession(req); // your auth\n    return session.tenantId;\n  },\n});\n```\n\n**4. Use the API:**\n\n```bash\n# Create employee\ncurl -X POST http://localhost:3000/api/payroll/employees \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"rut\":\"12.345.678-9\",\"firstName\":\"Juan\",\"lastName\":\"Pérez\",\"baseSalary\":1500000}'\n\n# Run payroll\ncurl -X POST http://localhost:3000/api/payroll/runs \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"period\":\"2026-03\"}'\n```\n\n## API Reference\n\n### Engine Exports (`@emisso/payroll-cl`)\n\n| Export | Description |\n|--------|-------------|\n| `calculatePayroll(input)` | Batch calculation for multiple employees |\n| `calculateEmployeePayroll(employee, refData)` | Single employee calculation |\n| `calculateNetToGross(netPay, options)` | Reverse calculation: net → gross |\n| `calculateFiniquito(input)` | Severance/termination calculation |\n| `calculateOvertime(hours, baseSalary, type)` | Overtime pay calculation |\n| `generatePreviredFile(data)` | Generate Previred DDJJ text file |\n| `validatePreviredData(data)` | Validate data before Previred generation |\n| `DEFAULT_REFERENCE_DATA` | Default economic indicators (Feb 2026) |\n| `formatRut(rut)` / `validateRut(rut)` | RUT utilities |\n\n### Providers (`@emisso/payroll-cl/providers`)\n\n| Export | Description |\n|--------|-------------|\n| `fetchCurrentIndicators()` | UF, UTM, UTA, IMM from mindicador.cl |\n| `fetchIndicatorsFromSII()` | Indicators from SII RSS feed |\n| `fetchAFPRates()` | Current AFP commission rates |\n\n## Payroll Rules\n\n| Rule | Module | Description |\n|------|--------|-------------|\n| AFP | `rules/afp` | Mandatory pension (10% + commission) |\n| Health | `rules/health` | Fonasa (7%) or Isapre (7% + additional UF) |\n| Income Tax | `rules/income-tax` | Progressive brackets in UTM |\n| Unemployment | `rules/unemployment` | Employee + employer portions by contract type |\n| Gratification | `rules/gratification` | Legal (Art. 50, capped at 4.75 IMM) or convenida |\n| Family Allowance | `rules/family-allowance` | Brackets by income level |\n| SIS | `rules/sis` | Employer disability/survival insurance |\n| Mutual | `rules/mutual` | Workplace accident insurance |\n| APV | `rules/apv` | Voluntary pension savings |\n| Pension Reform | `rules/employer-pension-reform` | Law 21.720 employer contribution |\n| Overtime | `rules/overtime` | 50% surcharge calculation |\n| Finiquito | `rules/finiquito` | Severance: indemnización, vacaciones, etc. |\n\n## CLI\n\n```bash\nnpm install -g @emisso/payroll-cli\n```\n\n### Commands\n\n| Command | Description |\n|---------|-------------|\n| `payroll calculate -i batch.json` | Batch payroll calculation from JSON file |\n| `payroll calculate-employee --base-salary 1500000 --afp habitat --health fonasa` | Single employee calculation |\n| `payroll net-to-gross --target-net 1200000 --afp habitat --health fonasa` | Reverse solver: net → gross |\n| `payroll finiquito --hire-date 2020-01-15 --termination-date 2026-03-15 --type despido_sin_causa --base-salary 1500000` | Severance calculation |\n| `payroll overtime --hours 10 --base-salary 1000000` | Overtime pay calculation |\n| `payroll indicators --source defaults` | Show economic indicators (UF, UTM, IMM) |\n| `payroll previred generate -i data.json -o ddjj.txt` | Generate Previred DDJJ file |\n| `payroll previred validate -i data.json` | Validate Previred data |\n| `payroll rut validate 12345678-5` | Validate Chilean RUT |\n| `payroll rut format 123456785` | Format RUT with dots and dash |\n| `payroll doctor` | Check system health and dependencies |\n\n### Output Formats\n\nAll commands support `--format table|csv|json` and `--json` shorthand. Defaults to table for TTY, CSV for pipes.\n\n```bash\npayroll calculate-employee --base-salary 1500000 --afp habitat --health fonasa --json\npayroll calculate -i batch.json --format csv \u003e output.csv\n```\n\n## Development\n\n```bash\npnpm install\npnpm build          # Build all packages\npnpm test           # Run all tests\npnpm lint           # Typecheck all packages\n```\n\n## FAQ\n\n**What is the best TypeScript library for Chilean payroll calculation?**\n[@emisso/payroll-cl](https://github.com/emisso-ai/emisso-payroll) is an MIT-licensed TypeScript engine that calculates AFP, health insurance (Fonasa/Isapre), income tax, unemployment, gratification, family allowance, pension reform (Law 21.720), finiquito, and generates Previred DDJJ files. It's a pure calculation engine with zero I/O.\n\n**How do I calculate remuneraciones in Node.js?**\nInstall `@emisso/payroll-cl` and call `calculateEmployeePayroll(employee, referenceData)`. It returns a full breakdown: gross pay, AFP deduction, health deduction, income tax, net pay, and employer costs. Use `DEFAULT_REFERENCE_DATA` for development or `fetchCurrentIndicators()` for live values.\n\n**How do I generate a Previred file in TypeScript?**\nUse `generatePreviredFile(data)` from `@emisso/payroll-cl`. It produces the fixed-width text file that Previred's portal expects. Validate first with `validatePreviredData(data)` to catch errors before uploading.\n\n**Can I calculate finiquito (severance) programmatically?**\nYes. `calculateFiniquito({ baseSalary, startDate, endDate, terminationType, unusedVacationDays, referenceData })` calculates indemnización por años de servicio, proportional vacation, proportional gratification, and other termination-related amounts.\n\n**Does this handle the 2024 pension reform (Law 21.720)?**\nYes. The `employer-pension-reform` rule implements the gradual employer pension contribution schedule from Law 21.720, which phases in from 2025 to 2035.\n\n**How do I get live economic indicators (UF, UTM, IMM)?**\nImport `fetchCurrentIndicators()` from `@emisso/payroll-cl/providers`. It fetches current UF, UTM, UTA, and IMM values from mindicador.cl. Alternative: `fetchIndicatorsFromSII()` for SII's RSS feed.\n\n## Alternatives\n\n| Library | Language | Payroll Calc | Previred | Finiquito | Open Source | Self-Hosted API |\n|---------|----------|:---:|:---:|:---:|:---:|:---:|\n| **@emisso/payroll-cl** | TypeScript | ✅ | ✅ | ✅ | ✅ MIT | ✅ |\n| Talana | SaaS | ✅ | ✅ | ✅ | ❌ | ❌ |\n| Nubox Remuneraciones | Desktop/.NET | ✅ | ✅ | ✅ | ❌ | ❌ |\n| Remuner | SaaS | ✅ | ✅ | ❌ | ❌ | ❌ |\n\n## License\n\nMIT — [Emisso](https://emisso.ai)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Femisso-ai%2Femisso-payroll","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Femisso-ai%2Femisso-payroll","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Femisso-ai%2Femisso-payroll/lists"}