@unifiedcommerce/plugin-pos 0.0.1

package/src/services/payment-service.ts

@@ -0,0 +1,133 @@
+import { eq, and, sql } from "drizzle-orm";
+import { Ok, Err } from "@unifiedcommerce/core";
+import type { PluginResult } from "@unifiedcommerce/core";
+import { posPayments, posTransactions, posShifts } from "../schema";
+import type { Db, Payment, Transaction } from "../types";
+
+export class PaymentService {
+  constructor(
+    private db: Db,
+    private transaction: (fn: (tx: Db) => Promise<unknown>) => Promise<unknown>,
+  ) {}
+
+  /**
+   * Add a payment to a transaction. Does NOT finalize.
+   * Supports split payment (multiple calls per transaction).
+   */
+  async addPayment(orgId: string, transactionId: string, input: {
+    method: "cash" | "card" | "gift_card" | "store_credit" | "other";
+    amount: number;
+    changeGiven?: number;
+    reference?: string;
+    metadata?: Record<string, unknown>;
+  }): Promise<PluginResult<Payment>> {
+    if (input.amount <= 0) return Err("Payment amount must be positive");
+
+    // Verify transaction is open
+    const txns = await this.db
+      .select()
+      .from(posTransactions)
+      .where(and(
+        eq(posTransactions.id, transactionId),
+        eq(posTransactions.organizationId, orgId),
+      ));
+
+    if (txns.length === 0) return Err("Transaction not found");
+    const txn = txns[0]!;
+    if (txn.status !== "open") return Err("Transaction is not open");
+
+    const rows = await this.db
+      .insert(posPayments)
+      .values({
+        transactionId,
+        method: input.method,
+        amount: input.amount,
+        changeGiven: input.changeGiven ?? 0,
+        reference: input.reference,
+        status: "collected",
+        processedAt: new Date(),
+        metadata: input.metadata ?? {},
+      })
+      .returning();
+
+    return Ok(rows[0]!);
+  }
+
+  /**
+   * Get total payments collected for a transaction.
+   */
+  async getPaymentTotal(transactionId: string): Promise<number> {
+    const rows = await this.db
+      .select({
+        total: sql<number>`COALESCE(SUM(${posPayments.amount} - ${posPayments.changeGiven}), 0)`.as("total"),
+      })
+      .from(posPayments)
+      .where(and(
+        eq(posPayments.transactionId, transactionId),
+        eq(posPayments.status, "collected"),
+      ));
+
+    return Number(rows[0]?.total ?? 0);
+  }
+
+  /**
+   * List all payments for a transaction.
+   */
+  async listPayments(transactionId: string): Promise<PluginResult<Payment[]>> {
+    const rows = await this.db
+      .select()
+      .from(posPayments)
+      .where(eq(posPayments.transactionId, transactionId));
+
+    return Ok(rows);
+  }
+
+  /**
+   * Validate that total payments cover the transaction total, then return
+   * the transaction details needed for checkout.
+   */
+  async validateForCompletion(orgId: string, transactionId: string): Promise<PluginResult<{
+    transaction: Transaction;
+    payments: Payment[];
+    totalPaid: number;
+  }>> {
+    const txns = await this.db
+      .select()
+      .from(posTransactions)
+      .where(and(
+        eq(posTransactions.id, transactionId),
+        eq(posTransactions.organizationId, orgId),
+      ));
+
+    if (txns.length === 0) return Err("Transaction not found");
+    const txn = txns[0]!;
+    if (txn.status !== "open") return Err(`Transaction is ${txn.status}, not open`);
+
+    const payments = await this.db
+      .select()
+      .from(posPayments)
+      .where(and(
+        eq(posPayments.transactionId, transactionId),
+        eq(posPayments.status, "collected"),
+      ));
+
+    const totalPaid = payments.reduce((sum, p) => sum + p.amount - p.changeGiven, 0);
+
+    if (txn.total > 0 && totalPaid < txn.total) {
+      return Err(`Insufficient payment: ${totalPaid} paid, ${txn.total} required`);
+    }
+
+    return Ok({ transaction: txn, payments, totalPaid });
+  }
+
+  /**
+   * Mark payments as refunded for a transaction.
+   */
+  async refundPayments(transactionId: string, tx?: Db): Promise<void> {
+    const db = tx ?? this.db;
+    await db
+      .update(posPayments)
+      .set({ status: "refunded" })
+      .where(eq(posPayments.transactionId, transactionId));
+  }
+}

