@hasna/microservices 0.0.3 → 0.0.4

package/microservices/microservice-payroll/src/cli/index.ts

@@ -0,0 +1,374 @@
+#!/usr/bin/env bun
+
+import { Command } from "commander";
+import {
+  createEmployee,
+  getEmployee,
+  listEmployees,
+  updateEmployee,
+  terminateEmployee,
+  createPayPeriod,
+  listPayPeriods,
+  getPayPeriod,
+  processPayroll,
+  listPayStubs,
+  getPayStub,
+  getPayrollReport,
+  getYtdReport,
+  getTaxSummary,
+} from "../db/payroll.js";
+
+const program = new Command();
+
+program
+  .name("microservice-payroll")
+  .description("Payroll management microservice")
+  .version("0.0.1");
+
+// --- Employees ---
+
+const employeeCmd = program
+  .command("employee")
+  .description("Employee management");
+
+employeeCmd
+  .command("add")
+  .description("Add a new employee")
+  .requiredOption("--name <name>", "Full name")
+  .requiredOption("--pay-rate <rate>", "Pay rate (annual salary or hourly rate)")
+  .option("--email <email>", "Email address")
+  .option("--type <type>", "Type: employee or contractor", "employee")
+  .option("--department <dept>", "Department")
+  .option("--title <title>", "Job title")
+  .option("--pay-type <type>", "Pay type: salary or hourly", "salary")
+  .option("--currency <currency>", "Currency code", "USD")
+  .option("--start-date <date>", "Start date (YYYY-MM-DD)")
+  .option("--json", "Output as JSON", false)
+  .action((opts) => {
+    const employee = createEmployee({
+      name: opts.name,
+      email: opts.email,
+      type: opts.type,
+      department: opts.department,
+      title: opts.title,
+      pay_rate: parseFloat(opts.payRate),
+      pay_type: opts.payType,
+      currency: opts.currency,
+      start_date: opts.startDate,
+    });
+
+    if (opts.json) {
+      console.log(JSON.stringify(employee, null, 2));
+    } else {
+      console.log(`Created employee: ${employee.name} (${employee.id})`);
+    }
+  });
+
+employeeCmd
+  .command("list")
+  .description("List employees")
+  .option("--status <status>", "Filter by status: active or terminated")
+  .option("--department <dept>", "Filter by department")
+  .option("--type <type>", "Filter by type: employee or contractor")
+  .option("--search <query>", "Search by name, email, or department")
+  .option("--json", "Output as JSON", false)
+  .action((opts) => {
+    const employees = listEmployees({
+      status: opts.status,
+      department: opts.department,
+      type: opts.type,
+      search: opts.search,
+    });
+
+    if (opts.json) {
+      console.log(JSON.stringify(employees, null, 2));
+    } else {
+      if (employees.length === 0) {
+        console.log("No employees found.");
+        return;
+      }
+      for (const e of employees) {
+        const dept = e.department ? ` (${e.department})` : "";
+        const status = e.status === "terminated" ? " [TERMINATED]" : "";
+        console.log(`  ${e.name}${dept} — ${e.pay_type} $${e.pay_rate}${status}`);
+      }
+      console.log(`\n${employees.length} employee(s)`);
+    }
+  });
+
+employeeCmd
+  .command("get")
+  .description("Get an employee by ID")
+  .argument("<id>", "Employee ID")
+  .option("--json", "Output as JSON", false)
+  .action((id, opts) => {
+    const employee = getEmployee(id);
+    if (!employee) {
+      console.error(`Employee '${id}' not found.`);
+      process.exit(1);
+    }
+
+    if (opts.json) {
+      console.log(JSON.stringify(employee, null, 2));
+    } else {
+      console.log(`${employee.name}`);
+      if (employee.email) console.log(`  Email: ${employee.email}`);
+      console.log(`  Type: ${employee.type}`);
+      console.log(`  Status: ${employee.status}`);
+      if (employee.department) console.log(`  Department: ${employee.department}`);
+      if (employee.title) console.log(`  Title: ${employee.title}`);
+      console.log(`  Pay: ${employee.pay_type} $${employee.pay_rate} ${employee.currency}`);
+    }
+  });
+
+employeeCmd
+  .command("update")
+  .description("Update an employee")
+  .argument("<id>", "Employee ID")
+  .option("--name <name>", "Full name")
+  .option("--email <email>", "Email")
+  .option("--department <dept>", "Department")
+  .option("--title <title>", "Job title")
+  .option("--pay-rate <rate>", "Pay rate")
+  .option("--pay-type <type>", "Pay type")
+  .option("--json", "Output as JSON", false)
+  .action((id, opts) => {
+    const input: Record<string, unknown> = {};
+    if (opts.name !== undefined) input.name = opts.name;
+    if (opts.email !== undefined) input.email = opts.email;
+    if (opts.department !== undefined) input.department = opts.department;
+    if (opts.title !== undefined) input.title = opts.title;
+    if (opts.payRate !== undefined) input.pay_rate = parseFloat(opts.payRate);
+    if (opts.payType !== undefined) input.pay_type = opts.payType;
+
+    const employee = updateEmployee(id, input);
+    if (!employee) {
+      console.error(`Employee '${id}' not found.`);
+      process.exit(1);
+    }
+
+    if (opts.json) {
+      console.log(JSON.stringify(employee, null, 2));
+    } else {
+      console.log(`Updated: ${employee.name}`);
+    }
+  });
+
+employeeCmd
+  .command("terminate")
+  .description("Terminate an employee")
+  .argument("<id>", "Employee ID")
+  .option("--end-date <date>", "End date (YYYY-MM-DD)")
+  .option("--json", "Output as JSON", false)
+  .action((id, opts) => {
+    const employee = terminateEmployee(id, opts.endDate);
+    if (!employee) {
+      console.error(`Employee '${id}' not found.`);
+      process.exit(1);
+    }
+
+    if (opts.json) {
+      console.log(JSON.stringify(employee, null, 2));
+    } else {
+      console.log(`Terminated: ${employee.name} (end date: ${employee.end_date})`);
+    }
+  });
+
+// --- Pay Periods ---
+
+const periodCmd = program
+  .command("payperiod")
+  .description("Pay period management");
+
+periodCmd
+  .command("create")
+  .description("Create a new pay period")
+  .requiredOption("--start <date>", "Start date (YYYY-MM-DD)")
+  .requiredOption("--end <date>", "End date (YYYY-MM-DD)")
+  .option("--json", "Output as JSON", false)
+  .action((opts) => {
+    const period = createPayPeriod({
+      start_date: opts.start,
+      end_date: opts.end,
+    });
+
+    if (opts.json) {
+      console.log(JSON.stringify(period, null, 2));
+    } else {
+      console.log(`Created pay period: ${period.start_date} to ${period.end_date} (${period.id})`);
+    }
+  });
+
+periodCmd
+  .command("list")
+  .description("List pay periods")
+  .option("--status <status>", "Filter by status")
+  .option("--json", "Output as JSON", false)
+  .action((opts) => {
+    const periods = listPayPeriods(opts.status);
+
+    if (opts.json) {
+      console.log(JSON.stringify(periods, null, 2));
+    } else {
+      if (periods.length === 0) {
+        console.log("No pay periods found.");
+        return;
+      }
+      for (const p of periods) {
+        console.log(`  ${p.start_date} to ${p.end_date} [${p.status}] (${p.id})`);
+      }
+      console.log(`\n${periods.length} pay period(s)`);
+    }
+  });
+
+periodCmd
+  .command("process")
+  .description("Process payroll for a pay period")
+  .argument("<id>", "Pay period ID")
+  .option("--json", "Output as JSON", false)
+  .action((id, opts) => {
+    try {
+      const stubs = processPayroll(id);
+      if (opts.json) {
+        console.log(JSON.stringify(stubs, null, 2));
+      } else {
+        console.log(`Processed payroll: ${stubs.length} pay stub(s) generated.`);
+        for (const s of stubs) {
+          console.log(`  Employee ${s.employee_id}: gross=$${s.gross_pay} net=$${s.net_pay}`);
+        }
+      }
+    } catch (error) {
+      console.error(`Error: ${error instanceof Error ? error.message : String(error)}`);
+      process.exit(1);
+    }
+  });
+
+// --- Pay Stubs ---
+
+const stubCmd = program
+  .command("paystub")
+  .description("Pay stub management");
+
+stubCmd
+  .command("list")
+  .description("List pay stubs")
+  .option("--employee <id>", "Filter by employee ID")
+  .option("--period <id>", "Filter by pay period ID")
+  .option("--json", "Output as JSON", false)
+  .action((opts) => {
+    const stubs = listPayStubs({
+      employee_id: opts.employee,
+      pay_period_id: opts.period,
+    });
+
+    if (opts.json) {
+      console.log(JSON.stringify(stubs, null, 2));
+    } else {
+      if (stubs.length === 0) {
+        console.log("No pay stubs found.");
+        return;
+      }
+      for (const s of stubs) {
+        console.log(`  ${s.id} — Employee ${s.employee_id}: gross=$${s.gross_pay} net=$${s.net_pay}`);
+      }
+      console.log(`\n${stubs.length} pay stub(s)`);
+    }
+  });
+
+stubCmd
+  .command("get")
+  .description("Get a pay stub by ID")
+  .argument("<id>", "Pay stub ID")
+  .option("--json", "Output as JSON", false)
+  .action((id, opts) => {
+    const stub = getPayStub(id);
+    if (!stub) {
+      console.error(`Pay stub '${id}' not found.`);
+      process.exit(1);
+    }
+
+    if (opts.json) {
+      console.log(JSON.stringify(stub, null, 2));
+    } else {
+      console.log(`Pay Stub: ${stub.id}`);
+      console.log(`  Employee: ${stub.employee_id}`);
+      console.log(`  Period: ${stub.pay_period_id}`);
+      console.log(`  Gross Pay: $${stub.gross_pay}`);
+      console.log(`  Deductions: ${JSON.stringify(stub.deductions)}`);
+      console.log(`  Net Pay: $${stub.net_pay}`);
+      if (stub.hours_worked !== null) console.log(`  Hours: ${stub.hours_worked}`);
+      if (stub.overtime_hours) console.log(`  Overtime: ${stub.overtime_hours}`);
+    }
+  });
+
+// --- Run (process payroll shortcut) ---
+
+program
+  .command("run")
+  .description("Process payroll for a pay period (shortcut)")
+  .argument("<period-id>", "Pay period ID")
+  .option("--json", "Output as JSON", false)
+  .action((periodId, opts) => {
+    try {
+      const stubs = processPayroll(periodId);
+      if (opts.json) {
+        console.log(JSON.stringify(stubs, null, 2));
+      } else {
+        console.log(`Payroll processed: ${stubs.length} pay stub(s) generated.`);
+      }
+    } catch (error) {
+      console.error(`Error: ${error instanceof Error ? error.message : String(error)}`);
+      process.exit(1);
+    }
+  });
+
+// --- Report ---
+
+program
+  .command("report")
+  .description("Get payroll report for a pay period")
+  .argument("<period-id>", "Pay period ID")
+  .option("--json", "Output as JSON", false)
+  .action((periodId, opts) => {
+    const report = getPayrollReport(periodId);
+    if (!report) {
+      console.error(`Pay period '${periodId}' not found.`);
+      process.exit(1);
+    }
+
+    if (opts.json) {
+      console.log(JSON.stringify(report, null, 2));
+    } else {
+      console.log(`Payroll Report: ${report.period.start_date} to ${report.period.end_date}`);
+      console.log(`  Status: ${report.period.status}`);
+      console.log(`  Employees: ${report.employee_count}`);
+      console.log(`  Total Gross: $${report.total_gross}`);
+      console.log(`  Total Deductions: $${report.total_deductions}`);
+      console.log(`  Total Net: $${report.total_net}`);
+    }
+  });
+
+// --- Taxes ---
+
+program
+  .command("taxes")
+  .description("Get tax summary for a year")
+  .argument("<year>", "Tax year")
+  .option("--json", "Output as JSON", false)
+  .action((year, opts) => {
+    const summary = getTaxSummary(parseInt(year));
+
+    if (opts.json) {
+      console.log(JSON.stringify(summary, null, 2));
+    } else {
+      if (summary.length === 0) {
+        console.log(`No tax data for ${year}.`);
+        return;
+      }
+      for (const entry of summary) {
+        console.log(`  ${entry.employee_name}: gross=$${entry.total_gross} fed=$${entry.total_federal_tax} state=$${entry.total_state_tax} net=$${entry.total_net}`);
+      }
+    }
+  });
+
+program.parse(process.argv);

