@porulle/plugin-pos 0.7.0 → 0.9.0

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,QAAQ,IAAI,EAAE,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,KAAK,EACV,YAAY,EACZ,SAAS,EACT,aAAa,EACb,eAAe,EACf,WAAW,EACX,cAAc,EACf,MAAM,aAAa,CAAC;AAErB,MAAM,MAAM,QAAQ,GAAG,OAAO,YAAY,CAAC,YAAY,CAAC;AACxD,MAAM,MAAM,cAAc,GAAG,OAAO,YAAY,CAAC,YAAY,CAAC;AAE9D,MAAM,MAAM,KAAK,GAAG,OAAO,SAAS,CAAC,YAAY,CAAC;AAClD,MAAM,MAAM,WAAW,GAAG,OAAO,SAAS,CAAC,YAAY,CAAC;AAExD,MAAM,MAAM,SAAS,GAAG,OAAO,aAAa,CAAC,YAAY,CAAC;AAC1D,MAAM,MAAM,eAAe,GAAG,OAAO,aAAa,CAAC,YAAY,CAAC;AAEhE,MAAM,MAAM,WAAW,GAAG,OAAO,eAAe,CAAC,YAAY,CAAC;AAC9D,MAAM,MAAM,iBAAiB,GAAG,OAAO,eAAe,CAAC,YAAY,CAAC;AAEpE,MAAM,MAAM,OAAO,GAAG,OAAO,WAAW,CAAC,YAAY,CAAC;AACtD,MAAM,MAAM,aAAa,GAAG,OAAO,WAAW,CAAC,YAAY,CAAC;AAE5D,MAAM,MAAM,UAAU,GAAG,OAAO,cAAc,CAAC,YAAY,CAAC;AAC5D,MAAM,MAAM,gBAAgB,GAAG,OAAO,cAAc,CAAC,YAAY,CAAC;AAElE,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,MAAM,GAAG,WAAW,GAAG,QAAQ,CAAC;AACzE,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,QAAQ,GAAG,UAAU,CAAC;AAC7D,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,MAAM,GAAG,WAAW,GAAG,cAAc,GAAG,OAAO,CAAC;AACrF,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,MAAM,GAAG,QAAQ,GAAG,SAAS,GAAG,UAAU,CAAC;AACjF,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,QAAQ,CAAC;AAC5C,MAAM,MAAM,YAAY,GAAG,UAAU,GAAG,QAAQ,GAAG,QAAQ,GAAG,OAAO,CAAC;AAEtE,MAAM,WAAW,gBAAgB;IAC/B,4DAA4D;IAC5D,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,mEAAmE;IACnE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gFAAgF;IAChF,yBAAyB,CAAC,EAAE,MAAM,CAAC;CACpC;AAED,eAAO,MAAM,mBAAmB,EAAE,QAAQ,CAAC,gBAAgB,CAI1D,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,QAAQ,IAAI,EAAE,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,KAAK,EACV,YAAY,EACZ,SAAS,EACT,aAAa,EACb,eAAe,EACf,WAAW,EACX,cAAc,EACd,eAAe,EACf,cAAc,EACf,MAAM,aAAa,CAAC;AAErB,MAAM,MAAM,QAAQ,GAAG,OAAO,YAAY,CAAC,YAAY,CAAC;AACxD,MAAM,MAAM,cAAc,GAAG,OAAO,YAAY,CAAC,YAAY,CAAC;AAE9D,MAAM,MAAM,KAAK,GAAG,OAAO,SAAS,CAAC,YAAY,CAAC;AAClD,MAAM,MAAM,WAAW,GAAG,OAAO,SAAS,CAAC,YAAY,CAAC;AAExD,MAAM,MAAM,SAAS,GAAG,OAAO,aAAa,CAAC,YAAY,CAAC;AAC1D,MAAM,MAAM,eAAe,GAAG,OAAO,aAAa,CAAC,YAAY,CAAC;AAEhE,MAAM,MAAM,WAAW,GAAG,OAAO,eAAe,CAAC,YAAY,CAAC;AAC9D,MAAM,MAAM,iBAAiB,GAAG,OAAO,eAAe,CAAC,YAAY,CAAC;AAEpE,MAAM,MAAM,OAAO,GAAG,OAAO,WAAW,CAAC,YAAY,CAAC;AACtD,MAAM,MAAM,aAAa,GAAG,OAAO,WAAW,CAAC,YAAY,CAAC;AAE5D,MAAM,MAAM,UAAU,GAAG,OAAO,cAAc,CAAC,YAAY,CAAC;AAC5D,MAAM,MAAM,gBAAgB,GAAG,OAAO,cAAc,CAAC,YAAY,CAAC;AAElE,MAAM,MAAM,WAAW,GAAG,OAAO,eAAe,CAAC,YAAY,CAAC;AAC9D,MAAM,MAAM,iBAAiB,GAAG,OAAO,eAAe,CAAC,YAAY,CAAC;AAEpE,MAAM,MAAM,UAAU,GAAG,OAAO,cAAc,CAAC,YAAY,CAAC;AAC5D,MAAM,MAAM,gBAAgB,GAAG,OAAO,cAAc,CAAC,YAAY,CAAC;AAElE,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,MAAM,GAAG,WAAW,GAAG,QAAQ,CAAC;AACzE,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,QAAQ,GAAG,UAAU,CAAC;AAC7D,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,MAAM,GAAG,WAAW,GAAG,cAAc,GAAG,OAAO,CAAC;AACrF,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,MAAM,GAAG,QAAQ,GAAG,SAAS,GAAG,UAAU,CAAC;AACjF,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,QAAQ,CAAC;AAC5C,MAAM,MAAM,YAAY,GAAG,UAAU,GAAG,QAAQ,GAAG,QAAQ,GAAG,OAAO,CAAC;AAEtE,MAAM,WAAW,gBAAgB;IAC/B,4DAA4D;IAC5D,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,mEAAmE;IACnE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gFAAgF;IAChF,yBAAyB,CAAC,EAAE,MAAM,CAAC;IACnC,oCAAoC;IACpC,OAAO,CAAC,EAAE;QACR,kEAAkE;QAClE,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,kEAAkE;QAClE,oBAAoB,CAAC,EAAE,MAAM,CAAC;QAC9B,+DAA+D;QAC/D,kBAAkB,CAAC,EAAE,MAAM,CAAC;QAC5B,qFAAqF;QACrF,oBAAoB,CAAC,EAAE,MAAM,CAAC;KAC/B,CAAC;CACH;AAED,eAAO,MAAM,mBAAmB,EAAE,QAAQ,CAAC,gBAAgB,CAK1D,CAAC"}

