@porulle/plugin-pos 0.7.0 → 0.8.0

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":"AA6BA,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,0CAsG3D"}

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, } 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,18 @@ export function posPlugin(userOptions = {}) {
             posTransactions,
             posPayments,
             posReturnItems,
+            posOperatorPins,
+        }),
+        // 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"] },
+                // 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 +111,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 +123,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,KAAK,EAAE,UAAU,EAAc,MAAM,4BAA4B,CAAC;AACzE,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,eAAe,CAAC;AAE7D;;;;;;;;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,60 @@
+import { router } from "@porulle/core";
+import { z } from "@hono/zod-openapi";
+/**
+ * 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)
+            throw new Error(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)
+            throw new Error(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)
+            throw new Error(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/schema.d.ts

@@ -1174,6 +1174,132 @@ 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 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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAaxB,CAAC"}

package/dist/schema.js

@@ -106,6 +106,20 @@ 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),
+}));
 // ─── Return Items ───────────────────────────────────────────────────────
 export const posReturnItems = pgTable("pos_return_items", {
     id: uuid("id").defaultRandom().primaryKey(),

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

@@ -0,0 +1,55 @@
+import type { PluginResult } from "@porulle/core";
+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;
+    }>;
+}
+export declare class ExchangeService {
+    private db;
+    private services;
+    private transaction;
+    private transactionService;
+    private returnService;
+    constructor(db: Db, services: Record<string, unknown>, transaction: <T>(fn: (tx: Db) => Promise<T>) => Promise<T>, transactionService: TransactionService, returnService: ReturnService);
+    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;
+    }>>;
+}
+//# sourceMappingURL=exchange-service.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"exchange-service.d.ts","sourceRoot":"","sources":["../../src/services/exchange-service.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAElD,OAAO,KAAK,EAAE,EAAE,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAEnE;;;;;;;;;;GAUG;AAEH,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,WAAW,EAAE,KAAK,CAAC;QACjB,kBAAkB,EAAE,MAAM,CAAC;QAC3B,QAAQ,EAAE,MAAM,CAAC;QACjB,MAAM,EAAE,WAAW,GAAG,YAAY,GAAG,cAAc,GAAG,OAAO,CAAC;KAC/D,CAAC,CAAC;IACH,gBAAgB,EAAE,KAAK,CAAC;QACtB,QAAQ,EAAE,MAAM,CAAC;QACjB,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;QAC/B,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;QACzB,KAAK,EAAE,MAAM,CAAC;QACd,QAAQ,EAAE,MAAM,CAAC;QACjB,SAAS,EAAE,MAAM,CAAC;QAClB,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;KAChC,CAAC,CAAC;CACJ;AAgBD,qBAAa,eAAe;IAExB,OAAO,CAAC,EAAE;IACV,OAAO,CAAC,QAAQ;IAChB,OAAO,CAAC,WAAW;IACnB,OAAO,CAAC,kBAAkB;IAC1B,OAAO,CAAC,aAAa;gBAJb,EAAE,EAAE,EAAE,EACN,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjC,WAAW,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,KAAK,OAAO,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,EAC1D,kBAAkB,EAAE,kBAAkB,EACtC,aAAa,EAAE,aAAa;IAGhC,QAAQ,CACZ,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,aAAa,EACpB,KAAK,EAAE;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAClD,OAAO,CAAC,YAAY,CAAC;QACtB,WAAW,EAAE,WAAW,CAAC;QACzB,QAAQ,EAAE,MAAM,CAAC;QACjB,WAAW,EAAE,MAAM,CAAC;QACpB,kBAAkB,EAAE,MAAM,CAAC;QAC3B,gBAAgB,EAAE,MAAM,CAAC;QACzB,QAAQ,EAAE,MAAM,CAAC;KAClB,CAAC,CAAC;CAsJJ"}

package/dist/services/exchange-service.js

@@ -0,0 +1,145 @@
+import { eq } from "@porulle/core/drizzle";
+import { Ok, Err } from "@porulle/core";
+import { posTransactions } from "../schema.js";
+export class ExchangeService {
+    db;
+    services;
+    transaction;
+    transactionService;
+    returnService;
+    constructor(db, services, transaction, transactionService, returnService) {
+        this.db = db;
+        this.services = services;
+        this.transaction = transaction;
+        this.transactionService = transactionService;
+        this.returnService = returnService;
+    }
+    async exchange(orgId, input, actor) {
+        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;
+        const currency = input.currency ?? "USD";
+        const subtotal = input.replacementItems.reduce((sum, i) => sum + i.unitPrice * i.quantity, 0);
+        const taxTotal = input.replacementItems.reduce((sum, i) => sum + (i.taxAmount ?? 0), 0);
+        const replacementTotal = subtotal + taxTotal;
+        // Atomic core half: refund the returned lines + create the replacement.
+        const core = await this.transaction(async (tx) => {
+            const txCtx = { tx, actor };
+            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: input.replacementItems.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);
+            if (!replacement.ok || !replacement.value) {
+                throw new Error(replacement.error?.message ?? "Replacement order creation failed");
+            }
+            return { refund: refund.value.refund, replacementOrder: replacement.value };
+        }).catch((error) => error);
+        if (core instanceof Error)
+            return Err(core.message);
+        const returnTotal = core.refund.amount;
+        const netDelta = replacementTotal - returnTotal;
+        // POS bookkeeping (post-commit): cart + exchange transaction + return rows.
+        const cart = this.services.cart;
+        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,
+            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,
+                    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];
+        }
+        return Ok({
+            transaction: finalTxn,
+            refundId: core.refund.id,
+            returnTotal,
+            replacementOrderId: core.replacementOrder.id,
+            replacementTotal,
+            netDelta,
+        });
+    }
+}