@porulle/core 0.1.0

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

@@ -0,0 +1,33 @@
+import { z } from "@hono/zod-openapi";
+export declare const CreatePromotionBodySchema: z.ZodObject<{
+    name: z.ZodString;
+    type: z.ZodEnum<{
+        percentage_off_order: "percentage_off_order";
+        fixed_off_order: "fixed_off_order";
+        percentage_off_item: "percentage_off_item";
+        fixed_off_item: "fixed_off_item";
+        free_shipping: "free_shipping";
+        buy_x_get_y: "buy_x_get_y";
+    }>;
+    value: z.ZodNumber;
+    code: z.ZodOptional<z.ZodString>;
+    buyQuantity: z.ZodOptional<z.ZodNumber>;
+    getQuantity: z.ZodOptional<z.ZodNumber>;
+    isAutomatic: z.ZodOptional<z.ZodBoolean>;
+    isActive: z.ZodOptional<z.ZodBoolean>;
+    priority: z.ZodOptional<z.ZodNumber>;
+    conditions: z.ZodOptional<z.ZodObject<{
+        minimumOrderValue: z.ZodOptional<z.ZodNumber>;
+        minimumQuantity: z.ZodOptional<z.ZodNumber>;
+        entityTypes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        categories: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        customerGroups: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+    usageLimitTotal: z.ZodOptional<z.ZodNumber>;
+    usageLimitPerCustomer: z.ZodOptional<z.ZodNumber>;
+    validFrom: z.ZodOptional<z.ZodCoercedDate<unknown>>;
+    validUntil: z.ZodOptional<z.ZodCoercedDate<unknown>>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+export type CreatePromotionInput = z.infer<typeof CreatePromotionBodySchema>;
+//# sourceMappingURL=schemas.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../../../src/modules/promotions/schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,mBAAmB,CAAC;AAItC,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA6BF,CAAC;AAIrC,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC"}

package/dist/modules/promotions/schemas.js

@@ -0,0 +1,32 @@
+import { z } from "@hono/zod-openapi";
+// ─── Zod Body Schemas (single source of truth) ─────────────────────────────
+export const CreatePromotionBodySchema = z.object({
+    name: z.string().openapi({ example: "Summer Sale" }),
+    type: z.enum([
+        "percentage_off_order",
+        "fixed_off_order",
+        "percentage_off_item",
+        "fixed_off_item",
+        "free_shipping",
+        "buy_x_get_y",
+    ]).openapi({ example: "percentage_off_order" }),
+    value: z.number().openapi({ example: 10 }),
+    code: z.string().optional().openapi({ example: "SUMMER10" }),
+    buyQuantity: z.number().int().optional(),
+    getQuantity: z.number().int().optional(),
+    isAutomatic: z.boolean().optional(),
+    isActive: z.boolean().optional(),
+    priority: z.number().int().optional(),
+    conditions: z.object({
+        minimumOrderValue: z.number().optional(),
+        minimumQuantity: z.number().int().optional(),
+        entityTypes: z.array(z.string()).optional(),
+        categories: z.array(z.string()).optional(),
+        customerGroups: z.array(z.string()).optional(),
+    }).optional(),
+    usageLimitTotal: z.number().int().optional(),
+    usageLimitPerCustomer: z.number().int().optional(),
+    validFrom: z.coerce.date().optional(),
+    validUntil: z.coerce.date().optional(),
+    metadata: z.record(z.string(), z.unknown()).optional(),
+}).openapi("CreatePromotionRequest");

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

@@ -0,0 +1,90 @@
+import type { DatabaseAdapter } from "../../kernel/database/adapter.js";
+import type { TxContext } from "../../kernel/database/tx-context.js";
+import type { HookRegistry } from "../../kernel/hooks/registry.js";
+import { type Result } from "../../kernel/result.js";
+import type { PromotionsRepository, Promotion, PromotionUsage } from "./repository/index.js";
+import type { CatalogRepository } from "../catalog/repository/index.js";
+import type { OrdersRepository } from "../orders/repository/index.js";
+import type { Actor } from "../../auth/types.js";
+export type PromotionType = "percentage_off_order" | "fixed_off_order" | "percentage_off_item" | "fixed_off_item" | "free_shipping" | "buy_x_get_y";
+/** Filter status for listing promotions. Used by the REST API and service layer. */
+export type PromotionStatusFilter = "active" | "inactive" | "expired" | "scheduled";
+interface PromotionServiceDeps {
+    repository: PromotionsRepository;
+    catalogRepository: CatalogRepository;
+    ordersRepository: OrdersRepository;
+    hooks: HookRegistry;
+    services: Record<string, unknown>;
+    database: DatabaseAdapter;
+}
+export interface PromotionLineItem {
+    entityId: string;
+    entityType: string;
+    quantity: number;
+    unitPrice: number;
+    totalPrice: number;
+}
+export interface PromotionEvaluationContext {
+    orgId?: string;
+    cartId?: string;
+    customerId?: string;
+    customerGroupIds?: string[];
+    currency: string;
+    subtotal: number;
+    lineItems: PromotionLineItem[];
+    promotionCodes?: string[];
+    timestamp?: Date;
+}
+export interface PromotionConditions {
+    minimumOrderValue?: number;
+    minimumQuantity?: number;
+    entityTypes?: string[];
+    categories?: string[];
+    customerGroups?: string[];
+    firstOrderOnly?: boolean;
+}
+export type { CreatePromotionInput } from "./schemas.js";
+import type { CreatePromotionInput } from "./schemas.js";
+export interface AppliedPromotion {
+    promotionId: string;
+    code?: string;
+    type: PromotionType;
+    discountAmount: number;
+    freeShipping: boolean;
+    description: string;
+}
+export interface PromotionApplicationResult {
+    totalDiscount: number;
+    freeShipping: boolean;
+    applied: AppliedPromotion[];
+    rejectedCodes: Array<{
+        code: string;
+        reason: string;
+    }>;
+}
+export declare class PromotionService {
+    private deps;
+    private readonly repo;
+    private readonly catalogRepo;
+    private readonly ordersRepo;
+    constructor(deps: PromotionServiceDeps);
+    create(input: CreatePromotionInput, actor?: Actor | null, ctx?: TxContext): Promise<Result<Promotion>>;
+    deactivate(orgId: string, id: string, ctx?: TxContext): Promise<Result<Promotion>>;
+    list(filter?: {
+        status?: PromotionStatusFilter;
+    }, actor?: Actor | null, ctx?: TxContext): Promise<Result<Promotion[]>>;
+    listActive(actor?: Actor | null, timestamp?: Date, ctx?: TxContext): Promise<Result<Promotion[]>>;
+    validate(code: string, context: PromotionEvaluationContext, ctx?: TxContext): Promise<Result<Promotion>>;
+    apply(code: string, context: PromotionEvaluationContext, ctx?: TxContext): Promise<Result<PromotionApplicationResult>>;
+    applyPromotions(context: PromotionEvaluationContext, ctx?: TxContext): Promise<Result<PromotionApplicationResult>>;
+    recordUsage(input: {
+        promotions: AppliedPromotion[];
+        customerId?: string;
+        orderId?: string;
+    }, ctx?: TxContext): Promise<Result<PromotionUsage[]>>;
+    private validatePromotionForContext;
+    private checkCategoryMatch;
+    private evaluatePromotion;
+    private filterEligibleLineItems;
+}
+//# sourceMappingURL=service.d.ts.map

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

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

package/dist/modules/promotions/service.js

@@ -0,0 +1,387 @@
+import { CommerceNotFoundError, CommerceValidationError, } 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 { resolveOrgId } from "../../auth/org.js";
+function hookContext(actor, services, database, tx) {
+    return createHookContext({
+        actor,
+        tx,
+        logger: createLogger("promotions"),
+        services,
+        context: { moduleName: "promotions" },
+        database: { db: database.db },
+    });
+}
+function matchesWindow(promotion, timestamp) {
+    if (!promotion.isActive)
+        return false;
+    if (promotion.validFrom && timestamp < promotion.validFrom)
+        return false;
+    if (promotion.validUntil && timestamp > promotion.validUntil)
+        return false;
+    return true;
+}
+function toConditions(raw) {
+    if (!raw)
+        return {};
+    const conditions = {};
+    if (typeof raw.minimumOrderValue === "number") {
+        conditions.minimumOrderValue = raw.minimumOrderValue;
+    }
+    if (typeof raw.minimumQuantity === "number") {
+        conditions.minimumQuantity = raw.minimumQuantity;
+    }
+    if (Array.isArray(raw.entityTypes)) {
+        conditions.entityTypes = raw.entityTypes.filter((item) => typeof item === "string");
+    }
+    if (Array.isArray(raw.categories)) {
+        conditions.categories = raw.categories.filter((item) => typeof item === "string");
+    }
+    if (Array.isArray(raw.customerGroups)) {
+        conditions.customerGroups = raw.customerGroups.filter((item) => typeof item === "string");
+    }
+    if (typeof raw.firstOrderOnly === "boolean") {
+        conditions.firstOrderOnly = raw.firstOrderOnly;
+    }
+    return conditions;
+}
+function roundMoney(amount) {
+    return Math.max(0, Math.round(amount));
+}
+function totalQuantity(items) {
+    return items.reduce((sum, item) => sum + item.quantity, 0);
+}
+function sortByPriority(promotions) {
+    return [...promotions].sort((a, b) => a.priority - b.priority);
+}
+export class PromotionService {
+    deps;
+    repo;
+    catalogRepo;
+    ordersRepo;
+    constructor(deps) {
+        this.deps = deps;
+        this.repo = deps.repository;
+        this.catalogRepo = deps.catalogRepository;
+        this.ordersRepo = deps.ordersRepository;
+    }
+    async create(input, actor, ctx) {
+        if (!input.name) {
+            return Err(new CommerceValidationError("Promotion name is required."));
+        }
+        if (input.value < 0) {
+            return Err(new CommerceValidationError("Promotion value cannot be negative."));
+        }
+        // Validate promotion type
+        const validTypes = [
+            "percentage_off_order",
+            "fixed_off_order",
+            "percentage_off_item",
+            "fixed_off_item",
+            "free_shipping",
+            "buy_x_get_y",
+        ];
+        if (!validTypes.includes(input.type)) {
+            return Err(new CommerceValidationError(`Invalid promotion type "${input.type}". Must be one of: ${validTypes.join(", ")}`));
+        }
+        const orgId = resolveOrgId(actor ?? ctx?.actor ?? null);
+        if (input.code) {
+            const normalized = input.code.trim().toUpperCase();
+            const existing = await this.repo.findByCode(orgId, normalized, ctx);
+            if (existing) {
+                return Err(new CommerceValidationError(`Promotion code ${normalized} already exists.`));
+            }
+        }
+        const promotion = await this.repo.create({
+            organizationId: orgId,
+            name: input.name,
+            type: input.type,
+            value: roundMoney(input.value),
+            isAutomatic: input.isAutomatic ?? false,
+            isActive: input.isActive ?? true,
+            priority: input.priority ?? 100,
+            conditions: (input.conditions ?? {}),
+            metadata: input.metadata ?? {},
+            code: input.code ? input.code.trim().toUpperCase() : null,
+            buyQuantity: input.buyQuantity ?? null,
+            getQuantity: input.getQuantity ?? null,
+            usageLimitTotal: input.usageLimitTotal ?? null,
+            usageLimitPerCustomer: input.usageLimitPerCustomer ?? null,
+            validFrom: input.validFrom ?? null,
+            validUntil: input.validUntil ?? null,
+        }, ctx);
+        const afterHooks = this.deps.hooks.resolve("promotions.afterCreate");
+        const hctx = hookContext(actor ?? ctx?.actor ?? null, this.deps.services, this.deps.database, ctx?.tx ?? null);
+        await runAfterHooks(afterHooks, null, promotion, "create", hctx);
+        return Ok(promotion);
+    }
+    async deactivate(orgId, id, ctx) {
+        const promotion = await this.repo.findById(orgId, id, ctx);
+        if (!promotion) {
+            return Err(new CommerceNotFoundError("Promotion not found."));
+        }
+        const updated = await this.repo.update(id, { isActive: false }, ctx);
+        if (!updated) {
+            return Err(new CommerceNotFoundError("Promotion not found."));
+        }
+        const afterHooks = this.deps.hooks.resolve("promotions.afterUpdate");
+        const hctx = hookContext(null, this.deps.services, this.deps.database, ctx?.tx ?? null);
+        await runAfterHooks(afterHooks, promotion, updated, "update", hctx);
+        return Ok(updated);
+    }
+    async list(filter, actor, ctx) {
+        const orgId = resolveOrgId(actor ?? ctx?.actor ?? null);
+        const all = await this.repo.findAll(orgId, ctx);
+        const now = new Date();
+        if (!filter?.status)
+            return Ok(sortByPriority(all));
+        const filtered = all.filter((p) => {
+            const isActive = p.isActive && matchesWindow(p, now);
+            const isExpired = p.isActive && p.validUntil && new Date(p.validUntil) < now;
+            const isScheduled = p.isActive && p.validFrom && new Date(p.validFrom) > now;
+            const isInactive = !p.isActive;
+            switch (filter.status) {
+                case "active": return isActive;
+                case "inactive": return isInactive;
+                case "expired": return isExpired;
+                case "scheduled": return isScheduled;
+                default: return true;
+            }
+        });
+        return Ok(sortByPriority(filtered));
+    }
+    async listActive(actor, timestamp = new Date(), ctx) {
+        const orgId = resolveOrgId(actor ?? ctx?.actor ?? null);
+        const active = await this.repo.findActive(orgId, ctx);
+        // Further filter by timestamp in case repo returns slightly stale results
+        const filtered = active.filter((p) => matchesWindow(p, timestamp));
+        return Ok(sortByPriority(filtered));
+    }
+    async validate(code, context, ctx) {
+        const normalized = code.trim().toUpperCase();
+        const evalOrgId = resolveOrgId(ctx?.actor ?? null, context.orgId);
+        const promotion = await this.repo.findByCode(evalOrgId, normalized, ctx);
+        if (!promotion) {
+            return Err(new CommerceNotFoundError(`Promotion code ${normalized} not found.`));
+        }
+        const validation = await this.validatePromotionForContext(promotion, context, context.timestamp ?? new Date(), ctx);
+        if (validation !== undefined) {
+            return Err(new CommerceValidationError(validation));
+        }
+        return Ok(promotion);
+    }
+    async apply(code, context, ctx) {
+        const validation = await this.validate(code, context, ctx);
+        if (!validation.ok)
+            return validation;
+        const evaluated = await this.evaluatePromotion(validation.value, context, ctx);
+        return Ok({
+            totalDiscount: evaluated.discountAmount,
+            freeShipping: evaluated.freeShipping,
+            applied: [evaluated],
+            rejectedCodes: [],
+        });
+    }
+    async applyPromotions(context, ctx) {
+        const timestamp = context.timestamp ?? new Date();
+        const applyOrgId = resolveOrgId(ctx?.actor ?? null, context.orgId);
+        const result = {
+            totalDiscount: 0,
+            freeShipping: false,
+            applied: [],
+            rejectedCodes: [],
+        };
+        const selectedPromotions = [];
+        // Process explicit promotion codes
+        const codeSet = new Set((context.promotionCodes ?? []).map((code) => code.trim().toUpperCase()));
+        if (codeSet.size > 0) {
+            for (const code of codeSet) {
+                const promotion = await this.repo.findByCode(applyOrgId, code, ctx);
+                if (!promotion) {
+                    result.rejectedCodes.push({ code, reason: "Code not found." });
+                    continue;
+                }
+                const reason = await this.validatePromotionForContext(promotion, context, timestamp, ctx);
+                if (reason !== undefined) {
+                    result.rejectedCodes.push({ code, reason });
+                    continue;
+                }
+                selectedPromotions.push(promotion);
+            }
+        }
+        // Process automatic promotions
+        const automaticPromotions = await this.repo.findAutomatic(applyOrgId, ctx);
+        for (const promotion of automaticPromotions) {
+            const reason = await this.validatePromotionForContext(promotion, context, timestamp, ctx);
+            if (reason !== undefined)
+                continue;
+            selectedPromotions.push(promotion);
+        }
+        for (const promotion of sortByPriority(selectedPromotions)) {
+            const evaluated = await this.evaluatePromotion(promotion, context, ctx);
+            if (evaluated.discountAmount <= 0 && !evaluated.freeShipping)
+                continue;
+            result.totalDiscount += evaluated.discountAmount;
+            result.freeShipping = result.freeShipping || evaluated.freeShipping;
+            result.applied.push(evaluated);
+        }
+        result.totalDiscount = Math.min(roundMoney(result.totalDiscount), roundMoney(context.subtotal));
+        return Ok(result);
+    }
+    async recordUsage(input, ctx) {
+        const usages = [];
+        for (const applied of input.promotions) {
+            const usage = await this.repo.createUsage({
+                promotionId: applied.promotionId,
+                customerId: input.customerId ?? null,
+                orderId: input.orderId ?? null,
+            }, ctx);
+            usages.push(usage);
+        }
+        return Ok(usages);
+    }
+    async validatePromotionForContext(promotion, context, timestamp, ctx) {
+        if (!matchesWindow(promotion, timestamp)) {
+            return "Promotion is inactive or outside validity window.";
+        }
+        const conditions = toConditions(promotion.conditions);
+        if (conditions.minimumOrderValue !== undefined &&
+            roundMoney(context.subtotal) < roundMoney(conditions.minimumOrderValue)) {
+            return `Requires minimum order value of ${conditions.minimumOrderValue}.`;
+        }
+        if (conditions.minimumQuantity !== undefined &&
+            totalQuantity(context.lineItems) < conditions.minimumQuantity) {
+            return `Requires minimum quantity of ${conditions.minimumQuantity}.`;
+        }
+        if (conditions.customerGroups && conditions.customerGroups.length > 0) {
+            const set = new Set(context.customerGroupIds ?? []);
+            const matchesGroup = conditions.customerGroups.some((group) => set.has(group));
+            if (!matchesGroup) {
+                return "Customer group not eligible for this promotion.";
+            }
+        }
+        if (conditions.entityTypes && conditions.entityTypes.length > 0) {
+            const hasType = context.lineItems.some((lineItem) => conditions.entityTypes.includes(lineItem.entityType));
+            if (!hasType)
+                return "Cart does not include required entity type.";
+        }
+        if (conditions.categories && conditions.categories.length > 0) {
+            const categoryMatches = await this.checkCategoryMatch(context.lineItems, conditions.categories, ctx);
+            if (!categoryMatches)
+                return "Cart does not include required category.";
+        }
+        if (conditions.firstOrderOnly) {
+            if (!context.customerId) {
+                return "First-order promotion requires authenticated customer.";
+            }
+            const orders = await this.ordersRepo.findByCustomerId(resolveOrgId(ctx?.actor ?? null, context.orgId), context.customerId, ctx);
+            if (orders.length > 0) {
+                return "Promotion is valid for first order only.";
+            }
+        }
+        // Check usage limits
+        const usageCount = await this.repo.countUsages(promotion.id, ctx);
+        if (promotion.usageLimitTotal !== null &&
+            usageCount >= promotion.usageLimitTotal) {
+            return "Promotion usage limit reached.";
+        }
+        if (promotion.usageLimitPerCustomer !== null && context.customerId) {
+            const customerUses = await this.repo.countUsagesByCustomer(promotion.id, context.customerId, ctx);
+            if (customerUses >= promotion.usageLimitPerCustomer) {
+                return "Promotion per-customer usage limit reached.";
+            }
+        }
+        return undefined;
+    }
+    async checkCategoryMatch(lineItems, categorySlugs, ctx) {
+        for (const lineItem of lineItems) {
+            const entityCategories = await this.catalogRepo.findEntityCategories(lineItem.entityId, ctx);
+            for (const link of entityCategories) {
+                const category = await this.catalogRepo.findCategoryById(link.categoryId, ctx);
+                if (category && categorySlugs.includes(category.slug)) {
+                    return true;
+                }
+            }
+        }
+        return false;
+    }
+    async evaluatePromotion(promotion, context, ctx) {
+        const conditions = toConditions(promotion.conditions);
+        const eligibleItems = await this.filterEligibleLineItems(context.lineItems, conditions, ctx);
+        const eligibleSubtotal = eligibleItems.reduce((sum, item) => sum + item.totalPrice, 0);
+        let discountAmount = 0;
+        let freeShipping = false;
+        switch (promotion.type) {
+            case "percentage_off_order":
+                discountAmount = Math.round((context.subtotal * promotion.value) / 100);
+                break;
+            case "fixed_off_order":
+                discountAmount = promotion.value;
+                break;
+            case "percentage_off_item":
+                discountAmount = Math.round((eligibleSubtotal * promotion.value) / 100);
+                break;
+            case "fixed_off_item": {
+                const totalUnits = eligibleItems.reduce((sum, item) => sum + item.quantity, 0);
+                discountAmount = totalUnits * promotion.value;
+                break;
+            }
+            case "free_shipping":
+                freeShipping = true;
+                break;
+            case "buy_x_get_y": {
+                const buy = promotion.buyQuantity ?? 0;
+                const get = promotion.getQuantity ?? 0;
+                const totalUnits = eligibleItems.reduce((sum, item) => sum + item.quantity, 0);
+                if (buy > 0 && get > 0 && totalUnits > 0) {
+                    const groups = Math.floor(totalUnits / (buy + get));
+                    const freeUnits = groups * get;
+                    const minUnitPrice = eligibleItems.length
+                        ? Math.min(...eligibleItems.map((item) => item.unitPrice))
+                        : 0;
+                    discountAmount = freeUnits * minUnitPrice;
+                }
+                break;
+            }
+            default:
+                discountAmount = 0;
+        }
+        return {
+            promotionId: promotion.id,
+            type: promotion.type,
+            discountAmount: roundMoney(discountAmount),
+            freeShipping,
+            description: promotion.code
+                ? `Promotion ${promotion.code}`
+                : `Promotion ${promotion.name}`,
+            ...(promotion.code !== null ? { code: promotion.code } : {}),
+        };
+    }
+    async filterEligibleLineItems(lineItems, conditions, ctx) {
+        const eligible = [];
+        for (const lineItem of lineItems) {
+            if (conditions.entityTypes && conditions.entityTypes.length > 0) {
+                if (!conditions.entityTypes.includes(lineItem.entityType))
+                    continue;
+            }
+            if (conditions.categories && conditions.categories.length > 0) {
+                const entityCats = await this.catalogRepo.findEntityCategories(lineItem.entityId, ctx);
+                const hasCategory = await (async () => {
+                    for (const link of entityCats) {
+                        const category = await this.catalogRepo.findCategoryById(link.categoryId, ctx);
+                        if (category && conditions.categories.includes(category.slug)) {
+                            return true;
+                        }
+                    }
+                    return false;
+                })();
+                if (!hasCategory)
+                    continue;
+            }
+            eligible.push(lineItem);
+        }
+        return eligible;
+    }
+}

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

@@ -0,0 +1,51 @@
+import type { Result } from "../../kernel/result.js";
+export interface SearchDocument {
+    id: string;
+    type: string;
+    slug: string;
+    title: string;
+    description?: string;
+    status?: string;
+    categories: string[];
+    brands: string[];
+    text: string;
+    payload?: Record<string, unknown>;
+}
+export interface SearchFilters {
+    type?: string;
+    category?: string;
+    brand?: string;
+    status?: string;
+}
+export interface SearchQueryParams {
+    query: string;
+    page?: number;
+    limit?: number;
+    filters?: SearchFilters;
+    facets?: string[];
+}
+export interface SearchSuggestParams {
+    prefix: string;
+    type?: string;
+    limit?: number;
+}
+export interface SearchHit {
+    id: string;
+    score?: number;
+    document: SearchDocument;
+}
+export interface SearchQueryResult {
+    hits: SearchHit[];
+    total: number;
+    page: number;
+    limit: number;
+    facets: Record<string, Record<string, number>>;
+}
+export interface SearchAdapter {
+    readonly providerId: string;
+    index(documents: SearchDocument[]): Promise<Result<void>>;
+    remove(ids: string[]): Promise<Result<void>>;
+    search(params: SearchQueryParams): Promise<Result<SearchQueryResult>>;
+    suggest(params: SearchSuggestParams): Promise<Result<string[]>>;
+}
+//# sourceMappingURL=adapter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../../src/modules/search/adapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAC;AAErD,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,aAAa,CAAC;IACxB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,cAAc,CAAC;CAC1B;AAED,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,SAAS,EAAE,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CAChD;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,KAAK,CAAC,SAAS,EAAE,cAAc,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;IAC1D,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;IAC7C,MAAM,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC,iBAAiB,CAAC,CAAC,CAAC;IACtE,OAAO,CAAC,MAAM,EAAE,mBAAmB,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;CACjE"}

package/dist/modules/search/adapter.js

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

package/dist/modules/search/hooks.d.ts

@@ -0,0 +1,8 @@
+import type { HookContext } from "../../kernel/hooks/types.js";
+export declare function syncToSearchIndex(args: {
+    result: {
+        id: string;
+    };
+    context: HookContext;
+}): Promise<void>;
+//# sourceMappingURL=hooks.d.ts.map

package/dist/modules/search/hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../../../src/modules/search/hooks.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAG/D,wBAAsB,iBAAiB,CAAC,IAAI,EAAE;IAC5C,MAAM,EAAE;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC;IACvB,OAAO,EAAE,WAAW,CAAC;CACtB,GAAG,OAAO,CAAC,IAAI,CAAC,CAKhB"}

package/dist/modules/search/hooks.js

@@ -0,0 +1,6 @@
+export async function syncToSearchIndex(args) {
+    const service = args.context.services.search;
+    if (!service)
+        return;
+    await service.syncEntity(args.result.id);
+}

package/dist/modules/search/module.d.ts

@@ -0,0 +1,8 @@
+import type { CatalogServiceImpl } from "../catalog/service.js";
+import { SearchService } from "./service.js";
+type SearchModuleDeps = {
+    catalog: CatalogServiceImpl;
+};
+export declare const searchModule: import("../../kernel/module/define.js").AppModule<Record<string, never>, SearchService, SearchModuleDeps>;
+export {};
+//# sourceMappingURL=module.d.ts.map

package/dist/modules/search/module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"module.d.ts","sourceRoot":"","sources":["../../../src/modules/search/module.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAChE,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAE7C,KAAK,gBAAgB,GAAG;IACtB,OAAO,EAAE,kBAAkB,CAAC;CAC7B,CAAC;AAEF,eAAO,MAAM,YAAY,2GAgBxB,CAAC"}

package/dist/modules/search/module.js

@@ -0,0 +1,17 @@
+import { defineModule } from "../../kernel/module/index.js";
+import { SearchService } from "./service.js";
+export const searchModule = defineModule({
+    id: "search",
+    dependencies: ["catalog"],
+    schema: () => ({}),
+    service: (deps) => {
+        const config = deps.config;
+        return new SearchService({
+            catalogRepository: deps.services.catalog.repository,
+            ...(config.search?.adapter ? { adapter: config.search.adapter } : {}),
+            ...(config.search?.defaultFacets
+                ? { defaultFacets: config.search.defaultFacets }
+                : {}),
+        });
+    },
+});