package/dist/types.js

@@ -2,4 +2,5 @@ export const DEFAULT_POS_OPTIONS = {
     defaultCurrency: "USD",
     maxHoldHours: 24,
     discountOverrideThreshold: 20,
+    pinAuth: {},
 };

package/package.json

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

package/src/hooks/checkout-pos.ts

@@ -5,7 +5,7 @@
  * checkout.afterCreate: Updates POS transaction with orderId, increments shift counters.
  */
 
-import { eq, sql } from "@porulle/core/drizzle";
+import { eq, and, sql } from "@porulle/core/drizzle";
 import { posTransactions, posShifts } from "../schema.js";
 import type { Db } from "../types.js";
 
@@ -79,6 +79,13 @@ export function buildPOSFinalizationHook(getDb: () => Db) {
       // Increment shift sales counters
       const posShiftId = metadata?.posShiftId as string | undefined;
       if (posShiftId) {
+        const txnRows = await db
+          .select({ organizationId: posTransactions.organizationId })
+          .from(posTransactions)
+          .where(eq(posTransactions.id, posTransactionId));
+        const orgId = txnRows[0]?.organizationId;
+        if (!orgId) return;
+
         await db
           .update(posShifts)
           .set({
@@ -86,7 +93,7 @@ export function buildPOSFinalizationHook(getDb: () => Db) {
             salesTotal: sql`${posShifts.salesTotal} + ${result.grandTotal ?? 0}`,
             updatedAt: new Date(),
           })
-          .where(eq(posShifts.id, posShiftId));
+          .where(and(eq(posShifts.id, posShiftId), eq(posShifts.organizationId, orgId)));
       }
     },
   };

