@unifiedcommerce/core 0.4.4 → 0.5.0

package/dist/modules/fulfillment/schema.js

@@ -0,0 +1,83 @@
+import { integer, jsonb, pgTable, text, timestamp, uuid, boolean, } from "drizzle-orm/pg-core";
+import { orders, orderLineItems } from "../orders/schema.js";
+import { customers } from "../customers/schema.js";
+/**
+ * Fulfillment Records Table
+ *
+ * Tracks physical shipments, digital deliveries, and access grants.
+ * Each fulfillment can be associated with one or more order line items.
+ */
+export const fulfillmentRecords = pgTable("fulfillment_records", {
+    id: uuid("id").defaultRandom().primaryKey(),
+    orderId: uuid("order_id")
+        .references(() => orders.id, { onDelete: "cascade" })
+        .notNull(),
+    customerId: uuid("customer_id").references(() => customers.id),
+    // Fulfillment type: "physical", "digital", "access_grant"
+    type: text("type").notNull(),
+    // Status: "pending", "processing", "shipped", "delivered", "cancelled", "failed"
+    status: text("status").notNull().default("pending"),
+    // Physical shipment fields
+    carrier: text("carrier"),
+    trackingNumber: text("tracking_number"),
+    trackingUrl: text("tracking_url"),
+    estimatedDelivery: timestamp("estimated_delivery", { withTimezone: true }),
+    shippedAt: timestamp("shipped_at", { withTimezone: true }),
+    deliveredAt: timestamp("delivered_at", { withTimezone: true }),
+    // Digital delivery fields
+    downloadUrl: text("download_url"),
+    downloadExpiresAt: timestamp("download_expires_at", { withTimezone: true }),
+    maxDownloads: integer("max_downloads"),
+    downloadCount: integer("download_count").notNull().default(0),
+    // Access grant fields (e.g., course access, membership)
+    entityType: text("entity_type"),
+    entityId: uuid("entity_id"),
+    grantedAt: timestamp("granted_at", { withTimezone: true }),
+    expiresAt: timestamp("expires_at", { withTimezone: true }),
+    isActive: boolean("is_active").notNull().default(true),
+    // Metadata for extensibility
+    metadata: jsonb("metadata").$type().default({}),
+    // Timestamps
+    createdAt: timestamp("created_at", { withTimezone: true })
+        .defaultNow()
+        .notNull(),
+    updatedAt: timestamp("updated_at", { withTimezone: true })
+        .defaultNow()
+        .notNull(),
+});
+/**
+ * Fulfillment Line Items Junction Table
+ *
+ * Links fulfillment records to order line items (many-to-many).
+ * Allows partial fulfillments where only some items from an order are fulfilled together.
+ */
+export const fulfillmentLineItems = pgTable("fulfillment_line_items", {
+    id: uuid("id").defaultRandom().primaryKey(),
+    fulfillmentId: uuid("fulfillment_id")
+        .references(() => fulfillmentRecords.id, { onDelete: "cascade" })
+        .notNull(),
+    orderLineItemId: uuid("order_line_item_id")
+        .references(() => orderLineItems.id, { onDelete: "cascade" })
+        .notNull(),
+    quantity: integer("quantity").notNull(),
+});
+/**
+ * Fulfillment Events Table
+ *
+ * Audit trail of fulfillment status changes and events.
+ */
+export const fulfillmentEvents = pgTable("fulfillment_events", {
+    id: uuid("id").defaultRandom().primaryKey(),
+    fulfillmentId: uuid("fulfillment_id")
+        .references(() => fulfillmentRecords.id, { onDelete: "cascade" })
+        .notNull(),
+    eventType: text("event_type").notNull(), // "created", "shipped", "delivered", "cancelled", "download", etc.
+    fromStatus: text("from_status"),
+    toStatus: text("to_status"),
+    description: text("description"),
+    actorId: text("actor_id"), // User/system that triggered the event
+    metadata: jsonb("metadata").$type().default({}),
+    occurredAt: timestamp("occurred_at", { withTimezone: true })
+        .defaultNow()
+        .notNull(),
+});

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

