@hasna/microservices 0.0.4 → 0.0.5

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

@@ -23,6 +23,17 @@ import {
   getPayrollReport,
   getYtdReport,
   getTaxSummary,
+  createBenefit,
+  listBenefits,
+  removeBenefit,
+  generateAchFile,
+  generateW2,
+  generate1099,
+  setSchedule,
+  getNextPayPeriod,
+  auditPayroll,
+  forecastPayroll,
+  checkOvertime,
 } from "../db/payroll.js";
 
 const server = new McpServer({
@@ -407,6 +418,241 @@ server.registerTool(
   }
 );
 
+// --- Benefits ---
+
+server.registerTool(
+  "create_benefit",
+  {
+    title: "Create Benefit",
+    description: "Add a benefit deduction to an employee (health, dental, vision, retirement, hsa, other).",
+    inputSchema: {
+      employee_id: z.string(),
+      type: z.enum(["health", "dental", "vision", "retirement", "hsa", "other"]),
+      description: z.string().optional(),
+      amount: z.number(),
+      frequency: z.enum(["per_period", "monthly", "annual"]).optional(),
+    },
+  },
+  async (params) => {
+    try {
+      const benefit = createBenefit(params);
+      return { content: [{ type: "text", text: JSON.stringify(benefit, null, 2) }] };
+    } catch (error) {
+      return {
+        content: [{ type: "text", text: `Error: ${error instanceof Error ? error.message : String(error)}` }],
+        isError: true,
+      };
+    }
+  }
+);
+
+server.registerTool(
+  "list_benefits",
+  {
+    title: "List Benefits",
+    description: "List benefit deductions, optionally filtered by employee.",
+    inputSchema: {
+      employee_id: z.string().optional(),
+    },
+  },
+  async ({ employee_id }) => {
+    const benefits = listBenefits(employee_id);
+    return {
+      content: [
+        { type: "text", text: JSON.stringify({ benefits, count: benefits.length }, null, 2) },
+      ],
+    };
+  }
+);
+
+server.registerTool(
+  "remove_benefit",
+  {
+    title: "Remove Benefit",
+    description: "Deactivate a benefit by ID.",
+    inputSchema: { id: z.string() },
+  },
+  async ({ id }) => {
+    const removed = removeBenefit(id);
+    if (!removed) {
+      return { content: [{ type: "text", text: `Benefit '${id}' not found.` }], isError: true };
+    }
+    return { content: [{ type: "text", text: JSON.stringify({ removed: true, id }) }] };
+  }
+);
+
+// --- ACH File Generation ---
+
+server.registerTool(
+  "generate_ach_file",
+  {
+    title: "Generate ACH File",
+    description: "Generate a NACHA-format ACH file for a completed pay period.",
+    inputSchema: {
+      period_id: z.string(),
+      bank_routing: z.string(),
+      bank_account: z.string(),
+      company_name: z.string().optional(),
+    },
+  },
+  async ({ period_id, bank_routing, bank_account, company_name }) => {
+    try {
+      const content = generateAchFile(period_id, bank_routing, bank_account, company_name);
+      return { content: [{ type: "text", text: content }] };
+    } catch (error) {
+      return {
+        content: [{ type: "text", text: `Error: ${error instanceof Error ? error.message : String(error)}` }],
+        isError: true,
+      };
+    }
+  }
+);
+
+// --- W-2 ---
+
+server.registerTool(
+  "generate_w2",
+  {
+    title: "Generate W-2",
+    description: "Generate W-2 data for an employee for a given tax year.",
+    inputSchema: {
+      employee_id: z.string(),
+      year: z.number(),
+    },
+  },
+  async ({ employee_id, year }) => {
+    const w2 = generateW2(employee_id, year);
+    if (!w2) {
+      return {
+        content: [{ type: "text", text: "No W-2 data found (employee not found, is a contractor, or has no pay stubs)." }],
+        isError: true,
+      };
+    }
+    return { content: [{ type: "text", text: JSON.stringify(w2, null, 2) }] };
+  }
+);
+
+// --- 1099-NEC ---
+
+server.registerTool(
+  "generate_1099",
+  {
+    title: "Generate 1099-NEC",
+    description: "Generate 1099-NEC data for contractors with >$600 compensation in a given year.",
+    inputSchema: {
+      employee_id: z.string().optional(),
+      year: z.number(),
+    },
+  },
+  async ({ employee_id, year }) => {
+    const forms = generate1099(employee_id || null, year);
+    return {
+      content: [
+        { type: "text", text: JSON.stringify({ forms, count: forms.length }, null, 2) },
+      ],
+    };
+  }
+);
+
+// --- Payroll Schedule ---
+
+server.registerTool(
+  "set_schedule",
+  {
+    title: "Set Payroll Schedule",
+    description: "Set the payroll schedule frequency and anchor date.",
+    inputSchema: {
+      frequency: z.enum(["weekly", "biweekly", "semimonthly", "monthly"]),
+      anchor_date: z.string(),
+    },
+  },
+  async ({ frequency, anchor_date }) => {
+    const schedule = setSchedule(frequency, anchor_date);
+    return { content: [{ type: "text", text: JSON.stringify(schedule, null, 2) }] };
+  }
+);
+
+server.registerTool(
+  "next_pay_period",
+  {
+    title: "Next Pay Period",
+    description: "Get the next pay period dates based on the configured payroll schedule.",
+    inputSchema: {},
+  },
+  async () => {
+    const next = getNextPayPeriod();
+    if (!next) {
+      return {
+        content: [{ type: "text", text: "No payroll schedule configured. Use set_schedule first." }],
+        isError: true,
+      };
+    }
+    return { content: [{ type: "text", text: JSON.stringify(next, null, 2) }] };
+  }
+);
+
+// --- Audit ---
+
+server.registerTool(
+  "audit_payroll",
+  {
+    title: "Audit Payroll",
+    description: "Audit a payroll period for issues: missing stubs, bad net_pay, deduction mismatches, duplicates.",
+    inputSchema: {
+      period_id: z.string(),
+    },
+  },
+  async ({ period_id }) => {
+    try {
+      const result = auditPayroll(period_id);
+      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    } catch (error) {
+      return {
+        content: [{ type: "text", text: `Error: ${error instanceof Error ? error.message : String(error)}` }],
+        isError: true,
+      };
+    }
+  }
+);
+
+// --- Forecast ---
+
+server.registerTool(
+  "forecast_payroll",
+  {
+    title: "Forecast Payroll",
+    description: "Project future payroll costs for a given number of months.",
+    inputSchema: {
+      months: z.number().min(1).max(60),
+    },
+  },
+  async ({ months }) => {
+    const result = forecastPayroll(months);
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+  }
+);
+
+// --- Overtime ---
+
+server.registerTool(
+  "check_overtime",
+  {
+    title: "Check Overtime",
+    description: "Flag employees exceeding a weekly hours threshold in the most recent completed period.",
+    inputSchema: {
+      threshold: z.number().optional(),
+    },
+  },
+  async ({ threshold }) => {
+    const alerts = checkOvertime(threshold);
+    return {
+      content: [
+        { type: "text", text: JSON.stringify({ alerts, count: alerts.length }, null, 2) },
+      ],
+    };
+  }
+);
+
 // --- Start ---
 async function main() {
   const transport = new StdioServerTransport();

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

@@ -1,6 +1,7 @@
 #!/usr/bin/env bun
 
 import { Command } from "commander";
+import { readFileSync } from "node:fs";
 import {
   createOrder,
   getOrder,
@@ -9,6 +10,9 @@ import {
   deleteOrder,
   searchOrders,
   listByStatus,
+  bulkImportOrders,
+  exportOrders,
+  getOrderTimeline,
 } from "../db/shipping.js";
 import {
   createShipment,
@@ -25,6 +29,11 @@ import {
 import {
   getShippingStats,
   getCostsByCarrier,
+  getDeliveryStats,
+  listOverdueShipments,
+  getCustomerHistory,
+  getCarrierPerformance,
+  optimizeCost,
 } from "../db/shipping.js";
 
 const program = new Command();
@@ -152,6 +161,61 @@ orderCmd
     }
   });
 
+orderCmd
+  .command("import")
+  .description("Bulk import orders from a CSV file")
+  .requiredOption("--file <path>", "Path to CSV file")
+  .option("--json", "Output as JSON", false)
+  .action((opts) => {
+    const csvData = readFileSync(opts.file, "utf-8");
+    const result = bulkImportOrders(csvData);
+
+    if (opts.json) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      console.log(`Imported ${result.imported} order(s)`);
+      if (result.errors.length > 0) {
+        console.log(`Errors:`);
+        for (const err of result.errors) {
+          console.log(`  Line ${err.line}: ${err.message}`);
+        }
+      }
+    }
+  });
+
+orderCmd
+  .command("export")
+  .description("Export orders to CSV or JSON")
+  .option("--format <format>", "Output format (csv/json)", "csv")
+  .option("--from <date>", "Filter from date (YYYY-MM-DD)")
+  .option("--to <date>", "Filter to date (YYYY-MM-DD)")
+  .action((opts) => {
+    const output = exportOrders(opts.format as "csv" | "json", opts.from, opts.to);
+    console.log(output);
+  });
+
+orderCmd
+  .command("timeline")
+  .description("Show full event timeline for an order")
+  .argument("<id>", "Order ID")
+  .option("--json", "Output as JSON", false)
+  .action((id, opts) => {
+    const timeline = getOrderTimeline(id);
+    if (timeline.length === 0) {
+      console.error(`No events found for order '${id}'.`);
+      process.exit(1);
+    }
+
+    if (opts.json) {
+      console.log(JSON.stringify(timeline, null, 2));
+    } else {
+      console.log(`Timeline for order ${id}:`);
+      for (const event of timeline) {
+        console.log(`  [${event.timestamp}] ${event.type}: ${event.details}`);
+      }
+    }
+  });
+
 // --- Ship (create shipment) ---
 
 program
@@ -259,17 +323,20 @@ returnCmd
   .description("Create a return request")
   .requiredOption("--order <id>", "Order ID")
   .option("--reason <reason>", "Return reason")
+  .option("--auto-rma", "Auto-generate RMA code", false)
   .option("--json", "Output as JSON", false)
   .action((opts) => {
     const ret = createReturn({
       order_id: opts.order,
       reason: opts.reason,
+      auto_rma: opts.autoRma,
     });
 
     if (opts.json) {
       console.log(JSON.stringify(ret, null, 2));
     } else {
       console.log(`Created return: ${ret.id} for order ${ret.order_id} [${ret.status}]`);
+      if (ret.rma_code) console.log(`  RMA Code: ${ret.rma_code}`);
     }
   });
 
@@ -347,9 +414,11 @@ program
 
 // --- Stats ---
 
-program
-  .command("stats")
-  .description("Show shipping statistics")
+const statsCmd = program.command("stats").description("Shipping statistics and analytics");
+
+statsCmd
+  .command("overview")
+  .description("Show overall shipping statistics")
   .option("--json", "Output as JSON", false)
   .action((opts) => {
     const stats = getShippingStats();
@@ -372,6 +441,56 @@ program
     }
   });
 
