@porulle/core 0.1.0

package/dist/modules/inventory/schemas.d.ts

@@ -0,0 +1,31 @@
+import { z } from "@hono/zod-openapi";
+export declare const InventoryAdjustBodySchema: z.ZodObject<{
+    entityId: z.ZodString;
+    variantId: z.ZodOptional<z.ZodString>;
+    warehouseId: z.ZodOptional<z.ZodString>;
+    adjustment: z.ZodNumber;
+    reason: z.ZodString;
+    performedBy: z.ZodOptional<z.ZodString>;
+    referenceType: z.ZodOptional<z.ZodString>;
+    referenceId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const InventoryReserveBodySchema: z.ZodObject<{
+    entityId: z.ZodString;
+    variantId: z.ZodOptional<z.ZodString>;
+    warehouseId: z.ZodOptional<z.ZodString>;
+    quantity: z.ZodNumber;
+    orderId: z.ZodString;
+    performedBy: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const InventoryReleaseBodySchema: z.ZodObject<{
+    entityId: z.ZodString;
+    variantId: z.ZodOptional<z.ZodString>;
+    warehouseId: z.ZodOptional<z.ZodString>;
+    quantity: z.ZodNumber;
+    orderId: z.ZodString;
+    performedBy: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type InventoryAdjustInput = z.infer<typeof InventoryAdjustBodySchema>;
+export type InventoryReserveInput = z.infer<typeof InventoryReserveBodySchema>;
+export type InventoryReleaseInput = z.infer<typeof InventoryReleaseBodySchema>;
+//# sourceMappingURL=schemas.d.ts.map

package/dist/modules/inventory/schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../../../src/modules/inventory/schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,mBAAmB,CAAC;AAItC,eAAO,MAAM,yBAAyB;;;;;;;;;iBASF,CAAC;AAErC,eAAO,MAAM,0BAA0B;;;;;;;iBAOF,CAAC;AAEtC,eAAO,MAAM,0BAA0B;;;;;;;iBAOF,CAAC;AAItC,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAC7E,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAC/E,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC"}

package/dist/modules/inventory/schemas.js

@@ -0,0 +1,28 @@
+import { z } from "@hono/zod-openapi";
+// ─── Zod Body Schemas (single source of truth) ─────────────────────────────
+export const InventoryAdjustBodySchema = z.object({
+    entityId: z.string().openapi({ example: "550e8400-e29b-41d4-a716-446655440000" }),
+    variantId: z.string().optional().openapi({ example: "variant-uuid" }),
+    warehouseId: z.string().optional().openapi({ example: "warehouse-uuid" }),
+    adjustment: z.number().int().refine((v) => v !== 0, { message: "Adjustment cannot be zero" }).openapi({ example: 10 }),
+    reason: z.string().openapi({ example: "Restock from supplier" }),
+    performedBy: z.string().optional(),
+    referenceType: z.string().optional(),
+    referenceId: z.string().optional(),
+}).openapi("InventoryAdjustRequest");
+export const InventoryReserveBodySchema = z.object({
+    entityId: z.string().openapi({ example: "550e8400-e29b-41d4-a716-446655440000" }),
+    variantId: z.string().optional(),
+    warehouseId: z.string().optional(),
+    quantity: z.number().int().min(1).openapi({ example: 2 }),
+    orderId: z.string().openapi({ example: "order-uuid" }),
+    performedBy: z.string().optional(),
+}).openapi("InventoryReserveRequest");
+export const InventoryReleaseBodySchema = z.object({
+    entityId: z.string().openapi({ example: "550e8400-e29b-41d4-a716-446655440000" }),
+    variantId: z.string().optional(),
+    warehouseId: z.string().optional(),
+    quantity: z.number().int().min(1).openapi({ example: 2 }),
+    orderId: z.string().openapi({ example: "order-uuid" }),
+    performedBy: z.string().optional(),
+}).openapi("InventoryReleaseRequest");

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

@@ -0,0 +1,70 @@
+import type { Actor } from "../../auth/types.js";
+import type { CommerceConfig } from "../../config/types.js";
+import type { HookRegistry } from "../../kernel/hooks/registry.js";
+import { type Result } from "../../kernel/result.js";
+import type { DatabaseAdapter } from "../../kernel/database/adapter.js";
+import { type TxContext } from "../../kernel/database/tx-context.js";
+import { InventoryRepository, type Warehouse, type InventoryLevel } from "./repository/index.js";
+export type { InventoryAdjustInput, InventoryReserveInput, InventoryReleaseInput } from "./schemas.js";
+import type { InventoryAdjustInput, InventoryReserveInput, InventoryReleaseInput } from "./schemas.js";
+export interface InventoryServiceDeps {
+    repository: InventoryRepository;
+    hooks: HookRegistry;
+    config: CommerceConfig;
+    services: Record<string, unknown>;
+    database: DatabaseAdapter;
+}
+export declare class InventoryService {
+    private deps;
+    private readonly repo;
+    constructor(deps: InventoryServiceDeps);
+    private withTransaction;
+    private pickWarehouse;
+    createWarehouse(input: Partial<Warehouse>, actor?: Actor | null, ctx?: TxContext): Promise<Result<Warehouse>>;
+    listWarehouses(actor?: Actor | null, ctx?: TxContext): Promise<Result<Warehouse[]>>;
+    getAvailable(entityId: string, variantId?: string, ctx?: TxContext, actor?: Actor | null): Promise<Result<number>>;
+    listLevels(params?: {
+        warehouseId?: string;
+        entityId?: string;
+    }, actor?: Actor | null, ctx?: TxContext): Promise<Result<InventoryLevel[]>>;
+    checkMultiple(entityIds: string[], actor?: Actor | null, ctx?: TxContext): Promise<Result<Record<string, number>>>;
+    getLevelsByEntityId(entityId: string, ctx?: TxContext, actor?: Actor | null): Promise<Result<InventoryLevel[]>>;
+    reserve(input: InventoryReserveInput, actor?: Actor | null, ctx?: TxContext): Promise<Result<void>>;
+    release(input: InventoryReleaseInput, actor?: Actor | null, ctx?: TxContext): Promise<Result<void>>;
+    adjust(input: InventoryAdjustInput, actor?: Actor | null, ctx?: TxContext): Promise<Result<InventoryLevel>>;
+    /**
+     * Set inventory to an absolute quantity (not a delta).
+     *
+     * Used by external store webhooks where the source system reports
+     * the current stock level (e.g., Shopify sends `{ available: 6 }`).
+     * Computes the delta internally so audit movements stay correct.
+     */
+    setAbsolute(input: {
+        entityId: string;
+        quantity: number;
+        warehouseId?: string;
+        variantId?: string;
+        reason?: string;
+    }, actor?: Actor | null, ctx?: TxContext): Promise<Result<InventoryLevel>>;
+    /**
+     * Deduct inventory on fulfillment (system-level, no permission check).
+     *
+     * Decrements quantityOnHand for fulfilled items. This is a system
+     * operation triggered by order status → fulfilled, not a manual
+     * stock adjustment. Creates a "fulfillment" type movement for audit.
+     *
+     * Net effect when paired with release():
+     *   Before: on_hand=100, reserved=5, available=95
+     *   After deduct+release: on_hand=95, reserved=0, available=95
+     */
+    deductForFulfillment(input: {
+        entityId: string;
+        variantId?: string;
+        warehouseId?: string;
+        quantity: number;
+        orderId: string;
+        orgId?: string;
+    }, ctx?: TxContext): Promise<Result<void>>;
+    setUnitCost(entityId: string, warehouseId: string, unitCost: number, variantId?: string, ctx?: TxContext): Promise<Result<InventoryLevel>>;
+}
+//# sourceMappingURL=service.d.ts.map

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

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

package/dist/modules/inventory/service.js

@@ -0,0 +1,284 @@
+import { resolveOrgId } from "../../auth/org.js";
+import { assertPermission } from "../../auth/permissions.js";
+import { CommerceNotFoundError, CommerceValidationError, toCommerceError, } from "../../kernel/errors.js";
+import { runAfterHooks } from "../../kernel/hooks/executor.js";
+import { createHookContext } from "../../kernel/hooks/create-context.js";
+import { Err, Ok } from "../../kernel/result.js";
+import { createLogger } from "../../utils/logger.js";
+import { createTxContext } from "../../kernel/database/tx-context.js";
+export class InventoryService {
+    deps;
+    repo;
+    constructor(deps) {
+        this.deps = deps;
+        this.repo = deps.repository;
+    }
+    async withTransaction(ctx, fn) {
+        if (ctx?.tx)
+            return fn(ctx.tx);
+        return this.deps.database.transaction(async (tx) => fn(tx));
+    }
+    async pickWarehouse(actor, ctx, orgIdOverride) {
+        const orgId = orgIdOverride ??
+            resolveOrgId(actor ?? ctx?.actor ?? null, undefined, this.deps.config);
+        const warehouses = await this.repo.findAllWarehouses(orgId, ctx);
+        const sorted = warehouses.sort((a, b) => a.priority - b.priority);
+        if (sorted.length > 0) {
+            return sorted[0].id;
+        }
+        // Create default warehouse if none exists
+        const defaultWarehouse = await this.repo.createWarehouse({
+            organizationId: orgId,
+            name: "Default Warehouse",
+            code: "DEFAULT",
+            isActive: true,
+            priority: 0,
+            metadata: {},
+        }, ctx);
+        return defaultWarehouse.id;
+    }
+    async createWarehouse(input, actor, ctx) {
+        if (!input.name || !input.code) {
+            return Err(new CommerceValidationError("Warehouse name and code are required."));
+        }
+        const orgId = resolveOrgId(actor ?? ctx?.actor ?? null, undefined, this.deps.config);
+        const warehouse = await this.repo.createWarehouse({
+            organizationId: orgId,
+            name: input.name,
+            code: input.code,
+            isActive: input.isActive ?? true,
+            priority: input.priority ?? 0,
+            metadata: input.metadata ?? {},
+            ...(input.address !== undefined ? { address: input.address } : {}),
+        }, ctx);
+        return Ok(warehouse);
+    }
+    async listWarehouses(actor, ctx) {
+        const orgId = resolveOrgId(actor ?? ctx?.actor ?? null, undefined, this.deps.config);
+        const warehouses = await this.repo.findAllWarehouses(orgId, ctx);
+        return Ok(warehouses.sort((a, b) => a.priority - b.priority));
+    }
+    async getAvailable(entityId, variantId, ctx, actor) {
+        const orgId = resolveOrgId(actor ?? ctx?.actor ?? null, undefined, this.deps.config);
+        const available = await this.repo.getAvailableQuantity(orgId, entityId, variantId, ctx);
+        return Ok(available);
+    }
+    async listLevels(params, actor, ctx) {
+        const orgId = resolveOrgId(actor ?? ctx?.actor ?? null, undefined, this.deps.config);
+        if (params?.entityId) {
+            const levels = await this.repo.findLevelsByEntityId(orgId, params.entityId, ctx);
+            return Ok(levels);
+        }
+        if (params?.warehouseId) {
+            const levels = await this.repo.findLevelsByWarehouseId(orgId, params.warehouseId, ctx);
+            return Ok(levels);
+        }
+        const levels = await this.repo.findAllLevels(orgId, ctx);
+        return Ok(levels);
+    }
+    async checkMultiple(entityIds, actor, ctx) {
+        const orgId = resolveOrgId(actor ?? ctx?.actor ?? null, undefined, this.deps.config);
+        const data = await this.repo.getAvailableQuantities(orgId, entityIds, ctx);
+        return Ok(data);
+    }
+    async getLevelsByEntityId(entityId, ctx, actor) {
+        const orgId = resolveOrgId(actor ?? ctx?.actor ?? null, undefined, this.deps.config);
+        const levels = await this.repo.findLevelsByEntityId(orgId, entityId, ctx);
+        return Ok(levels);
+    }
+    async reserve(input, actor, ctx) {
+        if (input.quantity <= 0) {
+            return Err(new CommerceValidationError("Reservation quantity must be greater than zero."));
+        }
+        const orgId = resolveOrgId(actor ?? ctx?.actor ?? null, undefined, this.deps.config);
+        const warehouseId = input.warehouseId ?? (await this.pickWarehouse(actor, ctx));
+        const performedBy = input.performedBy ?? actor?.userId ?? "system";
+        const variantId = input.variantId ?? null;
+        return this.withTransaction(ctx, async (tx) => {
+            const txCtx = ctx?.tx ? ctx : createTxContext(tx, { actor: actor ?? null });
+            const reserveResult = await this.repo.reserveWithLock(orgId, input.entityId, variantId, warehouseId, input.quantity, txCtx);
+            if (!reserveResult.ok) {
+                return Err(new CommerceValidationError(reserveResult.reason));
+            }
+            await this.repo.createMovement({
+                organizationId: orgId,
+                entityId: input.entityId,
+                warehouseId,
+                type: "reservation",
+                quantity: input.quantity,
+                performedBy,
+                referenceType: "order",
+                referenceId: input.orderId,
+                ...(input.variantId != null
+                    ? { variantId: input.variantId }
+                    : {}),
+            }, txCtx);
+            return Ok(undefined);
+        });
+    }
+    async release(input, actor, ctx) {
+        const orgId = resolveOrgId(actor ?? ctx?.actor ?? null, undefined, this.deps.config);
+        const warehouseId = input.warehouseId ?? (await this.pickWarehouse(actor, ctx));
+        const performedBy = input.performedBy ?? actor?.userId ?? "system";
+        const variantId = input.variantId ?? null;
+        const doRelease = async (txCtx) => {
+            const releaseResult = await this.repo.releaseWithLock(orgId, input.entityId, variantId, warehouseId, input.quantity, txCtx);
+            if (!releaseResult.ok) {
+                return Err(new CommerceValidationError(releaseResult.reason));
+            }
+            await this.repo.createMovement({
+                organizationId: orgId,
+                entityId: input.entityId,
+                warehouseId,
+                type: "release",
+                quantity: input.quantity,
+                performedBy,
+                referenceType: "order",
+                referenceId: input.orderId,
+                ...(input.variantId != null
+                    ? { variantId: input.variantId }
+                    : {}),
+            }, txCtx);
+            return Ok(undefined);
+        };
+        return this.withTransaction(ctx, async (tx) => {
+            const txCtx = ctx?.tx ? ctx : createTxContext(tx, { actor: actor ?? null });
+            return doRelease(txCtx);
+        });
+    }
+    async adjust(input, actor, ctx) {
+        try {
+            assertPermission(actor ?? null, "inventory:adjust");
+        }
+        catch (error) {
+            return Err(toCommerceError(error));
+        }
+        const warehouseId = input.warehouseId ?? (await this.pickWarehouse(actor, ctx));
+        const variantId = input.variantId ?? null;
+        const performedBy = input.performedBy ?? actor?.userId ?? "system";
+        const doAdjust = async (txCtx) => {
+            const orgId = resolveOrgId(actor ?? txCtx.actor ?? null, undefined, this.deps.config);
+            // Row-locked read + atomic SQL increment prevents lost updates
+            const lockResult = await this.repo.adjustWithLock(orgId, input.entityId, variantId, warehouseId, input.adjustment, txCtx);
+            let level;
+            if (lockResult.ok) {
+                level = lockResult.level;
+            }
+            else {
+                // No existing level — create is safe; unique index on
+                // (entityId, variantId, warehouseId) prevents duplicate inserts.
+                level = await this.repo.createLevel({
+                    organizationId: orgId,
+                    entityId: input.entityId,
+                    warehouseId,
+                    quantityOnHand: Math.max(0, input.adjustment),
+                    quantityReserved: 0,
+                    quantityIncoming: 0,
+                    ...(input.variantId !== undefined
+                        ? { variantId: input.variantId }
+                        : {}),
+                }, txCtx);
+            }
+            await this.repo.createMovement({
+                organizationId: orgId,
+                entityId: input.entityId,
+                warehouseId,
+                type: "adjustment",
+                quantity: input.adjustment,
+                reason: input.reason,
+                performedBy,
+                ...(input.variantId !== undefined
+                    ? { variantId: input.variantId }
+                    : {}),
+                ...(input.referenceType !== undefined
+                    ? { referenceType: input.referenceType }
+                    : {}),
+                ...(input.referenceId !== undefined
+                    ? { referenceId: input.referenceId }
+                    : {}),
+            }, txCtx);
+            const hookCtx = createHookContext({
+                actor: actor ?? null,
+                tx: txCtx.tx,
+                logger: createLogger("inventory.adjust"),
+                services: this.deps.services,
+                context: { moduleName: "inventory" },
+                database: { db: this.deps.database.db },
+            });
+            const afterHooks = this.deps.hooks.resolve("inventory.afterAdjust");
+            await runAfterHooks(afterHooks, null, level, "update", hookCtx);
+            return Ok(level);
+        };
+        return this.withTransaction(ctx, async (tx) => {
+            const txCtx = ctx?.tx ? ctx : createTxContext(tx, { actor: actor ?? null });
+            return doAdjust(txCtx);
+        });
+    }
+    /**
+     * Set inventory to an absolute quantity (not a delta).
+     *
+     * Used by external store webhooks where the source system reports
+     * the current stock level (e.g., Shopify sends `{ available: 6 }`).
+     * Computes the delta internally so audit movements stay correct.
+     */
+    async setAbsolute(input, actor, ctx) {
+        const warehouseId = input.warehouseId ?? (await this.pickWarehouse(actor, ctx));
+        const orgId = resolveOrgId(actor ?? ctx?.actor ?? null, undefined, this.deps.config);
+        const existingLevel = await this.repo.findLevelByKey(orgId, input.entityId, warehouseId, input.variantId, ctx);
+        const currentOnHand = existingLevel?.quantityOnHand ?? 0;
+        const delta = input.quantity - currentOnHand;
+        // Delegate to adjust() so hooks, movements, and permission checks are consistent
+        return this.adjust({
+            entityId: input.entityId,
+            warehouseId,
+            adjustment: delta,
+            reason: input.reason ?? "External store absolute inventory sync",
+            ...(input.variantId !== undefined ? { variantId: input.variantId } : {}),
+        }, actor, ctx);
+    }
+    /**
+     * Deduct inventory on fulfillment (system-level, no permission check).
+     *
+     * Decrements quantityOnHand for fulfilled items. This is a system
+     * operation triggered by order status → fulfilled, not a manual
+     * stock adjustment. Creates a "fulfillment" type movement for audit.
+     *
+     * Net effect when paired with release():
+     *   Before: on_hand=100, reserved=5, available=95
+     *   After deduct+release: on_hand=95, reserved=0, available=95
+     */
+    async deductForFulfillment(input, ctx) {
+        const orgId = input.orgId ??
+            resolveOrgId(ctx?.actor ?? null, undefined, this.deps.config);
+        const warehouseId = input.warehouseId ?? (await this.pickWarehouse(null, ctx, orgId));
+        const variantId = input.variantId ?? null;
+        const level = await this.repo.findLevelByKey(orgId, input.entityId, warehouseId, variantId != null ? variantId : undefined, ctx);
+        if (!level) {
+            // No inventory record — nothing to deduct
+            return Ok(undefined);
+        }
+        const newOnHand = Math.max(0, level.quantityOnHand - input.quantity);
+        await this.repo.updateLevel(orgId, level.id, { quantityOnHand: newOnHand }, ctx);
+        await this.repo.createMovement({
+            organizationId: orgId,
+            entityId: input.entityId,
+            warehouseId,
+            type: "fulfillment",
+            quantity: -input.quantity,
+            performedBy: "system",
+            referenceType: "order",
+            referenceId: input.orderId,
+            ...(variantId != null ? { variantId } : {}),
+        }, ctx);
+        return Ok(undefined);
+    }
+    async setUnitCost(entityId, warehouseId, unitCost, variantId, ctx) {
+        const orgId = resolveOrgId(ctx?.actor ?? null, undefined, this.deps.config);
+        const level = await this.repo.findLevelByKey(orgId, entityId, warehouseId, variantId, ctx);
+        if (!level) {
+            return Err(new CommerceNotFoundError(`Inventory level not found for entity ${entityId} at warehouse ${warehouseId}.`));
+        }
+        const updated = await this.repo.updateLevel(orgId, level.id, { unitCost }, ctx);
+        return Ok(updated);
+    }
+}

package/dist/modules/media/adapter.d.ts

@@ -0,0 +1,16 @@
+import type { Result } from "../../kernel/result.js";
+export interface StoredFile {
+    key: string;
+    url: string;
+    contentType: string;
+    size?: number;
+}
+export interface StorageAdapter {
+    readonly providerId: string;
+    upload(key: string, data: ArrayBuffer | ReadableStream, contentType: string): Promise<Result<StoredFile>>;
+    getUrl(key: string): Promise<Result<string>>;
+    getSignedUrl(key: string, expiresIn: number): Promise<Result<string>>;
+    delete(key: string): Promise<Result<void>>;
+    list(prefix: string): Promise<Result<StoredFile[]>>;
+}
+//# sourceMappingURL=adapter.d.ts.map

package/dist/modules/media/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../../src/modules/media/adapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAC;AAErD,MAAM,WAAW,UAAU;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,GAAG,cAAc,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC;IAC1G,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;IAC7C,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;IACtE,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;IAC3C,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC;CACrD"}

package/dist/modules/media/adapter.js

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

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

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

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

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

package/dist/modules/media/index.js

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