@porulle/plugin-pos 0.11.0 → 0.14.0

package/dist/routes/returns.d.ts

@@ -2,6 +2,7 @@ import type { ReturnService } from "../services/return-service.js";
 import type { TransactionService } from "../services/transaction-service.js";
 import type { PaymentService } from "../services/payment-service.js";
 import type { PluginRouteRegistration } from "@porulle/core";
+import type { Db } from "../types.js";
 export declare function buildReturnRoutes(returnService: ReturnService, transactionService: TransactionService, paymentService: PaymentService, cartService: {
     create: (input: {
         currency?: string;
@@ -16,6 +17,7 @@ export declare function buildReturnRoutes(returnService: ReturnService, transact
     services?: Record<string, unknown>;
     database?: {
         db: unknown;
+        transaction?: (fn: (tx: Db) => Promise<unknown>) => Promise<unknown>;
     };
 }): PluginRouteRegistration[];
 //# sourceMappingURL=returns.d.ts.map

package/dist/routes/returns.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"returns.d.ts","sourceRoot":"","sources":["../../src/routes/returns.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AACnE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,oCAAoC,CAAC;AAC7E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AACrE,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,eAAe,CAAC;AAE7D,wBAAgB,iBAAiB,CAC/B,aAAa,EAAE,aAAa,EAC5B,kBAAkB,EAAE,kBAAkB,EACtC,cAAc,EAAE,cAAc,EAC9B,WAAW,EAAE;IAAE,MAAM,EAAE,CAAC,KAAK,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,EAAE,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC;QAAE,EAAE,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE;YAAE,EAAE,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,CAAC,CAAA;CAAE,EAC/J,GAAG,EAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,QAAQ,CAAC,EAAE;QAAE,EAAE,EAAE,OAAO,CAAA;KAAE,CAAA;CAAE,GACtE,uBAAuB,EAAE,CAgJ3B"}
+{"version":3,"file":"returns.d.ts","sourceRoot":"","sources":["../../src/routes/returns.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AACnE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,oCAAoC,CAAC;AAC7E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AACrE,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,eAAe,CAAC;AAC7D,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,aAAa,CAAC;AAQtC,wBAAgB,iBAAiB,CAC/B,aAAa,EAAE,aAAa,EAC5B,kBAAkB,EAAE,kBAAkB,EACtC,cAAc,EAAE,cAAc,EAC9B,WAAW,EAAE;IAAE,MAAM,EAAE,CAAC,KAAK,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,EAAE,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC;QAAE,EAAE,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE;YAAE,EAAE,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,CAAC,CAAA;CAAE,EAC/J,GAAG,EAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,QAAQ,CAAC,EAAE;QAAE,EAAE,EAAE,OAAO,CAAC;QAAC,WAAW,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,KAAK,OAAO,CAAC,OAAO,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;KAAE,CAAA;CAAE,GAC5I,uBAAuB,EAAE,CAwK3B"}

package/dist/routes/returns.js

@@ -1,7 +1,16 @@
-import { router } from "@porulle/core";
+import { requireUserId, router } from "@porulle/core";
 import { z } from "@hono/zod-openapi";
+const paymentInputSchema = z.object({
+    method: z.enum(["cash", "card", "gift_card", "store_credit", "other"]),
+    amount: z.number().int().positive(),
+    reference: z.string().max(200).optional(),
+});
 export function buildReturnRoutes(returnService, transactionService, paymentService, cartService, ctx) {
     const r = router("POS Returns", "/pos/returns", ctx);
+    const transactionFn = ctx.database?.transaction;
+    if (!transactionFn) {
+        throw new Error("POS returns require database.transaction from plugin context");
+    }
     r.post("/")
         .summary("Create return")
         .permission("pos:manage")
@@ -17,73 +26,75 @@ export function buildReturnRoutes(returnService, transactionService, paymentServ
             // refundAmount is NOT accepted from the client — it is computed
             // server-side from the original order (SEC-08).
         })).min(1),
+        payment: paymentInputSchema,
     }))
         .handler(async ({ input, actor, orgId }) => {
         const body = input;
-        // Create a cart for the return transaction
+        // Create a cart for the return transaction (outside the financial tx —
+        // same pattern as exchanges).
         const cartResult = await cartService.create({ currency: "USD", metadata: { posReturn: true } }, actor);
         if (!cartResult.ok || !cartResult.value) {
             throw new Error("Failed to create cart for return");
         }
-        // Create return transaction
-        const txnResult = await transactionService.create(orgId, {
-            shiftId: body.shiftId,
-            terminalId: body.terminalId,
-            operatorId: actor.userId,
-            cartId: cartResult.value.id,
-            type: "return",
-        });
-        if (!txnResult.ok)
-            throw new Error(txnResult.error);
-        // SEC-08: derive the refund server-side via orders.refundLines (the same
-        // primitive the exchange flow uses). It validates the order + line items
-        // belong to this org, enforces the per-line refundable quantity
-        // (quantity - refundedQuantity) and updates that ledger — so a fabricated
-        // or foreign order, an over-refund, or a repeat refund of the same units
-        // is rejected — and computes the amount from the recorded sale price. The
-        // client can no longer set the refund amount.
         const orders = ctx.services?.orders;
         if (!orders?.refundLines) {
             throw new Error("Orders service unavailable for return refund");
         }
-        const refundResult = await orders.refundLines(body.originalOrderId, {
-            lines: body.items.map((i) => ({ lineItemId: i.originalLineItemId, quantity: i.quantity })),
-            reason: "pos_return",
-        }, actor);
-        if (!refundResult.ok || !refundResult.value) {
-            throw new Error(refundResult.error?.message ??
-                "Return could not be validated against the original order.");
-        }
-        const serverAmountByLine = new Map(refundResult.value.refund.lines.map((l) => [l.lineItemId, l.amount]));
-        const refundTotal = refundResult.value.refund.amount;
-        // Record return items with the SERVER-computed refund amounts
-        const itemsResult = await returnService.addReturnItems(txnResult.value.id, body.items.map((item) => ({
-            ...item,
-            originalOrderId: body.originalOrderId,
-            refundAmount: serverAmountByLine.get(item.originalLineItemId) ?? 0,
-        })));
-        if (!itemsResult.ok)
-            throw new Error(itemsResult.error);
-        await transactionService.updateTotals(txnResult.value.id, {
-            subtotal: refundTotal,
-            taxTotal: 0,
-            total: refundTotal,
-            discountTotal: 0,
-        });
-        return {
-            transaction: txnResult.value,
-            returnItems: itemsResult.value,
-            refundTotal,
-        };
+        const result = await transactionFn(async (tx) => {
+            const txCtx = { tx, actor };
+            const txnResult = await transactionService.create(orgId, {
+                shiftId: body.shiftId,
+                terminalId: body.terminalId,
+                operatorId: requireUserId(actor),
+                cartId: cartResult.value.id,
+                type: "return",
+            }, tx);
+            if (!txnResult.ok)
+                throw new Error(txnResult.error);
+            const refundResult = await orders.refundLines(body.originalOrderId, {
+                lines: body.items.map((i) => ({ lineItemId: i.originalLineItemId, quantity: i.quantity })),
+                reason: "pos_return",
+            }, actor, txCtx);
+            if (!refundResult.ok || !refundResult.value) {
+                throw new Error(refundResult.error?.message ??
+                    "Return could not be validated against the original order.");
+            }
+            const serverAmountByLine = new Map(refundResult.value.refund.lines.map((l) => [l.lineItemId, l.amount]));
+            const refundTotal = refundResult.value.refund.amount;
+            if (body.payment.amount > refundTotal) {
+                throw new Error(`Payment amount ${body.payment.amount} exceeds refund total ${refundTotal}`);
+            }
+            const itemsResult = await returnService.addReturnItems(txnResult.value.id, body.items.map((item) => ({
+                ...item,
+                originalOrderId: body.originalOrderId,
+                refundAmount: serverAmountByLine.get(item.originalLineItemId) ?? 0,
+            })), tx);
+            if (!itemsResult.ok)
+                throw new Error(itemsResult.error);
+            await transactionService.updateTotals(txnResult.value.id, {
+                subtotal: refundTotal,
+                taxTotal: 0,
+                total: refundTotal,
+                discountTotal: 0,
+            }, tx);
+            const paymentResult = await paymentService.addPayment(orgId, txnResult.value.id, body.payment, tx);
+            if (!paymentResult.ok)
+                throw new Error(paymentResult.error);
+            return {
+                transaction: txnResult.value,
+                returnItems: itemsResult.value,
+                refundTotal,
+                payment: paymentResult.value,
+            };
+        }).catch((error) => error);
+        if (result instanceof Error)
+            throw result;
+        return result;
     });
     r.post("/{id}/payments")
         .summary("Add refund payment")
         .permission("pos:operate")
