@porulle/core 0.6.0 → 0.8.0

package/src/modules/media/service.ts

@@ -28,6 +28,16 @@ export interface AttachMediaInput {
   sortOrder?: number;
 }
 
+export interface AttachedMedia {
+  mediaAssetId: string;
+  role: string;
+  sortOrder: number;
+  variantId: string | null;
+  url: string;
+  alt: string | null;
+  contentType: string;
+}
+
 interface MediaServiceDeps {
   repository: MediaRepository;
   catalogRepository: CatalogRepository;
@@ -234,4 +244,34 @@ export class MediaService {
 
     return Ok(undefined);
   }
+
+  /**
+   * Media attached to an entity, resolved to public URLs and ordered by
+   * sortOrder. Powers catalog `?include=media` hydration. Returns entity-level
+   * links only unless a specific variantId is requested.
+   */
+  async listEntityMedia(
+    entityId: string,
+    opts?: { variantId?: string; orgId?: string },
+    ctx?: TxContext,
+  ): Promise<Result<AttachedMedia[]>> {
+    const links = await this.repo.findEntityMedia(entityId, opts?.variantId, ctx);
+    const out: AttachedMedia[] = [];
+    for (const link of links) {
+      const asset = await this.repo.findAssetById(link.mediaAssetId, ctx, opts?.orgId);
+      if (!asset) continue;
+      const urlResult = await this.deps.storage.getUrl(asset.storageKey);
+      out.push({
+        mediaAssetId: link.mediaAssetId,
+        role: link.role,
+        sortOrder: link.sortOrder,
+        variantId: link.variantId ?? null,
+        url: urlResult.ok ? urlResult.value : "",
+        alt: asset.alt ?? null,
+        contentType: asset.contentType,
+      });
+    }
+    out.sort((a, b) => a.sortOrder - b.sortOrder);
+    return Ok(out);
+  }
 }

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")