@porulle/core 0.1.0

package/src/modules/search/adapter.ts

@@ -0,0 +1,57 @@
+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[]>>;
+}

package/src/modules/search/hooks.ts

@@ -0,0 +1,12 @@
+import type { HookContext } from "../../kernel/hooks/types.js";
+import type { SearchService } from "./service.js";
+
+export async function syncToSearchIndex(args: {
+  result: { id: string };
+  context: HookContext;
+}): Promise<void> {
+  const service = args.context.services.search as SearchService | undefined;
+  if (!service) return;
+
+  await service.syncEntity(args.result.id);
+}

package/src/modules/search/module.ts

@@ -0,0 +1,26 @@
+import type { CommerceConfig } from "../../config/types.js";
+import { defineModule } from "../../kernel/module/index.js";
+import type { CatalogServiceImpl } from "../catalog/service.js";
+import { SearchService } from "./service.js";
+
+type SearchModuleDeps = {
+  catalog: CatalogServiceImpl;
+};
+
+export const searchModule = defineModule<Record<string, never>, SearchService, SearchModuleDeps>(
+  {
+    id: "search",
+    dependencies: ["catalog"],
+    schema: () => ({}),
+    service: (deps) => {
+      const config = deps.config as CommerceConfig;
+      return new SearchService({
+        catalogRepository: deps.services.catalog.repository,
+        ...(config.search?.adapter ? { adapter: config.search.adapter } : {}),
+        ...(config.search?.defaultFacets
+          ? { defaultFacets: config.search.defaultFacets }
+          : {}),
+      });
+    },
+  },
+);

package/src/modules/search/repository/index.ts

@@ -0,0 +1,6 @@
+import type { TxContext } from "../../../kernel/database/tx-context.js";
+
+export interface SearchRepository {
+  // RFC-002 scaffold: module repositories become the only persistence boundary.
+  ping(ctx: TxContext): Promise<void>;
+}

package/src/modules/search/service.ts

