@porulle/plugin-pos 0.7.0 → 0.8.0

package/src/services/exchange-service.ts

@@ -0,0 +1,227 @@
+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 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,
+  ): 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 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: unknown) => error as 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 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,
+      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] as Transaction;
+    }
+
+    return Ok({
+      transaction: finalTxn,
+      refundId: core.refund.id,
+      returnTotal,
+      replacementOrderId: core.replacementOrder.id,
+      replacementTotal,
+      netDelta,
+    });
+  }
+}

package/src/services/pin-service.ts

@@ -0,0 +1,228 @@
+import { eq, and } from "@porulle/core/drizzle";
+import { Ok, Err } from "@porulle/core";
+import type { PluginResult } from "@porulle/core";
+import { posOperatorPins, posShifts } from "../schema.js";
+import type { Db, OperatorPin, Shift } from "../types.js";
+
+/**
+ * PIN auth runtime (issue #51).
+ *
+ * PINs hash with PBKDF2-SHA256 via Web Crypto (Workers-safe, no Node-only
+ * APIs). PIN login verifies the operator's PIN against their open shift and
+ * mints a short-lived Better Auth API key scoped to POS operation — the
+ * per-shift credential POS apps previously hand-rolled through module-global
+ * auth holders. Manager override verifies a PIN whose record carries
+ * `canOverride` and returns an audited approval.
+ */
+
+const PBKDF2_ITERATIONS = 100_000;
+
+/** Narrow Better Auth surface the PIN runtime uses. */
+export interface PinAuthApi {
+  api: {
+    createApiKey(input: { body: Record<string, unknown> }): Promise<unknown>;
+  };
+}
+
+function toBase64(bytes: Uint8Array): string {
+  let binary = "";
+  for (const b of bytes) binary += String.fromCharCode(b);
+  return btoa(binary);
+}
+
+function fromBase64(value: string): Uint8Array {
+  const binary = atob(value);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+  return bytes;
+}
+
+async function deriveHash(pin: string, salt: Uint8Array, iterations: number): Promise<Uint8Array> {
+  const keyMaterial = await crypto.subtle.importKey(
+    "raw",
+    new TextEncoder().encode(pin),
+    "PBKDF2",
+    false,
+    ["deriveBits"],
+  );
+  const bits = await crypto.subtle.deriveBits(
+    { name: "PBKDF2", hash: "SHA-256", salt: salt.slice().buffer as ArrayBuffer, iterations },
+    keyMaterial,
+    256,
+  );
+  return new Uint8Array(bits);
+}
+
+export async function hashPin(pin: string): Promise<string> {
+  const salt = crypto.getRandomValues(new Uint8Array(16));
+  const hash = await deriveHash(pin, salt, PBKDF2_ITERATIONS);
+  return `pbkdf2$${PBKDF2_ITERATIONS}$${toBase64(salt)}$${toBase64(hash)}`;
+}
+
+export async function verifyPinHash(pin: string, encoded: string): Promise<boolean> {
+  const [scheme, iterationsRaw, saltB64, hashB64] = encoded.split("$");
+  if (scheme !== "pbkdf2" || !iterationsRaw || !saltB64 || !hashB64) return false;
+  const expected = fromBase64(hashB64);
+  const actual = await deriveHash(pin, fromBase64(saltB64), Number(iterationsRaw));
+  if (actual.length !== expected.length) return false;
+  let diff = 0;
+  for (let i = 0; i < actual.length; i++) diff |= actual[i]! ^ expected[i]!;
+  return diff === 0;
+}
+
+export class PinService {
+  constructor(
+    private db: Db,
+    private options: {
+      /** Named auth.apiKeyScopes config used to mint shift keys (optional). */
+      apiKeyScope?: string | undefined;
+      /** Shift-credential lifetime in seconds. Default: 12h. */
+      credentialTtlSeconds?: number | undefined;
+    } = {},
+  ) {}
+
+  async setPin(
+    orgId: string,
+    input: { operatorId: string; pin: string; canOverride?: boolean | undefined },
+  ): Promise<PluginResult<{ operatorId: string; canOverride: boolean }>> {
+    if (!/^\d{4,8}$/.test(input.pin)) {
+      return Err("PIN must be 4-8 digits");
+    }
+    const pinHash = await hashPin(input.pin);
+    const existing = await this.db
+      .select()
+      .from(posOperatorPins)
+      .where(and(
+        eq(posOperatorPins.organizationId, orgId),
+        eq(posOperatorPins.operatorId, input.operatorId),
+      ));
+    if (existing.length > 0) {
+      await this.db
+        .update(posOperatorPins)
+        .set({
+          pinHash,
+          canOverride: input.canOverride ?? (existing[0] as OperatorPin).canOverride,
+          updatedAt: new Date(),
+        })
+        .where(eq(posOperatorPins.id, (existing[0] as OperatorPin).id));
+    } else {
+      await this.db.insert(posOperatorPins).values({
+        organizationId: orgId,
+        operatorId: input.operatorId,
+        pinHash,
+        canOverride: input.canOverride ?? false,
+      });
+    }
+    return Ok({ operatorId: input.operatorId, canOverride: input.canOverride ?? false });
+  }
+
+  private async verifyOperatorPin(
+    orgId: string,
+    operatorId: string,
+    pin: string,
+  ): Promise<OperatorPin | null> {
+    const rows = await this.db
+      .select()
+      .from(posOperatorPins)
+      .where(and(
+        eq(posOperatorPins.organizationId, orgId),
+        eq(posOperatorPins.operatorId, operatorId),
+      ));
+    const record = rows[0] as OperatorPin | undefined;
+    if (!record) return null;
+    return (await verifyPinHash(pin, record.pinHash)) ? record : null;
+  }
+
+  /**
+   * PIN login: verifies the PIN, resolves the operator's open shift, and
+   * mints a short-lived API key bound to it. The terminal's device key
+   * authenticates this call (pos:operate); the returned key is personal.
+   */
+  async pinLogin(
+    orgId: string,
+    input: { operatorId: string; pin: string; shiftId?: string | undefined },
+    auth: PinAuthApi | undefined,
+  ): Promise<PluginResult<{
+    operatorId: string;
+    shiftId: string;
+    terminalId: string;
+    apiKey: string;
+    expiresAt: string;
+  }>> {
+    const record = await this.verifyOperatorPin(orgId, input.operatorId, input.pin);
+    if (!record) return Err("Invalid operator or PIN");
+
+    const conditions = [
+      eq(posShifts.organizationId, orgId),
+      eq(posShifts.operatorId, input.operatorId),
+      eq(posShifts.status, "open"),
+    ];
+    if (input.shiftId) conditions.push(eq(posShifts.id, input.shiftId));
+    const shifts = await this.db.select().from(posShifts).where(and(...conditions));
+    const shift = shifts[0] as Shift | undefined;
+    if (!shift) return Err("No open shift for this operator — open a shift first");
+
+    if (!auth) {
+      return Err("PIN login requires the Better Auth instance (plugin ctx.auth) — are routes mounted by createServer?");
+    }
+
+    const ttlSeconds = this.options.credentialTtlSeconds ?? 12 * 3600;
+    const created = (await auth.api.createApiKey({
+      body: {
+        // Better Auth caps name length at 32; the full shift id lives on the
+        // shift row (metadata.pinLoginApiKeyId links back).
+        name: `pos-shift-${shift.id.slice(0, 8)}`,
+        userId: input.operatorId,
+        expiresIn: ttlSeconds,
+        permissions: { pos: ["operate"] },
+        // Shift/terminal binding is recorded on the shift row (metadata is
+        // disabled by default in Better Auth's apiKey plugin); the key name
+        // carries the shift id for traceability.
+        // The plugin registers this scope via its apiKeyScopes manifest.
+        configId: this.options.apiKeyScope ?? "pos",
+      },
+    })) as { key?: string; id?: string };
+    if (!created?.key) return Err("Failed to mint shift credential");
+
+    // Record the credential on the shift so admins can trace/revoke it.
+    await this.db
+      .update(posShifts)
+      .set({
+        metadata: { ...(shift.metadata ?? {}), pinLoginApiKeyId: created.id ?? null },
+        updatedAt: new Date(),
+      })
+      .where(eq(posShifts.id, shift.id));
+
+    return Ok({
+      operatorId: input.operatorId,
+      shiftId: shift.id,
+      terminalId: shift.terminalId,
+      apiKey: created.key,
+      expiresAt: new Date(Date.now() + ttlSeconds * 1000).toISOString(),
+    });
+  }
+
+  /**
+   * Manager override: verifies the manager's PIN (record must carry
+   * canOverride) and returns an approval envelope for the requested action.
+   */
+  async override(
+    orgId: string,
+    input: { operatorId: string; pin: string; action: string },
+  ): Promise<PluginResult<{
+    approved: true;
+    operatorId: string;
+    action: string;
+    approvedAt: string;
+  }>> {
+    const record = await this.verifyOperatorPin(orgId, input.operatorId, input.pin);
+    if (!record) return Err("Invalid operator or PIN");
+    if (!record.canOverride) return Err("This operator cannot approve overrides");
+    return Ok({
+      approved: true,
+      operatorId: input.operatorId,
+      action: input.action,
+      approvedAt: new Date().toISOString(),
+    });
+  }
+}

