@porulle/plugin-pos 0.7.0 → 0.9.0

package/dist/hooks/checkout-pos.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"checkout-pos.d.ts","sourceRoot":"","sources":["../../src/hooks/checkout-pos.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,aAAa,CAAC;AAEtC,UAAU,YAAY;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC1C,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAaD;;GAEG;AACH,wBAAgB,oBAAoB;;uBAGP,OAAO,EAAE;EAWrC;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,MAAM,EAAE;;uBAG3B,OAAO,EAAE;EAsCrC"}
+{"version":3,"file":"checkout-pos.d.ts","sourceRoot":"","sources":["../../src/hooks/checkout-pos.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,aAAa,CAAC;AAEtC,UAAU,YAAY;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC1C,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAaD;;GAEG;AACH,wBAAgB,oBAAoB;;uBAGP,OAAO,EAAE;EAWrC;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,MAAM,EAAE;;uBAG3B,OAAO,EAAE;EA6CrC"}

package/dist/hooks/checkout-pos.js

@@ -4,7 +4,7 @@
  * checkout.beforePayment: Sets shippingTotal = 0 for POS transactions (no shipping).
  * 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";
 /**
  * Before payment hook: zero out shipping for POS transactions.
@@ -55,6 +55,13 @@ export function buildPOSFinalizationHook(getDb) {
             // Increment shift sales counters
             const posShiftId = metadata?.posShiftId;
             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({
@@ -62,7 +69,7 @@ export function buildPOSFinalizationHook(getDb) {
                     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/dist/index.d.ts

@@ -7,6 +7,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";
 /**
  * POS Plugin — Tier 0 Core Primitives

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAwBA,OAAO,KAAK,EAAE,gBAAgB,EAAM,MAAM,YAAY,CAAC;AAGvD,YAAY,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACnD,OAAO,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AACjE,OAAO,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAC3D,OAAO,EAAE,kBAAkB,EAAE,MAAM,mCAAmC,CAAC;AACvE,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAC/D,OAAO,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAC7D,OAAO,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAC7D,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAC/D,OAAO,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AAE/D;;;;;;;;;;;;;GAaG;AACH,wBAAgB,SAAS,CAAC,WAAW,GAAE,gBAAqB,0CA+E3D"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AA8BA,OAAO,KAAK,EAAE,gBAAgB,EAAM,MAAM,YAAY,CAAC;AAGvD,YAAY,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACnD,OAAO,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AACjE,OAAO,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAC3D,OAAO,EAAE,kBAAkB,EAAE,MAAM,mCAAmC,CAAC;AACvE,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAC/D,OAAO,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAC7D,OAAO,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAC7D,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAC/D,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAC/E,OAAO,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AACjE,OAAO,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AAE/D;;;;;;;;;;;;;GAaG;AACH,wBAAgB,SAAS,CAAC,WAAW,GAAE,gBAAqB,0CAwG3D"}

package/dist/index.js

@@ -1,5 +1,5 @@
 import { defineCommercePlugin } from "@porulle/core";
-import { posTerminals, posShifts, posCashEvents, posTransactions, posPayments, posReturnItems, } from "./schema.js";
+import { posTerminals, posShifts, posCashEvents, posTransactions, posPayments, posReturnItems, posOperatorPins, posPinAttempts, } from "./schema.js";
 import { TerminalService } from "./services/terminal-service.js";
 import { ShiftService } from "./services/shift-service.js";
 import { TransactionService } from "./services/transaction-service.js";
@@ -7,6 +7,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";
@@ -14,6 +16,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 { DEFAULT_POS_OPTIONS } from "./types.js";
 export { TerminalService } from "./services/terminal-service.js";
@@ -23,6 +27,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";
 /**
  * POS Plugin — Tier 0 Core Primitives
@@ -69,6 +75,20 @@ export function posPlugin(userOptions = {}) {
             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: () => [
             buildPOSShippingHook(),
@@ -93,6 +113,8 @@ export function posPlugin(userOptions = {}) {
             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, transactionService, returnService);
             // Cart service from core (for creating POS transaction carts)
             const cartService = ctx.services.cart;
             return [
@@ -103,6 +125,8 @@ export function posPlugin(userOptions = {}) {
                 ...buildReturnRoutes(returnService, transactionService, paymentService, cartService, ctx),
                 ...buildLookupRoutes(lookupService, ctx),
                 ...buildReceiptRoutes(receiptService, ctx),
+                ...buildPinAuthRoutes(pinService, ctx),
+                ...buildExchangeRoutes(exchangeService, ctx),
             ];
         },
     });

package/dist/routes/auth.d.ts

@@ -0,0 +1,19 @@
+import { type PinService } from "../services/pin-service.js";
+import type { PluginRouteRegistration } from "@porulle/core";
+/**
+ * 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 declare function buildPinAuthRoutes(service: PinService, ctx: {
+    services?: Record<string, unknown>;
+    database?: {
+        db: unknown;
+    };
+    auth?: unknown;
+}): PluginRouteRegistration[];
+//# sourceMappingURL=auth.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/routes/auth.ts"],"names":[],"mappings":"AAEA,OAAO,EAAqB,KAAK,UAAU,EAAmB,MAAM,4BAA4B,CAAC;AACjG,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,eAAe,CAAC;AAO7D;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,UAAU,EACnB,GAAG,EAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,QAAQ,CAAC,EAAE;QAAE,EAAE,EAAE,OAAO,CAAA;KAAE,CAAC;IAAC,IAAI,CAAC,EAAE,OAAO,CAAA;CAAE,GACtF,uBAAuB,EAAE,CAiD3B"}

package/dist/routes/auth.js

@@ -0,0 +1,66 @@
+import { router, CommerceValidationError } from "@porulle/core";
+import { z } from "@hono/zod-openapi";
+import { PIN_LOCKOUT_ERROR } from "../services/pin-service.js";
+function throwPinRouteError(message) {
+    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, ctx) {
+    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;
+        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;
+        const result = await service.pinLogin(orgId, body, ctx.auth);
+        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;
+        const result = await service.override(orgId, body);
+        if (!result.ok)
+            throwPinRouteError(result.error);
+        return result.value;
+    });
+    return r.routes();
+}

package/dist/routes/exchanges.d.ts

@@ -0,0 +1,15 @@
+import type { ExchangeService } 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 declare function buildExchangeRoutes(service: ExchangeService, ctx: {
+    services?: Record<string, unknown>;
+    database?: {
+        db: unknown;
+    };
+}): PluginRouteRegistration[];
+//# sourceMappingURL=exchanges.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"exchanges.d.ts","sourceRoot":"","sources":["../../src/routes/exchanges.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAiB,MAAM,iCAAiC,CAAC;AACtF,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,eAAe,CAAC;AAE7D;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,eAAe,EACxB,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,CAsC3B"}

package/dist/routes/exchanges.js

@@ -0,0 +1,42 @@
+import { router } from "@porulle/core";
+import { z } from "@hono/zod-openapi";
+/**
+ * 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, ctx) {
+    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, actor);
+        if (!result.ok)
+            throw new Error(result.error);
+        return result.value;
+    });
+    return r.routes();
+}

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,CAsG3B"}
+{"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"}

package/dist/routes/returns.js

@@ -14,7 +14,8 @@ export function buildReturnRoutes(returnService, transactionService, paymentServ
             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 }) => {
@@ -34,15 +35,35 @@ export function buildReturnRoutes(returnService, transactionService, paymentServ
         });
         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;
+        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/dist/schema.d.ts

@@ -1174,6 +1174,241 @@ export declare const posPayments: import("drizzle-orm/pg-core/table").PgTableWit
     };
     dialect: "pg";
 }>;
+export declare const posOperatorPins: import("drizzle-orm/pg-core/table").PgTableWithColumns<{
+    name: "pos_operator_pins";
+    schema: undefined;
+    columns: {
+        id: import("@porulle/core/drizzle").PgColumn<{
+            name: "id";
+            tableName: "pos_operator_pins";
+            dataType: "string";
+            columnType: "PgUUID";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: true;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        organizationId: import("@porulle/core/drizzle").PgColumn<{
+            name: "organization_id";
+            tableName: "pos_operator_pins";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        operatorId: import("@porulle/core/drizzle").PgColumn<{
+            name: "operator_id";
+            tableName: "pos_operator_pins";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        pinHash: import("@porulle/core/drizzle").PgColumn<{
+            name: "pin_hash";
+            tableName: "pos_operator_pins";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        canOverride: import("@porulle/core/drizzle").PgColumn<{
+            name: "can_override";
+            tableName: "pos_operator_pins";
+            dataType: "boolean";
+            columnType: "PgBoolean";
+            data: boolean;
+            driverParam: boolean;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        createdAt: import("@porulle/core/drizzle").PgColumn<{
+            name: "created_at";
+            tableName: "pos_operator_pins";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        updatedAt: import("@porulle/core/drizzle").PgColumn<{
+            name: "updated_at";
+            tableName: "pos_operator_pins";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+    };
+    dialect: "pg";
+}>;
+export declare const posPinAttempts: import("drizzle-orm/pg-core/table").PgTableWithColumns<{
+    name: "pos_pin_attempts";
+    schema: undefined;
+    columns: {
+        id: import("@porulle/core/drizzle").PgColumn<{
+            name: "id";
+            tableName: "pos_pin_attempts";
+            dataType: "string";
+            columnType: "PgUUID";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: true;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        organizationId: import("@porulle/core/drizzle").PgColumn<{
+            name: "organization_id";
+            tableName: "pos_pin_attempts";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        operatorId: import("@porulle/core/drizzle").PgColumn<{
+            name: "operator_id";
+            tableName: "pos_pin_attempts";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        failedCount: import("@porulle/core/drizzle").PgColumn<{
+            name: "failed_count";
+            tableName: "pos_pin_attempts";
+            dataType: "number";
+            columnType: "PgInteger";
+            data: number;
+            driverParam: string | number;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        lockedUntil: import("@porulle/core/drizzle").PgColumn<{
+            name: "locked_until";
+            tableName: "pos_pin_attempts";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        updatedAt: import("@porulle/core/drizzle").PgColumn<{
+            name: "updated_at";
+            tableName: "pos_pin_attempts";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+    };
+    dialect: "pg";
+}>;
 export declare const posReturnItems: import("drizzle-orm/pg-core/table").PgTableWithColumns<{
     name: "pos_return_items";
     schema: undefined;

package/dist/schema.d.ts.map

@@ -1 +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"}
+{"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,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAYzB,CAAC;AAIJ,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EASxB,CAAC;AAIJ,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAaxB,CAAC"}

package/dist/schema.js

@@ -106,6 +106,31 @@ export const posPayments = pgTable("pos_payments", {
 }, (table) => ({
     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", {
     id: uuid("id").defaultRandom().primaryKey(),