@hasna/microservices 0.0.4 → 0.0.6

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

@@ -83,6 +83,7 @@ export interface Return {
   id: string;
   order_id: string;
   reason: string | null;
+  rma_code: string | null;
   status: "requested" | "approved" | "received" | "refunded";
   created_at: string;
   updated_at: string;
@@ -92,6 +93,7 @@ interface ReturnRow {
   id: string;
   order_id: string;
   reason: string | null;
+  rma_code: string | null;
   status: string;
   created_at: string;
   updated_at: string;
@@ -476,20 +478,32 @@ export interface CreateReturnInput {
   order_id: string;
   reason?: string;
   status?: Return["status"];
+  auto_rma?: boolean;
+}
+
+function generateRmaCode(): string {
+  const chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789";
+  let code = "RMA-";
+  for (let i = 0; i < 8; i++) {
+    code += chars.charAt(Math.floor(Math.random() * chars.length));
+  }
+  return code;
 }
 
 export function createReturn(input: CreateReturnInput): Return {
   const db = getDatabase();
   const id = crypto.randomUUID();
+  const rmaCode = input.auto_rma ? generateRmaCode() : null;
 
   db.prepare(
-    `INSERT INTO returns (id, order_id, reason, status)
-     VALUES (?, ?, ?, ?)`
+    `INSERT INTO returns (id, order_id, reason, status, rma_code)
+     VALUES (?, ?, ?, ?, ?)`
   ).run(
     id,
     input.order_id,
     input.reason || null,
-    input.status || "requested"
+    input.status || "requested",
+    rmaCode
   );
 
   return getReturn(id)!;
@@ -641,3 +655,439 @@ export function getCostsByCarrier(): CarrierCosts[] {
   ).all() as CarrierCosts[];
   return rows;
 }
+
+// ─── Bulk Import/Export ─────────────────────────────────────────────────────
+
+export interface BulkImportResult {
+  imported: number;
+  errors: { line: number; message: string }[];
+}
+
+export function bulkImportOrders(csvData: string): BulkImportResult {
+  const lines = csvData.trim().split("\n");
+  if (lines.length < 2) return { imported: 0, errors: [{ line: 1, message: "No data rows found" }] };
+
+  const header = lines[0].split(",").map((h) => h.trim().toLowerCase());
+  const result: BulkImportResult = { imported: 0, errors: [] };
+
+  for (let i = 1; i < lines.length; i++) {
+    try {
+      const values = parseCSVLine(lines[i]);
+      const row: Record<string, string> = {};
+      header.forEach((h, idx) => {
+        row[h] = (values[idx] || "").trim();
+      });
+
+      const address: Address = {
+        street: row["street"] || "",
+        city: row["city"] || "",
+        state: row["state"] || "",
+        zip: row["zip"] || "",
+        country: row["country"] || "US",
+      };
+
+      let items: OrderItem[] = [];
+      if (row["items_json"]) {
+        try {
+          items = JSON.parse(row["items_json"]);
+        } catch {
+          items = [];
+        }
+      }
+
+      createOrder({
+        customer_name: row["customer_name"] || "Unknown",
+        customer_email: row["customer_email"] || undefined,
+        address,
+        items,
+        total_value: row["total_value"] ? parseFloat(row["total_value"]) : undefined,
+      });
+
+      result.imported++;
+    } catch (err) {
+      result.errors.push({
+        line: i + 1,
+        message: err instanceof Error ? err.message : String(err),
+      });
+    }
+  }
+
+  return result;
+}
+
+function parseCSVLine(line: string): string[] {
+  const result: string[] = [];
+  let current = "";
+  let inQuotes = false;
+
+  for (let i = 0; i < line.length; i++) {
+    const ch = line[i];
+    if (inQuotes) {
+      if (ch === '"' && line[i + 1] === '"') {
+        current += '"';
+        i++;
+      } else if (ch === '"') {
+        inQuotes = false;
+      } else {
+        current += ch;
+      }
+    } else {
+      if (ch === '"') {
+        inQuotes = true;
+      } else if (ch === ",") {
+        result.push(current);
+        current = "";
+      } else {
+        current += ch;
+      }
+    }
+  }
+  result.push(current);
+  return result;
+}
+
+export function exportOrders(
+  format: "csv" | "json",
+  dateFrom?: string,
+  dateTo?: string
+): string {
+  const db = getDatabase();
+  const conditions: string[] = [];
+  const params: unknown[] = [];
+
+  if (dateFrom) {
+    conditions.push("created_at >= ?");
+    params.push(dateFrom);
+  }
+  if (dateTo) {
+    conditions.push("created_at <= ?");
+    params.push(dateTo);
+  }
+
+  let sql = "SELECT * FROM orders";
+  if (conditions.length > 0) {
+    sql += " WHERE " + conditions.join(" AND ");
+  }
+  sql += " ORDER BY created_at DESC";
+
+  const rows = db.prepare(sql).all(...params) as OrderRow[];
+  const orders = rows.map(rowToOrder);
+
+  if (format === "json") {
+    return JSON.stringify(orders, null, 2);
+  }
+
+  // CSV format
+  const csvHeader = "id,customer_name,customer_email,street,city,state,zip,country,items_json,total_value,currency,status,created_at";
+  const csvRows = orders.map((o) => {
+    const itemsJson = JSON.stringify(o.items).replace(/"/g, '""');
+    return [
+      o.id,
+      escapeCSV(o.customer_name),
+      o.customer_email || "",
+      escapeCSV(o.address.street),
+      escapeCSV(o.address.city),
+      escapeCSV(o.address.state),
+      o.address.zip,
+      o.address.country,
+      `"${itemsJson}"`,
+      o.total_value.toString(),
+      o.currency,
+      o.status,
+      o.created_at,
+    ].join(",");
+  });
+
+  return [csvHeader, ...csvRows].join("\n");
+}
+
+function escapeCSV(value: string): string {
+  if (value.includes(",") || value.includes('"') || value.includes("\n")) {
+    return `"${value.replace(/"/g, '""')}"`;
+  }
+  return value;
+}
+
+// ─── Delivery Timeline Analytics ────────────────────────────────────────────
+
+export interface DeliveryStats {
+  carrier: string;
+  service: string;
+  total_shipments: number;
+  delivered_count: number;
+  avg_delivery_days: number;
+  on_time_pct: number;
+  late_pct: number;
+}
+
+export function getDeliveryStats(carrier?: string): DeliveryStats[] {
+  const db = getDatabase();
+  const conditions: string[] = ["delivered_at IS NOT NULL", "shipped_at IS NOT NULL"];
+  const params: unknown[] = [];
+
+  if (carrier) {
+    conditions.push("carrier = ?");
+    params.push(carrier);
+  }
+
+  const sql = `
+    SELECT
+      carrier,
+      service,
+      COUNT(*) as total_shipments,
+      SUM(CASE WHEN status = 'delivered' THEN 1 ELSE 0 END) as delivered_count,
+      AVG(julianday(delivered_at) - julianday(shipped_at)) as avg_delivery_days,
+      SUM(CASE WHEN estimated_delivery IS NOT NULL AND delivered_at <= estimated_delivery THEN 1 ELSE 0 END) * 100.0 / COUNT(*) as on_time_pct,
+      SUM(CASE WHEN estimated_delivery IS NOT NULL AND delivered_at > estimated_delivery THEN 1 ELSE 0 END) * 100.0 / COUNT(*) as late_pct
+    FROM shipments
+    WHERE ${conditions.join(" AND ")}
+    GROUP BY carrier, service
+    ORDER BY carrier, service
+  `;
+
+  return db.prepare(sql).all(...params) as DeliveryStats[];
+}
+
+// ─── Late Delivery Alerts ───────────────────────────────────────────────────
+
+export interface OverdueShipment {
+  shipment_id: string;
+  order_id: string;
+  carrier: string;
+  service: string;
+  tracking_number: string | null;
+  estimated_delivery: string;
+  days_overdue: number;
+  status: string;
+}
+
+export function listOverdueShipments(graceDays: number = 0): OverdueShipment[] {
+  const db = getDatabase();
+
+  const sql = `
+    SELECT
+      id as shipment_id,
+      order_id,
+      carrier,
+      service,
+      tracking_number,
+      estimated_delivery,
+      CAST(julianday('now') - julianday(estimated_delivery) - ? AS INTEGER) as days_overdue,
+      status
+    FROM shipments
+    WHERE estimated_delivery IS NOT NULL
+      AND status != 'delivered'
+      AND julianday('now') > julianday(estimated_delivery) + ?
+    ORDER BY days_overdue DESC
+  `;
+
+  return db.prepare(sql).all(graceDays, graceDays) as OverdueShipment[];
+}
+
+// ─── Customer History ───────────────────────────────────────────────────────
+
+export interface CustomerHistory {
+  customer_email: string;
+  orders: Order[];
+  shipments: Shipment[];
+  returns: Return[];
+}
+
+export function getCustomerHistory(email: string): CustomerHistory {
+  const db = getDatabase();
+
+  const orderRows = db.prepare(
+    "SELECT * FROM orders WHERE customer_email = ? ORDER BY created_at DESC"
+  ).all(email) as OrderRow[];
+  const orders = orderRows.map(rowToOrder);
+
+  const orderIds = orders.map((o) => o.id);
+  let shipments: Shipment[] = [];
+  let returns: Return[] = [];
+
+  if (orderIds.length > 0) {
+    const placeholders = orderIds.map(() => "?").join(",");
+
+    const shipmentRows = db.prepare(
+      `SELECT * FROM shipments WHERE order_id IN (${placeholders}) ORDER BY created_at DESC`
+    ).all(...orderIds) as ShipmentRow[];
+    shipments = shipmentRows.map(rowToShipment);
+
+    const returnRows = db.prepare(
+      `SELECT * FROM returns WHERE order_id IN (${placeholders}) ORDER BY created_at DESC`
+    ).all(...orderIds) as ReturnRow[];
+    returns = returnRows.map(rowToReturn);
+  }
+
+  return { customer_email: email, orders, shipments, returns };
+}
+
+// ─── Carrier Performance ────────────────────────────────────────────────────
+
+export interface CarrierPerformance {
+  carrier: string;
+  total_shipments: number;
+  delivered_count: number;
+  on_time_pct: number;
+  avg_cost: number;
+  avg_delivery_days: number;
+}
+
+export function getCarrierPerformance(): CarrierPerformance[] {
+  const db = getDatabase();
+
+  const sql = `
+    SELECT
+      carrier,
+      COUNT(*) as total_shipments,
+      SUM(CASE WHEN status = 'delivered' THEN 1 ELSE 0 END) as delivered_count,
+      COALESCE(
+        SUM(CASE WHEN estimated_delivery IS NOT NULL AND delivered_at IS NOT NULL AND delivered_at <= estimated_delivery THEN 1 ELSE 0 END) * 100.0
+        / NULLIF(SUM(CASE WHEN estimated_delivery IS NOT NULL AND delivered_at IS NOT NULL THEN 1 ELSE 0 END), 0),
+        0
+      ) as on_time_pct,
+      COALESCE(AVG(cost), 0) as avg_cost,
+      COALESCE(
+        AVG(CASE WHEN delivered_at IS NOT NULL AND shipped_at IS NOT NULL THEN julianday(delivered_at) - julianday(shipped_at) END),
+        0
+      ) as avg_delivery_days
+    FROM shipments
+    GROUP BY carrier
+    ORDER BY on_time_pct DESC
+  `;
+
+  return db.prepare(sql).all() as CarrierPerformance[];
+}
+
+// ─── Cost Optimizer ─────────────────────────────────────────────────────────
+
+export interface CostRecommendation {
+  carrier: string;
+  service: string;
+  avg_cost: number;
+  avg_delivery_days: number;
+  shipment_count: number;
+}
+
+export function optimizeCost(
+  weight: number,
+  _fromZip?: string,
+  _toZip?: string
+): CostRecommendation[] {
+  const db = getDatabase();
+
+  // Find historical shipments with similar weight (within 50% range)
+  const minWeight = weight * 0.5;
+  const maxWeight = weight * 1.5;
+
+  const sql = `
+    SELECT
+      carrier,
+      service,
+      AVG(cost) as avg_cost,
+      AVG(CASE WHEN delivered_at IS NOT NULL AND shipped_at IS NOT NULL THEN julianday(delivered_at) - julianday(shipped_at) END) as avg_delivery_days,
+      COUNT(*) as shipment_count
+    FROM shipments
+    WHERE cost IS NOT NULL
+      AND weight IS NOT NULL
+      AND weight BETWEEN ? AND ?
+    GROUP BY carrier, service
+    HAVING shipment_count >= 1
+    ORDER BY avg_cost ASC
+  `;
+
+  return db.prepare(sql).all(minWeight, maxWeight) as CostRecommendation[];
+}
+
+// ─── Order Timeline ─────────────────────────────────────────────────────────
+
+export interface TimelineEvent {
+  timestamp: string;
+  type: "order_created" | "order_updated" | "shipment_created" | "shipment_updated" | "return_created" | "return_updated";
+  entity_id: string;
+  details: string;
+}
+
+export function getOrderTimeline(orderId: string): TimelineEvent[] {
+  const db = getDatabase();
+  const events: TimelineEvent[] = [];
+
+  // Order creation
+  const order = db.prepare("SELECT * FROM orders WHERE id = ?").get(orderId) as OrderRow | null;
+  if (!order) return [];
+
+  events.push({
+    timestamp: order.created_at,
+    type: "order_created",
+    entity_id: order.id,
+    details: `Order created for ${order.customer_name} — $${order.total_value} ${order.currency} [${order.status}]`,
+  });
+
+  if (order.updated_at !== order.created_at) {
+    events.push({
+      timestamp: order.updated_at,
+      type: "order_updated",
+      entity_id: order.id,
+      details: `Order updated — status: ${order.status}`,
+    });
+  }
+
+  // Shipments
+  const shipmentRows = db.prepare(
+    "SELECT * FROM shipments WHERE order_id = ? ORDER BY created_at ASC"
+  ).all(orderId) as ShipmentRow[];
+
+  for (const s of shipmentRows) {
+    events.push({
+      timestamp: s.created_at,
+      type: "shipment_created",
+      entity_id: s.id,
+      details: `Shipment created via ${s.carrier}/${s.service}${s.tracking_number ? ` (${s.tracking_number})` : ""} [${s.status}]`,
+    });
+
+    if (s.shipped_at) {
+      events.push({
+        timestamp: s.shipped_at,
+        type: "shipment_updated",
+        entity_id: s.id,
+        details: `Shipment shipped via ${s.carrier}`,
+      });
+    }
+    if (s.delivered_at) {
+      events.push({
+        timestamp: s.delivered_at,
+        type: "shipment_updated",
+        entity_id: s.id,
+        details: `Shipment delivered via ${s.carrier}`,
+      });
+    }
+  }
+
+  // Returns
+  const returnRows = db.prepare(
+    "SELECT * FROM returns WHERE order_id = ? ORDER BY created_at ASC"
+  ).all(orderId) as ReturnRow[];
+
+  for (const r of returnRows) {
+    events.push({
+      timestamp: r.created_at,
+      type: "return_created",
+      entity_id: r.id,
+      details: `Return requested${r.reason ? `: ${r.reason}` : ""}${r.rma_code ? ` (${r.rma_code})` : ""} [${r.status}]`,
+    });
+
+    if (r.updated_at !== r.created_at) {
+      events.push({
+        timestamp: r.updated_at,
+        type: "return_updated",
+        entity_id: r.id,
+        details: `Return updated — status: ${r.status}`,
+      });
+    }
+  }
+
+  // Sort by timestamp
+  events.sort((a, b) => a.timestamp.localeCompare(b.timestamp));
+
+  return events;
+}

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

@@ -11,6 +11,9 @@ import {
   deleteOrder,
   searchOrders,
   listByStatus,
+  bulkImportOrders,
+  exportOrders,
+  getOrderTimeline,
 } from "../db/shipping.js";
 import {
   createShipment,
@@ -28,6 +31,11 @@ import {
 import {
   getShippingStats,
   getCostsByCarrier,
+  getDeliveryStats,
+  listOverdueShipments,
+  getCustomerHistory,
+  getCarrierPerformance,
+  optimizeCost,
 } from "../db/shipping.js";
 
 const server = new McpServer({
@@ -275,10 +283,11 @@ server.registerTool(
   "create_return",
   {
     title: "Create Return",
-    description: "Create a return request for an order.",
+    description: "Create a return request for an order. Set auto_rma to true to generate a unique RMA code.",
     inputSchema: {
       order_id: z.string(),
       reason: z.string().optional(),
+      auto_rma: z.boolean().optional(),
     },
   },
   async (params) => {
@@ -372,6 +381,145 @@ server.registerTool(
   }
 );
 
+// ─── Bulk Import/Export ──────────────────────────────────────────────────────
+
+server.registerTool(
+  "bulk_import_orders",
+  {
+    title: "Bulk Import Orders",
+    description: "Import orders from CSV data. Columns: customer_name,customer_email,street,city,state,zip,country,items_json,total_value.",
+    inputSchema: {
+      csv_data: z.string().describe("CSV data with header row"),
+    },
+  },
+  async ({ csv_data }) => {
+    const result = bulkImportOrders(csv_data);
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+  }
+);
+
+server.registerTool(
+  "export_orders",
+  {
+    title: "Export Orders",
+    description: "Export orders in CSV or JSON format, optionally filtered by date range.",
+    inputSchema: {
+      format: z.enum(["csv", "json"]).describe("Output format"),
+      date_from: z.string().optional().describe("Filter from date (YYYY-MM-DD)"),
+      date_to: z.string().optional().describe("Filter to date (YYYY-MM-DD)"),
+    },
+  },
+  async ({ format, date_from, date_to }) => {
+    const output = exportOrders(format, date_from, date_to);
+    return { content: [{ type: "text", text: output }] };
+  }
+);
+
+// ─── Delivery Timeline Analytics ────────────────────────────────────────────
+
+server.registerTool(
+  "delivery_timeline_stats",
+  {
+    title: "Delivery Timeline Stats",
+    description: "Get delivery time analytics (avg days, on-time %, late %) per carrier and service level.",
+    inputSchema: {
+      carrier: z.string().optional().describe("Filter by carrier"),
+    },
+  },
+  async ({ carrier }) => {
+    const stats = getDeliveryStats(carrier);
+    return { content: [{ type: "text", text: JSON.stringify(stats, null, 2) }] };
+  }
+);
+
+// ─── Late Delivery Alerts ───────────────────────────────────────────────────
+
+server.registerTool(
+  "list_overdue_shipments",
+  {
+    title: "List Overdue Shipments",
+    description: "Find shipments past their estimated delivery date + grace period that are not yet delivered.",
+    inputSchema: {
+      grace_days: z.number().optional().describe("Grace days beyond estimated delivery (default 0)"),
+    },
+  },
+  async ({ grace_days }) => {
+    const overdue = listOverdueShipments(grace_days ?? 0);
+    return { content: [{ type: "text", text: JSON.stringify({ overdue, count: overdue.length }, null, 2) }] };
+  }
+);
+
+// ─── Customer History ───────────────────────────────────────────────────────
+
+server.registerTool(
+  "customer_shipping_history",
+  {
+    title: "Customer Shipping History",
+    description: "Get all orders, shipments, and returns for a customer by email.",
+    inputSchema: {
+      email: z.string().describe("Customer email address"),
+    },
+  },
+  async ({ email }) => {
+    const history = getCustomerHistory(email);
+    return { content: [{ type: "text", text: JSON.stringify(history, null, 2) }] };
+  }
+);
+
+// ─── Carrier Performance ────────────────────────────────────────────────────
+
+server.registerTool(
+  "carrier_performance",
+  {
+    title: "Carrier Performance",
+    description: "Rank carriers by on-time delivery %, average cost, and average delivery days.",
+    inputSchema: {},
+  },
+  async () => {
+    const perf = getCarrierPerformance();
+    return { content: [{ type: "text", text: JSON.stringify(perf, null, 2) }] };
+  }
+);
+
+// ─── Cost Optimizer ─────────────────────────────────────────────────────────
+
+server.registerTool(
+  "optimize_shipping_cost",
+  {
+    title: "Optimize Shipping Cost",
+    description: "Recommend cheapest carrier/service based on historical cost data for a given package weight.",
+    inputSchema: {
+      weight: z.number().describe("Package weight in kg"),
+      from_zip: z.string().optional().describe("Origin zip code"),
+      to_zip: z.string().optional().describe("Destination zip code"),
+    },
+  },
+  async ({ weight, from_zip, to_zip }) => {
+    const recommendations = optimizeCost(weight, from_zip, to_zip);
+    return { content: [{ type: "text", text: JSON.stringify(recommendations, null, 2) }] };
+  }
+);
+
+// ─── Order Timeline ─────────────────────────────────────────────────────────
+
+server.registerTool(
+  "order_timeline",
+  {
+    title: "Order Timeline",
+    description: "Get the full event history for an order, including shipments and returns.",
+    inputSchema: {
+      order_id: z.string().describe("Order ID"),
+    },
+  },
+  async ({ order_id }) => {
+    const timeline = getOrderTimeline(order_id);
+    if (timeline.length === 0) {
+      return { content: [{ type: "text", text: `No events found for order '${order_id}'.` }], isError: true };
+    }
+    return { content: [{ type: "text", text: JSON.stringify(timeline, null, 2) }] };
+  }
+);
+
 // --- Start ---
 async function main() {
   const transport = new StdioServerTransport();