@porulle/core 0.1.0

package/dist/modules/orders/schema.js

@@ -0,0 +1,64 @@
+import { 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", {
+    id: uuid("id").defaultRandom().primaryKey(),
+    organizationId: text("organization_id").notNull().references(() => organization.id, { onDelete: "cascade" }),
+    orderNumber: text("order_number").notNull(),
+    customerId: uuid("customer_id"),
+    status: text("status").notNull().default("pending"),
+    currency: text("currency").notNull(),
+    subtotal: integer("subtotal").notNull(),
+    taxTotal: integer("tax_total").notNull(),
+    shippingTotal: integer("shipping_total").notNull(),
+    discountTotal: integer("discount_total").notNull().default(0),
+    grandTotal: integer("grand_total").notNull(),
+    amountCaptured: integer("amount_captured"),
+    paymentIntentId: text("payment_intent_id"),
+    paymentMethodId: text("payment_method_id"),
+    metadata: jsonb("metadata").$type().default({}),
+    placedAt: timestamp("placed_at", { withTimezone: true }).defaultNow().notNull(),
+    fulfilledAt: timestamp("fulfilled_at", { withTimezone: true }),
+    cancelledAt: timestamp("cancelled_at", { withTimezone: true }),
+}, (table) => ({
+    orgIdx: index("idx_orders_org").on(table.organizationId),
+    orgOrderNumberUnique: uniqueIndex("orders_org_order_number_unique").on(table.organizationId, table.orderNumber),
+    statusIdx: index("idx_orders_status").on(table.status),
+    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),
+}));
+export const orderLineItems = pgTable("order_line_items", {
+    id: uuid("id").defaultRandom().primaryKey(),
+    orderId: uuid("order_id")
+        .references(() => orders.id, { onDelete: "cascade" })
+        .notNull(),
+    entityId: uuid("entity_id").references(() => sellableEntities.id).notNull(),
+    entityType: text("entity_type").notNull(),
+    variantId: uuid("variant_id").references(() => variants.id),
+    sku: text("sku"),
+    title: text("title").notNull(),
+    quantity: integer("quantity").notNull(),
+    unitPrice: integer("unit_price").notNull(),
+    totalPrice: integer("total_price").notNull(),
+    taxAmount: integer("tax_amount").notNull().default(0),
+    discountAmount: integer("discount_amount").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),
+]);
+export const orderStatusHistory = pgTable("order_status_history", {
+    id: uuid("id").defaultRandom().primaryKey(),
+    orderId: uuid("order_id")
+        .references(() => orders.id, { onDelete: "cascade" })
+        .notNull(),
+    fromStatus: text("from_status").notNull(),
+    toStatus: text("to_status").notNull(),
+    reason: text("reason"),
+    changedBy: text("changed_by").notNull(),
+    changedAt: timestamp("changed_at", { withTimezone: true }).defaultNow().notNull(),
+}, (table) => [
+    index("idx_order_status_history_order_id").on(table.orderId),
+]);

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

@@ -0,0 +1,2 @@
+export declare const orderNumberSeq: import("drizzle-orm/pg-core").PgSequence;
+//# sourceMappingURL=sequences.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sequences.d.ts","sourceRoot":"","sources":["../../../src/modules/orders/sequences.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,cAAc,0CAGzB,CAAC"}

package/dist/modules/orders/sequences.js

@@ -0,0 +1,5 @@
+import { pgSequence } from "drizzle-orm/pg-core";
+export const orderNumberSeq = pgSequence("order_number_seq", {
+    startWith: 1,
+    increment: 1,
+});

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

