@porulle/core 0.7.0 → 0.8.0

package/src/modules/documents/repository/index.ts

@@ -0,0 +1,68 @@
+import { and, eq, sql } from "drizzle-orm";
+import type { TxContext } from "../../../kernel/database/tx-context.js";
+import type {
+  DrizzleDatabase,
+  DbOrTx,
+} from "../../../kernel/database/drizzle-db.js";
+import { invoiceSequences, orderDocuments } from "../schema.js";
+
+export type OrderDocument = typeof orderDocuments.$inferSelect;
+
+/**
+ * Persistence for fiscal sequences and issued documents (issue #47).
+ */
+export class DocumentsRepository {
+  constructor(private readonly db: DrizzleDatabase) {}
+
+  private getDb(ctx?: TxContext): DbOrTx {
+    return (ctx?.tx as DbOrTx | undefined) ?? this.db;
+  }
+
+  /**
+   * Atomically allocates the next sequence value for (org, series).
+   * Single upsert-returning statement — safe under concurrency.
+   */
+  async allocate(orgId: string, series: string, ctx?: TxContext): Promise<number> {
+    const db = this.getDb(ctx);
+    const rows = await db
+      .insert(invoiceSequences)
+      .values({ organizationId: orgId, series, nextValue: 2 })
+      .onConflictDoUpdate({
+        target: [invoiceSequences.organizationId, invoiceSequences.series],
+        set: {
+          nextValue: sql`${invoiceSequences.nextValue} + 1`,
+          updatedAt: new Date(),
+        },
+      })
+      .returning({ nextValue: invoiceSequences.nextValue });
+    // nextValue is post-increment; the allocated number is one less.
+    return rows[0]!.nextValue - 1;
+  }
+
+  async findDocument(
+    orgId: string,
+    orderId: string,
+    type: string,
+    ctx?: TxContext,
+  ): Promise<OrderDocument | undefined> {
+    const db = this.getDb(ctx);
+    const rows = await db
+      .select()
+      .from(orderDocuments)
+      .where(and(
+        eq(orderDocuments.organizationId, orgId),
+        eq(orderDocuments.orderId, orderId),
+        eq(orderDocuments.type, type),
+      ));
+    return rows[0];
+  }
+
+  async createDocument(
+    data: { organizationId: string; orderId: string; type: string; documentNumber: string },
+    ctx?: TxContext,
+  ): Promise<OrderDocument> {
+    const db = this.getDb(ctx);
+    const rows = await db.insert(orderDocuments).values(data).returning();
+    return rows[0]!;
+  }
+}

package/src/modules/documents/schema.ts

@@ -0,0 +1,44 @@
+import { index, integer, pgTable, text, timestamp, uniqueIndex, uuid } from "drizzle-orm/pg-core";
+import { organization } from "../../auth/auth-schema.js";
+import { orders } from "../orders/schema.js";
+
+/**
+ * Fiscal document sequences (issue #47).
+ *
+ * Per-(org, series) counters for legally sequential invoice numbers.
+ * Allocation is a single atomic upsert-returning statement, so concurrent
+ * requests never observe the same value.
+ */
+export const invoiceSequences = pgTable("invoice_sequences", {
+  id: uuid("id").defaultRandom().primaryKey(),
+  organizationId: text("organization_id")
+    .notNull()
+    .references(() => organization.id, { onDelete: "cascade" }),
+  series: text("series").notNull().default("default"),
+  // The NEXT value to hand out; allocation returns the pre-increment value.
+  nextValue: integer("next_value").notNull().default(1),
+  updatedAt: timestamp("updated_at", { withTimezone: true }).defaultNow().notNull(),
+}, (table) => ({
+  orgSeriesUnique: uniqueIndex("invoice_sequences_org_series_unique").on(table.organizationId, table.series),
+}));
+
+/**
+ * Issued documents (issue #47). One row per (org, order, type) — re-rendering
+ * an order's invoice returns the number issued the first time, so a fiscal
+ * number never changes once handed out.
+ */
+export const orderDocuments = pgTable("order_documents", {
+  id: uuid("id").defaultRandom().primaryKey(),
+  organizationId: text("organization_id")
+    .notNull()
+    .references(() => organization.id, { onDelete: "cascade" }),
+  orderId: uuid("order_id")
+    .notNull()
+    .references(() => orders.id, { onDelete: "cascade" }),
+  type: text("type").notNull(), // "invoice" | "receipt"
+  documentNumber: text("document_number").notNull(),
+  createdAt: timestamp("created_at", { withTimezone: true }).defaultNow().notNull(),
+}, (table) => ({
+  orgOrderTypeUnique: uniqueIndex("order_documents_org_order_type_unique").on(table.organizationId, table.orderId, table.type),
+  orgIdx: index("idx_order_documents_org").on(table.organizationId),
+}));