@@ -0,0 +1,341 @@
+import { Ok, type Result } from "../../kernel/result.js";
+import { resolveOrgId } from "../../auth/org.js";
+import type { TxContext } from "../../kernel/database/tx-context.js";
+import type { CatalogRepository, SellableEntity } from "../catalog/repository/index.js";
+import type {
+  SearchAdapter,
+  SearchDocument,
+  SearchFilters,
+  SearchQueryParams,
+  SearchQueryResult,
+  SearchSuggestParams,
+} from "./adapter.js";
+
+interface SearchServiceDeps {
+  catalogRepository: CatalogRepository;
+  adapter?: SearchAdapter;
+  defaultFacets?: string[];
+}
+
+function unique(values: string[]): string[] {
+  return [...new Set(values)];
+}
+
+function clamp(value: number, min: number, max: number): number {
+  return Math.max(min, Math.min(max, value));
+}
+
+function tokenize(query: string): string[] {
+  return query
+    .toLowerCase()
+    .split(/\s+/)
+    .map((part) => part.trim())
+    .filter(Boolean);
+}
+
+function includesAllTokens(haystack: string, tokens: string[]): boolean {
+  if (tokens.length === 0) return true;
+  const lower = haystack.toLowerCase();
+  return tokens.every((token) => lower.includes(token));
+}
+
+function scoreText(document: SearchDocument, tokens: string[]): number {
+  if (tokens.length === 0) return 1;
+
+  const title = document.title.toLowerCase();
+  const text = document.text.toLowerCase();
+
+  let score = 0;
+  for (const token of tokens) {
+    if (title.includes(token)) score += 2;
+    if (text.includes(token)) score += 1;
+  }
+
+  return score;
+}
+
+export class SearchService {
+  constructor(private deps: SearchServiceDeps) {}
+
+  private async entityCategories(
+    entityId: string,
+    ctx?: TxContext,
+  ): Promise<string[]> {
+    const entries = await this.deps.catalogRepository.findEntityCategories(
+      entityId,
+      ctx,
+    );
+
+    const slugs = (
+      await Promise.all(
+        entries.map(async (entry) => {
+          const category = await this.deps.catalogRepository.findCategoryById(
+            entry.categoryId,
+            ctx,
+          );
+          return category?.slug;
+        }),
+      )
+    ).filter((slug): slug is string => typeof slug === "string");
+
+    return unique(slugs);
+  }
+
+  private async entityBrands(
+    entityId: string,
+    ctx?: TxContext,
+  ): Promise<string[]> {
+    const entries = await this.deps.catalogRepository.findEntityBrands(
+      entityId,
+      ctx,
+    );
+
+    const slugs = (
+      await Promise.all(
+        entries.map(async (entry) => {
+          const brand = await this.deps.catalogRepository.findBrandById(
+            entry.brandId,
+            ctx,
+          );
+          return brand?.slug;
+        }),
+      )
+    ).filter((slug): slug is string => typeof slug === "string");
+
+    return unique(slugs);
+  }
+
+  private async buildDocument(
+    entity: SellableEntity,
+    ctx?: TxContext,
+  ): Promise<SearchDocument> {
+    const attributes =
+      await this.deps.catalogRepository.findAttributesByEntityId(
+        entity.id,
+        ctx,
+      );
+    const primary = attributes[0];
+    const title = primary?.title ?? entity.slug;
+    const description = primary?.description;
+    const categories = await this.entityCategories(entity.id, ctx);
+    const brands = await this.entityBrands(entity.id, ctx);
+
+    const textParts: string[] = [
+      entity.slug,
+      title,
+      description ?? "",
+      ...categories,
+      ...brands,
+      ...attributes.map((attr) => attr.title),
+      ...attributes.map((attr) => attr.description ?? ""),
+    ];
+
+    return {
+      id: entity.id,
+      type: entity.type,
+      slug: entity.slug,
+      title,
+      ...(description ? { description } : {}),
+      status: entity.status,
+      categories,
+      brands,
+      text: textParts.join(" ").trim(),
+      payload: {
+        metadata: entity.metadata ?? undefined,
+      },
+    };
+  }
+
+  private async allDocuments(ctx?: TxContext): Promise<SearchDocument[]> {
+    const orgId = resolveOrgId(ctx?.actor ?? null);
+    const entities = await this.deps.catalogRepository.findEntities(
+      orgId,
+      undefined,
+      ctx,
+    );
+    return Promise.all(
+      entities.map((entity) => this.buildDocument(entity, ctx)),
+    );
+  }
+
+  private matchesFilters(
+    document: SearchDocument,
+    filters: SearchFilters | undefined,
+  ): boolean {
+    if (!filters) return true;
+    if (filters.type && document.type !== filters.type) return false;
+    if (filters.status && document.status !== filters.status) return false;
+    if (filters.category && !document.categories.includes(filters.category))
+      return false;
+    if (filters.brand && !document.brands.includes(filters.brand)) return false;
+    return true;
+  }
+
+  private computeFacets(
+    documents: SearchDocument[],
+    requested?: string[],
+  ): Record<string, Record<string, number>> {
+    const facets =
+      requested && requested.length > 0
+        ? requested
+        : (this.deps.defaultFacets ?? ["type", "category", "brand", "status"]);
+    const output: Record<string, Record<string, number>> = {};
+
+    for (const facet of facets) {
+      if (facet === "type") {
+        output.type = {};
+        for (const document of documents) {
+          output.type[document.type] = (output.type[document.type] ?? 0) + 1;
+        }
+      }
+
+      if (facet === "status") {
+        output.status = {};
+        for (const document of documents) {
+          const status = document.status ?? "unknown";
+          output.status[status] = (output.status[status] ?? 0) + 1;
+        }
+      }
+
+      if (facet === "category" || facet === "categories") {
+        output.category = {};
+        for (const document of documents) {
+          for (const category of document.categories) {
+            output.category[category] = (output.category[category] ?? 0) + 1;
+          }
+        }
+      }
+
+      if (facet === "brand" || facet === "brands") {
+        output.brand = {};
+        for (const document of documents) {
+          for (const brand of document.brands) {
+            output.brand[brand] = (output.brand[brand] ?? 0) + 1;
+          }
+        }
+      }
+    }
+
+    return output;
+  }
+
+  async syncEntity(entityId: string, ctx?: TxContext): Promise<Result<void>> {
+    if (!this.deps.adapter) return Ok(undefined);
+
+    const entity = await this.deps.catalogRepository.findEntityById(
+      entityId,
+      ctx,
+    );
+    if (!entity) {
+      return this.deps.adapter.remove([entityId]);
+    }
+
+    return this.deps.adapter.index([await this.buildDocument(entity, ctx)]);
+  }
+
+  async query(
+    params: SearchQueryParams,
+    ctx?: TxContext,
+  ): Promise<Result<SearchQueryResult>> {
+    const page = clamp(params.page ?? 1, 1, 100000);
+    const limit = clamp(params.limit ?? 20, 1, 100);
+
+    // Cap query length to prevent abuse / excessive processing
+    const safeQuery = (params.query ?? "").slice(0, 500);
+
+    if (this.deps.adapter) {
+      return this.deps.adapter.search({
+        ...params,
+        query: safeQuery,
+        page,
+        limit,
+      });
+    }
+
+    // In-memory fallback: require a non-empty query to avoid loading all entities
+    // (allDocuments triggers N+1 DB queries per entity — unsafe at scale)
+    const tokens = tokenize(safeQuery);
+    if (tokens.length === 0 && !params.filters?.type && !params.filters?.category && !params.filters?.brand && !params.filters?.status) {
+      return Ok({ hits: [], total: 0, page, limit, facets: {} });
+    }
+
+    try {
+      const allDocs = await this.allDocuments(ctx);
+      const filtered = allDocs.filter((document) => {
+        if (!this.matchesFilters(document, params.filters)) return false;
+        if (tokens.length === 0) return true;
+        return includesAllTokens(document.text, tokens);
+      });
+
+      const scored = filtered
+        .map((document) => ({
+          document,
+          score: scoreText(document, tokens),
+        }))
+        .sort((first, second) => {
+          if (second.score !== first.score) return second.score - first.score;
+          return first.document.title.localeCompare(second.document.title);
+        });
+
+      const offset = (page - 1) * limit;
+      const hits = scored.slice(offset, offset + limit).map((row) => ({
+        id: row.document.id,
+        score: row.score,
+        document: row.document,
+      }));
+
+      return Ok({
+        hits,
+        total: scored.length,
+        page,
+        limit,
+        facets: this.computeFacets(filtered, params.facets),
+      });
+    } catch (error) {
+      // In-memory search is best-effort; surface error as empty result
+      // rather than crashing the entire request with a 500
+      console.error("[search] In-memory fallback failed:", error instanceof Error ? error.message : error);
+      return Ok({ hits: [], total: 0, page, limit, facets: {} });
+    }
+  }
+
+  async suggest(
+    params: SearchSuggestParams,
+    ctx?: TxContext,
+  ): Promise<Result<string[]>> {
+    const limit = clamp(params.limit ?? 10, 1, 25);
+    const prefix = (params.prefix ?? "").trim().toLowerCase().slice(0, 200);
+
+    if (prefix.length === 0) return Ok([]);
+
+    if (this.deps.adapter) {
+      return this.deps.adapter.suggest({
+        ...params,
+        prefix,
+        limit,
+      });
+    }
+
+    // In-memory fallback: require prefix >= 2 chars to avoid loading all entities
+    // (allDocuments triggers N+1 DB queries per entity — unsafe at scale)
+    if (prefix.length < 2) return Ok([]);
+
+    try {
+      const allDocs = await this.allDocuments(ctx);
+      const titles = allDocs
+        .filter(
+          (document) =>
+            (!params.type || document.type === params.type) &&
+            document.title.toLowerCase().startsWith(prefix),
+        )
+        .map((document) => document.title)
+        .filter((title, index, list) => list.indexOf(title) === index)
+        .slice(0, limit);
+
+      return Ok(titles);
+    } catch (error) {
+      console.error("[search] Suggest fallback failed:", error instanceof Error ? error.message : error);
+      return Ok([]);
+    }
+  }
+}