@@ -0,0 +1,58 @@
+import type { Actor } from "../../auth/types.js";
+import { type Result } from "../../kernel/result.js";
+import type { TxContext } from "../../kernel/database/tx-context.js";
+import type { FulfillmentRepository } from "./repository/index.js";
+import type { OrdersRepository } from "../orders/repository/index.js";
+import type { FulfillmentRecord } from "./types.js";
+interface InventoryServiceLike {
+    adjust(input: {
+        entityId: string;
+        variantId?: string;
+        warehouseId?: string;
+        adjustment: number;
+        reason: string;
+        referenceType?: string;
+        referenceId?: string;
+    }, actor?: unknown): Promise<unknown>;
+    release(input: {
+        entityId: string;
+        variantId?: string;
+        quantity: number;
+        orderId: string;
+        performedBy?: string;
+    }): Promise<unknown>;
+}
+interface FulfillmentServiceDeps {
+    repository: FulfillmentRepository;
+    ordersRepository: OrdersRepository;
+    inventoryService?: InventoryServiceLike;
+}
+export declare class FulfillmentService {
+    private deps;
+    private strategies;
+    constructor(deps: FulfillmentServiceDeps);
+    fulfillOrder(orderId: string, actor?: Actor | null, ctx?: TxContext): Promise<Result<void>>;
+    getByOrderId(orderId: string, ctx?: TxContext): Promise<Result<FulfillmentRecord[]>>;
+    updateTracking(input: {
+        fulfillmentId: string;
+        carrier?: string;
+        trackingNumber?: string;
+        trackingUrl?: string;
+        status?: string;
+    }, ctx?: TxContext): Promise<Result<void>>;
+    getDownloadUrl(orderId: string, lineItemId: string, userId: string, actor?: Actor | null, ctx?: TxContext): Promise<Result<{
+        url: string;
+        remaining: number;
+        expiresAt: string;
+    }>>;
+    getDigitalAccess(userId: string, type?: string, ctx?: TxContext): Promise<Result<Array<{
+        entityId: string;
+        title: string;
+        grantedAt: string;
+        expiresAt: string | null;
+        isActive: boolean;
+        orderId: string;
+    }>>>;
+}
+export {};
+//# sourceMappingURL=service.d.ts.map

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

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

package/dist/modules/fulfillment/service.js