package/src/modules/documents/service.ts

@@ -0,0 +1,176 @@
+import { resolveOrgId } from "../../auth/org.js";
+import type { Actor } from "../../auth/types.js";
+import type { TxContext } from "../../kernel/database/tx-context.js";
+import { CommerceValidationError } from "../../kernel/errors.js";
+import { Err, Ok, type Result } from "../../kernel/result.js";
+import type { HydratedOrder, OrderService } from "../orders/service.js";
+import type { SettingsService } from "../settings/service.js";
+import { buildPdf } from "./pdf.js";
+import {
+  invoiceHtml,
+  invoicePdfOps,
+  receiptHtml,
+  type DocumentBranding,
+} from "./render.js";
+import type { DocumentsRepository, OrderDocument } from "./repository/index.js";
+
+interface DocumentsServiceDeps {
+  repository: DocumentsRepository;
+  // The shared kernel service container — orders/settings/email are resolved
+  // at call time (they may instantiate after this module).
+  services: Record<string, unknown>;
+}
+
+interface EmailAdapter {
+  send(input: { template: string; to: string; data?: Record<string, unknown> }): Promise<void>;
+}
+
+const DEFAULT_INVOICE_PREFIX = "INV-";
+
+/**
+ * Order document rendering + fiscal numbering (issue #47).
+ */
+export class DocumentsService {
+  private repository: DocumentsRepository;
+  private services: Record<string, unknown>;
+
+  constructor(deps: DocumentsServiceDeps) {
+    this.repository = deps.repository;
+    this.services = deps.services;
+  }
+
+  private get orders(): OrderService {
+    return this.services.orders as OrderService;
+  }
+
+  private get settings(): SettingsService {
+    return this.services.settings as SettingsService;
+  }
+
+  private async brandingFor(orgId: string, ctx?: TxContext): Promise<DocumentBranding> {
+    return (await this.settings.read(orgId, "branding", ctx)) as DocumentBranding;
+  }
+
+  /**
+   * Issues (or returns the previously issued) fiscal invoice number for an
+   * order. Idempotent per (org, order): once handed out, the number never
+   * changes. Sequence allocation is atomic; a lost creation race falls back
+   * to the winner's document.
+   */
+  async issueInvoiceNumber(
+    order: HydratedOrder,
+    ctx?: TxContext,
+  ): Promise<OrderDocument> {
+    const orgId = order.organizationId;
+    const existing = await this.repository.findDocument(orgId, order.id, "invoice", ctx);
+    if (existing) return existing;
+
+    const documentsSettings = await this.settings.read(orgId, "documents", ctx);
+    const prefix =
+      typeof documentsSettings.invoicePrefix === "string"
+        ? documentsSettings.invoicePrefix
+        : DEFAULT_INVOICE_PREFIX;
+
+    const value = await this.repository.allocate(orgId, "invoice", ctx);
+    const documentNumber = `${prefix}${String(value).padStart(6, "0")}`;
+    try {
+      return await this.repository.createDocument(
+        { organizationId: orgId, orderId: order.id, type: "invoice", documentNumber },
+        ctx,
+      );
+    } catch (error) {
+      // Unique (org, order, type) — a concurrent request won; use its number.
+      const winner = await this.repository.findDocument(orgId, order.id, "invoice", ctx);
+      if (winner) return winner;
+      throw error;
+    }
+  }
+
+  private async loadOrder(
+    orderId: string,
+    actor: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<HydratedOrder>> {
+    return this.orders.getById(orderId, actor, ctx);
+  }
+
+  async renderInvoiceHtml(
+    orderId: string,
+    actor: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<{ html: string; invoiceNumber: string }>> {
+    const order = await this.loadOrder(orderId, actor, ctx);
+    if (!order.ok) return order;
+    const branding = await this.brandingFor(order.value.organizationId, ctx);
+    const doc = await this.issueInvoiceNumber(order.value, ctx);
+    return Ok({
+      html: invoiceHtml({ order: order.value, branding, invoiceNumber: doc.documentNumber }),
+      invoiceNumber: doc.documentNumber,
+    });
+  }
+
+  async renderInvoicePdf(
+    orderId: string,
+    actor: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<{ pdf: Uint8Array; invoiceNumber: string }>> {
+    const order = await this.loadOrder(orderId, actor, ctx);
+    if (!order.ok) return order;
+    const branding = await this.brandingFor(order.value.organizationId, ctx);
+    const doc = await this.issueInvoiceNumber(order.value, ctx);
+    const pages = invoicePdfOps({
+      order: order.value,
+      branding,
+      invoiceNumber: doc.documentNumber,
+    });
+    return Ok({ pdf: buildPdf(pages), invoiceNumber: doc.documentNumber });
+  }
+
+  async renderReceiptHtml(
+    orderId: string,
+    actor: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<{ html: string }>> {
+    const order = await this.loadOrder(orderId, actor, ctx);
+    if (!order.ok) return order;
+    const branding = await this.brandingFor(order.value.organizationId, ctx);
+    return Ok({ html: receiptHtml({ order: order.value, branding }) });
+  }
+
+  /**
+   * Emails the invoice via the configured email adapter. The adapter's
+   * template contract is (template, to, data) — the rendered HTML and the
+   * fiscal number ride in `data` so template-based adapters can use either.
+   */
+  async emailInvoice(
+    orderId: string,
+    to: string,
+    actor: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<{ sent: true; invoiceNumber: string; to: string }>> {
+    const email = this.services.email as EmailAdapter | undefined;
+    if (!email) {
+      return Err(new CommerceValidationError("No email adapter is configured."));
+    }
+    const rendered = await this.renderInvoiceHtml(orderId, actor, ctx);
+    if (!rendered.ok) return rendered;
+
+    const order = await this.loadOrder(orderId, actor, ctx);
+    if (!order.ok) return order;
+
+    await email.send({
+      template: "order-invoice",
+      to,
+      data: {
+        orgId: resolveOrgId(actor ?? ctx?.actor ?? null),
+        orderId,
+        orderNumber: order.value.orderNumber,
+        invoiceNumber: rendered.value.invoiceNumber,
+        grandTotal: order.value.grandTotal,
+        currency: order.value.currency,
+        html: rendered.value.html,
+      },
+    });
+    return Ok({ sent: true, invoiceNumber: rendered.value.invoiceNumber, to });
+  }
+}

package/src/modules/fulfillment/service.ts

@@ -4,7 +4,7 @@ import type { Actor } from "../../auth/types.js";
 import type { DatabaseAdapter } from "../../kernel/database/adapter.js";
 import type { PluginDb } from "../../kernel/database/plugin-types.js";
 import type { TxContext } from "../../kernel/database/tx-context.js";
-import { CommerceNotFoundError } from "../../kernel/errors.js";
+import { CommerceNotFoundError, CommerceValidationError } from "../../kernel/errors.js";
 import { runAfterHooks } from "../../kernel/hooks/executor.js";
 import { createHookContext } from "../../kernel/hooks/create-context.js";
 import type { HookRegistry } from "../../kernel/hooks/registry.js";
@@ -346,6 +346,144 @@ export class FulfillmentService {
     return Ok(undefined);
   }
 
+  /**
+   * Records a fulfillment (e.g. a shipment) for a subset of an order's line
+   * items, with optional carrier/tracking details. Supports partial
+   * fulfillment (per-line quantities) and multiple fulfillments per order.
+   */
+  async createFulfillment(
+    input: {
+      orderId: string;
+      lineItems: Array<{ orderLineItemId: string; quantity: number }>;
+      carrier?: string;
+      trackingNumber?: string;
+      trackingUrl?: string;
+      type?: string;
+      status?: string;
+      metadata?: Record<string, unknown>;
+    },
+    actor?: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<FulfillmentRecord>> {
+    const orgId = resolveOrgId(actor ?? ctx?.actor ?? null);
+    const order = await this.deps.ordersRepository.findById(orgId, input.orderId, ctx);
+    if (!order) return Err(new CommerceNotFoundError("Order not found."));
+
+    const orderLines = await this.deps.ordersRepository.findLineItemsByOrderId(
+      input.orderId,
+      ctx,
+    );
+    const linesById = new Map(orderLines.map((li) => [li.id, li]));
+
+    // Validate every requested line before writing anything: it must belong
+    // to the order, and requested + already-fulfilled must not exceed ordered.
+    const alreadyFulfilled = new Map<string, number>();
+    for (const req of input.lineItems) {
+      const line = linesById.get(req.orderLineItemId);
+      if (!line) {
+        return Err(
+          new CommerceValidationError(
+            `Line item ${req.orderLineItemId} does not belong to this order.`,
+          ),
+        );
+      }
+      const fulfilled = await this.deps.repository.getFulfilledQuantity(
+        req.orderLineItemId,
+        ctx,
+      );
+      alreadyFulfilled.set(req.orderLineItemId, fulfilled);
+      if (fulfilled + req.quantity > line.quantity) {
+        return Err(
+          new CommerceValidationError(
+            `Cannot fulfill ${req.quantity} of "${line.title}" — only ${line.quantity - fulfilled} remaining.`,
+          ),
+        );
+      }
+    }
+
+    const status = input.status ?? "shipped";
+    const created = await this.deps.repository.create(
+      {
+        orderId: order.id,
+        type: input.type ?? "physical",
+        status,
+        carrier: input.carrier ?? null,
+        trackingNumber: input.trackingNumber ?? null,
+        trackingUrl: input.trackingUrl ?? null,
+        ...(status === "shipped" ? { shippedAt: new Date() } : {}),
+        ...(status === "delivered" ? { deliveredAt: new Date() } : {}),
+        ...(order.customerId != null ? { customerId: order.customerId } : {}),
+        metadata: input.metadata ?? {},
+      },
+      ctx,
+    );
+
+    await this.deps.repository.createLineItems(
+      input.lineItems.map((li) => ({
+        fulfillmentId: created.id,
+        orderLineItemId: li.orderLineItemId,
+        quantity: li.quantity,
+      })),
+      ctx,
+    );
+
+    await this.deps.repository.createEvent(
+      {
+        fulfillmentId: created.id,
+        eventType: "created",
+        toStatus: status,
+        ...(actor?.userId !== undefined ? { actorId: actor.userId } : {}),
+        description: input.trackingNumber
+          ? `Shipment recorded (${input.trackingNumber})`
+          : "Fulfillment recorded",
+      },
+      ctx,
+    );
+
+    // Reflect per-line fulfillment progress on the order line items
+    for (const req of input.lineItems) {
+      const line = linesById.get(req.orderLineItemId)!;
+      const total = (alreadyFulfilled.get(req.orderLineItemId) ?? 0) + req.quantity;
+      await this.deps.ordersRepository.updateLineItem(
+        req.orderLineItemId,
+        { fulfillmentStatus: total >= line.quantity ? "fulfilled" : "partial" },
+        ctx,
+      );
+    }
+
+    const record: FulfillmentRecord = {
+      ...toServiceRecord(
+        created,
+        input.lineItems.map((li) => ({
+          id: "",
+          fulfillmentId: created.id,
+          orderLineItemId: li.orderLineItemId,
+          quantity: li.quantity,
+        })),
+      ),
+      lineItems: input.lineItems.map((li) => ({
+        id: li.orderLineItemId,
+        title: linesById.get(li.orderLineItemId)?.title ?? "",
+        quantity: li.quantity,
+      })),
+    };
+
+    const afterHooks = this.deps.hooks.resolve(
+      "fulfillment.afterCreate",
+    ) as AfterHook<FulfillmentRecord>[];
+    const hookCtx: HookContext = createHookContext({
+      actor: actor ?? ctx?.actor ?? null,
+      tx: ctx?.tx ?? null,
+      logger: createLogger("fulfillment"),
+      services: this.deps.services,
+      context: { moduleName: "fulfillment" },
+      database: { db: this.deps.database.db as PluginDb },
+    });
+    await runAfterHooks(afterHooks, null, record, "create", hookCtx);
+
+    return Ok(record);
+  }
+
   async getByOrderId(
     orderId: string,
     ctx?: TxContext,

package/src/modules/orders/repository/index.ts

@@ -4,7 +4,7 @@ import type {
   DrizzleDatabase,
   DbOrTx,
 } from "../../../kernel/database/drizzle-db.js";
-import { orders, orderLineItems, orderStatusHistory } from "../schema.js";
+import { orders, orderLineItems, orderNotes, orderRefunds, orderStatusHistory } from "../schema.js";
 import { customers } from "../../customers/schema.js";
 
 export interface OrderLookupRow {
@@ -26,6 +26,10 @@ export type OrderLineItem = typeof orderLineItems.$inferSelect;
 export type OrderLineItemInsert = typeof orderLineItems.$inferInsert;
 export type OrderStatusHistory = typeof orderStatusHistory.$inferSelect;
 export type OrderStatusHistoryInsert = typeof orderStatusHistory.$inferInsert;
+export type OrderRefund = typeof orderRefunds.$inferSelect;
+export type OrderRefundInsert = typeof orderRefunds.$inferInsert;
+export type OrderNote = typeof orderNotes.$inferSelect;
+export type OrderNoteInsert = typeof orderNotes.$inferInsert;
 
 /**
  * OrdersRepository provides type-safe database operations for orders.
@@ -159,6 +163,24 @@ export class OrdersRepository {
     return query;
   }
 
+  async findByIdempotencyKey(
+    orgId: string,
+    idempotencyKey: string,
+    ctx?: TxContext,
+  ): Promise<Order | undefined> {
+    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: OrderInsert, ctx?: TxContext): Promise<Order> {
     const db = this.getDb(ctx);
     const rows = await db.insert(orders).values(data).returning();
@@ -328,6 +350,110 @@ export class OrdersRepository {
     return { order, lineItems };
   }
 
+  // ─────────────────────────────────────────────────────────────────────────────
+  // Line-level refunds (issue #52)
+  // ─────────────────────────────────────────────────────────────────────────────
+
+  async createRefund(data: OrderRefundInsert, ctx?: TxContext): Promise<OrderRefund> {
+    const db = this.getDb(ctx);
+    const rows = await db.insert(orderRefunds).values(data).returning();
+    return rows[0]!;
+  }
+
+  async findRefundById(
+    orgId: string,
+    id: string,
+    ctx?: TxContext,
+  ): Promise<OrderRefund | undefined> {
+    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: string, ctx?: TxContext): Promise<OrderRefund[]> {
+    const db = this.getDb(ctx);
+    return db
+      .select()
+      .from(orderRefunds)
+      .where(eq(orderRefunds.orderId, orderId))
+      .orderBy(desc(orderRefunds.createdAt));
+  }
+
+  async markRefundUndone(
+    id: string,
+    undoneBy: string,
+    ctx?: TxContext,
+  ): Promise<OrderRefund | undefined> {
+    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: string,
+    performedBy: string,
+    timezone: string,
+    ctx?: TxContext,
+  ): Promise<number> {
+    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 as Record<string, unknown>[])
+      : ((result as { rows?: Record<string, unknown>[] }).rows ?? []);
+    const total = rows[0]?.total;
+    return typeof total === "bigint" ? Number(total) : ((total as number) ?? 0);
+  }
+
+  // ─────────────────────────────────────────────────────────────────────────────
+  // Order notes (issue #56)
+  // ─────────────────────────────────────────────────────────────────────────────
+
+  async createNote(data: OrderNoteInsert, ctx?: TxContext): Promise<OrderNote> {
+    const db = this.getDb(ctx);
+    const rows = await db.insert(orderNotes).values(data).returning();
+    return rows[0]!;
+  }
+
+  async findNotesByOrderId(orderId: string, ctx?: TxContext): Promise<OrderNote[]> {
+    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: string, orderId: string, noteId: string, ctx?: TxContext): Promise<boolean> {
+    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
   // ─────────────────────────────────────────────────────────────────────────────

package/src/modules/orders/schema.ts

@@ -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";
 
@@ -17,6 +18,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<Record<string, unknown>>().default({}),
   placedAt: timestamp("placed_at", { withTimezone: true }).defaultNow().notNull(),
   fulfilledAt: timestamp("fulfilled_at", { withTimezone: true }),
@@ -28,6 +32,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", {
@@ -45,6 +52,9 @@ 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<Record<string, unknown>>().default({}),
 }, (table) => [
@@ -52,6 +62,49 @@ export const orderLineItems = pgTable("order_line_items", {
   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<Array<{ lineItemId: string; quantity: number; amount: number }>>().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")