@classytic/payroll 1.0.0 → 2.8.0

package/package.json

@@ -1,20 +1,36 @@
 {
   "name": "@classytic/payroll",
-  "version": "1.0.0",
-  "description": "Modern HRM and payroll management library for Node.js applications",
+  "version": "2.8.0",
+  "description": "Modern HRM and payroll management for Mongoose - Plugin-based, event-driven, multi-tenant ready. Salary processing, compensation management, tax calculations, and employee lifecycle management.",
   "type": "module",
-  "main": "./src/index.js",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "exports": {
-    ".": "./src/index.js",
-    "./init": "./src/init.js",
-    "./service": "./src/service.js",
-    "./adapters/*": "./src/adapters/*.js",
-    "./events/*": "./src/events/*.js",
-    "./workflows/*": "./src/workflows/*.js",
-    "./schemas/*": "./src/schemas/*.js"
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./schemas": {
+      "types": "./dist/schemas/index.d.ts",
+      "default": "./dist/schemas/index.js"
+    },
+    "./utils": {
+      "types": "./dist/utils/index.d.ts",
+      "default": "./dist/utils/index.js"
+    },
+    "./calculators": {
+      "types": "./dist/calculators/index.d.ts",
+      "default": "./dist/calculators/index.js"
+    },
+    "./core": {
+      "types": "./dist/core/index.d.ts",
+      "default": "./dist/core/index.js"
+    }
   },
   "files": [
-    "src/**/*.js",
+    "dist",
     "README.md",
     "LICENSE"
   ],
@@ -23,13 +39,23 @@
     "payroll",
     "employee",
     "management",
-    "attendance",
-    "leave",
     "salary",
-    "nodejs",
-    "mongoose"
+    "compensation",
+    "tax",
+    "multi-tenant",
+    "mongoose",
+    "typescript",
+    "plugin",
+    "hr",
+    "human-resources",
+    "workforce",
+    "attendance",
+    "nodejs"
+  ],
+  "author": "Classytic <classytic.dev@gmail.com> (https://github.com/classytic)",
+  "contributors": [
+    "Sadman Chowdhury (https://github.com/siam923)"
   ],
-  "author": "Sadman Chowdhury",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -40,20 +66,51 @@
   },
   "homepage": "https://github.com/classytic/payroll#readme",
   "peerDependencies": {
-    "mongoose": "^8.0.0"
+    "@classytic/clockin": "^2.2.0",
+    "@classytic/mongokit": "^3.0.0",
+    "@classytic/shared-types": "^1.0.0",
+    "mongoose": "^8.0.0 || ^9.0.0",
+    "lru-cache": "^11.0.0",
+    "p-limit": "^6.0.0 || ^7.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@classytic/clockin": {
+      "optional": true
+    }
   },
   "devDependencies": {
-    "mongoose": "^8.0.0",
-    "mongoose-paginate-v2": "^1.8.0",
-    "mongoose-aggregate-paginate-v2": "^1.1.0"
+    "@classytic/clockin": "^2.2.0",
+    "@classytic/mongokit": "^3.0.0",
+    "@classytic/shared-types": "^1.0.0",
+    "@types/node": "^22.8.7",
+    "@vitest/coverage-v8": "^3.2.4",
+    "lru-cache": "^11.2.4",
+    "mongodb-memory-server": "^10.0.0",
+    "mongoose": "^9.0.0",
+    "p-limit": "^7.2.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
   },
   "engines": {
     "node": ">=18.0.0"
   },
   "scripts": {
-    "example:basic": "node test/examples/basic-usage.js",
-    "example:mongoose": "node test/examples/with-mongoose.js",
-    "example:workflow": "node test/examples/full-workflow.js",
-    "test": "npm run example:basic && npm run example:mongoose && npm run example:workflow"
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:local": "node scripts/test-local.mjs",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "test:exports": "node scripts/test-exports.mjs",
+    "typecheck": "tsc --noEmit",
+    "lint": "tsc --noEmit",
+    "prepublishOnly": "npm run build && npm run typecheck && npm run test:exports",
+    "publish:dry": "npm publish --dry-run --access public",
+    "publish:npm": "npm publish --access public",
+    "release": "npm run build && npm run typecheck && npm run test:exports && npm publish --access public",
+    "release:patch": "npm version patch && npm run release",
+    "release:minor": "npm version minor && npm run release",
+    "release:major": "npm version major && npm run release"
   }
 }