@@ -0,0 +1,81 @@
+import type { Actor } from "../../auth/types.js";
+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 { DatabaseAdapter } from "../../kernel/database/adapter.js";
+import { OrdersRepository, type Order, type OrderLineItem, type OrderStatusHistory } from "./repository/index.js";
+export interface CreateOrderInput {
+    customerId?: string;
+    currency: string;
+    subtotal: number;
+    taxTotal: number;
+    shippingTotal: number;
+    discountTotal?: number;
+    grandTotal: number;
+    paymentIntentId?: string | undefined;
+    paymentMethodId?: string | undefined;
+    metadata?: Record<string, unknown>;
+    lineItems: Array<{
+        entityId: string;
+        entityType: string;
+        variantId?: string;
+        sku?: string;
+        title: string;
+        quantity: number;
+        unitPrice: number;
+        totalPrice: number;
+        taxAmount?: number;
+        discountAmount?: number;
+        metadata?: Record<string, unknown>;
+    }>;
+}
+export interface ListOrdersParams {
+    page?: number;
+    limit?: number;
+    status?: string;
+}
+export interface ChangeStatusInput {
+    orderId: string;
+    newStatus: OrderState;
+    reason?: string;
+}
+export interface OrderServiceDeps {
+    repository: OrdersRepository;
+    hooks: HookRegistry;
+    services: Record<string, unknown>;
+    /** Custom state machine. If provided, overrides the default order transitions. */
+    stateMachine?: StateDefinition<string>;
+    database: DatabaseAdapter;
+}
+export type HydratedOrder = Order & {
+    lineItems: OrderLineItem[];
+};
+type OrderListResult = {
+    items: HydratedOrder[];
+    pagination: Pagination;
+};
+export declare class OrderService {
+    private deps;
+    private readonly repo;
+    private readonly machine;
+    constructor(deps: OrderServiceDeps);
+    private hydrateOrder;
+    create(input: CreateOrderInput, actor: Actor | null, ctx?: TxContext): 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>>;
+    list(params: ListOrdersParams, actor: Actor | null, ctx?: TxContext): Promise<Result<OrderListResult>>;
+    listByCustomer(customerId: string, params: ListOrdersParams, actor?: Actor | null, ctx?: TxContext): Promise<Result<OrderListResult>>;
+    changeStatus(input: ChangeStatusInput, actor: Actor | null, ctx?: TxContext): Promise<Result<HydratedOrder>>;
+    cancel(orderId: string, actor: Actor | null, reason?: string, ctx?: TxContext): Promise<Result<HydratedOrder>>;
+    refund(orderId: string, actor: Actor | null, reason?: string, ctx?: TxContext): Promise<Result<HydratedOrder>>;
+    getStatusHistory(orderId: string, actor?: Actor | null, ctx?: TxContext): Promise<Result<OrderStatusHistory[]>>;
+    updateOrder(orderId: string, data: {
+        placedAt?: Date;
+        metadata?: Record<string, unknown>;
+        amountCaptured?: number;
+    }, actor?: Actor | null, ctx?: TxContext): Promise<Result<Order>>;
+}
+export {};
+//# sourceMappingURL=service.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../../../src/modules/orders/service.ts"],"names":[],"mappings":"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"}

package/dist/modules/orders/service.js