package/src/index.ts

@@ -6,6 +6,8 @@ import {
   posTransactions,
   posPayments,
   posReturnItems,
+  posOperatorPins,
+  posPinAttempts,
 } from "./schema.js";
 import { TerminalService } from "./services/terminal-service.js";
 import { ShiftService } from "./services/shift-service.js";
@@ -14,6 +16,8 @@ import { PaymentService } from "./services/payment-service.js";
 import { ReturnService } from "./services/return-service.js";
 import { LookupService } from "./services/lookup-service.js";
 import { ReceiptService } from "./services/receipt-service.js";
+import { PinService } from "./services/pin-service.js";
+import { ExchangeService } from "./services/exchange-service.js";
 import { buildTerminalRoutes } from "./routes/terminals.js";
 import { buildShiftRoutes } from "./routes/shifts.js";
 import { buildTransactionRoutes } from "./routes/transactions.js";
@@ -21,6 +25,8 @@ import { buildPaymentRoutes } from "./routes/payments.js";
 import { buildReturnRoutes } from "./routes/returns.js";
 import { buildLookupRoutes } from "./routes/lookup.js";
 import { buildReceiptRoutes } from "./routes/receipts.js";
+import { buildPinAuthRoutes } from "./routes/auth.js";
+import { buildExchangeRoutes } from "./routes/exchanges.js";
 import { buildPOSShippingHook, buildPOSFinalizationHook } from "./hooks/checkout-pos.js";
 import type { POSPluginOptions, Db } from "./types.js";
 import { DEFAULT_POS_OPTIONS } from "./types.js";
@@ -33,6 +39,8 @@ export { PaymentService } from "./services/payment-service.js";
 export { ReturnService } from "./services/return-service.js";
 export { LookupService } from "./services/lookup-service.js";
 export { ReceiptService } from "./services/receipt-service.js";
