@unifiedcommerce/plugin-pos 0.0.1

package/dist/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAMH,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAatB,CAAC;AAIJ,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAsBnB,CAAC;AAIJ,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAWvB,CAAC;AAIJ,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA2BzB,CAAC;AAIJ,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAarB,CAAC;AAIJ,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAaxB,CAAC"}

package/dist/schema.js

@@ -0,0 +1,123 @@
+/**
+ * POS Plugin Schema — RFC-023 Tier 0 Core Primitives
+ *
+ * 6 tables replacing the old single pos_sessions table:
+ * - pos_terminals: physical register/device registry
+ * - pos_shifts: operator working periods with cash tracking
+ * - pos_cash_events: cash drawer operations within a shift
+ * - pos_transactions: individual sales, returns, exchanges
+ * - pos_payments: payment records (supports split tender)
+ * - pos_return_items: links return transactions to original order line items
+ */
+import { pgTable, uuid, text, integer, boolean, timestamp, jsonb, index, uniqueIndex } from "drizzle-orm/pg-core";
+// ─── Terminals ──────────────────────────────────────────────────────────
+export const posTerminals = pgTable("pos_terminals", {
+    id: uuid("id").defaultRandom().primaryKey(),
+    organizationId: text("organization_id").notNull(),
+    name: text("name").notNull(),
+    code: text("code").notNull(),
+    type: text("type", { enum: ["register", "tablet", "mobile", "kiosk"] }).notNull().default("register"),
+    isActive: boolean("is_active").notNull().default(true),
+    metadata: jsonb("metadata").$type().default({}),
+    createdAt: timestamp("created_at", { withTimezone: true }).defaultNow().notNull(),
+    updatedAt: timestamp("updated_at", { withTimezone: true }).defaultNow().notNull(),
+}, (table) => ({
+    orgIdx: index("idx_pos_terminals_org").on(table.organizationId),
+    codeUnique: uniqueIndex("pos_terminals_org_code_unique").on(table.organizationId, table.code),
+}));
+// ─── Shifts ─────────────────────────────────────────────────────────────
+export const posShifts = pgTable("pos_shifts", {
+    id: uuid("id").defaultRandom().primaryKey(),
+    organizationId: text("organization_id").notNull(),
+    terminalId: uuid("terminal_id").references(() => posTerminals.id, { onDelete: "cascade" }).notNull(),
+    operatorId: text("operator_id").notNull(),
+    status: text("status", { enum: ["open", "closed"] }).notNull().default("open"),
+    openingFloat: integer("opening_float").notNull().default(0),
+    closingCount: integer("closing_count"),
+    expectedCash: integer("expected_cash"),
+    cashVariance: integer("cash_variance"),
+    salesCount: integer("sales_count").notNull().default(0),
+    salesTotal: integer("sales_total").notNull().default(0),
+    refundsCount: integer("refunds_count").notNull().default(0),
+    refundsTotal: integer("refunds_total").notNull().default(0),
+    voidsCount: integer("voids_count").notNull().default(0),
+    closedAt: timestamp("closed_at", { withTimezone: true }),
+    metadata: jsonb("metadata").$type().default({}),
+    createdAt: timestamp("created_at", { withTimezone: true }).defaultNow().notNull(),
+    updatedAt: timestamp("updated_at", { withTimezone: true }).defaultNow().notNull(),
+}, (table) => ({
+    orgIdx: index("idx_pos_shifts_org").on(table.organizationId),
+    terminalIdx: index("idx_pos_shifts_terminal").on(table.terminalId),
+}));
+// ─── Cash Events ────────────────────────────────────────────────────────
+export const posCashEvents = pgTable("pos_cash_events", {
+    id: uuid("id").defaultRandom().primaryKey(),
+    shiftId: uuid("shift_id").references(() => posShifts.id, { onDelete: "cascade" }).notNull(),
+    type: text("type", { enum: ["float", "drop", "pickup", "paid_in", "paid_out"] }).notNull(),
+    amount: integer("amount").notNull(),
+    reason: text("reason"),
+    performedBy: text("performed_by").notNull(),
+    performedAt: timestamp("performed_at", { withTimezone: true }).defaultNow().notNull(),
+    createdAt: timestamp("created_at", { withTimezone: true }).defaultNow().notNull(),
+}, (table) => ({
+    shiftIdx: index("idx_pos_cash_events_shift").on(table.shiftId),
+}));
+// ─── Transactions ───────────────────────────────────────────────────────
+export const posTransactions = pgTable("pos_transactions", {
+    id: uuid("id").defaultRandom().primaryKey(),
+    organizationId: text("organization_id").notNull(),
+    shiftId: uuid("shift_id").references(() => posShifts.id, { onDelete: "cascade" }).notNull(),
+    terminalId: uuid("terminal_id").references(() => posTerminals.id).notNull(),
+    operatorId: text("operator_id").notNull(),
+    cartId: uuid("cart_id").notNull(),
+    orderId: uuid("order_id"),
+    type: text("type", { enum: ["sale", "return", "exchange"] }).notNull().default("sale"),
+    status: text("status", { enum: ["open", "held", "completed", "voided"] }).notNull().default("open"),
+    customerId: uuid("customer_id"),
+    receiptNumber: text("receipt_number").notNull(),
+    subtotal: integer("subtotal").notNull().default(0),
+    taxTotal: integer("tax_total").notNull().default(0),
+    total: integer("total").notNull().default(0),
+    discountTotal: integer("discount_total").notNull().default(0),
+    holdLabel: text("hold_label"),
+    voidReason: text("void_reason"),
+    metadata: jsonb("metadata").$type().default({}),
+    createdAt: timestamp("created_at", { withTimezone: true }).defaultNow().notNull(),
+    updatedAt: timestamp("updated_at", { withTimezone: true }).defaultNow().notNull(),
+    completedAt: timestamp("completed_at", { withTimezone: true }),
+}, (table) => ({
+    orgIdx: index("idx_pos_transactions_org").on(table.organizationId),
+    shiftIdx: index("idx_pos_transactions_shift").on(table.shiftId),
+    statusIdx: index("idx_pos_transactions_status").on(table.status),
+    receiptIdx: index("idx_pos_transactions_receipt").on(table.receiptNumber),
+}));
+// ─── Payments (Tenders) ─────────────────────────────────────────────────
+export const posPayments = pgTable("pos_payments", {
+    id: uuid("id").defaultRandom().primaryKey(),
+    transactionId: uuid("transaction_id").references(() => posTransactions.id, { onDelete: "cascade" }).notNull(),
+    method: text("method", { enum: ["cash", "card", "gift_card", "store_credit", "other"] }).notNull(),
+    amount: integer("amount").notNull(),
+    changeGiven: integer("change_given").notNull().default(0),
+    reference: text("reference"),
+    status: text("status", { enum: ["collected", "refunded"] }).notNull().default("collected"),
+    processedAt: timestamp("processed_at", { withTimezone: true }).defaultNow().notNull(),
+    metadata: jsonb("metadata").$type().default({}),
+    createdAt: timestamp("created_at", { withTimezone: true }).defaultNow().notNull(),
+}, (table) => ({
+    transactionIdx: index("idx_pos_payments_transaction").on(table.transactionId),
+}));
+// ─── Return Items ───────────────────────────────────────────────────────
+export const posReturnItems = pgTable("pos_return_items", {
+    id: uuid("id").defaultRandom().primaryKey(),
+    transactionId: uuid("transaction_id").references(() => posTransactions.id, { onDelete: "cascade" }).notNull(),
+    originalOrderId: uuid("original_order_id").notNull(),
+    originalLineItemId: uuid("original_line_item_id").notNull(),
+    quantity: integer("quantity").notNull(),
+    reason: text("reason", { enum: ["defective", "wrong_item", "changed_mind", "other"] }).notNull(),
+    restockingFee: integer("restocking_fee").notNull().default(0),
+    refundAmount: integer("refund_amount").notNull(),
+    createdAt: timestamp("created_at", { withTimezone: true }).defaultNow().notNull(),
+}, (table) => ({
+    transactionIdx: index("idx_pos_return_items_transaction").on(table.transactionId),
+    originalOrderIdx: index("idx_pos_return_items_order").on(table.originalOrderId),
+}));