@@ -0,0 +1,325 @@
+import { resolveOrgId } from "../../auth/org.js";
+import { assertOwnership, assertPermission } from "../../auth/permissions.js";
+import { CommerceInvalidTransitionError, CommerceNotFoundError, CommerceValidationError, toCommerceError, } from "../../kernel/errors.js";
+import { runAfterHooks, runBeforeHooks } from "../../kernel/hooks/executor.js";
+import { createHookContext } from "../../kernel/hooks/create-context.js";
+import { canTransition, orderStateMachine, } from "../../kernel/state-machine/machine.js";
+import { Err, Ok } from "../../kernel/result.js";
+import { createLogger } from "../../utils/logger.js";
+import { paginate } from "../../utils/pagination.js";
+function context(actor, services, database, tx = null) {
+    return createHookContext({
+        actor,
+        tx,
+        logger: createLogger("orders"),
+        services,
+        context: { moduleName: "orders" },
+        database: { db: database.db },
+    });
+}
+export class OrderService {
+    deps;
+    repo;
+    machine;
+    constructor(deps) {
+        this.deps = deps;
+        this.repo = deps.repository;
+        this.machine = deps.stateMachine ?? orderStateMachine;
+    }
+    async hydrateOrder(order, ctx) {
+        const lineItems = await this.repo.findLineItemsByOrderId(order.id, ctx);
+        return { ...order, lineItems };
+    }
+    async create(input, actor, ctx) {
+        try {
+            assertPermission(actor, "orders:create");
+        }
+        catch (error) {
+            return Err(toCommerceError(error));
+        }
+        if (input.lineItems.length === 0) {
+            return Err(new CommerceValidationError("Order requires at least one line item."));
+        }
+        const beforeHooks = this.deps.hooks.resolve("orders.beforeCreate");
+        const afterHooks = this.deps.hooks.resolve("orders.afterCreate");
+        const hookCtx = context(actor, this.deps.services, this.deps.database, ctx?.tx);
+        const processed = await runBeforeHooks(beforeHooks, input, "create", hookCtx);
+        const orderNumber = await this.repo.getNextOrderNumber(ctx);
+        const orgId = resolveOrgId(actor);
+        const order = await this.repo.create({
+            organizationId: orgId,
+            orderNumber,
+            status: "pending",
+            currency: processed.currency,
+            subtotal: processed.subtotal,
+            taxTotal: processed.taxTotal,
+            shippingTotal: processed.shippingTotal,
+            discountTotal: processed.discountTotal ?? 0,
+            grandTotal: processed.grandTotal,
+            ...(processed.paymentIntentId != null ? { paymentIntentId: processed.paymentIntentId } : {}),
+            ...(processed.paymentMethodId != null ? { paymentMethodId: processed.paymentMethodId } : {}),
+            metadata: processed.metadata ?? {},
+            placedAt: new Date(),
+            ...(processed.customerId !== undefined
+                ? { customerId: processed.customerId }
+                : {}),
+        }, ctx);
+        const lineItemsData = processed.lineItems.map((item) => ({
+            orderId: order.id,
+            entityId: item.entityId,
+            entityType: item.entityType,
+            title: item.title,
+            quantity: item.quantity,
+            unitPrice: item.unitPrice,
+            totalPrice: item.totalPrice,
+            taxAmount: item.taxAmount ?? 0,
+            discountAmount: item.discountAmount ?? 0,
+            fulfillmentStatus: "unfulfilled",
+            metadata: item.metadata ?? {},
+            ...(item.variantId !== undefined ? { variantId: item.variantId } : {}),
+            ...(item.sku !== undefined ? { sku: item.sku } : {}),
+        }));
+        await this.repo.createLineItems(lineItemsData, ctx);
+        await this.repo.createStatusHistory({
+            orderId: order.id,
+            fromStatus: "pending",
+            toStatus: "pending",
+            reason: "order_created",
+            changedBy: actor?.userId ?? "system",
+        }, ctx);
+        const hydrated = await this.hydrateOrder(order, ctx);
+        const report = await runAfterHooks(afterHooks, null, hydrated, "create", hookCtx);
+        return Ok(hydrated, report.hasErrors ? { hookErrors: report.errors } : undefined);
+    }
+    async getById(id, actor, ctx) {
+        const orgId = resolveOrgId(actor);
+        const order = await this.repo.findById(orgId, id, ctx);
+        if (!order)
+            return Err(new CommerceNotFoundError("Order not found."));
+        try {
+            if (actor?.permissions.includes("orders:read") ||
+                actor?.permissions.includes("*:*")) {
+                // no-op
+            }
+            else if (actor?.permissions.includes("orders:read:own")) {
+                assertOwnership(actor, order.customerId ?? null);
+            }
+            else {
+                assertPermission(actor, "orders:read");
+            }
+        }
+        catch (error) {
+            return Err(toCommerceError(error));
+        }
+        const hydrated = await this.hydrateOrder(order, ctx);
+        // Run afterGet hooks — allows plugins to enrich the order (e.g., vendor fulfillment)
+        const afterGetHooks = this.deps.hooks.resolve("orders.afterGet");
+        if (afterGetHooks.length > 0) {
+            const hookCtx = context(actor, this.deps.services, this.deps.database, ctx?.tx);
+            await runAfterHooks(afterGetHooks, null, hydrated, "read", hookCtx);
+        }
+        return Ok(hydrated);
+    }
+    async getByNumber(orderNumber, actor, ctx) {
+        const orgId = resolveOrgId(actor);
+        const order = await this.repo.findByOrderNumber(orgId, orderNumber, ctx);
+        if (!order)
+            return Err(new CommerceNotFoundError("Order not found."));
+        return this.getById(order.id, actor, ctx);
+    }
+    async list(params, actor, ctx) {
+        try {
+            assertPermission(actor, "orders:read");
+        }
+        catch (error) {
+            return Err(toCommerceError(error));
+        }
+        const orgId = resolveOrgId(actor);
+        let items;
+        if (params.status) {
+            items = await this.repo.findByStatus(orgId, params.status, ctx);
+        }
+        else {
+            items = await this.repo.findAll(orgId, undefined, ctx);
+        }
+        // Sort by placedAt descending (in-memory, as findAll already sorts)
+        items.sort((a, b) => b.placedAt.getTime() - a.placedAt.getTime());
+        const paged = paginate(items, params.page ?? 1, params.limit ?? 20);
+        const hydratedItems = await Promise.all(paged.items.map((order) => this.hydrateOrder(order, ctx)));
+        return Ok({
+            items: hydratedItems,
+            pagination: paged.pagination,
+        });
+    }
+    async listByCustomer(customerId, params, actor, ctx) {
+        const orgId = resolveOrgId(actor ?? ctx?.actor ?? null);
+        let items = await this.repo.findByCustomerId(orgId, customerId, ctx);
+        if (params.status) {
+            items = items.filter((order) => order.status === params.status);
+        }
+        items.sort((a, b) => b.placedAt.getTime() - a.placedAt.getTime());
+        const paged = paginate(items, params.page ?? 1, params.limit ?? 20);
+        const hydratedItems = await Promise.all(paged.items.map((order) => this.hydrateOrder(order, ctx)));
+        return Ok({
+            items: hydratedItems,
+            pagination: paged.pagination,
+        });
+    }
+    async changeStatus(input, actor, ctx) {
+        const orgId = resolveOrgId(actor);
+        const order = await this.repo.findById(orgId, input.orderId, ctx);
+        if (!order)
+            return Err(new CommerceNotFoundError("Order not found."));
+        try {
+            assertPermission(actor, "orders:update");
+        }
+        catch (error) {
+            return Err(toCommerceError(error));
+        }
+        if (!canTransition(this.machine, order.status, input.newStatus)) {
+            return Err(new CommerceInvalidTransitionError(`Cannot transition from ${order.status} to ${input.newStatus}.`));
+        }
+        const beforeHooks = this.deps.hooks.resolve("orders.beforeStatusChange");
+        const afterHooks = this.deps.hooks.resolve("orders.afterStatusChange");
+        const hookCtx = context(actor, this.deps.services, this.deps.database, ctx?.tx);
+        const statusHookInput = {
+            orderId: order.id,
+            fromStatus: order.status,
+            newStatus: input.newStatus,
+            ...(input.reason !== undefined ? { reason: input.reason } : {}),
+        };
+        await runBeforeHooks(beforeHooks, statusHookInput, "statusChange", hookCtx);
+        const previous = order.status;
+        const lineItems = await this.repo.findLineItemsByOrderId(order.id, ctx);
+        // VAPT r2 (codex) finding: side effects (inventory release, payment
+        // refund, tax void) used to run BEFORE the atomic compare-and-swap on
+        // updateStatus. Two parallel cancel/refund requests on the same order
+        // would both pass the canTransition check, both release inventory,
+        // and both call payments.refund() — double refund and double release —
+        // before one of them lost the CAS and returned "concurrent change".
+        //
+        // Fix: do the CAS first. Only the thread that wins the status update
+        // proceeds to the side effects. Losers see the validation error and
+        // exit before touching payments / inventory / tax.
+        const cas = await this.repo.updateStatus(order.id, previous, input.newStatus, ctx);
+        if (!cas) {
+            return Err(new CommerceValidationError(`Order status changed concurrently. Refresh and retry.`));
+        }
+        // Handle cancellation and refund side effects
+        if (input.newStatus === "cancelled" || input.newStatus === "refunded") {
+            // 1. Release inventory reservations
+            const inventory = this.deps.services.inventory;
+            if (inventory?.release) {
+                for (const lineItem of lineItems) {
+                    // Only release inventory for unfulfilled items.
+                    // Fulfilled items had their reservation released during the
+                    // fulfilled transition — releasing again would double-release.
+                    if (lineItem.fulfillmentStatus === "unfulfilled") {
+                        await inventory.release({
+                            entityId: lineItem.entityId,
+                            quantity: lineItem.quantity,
+                            orderId: order.id,
+                            performedBy: actor?.userId ?? "system",
+                            ...(lineItem.variantId != null
+                                ? { variantId: lineItem.variantId }
+                                : {}),
+                        });
+                    }
+                }
+            }
+            // 2. Refund payment (if captured)
+            const paymentIntentId = order.paymentIntentId
+                ?? order.metadata?.paymentIntentId;
+            if (paymentIntentId) {
+                const payments = this.deps.services.payments;
+                if (payments?.refund) {
+                    const refundAmount = Math.min(order.grandTotal, order.amountCaptured ?? order.grandTotal);
+                    await payments.refund(paymentIntentId, refundAmount, input.reason ?? `order_${input.newStatus}`);
+                }
+            }
+            // 3. Void tax transaction
+            const tax = this.deps.services.tax;
+            if (tax?.voidTransaction) {
+                await tax.voidTransaction({ transactionId: order.id });
+            }
+        }
+        // Handle fulfillment: deduct on_hand and release reservations.
+        // Items have been shipped — on_hand decreases (stock left the warehouse)
+        // and reservations are cleared (no longer needed).
+        //
+        // Net effect per line item:
+        //   on_hand -= quantity, reserved -= quantity, available unchanged
+        //   Before: on_hand=100, reserved=5, available=95
+        //   After:  on_hand=95,  reserved=0, available=95
+        if (input.newStatus === "fulfilled" || input.newStatus === "partially_fulfilled") {
+            const inventory = this.deps.services.inventory;
+            if (inventory) {
+                for (const lineItem of lineItems) {
+                    if (lineItem.fulfillmentStatus === "unfulfilled") {
+                        // Deduct on_hand (stock physically left warehouse)
+                        await inventory.deductForFulfillment({
+                            entityId: lineItem.entityId,
+                            quantity: lineItem.quantity,
+                            orderId: order.id,
+                            orgId: order.organizationId,
+                            ...(lineItem.variantId != null
+                                ? { variantId: lineItem.variantId }
+                                : {}),
+                        });
+                        // Release reservation (no longer needed)
+                        await inventory.release({
+                            entityId: lineItem.entityId,
+                            quantity: lineItem.quantity,
+                            orderId: order.id,
+                            performedBy: actor?.userId ?? "system",
+                            ...(lineItem.variantId != null
+                                ? { variantId: lineItem.variantId }
+                                : {}),
+                        });
+                        // Mark line item as fulfilled
+                        await this.repo.updateLineItem(lineItem.id, { fulfillmentStatus: "fulfilled" }, ctx);
+                    }
+                }
+            }
+        }
+        // Status was atomically updated above; proceed with audit trail.
+        await this.repo.createStatusHistory({
+            orderId: order.id,
+            fromStatus: previous,
+            toStatus: input.newStatus,
+            changedBy: actor?.userId ?? "system",
+            ...(input.reason !== undefined ? { reason: input.reason } : {}),
+        }, ctx);
+        // Audit logging is now automatic via audit hooks (RFC-005)
+        // registered in kernel boot — no manual audit.record() needed.
+        const hydrated = await this.hydrateOrder(cas, ctx);
+        const report = await runAfterHooks(afterHooks, null, hydrated, "statusChange", hookCtx);
+        return Ok(hydrated, report.hasErrors ? { hookErrors: report.errors } : undefined);
+    }
+    async cancel(orderId, actor, reason = "cancelled_by_user", ctx) {
+        return this.changeStatus({ orderId, newStatus: "cancelled", reason }, actor, ctx);
+    }
+    async refund(orderId, actor, reason = "refunded", ctx) {
+        return this.changeStatus({ orderId, newStatus: "refunded", reason }, actor, ctx);
+    }
+    async getStatusHistory(orderId, actor, ctx) {
+        const orgId = resolveOrgId(actor ?? ctx?.actor ?? null);
+        const order = await this.repo.findById(orgId, orderId, ctx);
+        if (!order) {
+            return Err(new CommerceNotFoundError("Order not found."));
+        }
+        const items = await this.repo.findStatusHistoryByOrderId(orderId, ctx);
+        // Sort by changedAt ascending (oldest first)
+        items.sort((a, b) => a.changedAt.getTime() - b.changedAt.getTime());
+        return Ok(items);
+    }
+    async updateOrder(orderId, data, actor, ctx) {
+        const orgId = resolveOrgId(actor ?? ctx?.actor ?? null);
+        const order = await this.repo.findById(orgId, orderId, ctx);
+        if (!order) {
+            return Err(new CommerceNotFoundError("Order not found."));
+        }
+        const updated = await this.repo.update(orderId, data, ctx);
+        return Ok(updated);
+    }
+}