package/src/modules/shipping/calculator.ts

@@ -0,0 +1,188 @@
+import type { CommerceConfig } from "../../config/types.js";
+import type { TxContext } from "../../kernel/database/tx-context.js";
+import type { CatalogRepository } from "../catalog/repository/index.js";
+
+export interface ShippingAddress {
+  country: string;
+  postalCode: string;
+  state?: string;
+  city?: string;
+  line1?: string;
+}
+
+export interface ShippingLineItem {
+  entityId: string;
+  variantId?: string;
+  quantity: number;
+  resolvedTotal: number;
+}
+
+export type ShippingStrategy =
+  | {
+      type: "flat";
+      flatRate: number;
+      freeShippingThreshold?: number;
+    }
+  | {
+      type: "weight_based";
+      brackets: Array<{ upToGrams: number; cost: number }>;
+      fallbackCost: number;
+      freeShippingThreshold?: number;
+    };
+
+export interface ShippingCalculationInput {
+  lineItems: ShippingLineItem[];
+  subtotalAfterDiscount: number;
+  currency: string;
+  address?: ShippingAddress;
+  isFreeShipping: boolean;
+}
+
+async function resolveWeightGrams(
+  catalogRepo: CatalogRepository,
+  entityId: string,
+  variantId: string | undefined,
+  ctx?: TxContext,
+): Promise<number> {
+  if (variantId !== undefined) {
+    const variant = await catalogRepo.findVariantById(variantId, ctx);
+    const weightFromVariant = (
+      variant?.metadata as Record<string, unknown> | null
+    )?.weightGrams;
+    if (
+      typeof weightFromVariant === "number" &&
+      Number.isFinite(weightFromVariant)
+    ) {
+      return Math.max(0, Math.round(weightFromVariant));
+    }
+  }
+
+  const entity = await catalogRepo.findEntityById(entityId, ctx);
+  const weightFromEntity = (entity?.metadata as Record<string, unknown> | null)
+    ?.weightGrams;
+  if (
+    typeof weightFromEntity === "number" &&
+    Number.isFinite(weightFromEntity)
+  ) {
+    return Math.max(0, Math.round(weightFromEntity));
+  }
+
+  return 0;
+}
+
+async function isShippableEntity(
+  config: CommerceConfig,
+  catalogRepo: CatalogRepository,
+  entityId: string,
+  ctx?: TxContext,
+): Promise<boolean> {
+  const entity = await catalogRepo.findEntityById(entityId, ctx);
+  if (!entity) return false;
+  const fulfillment = config.entities?.[entity.type]?.fulfillment;
+  return (
+    fulfillment === "physical" ||
+    fulfillment === "internal-transfer" ||
+    fulfillment === undefined
+  );
+}
+
+function resolveStrategy(config: CommerceConfig): ShippingStrategy {
+  const shipping = config.shipping;
+  if (!shipping) {
+    return {
+      type: "flat",
+      flatRate: 0,
+    };
+  }
+
+  if (shipping.type === "weight_based") {
+    return {
+      type: "weight_based",
+      brackets: [...shipping.brackets].sort(
+        (a, b) => a.upToGrams - b.upToGrams,
+      ),
+      fallbackCost: shipping.fallbackCost,
+      ...(shipping.freeShippingThreshold !== undefined
+        ? { freeShippingThreshold: shipping.freeShippingThreshold }
+        : {}),
+    };
+  }
+
+  return {
+    type: "flat",
+    flatRate: shipping.flatRate,
+    ...(shipping.freeShippingThreshold !== undefined
+      ? { freeShippingThreshold: shipping.freeShippingThreshold }
+      : {}),
+  };
+}
+
+export async function calculateShippingCost(
+  config: CommerceConfig,
+  catalogRepo: CatalogRepository,
+  input: ShippingCalculationInput,
+  ctx?: TxContext,
+): Promise<{ amount: number; strategy: string; weightGrams: number }> {
+  if (input.isFreeShipping) {
+    return { amount: 0, strategy: "promotion:free_shipping", weightGrams: 0 };
+  }
+
+  const strategy = resolveStrategy(config);
+  if (
+    strategy.freeShippingThreshold !== undefined &&
+    input.subtotalAfterDiscount >= strategy.freeShippingThreshold
+  ) {
+    return { amount: 0, strategy: "threshold:free_shipping", weightGrams: 0 };
+  }
+
+  // Filter to shippable items
+  const shippableFlags = await Promise.all(
+    input.lineItems.map((lineItem) =>
+      isShippableEntity(config, catalogRepo, lineItem.entityId, ctx),
+    ),
+  );
+  const shippableItems = input.lineItems.filter((_, i) => shippableFlags[i]);
+
+  if (shippableItems.length === 0) {
+    return {
+      amount: 0,
+      strategy: `${strategy.type}:digital_only`,
+      weightGrams: 0,
+    };
+  }
+
+  // Calculate total weight
+  const weights = await Promise.all(
+    shippableItems.map((lineItem) =>
+      resolveWeightGrams(
+        catalogRepo,
+        lineItem.entityId,
+        lineItem.variantId,
+        ctx,
+      ),
+    ),
+  );
+  const weightGrams = shippableItems.reduce(
+    (sum, lineItem, i) => sum + (weights[i] ?? 0) * lineItem.quantity,
+    0,
+  );
+
+  if (strategy.type === "flat") {
+    return {
+      amount: Math.max(0, Math.round(strategy.flatRate)),
+      strategy: "flat",
+      weightGrams,
+    };
+  }
+
+  const matchedBracket = strategy.brackets.find(
+    (bracket) => weightGrams <= bracket.upToGrams,
+  );
+  return {
+    amount: matchedBracket
+      ? Math.max(0, Math.round(matchedBracket.cost))
+      : Math.max(0, Math.round(strategy.fallbackCost)),
+    strategy: "weight_based",
+    weightGrams,
+  };
+}

package/src/modules/shipping/module.ts

@@ -0,0 +1,23 @@
+import type { CommerceConfig } from "../../config/types.js";
+import { defineModule } from "../../kernel/module/index.js";
+import type { CatalogServiceImpl } from "../catalog/service.js";
+import { ShippingService } from "./service.js";
+
+type ShippingModuleDeps = {
+  catalog: CatalogServiceImpl;
+};
+
+export const shippingModule = defineModule<
+  Record<string, never>,
+  ShippingService,
+  ShippingModuleDeps
+>({
+  id: "shipping",
+  dependencies: ["catalog"],
+  schema: () => ({}),
+  service: (deps) =>
+    new ShippingService({
+      config: deps.config as CommerceConfig,
+      catalogRepository: deps.services.catalog.repository,
+    }),
+});

package/src/modules/shipping/repository/index.ts

@@ -0,0 +1,6 @@
+import type { TxContext } from "../../../kernel/database/tx-context.js";
+
+export interface ShippingRepository {
+  // RFC-002 scaffold: module repositories become the only persistence boundary.
+  ping(ctx: TxContext): Promise<void>;
+}