package/dist/services/lookup-service.d.ts

@@ -0,0 +1,38 @@
+import type { PluginResult } from "@unifiedcommerce/core";
+import type { Db } from "../types";
+export interface LookupResult {
+    entityId: string;
+    variantId: string;
+    entityType: string;
+    slug: string;
+    barcode: string | null;
+    sku: string | null;
+    title?: string | undefined;
+    price?: number | undefined;
+}
+/**
+ * Item lookup service for POS.
+ * Uses indexed queries on variants.barcode and variants.sku.
+ *
+ * Depends on core schema tables (variants, sellable_entities, entity_attributes)
+ * accessed via the scoped DB proxy.
+ */
+export declare class LookupService {
+    private db;
+    private services;
+    constructor(db: Db, services: Record<string, unknown>);
+    /**
+     * Find entity + variant by barcode. Single indexed query.
+     */
+    byBarcode(orgId: string, barcode: string): Promise<PluginResult<LookupResult>>;
+    /**
+     * Find entity + variant by SKU. Single indexed query.
+     */
+    bySku(orgId: string, sku: string): Promise<PluginResult<LookupResult>>;
+    /**
+     * Quick text search across entity attributes (name, title).
+     * Delegates to the core search service.
+     */
+    search(orgId: string, query: string): Promise<PluginResult<LookupResult[]>>;
+}
+//# sourceMappingURL=lookup-service.d.ts.map

