@hasna/microservices 0.0.4 → 0.0.6

package/microservices/microservice-payments/src/mcp/index.ts

@@ -17,6 +17,17 @@ import {
   getPaymentStats,
   getBalanceByProvider,
   listByProvider,
+  autoReconcile,
+  retryPayment,
+  listRetries,
+  getRetryStats,
+  convertCurrency,
+  feeAnalysis,
+  declineReport,
+  addDisputeEvidence,
+  splitPayment,
+  revenueForecast,
+  findReconciliationGaps,
 } from "../db/payments.js";
 import {
   createDispute,
@@ -447,6 +458,218 @@ server.registerTool(
   }
 );
 
+// --- Auto-Reconciliation ---
+
+server.registerTool(
+  "auto_reconcile",
+  {
+    title: "Auto Reconcile",
+    description: "Auto-reconcile payments to invoices by matching amount, customer email, and date (+-3 days tolerance).",
+    inputSchema: {
+      date_from: z.string().optional(),
+      date_to: z.string().optional(),
+    },
+  },
+  async ({ date_from, date_to }) => {
+    const result = autoReconcile(date_from, date_to);
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+  }
+);
+
+// --- Retry ---
+
+server.registerTool(
+  "retry_payment",
+  {
+    title: "Retry Payment",
+    description: "Retry a failed payment. Creates a retry attempt record and re-processes the payment.",
+    inputSchema: { id: z.string() },
+  },
+  async ({ id }) => {
+    const attempt = retryPayment(id);
+    if (!attempt) {
+      return {
+        content: [{ type: "text", text: `Cannot retry payment '${id}' — not found or not failed.` }],
+        isError: true,
+      };
+    }
+    return { content: [{ type: "text", text: JSON.stringify(attempt, null, 2) }] };
+  }
+);
+
+server.registerTool(
+  "list_retries",
+  {
+    title: "List Retries",
+    description: "List all retry attempts for a payment.",
+    inputSchema: { payment_id: z.string() },
+  },
+  async ({ payment_id }) => {
+    const retries = listRetries(payment_id);
+    return {
+      content: [
+        { type: "text", text: JSON.stringify({ retries, count: retries.length }, null, 2) },
+      ],
+    };
+  }
+);
+
+server.registerTool(
+  "retry_stats",
+  {
+    title: "Retry Statistics",
+    description: "Get overall retry attempt statistics.",
+    inputSchema: {},
+  },
+  async () => {
+    const stats = getRetryStats();
+    return { content: [{ type: "text", text: JSON.stringify(stats, null, 2) }] };
+  }
+);
+
+// --- Currency Conversion ---
+
+server.registerTool(
+  "convert_currency",
+  {
+    title: "Convert Currency",
+    description: "Convert an amount between currencies using built-in rates (USD/EUR/GBP/CAD/AUD).",
+    inputSchema: {
+      amount: z.number(),
+      from: z.string(),
+      to: z.string(),
+    },
+  },
+  async ({ amount, from, to }) => {
+    const result = convertCurrency(amount, from, to);
+    if (!result) {
+      return {
+        content: [{ type: "text", text: `Unsupported currency pair: ${from} -> ${to}` }],
+        isError: true,
+      };
+    }
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+  }
+);
+
+// --- Fee Analysis ---
+
+server.registerTool(
+  "fee_analysis",
+  {
+    title: "Fee Analysis",
+    description: "Analyze processor fees per provider for a given month. Shows gross, fees, and net per provider.",
+    inputSchema: {
+      month: z.string().describe("Month in YYYY-MM format"),
+    },
+  },
+  async ({ month }) => {
+    const result = feeAnalysis(month);
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+  }
+);
+
+// --- Decline Analytics ---
+
+server.registerTool(
+  "decline_analysis",
+  {
+    title: "Decline Analysis",
+    description: "Get decline analytics — groups failed payments by description/reason.",
+    inputSchema: {
+      provider: z.enum(["stripe", "square", "mercury", "manual"]).optional(),
+    },
+  },
+  async ({ provider }) => {
+    const report = declineReport(provider);
+    return { content: [{ type: "text", text: JSON.stringify(report, null, 2) }] };
+  }
+);
+
+// --- Dispute Evidence ---
+
+server.registerTool(
+  "add_dispute_evidence",
+  {
+    title: "Add Dispute Evidence",
+    description: "Add evidence to an existing dispute. Appends to the evidence items array.",
+    inputSchema: {
+      dispute_id: z.string(),
+      description: z.string(),
+      file_ref: z.string().optional(),
+    },
+  },
+  async ({ dispute_id, description, file_ref }) => {
+    const dispute = addDisputeEvidence(dispute_id, description, file_ref);
+    if (!dispute) {
+      return {
+        content: [{ type: "text", text: `Dispute '${dispute_id}' not found.` }],
+        isError: true,
+      };
+    }
+    return { content: [{ type: "text", text: JSON.stringify(dispute, null, 2) }] };
+  }
+);
+
+// --- Payment Split ---
+
+server.registerTool(
+  "split_payment",
+  {
+    title: "Split Payment",
+    description: "Record marketplace commission splits for a payment. Stores split percentages in payment metadata.",
+    inputSchema: {
+      payment_id: z.string(),
+      splits: z.record(z.number()).describe("Map of vendor name to percentage (e.g. {vendor1: 70, vendor2: 30})"),
+    },
+  },
+  async ({ payment_id, splits }) => {
+    const payment = splitPayment(payment_id, splits);
+    if (!payment) {
+      return {
+        content: [{ type: "text", text: `Payment '${payment_id}' not found.` }],
+        isError: true,
+      };
+    }
+    return { content: [{ type: "text", text: JSON.stringify(payment, null, 2) }] };
+  }
+);
+
+// --- Revenue Forecast ---
+
+server.registerTool(
+  "revenue_forecast",
+  {
+    title: "Revenue Forecast",
+    description: "Project revenue for upcoming months based on last 3 months trend.",
+    inputSchema: {
+      months: z.number().describe("Number of months to forecast"),
+    },
+  },
+  async ({ months }) => {
+    const result = revenueForecast(months);
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+  }
+);
+
+// --- Reconciliation Gaps ---
+
+server.registerTool(
+  "reconciliation_gaps",
+  {
+    title: "Reconciliation Gaps",
+    description: "Find payments without invoice_id and invoice IDs without a succeeded payment in a date range.",
+    inputSchema: {
+      date_from: z.string(),
+      date_to: z.string(),
+    },
+  },
+  async ({ date_from, date_to }) => {
+    const gaps = findReconciliationGaps(date_from, date_to);
+    return { content: [{ type: "text", text: JSON.stringify(gaps, null, 2) }] };
+  }
+);
+
 // --- Start ---
 async function main() {
   const transport = new StdioServerTransport();

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

@@ -16,6 +16,17 @@ import {
   getPayrollReport,
   getYtdReport,
   getTaxSummary,
+  createBenefit,
+  listBenefits,
+  removeBenefit,
+  generateAchFile,
+  generateW2,
+  generate1099,
+  setSchedule,
+  getNextPayPeriod,
+  auditPayroll,
+  forecastPayroll,
+  checkOvertime,
 } from "../db/payroll.js";
 
 const program = new Command();
@@ -371,4 +382,262 @@ program
     }
   });
 