package/microservices/microservice-payroll/src/db/database.ts

@@ -0,0 +1,93 @@
+/**
+ * Database connection for microservice-payroll
+ */
+
+import { Database } from "bun:sqlite";
+import { existsSync, mkdirSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { MIGRATIONS } from "./migrations.js";
+
+let _db: Database | null = null;
+
+function getDbPath(): string {
+  // Environment variable override
+  if (process.env["MICROSERVICES_DIR"]) {
+    return join(process.env["MICROSERVICES_DIR"], "microservice-payroll", "data.db");
+  }
+
+  // Check for .microservices in current or parent directories
+  let dir = resolve(process.cwd());
+  while (true) {
+    const candidate = join(dir, ".microservices", "microservice-payroll", "data.db");
+    const msDir = join(dir, ".microservices");
+    if (existsSync(msDir)) return candidate;
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+
+  // Global fallback
+  const home = process.env["HOME"] || process.env["USERPROFILE"] || "~";
+  return join(home, ".microservices", "microservice-payroll", "data.db");
+}
+
+function ensureDir(filePath: string): void {
+  const dir = dirname(resolve(filePath));
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+}
+
+export function getDatabase(): Database {
+  if (_db) return _db;
+
+  const dbPath = getDbPath();
+  ensureDir(dbPath);
+
+  _db = new Database(dbPath);
+  _db.exec("PRAGMA journal_mode = WAL");
+  _db.exec("PRAGMA foreign_keys = ON");
+
+  // Create migrations table
+  _db.exec(`
+    CREATE TABLE IF NOT EXISTS _migrations (
+      id INTEGER PRIMARY KEY,
+      name TEXT NOT NULL,
+      applied_at TEXT NOT NULL DEFAULT (datetime('now'))
+    )
+  `);
+
+  // Apply pending migrations
+  const applied = _db
+    .query("SELECT id FROM _migrations ORDER BY id")
+    .all() as { id: number }[];
+  const appliedIds = new Set(applied.map((r) => r.id));
+
+  for (const migration of MIGRATIONS) {
+    if (appliedIds.has(migration.id)) continue;
+
+    _db.exec("BEGIN");
+    try {
+      _db.exec(migration.sql);
+      _db.prepare("INSERT INTO _migrations (id, name) VALUES (?, ?)").run(
+        migration.id,
+        migration.name
+      );
+      _db.exec("COMMIT");
+    } catch (error) {
+      _db.exec("ROLLBACK");
+      throw new Error(
+        `Migration ${migration.id} (${migration.name}) failed: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+  }
+
+  return _db;
+}
+
+export function closeDatabase(): void {
+  if (_db) {
+    _db.close();
+    _db = null;
+  }
+}

package/microservices/microservice-payroll/src/db/migrations.ts

@@ -0,0 +1,69 @@
+export interface MigrationEntry {
+  id: number;
+  name: string;
+  sql: string;
+}
+
+export const MIGRATIONS: MigrationEntry[] = [
+  {
+    id: 1,
+    name: "initial_schema",
+    sql: `
+      CREATE TABLE IF NOT EXISTS employees (
+        id TEXT PRIMARY KEY,
+        name TEXT NOT NULL,
+        email TEXT,
+        type TEXT NOT NULL DEFAULT 'employee' CHECK (type IN ('employee', 'contractor')),
+        status TEXT NOT NULL DEFAULT 'active' CHECK (status IN ('active', 'terminated')),
+        department TEXT,
+        title TEXT,
+        pay_rate REAL NOT NULL,
+        pay_type TEXT NOT NULL DEFAULT 'salary' CHECK (pay_type IN ('salary', 'hourly')),
+        currency TEXT NOT NULL DEFAULT 'USD',
+        tax_info TEXT NOT NULL DEFAULT '{}',
+        start_date TEXT,
+        end_date TEXT,
+        created_at TEXT NOT NULL DEFAULT (datetime('now')),
+        updated_at TEXT NOT NULL DEFAULT (datetime('now'))
+      );
+
+      CREATE TABLE IF NOT EXISTS pay_periods (
+        id TEXT PRIMARY KEY,
+        start_date TEXT NOT NULL,
+        end_date TEXT NOT NULL,
+        status TEXT NOT NULL DEFAULT 'draft' CHECK (status IN ('draft', 'processing', 'completed')),
+        created_at TEXT NOT NULL DEFAULT (datetime('now'))
+      );
+
+      CREATE TABLE IF NOT EXISTS pay_stubs (
+        id TEXT PRIMARY KEY,
+        employee_id TEXT NOT NULL REFERENCES employees(id) ON DELETE CASCADE,
+        pay_period_id TEXT NOT NULL REFERENCES pay_periods(id) ON DELETE CASCADE,
+        gross_pay REAL NOT NULL DEFAULT 0,
+        deductions TEXT NOT NULL DEFAULT '{}',
+        net_pay REAL NOT NULL DEFAULT 0,
+        hours_worked REAL,
+        overtime_hours REAL DEFAULT 0,
+        created_at TEXT NOT NULL DEFAULT (datetime('now'))
+      );
+
+      CREATE TABLE IF NOT EXISTS payments (
+        id TEXT PRIMARY KEY,
+        pay_stub_id TEXT NOT NULL REFERENCES pay_stubs(id) ON DELETE CASCADE,
+        method TEXT NOT NULL DEFAULT 'direct_deposit' CHECK (method IN ('direct_deposit', 'check', 'wire')),
+        status TEXT NOT NULL DEFAULT 'pending' CHECK (status IN ('pending', 'paid', 'failed')),
+        paid_at TEXT,
+        reference TEXT,
+        created_at TEXT NOT NULL DEFAULT (datetime('now'))
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_employees_email ON employees(email);
+      CREATE INDEX IF NOT EXISTS idx_employees_status ON employees(status);
+      CREATE INDEX IF NOT EXISTS idx_employees_department ON employees(department);
+      CREATE INDEX IF NOT EXISTS idx_pay_stubs_employee ON pay_stubs(employee_id);
+      CREATE INDEX IF NOT EXISTS idx_pay_stubs_period ON pay_stubs(pay_period_id);
+      CREATE INDEX IF NOT EXISTS idx_payments_stub ON payments(pay_stub_id);
+      CREATE INDEX IF NOT EXISTS idx_payments_status ON payments(status);
+    `,
+  },
+];