package/src/config.js

@@ -1,177 +0,0 @@
-export const HRM_CONFIG = {
-  // Data Retention: Auto-delete exported records after 2 years
-  // Organizations must download records via /payroll/export API before deletion
-  dataRetention: {
-    payrollRecordsTTL: 63072000,  // 2 years in seconds
-    exportWarningDays: 30,         // Warn before TTL expires
-  },
-
-  payroll: {
-    defaultCurrency: 'BDT',
-    allowProRating: true,
-    attendanceIntegration: true,
-    autoDeductions: true,
-    overtimeEnabled: false,
-  },
-
-  salary: {
-    minimumWage: 0,
-    maximumAllowances: 10,
-    maximumDeductions: 10,
-    defaultFrequency: 'monthly',
-  },
-
-  employment: {
-    defaultProbationMonths: 3,
-    maxProbationMonths: 6,
-    allowReHiring: true,
-    trackEmploymentHistory: true,
-  },
-
-  validation: {
-    requireBankDetails: false,
-    requireEmployeeId: true,
-    uniqueEmployeeIdPerOrg: true,
-    allowMultiTenantEmployees: true,
-  },
-};
-
-// ============ ORGANIZATION ROLES CONFIGURATION ============
-// Defines available organization roles for frontend authentication and access control
-// Frontend is responsible for implementing access control based on these roles
-export const ORG_ROLES = {
-  OWNER: {
-    key: 'owner',
-    label: 'Owner',
-    description: 'Full organization access (set by Organization model)',
-  },
-  MANAGER: {
-    key: 'manager',
-    label: 'Manager',
-    description: 'Management and administrative features',
-  },
-  TRAINER: {
-    key: 'trainer',
-    label: 'Trainer',
-    description: 'Training and coaching features',
-  },
-  STAFF: {
-    key: 'staff',
-    label: 'Staff',
-    description: 'General staff access to basic features',
-  },
-  INTERN: {
-    key: 'intern',
-    label: 'Intern',
-    description: 'Limited access for interns',
-  },
-  CONSULTANT: {
-    key: 'consultant',
-    label: 'Consultant',
-    description: 'Project-based consultant access',
-  },
-};
-
-// Get all available org role keys
-export const ORG_ROLE_KEYS = Object.values(ORG_ROLES).map(role => role.key);
-
-// ============ ROLE MAPPING CONFIGURATION ============
-// Maps employee attributes (department, position, employment type) to organization roles
-// Priority: department > employmentType > default
-export const ROLE_MAPPING = {
-  // Department-based mapping (highest priority)
-  byDepartment: {
-    management: 'manager',
-    training: 'trainer',
-    sales: 'staff',
-    operations: 'staff',
-    finance: 'staff',
-    hr: 'staff',
-    marketing: 'staff',
-    it: 'staff',
-    support: 'staff',
-  },
-
-  // Employment type mapping (fallback)
-  byEmploymentType: {
-    full_time: 'staff',
-    part_time: 'staff',
-    contract: 'consultant',
-    intern: 'intern',
-    consultant: 'consultant',
-  },
-
-  // Default role if no match found
-  default: 'staff',
-};
-
-export const SALARY_BANDS = {
-  intern: { min: 10000, max: 20000 },
-  junior: { min: 20000, max: 40000 },
-  mid: { min: 40000, max: 70000 },
-  senior: { min: 70000, max: 120000 },
-  lead: { min: 100000, max: 200000 },
-  executive: { min: 150000, max: 500000 },
-};
-
-export const TAX_BRACKETS = {
-  BDT: [
-    { min: 0, max: 300000, rate: 0 },
-    { min: 300000, max: 400000, rate: 0.05 },
-    { min: 400000, max: 500000, rate: 0.10 },
-    { min: 500000, max: 600000, rate: 0.15 },
-    { min: 600000, max: 3000000, rate: 0.20 },
-    { min: 3000000, max: Infinity, rate: 0.25 },
-  ],
-};
-
-export function calculateTax(annualIncome, currency = 'BDT') {
-  const brackets = TAX_BRACKETS[currency];
-  if (!brackets) return 0;
-
-  let tax = 0;
-  for (const bracket of brackets) {
-    if (annualIncome > bracket.min) {
-      const taxableAmount = Math.min(annualIncome, bracket.max) - bracket.min;
-      tax += taxableAmount * bracket.rate;
-    }
-  }
-  return Math.round(tax);
-}
-
-export function getSalaryBand(amount) {
-  for (const [band, range] of Object.entries(SALARY_BANDS)) {
-    if (amount >= range.min && amount <= range.max) {
-      return band;
-    }
-  }
-  return 'custom';
-}
-
-/**
- * Determines the appropriate organization role for an employee
- * Based on department, employment type, and position
- * @param {Object} employmentData - Employee's employment data
- * @param {string} employmentData.department - Employee's department
- * @param {string} employmentData.type - Employment type (full_time, intern, etc.)
- * @param {string} employmentData.position - Job position/title
- * @returns {string} Organization role key
- */
-export function determineOrgRole(employmentData = {}) {
-  const { department, type: employmentType } = employmentData;
-
-  // Priority 1: Department-based mapping
-  if (department && ROLE_MAPPING.byDepartment[department]) {
-    return ROLE_MAPPING.byDepartment[department];
-  }
-
-  // Priority 2: Employment type mapping
-  if (employmentType && ROLE_MAPPING.byEmploymentType[employmentType]) {
-    return ROLE_MAPPING.byEmploymentType[employmentType];
-  }
-
-  // Priority 3: Default role
-  return ROLE_MAPPING.default;
-}
-
-export default HRM_CONFIG;