+// --- Benefits ---
+
+const benefitCmd = program
+  .command("benefit")
+  .description("Employee benefit management");
+
+benefitCmd
+  .command("add")
+  .description("Add a benefit to an employee")
+  .requiredOption("--employee <id>", "Employee ID")
+  .requiredOption("--type <type>", "Benefit type: health, dental, vision, retirement, hsa, other")
+  .requiredOption("--amount <amount>", "Deduction amount")
+  .option("--description <desc>", "Description")
+  .option("--frequency <freq>", "Frequency: per_period, monthly, annual", "per_period")
+  .option("--json", "Output as JSON", false)
+  .action((opts) => {
+    try {
+      const benefit = createBenefit({
+        employee_id: opts.employee,
+        type: opts.type,
+        amount: parseFloat(opts.amount),
+        description: opts.description,
+        frequency: opts.frequency,
+      });
+
+      if (opts.json) {
+        console.log(JSON.stringify(benefit, null, 2));
+      } else {
+        console.log(`Created benefit: ${benefit.type} $${benefit.amount}/${benefit.frequency} (${benefit.id})`);
+      }
+    } catch (error) {
+      console.error(`Error: ${error instanceof Error ? error.message : String(error)}`);
+      process.exit(1);
+    }
+  });
+
+benefitCmd
+  .command("list")
+  .description("List benefits")
+  .option("--employee <id>", "Filter by employee ID")
+  .option("--json", "Output as JSON", false)
+  .action((opts) => {
+    const benefits = listBenefits(opts.employee);
+
+    if (opts.json) {
+      console.log(JSON.stringify(benefits, null, 2));
+    } else {
+      if (benefits.length === 0) {
+        console.log("No benefits found.");
+        return;
+      }
+      for (const b of benefits) {
+        const status = b.active ? "" : " [INACTIVE]";
+        console.log(`  ${b.type} — $${b.amount}/${b.frequency} (${b.employee_id})${status}`);
+      }
+      console.log(`\n${benefits.length} benefit(s)`);
+    }
+  });
+
+benefitCmd
+  .command("remove")
+  .description("Deactivate a benefit")
+  .argument("<id>", "Benefit ID")
+  .option("--json", "Output as JSON", false)
+  .action((id, opts) => {
+    const removed = removeBenefit(id);
+    if (opts.json) {
+      console.log(JSON.stringify({ removed }));
+    } else {
+      console.log(removed ? `Benefit ${id} deactivated.` : `Benefit '${id}' not found.`);
+    }
+  });
+
+// --- ACH File Generation ---
+
+program
+  .command("generate-ach")
+  .description("Generate NACHA-format ACH file for a pay period")
+  .requiredOption("--period <id>", "Pay period ID")
+  .requiredOption("--routing <number>", "Bank routing number")
+  .requiredOption("--account <number>", "Bank account number")
+  .option("--company <name>", "Company name", "PAYROLL CO")
+  .action((opts) => {
+    try {
+      const achContent = generateAchFile(opts.period, opts.routing, opts.account, opts.company);
+      console.log(achContent);
+    } catch (error) {
+      console.error(`Error: ${error instanceof Error ? error.message : String(error)}`);
+      process.exit(1);
+    }
+  });
+
+// --- W-2 Generation ---
+
+program
+  .command("w2")
+  .description("Generate W-2 data for an employee")
+  .requiredOption("--year <year>", "Tax year")
+  .requiredOption("--employee <id>", "Employee ID")
+  .option("--json", "Output as JSON", false)
+  .action((opts) => {
+    const w2 = generateW2(opts.employee, parseInt(opts.year));
+    if (!w2) {
+      console.error("No W-2 data found (employee not found, is a contractor, or has no pay stubs).");
+      process.exit(1);
+    }
+
+    if (opts.json) {
+      console.log(JSON.stringify(w2, null, 2));
+    } else {
+      console.log(`W-2 for ${w2.employee_name} (${w2.year})`);
+      console.log(`  Gross Wages: $${w2.gross}`);
+      console.log(`  Federal Tax Withheld: $${w2.federal_withheld}`);
+      console.log(`  State Tax Withheld: $${w2.state_withheld}`);
+      console.log(`  Social Security: $${w2.social_security}`);
+      console.log(`  Medicare: $${w2.medicare}`);
+    }
+  });
+
+// --- 1099-NEC Generation ---
+
+program
+  .command("1099")
+  .description("Generate 1099-NEC data for contractors")
+  .requiredOption("--year <year>", "Tax year")
+  .option("--employee <id>", "Specific contractor ID (optional)")
+  .option("--json", "Output as JSON", false)
+  .action((opts) => {
+    const forms = generate1099(opts.employee || null, parseInt(opts.year));
+
+    if (opts.json) {
+      console.log(JSON.stringify(forms, null, 2));
+    } else {
+      if (forms.length === 0) {
+        console.log("No 1099-NEC forms to generate (no contractors with >$600 compensation).");
+        return;
+      }
+      for (const f of forms) {
+        console.log(`  ${f.employee_name}: $${f.total_compensation} (${f.year})`);
+      }
+      console.log(`\n${forms.length} form(s)`);
+    }
+  });
+
+// --- Payroll Schedule ---
+
+const scheduleCmd = program
+  .command("schedule")
+  .description("Payroll schedule management");
+
+scheduleCmd
+  .command("set")
+  .description("Set the payroll schedule")
+  .requiredOption("--frequency <freq>", "Frequency: weekly, biweekly, semimonthly, monthly")
+  .requiredOption("--anchor <date>", "Anchor date (YYYY-MM-DD)")
+  .option("--json", "Output as JSON", false)
+  .action((opts) => {
+    const schedule = setSchedule(opts.frequency, opts.anchor);
+
+    if (opts.json) {
+      console.log(JSON.stringify(schedule, null, 2));
+    } else {
+      console.log(`Schedule set: ${schedule.frequency} starting ${schedule.anchor_date}`);
+    }
+  });
+
+scheduleCmd
+  .command("next")
+  .description("Get the next pay period dates based on schedule")
+  .option("--json", "Output as JSON", false)
+  .action((opts) => {
+    const next = getNextPayPeriod();
+    if (!next) {
+      console.error("No payroll schedule configured. Use 'schedule set' first.");
+      process.exit(1);
+    }
+
+    if (opts.json) {
+      console.log(JSON.stringify(next, null, 2));
+    } else {
+      console.log(`Next pay period: ${next.start_date} to ${next.end_date}`);
+    }
+  });
+
+// --- Audit ---
+
+program
+  .command("audit")
+  .description("Audit a payroll period for issues")
+  .requiredOption("--period <id>", "Pay period ID")
+  .option("--json", "Output as JSON", false)
+  .action((opts) => {
+    try {
+      const result = auditPayroll(opts.period);
+
+      if (opts.json) {
+        console.log(JSON.stringify(result, null, 2));
+      } else {
+        if (result.passed) {
+          console.log("PASSED — No issues found.");
+        } else {
+          console.log(`FAILED — ${result.issues.length} issue(s):`);
+          for (const issue of result.issues) {
+            console.log(`  - ${issue}`);
+          }
+        }
+      }
+    } catch (error) {
+      console.error(`Error: ${error instanceof Error ? error.message : String(error)}`);
+      process.exit(1);
+    }
+  });
+
+// --- Forecast ---
+
+program
+  .command("forecast")
+  .description("Forecast future payroll costs")
+  .option("--months <n>", "Number of months to forecast", "3")
+  .option("--json", "Output as JSON", false)
+  .action((opts) => {
+    const result = forecastPayroll(parseInt(opts.months));
+
+    if (opts.json) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      console.log(`Payroll Forecast (${result.months} months):`);
+      for (const p of result.periods) {
+        console.log(`  ${p.month}: gross=$${p.estimated_gross} deductions=$${p.estimated_deductions} net=$${p.estimated_net}`);
+      }
+      console.log(`\nTotal: gross=$${result.total_estimated_gross} deductions=$${result.total_estimated_deductions} net=$${result.total_estimated_net}`);
+    }
+  });
+
+// --- Overtime Check ---
+
+program
+  .command("overtime-check")
+  .description("Check for employees exceeding weekly hours threshold")
+  .option("--threshold <hours>", "Hours threshold", "40")
+  .option("--json", "Output as JSON", false)
+  .action((opts) => {
+    const alerts = checkOvertime(parseFloat(opts.threshold));
+
+    if (opts.json) {
+      console.log(JSON.stringify(alerts, null, 2));
+    } else {
+      if (alerts.length === 0) {
+        console.log("No overtime alerts.");
+        return;
+      }
+      for (const a of alerts) {
+        console.log(`  ${a.employee_name}: ${a.total_hours}h total (${a.overtime_hours}h over ${a.threshold}h threshold)`);
+      }
+      console.log(`\n${alerts.length} alert(s)`);
+    }
+  });
+
 program.parse(process.argv);

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