@@ -0,0 +1,338 @@
+import { createHmac } from "node:crypto";
+import { resolveOrgId } from "../../auth/org.js";
+import { CommerceNotFoundError } from "../../kernel/errors.js";
+import { Err, Ok } from "../../kernel/result.js";
+import { makeId } from "../../utils/id.js";
+function toFulfillmentLineItem(lineItem) {
+    return {
+        id: lineItem.id,
+        title: lineItem.title,
+        quantity: lineItem.quantity,
+        ...(lineItem.sku != null ? { sku: lineItem.sku } : {}),
+    };
+}
+class PhysicalFulfillmentStrategy {
+    type = "physical";
+    async canFulfill(_lineItem, _context) {
+        return Ok(true);
+    }
+    async fulfill(lineItem, _context) {
+        return Ok({
+            id: makeId(),
+            orderId: lineItem.orderId,
+            type: this.type,
+            status: "pending",
+            lineItems: [toFulfillmentLineItem(lineItem)],
+        });
+    }
+    async reverse(_fulfillmentId, _context) {
+        return Ok(undefined);
+    }
+}
+class DigitalDownloadFulfillmentStrategy {
+    type = "digital-download";
+    async canFulfill(_lineItem, _context) {
+        return Ok(true);
+    }
+    async fulfill(lineItem, _context) {
+        const expiresAt = new Date(Date.now() + 1000 * 60 * 60 * 24).toISOString();
+        return Ok({
+            id: makeId(),
+            orderId: lineItem.orderId,
+            type: this.type,
+            status: "fulfilled",
+            downloadUrl: `https://downloads.local/${lineItem.id}?token=${createHmac("sha256", "download").update(lineItem.id).digest("hex")}`,
+            downloadExpiresAt: expiresAt,
+            maxDownloads: 5,
+            downloadCount: 0,
+            lineItems: [toFulfillmentLineItem(lineItem)],
+            entityType: "digitalDownload",
+            entityId: lineItem.entityId,
+            ...(lineItem.customerId !== undefined
+                ? { customerId: lineItem.customerId }
+                : {}),
+        });
+    }
+    async reverse(_fulfillmentId, _context) {
+        return Ok(undefined);
+    }
+}
+class DigitalAccessFulfillmentStrategy {
+    type = "digital-access";
+    async canFulfill(_lineItem, _context) {
+        return Ok(true);
+    }
+    async fulfill(lineItem, _context) {
+        return Ok({
+            id: makeId(),
+            orderId: lineItem.orderId,
+            type: this.type,
+            status: "fulfilled",
+            lineItems: [toFulfillmentLineItem(lineItem)],
+            entityType: "course",
+            entityId: lineItem.entityId,
+            ...(lineItem.customerId !== undefined
+                ? { customerId: lineItem.customerId }
+                : {}),
+            isActive: true,
+            grantedAt: new Date().toISOString(),
+        });
+    }
+    async reverse(_fulfillmentId, _context) {
+        return Ok(undefined);
+    }
+}
+class InternalTransferFulfillmentStrategy {
+    type = "internal-transfer";
+    async canFulfill(_lineItem, _context) {
+        return Ok(true);
+    }
+    async fulfill(lineItem, _context) {
+        return Ok({
+            id: makeId(),
+            orderId: lineItem.orderId,
+            type: this.type,
+            status: "processing",
+            lineItems: [toFulfillmentLineItem(lineItem)],
+        });
+    }
+    async reverse(_fulfillmentId, _context) {
+        return Ok(undefined);
+    }
+}
+class AppointmentFulfillmentStrategy {
+    type = "appointment";
+    async canFulfill(_lineItem, _context) {
+        return Ok(true);
+    }
+    async fulfill(lineItem, _context) {
+        return Ok({
+            id: makeId(),
+            orderId: lineItem.orderId,
+            type: this.type,
+            status: "pending",
+            lineItems: [toFulfillmentLineItem(lineItem)],
+        });
+    }
+    async reverse(_fulfillmentId, _context) {
+        return Ok(undefined);
+    }
+}
+export class FulfillmentService {
+    deps;
+    strategies = new Map();
+    constructor(deps) {
+        this.deps = deps;
+        this.strategies.set("physical", new PhysicalFulfillmentStrategy());
+        this.strategies.set("digital-download", new DigitalDownloadFulfillmentStrategy());
+        this.strategies.set("digital-access", new DigitalAccessFulfillmentStrategy());
+        this.strategies.set("internal-transfer", new InternalTransferFulfillmentStrategy());
+        this.strategies.set("appointment", new AppointmentFulfillmentStrategy());
+    }
+    async fulfillOrder(orderId, actor, ctx) {
+        const orgId = resolveOrgId(actor ?? ctx?.actor ?? null);
+        const order = await this.deps.ordersRepository.findById(orgId, orderId, ctx);
+        if (!order)
+            return Err(new CommerceNotFoundError("Order not found."));
+        const lineItems = await this.deps.ordersRepository.findLineItemsByOrderId(orderId, ctx);
+        for (const lineItem of lineItems) {
+            const strategyId = lineItem.entityType === "digitalDownload"
+                ? "digital-download"
+                : lineItem.entityType === "course"
+                    ? "digital-access"
+                    : lineItem.entityType === "internalAsset"
+                        ? "internal-transfer"
+                        : "physical";
+            const strategy = this.strategies.get(strategyId);
+            const result = await strategy.fulfill({
+                ...lineItem,
+                orderId,
+                ...(order.customerId != null ? { customerId: order.customerId } : {}),
+            }, {});
+            if (!result.ok)
+                return result;
+            const record = result.value;
+            // Persist the fulfillment record via repository
+            const created = await this.deps.repository.create({
+                id: record.id,
+                orderId: record.orderId,
+                type: record.type,
+                status: record.status,
+                carrier: record.carrier ?? null,
+                trackingNumber: record.trackingNumber ?? null,
+                trackingUrl: record.trackingUrl ?? null,
+                downloadUrl: record.downloadUrl ?? null,
+                downloadExpiresAt: record.downloadExpiresAt
+                    ? new Date(record.downloadExpiresAt)
+                    : null,
+                maxDownloads: record.maxDownloads ?? null,
+                downloadCount: record.downloadCount ?? 0,
+                entityType: record.entityType ?? null,
+                entityId: record.entityId ?? null,
+                grantedAt: record.grantedAt ? new Date(record.grantedAt) : null,
+                expiresAt: record.expiresAt ? new Date(record.expiresAt) : null,
+                isActive: record.isActive ?? true,
+                customerId: record.customerId ?? null,
+            }, ctx);
+            // Create a fulfillment line item linking this fulfillment to the order line item
+            for (const li of record.lineItems) {
+                await this.deps.repository.createLineItem({
+                    fulfillmentId: created.id,
+                    orderLineItemId: li.id,
+                    quantity: li.quantity,
+                }, ctx);
+            }
+        }
+        return Ok(undefined);
+    }
+    async getByOrderId(orderId, ctx) {
+        const dbRecords = await this.deps.repository.findByOrderId(orderId, ctx);
+        // Hydrate each record with its associated line items
+        const records = [];
+        for (const dbRecord of dbRecords) {
+            const fulfillmentLineItems = await this.deps.repository.findLineItemsByFulfillmentId(dbRecord.id, ctx);
+            records.push(toServiceRecord(dbRecord, fulfillmentLineItems));
+        }
+        return Ok(records);
+    }
+    async updateTracking(input, ctx) {
+        const existing = await this.deps.repository.findById(input.fulfillmentId, ctx);
+        if (!existing) {
+            return Err(new CommerceNotFoundError("Fulfillment record not found."));
+        }
+        const updateData = {};
+        if (input.carrier !== undefined)
+            updateData.carrier = input.carrier;
+        if (input.trackingNumber !== undefined)
+            updateData.trackingNumber = input.trackingNumber;
+        if (input.trackingUrl !== undefined)
+            updateData.trackingUrl = input.trackingUrl;
+        if (input.status !== undefined)
+            updateData.status = input.status;
+        if (input.status === "shipped")
+            updateData.shippedAt = new Date();
+        if (input.status === "delivered")
+            updateData.deliveredAt = new Date();
+        await this.deps.repository.update(input.fulfillmentId, updateData, ctx);
+        return Ok(undefined);
+    }
+    async getDownloadUrl(orderId, lineItemId, userId, actor, ctx) {
+        const dbRecords = await this.deps.repository.findByOrderId(orderId, ctx);
+        let matchedRecord;
+        for (const dbRecord of dbRecords) {
+            if (dbRecord.type !== "digital-download" && dbRecord.type !== "digital")
+                continue;
+            const fliItems = await this.deps.repository.findLineItemsByFulfillmentId(dbRecord.id, ctx);
+            if (fliItems.some((item) => item.orderLineItemId === lineItemId)) {
+                matchedRecord = dbRecord;
+                break;
+            }
+        }
+        if (!matchedRecord) {
+            return Err(new CommerceNotFoundError("Digital download not found."));
+        }
+        const orgId = resolveOrgId(actor ?? ctx?.actor ?? null);
+        const order = await this.deps.ordersRepository.findById(orgId, orderId, ctx);
+        if (!order || order.customerId !== userId) {
+            return Err(new CommerceNotFoundError("Order not found."));
+        }
+        if (!matchedRecord.downloadExpiresAt || !matchedRecord.downloadUrl) {
+            return Err(new CommerceNotFoundError("Download metadata missing."));
+        }
+        if (new Date(matchedRecord.downloadExpiresAt).getTime() < Date.now()) {
+            return Err(new CommerceNotFoundError("Download link expired."));
+        }
+        const updated = await this.deps.repository.incrementDownloadCount(matchedRecord.id, ctx);
+        const downloadCount = updated?.downloadCount ?? matchedRecord.downloadCount + 1;
+        const remaining = Math.max(0, (matchedRecord.maxDownloads ?? 5) - downloadCount);
+        return Ok({
+            url: matchedRecord.downloadUrl,
+            remaining,
+            expiresAt: matchedRecord.downloadExpiresAt.toISOString(),
+        });
+    }
+    async getDigitalAccess(userId, type = "course", ctx) {
+        const output = [];
+        // Find all fulfillments for this customer
+        const dbRecords = await this.deps.repository.findByCustomerId(userId, ctx);
+        for (const entry of dbRecords) {
+            if (entry.type !== "digital-access" && entry.type !== "access_grant")
+                continue;
+            if (entry.entityType !== type)
+                continue;
+            if (!entry.entityId || !entry.grantedAt)
+                continue;
+            // Get the first fulfillment line item to extract the title
+            const fliItems = await this.deps.repository.findLineItemsByFulfillmentId(entry.id, ctx);
+            let title = "Untitled";
+            if (fliItems.length > 0) {
+                const orderLineItem = await this.deps.ordersRepository.findLineItemById(fliItems[0].orderLineItemId, ctx);
+                if (orderLineItem) {
+                    title = orderLineItem.title;
+                }
+            }
+            output.push({
+                entityId: entry.entityId,
+                title,
+                grantedAt: entry.grantedAt.toISOString(),
+                expiresAt: entry.expiresAt?.toISOString() ?? null,
+                isActive: entry.isActive,
+                orderId: entry.orderId,
+            });
+        }
+        return Ok(output);
+    }
+}
+/**
+ * Maps a Drizzle FulfillmentRecord + its fulfillment line items back to
+ * the service-layer FulfillmentRecord shape used by callers.
+ */
+function toServiceRecord(dbRecord, fulfillmentLineItems) {
+    return {
+        id: dbRecord.id,
+        orderId: dbRecord.orderId,
+        type: dbRecord.type,
+        status: dbRecord.status,
+        lineItems: fulfillmentLineItems.map((fli) => ({
+            id: fli.orderLineItemId,
+            title: "", // Title is on the order line item; callers should join if needed
+            quantity: fli.quantity,
+        })),
+        ...(dbRecord.carrier != null ? { carrier: dbRecord.carrier } : {}),
+        ...(dbRecord.trackingNumber != null
+            ? { trackingNumber: dbRecord.trackingNumber }
+            : {}),
+        ...(dbRecord.trackingUrl != null
+            ? { trackingUrl: dbRecord.trackingUrl }
+            : {}),
+        ...(dbRecord.estimatedDelivery != null
+            ? { estimatedDelivery: dbRecord.estimatedDelivery.toISOString() }
+            : {}),
+        ...(dbRecord.shippedAt != null
+            ? { shippedAt: dbRecord.shippedAt.toISOString() }
+            : {}),
+        ...(dbRecord.deliveredAt != null
+            ? { deliveredAt: dbRecord.deliveredAt.toISOString() }
+            : {}),
+        ...(dbRecord.downloadUrl != null
+            ? { downloadUrl: dbRecord.downloadUrl }
+            : {}),
+        ...(dbRecord.downloadExpiresAt != null
+            ? { downloadExpiresAt: dbRecord.downloadExpiresAt.toISOString() }
+            : {}),
+        ...(dbRecord.maxDownloads != null
+            ? { maxDownloads: dbRecord.maxDownloads }
+            : {}),
+        downloadCount: dbRecord.downloadCount,
+        ...(dbRecord.customerId != null ? { customerId: dbRecord.customerId } : {}),
+        ...(dbRecord.entityType != null ? { entityType: dbRecord.entityType } : {}),
+        ...(dbRecord.entityId != null ? { entityId: dbRecord.entityId } : {}),
+        ...(dbRecord.grantedAt != null
+            ? { grantedAt: dbRecord.grantedAt.toISOString() }
+            : {}),
+        ...(dbRecord.expiresAt != null
+            ? { expiresAt: dbRecord.expiresAt.toISOString() }
+            : {}),
+        isActive: dbRecord.isActive,
+    };
+}