package/src/core/compensation.manager.js

@@ -1,242 +0,0 @@
-import logger from '../utils/logger.js';
-
-export async function updateSalary({
-  EmployeeModel,
-  employeeId,
-  compensation = {},
-  effectiveFrom = new Date(),
-  context = {},
-  session = null
-}) {
-  const employee = await EmployeeModel.findById(employeeId).session(session);
-
-  if (!employee) {
-    throw new Error('Employee not found');
-  }
-
-  if (employee.status === 'terminated') {
-    throw new Error('Cannot update salary for terminated employee');
-  }
-
-  const oldSalary = employee.compensation.netSalary;
-
-  if (compensation.baseAmount !== undefined) {
-    employee.compensation.baseAmount = compensation.baseAmount;
-  }
-
-  if (compensation.frequency) {
-    employee.compensation.frequency = compensation.frequency;
-  }
-
-  if (compensation.currency) {
-    employee.compensation.currency = compensation.currency;
-  }
-
-  employee.compensation.effectiveFrom = effectiveFrom;
-  employee.updateSalaryCalculations();
-
-  await employee.save({ session });
-
-  logger.info('Salary updated', {
-    employeeId: employee.employeeId,
-    organizationId: employee.organizationId,
-    oldSalary,
-    newSalary: employee.compensation.netSalary,
-    effectiveFrom,
-  });
-
-  return employee;
-}
-
-export async function addAllowance({
-  EmployeeModel,
-  employeeId,
-  type,
-  amount,
-  taxable = true,
-  recurring = true,
-  effectiveFrom = new Date(),
-  effectiveTo = null,
-  context = {},
-  session = null
-}) {
-  const employee = await EmployeeModel.findById(employeeId).session(session);
-
-  if (!employee) {
-    throw new Error('Employee not found');
-  }
-
-  if (employee.status === 'terminated') {
-    throw new Error('Cannot add allowance to terminated employee');
-  }
-
-  if (!employee.compensation.allowances) {
-    employee.compensation.allowances = [];
-  }
-
-  employee.compensation.allowances.push({
-    type,
-    amount,
-    taxable,
-    recurring,
-    effectiveFrom,
-    effectiveTo,
-  });
-
-  employee.updateSalaryCalculations();
-
-  await employee.save({ session });
-
-  logger.info('Allowance added', {
-    employeeId: employee.employeeId,
-    organizationId: employee.organizationId,
-    type,
-    amount,
-  });
-
-  return employee;
-}
-
-export async function removeAllowance({
-  EmployeeModel,
-  employeeId,
-  type,
-  context = {},
-  session = null
-}) {
-  const employee = await EmployeeModel.findById(employeeId).session(session);
-
-  if (!employee) {
-    throw new Error('Employee not found');
-  }
-
-  const before = employee.compensation.allowances?.length || 0;
-  employee.removeAllowance(type);
-  const after = employee.compensation.allowances?.length || 0;
-
-  if (before === after) {
-    throw new Error(`Allowance type '${type}' not found`);
-  }
-
-  await employee.save({ session });
-
-  logger.info('Allowance removed', {
-    employeeId: employee.employeeId,
-    organizationId: employee.organizationId,
-    type,
-  });
-
-  return employee;
-}
-
-export async function addDeduction({
-  EmployeeModel,
-  employeeId,
-  type,
-  amount,
-  auto = false,
-  recurring = true,
-  description = '',
-  effectiveFrom = new Date(),
-  effectiveTo = null,
-  context = {},
-  session = null
-}) {
-  const employee = await EmployeeModel.findById(employeeId).session(session);
-
-  if (!employee) {
-    throw new Error('Employee not found');
-  }
-
-  if (employee.status === 'terminated') {
-    throw new Error('Cannot add deduction to terminated employee');
-  }
-
-  if (!employee.compensation.deductions) {
-    employee.compensation.deductions = [];
-  }
-
-  employee.compensation.deductions.push({
-    type,
-    amount,
-    auto,
-    recurring,
-    description,
-    effectiveFrom,
-    effectiveTo,
-  });
-
-  employee.updateSalaryCalculations();
-
-  await employee.save({ session });
-
-  logger.info('Deduction added', {
-    employeeId: employee.employeeId,
-    organizationId: employee.organizationId,
-    type,
-    amount,
-    auto,
-  });
-
-  return employee;
-}
-
-export async function removeDeduction({
-  EmployeeModel,
-  employeeId,
-  type,
-  context = {},
-  session = null
-}) {
-  const employee = await EmployeeModel.findById(employeeId).session(session);
-
-  if (!employee) {
-    throw new Error('Employee not found');
-  }
-
-  const before = employee.compensation.deductions?.length || 0;
-  employee.removeDeduction(type);
-  const after = employee.compensation.deductions?.length || 0;
-
-  if (before === after) {
-    throw new Error(`Deduction type '${type}' not found`);
-  }
-
-  await employee.save({ session });
-
-  logger.info('Deduction removed', {
-    employeeId: employee.employeeId,
-    organizationId: employee.organizationId,
-    type,
-  });
-
-  return employee;
-}
-
-export async function updateBankDetails({
-  EmployeeModel,
-  employeeId,
-  bankDetails = {},
-  context = {},
-  session = null
-}) {
-  const employee = await EmployeeModel.findById(employeeId).session(session);
-
-  if (!employee) {
-    throw new Error('Employee not found');
-  }
-
-  employee.bankDetails = {
-    ...employee.bankDetails,
-    ...bankDetails,
-  };
-
-  await employee.save({ session });
-
-  logger.info('Bank details updated', {
-    employeeId: employee.employeeId,
-    organizationId: employee.organizationId,
-  });
-
-  return employee;
-}