+statsCmd
+  .command("delivery-times")
+  .description("Delivery timeline analytics per carrier/service")
+  .option("--carrier <carrier>", "Filter by carrier")
+  .option("--json", "Output as JSON", false)
+  .action((opts) => {
+    const stats = getDeliveryStats(opts.carrier);
+
+    if (opts.json) {
+      console.log(JSON.stringify(stats, null, 2));
+    } else {
+      if (stats.length === 0) {
+        console.log("No delivery data available (need shipments with shipped_at and delivered_at).");
+        return;
+      }
+      console.log("Delivery Timeline Analytics:");
+      for (const s of stats) {
+        console.log(`  ${s.carrier.toUpperCase()}/${s.service}:`);
+        console.log(`    Shipments: ${s.total_shipments} (${s.delivered_count} delivered)`);
+        console.log(`    Avg delivery: ${s.avg_delivery_days.toFixed(1)} days`);
+        console.log(`    On-time: ${s.on_time_pct.toFixed(1)}%, Late: ${s.late_pct.toFixed(1)}%`);
+      }
+    }
+  });
+
+statsCmd
+  .command("carrier-performance")
+  .description("Rank carriers by on-time %, avg cost, avg delivery days")
+  .option("--json", "Output as JSON", false)
+  .action((opts) => {
+    const perf = getCarrierPerformance();
+
+    if (opts.json) {
+      console.log(JSON.stringify(perf, null, 2));
+    } else {
+      if (perf.length === 0) {
+        console.log("No carrier data available.");
+        return;
+      }
+      console.log("Carrier Performance (ranked by on-time %):");
+      for (const p of perf) {
+        console.log(`  ${p.carrier.toUpperCase()}:`);
+        console.log(`    Shipments: ${p.total_shipments} (${p.delivered_count} delivered)`);
+        console.log(`    On-time: ${p.on_time_pct.toFixed(1)}%`);
+        console.log(`    Avg cost: $${p.avg_cost.toFixed(2)}`);
+        console.log(`    Avg delivery: ${p.avg_delivery_days.toFixed(1)} days`);
+      }
+    }
+  });
+
 // --- Costs ---
 
 program
