@unifiedcommerce/core 0.2.0 → 0.2.2

package/src/modules/search/service.ts

@@ -0,0 +1,315 @@
+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);
+
+    if (this.deps.adapter) {
+      return this.deps.adapter.search({
+        ...params,
+        page,
+        limit,
+      });
+    }
+
+    const tokens = tokenize(params.query);
+    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),
+    });
+  }
+
+  async suggest(
+    params: SearchSuggestParams,
+    ctx?: TxContext,
+  ): Promise<Result<string[]>> {
+    const limit = clamp(params.limit ?? 10, 1, 25);
+    const prefix = params.prefix.trim().toLowerCase();
+
+    if (prefix.length === 0) return Ok([]);
+
+    if (this.deps.adapter) {
+      return this.deps.adapter.suggest({
+        ...params,
+        prefix,
+        limit,
+      });
+    }
+
+    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);
+  }
+}

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/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>;
+}

package/src/modules/shipping/service.ts

@@ -0,0 +1,51 @@
+import type { CommerceConfig } from "../../config/types.js";
+import { Ok, type Result } from "../../kernel/result.js";
+import type { TxContext } from "../../kernel/database/tx-context.js";
+import type { CatalogRepository } from "../catalog/repository/index.js";
+import {
+  calculateShippingCost,
+  type ShippingAddress,
+  type ShippingLineItem,
+} from "./calculator.js";
+
+interface ShippingServiceDeps {
+  config: CommerceConfig;
+  catalogRepository: CatalogRepository;
+}
+
+export interface CalculateShippingInput {
+  lineItems: ShippingLineItem[];
+  subtotalAfterDiscount: number;
+  currency: string;
+  address?: ShippingAddress;
+  isFreeShipping?: boolean;
+}
+
+export class ShippingService {
+  private readonly catalogRepo: CatalogRepository;
+
+  constructor(private deps: ShippingServiceDeps) {
+    this.catalogRepo = deps.catalogRepository;
+  }
+
+  async calculate(
+    input: CalculateShippingInput,
+    ctx?: TxContext,
+  ): Promise<
+    Result<{ amount: number; strategy: string; weightGrams: number }>
+  > {
+    const result = await calculateShippingCost(
+      this.deps.config,
+      this.catalogRepo,
+      {
+        lineItems: input.lineItems,
+        subtotalAfterDiscount: input.subtotalAfterDiscount,
+        currency: input.currency,
+        isFreeShipping: input.isFreeShipping ?? false,
+        ...(input.address !== undefined ? { address: input.address } : {}),
+      },
+      ctx,
+    );
+    return Ok(result);
+  }
+}

package/src/modules/tax/adapter.ts

@@ -0,0 +1,60 @@
+import type { Result } from "../../kernel/result.js";
+
+export interface TaxAddress {
+  country: string;
+  postalCode: string;
+  state?: string;
+  city?: string;
+  line1?: string;
+}
+
+export interface TaxLineItem {
+  id: string;
+  entityId: string;
+  description: string;
+  quantity: number;
+  unitPrice: number;
+  discount?: number;
+  productTaxCode?: string;
+}
+
+export interface TaxCalculationParams {
+  currency: string;
+  customerId?: string;
+  orderId?: string;
+  fromAddress?: TaxAddress;
+  toAddress?: TaxAddress;
+  shippingAmount: number;
+  lineItems: TaxLineItem[];
+}
+
+export interface TaxCalculationResult {
+  amountToCollect: number;
+  taxableAmount: number;
+  rate: number;
+  breakdown?: Record<string, unknown>;
+}
+
+export interface TaxReportParams {
+  transactionId: string;
+  transactionDate: Date;
+  currency: string;
+  customerId?: string;
+  fromAddress?: TaxAddress;
+  toAddress?: TaxAddress;
+  amount: number;
+  shipping: number;
+  salesTax: number;
+  lineItems: TaxLineItem[];
+}
+
+export interface TaxVoidParams {
+  transactionId: string;
+}
+
+export interface TaxAdapter {
+  readonly providerId: string;
+  calculateTax(params: TaxCalculationParams): Promise<Result<TaxCalculationResult>>;
+  reportTransaction(params: TaxReportParams): Promise<Result<{ transactionId: string }>>;
+  voidTransaction(params: TaxVoidParams): Promise<Result<{ transactionId: string }>>;
+}

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

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

package/src/modules/tax/service.ts

@@ -0,0 +1,53 @@
+import { CommerceValidationError } from "../../kernel/errors.js";
+import { Err, Ok, type Result } from "../../kernel/result.js";
+import type {
+  TaxAdapter,
+  TaxCalculationParams,
+  TaxCalculationResult,
+  TaxReportParams,
+  TaxVoidParams,
+} from "./adapter.js";
+
+interface TaxServiceDeps {
+  adapter: TaxAdapter | undefined;
+}
+
+export class TaxService {
+  private adapter: TaxAdapter | undefined;
+
+  constructor(deps: TaxServiceDeps) {
+    this.adapter = deps.adapter;
+  }
+
+  async calculate(params: TaxCalculationParams): Promise<Result<TaxCalculationResult>> {
+    if (!this.adapter) {
+      return Ok({
+        amountToCollect: 0,
+        taxableAmount:
+          params.lineItems.reduce(
+            (sum, lineItem) => sum + lineItem.unitPrice * lineItem.quantity - (lineItem.discount ?? 0),
+            0,
+          ) + params.shippingAmount,
+        rate: 0,
+      });
+    }
+    return this.adapter.calculateTax(params);
+  }
+
+  async reportTransaction(params: TaxReportParams): Promise<Result<{ transactionId: string }>> {
+    if (!this.adapter) return Ok({ transactionId: params.transactionId });
+    return this.adapter.reportTransaction(params);
+  }
+
+  async voidTransaction(params: TaxVoidParams): Promise<Result<{ transactionId: string }>> {
+    if (!this.adapter) return Ok({ transactionId: params.transactionId });
+    return this.adapter.voidTransaction(params);
+  }
+
+  requireConfigured(): Result<TaxAdapter> {
+    if (!this.adapter) {
+      return Err(new CommerceValidationError("Tax adapter is not configured."));
+    }
+    return Ok(this.adapter);
+  }
+}