@unifiedcommerce/core 0.0.1

package/dist/modules/promotions/schema.js

@@ -0,0 +1,52 @@
+import { boolean, index, integer, jsonb, pgTable, text, timestamp, uniqueIndex, uuid } from "drizzle-orm/pg-core";
+import { organization } from "../../auth/auth-schema";
+export const promotions = pgTable("promotions", {
+    id: uuid("id").defaultRandom().primaryKey(),
+    organizationId: text("organization_id")
+        .notNull()
+        .references(() => organization.id, { onDelete: "cascade" }),
+    code: text("code"),
+    name: text("name").notNull(),
+    type: text("type", {
+        enum: [
+            "percentage_off_order",
+            "fixed_off_order",
+            "percentage_off_item",
+            "fixed_off_item",
+            "free_shipping",
+            "buy_x_get_y",
+        ],
+    }).notNull(),
+    value: integer("value").notNull().default(0),
+    buyQuantity: integer("buy_quantity"),
+    getQuantity: integer("get_quantity"),
+    isAutomatic: boolean("is_automatic").notNull().default(false),
+    isActive: boolean("is_active").notNull().default(true),
+    priority: integer("priority").notNull().default(100),
+    conditions: jsonb("conditions").$type().default({}),
+    usageLimitTotal: integer("usage_limit_total"),
+    usageLimitPerCustomer: integer("usage_limit_per_customer"),
+    validFrom: timestamp("valid_from", { withTimezone: true }),
+    validUntil: timestamp("valid_until", { withTimezone: true }),
+    metadata: jsonb("metadata").$type().default({}),
+    createdAt: timestamp("created_at", { withTimezone: true }).defaultNow().notNull(),
+    updatedAt: timestamp("updated_at", { withTimezone: true }).defaultNow().notNull(),
+}, (table) => ({
+    codeIdx: index("idx_promotions_code").on(table.code),
+    activePriorityIdx: index("idx_promotions_active_priority").on(table.isActive, table.priority),
+    validityIdx: index("idx_promotions_validity").on(table.validFrom, table.validUntil),
+    orgIdx: index("idx_promotions_org").on(table.organizationId),
+    orgCodeUnique: uniqueIndex("promotions_org_code_unique").on(table.organizationId, table.code),
+}));
+export const promotionUsages = pgTable("promotion_usages", {
+    id: uuid("id").defaultRandom().primaryKey(),
+    promotionId: uuid("promotion_id")
+        .references(() => promotions.id, { onDelete: "cascade" })
+        .notNull(),
+    customerId: uuid("customer_id"),
+    orderId: uuid("order_id"),
+    usedAt: timestamp("used_at", { withTimezone: true }).defaultNow().notNull(),
+}, (table) => ({
+    promotionIdx: index("idx_promotion_usage_promotion").on(table.promotionId),
+    customerIdx: index("idx_promotion_usage_customer").on(table.customerId),
+}));

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,80 @@
+import { type Result } from "../../kernel/result";
+import type { TxContext } from "../../kernel/database/tx-context";
+import type { PromotionsRepository, Promotion, PromotionUsage } from "./repository";
+import type { CatalogRepository } from "../catalog/repository";
+import type { OrdersRepository } from "../orders/repository";
+import type { Actor } from "../../auth/types";
+export type PromotionType = "percentage_off_order" | "fixed_off_order" | "percentage_off_item" | "fixed_off_item" | "free_shipping" | "buy_x_get_y";
+interface PromotionServiceDeps {
+    repository: PromotionsRepository;
+    catalogRepository: CatalogRepository;
+    ordersRepository: OrdersRepository;
+}
+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";
+import type { CreatePromotionInput } from "./schemas";
+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>>;
+    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,347 @@
+import { CommerceNotFoundError, CommerceValidationError, } from "../../kernel/errors";
+import { Err, Ok } from "../../kernel/result";
+import { DEFAULT_ORG_ID, resolveOrgId } from "../../auth/org";
+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);
+        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."));
+        }
+        return Ok(updated);
+    }
+    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 = context.orgId ?? DEFAULT_ORG_ID;
+        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 = context.orgId ?? DEFAULT_ORG_ID;
+        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(context.orgId ?? DEFAULT_ORG_ID, 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";
+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,qBAAqB,CAAC;AAElD,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";
+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,0BAA0B,CAAC;AAG5D,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/repository/index.d.ts

@@ -0,0 +1,5 @@
+import type { TxContext } from "../../../kernel/database/tx-context";
+export interface SearchRepository {
+    ping(ctx: TxContext): Promise<void>;
+}
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/modules/search/repository/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qCAAqC,CAAC;AAErE,MAAM,WAAW,gBAAgB;IAE/B,IAAI,CAAC,GAAG,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACrC"}

package/dist/modules/search/repository/index.js

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