package/src/types.ts

@@ -6,6 +6,7 @@ import type {
   posTransactions,
   posPayments,
   posReturnItems,
+  posOperatorPins,
 } from "./schema.js";
 
 export type Terminal = typeof posTerminals.$inferSelect;
@@ -26,6 +27,9 @@ export type PaymentInsert = typeof posPayments.$inferInsert;
 export type ReturnItem = typeof posReturnItems.$inferSelect;
 export type ReturnItemInsert = typeof posReturnItems.$inferInsert;
 
+export type OperatorPin = typeof posOperatorPins.$inferSelect;
+export type OperatorPinInsert = typeof posOperatorPins.$inferInsert;
+
 export type TransactionStatus = "open" | "held" | "completed" | "voided";
 export type TransactionType = "sale" | "return" | "exchange";
 export type PaymentMethod = "cash" | "card" | "gift_card" | "store_credit" | "other";
@@ -40,10 +44,18 @@ export interface POSPluginOptions {
   maxHoldHours?: number;
   /** Require manager override for discounts above this percentage. Default: 20 */
   discountOverrideThreshold?: number;
+  /** PIN auth runtime (issue #51). */
+  pinAuth?: {
+    /** Named auth.apiKeyScopes config used to mint per-shift keys. */
+    apiKeyScope?: string;
+    /** Shift-credential lifetime in seconds. Default: 43200 (12h). */
+    credentialTtlSeconds?: number;
+  };
 }
 
 export const DEFAULT_POS_OPTIONS: Required<POSPluginOptions> = {
   defaultCurrency: "USD",
   maxHoldHours: 24,
   discountOverrideThreshold: 20,
+  pinAuth: {},
 };