package/src/services/receipt-service.ts

@@ -0,0 +1,169 @@
+import { eq, and } from "drizzle-orm";
+import { Ok, Err } from "@unifiedcommerce/core";
+import type { PluginResult } from "@unifiedcommerce/core";
+import { posTransactions, posPayments } from "../schema";
+import type { Db, Transaction, Payment } from "../types";
+
+export interface ReceiptData {
+  receiptNumber: string;
+  transactionId: string;
+  terminalCode: string;
+  operatorName: string;
+  timestamp: Date;
+  lineItems: Array<{
+    title: string;
+    quantity: number;
+    unitPrice: number;
+    totalPrice: number;
+    notes?: string | null;
+  }>;
+  subtotal: number;
+  discountTotal: number;
+  taxTotal: number;
+  total: number;
+  payments: Array<{
+    method: string;
+    amount: number;
+    changeGiven: number;
+    reference?: string | null;
+  }>;
+  changeDue: number;
+  customerId?: string | null;
+}
+
+export class ReceiptService {
+  constructor(
+    private db: Db,
+    private services: Record<string, unknown>,
+  ) {}
+
+  /**
+   * Assemble full receipt data for a completed transaction.
+   */
+  async getReceipt(orgId: string, transactionId: string): Promise<PluginResult<ReceiptData>> {
+    // Get transaction
+    const txns = await this.db
+      .select()
+      .from(posTransactions)
+      .where(and(
+        eq(posTransactions.id, transactionId),
+        eq(posTransactions.organizationId, orgId),
+      ));
+
+    if (txns.length === 0) return Err("Transaction not found");
+    const txn = txns[0]!;
+
+    if (txn.status !== "completed" && txn.status !== "voided") {
+      return Err("Receipt is only available for completed or voided transactions");
+    }
+
+    // Get terminal code
+    const { posTerminals } = await import("../schema");
+    const terminals = await this.db
+      .select({ code: posTerminals.code, name: posTerminals.name })
+      .from(posTerminals)
+      .where(eq(posTerminals.id, txn.terminalId));
+
+    const terminalCode = terminals[0]?.code ?? "POS";
+
+    // Get payments
+    const payments = await this.db
+      .select()
+      .from(posPayments)
+      .where(eq(posPayments.transactionId, transactionId));
+
+    // Get order line items from core
+    let lineItems: ReceiptData["lineItems"] = [];
+    if (txn.orderId) {
+      const orders = this.services.orders as {
+        getById: (id: string, actor: unknown) => Promise<{ ok: boolean; value?: { lineItems?: Array<{ title?: string; quantity: number; unitPrice?: number; totalPrice?: number }> } }>;
+      } | undefined;
+
+      if (orders) {
+        const orderResult = await orders.getById(txn.orderId, null);
+        if (orderResult.ok && orderResult.value?.lineItems) {
+          lineItems = orderResult.value.lineItems.map((li) => ({
+            title: li.title ?? "Item",
+            quantity: li.quantity,
+            unitPrice: li.unitPrice ?? 0,
+            totalPrice: li.totalPrice ?? 0,
+          }));
+        }
+      }
+    }
+
+    // Calculate change due
+    const totalPaid = payments
+      .filter((p) => p.status === "collected")
+      .reduce((sum, p) => sum + p.amount, 0);
+    const changeDue = payments
+      .filter((p) => p.status === "collected")
+      .reduce((sum, p) => sum + p.changeGiven, 0);
+
+    return Ok({
+      receiptNumber: txn.receiptNumber,
+      transactionId: txn.id,
+      terminalCode,
+      operatorName: txn.operatorId,
+      timestamp: txn.completedAt ?? txn.createdAt,
+      lineItems,
+      subtotal: txn.subtotal,
+      discountTotal: txn.discountTotal,
+      taxTotal: txn.taxTotal,
+      total: txn.total,
+      payments: payments.map((p) => ({
+        method: p.method,
+        amount: p.amount,
+        changeGiven: p.changeGiven,
+        reference: p.reference,
+      })),
+      changeDue,
+      customerId: txn.customerId,
+    });
+  }
+
+  /**
+   * Send receipt via email (delegates to email service).
+   */
+  async emailReceipt(orgId: string, transactionId: string, email: string): Promise<PluginResult<{ sent: boolean }>> {
+    const receiptResult = await this.getReceipt(orgId, transactionId);
+    if (!receiptResult.ok) return receiptResult;
+
+    const emailService = this.services.email as {
+      send?: (opts: { to: string; subject: string; html: string }) => Promise<void>;
+    } | undefined;
+
+    if (!emailService?.send) {
+      return Err("Email service not configured");
+    }
+
+    await emailService.send({
+      to: email,
+      subject: `Receipt ${receiptResult.value.receiptNumber}`,
+      html: this.formatReceiptHtml(receiptResult.value),
+    });
+
+    return Ok({ sent: true });
+  }
+
+  private formatReceiptHtml(receipt: ReceiptData): string {
+    const lines = receipt.lineItems
+      .map((li) => `<tr><td>${li.title}</td><td>${li.quantity}</td><td>${(li.unitPrice / 100).toFixed(2)}</td><td>${(li.totalPrice / 100).toFixed(2)}</td></tr>`)
+      .join("");
+
+    return `
+      <h2>Receipt ${receipt.receiptNumber}</h2>
+      <p>Date: ${receipt.timestamp.toISOString()}</p>
+      <table>
+        <tr><th>Item</th><th>Qty</th><th>Price</th><th>Total</th></tr>
+        ${lines}
+      </table>
+      <p>Subtotal: ${(receipt.subtotal / 100).toFixed(2)}</p>
+      ${receipt.discountTotal > 0 ? `<p>Discount: -${(receipt.discountTotal / 100).toFixed(2)}</p>` : ""}
+      <p>Tax: ${(receipt.taxTotal / 100).toFixed(2)}</p>
+      <p><strong>Total: ${(receipt.total / 100).toFixed(2)}</strong></p>
+      ${receipt.payments.map((p) => `<p>${p.method}: ${(p.amount / 100).toFixed(2)}</p>`).join("")}
+      ${receipt.changeDue > 0 ? `<p>Change: ${(receipt.changeDue / 100).toFixed(2)}</p>` : ""}
+    `;
+  }
+}