-        .input(z.object({
-        method: z.enum(["cash", "card", "gift_card", "store_credit", "other"]),
-        amount: z.number().int().positive(),
-        reference: z.string().max(200).optional(),
-    }))
+        .input(paymentInputSchema)
         .handler(async ({ params, input, orgId }) => {
         const body = input;
         const result = await paymentService.addPayment(orgId, params.id, body);

package/dist/routes/shifts.js

@@ -1,4 +1,4 @@
-import { router } from "@porulle/core";
+import { requireUserId, router } from "@porulle/core";
 import { z } from "@hono/zod-openapi";
 export function buildShiftRoutes(service, ctx) {
     const r = router("POS Shifts", "/pos/shifts", ctx);
@@ -13,7 +13,7 @@ export function buildShiftRoutes(service, ctx) {
         const body = input;
         const result = await service.open(orgId, {
             ...body,
-            operatorId: actor.userId,
+            operatorId: requireUserId(actor),
         });
         if (!result.ok)
             throw new Error(result.error);
@@ -36,7 +36,7 @@ export function buildShiftRoutes(service, ctx) {
         .summary("Get current open shift")
         .permission("pos:operate")
         .handler(async ({ actor, orgId }) => {
-        const result = await service.getCurrent(orgId, actor.userId);
+        const result = await service.getCurrent(orgId, requireUserId(actor));
         if (!result.ok)
             throw new Error(result.error);
         return result.value;
@@ -72,7 +72,7 @@ export function buildShiftRoutes(service, ctx) {
         const body = input;
         const result = await service.addCashEvent(params.id, {
             ...body,
-            performedBy: actor.userId,
+            performedBy: requireUserId(actor),
         });
         if (!result.ok)
             throw new Error(result.error);

package/dist/routes/transactions.js

@@ -1,4 +1,4 @@
-import { router } from "@porulle/core";
+import { requireUserId, router } from "@porulle/core";
 import { z } from "@hono/zod-openapi";
 export function buildTransactionRoutes(service, cartService, ctx) {
     const r = router("POS Transactions", "/pos/transactions", ctx);
@@ -22,7 +22,7 @@ export function buildTransactionRoutes(service, cartService, ctx) {
         const result = await service.create(orgId, {
             shiftId: body.shiftId,
             terminalId: body.terminalId,
-            operatorId: actor.userId,
+            operatorId: requireUserId(actor),
             cartId: cartResult.value.id,
             ...(body.type != null ? { type: body.type } : {}),
             ...(body.customerId != null ? { customerId: body.customerId } : {}),

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

@@ -14,11 +14,11 @@ export declare class PaymentService {
         changeGiven?: number;
         reference?: string;
         metadata?: Record<string, unknown>;
-    }): Promise<PluginResult<Payment>>;
+    }, tx?: Db): Promise<PluginResult<Payment>>;
     /**
      * Get total payments collected for a transaction.
      */
-    getPaymentTotal(transactionId: string): Promise<number>;
+    getPaymentTotal(transactionId: string, tx?: Db): Promise<number>;
     /**
      * List all payments for a transaction.
      */

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

@@ -1 +1 @@
-{"version":3,"file":"payment-service.d.ts","sourceRoot":"","sources":["../../src/services/payment-service.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAElD,OAAO,KAAK,EAAE,EAAE,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE5D,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"}
+{"version":3,"file":"payment-service.d.ts","sourceRoot":"","sources":["../../src/services/payment-service.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAElD,OAAO,KAAK,EAAE,EAAE,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE5D,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,EAAE,EAAE,CAAC,EAAE,EAAE,GAAG,OAAO,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC;IA0C3C;;OAEG;IACG,eAAe,CAAC,aAAa,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC;IAetE;;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

@@ -12,11 +12,12 @@ export class PaymentService {
      * Add a payment to a transaction. Does NOT finalize.
      * Supports split payment (multiple calls per transaction).
      */
-    async addPayment(orgId, transactionId, input) {
+    async addPayment(orgId, transactionId, input, tx) {
         if (input.amount <= 0)
             return Err("Payment amount must be positive");
+        const db = tx ?? this.db;
         // Verify transaction is open
-        const txns = await this.db
+        const txns = await db
             .select()
             .from(posTransactions)
             .where(and(eq(posTransactions.id, transactionId), eq(posTransactions.organizationId, orgId)));
@@ -25,7 +26,13 @@ export class PaymentService {
         const txn = txns[0];
         if (txn.status !== "open")
             return Err("Transaction is not open");
-        const rows = await this.db
+        if (txn.type === "return" && txn.total > 0) {
+            const currentPaid = await this.getPaymentTotal(transactionId, db);
+            if (currentPaid + input.amount > txn.total) {
+                return Err(`Payment would exceed refund total: ${currentPaid + input.amount} > ${txn.total}`);
+            }
+        }
+        const rows = await db
             .insert(posPayments)
             .values({
             transactionId,
@@ -43,8 +50,9 @@ export class PaymentService {
     /**
      * Get total payments collected for a transaction.
      */
-    async getPaymentTotal(transactionId) {
-        const rows = await this.db
+    async getPaymentTotal(transactionId, tx) {
+        const db = tx ?? this.db;
+        const rows = await db
             .select({
             total: sql `COALESCE(SUM(${posPayments.amount} - ${posPayments.changeGiven}), 0)`.as("total"),
         })

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

@@ -14,7 +14,7 @@ export declare class ReturnService {
         reason: "defective" | "wrong_item" | "changed_mind" | "other";
         restockingFee?: number;
         refundAmount: number;
-    }>): Promise<PluginResult<ReturnItem[]>>;
+    }>, tx?: Db): Promise<PluginResult<ReturnItem[]>>;
     /**
      * Get all return items for a return transaction.
      */

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

@@ -1 +1 @@
-{"version":3,"file":"return-service.d.ts","sourceRoot":"","sources":["../../src/services/return-service.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAElD,OAAO,KAAK,EAAE,EAAE,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAElD,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"}
+{"version":3,"file":"return-service.d.ts","sourceRoot":"","sources":["../../src/services/return-service.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAElD,OAAO,KAAK,EAAE,EAAE,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAElD,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,EAAE,EAAE,CAAC,EAAE,EAAE,GAAG,OAAO,CAAC,YAAY,CAAC,UAAU,EAAE,CAAC,CAAC;IAsBjD;;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"}

package/dist/services/return-service.js

@@ -10,9 +10,10 @@ export class ReturnService {
      * Record return items linking back to an original order's line items.
      * Called after a return transaction is created.
      */
-    async addReturnItems(transactionId, items) {
+    async addReturnItems(transactionId, items, tx) {
         if (items.length === 0)
             return Err("At least one item is required");
+        const db = tx ?? this.db;
         const values = items.map((item) => ({
             transactionId,
             originalOrderId: item.originalOrderId,
@@ -22,7 +23,7 @@ export class ReturnService {
             restockingFee: item.restockingFee ?? 0,
             refundAmount: item.refundAmount,
         }));
-        const rows = await this.db
+        const rows = await db
             .insert(posReturnItems)
             .values(values)
             .returning();

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

@@ -11,7 +11,7 @@ export declare class TransactionService {
         cartId: string;
         type?: "sale" | "return" | "exchange";
         customerId?: string;
-    }): Promise<PluginResult<Transaction>>;
+    }, tx?: Db): Promise<PluginResult<Transaction>>;
     getById(orgId: string, id: string): Promise<PluginResult<Transaction>>;
     hold(orgId: string, id: string, label: string): Promise<PluginResult<Transaction>>;
     recall(orgId: string, id: string): Promise<PluginResult<Transaction>>;
@@ -23,7 +23,7 @@ export declare class TransactionService {
         taxTotal: number;
         total: number;
         discountTotal: number;
-    }): Promise<void>;
+    }, tx?: Db): Promise<void>;
     complete(id: string, orderId: string | null): Promise<PluginResult<Transaction>>;
     private generateReceiptNumber;
 }

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

@@ -1 +1 @@
-{"version":3,"file":"transaction-service.d.ts","sourceRoot":"","sources":["../../src/services/transaction-service.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAElD,OAAO,KAAK,EAAE,EAAE,EAAE,WAAW,EAAqB,MAAM,aAAa,CAAC;AAEtE,qBAAa,kBAAkB;IAE3B,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;IAGvE,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE;QACjC,OAAO,EAAE,MAAM,CAAC;QAChB,UAAU,EAAE,MAAM,CAAC;QACnB,UAAU,EAAE,MAAM,CAAC;QACnB,MAAM,EAAE,MAAM,CAAC;QACf,IAAI,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,UAAU,CAAC;QACtC,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,GAAG,OAAO,CAAC,YAAY,CAAC,WAAW,CAAC,CAAC;IA4BhC,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,WAAW,CAAC,CAAC;IAUtE,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,WAAW,CAAC,CAAC;IAclF,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,WAAW,CAAC,CAAC;IAcrE,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,WAAW,EAAE,CAAC,CAAC;IAcjF,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,WAAW,CAAC,CAAC;IAgCnF,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,WAAW,CAAC,CAAC;IAc9F,YAAY,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE;QACrC,QAAQ,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;QACjB,KAAK,EAAE,MAAM,CAAC;QACd,aAAa,EAAE,MAAM,CAAC;KACvB,GAAG,OAAO,CAAC,IAAI,CAAC;IAOX,QAAQ,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,YAAY,CAAC,WAAW,CAAC,CAAC;YAgExE,qBAAqB;CA2BpC"}
+{"version":3,"file":"transaction-service.d.ts","sourceRoot":"","sources":["../../src/services/transaction-service.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAElD,OAAO,KAAK,EAAE,EAAE,EAAE,WAAW,EAAqB,MAAM,aAAa,CAAC;AAEtE,qBAAa,kBAAkB;IAE3B,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;IAGvE,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE;QACjC,OAAO,EAAE,MAAM,CAAC;QAChB,UAAU,EAAE,MAAM,CAAC;QACnB,UAAU,EAAE,MAAM,CAAC;QACnB,MAAM,EAAE,MAAM,CAAC;QACf,IAAI,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,UAAU,CAAC;QACtC,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,EAAE,EAAE,CAAC,EAAE,EAAE,GAAG,OAAO,CAAC,YAAY,CAAC,WAAW,CAAC,CAAC;IA8BzC,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,WAAW,CAAC,CAAC;IAUtE,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,WAAW,CAAC,CAAC;IAclF,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,WAAW,CAAC,CAAC;IAcrE,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,WAAW,EAAE,CAAC,CAAC;IAcjF,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,WAAW,CAAC,CAAC;IAgCnF,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,WAAW,CAAC,CAAC;IAc9F,YAAY,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE;QACrC,QAAQ,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;QACjB,KAAK,EAAE,MAAM,CAAC;QACd,aAAa,EAAE,MAAM,CAAC;KACvB,EAAE,EAAE,CAAC,EAAE,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAQpB,QAAQ,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,YAAY,CAAC,WAAW,CAAC,CAAC;YAgExE,qBAAqB;CA4BpC"}

package/dist/services/transaction-service.js

@@ -8,16 +8,17 @@ export class TransactionService {
         this.db = db;
         this.transaction = transaction;
     }
-    async create(orgId, input) {
+    async create(orgId, input, tx) {
+        const db = tx ?? this.db;
         // Verify shift is open
-        const shifts = await this.db
+        const shifts = await db
             .select()
             .from(posShifts)
             .where(and(eq(posShifts.id, input.shiftId), eq(posShifts.status, "open")));
         if (shifts.length === 0)
             return Err("Shift is not open");
-        const receiptNumber = await this.generateReceiptNumber(orgId, input.terminalId);
-        const rows = await this.db
+        const receiptNumber = await this.generateReceiptNumber(orgId, input.terminalId, db);
+        const rows = await db
             .insert(posTransactions)
             .values({
             organizationId: orgId,
@@ -117,8 +118,9 @@ export class TransactionService {
             .returning();
         return Ok(rows[0]);
     }
-    async updateTotals(id, totals) {
-        await this.db
+    async updateTotals(id, totals, tx) {
+        const db = tx ?? this.db;
+        await db
             .update(posTransactions)
             .set({ ...totals, updatedAt: new Date() })
             .where(eq(posTransactions.id, id));
@@ -180,19 +182,20 @@ export class TransactionService {
     }
     // ─── Receipt Number Generation ─────────────────────────────────────
     // Sequential per terminal per day: {terminal_code}-{sequence}
-    async generateReceiptNumber(orgId, terminalId) {
+    async generateReceiptNumber(orgId, terminalId, tx) {
+        const db = tx ?? this.db;
         const today = new Date();
         const startOfDay = new Date(today.getFullYear(), today.getMonth(), today.getDate());
         const startOfDayISO = startOfDay.toISOString();
         // Get terminal code
         const { posTerminals } = await import("../schema.js");
-        const terminals = await this.db
+        const terminals = await db
             .select({ code: posTerminals.code })
             .from(posTerminals)
             .where(eq(posTerminals.id, terminalId));
         const terminalCode = terminals[0]?.code ?? "POS";
         // Count today's transactions for this terminal
-        const countRows = await this.db
+        const countRows = await db
             .select({ count: sql `COUNT(*)`.as("count") })
             .from(posTransactions)
             .where(and(eq(posTransactions.organizationId, orgId), eq(posTransactions.terminalId, terminalId), sql `${posTransactions.createdAt} >= ${startOfDayISO}::timestamptz`));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@porulle/plugin-pos",
-  "version": "0.11.0",
+  "version": "0.14.0",
   "license": "MIT",
   "type": "module",
   "exports": {
@@ -19,8 +19,8 @@
   "dependencies": {
     "@hono/zod-openapi": "^1.2.2",
     "hono": "^4.12.5",
-    "@porulle/core": "0.11.0",
-    "@porulle/db": "0.11.0"
+    "@porulle/core": "0.14.0",
+    "@porulle/db": "0.14.0"
   },
   "devDependencies": {
     "@types/node": "^24.5.2",

package/src/routes/returns.ts

@@ -1,18 +1,29 @@
-import { router } from "@porulle/core";
+import { requireUserId, router } from "@porulle/core";
 import { z } from "@hono/zod-openapi";
 import type { ReturnService } from "../services/return-service.js";
 import type { TransactionService } from "../services/transaction-service.js";
 import type { PaymentService } from "../services/payment-service.js";
 import type { PluginRouteRegistration } from "@porulle/core";
+import type { Db } from "../types.js";
+
+const paymentInputSchema = z.object({
+  method: z.enum(["cash", "card", "gift_card", "store_credit", "other"]),
+  amount: z.number().int().positive(),
+  reference: z.string().max(200).optional(),
+});
 
 export function buildReturnRoutes(
   returnService: ReturnService,
   transactionService: TransactionService,
   paymentService: PaymentService,
   cartService: { create: (input: { currency?: string; metadata?: Record<string, unknown> }, actor: unknown) => Promise<{ ok: boolean; value?: { id: string } }> },
-  ctx: { services?: Record<string, unknown>; database?: { db: unknown } },
+  ctx: { services?: Record<string, unknown>; database?: { db: unknown; transaction?: (fn: (tx: Db) => Promise<unknown>) => Promise<unknown> } },
 ): PluginRouteRegistration[] {
   const r = router("POS Returns", "/pos/returns", ctx);
+  const transactionFn = ctx.database?.transaction;
+  if (!transactionFn) {
+    throw new Error("POS returns require database.transaction from plugin context");
+  }
 
   r.post("/")
     .summary("Create return")
@@ -29,6 +40,7 @@ export function buildReturnRoutes(
         // refundAmount is NOT accepted from the client — it is computed
         // server-side from the original order (SEC-08).
       })).min(1),
+      payment: paymentInputSchema,
     }))
     .handler(async ({ input, actor, orgId }) => {
       const body = input as {
@@ -41,9 +53,15 @@ export function buildReturnRoutes(
           reason: "defective" | "wrong_item" | "changed_mind" | "other";
           restockingFee?: number;
         }>;
+        payment: {
+          method: "cash" | "card" | "gift_card" | "store_credit" | "other";
+          amount: number;
+          reference?: string;
+        };
       };
 
-      // Create a cart for the return transaction
+      // Create a cart for the return transaction (outside the financial tx —
+      // same pattern as exchanges).
       const cartResult = await cartService.create(
         { currency: "USD", metadata: { posReturn: true } },
         actor,
@@ -52,29 +70,13 @@ export function buildReturnRoutes(
         throw new Error("Failed to create cart for return");
       }
 
-      // Create return transaction
-      const txnResult = await transactionService.create(orgId, {
-        shiftId: body.shiftId,
-        terminalId: body.terminalId,
-        operatorId: actor!.userId,
-        cartId: cartResult.value.id,
-        type: "return",
-      });
-      if (!txnResult.ok) throw new Error(txnResult.error);
-
-      // SEC-08: derive the refund server-side via orders.refundLines (the same
-      // primitive the exchange flow uses). It validates the order + line items
-      // belong to this org, enforces the per-line refundable quantity
-      // (quantity - refundedQuantity) and updates that ledger — so a fabricated
-      // or foreign order, an over-refund, or a repeat refund of the same units
-      // is rejected — and computes the amount from the recorded sale price. The
-      // client can no longer set the refund amount.
       const orders = ctx.services?.orders as
         | {
             refundLines(
               orderId: string,
               refundInput: { lines: Array<{ lineItemId: string; quantity: number }>; reason?: string },
               actor: unknown,
+              txCtx?: { tx: Db; actor: unknown },
             ): Promise<{
               ok: boolean;
               value?: { refund: { amount: number; lines: Array<{ lineItemId: string; quantity: number; amount: number }> } };
@@ -86,58 +88,87 @@ export function buildReturnRoutes(
         throw new Error("Orders service unavailable for return refund");
       }
 
-      const refundResult = await orders.refundLines(
-        body.originalOrderId,
-        {
-          lines: body.items.map((i) => ({ lineItemId: i.originalLineItemId, quantity: i.quantity })),
-          reason: "pos_return",
-        },
-        actor,
-      );
-      if (!refundResult.ok || !refundResult.value) {
-        throw new Error(
-          refundResult.error?.message ??
-            "Return could not be validated against the original order.",
+      const result = await transactionFn(async (tx) => {
+        const txCtx = { tx, actor };
+
+        const txnResult = await transactionService.create(orgId, {
+          shiftId: body.shiftId,
+          terminalId: body.terminalId,
+          operatorId: requireUserId(actor),
+          cartId: cartResult.value!.id,
+          type: "return",
+        }, tx);
+        if (!txnResult.ok) throw new Error(txnResult.error);
+
+        const refundResult = await orders.refundLines(
+          body.originalOrderId,
+          {
+            lines: body.items.map((i) => ({ lineItemId: i.originalLineItemId, quantity: i.quantity })),
+            reason: "pos_return",
+          },
+          actor,
+          txCtx,
         );
-      }
-      const serverAmountByLine = new Map(
-        refundResult.value.refund.lines.map((l) => [l.lineItemId, l.amount]),
-      );
-      const refundTotal = refundResult.value.refund.amount;
-
-      // Record return items with the SERVER-computed refund amounts
-      const itemsResult = await returnService.addReturnItems(
-        txnResult.value.id,
-        body.items.map((item) => ({
-          ...item,
-          originalOrderId: body.originalOrderId,
-          refundAmount: serverAmountByLine.get(item.originalLineItemId) ?? 0,
-        })),
-      );
-      if (!itemsResult.ok) throw new Error(itemsResult.error);
-
-      await transactionService.updateTotals(txnResult.value.id, {
-        subtotal: refundTotal,
-        taxTotal: 0,
-        total: refundTotal,
-        discountTotal: 0,
-      });
-
-      return {
-        transaction: txnResult.value,
-        returnItems: itemsResult.value,
-        refundTotal,
-      };
+        if (!refundResult.ok || !refundResult.value) {
+          throw new Error(
+            refundResult.error?.message ??
+              "Return could not be validated against the original order.",
+          );
+        }
+
+        const serverAmountByLine = new Map(
+          refundResult.value.refund.lines.map((l) => [l.lineItemId, l.amount]),
+        );
+        const refundTotal = refundResult.value.refund.amount;
+
+        if (body.payment.amount > refundTotal) {
+          throw new Error(
+            `Payment amount ${body.payment.amount} exceeds refund total ${refundTotal}`,
+          );
+        }
+
+        const itemsResult = await returnService.addReturnItems(
+          txnResult.value.id,
+          body.items.map((item) => ({
+            ...item,
+            originalOrderId: body.originalOrderId,
+            refundAmount: serverAmountByLine.get(item.originalLineItemId) ?? 0,
+          })),
+          tx,
+        );
+        if (!itemsResult.ok) throw new Error(itemsResult.error);
+
+        await transactionService.updateTotals(txnResult.value.id, {
+          subtotal: refundTotal,
+          taxTotal: 0,
+          total: refundTotal,
+          discountTotal: 0,
+        }, tx);
+
+        const paymentResult = await paymentService.addPayment(
+          orgId,
+          txnResult.value.id,
+          body.payment,
+          tx,
+        );
+        if (!paymentResult.ok) throw new Error(paymentResult.error);
+
+        return {
+          transaction: txnResult.value,
+          returnItems: itemsResult.value,
+          refundTotal,
+          payment: paymentResult.value,
+        };
+      }).catch((error: unknown) => error as Error);
+
+      if (result instanceof Error) throw result;
+      return result;
     });
 
   r.post("/{id}/payments")
     .summary("Add refund payment")
     .permission("pos:operate")
-    .input(z.object({
-      method: z.enum(["cash", "card", "gift_card", "store_credit", "other"]),
-      amount: z.number().int().positive(),
-      reference: z.string().max(200).optional(),
-    }))
+    .input(paymentInputSchema)
     .handler(async ({ params, input, orgId }) => {
       const body = input as { method: "cash" | "card" | "gift_card" | "store_credit" | "other"; amount: number; reference?: string };
       const result = await paymentService.addPayment(orgId, params.id!, body);

package/src/routes/shifts.ts

@@ -1,4 +1,4 @@
-import { router } from "@porulle/core";
+import { requireUserId, router } from "@porulle/core";
 import { z } from "@hono/zod-openapi";
 import type { ShiftService } from "../services/shift-service.js";
 import type { PluginRouteRegistration } from "@porulle/core";
@@ -20,7 +20,7 @@ export function buildShiftRoutes(
       const body = input as { terminalId: string; openingFloat: number };
       const result = await service.open(orgId, {
         ...body,
-        operatorId: actor!.userId,
+        operatorId: requireUserId(actor),
       });
       if (!result.ok) throw new Error(result.error);
       return result.value;
@@ -43,7 +43,7 @@ export function buildShiftRoutes(
     .summary("Get current open shift")
     .permission("pos:operate")
     .handler(async ({ actor, orgId }) => {
-      const result = await service.getCurrent(orgId, actor!.userId);
+      const result = await service.getCurrent(orgId, requireUserId(actor));
       if (!result.ok) throw new Error(result.error);
       return result.value;
     });
@@ -80,7 +80,7 @@ export function buildShiftRoutes(
       const body = input as { type: "drop" | "pickup" | "paid_in" | "paid_out"; amount: number; reason?: string };
       const result = await service.addCashEvent(params.id!, {
         ...body,
-        performedBy: actor!.userId,
+        performedBy: requireUserId(actor),
       });
 
       if (!result.ok) throw new Error(result.error);

package/src/routes/transactions.ts

@@ -1,4 +1,4 @@
-import { router } from "@porulle/core";
+import { requireUserId, router } from "@porulle/core";
 import { z } from "@hono/zod-openapi";
 import type { TransactionService } from "../services/transaction-service.js";
 import type { PluginRouteRegistration } from "@porulle/core";
@@ -35,7 +35,7 @@ export function buildTransactionRoutes(
       const result = await service.create(orgId, {
         shiftId: body.shiftId,
         terminalId: body.terminalId,
-        operatorId: actor!.userId,
+        operatorId: requireUserId(actor),
         cartId: cartResult.value.id,
         ...(body.type != null ? { type: body.type } : {}),
         ...(body.customerId != null ? { customerId: body.customerId } : {}),

package/src/services/payment-service.ts

@@ -20,11 +20,13 @@ export class PaymentService {
     changeGiven?: number;
     reference?: string;
     metadata?: Record<string, unknown>;
-  }): Promise<PluginResult<Payment>> {
+  }, tx?: Db): Promise<PluginResult<Payment>> {
     if (input.amount <= 0) return Err("Payment amount must be positive");
 
+    const db = tx ?? this.db;
+
     // Verify transaction is open
-    const txns = await this.db
+    const txns = await db
       .select()
       .from(posTransactions)
       .where(and(
@@ -36,7 +38,14 @@ export class PaymentService {
     const txn = txns[0]!;
     if (txn.status !== "open") return Err("Transaction is not open");
 
-    const rows = await this.db
+    if (txn.type === "return" && txn.total > 0) {
+      const currentPaid = await this.getPaymentTotal(transactionId, db);
+      if (currentPaid + input.amount > txn.total) {
+        return Err(`Payment would exceed refund total: ${currentPaid + input.amount} > ${txn.total}`);
+      }
+    }
+
+    const rows = await db
       .insert(posPayments)
       .values({
         transactionId,
@@ -56,8 +65,9 @@ export class PaymentService {
   /**
    * Get total payments collected for a transaction.
    */
-  async getPaymentTotal(transactionId: string): Promise<number> {
-    const rows = await this.db
+  async getPaymentTotal(transactionId: string, tx?: Db): Promise<number> {
+    const db = tx ?? this.db;
+    const rows = await db
       .select({
         total: sql<number>`COALESCE(SUM(${posPayments.amount} - ${posPayments.changeGiven}), 0)`.as("total"),
       })

package/src/services/return-service.ts

@@ -18,9 +18,10 @@ export class ReturnService {
     reason: "defective" | "wrong_item" | "changed_mind" | "other";
     restockingFee?: number;
     refundAmount: number;
-  }>): Promise<PluginResult<ReturnItem[]>> {
+  }>, tx?: Db): Promise<PluginResult<ReturnItem[]>> {
     if (items.length === 0) return Err("At least one item is required");
 
+    const db = tx ?? this.db;
     const values = items.map((item) => ({
       transactionId,
       originalOrderId: item.originalOrderId,
@@ -31,7 +32,7 @@ export class ReturnService {
       refundAmount: item.refundAmount,
     }));
 
-    const rows = await this.db
+    const rows = await db
       .insert(posReturnItems)
       .values(values)
       .returning();

package/src/services/transaction-service.ts

@@ -17,17 +17,19 @@ export class TransactionService {
     cartId: string;
     type?: "sale" | "return" | "exchange";
     customerId?: string;
-  }): Promise<PluginResult<Transaction>> {
+  }, tx?: Db): Promise<PluginResult<Transaction>> {
+    const db = tx ?? this.db;
+
     // Verify shift is open
-    const shifts = await this.db
+    const shifts = await db
       .select()
       .from(posShifts)
       .where(and(eq(posShifts.id, input.shiftId), eq(posShifts.status, "open")));
     if (shifts.length === 0) return Err("Shift is not open");
 
-    const receiptNumber = await this.generateReceiptNumber(orgId, input.terminalId);
+    const receiptNumber = await this.generateReceiptNumber(orgId, input.terminalId, db);
 
-    const rows = await this.db
+    const rows = await db
       .insert(posTransactions)
       .values({
         organizationId: orgId,
@@ -148,8 +150,9 @@ export class TransactionService {
     taxTotal: number;
     total: number;
     discountTotal: number;
-  }): Promise<void> {
-    await this.db
+  }, tx?: Db): Promise<void> {
+    const db = tx ?? this.db;
+    await db
       .update(posTransactions)
       .set({ ...totals, updatedAt: new Date() })
       .where(eq(posTransactions.id, id));
@@ -219,14 +222,15 @@ export class TransactionService {
   // ─── Receipt Number Generation ─────────────────────────────────────
   // Sequential per terminal per day: {terminal_code}-{sequence}
 
-  private async generateReceiptNumber(orgId: string, terminalId: string): Promise<string> {
+  private async generateReceiptNumber(orgId: string, terminalId: string, tx?: Db): Promise<string> {
+    const db = tx ?? this.db;
     const today = new Date();
     const startOfDay = new Date(today.getFullYear(), today.getMonth(), today.getDate());
     const startOfDayISO = startOfDay.toISOString();
 
     // Get terminal code
     const { posTerminals } = await import("../schema.js");
-    const terminals = await this.db
+    const terminals = await db
       .select({ code: posTerminals.code })
       .from(posTerminals)
       .where(eq(posTerminals.id, terminalId));
@@ -234,7 +238,7 @@ export class TransactionService {
     const terminalCode = terminals[0]?.code ?? "POS";
 
     // Count today's transactions for this terminal
-    const countRows = await this.db
+    const countRows = await db
       .select({ count: sql<number>`COUNT(*)`.as("count") })
       .from(posTransactions)
       .where(and(