package/dist/services/lookup-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lookup-service.d.ts","sourceRoot":"","sources":["../../src/services/lookup-service.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAE1D,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAEnC,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC5B;AAED;;;;;;GAMG;AACH,qBAAa,aAAa;IAEtB,OAAO,CAAC,EAAE;IACV,OAAO,CAAC,QAAQ;gBADR,EAAE,EAAE,EAAE,EACN,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAG3C;;OAEG;IACG,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,YAAY,CAAC,CAAC;IAiCpF;;OAEG;IACG,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,YAAY,CAAC,CAAC;IAgC5E;;;OAGG;IACG,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,YAAY,EAAE,CAAC,CAAC;CA8BlF"}

package/dist/services/lookup-service.js

@@ -0,0 +1,104 @@
+import { eq, and } from "drizzle-orm";
+import { Ok, Err } from "@unifiedcommerce/core";
+import { variants, sellableEntities } from "@unifiedcommerce/core/schema";
+/**
+ * Item lookup service for POS.
+ * Uses indexed queries on variants.barcode and variants.sku.
+ *
+ * Depends on core schema tables (variants, sellable_entities, entity_attributes)
+ * accessed via the scoped DB proxy.
+ */
+export class LookupService {
+    db;
+    services;
+    constructor(db, services) {
+        this.db = db;
+        this.services = services;
+    }
+    /**
+     * Find entity + variant by barcode. Single indexed query.
+     */
+    async byBarcode(orgId, barcode) {
+        const rows = await this.db
+            .select({
+            variantId: variants.id,
+            entityId: variants.entityId,
+            barcode: variants.barcode,
+            sku: variants.sku,
+            entityType: sellableEntities.type,
+            slug: sellableEntities.slug,
+            orgId: sellableEntities.organizationId,
+        })
+            .from(variants)
+            .innerJoin(sellableEntities, eq(variants.entityId, sellableEntities.id))
+            .where(and(eq(variants.barcode, barcode), eq(sellableEntities.organizationId, orgId)))
+            .limit(1);
+        if (rows.length === 0)
+            return Err("No item found for barcode");
+        const row = rows[0];
+        return Ok({
+            entityId: row.entityId,
+            variantId: row.variantId,
+            entityType: row.entityType,
+            slug: row.slug,
+            barcode: row.barcode,
+            sku: row.sku,
+        });
+    }
+    /**
+     * Find entity + variant by SKU. Single indexed query.
+     */
+    async bySku(orgId, sku) {
+        const rows = await this.db
+            .select({
+            variantId: variants.id,
+            entityId: variants.entityId,
+            barcode: variants.barcode,
+            sku: variants.sku,
+            entityType: sellableEntities.type,
+            slug: sellableEntities.slug,
+            orgId: sellableEntities.organizationId,
+        })
+            .from(variants)
+            .innerJoin(sellableEntities, eq(variants.entityId, sellableEntities.id))
+            .where(and(eq(variants.sku, sku), eq(sellableEntities.organizationId, orgId)))
+            .limit(1);
+        if (rows.length === 0)
+            return Err("No item found for SKU");
+        const row = rows[0];
+        return Ok({
+            entityId: row.entityId,
+            variantId: row.variantId,
+            entityType: row.entityType,
+            slug: row.slug,
+            barcode: row.barcode,
+            sku: row.sku,
+        });
+    }
+    /**
+     * Quick text search across entity attributes (name, title).
+     * Delegates to the core search service.
+     */
+    async search(orgId, query) {
+        const searchService = this.services.search;
+        if (!searchService) {
+            return Ok([]);
+        }
+        const result = await searchService.search({
+            query,
+            organizationId: orgId,
+            limit: 20,
+        });
+        if (!result.ok || !result.value)
+            return Ok([]);
+        return Ok(result.value.results.map((r) => ({
+            entityId: r.entityId,
+            variantId: "",
+            entityType: r.type,
+            slug: r.slug,
+            barcode: null,
+            sku: null,
+            title: r.title ?? undefined,
+        })));
+    }
+}