+export { PinService, hashPin, verifyPinHash } from "./services/pin-service.js";
+export { ExchangeService } from "./services/exchange-service.js";
 export { createPOSPaymentAdapter } from "./payment-adapter.js";
 
 /**
@@ -84,6 +92,21 @@ export function posPlugin(userOptions: POSPluginOptions = {}) {
       posTransactions,
       posPayments,
       posReturnItems,
+      posOperatorPins,
+      posPinAttempts,
+    }),
+
+    // Scope used by PIN login to mint per-shift credentials (issue #51).
+    apiKeyScopes: () => ({
+      [options.pinAuth.apiKeyScope ?? "pos"]: {
+        prefix: "pos_shift_",
+        description: "Short-lived per-shift POS credentials minted by PIN login.",
+        permissions: { pos: ["operate"] },
+        enableMetadata: true,
+        // Allow credentials as short as 15 minutes (Better Auth default
+        // minimum is 1 day — too long for per-shift keys).
+        keyExpiration: { minExpiresIn: 1 / 96 },
+      },
     }),
 
     hooks: () => [
@@ -111,6 +134,14 @@ export function posPlugin(userOptions: POSPluginOptions = {}) {
       const returnService = new ReturnService(db);
       const lookupService = new LookupService(db, ctx.services);
       const receiptService = new ReceiptService(db, ctx.services);
+      const pinService = new PinService(db, options.pinAuth);
+      const exchangeService = new ExchangeService(
+        db,
+        ctx.services,
+        transactionFn as <T>(fn: (tx: typeof db) => Promise<T>) => Promise<T>,
+        transactionService,
+        returnService,
+      );
 
       // Cart service from core (for creating POS transaction carts)
       const cartService = ctx.services.cart as {
@@ -125,6 +156,8 @@ export function posPlugin(userOptions: POSPluginOptions = {}) {
         ...buildReturnRoutes(returnService, transactionService, paymentService, cartService, ctx),
         ...buildLookupRoutes(lookupService, ctx),
         ...buildReceiptRoutes(receiptService, ctx),
+        ...buildPinAuthRoutes(pinService, ctx),
+        ...buildExchangeRoutes(exchangeService, ctx),
       ];
     },
   });

package/src/routes/auth.ts

@@ -0,0 +1,72 @@
+import { router, CommerceValidationError } from "@porulle/core";
+import { z } from "@hono/zod-openapi";
+import { PIN_LOCKOUT_ERROR, type PinService, type PinAuthApi } from "../services/pin-service.js";
+import type { PluginRouteRegistration } from "@porulle/core";
+
+function throwPinRouteError(message: string): never {
+  if (message === PIN_LOCKOUT_ERROR) throw new CommerceValidationError(message);
+  throw new Error(message);
+}
+
+/**
+ * PIN auth runtime (issue #51).
+ *
+ * - PUT /pos/auth/pin        — set/rotate an operator's PIN (pos:admin)
+ * - POST /pos/auth/pin-login — operator PIN → short-lived per-shift API key.
+ *   Authenticated by the terminal's device credential (pos:operate); the
+ *   minted key is personal and carries pos:operate + shift/terminal metadata.
+ * - POST /pos/auth/override  — manager PIN approves one elevated action.
+ */
+export function buildPinAuthRoutes(
+  service: PinService,
+  ctx: { services?: Record<string, unknown>; database?: { db: unknown }; auth?: unknown },
+): PluginRouteRegistration[] {
+  const r = router("POS Auth", "/pos/auth", ctx);
+
+  r.put("/pin")
+    .summary("Set or rotate an operator PIN")
+    .permission("pos:admin")
+    .input(z.object({
+      operatorId: z.string().min(1),
+      pin: z.string().regex(/^\d{4,8}$/, "PIN must be 4-8 digits"),
+      canOverride: z.boolean().optional(),
+    }))
+    .handler(async ({ input, orgId }) => {
+      const body = input as { operatorId: string; pin: string; canOverride?: boolean };
+      const result = await service.setPin(orgId, body);
+      if (!result.ok) throwPinRouteError(result.error);
+      return result.value;
+    });
+
+  r.post("/pin-login")
+    .summary("PIN login — mint a short-lived per-shift credential")
+    .permission("pos:operate")
+    .input(z.object({
+      operatorId: z.string().min(1),
+      pin: z.string().regex(/^\d{4,8}$/),
+      shiftId: z.string().uuid().optional(),
+    }))
+    .handler(async ({ input, orgId }) => {
+      const body = input as { operatorId: string; pin: string; shiftId?: string };
+      const result = await service.pinLogin(orgId, body, ctx.auth as PinAuthApi | undefined);
+      if (!result.ok) throwPinRouteError(result.error);
+      return result.value;
+    });
+
+  r.post("/override")
+    .summary("Manager override — approve one elevated action by PIN")
+    .permission("pos:operate")
+    .input(z.object({
+      operatorId: z.string().min(1),
+      pin: z.string().regex(/^\d{4,8}$/),
+      action: z.string().min(1).max(200),
+    }))
+    .handler(async ({ input, orgId }) => {
+      const body = input as { operatorId: string; pin: string; action: string };
+      const result = await service.override(orgId, body);
+      if (!result.ok) throwPinRouteError(result.error);
+      return result.value;
+    });
+
+  return r.routes();
+}