package/src/services/return-service.ts

@@ -0,0 +1,65 @@
+import { eq } from "drizzle-orm";
+import { Ok, Err } from "@unifiedcommerce/core";
+import type { PluginResult } from "@unifiedcommerce/core";
+import { posReturnItems } from "../schema";
+import type { Db, ReturnItem } from "../types";
+
+export class ReturnService {
+  constructor(private db: Db) {}
+
+  /**
+   * Record return items linking back to an original order's line items.
+   * Called after a return transaction is created.
+   */
+  async addReturnItems(transactionId: string, items: Array<{
+    originalOrderId: string;
+    originalLineItemId: string;
+    quantity: number;
+    reason: "defective" | "wrong_item" | "changed_mind" | "other";
+    restockingFee?: number;
+    refundAmount: number;
+  }>): Promise<PluginResult<ReturnItem[]>> {
+    if (items.length === 0) return Err("At least one item is required");
+
+    const values = items.map((item) => ({
+      transactionId,
+      originalOrderId: item.originalOrderId,
+      originalLineItemId: item.originalLineItemId,
+      quantity: item.quantity,
+      reason: item.reason,
+      restockingFee: item.restockingFee ?? 0,
+      refundAmount: item.refundAmount,
+    }));
+
+    const rows = await this.db
+      .insert(posReturnItems)
+      .values(values)
+      .returning();
+
+    return Ok(rows);
+  }
+
+  /**
+   * Get all return items for a return transaction.
+   */
+  async getReturnItems(transactionId: string): Promise<PluginResult<ReturnItem[]>> {
+    const rows = await this.db
+      .select()
+      .from(posReturnItems)
+      .where(eq(posReturnItems.transactionId, transactionId));
+
+    return Ok(rows);
+  }
+
+  /**
+   * Calculate total refund amount for a return transaction.
+   */
+  async calculateRefundTotal(transactionId: string): Promise<number> {
+    const items = await this.db
+      .select()
+      .from(posReturnItems)
+      .where(eq(posReturnItems.transactionId, transactionId));
+
+    return items.reduce((sum, item) => sum + item.refundAmount, 0);
+  }
+}

