@porulle/core 0.7.0 → 0.9.0

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";
@@ -487,6 +504,23 @@ export declare const orderLineItems: import("drizzle-orm/pg-core").PgTableWithCo
             identity: undefined;
             generated: undefined;
         }, {}, {}>;
+        isCustomPrice: import("drizzle-orm/pg-core").PgColumn<{
+            name: "is_custom_price";
+            tableName: "order_line_items";
+            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;
+        }, {}, {}>;
         taxAmount: import("drizzle-orm/pg-core").PgColumn<{
             name: "tax_amount";
             tableName: "order_line_items";
@@ -521,6 +555,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 +611,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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA2BzB,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(),
@@ -41,14 +48,62 @@ export const orderLineItems = pgTable("order_line_items", {
     quantity: integer("quantity").notNull(),
     unitPrice: integer("unit_price").notNull(),
     totalPrice: integer("total_price").notNull(),
+    // Price provenance (matches Medusa's `is_custom_price`): true when a staff
+    // actor with `orders:manage` supplied an explicit override price rather than
+    // the server-derived catalog price. Audit + reporting signal.
+    isCustomPrice: boolean("is_custom_price").notNull().default(false),
     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")

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

@@ -3,11 +3,13 @@ import type { HookRegistry } from "../../kernel/hooks/registry.js";
 import { type OrderState, type StateDefinition } from "../../kernel/state-machine/machine.js";
 import { type Result } from "../../kernel/result.js";
 import { type Pagination } from "../../utils/pagination.js";
-import type { TxContext } from "../../kernel/database/tx-context.js";
+import { type TxContext } from "../../kernel/database/tx-context.js";
 import type { DatabaseAdapter } from "../../kernel/database/adapter.js";
-import { OrdersRepository, type Order, type OrderLineItem, type OrderStatusHistory } from "./repository/index.js";
+import { OrdersRepository, type Order, type OrderLineItem, type OrderNote, type OrderRefund, type OrderStatusHistory } from "./repository/index.js";
 export interface CreateOrderInput {
     customerId?: string;
+    /** Client-supplied retry key — a repeat create with the same key returns the original order. */
+    idempotencyKey?: string | undefined;
     currency: string;
     subtotal: number;
     taxTotal: number;
@@ -75,9 +77,25 @@ export declare class OrderService {
     private readonly machine;
     constructor(deps: OrderServiceDeps);
     private hydrateOrder;
-    create(input: CreateOrderInput, actor: Actor | null, ctx?: TxContext): Promise<Result<HydratedOrder>>;
+    /**
+     * Resolve every line item's price with org-integrity + price provenance,
+     * mirroring how our forefathers handle this (Vendure: order lines are always
+     * server-priced from the variant; Medusa: an admin override is honored but
+     * flagged `is_custom_price`). Three modes:
+     *   - trusted caller (checkout / POS exchange, already server-priced) → prices honored as-is.
+     *   - actor with `orders:manage` → explicit price honored as a manual override, flagged isCustomPrice.
+     *   - otherwise → price re-derived server-side from the catalog; client prices ignored.
+     * The referenced entity MUST belong to the order's org in every mode.
+     */
+    private resolveLines;
+    create(input: CreateOrderInput, actor: Actor | null, ctx?: TxContext, opts?: {
+        trustedPricing?: boolean;
+        stockPolicy?: "reserve" | "backorder";
+    }): Promise<Result<HydratedOrder>>;
     getById(id: string, actor: Actor | null, ctx?: TxContext): Promise<Result<HydratedOrder>>;
     getByNumber(orderNumber: string, actor: Actor | null, ctx?: TxContext): Promise<Result<HydratedOrder>>;
+    /** Returns the order previously created with this idempotency key, or null. */
+    getByIdempotencyKey(idempotencyKey: string, actor?: Actor | null, ctx?: TxContext): Promise<Result<HydratedOrder | null>>;
     list(params: ListOrdersParams, actor: Actor | null, ctx?: TxContext): Promise<Result<OrderListResult>>;
     listByCustomer(customerId: string, params: ListOrdersParams, actor?: Actor | null, ctx?: TxContext): Promise<Result<OrderListResult>>;
     /**
@@ -108,6 +126,62 @@ export declare class OrderService {
     refund(orderId: string, actor: Actor | null, reason?: string, ctx?: TxContext, opts?: {
         amount?: number;
     }): Promise<Result<HydratedOrder>>;
+    private refundPolicies;
+    /**
+     * Refunds specific line-item quantities (issue #52). Enforces per-line
+     * refundable quantity (`quantity - refundedQuantity`), the operator's daily
+     * refund cap (`policies.refundDailyCap`, 403 with the cap surfaced), moves
+     * money through the payment adapter when the order has a captured payment,
+     * and records an auditable `order_refunds` ledger row.
+     */
+    refundLines(orderId: string, input: {
+        lines: Array<{
+            lineItemId: string;
+            quantity: number;
+        }>;
+        reason?: string | undefined;
+    }, actor: Actor | null, ctx?: TxContext): Promise<Result<{
+        order: HydratedOrder;
+        refund: OrderRefund;
+    }>>;
+    /**
+     * Undoes a refund within the configured window
+     * (`policies.refundUndoWindowMinutes`, default 15). Restores line
+     * refundedQuantity and marks the ledger row `undone` — an audited,
+     * compensating ledger operation; re-collecting the money (cash back into
+     * the drawer) is the operator's side of the exchange.
+     */
+    undoRefund(orderId: string, refundId: string, actor: Actor | null, ctx?: TxContext): Promise<Result<{
+        order: HydratedOrder;
+        refund: OrderRefund;
+    }>>;
+    listRefunds(orderId: string, actor: Actor | null, ctx?: TxContext): Promise<Result<OrderRefund[]>>;
+    /** The acting operator's daily refund-cap status (issue #52). */
+    refundCapStatus(actor: Actor | null, ctx?: TxContext): Promise<Result<{
+        cap: number | null;
+        usedToday: number;
+        remaining: number | null;
+    }>>;
+    private requireOrderAccess;
+    addNote(orderId: string, input: {
+        body: string;
+        pinned?: boolean | undefined;
+    }, actor: Actor | null, ctx?: TxContext): Promise<Result<OrderNote>>;
+    listNotes(orderId: string, actor: Actor | null, ctx?: TxContext): Promise<Result<OrderNote[]>>;
+    deleteNote(orderId: string, noteId: string, actor: Actor | null, ctx?: TxContext): Promise<Result<{
+        deleted: true;
+    }>>;
+    /**
+     * One merged per-order activity view (issue #56): status history + operator
+     * notes + refund ledger events (both directions), newest first.
+     */
+    timeline(orderId: string, actor: Actor | null, ctx?: TxContext): Promise<Result<Array<{
+        type: "status" | "note" | "refund";
+        at: Date;
+        actor: string;
+        summary: string;
+        data: Record<string, unknown>;
+    }>>>;
     /**
      * Capture an authorized payment for an order via the payment adapter and
      * record the captured amount. Does not transition order status — capture is a
@@ -117,6 +191,31 @@ export declare class OrderService {
         amount?: number;
     }, ctx?: TxContext): Promise<Result<HydratedOrder>>;
     getStatusHistory(orderId: string, actor?: Actor | null, ctx?: TxContext): Promise<Result<OrderStatusHistory[]>>;
+    /** Line items may not be edited on terminal or fully-captured orders. */
+    private lineItemEditGuard;
+    /**
+     * Recomputes subtotal/taxTotal/grandTotal from the order's line items
+     * (shippingTotal and order-level discountTotal are preserved), persists
+     * them, and records an audit entry in the status history.
+     */
+    private recalcOrderTotals;
+    addLineItem(orderId: string, input: {
+        entityId: string;
+        entityType: string;
+        variantId?: string | undefined;
+        sku?: string | undefined;
+        title: string;
+        quantity: number;
+        unitPrice: number;
+        totalPrice?: number | undefined;
+        taxAmount?: number | undefined;
+        discountAmount?: number | undefined;
+        metadata?: Record<string, unknown> | undefined;
+    }, actor: Actor | null, ctx?: TxContext): Promise<Result<HydratedOrder>>;
+    updateOrderLineItem(orderId: string, lineItemId: string, patch: {
+        quantity: number;
+    }, actor: Actor | null, ctx?: TxContext): Promise<Result<HydratedOrder>>;
+    removeLineItem(orderId: string, lineItemId: string, actor: Actor | null, ctx?: TxContext): Promise<Result<HydratedOrder>>;
     updateOrder(orderId: string, data: {
         placedAt?: Date;
         metadata?: Record<string, unknown>;