package/dist/modules/orders/stale-order-cleanup.d.ts

@@ -0,0 +1,27 @@
+import type { TaskDefinition } from "../../kernel/jobs/types.js";
+/**
+ * Stale Order Cleanup Task
+ *
+ * Cancels orders stuck in "pending" status for longer than the configured
+ * threshold (default: 48 hours). This releases reserved inventory and
+ * refunds captured payments, preventing phantom stock loss from abandoned
+ * orders.
+ *
+ * Register via config.jobs.tasks:
+ * ```ts
+ * import { staleOrderCleanupTask } from "@porulle/core";
+ * defineConfig({
+ *   jobs: {
+ *     tasks: [staleOrderCleanupTask],
+ *     autorun: { enabled: true, intervalMs: 3600_000 }, // hourly
+ *   },
+ * });
+ * ```
+ */
+export declare const staleOrderCleanupTask: TaskDefinition<{
+    thresholdHours?: number;
+}, {
+    cancelledCount: number;
+    orderIds: string[];
+}>;
+//# sourceMappingURL=stale-order-cleanup.d.ts.map

package/dist/modules/orders/stale-order-cleanup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stale-order-cleanup.d.ts","sourceRoot":"","sources":["../../../src/modules/orders/stale-order-cleanup.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAe,MAAM,4BAA4B,CAAC;AAE9E;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,qBAAqB,EAAE,cAAc,CAChD;IAAE,cAAc,CAAC,EAAE,MAAM,CAAA;CAAE,EAC3B;IAAE,cAAc,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;CAAE,CAkD/C,CAAC"}