package/src/services/shift-service.ts

@@ -0,0 +1,260 @@
+import { eq, and, desc, sql } from "drizzle-orm";
+import { Ok, Err } from "@unifiedcommerce/core";
+import type { PluginResult } from "@unifiedcommerce/core";
+import { posShifts, posCashEvents, posPayments, posTransactions } from "../schema";
+import type { Db, Shift, CashEvent } from "../types";
+
+export class ShiftService {
+  constructor(
+    private db: Db,
+    private transaction: (fn: (tx: Db) => Promise<unknown>) => Promise<unknown>,
+  ) {}
+
+  async open(orgId: string, input: {
+    terminalId: string;
+    operatorId: string;
+    openingFloat: number;
+  }): Promise<PluginResult<Shift>> {
+    if (input.openingFloat < 0) return Err("Opening float must be non-negative");
+
+    // Check no open shift on this terminal
+    const openShifts = await this.db
+      .select()
+      .from(posShifts)
+      .where(and(
+        eq(posShifts.terminalId, input.terminalId),
+        eq(posShifts.status, "open"),
+      ));
+
+    if (openShifts.length > 0) {
+      return Err("Terminal already has an open shift");
+    }
+
+    const rows = await this.db
+      .insert(posShifts)
+      .values({
+        organizationId: orgId,
+        terminalId: input.terminalId,
+        operatorId: input.operatorId,
+        openingFloat: input.openingFloat,
+        status: "open",
+      })
+      .returning();
+
+    const shift = rows[0]!;
+
+    // Record the opening float as a cash event
+    await this.db.insert(posCashEvents).values({
+      shiftId: shift.id,
+      type: "float",
+      amount: input.openingFloat,
+      performedBy: input.operatorId,
+      performedAt: new Date(),
+    });
+
+    return Ok(shift);
+  }
+
+  async close(orgId: string, shiftId: string, input: {
+    closingCount: number;
+  }): Promise<PluginResult<Shift>> {
+    const result = await this.transaction(async (tx) => {
+      const shifts = await tx
+        .select()
+        .from(posShifts)
+        .where(and(eq(posShifts.id, shiftId), eq(posShifts.organizationId, orgId)))
+        .for("update");
+
+      if (shifts.length === 0) return Err("Shift not found");
+      const shift = shifts[0]!;
+      if (shift.status === "closed") return Err("Shift is already closed");
+
+      // Calculate expected cash
+      const expectedCash = await this.calculateExpectedCash(tx, shiftId, shift.openingFloat);
+      const cashVariance = input.closingCount - expectedCash;
+
+      const updated = await tx
+        .update(posShifts)
+        .set({
+          status: "closed",
+          closingCount: input.closingCount,
+          expectedCash,
+          cashVariance,
+          closedAt: new Date(),
+          updatedAt: new Date(),
+        })
+        .where(eq(posShifts.id, shiftId))
+        .returning();
+
+      return Ok(updated[0]!);
+    });
+
+    return result as PluginResult<Shift>;
+  }
+
+  async getCurrent(orgId: string, operatorId: string): Promise<PluginResult<Shift | null>> {
+    const rows = await this.db
+      .select()
+      .from(posShifts)
+      .where(and(
+        eq(posShifts.organizationId, orgId),
+        eq(posShifts.operatorId, operatorId),
+        eq(posShifts.status, "open"),
+      ));
+
+    return Ok(rows[0] ?? null);
+  }
+
+  async getById(orgId: string, id: string): Promise<PluginResult<Shift>> {
+    const rows = await this.db
+      .select()
+      .from(posShifts)
+      .where(and(eq(posShifts.id, id), eq(posShifts.organizationId, orgId)));
+
+    if (rows.length === 0) return Err("Shift not found");
+    return Ok(rows[0]!);
+  }
+
+  // ─── Cash Events ───────────────────────────────────────────────────
+
+  async addCashEvent(shiftId: string, input: {
+    type: "drop" | "pickup" | "paid_in" | "paid_out";
+    amount: number;
+    reason?: string;
+    performedBy: string;
+  }): Promise<PluginResult<CashEvent>> {
+    if (input.amount <= 0) return Err("Amount must be positive");
+
+    // Verify shift is open
+    const shifts = await this.db
+      .select()
+      .from(posShifts)
+      .where(eq(posShifts.id, shiftId));
+
+    if (shifts.length === 0) return Err("Shift not found");
+    if (shifts[0]!.status !== "open") return Err("Shift is not open");
+
+    const rows = await this.db
+      .insert(posCashEvents)
+      .values({
+        shiftId,
+        type: input.type,
+        amount: input.amount,
+        reason: input.reason,
+        performedBy: input.performedBy,
+        performedAt: new Date(),
+      })
+      .returning();
+
+    return Ok(rows[0]!);
+  }
+
+  async listCashEvents(shiftId: string): Promise<PluginResult<CashEvent[]>> {
+    const rows = await this.db
+      .select()
+      .from(posCashEvents)
+      .where(eq(posCashEvents.shiftId, shiftId))
+      .orderBy(desc(posCashEvents.performedAt));
+    return Ok(rows);
+  }
+
+  // ─── Z-Report ──────────────────────────────────────────────────────
+
+  async getReport(orgId: string, shiftId: string): Promise<PluginResult<{
+    shift: Shift;
+    cashEvents: CashEvent[];
+    paymentMethodTotals: Array<{ method: string; total: number; count: number }>;
+    transactionCount: number;
+  }>> {
+    const shiftResult = await this.getById(orgId, shiftId);
+    if (!shiftResult.ok) return shiftResult;
+    const shift = shiftResult.value;
+
+    const cashEvents = await this.db
+      .select()
+      .from(posCashEvents)
+      .where(eq(posCashEvents.shiftId, shiftId))
+      .orderBy(desc(posCashEvents.performedAt));
+
+    // Payment method totals
+    const paymentRows = await this.db
+      .select({
+        method: posPayments.method,
+        total: sql<number>`SUM(${posPayments.amount})`.as("total"),
+        count: sql<number>`COUNT(*)`.as("count"),
+      })
+      .from(posPayments)
+      .innerJoin(posTransactions, eq(posPayments.transactionId, posTransactions.id))
+      .where(and(
+        eq(posTransactions.shiftId, shiftId),
+        eq(posTransactions.status, "completed"),
+      ))
+      .groupBy(posPayments.method);
+
+    const transactionCountRows = await this.db
+      .select({ count: sql<number>`COUNT(*)`.as("count") })
+      .from(posTransactions)
+      .where(and(
+        eq(posTransactions.shiftId, shiftId),
+        eq(posTransactions.status, "completed"),
+      ));
+
+    return Ok({
+      shift,
+      cashEvents,
+      paymentMethodTotals: paymentRows.map((r) => ({
+        method: r.method,
+        total: Number(r.total),
+        count: Number(r.count),
+      })),
+      transactionCount: Number(transactionCountRows[0]?.count ?? 0),
+    });
+  }
+
+  // ─── Helpers ───────────────────────────────────────────────────────
+
+  private async calculateExpectedCash(db: Db, shiftId: string, openingFloat: number): Promise<number> {
+    // Cash payments collected during this shift
+    const cashPaymentRows = await db
+      .select({
+        total: sql<number>`COALESCE(SUM(${posPayments.amount} - ${posPayments.changeGiven}), 0)`.as("total"),
+      })
+      .from(posPayments)
+      .innerJoin(posTransactions, eq(posPayments.transactionId, posTransactions.id))
+      .where(and(
+        eq(posTransactions.shiftId, shiftId),
+        eq(posPayments.method, "cash"),
+        eq(posPayments.status, "collected"),
+      ));
+
+    const cashFromSales = Number(cashPaymentRows[0]?.total ?? 0);
+
+    // Cash events: drops reduce, pickups add to drawer
+    const cashEventRows = await db
+      .select({
+        type: posCashEvents.type,
+        total: sql<number>`SUM(${posCashEvents.amount})`.as("total"),
+      })
+      .from(posCashEvents)
+      .where(eq(posCashEvents.shiftId, shiftId))
+      .groupBy(posCashEvents.type);
+
+    let cashAdjustment = 0;
+    for (const row of cashEventRows) {
+      const amount = Number(row.total);
+      switch (row.type) {
+        case "drop":
+        case "paid_out":
+          cashAdjustment -= amount;
+          break;
+        case "pickup":
+        case "paid_in":
+          cashAdjustment += amount;
+          break;
+        // float is already accounted for in openingFloat
+      }
+    }
+
+    return openingFloat + cashFromSales + cashAdjustment;
+  }
+}

