@unifiedcommerce/core 0.0.1

package/src/modules/catalog/service.ts

@@ -0,0 +1,1544 @@
+import { resolveOrgId } from "../../auth/org";
+import { assertPermission } from "../../auth/permissions";
+import type { Actor } from "../../auth/types";
+import type { CommerceConfig } from "../../config/types";
+import {
+  CommerceConflictError,
+  CommerceNotFoundError,
+  CommerceValidationError,
+  toCommerceError,
+} from "../../kernel/errors";
+import { runAfterHooks, runBeforeHooks } from "../../kernel/hooks/executor";
+import { createHookContext } from "../../kernel/hooks/create-context";
+import type {
+  AfterHook,
+  BeforeHook,
+  HookContext,
+} from "../../kernel/hooks/types";
+import type { HookRegistry } from "../../kernel/hooks/registry";
+import { Err, Ok, type Result } from "../../kernel/result";
+import { createLogger } from "../../utils/logger";
+import { paginate, type Pagination } from "../../utils/pagination";
+import type { TxContext } from "../../kernel/database/tx-context";
+import {
+  CatalogRepository,
+  type SellableEntity,
+  type SellableAttribute,
+  type SellableCustomField,
+  type SellableCustomFieldInsert,
+  type Category,
+  type EntityCategory,
+  type EntityBrand,
+  type Brand,
+  type OptionType,
+  type OptionValue,
+  type Variant,
+} from "./repository";
+
+// ─── Re-exported schema-derived types ────────────────────────────────────────
+export type {
+  CreateEntityInput,
+  UpdateEntityInput,
+  CreateCategoryInput,
+  UpdateCategoryInput,
+  CreateBrandInput,
+  UpdateBrandInput,
+  CreateOptionTypeInput,
+  CreateOptionValueInput,
+  CreateVariantInput,
+} from "./schemas";
+
+import type {
+  CreateEntityInput,
+  UpdateEntityInput,
+  CreateCategoryInput,
+  UpdateCategoryInput,
+  CreateBrandInput,
+  UpdateBrandInput,
+  CreateOptionTypeInput,
+  CreateOptionValueInput,
+  CreateVariantInput,
+} from "./schemas";
+
+// ─── Hand-written types (not derivable from a single z.infer) ───────────────
+
+export interface SetAttributesInput {
+  title: string;
+  subtitle?: string;
+  description?: string;
+  richDescription?: unknown;
+  seoTitle?: string;
+  seoDescription?: string;
+}
+
+export interface ListParams {
+  filter?: {
+    type?: string;
+    status?: string;
+    category?: string;
+    brand?: string;
+    customField?: {
+      fieldName: string;
+      value: unknown;
+    };
+  };
+  sort?: {
+    field: "createdAt" | "updatedAt" | "slug";
+    direction: "asc" | "desc";
+  };
+  pagination?: {
+    page: number;
+    limit: number;
+  };
+}
+
+export interface GetOptions {
+  includeAttributes?: boolean | { locales: string[] };
+  includeVariants?: boolean;
+  includeOptionTypes?: boolean;
+  includePricing?: boolean;
+  includeInventory?: boolean;
+  includeMedia?: boolean;
+  includeCategories?: boolean;
+  includeBrands?: boolean;
+}
+
+export interface VariantMatrixRule {
+  include?: string[][];
+  exclude?: string[][];
+}
+
+export type VariantGenerationStrategy =
+  | { mode: "all" }
+  | { mode: "manual"; combinations: string[][] }
+  | { mode: "matrix"; matrix: VariantMatrixRule };
+
+export interface CatalogEntityHydrated extends SellableEntity {
+  attributes?: SellableAttribute[];
+  variants?: Array<Variant & { optionValueIds: string[] }>;
+  optionTypes?: Array<OptionType & { values: OptionValue[] }>;
+  categories?: EntityCategory[];
+  brands?: EntityBrand[];
+  media?: Array<{ mediaAssetId: string; role: string; variantId?: string }>;
+}
+
+export interface CatalogService {
+  create(
+    input: CreateEntityInput,
+    actor: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<CatalogEntityHydrated>>;
+  update(
+    id: string,
+    input: UpdateEntityInput,
+    actor: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<CatalogEntityHydrated>>;
+  delete(
+    id: string,
+    actor: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<void>>;
+  getById(
+    id: string,
+    options?: GetOptions,
+    actor?: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<CatalogEntityHydrated>>;
+  getBySlug(
+    slug: string,
+    options?: GetOptions,
+    actor?: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<CatalogEntityHydrated>>;
+  list(params: ListParams, actor?: Actor | null, ctx?: TxContext): Promise<Result<CatalogListResult>>;
+  publish(
+    id: string,
+    actor: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<CatalogEntityHydrated>>;
+  archive(
+    id: string,
+    actor: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<CatalogEntityHydrated>>;
+  discontinue(
+    id: string,
+    actor: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<CatalogEntityHydrated>>;
+  setAttributes(
+    entityId: string,
+    locale: string,
+    attrs: SetAttributesInput,
+    ctx?: TxContext,
+  ): Promise<Result<void>>;
+  getAttributes(
+    entityId: string,
+    locale: string,
+    ctx?: TxContext,
+  ): Promise<Result<SellableAttribute>>;
+  listCategories(ctx?: TxContext): Promise<Result<CategorySummary[]>>;
+  createCategory(
+    input: CreateCategoryInput,
+    actor: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<CategorySummary>>;
+  updateCategory(
+    id: string,
+    input: UpdateCategoryInput,
+    actor: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<CategorySummary>>;
+  deleteCategory(
+    id: string,
+    actor: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<void>>;
+  addToCategory(
+    entityId: string,
+    categoryId: string,
+    ctx?: TxContext,
+  ): Promise<Result<void>>;
+  removeFromCategory(
+    entityId: string,
+    categoryId: string,
+    ctx?: TxContext,
+  ): Promise<Result<void>>;
+  listBrands(ctx?: TxContext): Promise<Result<Brand[]>>;
+  createBrand(
+    input: CreateBrandInput,
+    actor: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<Brand>>;
+  updateBrand(
+    id: string,
+    input: UpdateBrandInput,
+    actor: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<Brand>>;
+  deleteBrand(
+    id: string,
+    actor: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<void>>;
+  addToBrand(
+    entityId: string,
+    brandId: string,
+    ctx?: TxContext,
+  ): Promise<Result<void>>;
+  removeFromBrand(
+    entityId: string,
+    brandId: string,
+    ctx?: TxContext,
+  ): Promise<Result<void>>;
+  createOptionType(
+    input: CreateOptionTypeInput,
+    actor: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<OptionType>>;
+  createOptionValue(
+    input: CreateOptionValueInput,
+    actor: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<OptionValue>>;
+  createVariant(
+    input: CreateVariantInput,
+    actor: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<Variant>>;
+  generateVariants(
+    entityId: string,
+    strategy: VariantGenerationStrategy,
+    actor: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<Variant[]>>;
+}
+
+export interface CatalogServiceDeps {
+  repository: CatalogRepository;
+  hooks: HookRegistry;
+  config: CommerceConfig;
+  services: Record<string, unknown>;
+}
+
+type CatalogListResult = {
+  items: CatalogEntityHydrated[];
+  pagination: Pagination;
+};
+
+type CategorySummary = {
+  id: string;
+  parentId?: string | null;
+  slug: string;
+  sortOrder: number;
+  metadata: Record<string, unknown>;
+};
+
+type CatalogCreateBeforeHook = BeforeHook<CreateEntityInput>;
+type CatalogCreateAfterHook = AfterHook<SellableEntity>;
+type CatalogUpdateBeforeHook = BeforeHook<UpdateEntityInput>;
+type CatalogUpdateAfterHook = AfterHook<SellableEntity>;
+type CatalogReadHookInput = {
+  id?: string;
+  slug?: string;
+  options?: GetOptions;
+};
+type CatalogReadBeforeHook = BeforeHook<CatalogReadHookInput>;
+type CatalogReadAfterHook = AfterHook<CatalogEntityHydrated>;
+type CatalogListBeforeHook = BeforeHook<ListParams>;
+type CatalogListAfterHook = AfterHook<CatalogListResult>;
+
+function cartesian<T>(arrays: T[][]): T[][] {
+  return arrays.reduce<T[][]>(
+    (acc, values) =>
+      acc.flatMap((entry) => values.map((value) => [...entry, value])),
+    [[]],
+  );
+}
+
+/**
+ * Helper to extract the value from a SellableCustomField based on its type.
+ */
+function getCustomFieldValue(field: SellableCustomField): unknown {
+  switch (field.fieldType) {
+    case "text":
+    case "relation":
+      return field.textValue;
+    case "number":
+      return field.numberValue;
+    case "boolean":
+      return field.booleanValue;
+    case "date":
+      return field.dateValue;
+    case "json":
+      return field.jsonValue;
+    default:
+      return null;
+  }
+}
+
+export class CatalogServiceImpl implements CatalogService {
+  private readonly repo: CatalogRepository;
+
+  constructor(private deps: CatalogServiceDeps) {
+    this.repo = deps.repository;
+  }
+
+  private async validateAndCreateCustomFields(
+    entityId: string,
+    entityType: string,
+    customFields: Record<string, unknown> | undefined,
+    ctx?: TxContext,
+  ): Promise<Result<void>> {
+    if (!customFields) return Ok(undefined);
+    const entityConfig = this.deps.config.entities?.[entityType];
+    if (!entityConfig) return Ok(undefined);
+
+    const definitionMap = new Map(entityConfig.fields.map((f) => [f.name, f]));
+
+    for (const [name, value] of Object.entries(customFields)) {
+      const def = definitionMap.get(name);
+      if (!def) {
+        return Err(
+          new CommerceValidationError(`Unknown custom field: ${name}`),
+        );
+      }
+
+      const type = def.type;
+      let valid = false;
+      switch (type) {
+        case "text":
+        case "relation":
+        case "select":
+          valid = typeof value === "string";
+          break;
+        case "number":
+          valid = typeof value === "number";
+          break;
+        case "boolean":
+          valid = typeof value === "boolean";
+          break;
+        case "date":
+          valid = typeof value === "string" || value instanceof Date;
+          break;
+        case "json":
+          valid = typeof value === "object";
+          break;
+        default:
+          valid = false;
+      }
+
+      if (!valid) {
+        return Err(
+          new CommerceValidationError(
+            `Custom field ${name} expected type ${type}.`,
+          ),
+        );
+      }
+
+      const fieldType = (
+        type === "select" ? "text" : type
+      ) as SellableCustomField["fieldType"];
+      const insertData: SellableCustomFieldInsert = {
+        entityId,
+        fieldName: name,
+        fieldType,
+      };
+
+      switch (fieldType) {
+        case "text":
+        case "relation":
+          insertData.textValue = value as string;
+          break;
+        case "number":
+          insertData.numberValue = value as number;
+          break;
+        case "boolean":
+          insertData.booleanValue = value as boolean;
+          break;
+        case "date":
+          insertData.dateValue =
+            value instanceof Date ? value : new Date(value as string);
+          break;
+        case "json":
+          insertData.jsonValue = value;
+          break;
+      }
+
+      await this.repo.createCustomField(insertData, ctx);
+    }
+
+    return Ok(undefined);
+  }
+
+  private async hydrateEntity(
+    entity: SellableEntity,
+    options?: GetOptions,
+    ctx?: TxContext,
+  ): Promise<CatalogEntityHydrated> {
+    const hydrated: CatalogEntityHydrated = { ...entity };
+
+    if (options?.includeAttributes) {
+      const attrs = await this.repo.findAttributesByEntityId(entity.id, ctx);
+      if (typeof options.includeAttributes === "object") {
+        hydrated.attributes = attrs.filter(
+          (a) =>
+            options.includeAttributes &&
+            typeof options.includeAttributes === "object" &&
+            options.includeAttributes.locales.includes(a.locale),
+        );
+      } else {
+        hydrated.attributes = attrs;
+      }
+    }
+
+    if (options?.includeVariants) {
+      const entityVariants = await this.repo.findVariantsByEntityId(
+        entity.id,
+        ctx,
+      );
+      const variantsWithOptions = await Promise.all(
+        entityVariants.map(async (variant) => {
+          const optionValues = await this.repo.findVariantOptionValues(
+            variant.id,
+            ctx,
+          );
+          return {
+            ...variant,
+            optionValueIds: optionValues.map((vov) => vov.optionValueId),
+          };
+        }),
+      );
+      hydrated.variants = variantsWithOptions;
+    }
+
+    if (options?.includeOptionTypes) {
+      const entityOptionTypes = await this.repo.findOptionTypesByEntityId(
+        entity.id,
+        ctx,
+      );
+      hydrated.optionTypes = await Promise.all(
+        entityOptionTypes.map(async (ot) => {
+          const values = await this.repo.findOptionValuesByTypeId(ot.id, ctx);
+          return { ...ot, values };
+        }),
+      );
+    }
+
+    if (options?.includeCategories) {
+      hydrated.categories = await this.repo.findEntityCategories(
+        entity.id,
+        ctx,
+      );
+    }
+
+    if (options?.includeBrands) {
+      hydrated.brands = await this.repo.findEntityBrands(entity.id, ctx);
+    }
+
+    if (options?.includeMedia) {
+      // TODO: integrate with MediaRepository when media service is refactored
+      hydrated.media = [];
+    }
+
+    return hydrated;
+  }
+
+  async create(
+    input: CreateEntityInput,
+    actor: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<CatalogEntityHydrated>> {
+    try {
+      assertPermission(actor, "catalog:create");
+
+      const orgId = resolveOrgId(actor);
+
+      const existingBySlug = await this.repo.findEntityBySlug(orgId, input.slug, ctx);
+      if (existingBySlug) {
+        return Err(
+          new CommerceConflictError(
+            `Entity with slug ${input.slug} already exists.`,
+          ),
+        );
+      }
+
+      const beforeHooks = this.deps.hooks.resolve(
+        "catalog.beforeCreate",
+      ) as CatalogCreateBeforeHook[];
+      const afterHooks = this.deps.hooks.resolve(
+        "catalog.afterCreate",
+      ) as CatalogCreateAfterHook[];
+      const logger = createLogger("catalog.create");
+      const context: HookContext = createHookContext({
+        actor,
+        tx: ctx?.tx ?? null,
+        logger,
+        services: this.deps.services,
+      });
+
+      const processedInput = await runBeforeHooks(
+        beforeHooks,
+        input,
+        "create",
+        context,
+      );
+      const entity = await this.repo.createEntity(
+        {
+          organizationId: orgId,
+          type: processedInput.type,
+          slug: processedInput.slug,
+          status: "draft",
+          isVisible: false,
+          metadata: processedInput.metadata ?? {},
+        },
+        ctx,
+      );
+
+      if (processedInput.attributes) {
+        await this.repo.createAttribute(
+          {
+            entityId: entity.id,
+            locale: processedInput.attributes.locale ?? "en",
+            title: processedInput.attributes.title,
+            subtitle: processedInput.attributes.subtitle,
+            description: processedInput.attributes.description,
+            richDescription: processedInput.attributes.richDescription,
+            seoTitle: processedInput.attributes.seoTitle,
+            seoDescription: processedInput.attributes.seoDescription,
+          },
+          ctx,
+        );
+      }
+
+      const customFieldsResult = await this.validateAndCreateCustomFields(
+        entity.id,
+        entity.type,
+        processedInput.customFields,
+        ctx,
+      );
+      if (!customFieldsResult.ok) return customFieldsResult;
+
+      const hookReport = await runAfterHooks(
+        afterHooks,
+        null,
+        entity,
+        "create",
+        context,
+      );
+      const hydrated = await this.hydrateEntity(entity, undefined, ctx);
+      return Ok(
+        hydrated,
+        hookReport.hasErrors ? { hookErrors: hookReport.errors } : undefined,
+      );
+    } catch (error) {
+      return Err(toCommerceError(error));
+    }
+  }
+
+  async update(
+    id: string,
+    input: UpdateEntityInput,
+    actor: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<CatalogEntityHydrated>> {
+    try {
+      assertPermission(actor, "catalog:update");
+      const existing = await this.repo.findEntityById(id, ctx);
+      if (!existing) return Err(new CommerceNotFoundError("Entity not found."));
+
+      const beforeHooks = this.deps.hooks.resolve(
+        "catalog.beforeUpdate",
+      ) as CatalogUpdateBeforeHook[];
+      const afterHooks = this.deps.hooks.resolve(
+        "catalog.afterUpdate",
+      ) as CatalogUpdateAfterHook[];
+      const context: HookContext = createHookContext({
+        actor,
+        tx: ctx?.tx ?? null,
+        logger: createLogger("catalog.update"),
+        services: this.deps.services,
+      });
+      const processed = await runBeforeHooks(
+        beforeHooks,
+        input,
+        "update",
+        context,
+      );
+
+      const updated = await this.repo.updateEntity(
+        id,
+        {
+          ...(processed.slug !== undefined ? { slug: processed.slug } : {}),
+          ...(processed.status !== undefined
+            ? { status: processed.status as SellableEntity["status"] }
+            : {}),
+          ...(processed.metadata !== undefined
+            ? { metadata: processed.metadata }
+            : {}),
+          ...(processed.isVisible !== undefined
+            ? { isVisible: processed.isVisible }
+            : {}),
+        },
+        ctx,
+      );
+
+      if (!updated) return Err(new CommerceNotFoundError("Entity not found."));
+
+      const hookReport = await runAfterHooks(
+        afterHooks,
+        existing,
+        updated,
+        "update",
+        context,
+      );
+      const hydrated = await this.hydrateEntity(updated, undefined, ctx);
+      return Ok(
+        hydrated,
+        hookReport.hasErrors ? { hookErrors: hookReport.errors } : undefined,
+      );
+    } catch (error) {
+      return Err(toCommerceError(error));
+    }
+  }
+
+  async delete(
+    id: string,
+    actor: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<void>> {
+    try {
+      assertPermission(actor, "catalog:delete");
+      const existing = await this.repo.findEntityById(id, ctx);
+      if (!existing) return Err(new CommerceNotFoundError("Entity not found."));
+
+      // Clean up related data (cascade handles most, but be explicit)
+      await this.repo.deleteAttributesByEntityId(id, ctx);
+      await this.repo.deleteCustomFieldsByEntityId(id, ctx);
+      await this.repo.deleteEntityCategoriesByEntityId(id, ctx);
+      await this.repo.deleteEntityBrandsByEntityId(id, ctx);
+      await this.repo.deleteVariantOptionValuesByEntityId(id, ctx);
+      await this.repo.deleteVariantsByEntityId(id, ctx);
+      await this.repo.deleteEntity(id, ctx);
+
+      return Ok(undefined);
+    } catch (error) {
+      return Err(toCommerceError(error));
+    }
+  }
+
+  async getById(
+    id: string,
+    options?: GetOptions,
+    actor?: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<CatalogEntityHydrated>> {
+    const context: HookContext = createHookContext({
+      actor: actor ?? null,
+      tx: ctx?.tx ?? null,
+      logger: createLogger("catalog.read"),
+      services: this.deps.services,
+    });
+    const beforeHooks = this.deps.hooks.resolve(
+      "catalog.beforeRead",
+    ) as CatalogReadBeforeHook[];
+    const afterHooks = this.deps.hooks.resolve(
+      "catalog.afterRead",
+    ) as CatalogReadAfterHook[];
+    const readInput: CatalogReadHookInput = {
+      id,
+      ...(options !== undefined ? { options } : {}),
+    };
+    const processed = await runBeforeHooks(
+      beforeHooks,
+      readInput,
+      "read",
+      context,
+    );
+
+    const entity = await this.repo.findEntityById(processed.id ?? id, ctx);
+    if (!entity) return Err(new CommerceNotFoundError("Entity not found."));
+
+    // Org boundary check — prevent cross-org access
+    if (actor && entity.organizationId) {
+      const orgId = resolveOrgId(actor);
+      if (entity.organizationId !== orgId) {
+        return Err(new CommerceNotFoundError("Entity not found."));
+      }
+    }
+
+    const result = await this.hydrateEntity(
+      entity,
+      processed.options ?? options,
+      ctx,
+    );
+    const report = await runAfterHooks(
+      afterHooks,
+      null,
+      result,
+      "read",
+      context,
+    );
+    return Ok(
+      result,
+      report.hasErrors ? { hookErrors: report.errors } : undefined,
+    );
+  }
+
+  async getBySlug(
+    slug: string,
+    options?: GetOptions,
+    actor?: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<CatalogEntityHydrated>> {
+    const context: HookContext = createHookContext({
+      actor: actor ?? null,
+      tx: ctx?.tx ?? null,
+      logger: createLogger("catalog.read"),
+      services: this.deps.services,
+    });
+    const beforeHooks = this.deps.hooks.resolve(
+      "catalog.beforeRead",
+    ) as CatalogReadBeforeHook[];
+    const afterHooks = this.deps.hooks.resolve(
+      "catalog.afterRead",
+    ) as CatalogReadAfterHook[];
+    const readInput: CatalogReadHookInput = {
+      slug,
+      ...(options !== undefined ? { options } : {}),
+    };
+    const processed = await runBeforeHooks(
+      beforeHooks,
+      readInput,
+      "read",
+      context,
+    );
+
+    const resolvedSlug = processed.slug ?? slug;
+    const orgId = resolveOrgId(actor ?? null);
+    const entity = await this.repo.findEntityBySlug(orgId, resolvedSlug, ctx);
+    if (!entity) return Err(new CommerceNotFoundError("Entity not found."));
+
+    const result = await this.hydrateEntity(
+      entity,
+      processed.options ?? options,
+      ctx,
+    );
+    const report = await runAfterHooks(
+      afterHooks,
+      null,
+      result,
+      "read",
+      context,
+    );
+    return Ok(
+      result,
+      report.hasErrors ? { hookErrors: report.errors } : undefined,
+    );
+  }
+
+  async list(
+    params: ListParams,
+    actor?: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<CatalogListResult>> {
+    const resolvedActor = actor ?? ctx?.actor ?? null;
+    const context: HookContext = createHookContext({
+      actor: resolvedActor,
+      tx: ctx?.tx ?? null,
+      logger: createLogger("catalog.list"),
+      services: this.deps.services,
+    });
+    const beforeHooks = this.deps.hooks.resolve(
+      "catalog.beforeList",
+    ) as CatalogListBeforeHook[];
+    const afterHooks = this.deps.hooks.resolve(
+      "catalog.afterList",
+    ) as CatalogListAfterHook[];
+    const processed = await runBeforeHooks(
+      beforeHooks,
+      params,
+      "list",
+      context,
+    );
+
+    const listOrgId = resolveOrgId(resolvedActor);
+    let entities = await this.repo.findEntities(
+      listOrgId,
+      {
+        ...(processed.filter?.type ? { type: processed.filter.type } : {}),
+        ...(processed.filter?.status
+          ? { status: processed.filter.status }
+          : {}),
+      },
+      ctx,
+    );
+
+    // Category filter (M1 fix: validate input format, return error if not found)
+    if (processed.filter?.category) {
+      const catInput = processed.filter.category;
+      const isUUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+      let category = await this.repo.findCategoryBySlug(listOrgId, catInput, ctx);
+
+      if (!category && isUUID.test(catInput)) {
+        category = await this.repo.findCategoryById(catInput, ctx);
+      }
+
+      if (!category) {
+        return Err(
+          new CommerceValidationError(`Category not found: "${catInput}".`),
+        );
+      }
+
+      const entityIds = await this.repo.findEntitiesByCategory(
+        category.id,
+        ctx,
+      );
+      const entityIdSet = new Set(entityIds);
+      entities = entities.filter((e) => entityIdSet.has(e.id));
+    }
+
+    // Brand filter
+    if (processed.filter?.brand) {
+      let brand = await this.repo.findBrandBySlug(listOrgId, processed.filter.brand, ctx);
+      if (!brand) {
+        brand = await this.repo.findBrandById(processed.filter.brand, ctx);
+      }
+      if (brand) {
+        const brandEntityIds: string[] = [];
+        for (const entity of entities) {
+          const entityBrands = await this.repo.findEntityBrands(entity.id, ctx);
+          if (entityBrands.some((eb) => eb.brandId === brand!.id)) {
+            brandEntityIds.push(entity.id);
+          }
+        }
+        const brandEntitySet = new Set(brandEntityIds);
+        entities = entities.filter((e) => brandEntitySet.has(e.id));
+      }
+    }
+
+    // Custom field filter
+    if (processed.filter?.customField) {
+      const filteredIds: string[] = [];
+      for (const entity of entities) {
+        const fields = await this.repo.findCustomFieldsByEntityId(
+          entity.id,
+          ctx,
+        );
+        const matches = fields.some((field) => {
+          if (field.fieldName !== processed.filter?.customField?.fieldName)
+            return false;
+          return (
+            getCustomFieldValue(field) === processed.filter.customField.value
+          );
+        });
+        if (matches) filteredIds.push(entity.id);
+      }
+      const filteredSet = new Set(filteredIds);
+      entities = entities.filter((e) => filteredSet.has(e.id));
+    }
+
+    // Sorting
+    if (processed.sort) {
+      const direction = processed.sort.direction === "asc" ? 1 : -1;
+      entities.sort((a, b) => {
+        const first = a[processed.sort!.field];
+        const second = b[processed.sort!.field];
+        if (first instanceof Date && second instanceof Date) {
+          return (first.getTime() - second.getTime()) * direction;
+        }
+        return String(first).localeCompare(String(second)) * direction;
+      });
+    }
+
+    const page = processed.pagination?.page ?? 1;
+    const limit = processed.pagination?.limit ?? 20;
+    const paged = paginate(entities, page, limit);
+
+    const hydratedItems = await Promise.all(
+      paged.items.map((entity) => this.hydrateEntity(entity, undefined, ctx)),
+    );
+
+    const result = { items: hydratedItems, pagination: paged.pagination };
+    const report = await runAfterHooks(
+      afterHooks,
+      null,
+      result,
+      "list",
+      context,
+    );
+    return Ok(
+      result,
+      report.hasErrors ? { hookErrors: report.errors } : undefined,
+    );
+  }
+
+  private async changeStatus(
+    id: string,
+    status: SellableEntity["status"],
+    actor: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<CatalogEntityHydrated>> {
+    const entity = await this.repo.findEntityById(id, ctx);
+    if (!entity) return Err(new CommerceNotFoundError("Entity not found."));
+
+    assertPermission(actor, "catalog:update");
+
+    const updateData: Partial<SellableEntity> = { status };
+    if (status === "active") {
+      updateData.publishedAt = new Date();
+      updateData.isVisible = true;
+    }
+
+    const updated = await this.repo.updateEntity(id, updateData, ctx);
+    if (!updated) return Err(new CommerceNotFoundError("Entity not found."));
+
+    return Ok(await this.hydrateEntity(updated, undefined, ctx));
+  }
+
+  publish(
+    id: string,
+    actor: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<CatalogEntityHydrated>> {
+    return this.changeStatus(id, "active", actor, ctx);
+  }
+
+  archive(
+    id: string,
+    actor: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<CatalogEntityHydrated>> {
+    return this.changeStatus(id, "archived", actor, ctx);
+  }
+
+  discontinue(
+    id: string,
+    actor: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<CatalogEntityHydrated>> {
+    return this.changeStatus(id, "discontinued", actor, ctx);
+  }
+
+  async setAttributes(
+    entityId: string,
+    locale: string,
+    attrs: SetAttributesInput,
+    ctx?: TxContext,
+  ): Promise<Result<void>> {
+    const entity = await this.repo.findEntityById(entityId, ctx);
+    if (!entity) return Err(new CommerceNotFoundError("Entity not found."));
+
+    await this.repo.upsertAttribute(
+      entityId,
+      locale,
+      {
+        title: attrs.title,
+        subtitle: attrs.subtitle,
+        description: attrs.description,
+        richDescription: attrs.richDescription,
+        seoTitle: attrs.seoTitle,
+        seoDescription: attrs.seoDescription,
+      },
+      ctx,
+    );
+
+    return Ok(undefined);
+  }
+
+  async getAttributes(
+    entityId: string,
+    locale: string,
+    ctx?: TxContext,
+  ): Promise<Result<SellableAttribute>> {
+    const attr = await this.repo.findAttributeByLocale(entityId, locale, ctx);
+    if (!attr)
+      return Err(
+        new CommerceNotFoundError(`Attributes for locale ${locale} not found.`),
+      );
+    return Ok(attr);
+  }
+
+  async listCategories(ctx?: TxContext): Promise<Result<CategorySummary[]>> {
+    const allCategories = await this.repo.findAllCategories(resolveOrgId(ctx?.actor ?? null), ctx);
+    const sorted = allCategories.sort(
+      (a, b) => a.sortOrder - b.sortOrder || a.slug.localeCompare(b.slug),
+    );
+    return Ok(
+      sorted.map((c) => ({
+        id: c.id,
+        parentId: c.parentId,
+        slug: c.slug,
+        sortOrder: c.sortOrder,
+        metadata: c.metadata ?? {},
+      })),
+    );
+  }
+
+  async createCategory(
+    input: CreateCategoryInput,
+    actor: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<CategorySummary>> {
+    assertPermission(actor, "catalog:update");
+
+    if (input.id) {
+      const existingById = await this.repo.findCategoryById(input.id, ctx);
+      if (existingById) {
+        return Err(
+          new CommerceConflictError(
+            `Category with id ${input.id} already exists.`,
+          ),
+        );
+      }
+    }
+
+    const orgId = resolveOrgId(actor);
+    const existingBySlug = await this.repo.findCategoryBySlug(orgId, input.slug, ctx);
+    if (existingBySlug) {
+      return Err(
+        new CommerceConflictError(
+          `Category with slug ${input.slug} already exists.`,
+        ),
+      );
+    }
+
+    const category = await this.repo.createCategory(
+      {
+        organizationId: orgId,
+        ...(input.id ? { id: input.id } : {}),
+        slug: input.slug,
+        sortOrder: input.sortOrder ?? 0,
+        metadata: input.metadata ?? {},
+        ...(input.parentId !== undefined ? { parentId: input.parentId } : {}),
+      },
+      ctx,
+    );
+
+    return Ok({
+      id: category.id,
+      parentId: category.parentId,
+      slug: category.slug,
+      sortOrder: category.sortOrder,
+      metadata: category.metadata ?? {},
+    });
+  }
+
+  async updateCategory(
+    id: string,
+    input: UpdateCategoryInput,
+    actor: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<CategorySummary>> {
+    assertPermission(actor, "catalog:update");
+
+    const existing = await this.repo.findCategoryById(id, ctx);
+    if (!existing) return Err(new CommerceNotFoundError("Category not found."));
+
+    if (input.slug) {
+      const catOrgId = resolveOrgId(actor);
+      const existingBySlug = await this.repo.findCategoryBySlug(
+        catOrgId,
+        input.slug,
+        ctx,
+      );
+      if (existingBySlug && existingBySlug.id !== id) {
+        return Err(
+          new CommerceConflictError(
+            `Category with slug ${input.slug} already exists.`,
+          ),
+        );
+      }
+    }
+
+    const updated = await this.repo.updateCategory(
+      id,
+      {
+        ...(input.slug !== undefined ? { slug: input.slug } : {}),
+        ...(input.sortOrder !== undefined
+          ? { sortOrder: input.sortOrder }
+          : {}),
+        ...(input.metadata !== undefined ? { metadata: input.metadata } : {}),
+        ...(input.parentId !== undefined ? { parentId: input.parentId } : {}),
+      },
+      ctx,
+    );
+
+    if (!updated) return Err(new CommerceNotFoundError("Category not found."));
+
+    return Ok({
+      id: updated.id,
+      parentId: updated.parentId,
+      slug: updated.slug,
+      sortOrder: updated.sortOrder,
+      metadata: updated.metadata ?? {},
+    });
+  }
+
+  async deleteCategory(
+    id: string,
+    actor: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<void>> {
+    assertPermission(actor, "catalog:update");
+
+    const existing = await this.repo.findCategoryById(id, ctx);
+    if (!existing) return Err(new CommerceNotFoundError("Category not found."));
+
+    await this.repo.deleteEntityCategoriesByCategoryId(id, ctx);
+    await this.repo.deleteCategory(id, ctx);
+
+    return Ok(undefined);
+  }
+
+  async addToCategory(
+    entityId: string,
+    categoryId: string,
+    ctx?: TxContext,
+  ): Promise<Result<void>> {
+    const entity = await this.repo.findEntityById(entityId, ctx);
+    if (!entity) return Err(new CommerceNotFoundError("Entity not found."));
+
+    const addCatOrgId = resolveOrgId(ctx?.actor ?? null);
+    const isUuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(categoryId);
+    let category = isUuid ? await this.repo.findCategoryById(categoryId, ctx) : null;
+    if (!category) {
+      category = await this.repo.findCategoryBySlug(addCatOrgId, categoryId, ctx);
+    }
+    if (!category) {
+      category = await this.repo.createCategory(
+        {
+          organizationId: addCatOrgId,
+          slug: categoryId,
+          sortOrder: 0,
+          metadata: {},
+        },
+        ctx,
+      );
+    }
+
+    await this.repo.addEntityToCategory(entityId, category.id, 0, ctx);
+    return Ok(undefined);
+  }
+
+  async removeFromCategory(
+    entityId: string,
+    categoryId: string,
+    ctx?: TxContext,
+  ): Promise<Result<void>> {
+    const isCatUuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(categoryId);
+    let category = isCatUuid ? await this.repo.findCategoryById(categoryId, ctx) : null;
+    if (!category) {
+      category = await this.repo.findCategoryBySlug(resolveOrgId(ctx?.actor ?? null), categoryId, ctx);
+    }
+    const resolvedCategoryId = category?.id ?? categoryId;
+
+    const removed = await this.repo.removeEntityFromCategory(
+      entityId,
+      resolvedCategoryId,
+      ctx,
+    );
+    if (!removed)
+      return Err(new CommerceNotFoundError("Category assignment not found."));
+    return Ok(undefined);
+  }
+
+  async listBrands(ctx?: TxContext): Promise<Result<Brand[]>> {
+    const allBrands = await this.repo.findAllBrands(resolveOrgId(ctx?.actor ?? null), ctx);
+    return Ok(
+      allBrands.sort((a, b) => a.displayName.localeCompare(b.displayName)),
+    );
+  }
+
+  async createBrand(
+    input: CreateBrandInput,
+    actor: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<Brand>> {
+    assertPermission(actor, "catalog:update");
+
+    if (input.id) {
+      const existingById = await this.repo.findBrandById(input.id, ctx);
+      if (existingById) {
+        return Err(
+          new CommerceConflictError(
+            `Brand with id ${input.id} already exists.`,
+          ),
+        );
+      }
+    }
+
+    const orgId = resolveOrgId(actor);
+    const existingBySlug = await this.repo.findBrandBySlug(orgId, input.slug, ctx);
+    if (existingBySlug) {
+      return Err(
+        new CommerceConflictError(
+          `Brand with slug ${input.slug} already exists.`,
+        ),
+      );
+    }
+
+    return Ok(
+      await this.repo.createBrand(
+        {
+          organizationId: orgId,
+          ...(input.id ? { id: input.id } : {}),
+          slug: input.slug,
+          displayName: input.displayName,
+          metadata: input.metadata ?? {},
+        },
+        ctx,
+      ),
+    );
+  }
+
+  async updateBrand(
+    id: string,
+    input: UpdateBrandInput,
+    actor: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<Brand>> {
+    assertPermission(actor, "catalog:update");
+
+    const existing = await this.repo.findBrandById(id, ctx);
+    if (!existing) return Err(new CommerceNotFoundError("Brand not found."));
+
+    if (input.slug) {
+      const brandOrgId = resolveOrgId(actor);
+      const existingBySlug = await this.repo.findBrandBySlug(brandOrgId, input.slug, ctx);
+      if (existingBySlug && existingBySlug.id !== id) {
+        return Err(
+          new CommerceConflictError(
+            `Brand with slug ${input.slug} already exists.`,
+          ),
+        );
+      }
+    }
+
+    const updated = await this.repo.updateBrand(
+      id,
+      {
+        ...(input.slug !== undefined ? { slug: input.slug } : {}),
+        ...(input.displayName !== undefined
+          ? { displayName: input.displayName }
+          : {}),
+        ...(input.metadata !== undefined ? { metadata: input.metadata } : {}),
+      },
+      ctx,
+    );
+
+    if (!updated) return Err(new CommerceNotFoundError("Brand not found."));
+    return Ok(updated);
+  }
+
+  async deleteBrand(
+    id: string,
+    actor: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<void>> {
+    assertPermission(actor, "catalog:update");
+
+    const existing = await this.repo.findBrandById(id, ctx);
+    if (!existing) return Err(new CommerceNotFoundError("Brand not found."));
+
+    await this.repo.deleteEntityBrandsByBrandId(id, ctx);
+    await this.repo.deleteBrand(id, ctx);
+
+    return Ok(undefined);
+  }
+
+  async addToBrand(
+    entityId: string,
+    brandId: string,
+    ctx?: TxContext,
+  ): Promise<Result<void>> {
+    const entity = await this.repo.findEntityById(entityId, ctx);
+    if (!entity) return Err(new CommerceNotFoundError("Entity not found."));
+
+    const addBrandOrgId = resolveOrgId(ctx?.actor ?? null);
+    const isBrandUuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(brandId);
+    let brand = isBrandUuid ? await this.repo.findBrandById(brandId, ctx) : null;
+    if (!brand) {
+      brand = await this.repo.findBrandBySlug(addBrandOrgId, brandId, ctx);
+    }
+    if (!brand) {
+      brand = await this.repo.createBrand(
+        {
+          organizationId: addBrandOrgId,
+          slug: brandId,
+          displayName: brandId,
+          metadata: {},
+        },
+        ctx,
+      );
+    }
+
+    await this.repo.addEntityToBrand(entityId, brand.id, 0, ctx);
+    return Ok(undefined);
+  }
+
+  async removeFromBrand(
+    entityId: string,
+    brandId: string,
+    ctx?: TxContext,
+  ): Promise<Result<void>> {
+    const isBrUuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(brandId);
+    let brand = isBrUuid ? await this.repo.findBrandById(brandId, ctx) : null;
+    if (!brand) {
+      brand = await this.repo.findBrandBySlug(resolveOrgId(ctx?.actor ?? null), brandId, ctx);
+    }
+    const resolvedBrandId = brand?.id ?? brandId;
+
+    const removed = await this.repo.removeEntityFromBrand(
+      entityId,
+      resolvedBrandId,
+      ctx,
+    );
+    if (!removed)
+      return Err(new CommerceNotFoundError("Brand assignment not found."));
+    return Ok(undefined);
+  }
+
+  async createOptionType(
+    input: CreateOptionTypeInput,
+    actor: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<OptionType>> {
+    assertPermission(actor, "catalog:update");
+
+    const entity = await this.repo.findEntityById(input.entityId, ctx);
+    if (!entity) return Err(new CommerceNotFoundError("Entity not found."));
+
+    const optionType = await this.repo.createOptionType(
+      {
+        entityId: input.entityId,
+        name: input.name,
+        displayName: input.name,
+        sortOrder: 0,
+      },
+      ctx,
+    );
+
+    // Create initial option values if provided
+    if (input.values) {
+      for (const value of input.values) {
+        await this.repo.createOptionValue(
+          {
+            optionTypeId: optionType.id,
+            value,
+            displayValue: value,
+            sortOrder: 0,
+            metadata: {},
+          },
+          ctx,
+        );
+      }
+    }
+
+    return Ok(optionType);
+  }
+
+  async createOptionValue(
+    input: CreateOptionValueInput,
+    actor: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<OptionValue>> {
+    assertPermission(actor, "catalog:update");
+
+    const optionType = await this.repo.findOptionTypeById(
+      input.optionTypeId,
+      ctx,
+    );
+    if (!optionType)
+      return Err(new CommerceNotFoundError("Option type not found."));
+
+    return Ok(
+      await this.repo.createOptionValue(
+        {
+          optionTypeId: input.optionTypeId,
+          value: input.value,
+          displayValue: input.value,
+          sortOrder: 0,
+          metadata: {},
+        },
+        ctx,
+      ),
+    );
+  }
+
+  async createVariant(
+    input: CreateVariantInput,
+    actor: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<Variant>> {
+    assertPermission(actor, "catalog:update");
+
+    const entity = await this.repo.findEntityById(input.entityId, ctx);
+    if (!entity) return Err(new CommerceNotFoundError("Entity not found."));
+
+    // Resolve options record (e.g. { Color: "Red" }) into option value IDs
+    const entityOptionTypes = await this.repo.findOptionTypesByEntityId(
+      input.entityId,
+      ctx,
+    );
+    const optionValueIds: string[] = [];
+    for (const [optName, optVal] of Object.entries(input.options)) {
+      const ot = entityOptionTypes.find((t) => t.name === optName);
+      if (!ot) {
+        return Err(
+          new CommerceValidationError(
+            `Option type "${optName}" does not exist on this entity.`,
+          ),
+        );
+      }
+      const typeValues = await this.repo.findOptionValuesByTypeId(ot.id, ctx);
+      const ov = typeValues.find((v) => v.value === optVal);
+      if (!ov) {
+        return Err(
+          new CommerceValidationError(
+            `Option value "${optVal}" does not exist for option type "${optName}".`,
+          ),
+        );
+      }
+      optionValueIds.push(ov.id);
+    }
+
+    const variant = await this.repo.createVariant(
+      {
+        entityId: input.entityId,
+        status: "active",
+        sortOrder: 0,
+        metadata: {},
+        ...(input.sku !== undefined ? { sku: input.sku } : {}),
+      },
+      ctx,
+    );
+
+    await this.repo.createVariantOptionValues(
+      optionValueIds.map((optionValueId) => ({
+        variantId: variant.id,
+        optionValueId,
+      })),
+      ctx,
+    );
+
+    return Ok(variant);
+  }
+
+  async generateVariants(
+    entityId: string,
+    strategy: VariantGenerationStrategy,
+    actor: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<Variant[]>> {
+    assertPermission(actor, "catalog:update");
+
+    const entity = await this.repo.findEntityById(entityId, ctx);
+    if (!entity) return Err(new CommerceNotFoundError("Entity not found."));
+
+    const entityOptionTypes = await this.repo.findOptionTypesByEntityId(
+      entityId,
+      ctx,
+    );
+    const sortedOptionTypes = entityOptionTypes.sort(
+      (a, b) => a.sortOrder - b.sortOrder,
+    );
+
+    const optionValueGroups: string[][] = [];
+    for (const optionType of sortedOptionTypes) {
+      const values = await this.repo.findOptionValuesByTypeId(
+        optionType.id,
+        ctx,
+      );
+      const sortedValues = values.sort((a, b) => a.sortOrder - b.sortOrder);
+      optionValueGroups.push(sortedValues.map((v) => v.id));
+    }
+
+    let combinations: string[][] = [];
+
+    if (strategy.mode === "all") {
+      combinations = cartesian(optionValueGroups);
+    } else if (strategy.mode === "manual") {
+      combinations = strategy.combinations;
+    } else {
+      const base = cartesian(optionValueGroups);
+      const include = strategy.matrix.include;
+      const exclude = strategy.matrix.exclude;
+      combinations = base.filter((combo) => {
+        const isExcluded = (exclude ?? []).some((pattern) =>
+          pattern.every((val) => combo.includes(val)),
+        );
+        if (isExcluded) return false;
+        if (!include || include.length === 0) return true;
+        return include.some((pattern) =>
+          pattern.every((val) => combo.includes(val)),
+        );
+      });
+    }
+
+    const created: Variant[] = [];
+    for (const combo of combinations) {
+      const variant = await this.repo.createVariant(
+        {
+          entityId,
+          status: "active",
+          sortOrder: 0,
+          metadata: { generatedBy: strategy.mode },
+        },
+        ctx,
+      );
+      await this.repo.createVariantOptionValues(
+        combo.map((optionValueId) => ({
+          variantId: variant.id,
+          optionValueId,
+        })),
+        ctx,
+      );
+      created.push(variant);
+    }
+
+    return Ok(created);
+  }
+}