@@ -66,4 +66,30 @@ export const MIGRATIONS: MigrationEntry[] = [
       CREATE INDEX IF NOT EXISTS idx_payments_status ON payments(status);
     `,
   },
+  {
+    id: 2,
+    name: "benefits_and_schedule",
+    sql: `
+      CREATE TABLE IF NOT EXISTS benefits (
+        id TEXT PRIMARY KEY,
+        employee_id TEXT NOT NULL REFERENCES employees(id) ON DELETE CASCADE,
+        type TEXT NOT NULL CHECK (type IN ('health', 'dental', 'vision', 'retirement', 'hsa', 'other')),
+        description TEXT,
+        amount REAL NOT NULL,
+        frequency TEXT NOT NULL DEFAULT 'per_period' CHECK (frequency IN ('per_period', 'monthly', 'annual')),
+        active INTEGER NOT NULL DEFAULT 1,
+        created_at TEXT NOT NULL DEFAULT (datetime('now'))
+      );
+
+      CREATE TABLE IF NOT EXISTS payroll_schedule (
+        id TEXT PRIMARY KEY,
+        frequency TEXT NOT NULL CHECK (frequency IN ('weekly', 'biweekly', 'semimonthly', 'monthly')),
+        anchor_date TEXT NOT NULL,
+        created_at TEXT NOT NULL DEFAULT (datetime('now'))
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_benefits_employee ON benefits(employee_id);
+      CREATE INDEX IF NOT EXISTS idx_benefits_active ON benefits(active);
+    `,
+  },
 ];