package/src/routes/exchanges.ts

@@ -0,0 +1,53 @@
+import { router } from "@porulle/core";
+import { z } from "@hono/zod-openapi";
+import type { ExchangeService, ExchangeInput } from "../services/exchange-service.js";
+import type { PluginRouteRegistration } from "@porulle/core";
+
+/**
+ * Exchanges (issue #53): POST /pos/exchanges — return + replacement order +
+ * net delta in one call. Requires pos:manage (like returns) plus core order
+ * scopes on the actor (orders:update for the refund, orders:create for the
+ * replacement) since the exchange moves money on core orders.
+ */
+export function buildExchangeRoutes(
+  service: ExchangeService,
+  ctx: { services?: Record<string, unknown>; database?: { db: unknown } },
+): PluginRouteRegistration[] {
+  const r = router("POS Exchanges", "/pos/exchanges", ctx);
+
+  r.post("/")
+    .summary("Exchange — return lines + replacement order in one atomic operation")
+    .permission("pos:manage")
+    .input(z.object({
+      shiftId: z.string().uuid(),
+      terminalId: z.string().uuid(),
+      originalOrderId: z.string().uuid(),
+      currency: z.string().length(3).optional(),
+      customerId: z.string().uuid().optional(),
+      returnItems: z.array(z.object({
+        originalLineItemId: z.string().uuid(),
+        quantity: z.number().int().positive(),
+        reason: z.enum(["defective", "wrong_item", "changed_mind", "other"]),
+      })).min(1),
+      replacementItems: z.array(z.object({
+        entityId: z.string().uuid(),
+        variantId: z.string().uuid().optional(),
+        sku: z.string().optional(),
+        title: z.string().min(1),
+        quantity: z.number().int().positive(),
+        unitPrice: z.number().int().min(0),
+        taxAmount: z.number().int().min(0).optional(),
+      })).min(1),
+    }))
+    .handler(async ({ input, actor, orgId }) => {
+      const result = await service.exchange(
+        orgId,
+        input as ExchangeInput,
+        actor as { userId: string } & Record<string, unknown>,
+      );
+      if (!result.ok) throw new Error(result.error);
+      return result.value;
+    });
+
+  return r.routes();
+}

package/src/routes/returns.ts

@@ -26,7 +26,8 @@ export function buildReturnRoutes(
         quantity: z.number().int().positive(),
         reason: z.enum(["defective", "wrong_item", "changed_mind", "other"]),
         restockingFee: z.number().int().min(0).optional(),
-        refundAmount: z.number().int().positive(),
+        // refundAmount is NOT accepted from the client — it is computed
+        // server-side from the original order (SEC-08).
       })).min(1),
     }))
     .handler(async ({ input, actor, orgId }) => {
@@ -39,7 +40,6 @@ export function buildReturnRoutes(
           quantity: number;
           reason: "defective" | "wrong_item" | "changed_mind" | "other";
           restockingFee?: number;
-          refundAmount: number;
         }>;
       };
 
@@ -62,18 +62,60 @@ export function buildReturnRoutes(
       });
       if (!txnResult.ok) throw new Error(txnResult.error);
 
-      // Record return items
+      // 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,
+            ): Promise<{
+              ok: boolean;
+              value?: { refund: { amount: number; lines: Array<{ lineItemId: string; quantity: number; amount: number }> } };
+              error?: { message?: string };
+            }>;
+          }
+        | undefined;
+      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);
 