package/src/services/terminal-service.ts

@@ -0,0 +1,76 @@
+import { eq, and } from "drizzle-orm";
+import { Ok, Err } from "@unifiedcommerce/core";
+import type { PluginResult } from "@unifiedcommerce/core";
+import { posTerminals } from "../schema";
+import type { Db, Terminal, TerminalInsert } from "../types";
+
+export class TerminalService {
+  constructor(private db: Db) {}
+
+  async create(orgId: string, input: {
+    name: string;
+    code: string;
+    type?: "register" | "tablet" | "mobile" | "kiosk";
+    metadata?: Record<string, unknown>;
+  }): Promise<PluginResult<Terminal>> {
+    // Check for duplicate code in same org
+    const existing = await this.db
+      .select()
+      .from(posTerminals)
+      .where(and(eq(posTerminals.organizationId, orgId), eq(posTerminals.code, input.code)));
+
+    if (existing.length > 0) {
+      return Err(`Terminal with code '${input.code}' already exists`);
+    }
+
+    const rows = await this.db
+      .insert(posTerminals)
+      .values({
+        organizationId: orgId,
+        name: input.name,
+        code: input.code,
+        type: input.type ?? "register",
+        metadata: input.metadata ?? {},
+      } as TerminalInsert)
+      .returning();
+
+    return Ok(rows[0]!);
+  }
+
+  async list(orgId: string): Promise<PluginResult<Terminal[]>> {
+    const rows = await this.db
+      .select()
+      .from(posTerminals)
+      .where(eq(posTerminals.organizationId, orgId));
+    return Ok(rows);
+  }
+
+  async getById(orgId: string, id: string): Promise<PluginResult<Terminal>> {
+    const rows = await this.db
+      .select()
+      .from(posTerminals)
+      .where(and(eq(posTerminals.id, id), eq(posTerminals.organizationId, orgId)));
+
+    if (rows.length === 0) return Err("Terminal not found");
+    return Ok(rows[0]!);
+  }
+
+  async update(orgId: string, id: string, input: {
+    name?: string;
+    isActive?: boolean;
+    metadata?: Record<string, unknown>;
+  }): Promise<PluginResult<Terminal>> {
+    const rows = await this.db
+      .update(posTerminals)
+      .set({ ...input, updatedAt: new Date() })
+      .where(and(eq(posTerminals.id, id), eq(posTerminals.organizationId, orgId)))
+      .returning();
+
+    if (rows.length === 0) return Err("Terminal not found");
+    return Ok(rows[0]!);
+  }
+
+  async deactivate(orgId: string, id: string): Promise<PluginResult<Terminal>> {
+    return this.update(orgId, id, { isActive: false });
+  }
+}