@porulle/core 0.7.0 → 0.8.0

package/dist/modules/orders/repository/index.js

@@ -1,5 +1,5 @@
 import { eq, and, or, gte, lte, desc, sql } from "drizzle-orm";
-import { orders, orderLineItems, orderStatusHistory } from "../schema.js";
+import { orders, orderLineItems, orderNotes, orderRefunds, orderStatusHistory } from "../schema.js";
 import { customers } from "../../customers/schema.js";
 /**
  * OrdersRepository provides type-safe database operations for orders.
@@ -106,6 +106,14 @@ export class OrdersRepository {
         }
         return query;
     }
+    async findByIdempotencyKey(orgId, idempotencyKey, ctx) {
+        const db = this.getDb(ctx);
+        const rows = await db
+            .select()
+            .from(orders)
+            .where(and(eq(orders.organizationId, orgId), eq(orders.idempotencyKey, idempotencyKey)));
+        return rows[0];
+    }
     async create(data, ctx) {
         const db = this.getDb(ctx);
         const rows = await db.insert(orders).values(data).returning();
@@ -223,6 +231,83 @@ export class OrdersRepository {
         return { order, lineItems };
     }
     // ─────────────────────────────────────────────────────────────────────────────
+    // Line-level refunds (issue #52)
+    // ─────────────────────────────────────────────────────────────────────────────
+    async createRefund(data, ctx) {
+        const db = this.getDb(ctx);
+        const rows = await db.insert(orderRefunds).values(data).returning();
+        return rows[0];
+    }
+    async findRefundById(orgId, id, ctx) {
+        const db = this.getDb(ctx);
+        const rows = await db
+            .select()
+            .from(orderRefunds)
+            .where(and(eq(orderRefunds.organizationId, orgId), eq(orderRefunds.id, id)));
+        return rows[0];
+    }
+    async findRefundsByOrderId(orderId, ctx) {
+        const db = this.getDb(ctx);
+        return db
+            .select()
+            .from(orderRefunds)
+            .where(eq(orderRefunds.orderId, orderId))
+            .orderBy(desc(orderRefunds.createdAt));
+    }
+    async markRefundUndone(id, undoneBy, ctx) {
+        const db = this.getDb(ctx);
+        const rows = await db
+            .update(orderRefunds)
+            .set({ status: "undone", undoneAt: new Date(), undoneBy })
+            .where(and(eq(orderRefunds.id, id), eq(orderRefunds.status, "completed")))
+            .returning();
+        return rows[0];
+    }
+    /**
+     * Sum of completed refunds performed by an operator for the local calendar
+     * day in the given timezone — the daily-cap accounting query.
+     */
+    async sumRefundsByOperatorToday(orgId, performedBy, timezone, ctx) {
+        const db = this.getDb(ctx);
+        const result = await db.execute(sql `
+      SELECT COALESCE(sum(amount), 0)::int AS "total"
+      FROM order_refunds
+      WHERE organization_id = ${orgId}
+        AND performed_by = ${performedBy}
+        AND status = 'completed'
+        AND (created_at AT TIME ZONE ${timezone})::date = (now() AT TIME ZONE ${timezone})::date
+    `);
+        const rows = Array.isArray(result)
+            ? result
+            : (result.rows ?? []);
+        const total = rows[0]?.total;
+        return typeof total === "bigint" ? Number(total) : (total ?? 0);
+    }
+    // ─────────────────────────────────────────────────────────────────────────────
+    // Order notes (issue #56)
+    // ─────────────────────────────────────────────────────────────────────────────
+    async createNote(data, ctx) {
+        const db = this.getDb(ctx);
+        const rows = await db.insert(orderNotes).values(data).returning();
+        return rows[0];
+    }
+    async findNotesByOrderId(orderId, ctx) {
+        const db = this.getDb(ctx);
+        return db
+            .select()
+            .from(orderNotes)
+            .where(eq(orderNotes.orderId, orderId))
+            .orderBy(desc(orderNotes.pinned), desc(orderNotes.createdAt));
+    }
+    async deleteNote(orgId, orderId, noteId, ctx) {
+        const db = this.getDb(ctx);
+        const rows = await db
+            .delete(orderNotes)
+            .where(and(eq(orderNotes.id, noteId), eq(orderNotes.orderId, orderId), eq(orderNotes.organizationId, orgId)))
+            .returning();
+        return rows.length > 0;
+    }
+    // ─────────────────────────────────────────────────────────────────────────────
     // Order Number Generation
     // ─────────────────────────────────────────────────────────────────────────────
     async getNextOrderNumber(ctx) {

package/dist/modules/orders/schema.d.ts

@@ -240,6 +240,23 @@ export declare const orders: import("drizzle-orm/pg-core").PgTableWithColumns<{
             identity: undefined;
             generated: undefined;
         }, {}, {}>;
+        idempotencyKey: import("drizzle-orm/pg-core").PgColumn<{
+            name: "idempotency_key";
+            tableName: "orders";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
         metadata: import("drizzle-orm/pg-core").PgColumn<{
             name: "metadata";
             tableName: "orders";
@@ -521,6 +538,23 @@ export declare const orderLineItems: import("drizzle-orm/pg-core").PgTableWithCo
             identity: undefined;
             generated: undefined;
         }, {}, {}>;
+        refundedQuantity: import("drizzle-orm/pg-core").PgColumn<{
+            name: "refunded_quantity";
+            tableName: "order_line_items";
+            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;
+        }, {}, {}>;
         fulfillmentStatus: import("drizzle-orm/pg-core").PgColumn<{
             name: "fulfillment_status";
             tableName: "order_line_items";
@@ -560,6 +594,346 @@ export declare const orderLineItems: import("drizzle-orm/pg-core").PgTableWithCo
     };
     dialect: "pg";
 }>;
+/**
+ * Line-level refunds (issue #52). One row per refund operation — the ledger
+ * behind the daily refund cap and the undo window. `lines` records which
+ * line items and quantities the refund covered so undo can restore them.
+ */
+export declare const orderRefunds: import("drizzle-orm/pg-core").PgTableWithColumns<{
+    name: "order_refunds";
+    schema: undefined;
+    columns: {
+        id: import("drizzle-orm/pg-core").PgColumn<{
+            name: "id";
+            tableName: "order_refunds";
+            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("drizzle-orm/pg-core").PgColumn<{
+            name: "organization_id";
+            tableName: "order_refunds";
+            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;
+        }, {}, {}>;
+        orderId: import("drizzle-orm/pg-core").PgColumn<{
+            name: "order_id";
+            tableName: "order_refunds";
+            dataType: "string";
+            columnType: "PgUUID";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        amount: import("drizzle-orm/pg-core").PgColumn<{
+            name: "amount";
+            tableName: "order_refunds";
+            dataType: "number";
+            columnType: "PgInteger";
+            data: number;
+            driverParam: string | number;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        reason: import("drizzle-orm/pg-core").PgColumn<{
+            name: "reason";
+            tableName: "order_refunds";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        lines: import("drizzle-orm/pg-core").PgColumn<{
+            name: "lines";
+            tableName: "order_refunds";
+            dataType: "json";
+            columnType: "PgJsonb";
+            data: {
+                lineItemId: string;
+                quantity: number;
+                amount: number;
+            }[];
+            driverParam: unknown;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            $type: {
+                lineItemId: string;
+                quantity: number;
+                amount: number;
+            }[];
+        }>;
+        performedBy: import("drizzle-orm/pg-core").PgColumn<{
+            name: "performed_by";
+            tableName: "order_refunds";
+            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;
+        }, {}, {}>;
+        status: import("drizzle-orm/pg-core").PgColumn<{
+            name: "status";
+            tableName: "order_refunds";
+            dataType: "string";
+            columnType: "PgText";
+            data: "completed" | "undone";
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: ["completed", "undone"];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        undoneAt: import("drizzle-orm/pg-core").PgColumn<{
+            name: "undone_at";
+            tableName: "order_refunds";
+            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;
+        }, {}, {}>;
+        undoneBy: import("drizzle-orm/pg-core").PgColumn<{
+            name: "undone_by";
+            tableName: "order_refunds";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        createdAt: import("drizzle-orm/pg-core").PgColumn<{
+            name: "created_at";
+            tableName: "order_refunds";
+            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";
+}>;
+/**
+ * Operator annotations on orders (issue #56) — "customer will pick up
+ * Thursday". Merged into GET /orders/{id}/timeline alongside status history
+ * and refund ledger events.
+ */
+export declare const orderNotes: import("drizzle-orm/pg-core").PgTableWithColumns<{
+    name: "order_notes";
+    schema: undefined;
+    columns: {
+        id: import("drizzle-orm/pg-core").PgColumn<{
+            name: "id";
+            tableName: "order_notes";
+            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("drizzle-orm/pg-core").PgColumn<{
+            name: "organization_id";
+            tableName: "order_notes";
+            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;
+        }, {}, {}>;
+        orderId: import("drizzle-orm/pg-core").PgColumn<{
+            name: "order_id";
+            tableName: "order_notes";
+            dataType: "string";
+            columnType: "PgUUID";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        author: import("drizzle-orm/pg-core").PgColumn<{
+            name: "author";
+            tableName: "order_notes";
+            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;
+        }, {}, {}>;
+        body: import("drizzle-orm/pg-core").PgColumn<{
+            name: "body";
+            tableName: "order_notes";
+            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;
+        }, {}, {}>;
+        pinned: import("drizzle-orm/pg-core").PgColumn<{
+            name: "pinned";
+            tableName: "order_notes";
+            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("drizzle-orm/pg-core").PgColumn<{
+            name: "created_at";
+            tableName: "order_notes";
+            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 orderStatusHistory: import("drizzle-orm/pg-core").PgTableWithColumns<{
     name: "order_status_history";
     schema: undefined;

package/dist/modules/orders/schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../src/modules/orders/schema.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA0BhB,CAAC;AAEJ,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAoBzB,CAAC;AAEH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAY7B,CAAC"}
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../src/modules/orders/schema.ts"],"names":[],"mappings":"AAKA,eAAO,MAAM,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAgChB,CAAC;AAEJ,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAuBzB,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;4BAQyB,MAAM;0BAAY,MAAM;wBAAU,MAAM;;;;;;;;;;;;;;4BAAxC,MAAM;0BAAY,MAAM;wBAAU,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EASxF,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAYrB,CAAC;AAEH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAY7B,CAAC"}

package/dist/modules/orders/schema.js

@@ -1,4 +1,5 @@
-import { index, integer, jsonb, pgTable, text, timestamp, uniqueIndex, uuid } from "drizzle-orm/pg-core";
+import { sql } from "drizzle-orm";
+import { boolean, index, integer, jsonb, pgTable, text, timestamp, uniqueIndex, uuid } from "drizzle-orm/pg-core";
 import { organization } from "../../auth/auth-schema.js";
 import { sellableEntities, variants } from "../catalog/schema.js";
 export const orders = pgTable("orders", {
@@ -16,6 +17,9 @@ export const orders = pgTable("orders", {
     amountCaptured: integer("amount_captured"),
     paymentIntentId: text("payment_intent_id"),
     paymentMethodId: text("payment_method_id"),
+    // Client-supplied key making order creation safely retryable (offline POS
+    // queues, network retries) — replays return the original order.
+    idempotencyKey: text("idempotency_key"),
     metadata: jsonb("metadata").$type().default({}),
     placedAt: timestamp("placed_at", { withTimezone: true }).defaultNow().notNull(),
     fulfilledAt: timestamp("fulfilled_at", { withTimezone: true }),
@@ -27,6 +31,9 @@ export const orders = pgTable("orders", {
     customerIdIdx: index("idx_orders_customer_id").on(table.customerId),
     placedAtIdx: index("idx_orders_placed_at").on(table.placedAt),
     paymentIntentIdx: index("idx_orders_payment_intent").on(table.paymentIntentId),
+    orgIdempotencyKeyUnique: uniqueIndex("orders_org_idempotency_key_unique")
+        .on(table.organizationId, table.idempotencyKey)
+        .where(sql `idempotency_key IS NOT NULL`),
 }));
 export const orderLineItems = pgTable("order_line_items", {
     id: uuid("id").defaultRandom().primaryKey(),
@@ -43,12 +50,56 @@ export const orderLineItems = pgTable("order_line_items", {
     totalPrice: integer("total_price").notNull(),
     taxAmount: integer("tax_amount").notNull().default(0),
     discountAmount: integer("discount_amount").notNull().default(0),
+    // Units already refunded on this line (issue #52) — line-level refund REST
+    // rejects refunds beyond `quantity - refundedQuantity`.
+    refundedQuantity: integer("refunded_quantity").notNull().default(0),
     fulfillmentStatus: text("fulfillment_status").notNull().default("unfulfilled"),
     metadata: jsonb("metadata").$type().default({}),
 }, (table) => [
     index("idx_order_line_items_order_id").on(table.orderId),
     index("idx_order_line_items_entity_id").on(table.entityId),
 ]);
+/**
+ * Line-level refunds (issue #52). One row per refund operation — the ledger
+ * behind the daily refund cap and the undo window. `lines` records which
+ * line items and quantities the refund covered so undo can restore them.
+ */
+export const orderRefunds = pgTable("order_refunds", {
+    id: uuid("id").defaultRandom().primaryKey(),
+    organizationId: text("organization_id").notNull().references(() => organization.id, { onDelete: "cascade" }),
+    orderId: uuid("order_id")
+        .references(() => orders.id, { onDelete: "cascade" })
+        .notNull(),
+    amount: integer("amount").notNull(),
+    reason: text("reason"),
+    lines: jsonb("lines").$type().notNull(),
+    performedBy: text("performed_by").notNull(),
+    status: text("status", { enum: ["completed", "undone"] }).notNull().default("completed"),
+    undoneAt: timestamp("undone_at", { withTimezone: true }),
+    undoneBy: text("undone_by"),
+    createdAt: timestamp("created_at", { withTimezone: true }).defaultNow().notNull(),
+}, (table) => [
+    index("idx_order_refunds_order_id").on(table.orderId),
+    index("idx_order_refunds_org_performed_by").on(table.organizationId, table.performedBy, table.createdAt),
+]);
+/**
+ * Operator annotations on orders (issue #56) — "customer will pick up
+ * Thursday". Merged into GET /orders/{id}/timeline alongside status history
+ * and refund ledger events.
+ */
+export const orderNotes = pgTable("order_notes", {
+    id: uuid("id").defaultRandom().primaryKey(),
+    organizationId: text("organization_id").notNull().references(() => organization.id, { onDelete: "cascade" }),
+    orderId: uuid("order_id")
+        .references(() => orders.id, { onDelete: "cascade" })
+        .notNull(),
+    author: text("author").notNull(),
+    body: text("body").notNull(),
+    pinned: boolean("pinned").notNull().default(false),
+    createdAt: timestamp("created_at", { withTimezone: true }).defaultNow().notNull(),
+}, (table) => [
+    index("idx_order_notes_order_id").on(table.orderId),
+]);
 export const orderStatusHistory = pgTable("order_status_history", {
     id: uuid("id").defaultRandom().primaryKey(),
     orderId: uuid("order_id")