-      // Update transaction totals
-      const refundTotal = body.items.reduce((sum, i) => sum + i.refundAmount, 0);
       await transactionService.updateTotals(txnResult.value.id, {
         subtotal: refundTotal,
         taxTotal: 0,

package/src/schema.ts

@@ -118,6 +118,35 @@ export const posPayments = pgTable("pos_payments", {
   transactionIdx: index("idx_pos_payments_transaction").on(table.transactionId),
 }));
 
+// ─── Operator PINs (issue #51) ──────────────────────────────────────────
+
+export const posOperatorPins = pgTable("pos_operator_pins", {
+  id: uuid("id").defaultRandom().primaryKey(),
+  organizationId: text("organization_id").notNull(),
+  operatorId: text("operator_id").notNull(),
+  // PBKDF2-SHA256, encoded as pbkdf2$<iterations>$<saltB64>$<hashB64>
+  pinHash: text("pin_hash").notNull(),
+  // Manager override capability — checked by POST /pos/auth/override.
+  canOverride: boolean("can_override").notNull().default(false),
+  createdAt: timestamp("created_at", { withTimezone: true }).defaultNow().notNull(),
+  updatedAt: timestamp("updated_at", { withTimezone: true }).defaultNow().notNull(),
+}, (table) => ({
+  orgOperatorUnique: uniqueIndex("pos_operator_pins_org_operator_unique").on(table.organizationId, table.operatorId),
+}));
+
+// ─── PIN attempt lockout (SEC-15) ───────────────────────────────────────
+
+export const posPinAttempts = pgTable("pos_pin_attempts", {
+  id: uuid("id").defaultRandom().primaryKey(),
+  organizationId: text("organization_id").notNull(),
+  operatorId: text("operator_id").notNull(),
+  failedCount: integer("failed_count").notNull().default(0),
+  lockedUntil: timestamp("locked_until", { withTimezone: true }),
+  updatedAt: timestamp("updated_at", { withTimezone: true }).defaultNow().notNull(),
+}, (table) => ({
+  orgOperatorUnique: uniqueIndex("pos_pin_attempts_org_operator_unique").on(table.organizationId, table.operatorId),
+}));
+
 // ─── Return Items ───────────────────────────────────────────────────────
 
 export const posReturnItems = pgTable("pos_return_items", {

package/src/services/exchange-service.ts

@@ -0,0 +1,272 @@
+import { eq } from "@porulle/core/drizzle";
+import { Ok, Err } from "@porulle/core";
+import type { PluginResult } from "@porulle/core";
+import { posTransactions } from "../schema.js";
+import type { Db, Transaction } from "../types.js";
+import type { ReturnService } from "./return-service.js";
+import type { TransactionService } from "./transaction-service.js";
+
+/**
+ * Exchanges (issue #53): return line items + create a replacement order +
+ * settle the difference, in one call.
+ *
+ * The financially-critical half — the line-level refund on the original
+ * order (core issue #52 primitives: refundable-quantity enforcement, daily
+ * cap, audited ledger) and the replacement order creation — runs inside ONE
+ * database transaction, so a failure in either leaves no money moved and no
+ * order created. The POS bookkeeping rows (transaction, return items) are
+ * written after commit and cross-linked for audit.
+ */
+
+export interface ExchangeInput {
+  shiftId: string;
+  terminalId: string;
+  originalOrderId: string;
+  currency?: string | undefined;
+  customerId?: string | undefined;
+  returnItems: Array<{
+    originalLineItemId: string;
+    quantity: number;
+    reason: "defective" | "wrong_item" | "changed_mind" | "other";
+  }>;
+  replacementItems: Array<{
+    entityId: string;
+    variantId?: string | undefined;
+    sku?: string | undefined;
+    title: string;
+    quantity: number;
+    unitPrice: number;
+    taxAmount?: number | undefined;
+  }>;
+}
+
+interface PricingService {
+  resolve(
+    input: {
+      entityId: string;
+      variantId?: string | undefined;
+      currency: string;
+      quantity: number;
+    },
+    actor: unknown,
+    ctx?: unknown,
+  ): Promise<{ ok: boolean; value?: { finalAmount: number }; error?: { message?: string } }>;
+}
+
+interface CoreOrdersService {
+  refundLines(
+    orderId: string,
+    input: { lines: Array<{ lineItemId: string; quantity: number }>; reason?: string },
+    actor: unknown,
+    ctx?: unknown,
+  ): Promise<{ ok: boolean; value?: { refund: { id: string; amount: number; lines: Array<{ lineItemId: string; quantity: number; amount: number }> } }; error?: { message?: string } }>;
+  create(
+    input: Record<string, unknown>,
+    actor: unknown,
+    ctx?: unknown,
+    opts?: { trustedPricing?: boolean; stockPolicy?: "reserve" | "backorder" },
+  ): Promise<{ ok: boolean; value?: { id: string; grandTotal: number }; error?: { message?: string } }>;
+}
+
+export class ExchangeService {
+  constructor(
+    private db: Db,
+    private services: Record<string, unknown>,
+    private transaction: <T>(fn: (tx: Db) => Promise<T>) => Promise<T>,
+    private transactionService: TransactionService,
+    private returnService: ReturnService,
+  ) {}
+
+  async exchange(
+    orgId: string,
+    input: ExchangeInput,
+    actor: { userId: string } & Record<string, unknown>,
+  ): Promise<PluginResult<{
+    transaction: Transaction;
+    refundId: string;
+    returnTotal: number;
+    replacementOrderId: string;
+    replacementTotal: number;
+    netDelta: number;
+  }>> {
+    if (input.returnItems.length === 0) return Err("At least one return item is required");
+    if (input.replacementItems.length === 0) return Err("At least one replacement item is required");
+
+    const orders = this.services.orders as CoreOrdersService;
+    const pricing = this.services.pricing as PricingService;
+    const currency = input.currency ?? "USD";
+
+    // Atomic core half: refund the returned lines + create the replacement.
+    const core = await this.transaction(async (tx) => {
+      const txCtx = { tx, actor };
+
+      const pricedReplacements: Array<ExchangeInput["replacementItems"][number] & { unitPrice: number }> = [];
+      for (const item of input.replacementItems) {
+        const resolved = await pricing.resolve(
+          {
+            entityId: item.entityId,
+            currency,
+            quantity: item.quantity,
+            ...(item.variantId ? { variantId: item.variantId } : {}),
+          },
+          actor,
+          txCtx,
+        );
+        if (!resolved.ok || !resolved.value) {
+          throw new Error(
+            resolved.error?.message ?? `Cannot resolve price for replacement item ${item.entityId}`,
+          );
+        }
+        pricedReplacements.push({ ...item, unitPrice: resolved.value.finalAmount });
+      }
+
+      const subtotal = pricedReplacements.reduce((sum, i) => sum + i.unitPrice * i.quantity, 0);
+      const taxTotal = pricedReplacements.reduce((sum, i) => sum + (i.taxAmount ?? 0), 0);
+      const replacementTotal = subtotal + taxTotal;
+
+      const refund = await orders.refundLines(
+        input.originalOrderId,
+        {
+          lines: input.returnItems.map((item) => ({
+            lineItemId: item.originalLineItemId,
+            quantity: item.quantity,
+          })),
+          reason: "exchange",
+        },
+        actor,
+        txCtx,
+      );
+      if (!refund.ok || !refund.value) {
+        throw new Error(refund.error?.message ?? "Exchange refund failed");
+      }
+
+      const replacement = await orders.create(
+        {
+          currency,
+          subtotal,
+          taxTotal,
+          shippingTotal: 0,
+          grandTotal: replacementTotal,
+          ...(input.customerId ? { customerId: input.customerId } : {}),
+          metadata: {
+            exchange: {
+              originalOrderId: input.originalOrderId,
+              refundId: refund.value.refund.id,
+            },
+          },
+          lineItems: pricedReplacements.map((item) => ({
+            entityId: item.entityId,
+            entityType: "product",
+            ...(item.variantId ? { variantId: item.variantId } : {}),
+            ...(item.sku ? { sku: item.sku } : {}),
+            title: item.title,
+            quantity: item.quantity,
+            unitPrice: item.unitPrice,
+            totalPrice: item.unitPrice * item.quantity,
+            taxAmount: item.taxAmount ?? 0,
+          })),
+        },
+        actor,
+        txCtx,
+        // Prices are server-resolved above (pricing.resolve); reserve stock for
+        // the replacement items so an exchange cannot oversell.
+        { trustedPricing: true, stockPolicy: "reserve" },
+      );
+      if (!replacement.ok || !replacement.value) {
+        throw new Error(replacement.error?.message ?? "Replacement order creation failed");
+      }
+      return {
+        refund: refund.value.refund,
+        replacementOrder: replacement.value,
+        subtotal,
+        taxTotal,
+        replacementTotal,
+      };
+    }).catch((error: unknown) => error as Error);
+
+    if (core instanceof Error) return Err(core.message);
+
+    const returnTotal = core.refund.amount;
+    const netDelta = core.replacementTotal - returnTotal;
+
+    // POS bookkeeping (post-commit): cart + exchange transaction + return rows.
+    const cart = this.services.cart as {
+      create(input: Record<string, unknown>, actor: unknown): Promise<{ ok: boolean; value?: { id: string } }>;
+    };
+    const cartResult = await cart.create(
+      { currency, metadata: { posExchange: true, originalOrderId: input.originalOrderId } },
+      actor,
+    );
+    if (!cartResult.ok || !cartResult.value) return Err("Failed to create cart for exchange");
+
+    const txnResult = await this.transactionService.create(orgId, {
+      shiftId: input.shiftId,
+      terminalId: input.terminalId,
+      operatorId: actor.userId,
+      cartId: cartResult.value.id,
+      type: "exchange",
+      ...(input.customerId ? { customerId: input.customerId } : {}),
+    });
+    if (!txnResult.ok) return Err(txnResult.error);
+    const txn = txnResult.value;
+
+    await this.returnService.addReturnItems(
+      txn.id,
+      input.returnItems.map((item) => ({
+        originalOrderId: input.originalOrderId,
+        originalLineItemId: item.originalLineItemId,
+        quantity: item.quantity,
+        reason: item.reason,
+        refundAmount:
+          core.refund.lines.find((l) => l.lineItemId === item.originalLineItemId)?.amount ?? 0,
+      })),
+    );
+
+    await this.transactionService.updateTotals(txn.id, {
+      subtotal: core.subtotal,
+      taxTotal: core.taxTotal,
+      total: netDelta,
+      discountTotal: 0,
+    });
+    // Cross-link everything on the POS transaction for audit.
+    await this.db
+      .update(posTransactions)
+      .set({
+        orderId: core.replacementOrder.id,
+        metadata: {
+          exchange: {
+            originalOrderId: input.originalOrderId,
+            refundId: core.refund.id,
+            replacementOrderId: core.replacementOrder.id,
+            returnTotal,
+            replacementTotal: core.replacementTotal,
+            netDelta,
+          },
+        },
+        updatedAt: new Date(),
+      })
+      .where(eq(posTransactions.id, txn.id));
+
+    // An even exchange settles itself — nothing to tender.
+    let finalTxn = txn;
+    if (netDelta === 0) {
+      const completed = await this.transactionService.complete(txn.id, core.replacementOrder.id);
+      if (completed.ok) finalTxn = completed.value;
+    } else {
+      const rows = await this.db
+        .select()
+        .from(posTransactions)
+        .where(eq(posTransactions.id, txn.id));
+      if (rows[0]) finalTxn = rows[0] as Transaction;
+    }
+
+    return Ok({
+      transaction: finalTxn,
+      refundId: core.refund.id,
+      returnTotal,
+      replacementOrderId: core.replacementOrder.id,
+      replacementTotal: core.replacementTotal,
+      netDelta,
+    });
+  }
+}