package/dist/modules/fulfillment/types.d.ts

@@ -0,0 +1,44 @@
+import type { Result } from "../../kernel/result.js";
+import type { OrderLineItem } from "../orders/repository/index.js";
+export interface FulfillmentRecord {
+    id: string;
+    orderId: string;
+    lineItems: Array<{
+        id: string;
+        title: string;
+        quantity: number;
+        sku?: string;
+    }>;
+    type: string;
+    status: string;
+    carrier?: string;
+    trackingNumber?: string;
+    trackingUrl?: string;
+    estimatedDelivery?: string;
+    shippedAt?: string;
+    deliveredAt?: string;
+    downloadUrl?: string;
+    downloadExpiresAt?: string;
+    maxDownloads?: number;
+    downloadCount?: number;
+    customerId?: string;
+    entityType?: string;
+    entityId?: string;
+    grantedAt?: string;
+    expiresAt?: string;
+    isActive?: boolean;
+}
+export interface FulfillmentStrategyContext {
+    actorId?: string;
+}
+export type FulfillmentLineItem = Pick<OrderLineItem, "id" | "entityId" | "entityType" | "sku" | "title" | "quantity"> & {
+    orderId: string;
+    customerId?: string;
+};
+export interface FulfillmentStrategy {
+    type: string;
+    canFulfill(lineItem: FulfillmentLineItem, context: FulfillmentStrategyContext): Promise<Result<boolean>>;
+    fulfill(lineItem: FulfillmentLineItem, context: FulfillmentStrategyContext): Promise<Result<FulfillmentRecord>>;
+    reverse(fulfillmentId: string, context: FulfillmentStrategyContext): Promise<Result<void>>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/modules/fulfillment/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/modules/fulfillment/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAEnE,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,KAAK,CAAC;QACf,EAAE,EAAE,MAAM,CAAC;QACX,KAAK,EAAE,MAAM,CAAC;QACd,QAAQ,EAAE,MAAM,CAAC;QACjB,GAAG,CAAC,EAAE,MAAM,CAAC;KACd,CAAC,CAAC;IACH,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,0BAA0B;IACzC,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,MAAM,mBAAmB,GAAG,IAAI,CACpC,aAAa,EACb,IAAI,GAAG,UAAU,GAAG,YAAY,GAAG,KAAK,GAAG,OAAO,GAAG,UAAU,CAChE,GAAG;IACF,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,CACR,QAAQ,EAAE,mBAAmB,EAC7B,OAAO,EAAE,0BAA0B,GAClC,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC;IAC5B,OAAO,CACL,QAAQ,EAAE,mBAAmB,EAC7B,OAAO,EAAE,0BAA0B,GAClC,OAAO,CAAC,MAAM,CAAC,iBAAiB,CAAC,CAAC,CAAC;IACtC,OAAO,CACL,aAAa,EAAE,MAAM,EACrB,OAAO,EAAE,0BAA0B,GAClC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;CAC1B"}

package/dist/modules/fulfillment/types.js

@@ -0,0 +1 @@
+export {};

package/dist/modules/inventory/repository/index.d.ts

@@ -0,0 +1,81 @@
+import type { TxContext } from "../../../kernel/database/tx-context.js";
+import type { DrizzleDatabase } from "../../../kernel/database/drizzle-db.js";
+import { warehouses, inventoryLevels, inventoryMovements } from "../schema.js";
+export type Warehouse = typeof warehouses.$inferSelect;
+export type WarehouseInsert = typeof warehouses.$inferInsert;
+export type InventoryLevel = typeof inventoryLevels.$inferSelect;
+export type InventoryLevelInsert = typeof inventoryLevels.$inferInsert;
+export type InventoryMovement = typeof inventoryMovements.$inferSelect;
+export type InventoryMovementInsert = typeof inventoryMovements.$inferInsert;
+/**
+ * InventoryRepository provides type-safe database operations for inventory entities.
+ *
+ * This repository manages warehouses, inventory levels, and inventory movements.
+ * All methods support an optional TxContext parameter for transaction participation.
+ */
+export declare class InventoryRepository {
+    private readonly db;
+    constructor(db: DrizzleDatabase);
+    private getDb;
+    findWarehouseById(id: string, ctx?: TxContext): Promise<Warehouse | undefined>;
+    findWarehouseByCode(orgId: string, code: string, ctx?: TxContext): Promise<Warehouse | undefined>;
+    findAllWarehouses(orgId: string, ctx?: TxContext): Promise<Warehouse[]>;
+    findActiveWarehouses(orgId: string, ctx?: TxContext): Promise<Warehouse[]>;
+    createWarehouse(data: WarehouseInsert, ctx?: TxContext): Promise<Warehouse>;
+    updateWarehouse(id: string, data: Partial<Omit<WarehouseInsert, "id">>, ctx?: TxContext): Promise<Warehouse | undefined>;
+    deleteWarehouse(id: string, ctx?: TxContext): Promise<boolean>;
+    findAllLevels(ctx?: TxContext): Promise<InventoryLevel[]>;
+    findLevelById(id: string, ctx?: TxContext): Promise<InventoryLevel | undefined>;
+    findLevelByKey(entityId: string, warehouseId: string, variantId?: string | null, ctx?: TxContext): Promise<InventoryLevel | undefined>;
+    findLevelsByEntityId(entityId: string, ctx?: TxContext): Promise<InventoryLevel[]>;
+    findLevelsByEntityAndVariant(entityId: string, variantId?: string | null, ctx?: TxContext): Promise<InventoryLevel[]>;
+    findLevelsByWarehouseId(warehouseId: string, ctx?: TxContext): Promise<InventoryLevel[]>;
+    createLevel(data: InventoryLevelInsert, ctx?: TxContext): Promise<InventoryLevel>;
+    updateLevel(id: string, data: Partial<Omit<InventoryLevelInsert, "id">>, ctx?: TxContext): Promise<InventoryLevel | undefined>;
+    upsertLevel(entityId: string, warehouseId: string, variantId: string | undefined, data: Omit<InventoryLevelInsert, "id" | "entityId" | "warehouseId" | "variantId">, ctx?: TxContext): Promise<InventoryLevel>;
+    deleteLevel(id: string, ctx?: TxContext): Promise<boolean>;
+    findMovementById(id: string, ctx?: TxContext): Promise<InventoryMovement | undefined>;
+    findMovementsByEntityId(entityId: string, ctx?: TxContext): Promise<InventoryMovement[]>;
+    findMovementsByReference(referenceType: string, referenceId: string, ctx?: TxContext): Promise<InventoryMovement[]>;
+    createMovement(data: InventoryMovementInsert, ctx?: TxContext): Promise<InventoryMovement>;
+    /**
+     * Issues SELECT ... FOR UPDATE on the inventory_levels row matching
+     * the given entity, variant, and warehouse within the provided transaction.
+     *
+     * MUST be called inside an active transaction (ctx.tx must be set).
+     * Calling outside a transaction provides no locking guarantee.
+     *
+     * Uses isNull() for null variantId instead of eq() to generate correct
+     * SQL (IS NULL instead of = NULL).
+     */
+    findLevelForUpdate(entityId: string, variantId: string | null, warehouseId: string, ctx: TxContext): Promise<InventoryLevel | undefined>;
+    /**
+     * Performs a read-modify-write under a row-level lock.
+     * This is the ONLY correct method for modifying quantityReserved
+     * in a concurrent environment. Must be called inside a transaction.
+     *
+     * The lock is held for the duration of the enclosing transaction,
+     * which is typically just the checkout reservation — microsecond-level.
+     */
+    reserveWithLock(entityId: string, variantId: string | null, warehouseId: string, quantity: number, ctx: TxContext): Promise<{
+        ok: true;
+        level: InventoryLevel;
+    } | {
+        ok: false;
+        reason: string;
+    }>;
+    /**
+     * Performs a release under a row-level lock, mirroring reserveWithLock.
+     * Used by compensation chains to undo a reservation.
+     */
+    releaseWithLock(entityId: string, variantId: string | null, warehouseId: string, quantity: number, ctx: TxContext): Promise<{
+        ok: true;
+        level: InventoryLevel;
+    } | {
+        ok: false;
+        reason: string;
+    }>;
+    getAvailableQuantity(entityId: string, variantId?: string | null, ctx?: TxContext): Promise<number>;
+    getAvailableQuantities(entityIds: string[], ctx?: TxContext): Promise<Record<string, number>>;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/modules/inventory/repository/index.d.ts.map

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