package/dist/modules/orders/stale-order-cleanup.js

@@ -0,0 +1,55 @@
+import { eq, and, lt } from "drizzle-orm";
+import { orders } from "./schema.js";
+/**
+ * Stale Order Cleanup Task
+ *
+ * Cancels orders stuck in "pending" status for longer than the configured
+ * threshold (default: 48 hours). This releases reserved inventory and
+ * refunds captured payments, preventing phantom stock loss from abandoned
+ * orders.
+ *
+ * Register via config.jobs.tasks:
+ * ```ts
+ * import { staleOrderCleanupTask } from "@porulle/core";
+ * defineConfig({
+ *   jobs: {
+ *     tasks: [staleOrderCleanupTask],
+ *     autorun: { enabled: true, intervalMs: 3600_000 }, // hourly
+ *   },
+ * });
+ * ```
+ */
+export const staleOrderCleanupTask = {
+    slug: "orders/stale-cleanup",
+    async handler({ input, ctx }) {
+        const thresholdHours = input.thresholdHours ?? 48;
+        const cutoff = new Date(Date.now() - thresholdHours * 60 * 60 * 1000);
+        // Find stale pending orders
+        const staleOrders = await ctx.db
+            .select()
+            .from(orders)
+            .where(and(eq(orders.status, "pending"), lt(orders.placedAt, cutoff)));
+        const cancelledIds = [];
+        // Cancel each stale order via the service (triggers inventory release + payment refund)
+        const orderService = ctx.services.orders;
+        for (const order of staleOrders) {
+            try {
+                await orderService.cancel(order.id, null, `Auto-cancelled: pending for >${thresholdHours}h`);
+                cancelledIds.push(order.id);
+                ctx.logger.info(`Stale order ${order.orderNumber} auto-cancelled`, {
+                    orderId: order.id,
+                    placedAt: order.placedAt,
+                });
+            }
+            catch (error) {
+                ctx.logger.error(`Failed to cancel stale order ${order.orderNumber}`, { error });
+            }
+        }
+        return {
+            output: {
+                cancelledCount: cancelledIds.length,
+                orderIds: cancelledIds,
+            },
+        };
+    },
+};

package/dist/modules/organization/index.d.ts

@@ -0,0 +1,2 @@
+export { organizationModule } from "./module.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/modules/organization/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/modules/organization/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC"}

package/dist/modules/organization/index.js

@@ -0,0 +1 @@
+export { organizationModule } from "./module.js";