package/dist/services/payment-service.d.ts

@@ -0,0 +1,40 @@
+import type { PluginResult } from "@unifiedcommerce/core";
+import type { Db, Payment, Transaction } from "../types";
+export declare class PaymentService {
+    private db;
+    private transaction;
+    constructor(db: Db, transaction: (fn: (tx: Db) => Promise<unknown>) => Promise<unknown>);
+    /**
+     * Add a payment to a transaction. Does NOT finalize.
+     * Supports split payment (multiple calls per transaction).
+     */
+    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>>;
+    /**
+     * Get total payments collected for a transaction.
+     */
+    getPaymentTotal(transactionId: string): Promise<number>;
+    /**
+     * List all payments for a transaction.
+     */
+    listPayments(transactionId: string): Promise<PluginResult<Payment[]>>;
+    /**
+     * Validate that total payments cover the transaction total, then return
+     * the transaction details needed for checkout.
+     */
+    validateForCompletion(orgId: string, transactionId: string): Promise<PluginResult<{
+        transaction: Transaction;
+        payments: Payment[];
+        totalPaid: number;
+    }>>;
+    /**
+     * Mark payments as refunded for a transaction.
+     */
+    refundPayments(transactionId: string, tx?: Db): Promise<void>;
+}
+//# sourceMappingURL=payment-service.d.ts.map

package/dist/services/payment-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"payment-service.d.ts","sourceRoot":"","sources":["../../src/services/payment-service.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAE1D,OAAO,KAAK,EAAE,EAAE,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAEzD,qBAAa,cAAc;IAEvB,OAAO,CAAC,EAAE;IACV,OAAO,CAAC,WAAW;gBADX,EAAE,EAAE,EAAE,EACN,WAAW,EAAE,CAAC,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,KAAK,OAAO,CAAC,OAAO,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC;IAG7E;;;OAGG;IACG,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,KAAK,EAAE;QAC5D,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,WAAW,GAAG,cAAc,GAAG,OAAO,CAAC;QACjE,MAAM,EAAE,MAAM,CAAC;QACf,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACpC,GAAG,OAAO,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC;IAiClC;;OAEG;IACG,eAAe,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAc7D;;OAEG;IACG,YAAY,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,OAAO,EAAE,CAAC,CAAC;IAS3E;;;OAGG;IACG,qBAAqB,CAAC,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;QACtF,WAAW,EAAE,WAAW,CAAC;QACzB,QAAQ,EAAE,OAAO,EAAE,CAAC;QACpB,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC,CAAC;IA8BH;;OAEG;IACG,cAAc,CAAC,aAAa,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;CAOpE"}

package/dist/services/payment-service.js