@@ -395,4 +514,93 @@ program
     }
   });
 
+// --- Late Delivery Alerts ---
+
+program
+  .command("check-late")
+  .description("List overdue shipments past estimated delivery + grace days")
+  .option("--days <n>", "Grace days beyond estimated delivery", "0")
+  .option("--json", "Output as JSON", false)
+  .action((opts) => {
+    const overdue = listOverdueShipments(parseInt(opts.days));
+
+    if (opts.json) {
+      console.log(JSON.stringify(overdue, null, 2));
+    } else {
+      if (overdue.length === 0) {
+        console.log("No overdue shipments found.");
+        return;
+      }
+      console.log(`Overdue Shipments (grace: ${opts.days} day(s)):`);
+      for (const s of overdue) {
+        const tracking = s.tracking_number ? ` (${s.tracking_number})` : "";
+        console.log(`  ${s.shipment_id.slice(0, 8)}... ${s.carrier}/${s.service}${tracking}`);
+        console.log(`    ETA: ${s.estimated_delivery}, ${s.days_overdue} day(s) overdue [${s.status}]`);
+      }
+      console.log(`\n${overdue.length} overdue shipment(s)`);
+    }
+  });
+
+// --- Customer History ---
+
+program
+  .command("customer-history")
+  .description("Show all orders, shipments, and returns for a customer")
+  .argument("<email>", "Customer email")
+  .option("--json", "Output as JSON", false)
+  .action((email, opts) => {
+    const history = getCustomerHistory(email);
+
+    if (opts.json) {
+      console.log(JSON.stringify(history, null, 2));
+    } else {
+      console.log(`Customer History for ${email}:`);
+      console.log(`  Orders: ${history.orders.length}`);
+      for (const o of history.orders) {
+        console.log(`    [${o.status}] ${o.id.slice(0, 8)}... $${o.total_value} ${o.currency}`);
+      }
+      console.log(`  Shipments: ${history.shipments.length}`);
+      for (const s of history.shipments) {
+        console.log(`    [${s.status}] ${s.id.slice(0, 8)}... ${s.carrier}/${s.service}`);
+      }
+      console.log(`  Returns: ${history.returns.length}`);
+      for (const r of history.returns) {
+        const rma = r.rma_code ? ` (${r.rma_code})` : "";
+        console.log(`    [${r.status}] ${r.id.slice(0, 8)}...${rma}`);
+      }
+    }
+  });
+
+// --- Cost Optimizer ---
+
+program
+  .command("optimize-cost")
+  .description("Recommend cheapest carrier/service based on historical data")
+  .requiredOption("--weight <kg>", "Package weight in kg")
+  .option("--from <zip>", "Origin zip code")
+  .option("--to <zip>", "Destination zip code")
+  .option("--json", "Output as JSON", false)
+  .action((opts) => {
+    const recommendations = optimizeCost(
+      parseFloat(opts.weight),
+      opts.from,
+      opts.to
+    );
+
+    if (opts.json) {
+      console.log(JSON.stringify(recommendations, null, 2));
+    } else {
+      if (recommendations.length === 0) {
+        console.log("No historical shipping data found for the given weight range.");
+        return;
+      }
+      console.log(`Cost recommendations for ${opts.weight}kg package:`);
+      for (let i = 0; i < recommendations.length; i++) {
+        const r = recommendations[i];
+        const deliveryInfo = r.avg_delivery_days ? `, ~${r.avg_delivery_days.toFixed(1)} days` : "";
+        console.log(`  ${i + 1}. ${r.carrier.toUpperCase()}/${r.service}: $${r.avg_cost.toFixed(2)} avg (${r.shipment_count} samples${deliveryInfo})`);
+      }
+    }
+  });
+
 program.parse(process.argv);

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

@@ -58,4 +58,12 @@ export const MIGRATIONS: MigrationEntry[] = [
       CREATE INDEX IF NOT EXISTS idx_returns_status ON returns(status);
     `,
   },
+  {
+    id: 2,
+    name: "add_rma_code",
+    sql: `
+      ALTER TABLE returns ADD COLUMN rma_code TEXT;
+      CREATE UNIQUE INDEX IF NOT EXISTS idx_returns_rma_code ON returns(rma_code);
+    `,
+  },
 ];