@@ -0,0 +1,99 @@
+import { eq, and, sql } from "drizzle-orm";
+import { Ok, Err } from "@unifiedcommerce/core";
+import { posPayments, posTransactions } from "../schema";
+export class PaymentService {
+    db;
+    transaction;
+    constructor(db, transaction) {
+        this.db = db;
+        this.transaction = transaction;
+    }
+    /**
+     * Add a payment to a transaction. Does NOT finalize.
+     * Supports split payment (multiple calls per transaction).
+     */
+    async addPayment(orgId, transactionId, input) {
+        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) {
+        const rows = await this.db
+            .select({
+            total: sql `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) {
+        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, transactionId) {
+        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, tx) {
+        const db = tx ?? this.db;
+        await db
+            .update(posPayments)
+            .set({ status: "refunded" })
+            .where(eq(posPayments.transactionId, transactionId));
+    }
+}

package/dist/services/receipt-service.d.ts

@@ -0,0 +1,45 @@
+import type { PluginResult } from "@unifiedcommerce/core";
+import type { Db } 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 declare class ReceiptService {
+    private db;
+    private services;
+    constructor(db: Db, services: Record<string, unknown>);
+    /**
+     * Assemble full receipt data for a completed transaction.
+     */
+    getReceipt(orgId: string, transactionId: string): Promise<PluginResult<ReceiptData>>;
+    /**
+     * Send receipt via email (delegates to email service).
+     */
+    emailReceipt(orgId: string, transactionId: string, email: string): Promise<PluginResult<{
+        sent: boolean;
+    }>>;
+    private formatReceiptHtml;
+}
+//# sourceMappingURL=receipt-service.d.ts.map

package/dist/services/receipt-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"receipt-service.d.ts","sourceRoot":"","sources":["../../src/services/receipt-service.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAE1D,OAAO,KAAK,EAAE,EAAE,EAAwB,MAAM,UAAU,CAAC;AAEzD,MAAM,WAAW,WAAW;IAC1B,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,IAAI,CAAC;IAChB,SAAS,EAAE,KAAK,CAAC;QACf,KAAK,EAAE,MAAM,CAAC;QACd,QAAQ,EAAE,MAAM,CAAC;QACjB,SAAS,EAAE,MAAM,CAAC;QAClB,UAAU,EAAE,MAAM,CAAC;QACnB,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;KACvB,CAAC,CAAC;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,KAAK,CAAC;QACd,MAAM,EAAE,MAAM,CAAC;QACf,MAAM,EAAE,MAAM,CAAC;QACf,WAAW,EAAE,MAAM,CAAC;QACpB,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;KAC3B,CAAC,CAAC;IACH,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AAED,qBAAa,cAAc;IAEvB,OAAO,CAAC,EAAE;IACV,OAAO,CAAC,QAAQ;gBADR,EAAE,EAAE,EAAE,EACN,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAG3C;;OAEG;IACG,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,WAAW,CAAC,CAAC;IAkF1F;;OAEG;IACG,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;QAAE,IAAI,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IAqBjH,OAAO,CAAC,iBAAiB;CAoB1B"}

package/dist/services/receipt-service.js

@@ -0,0 +1,119 @@
+import { eq, and } from "drizzle-orm";
+import { Ok, Err } from "@unifiedcommerce/core";
+import { posTransactions, posPayments } from "../schema";
+export class ReceiptService {
+    db;
+    services;
+    constructor(db, services) {
+        this.db = db;
+        this.services = services;
+    }
+    /**
+     * Assemble full receipt data for a completed transaction.
+     */
+    async getReceipt(orgId, transactionId) {
+        // 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 = [];
+        if (txn.orderId) {
+            const orders = this.services.orders;
+            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, transactionId, email) {
+        const receiptResult = await this.getReceipt(orgId, transactionId);
+        if (!receiptResult.ok)
+            return receiptResult;
+        const emailService = this.services.email;
+        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 });
+    }
+    formatReceiptHtml(receipt) {
+        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/dist/services/return-service.d.ts

@@ -0,0 +1,27 @@
+import type { PluginResult } from "@unifiedcommerce/core";
+import type { Db, ReturnItem } from "../types";
+export declare class ReturnService {
+    private db;
+    constructor(db: Db);
+    /**
+     * Record return items linking back to an original order's line items.
+     * Called after a return transaction is created.
+     */
+    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[]>>;
+    /**
+     * Get all return items for a return transaction.
+     */
+    getReturnItems(transactionId: string): Promise<PluginResult<ReturnItem[]>>;
+    /**
+     * Calculate total refund amount for a return transaction.
+     */
+    calculateRefundTotal(transactionId: string): Promise<number>;
+}
+//# sourceMappingURL=return-service.d.ts.map

package/dist/services/return-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"return-service.d.ts","sourceRoot":"","sources":["../../src/services/return-service.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAE1D,OAAO,KAAK,EAAE,EAAE,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAE/C,qBAAa,aAAa;IACZ,OAAO,CAAC,EAAE;gBAAF,EAAE,EAAE,EAAE;IAE1B;;;OAGG;IACG,cAAc,CAAC,aAAa,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,CAAC;QACvD,eAAe,EAAE,MAAM,CAAC;QACxB,kBAAkB,EAAE,MAAM,CAAC;QAC3B,QAAQ,EAAE,MAAM,CAAC;QACjB,MAAM,EAAE,WAAW,GAAG,YAAY,GAAG,cAAc,GAAG,OAAO,CAAC;QAC9D,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,YAAY,EAAE,MAAM,CAAC;KACtB,CAAC,GAAG,OAAO,CAAC,YAAY,CAAC,UAAU,EAAE,CAAC,CAAC;IAqBxC;;OAEG;IACG,cAAc,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,UAAU,EAAE,CAAC,CAAC;IAShF;;OAEG;IACG,oBAAoB,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;CAQnE"}