@unifiedcommerce/core 0.4.4 → 0.5.0

package/dist/modules/catalog/service.js

@@ -0,0 +1,775 @@
+import { resolveOrgId } from "../../auth/org.js";
+import { assertPermission } from "../../auth/permissions.js";
+import { CommerceConflictError, CommerceNotFoundError, CommerceValidationError, toCommerceError, } from "../../kernel/errors.js";
+import { runAfterHooks, runBeforeHooks } from "../../kernel/hooks/executor.js";
+import { createHookContext } from "../../kernel/hooks/create-context.js";
+import { Err, Ok } from "../../kernel/result.js";
+import { createLogger } from "../../utils/logger.js";
+import { paginate } from "../../utils/pagination.js";
+function cartesian(arrays) {
+    return arrays.reduce((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) {
+    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 {
+    deps;
+    repo;
+    constructor(deps) {
+        this.deps = deps;
+        this.repo = deps.repository;
+    }
+    async validateAndCreateCustomFields(entityId, entityType, customFields, ctx) {
+        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);
+            const insertData = {
+                entityId,
+                fieldName: name,
+                fieldType,
+            };
+            switch (fieldType) {
+                case "text":
+                case "relation":
+                    insertData.textValue = value;
+                    break;
+                case "number":
+                    insertData.numberValue = value;
+                    break;
+                case "boolean":
+                    insertData.booleanValue = value;
+                    break;
+                case "date":
+                    insertData.dateValue =
+                        value instanceof Date ? value : new Date(value);
+                    break;
+                case "json":
+                    insertData.jsonValue = value;
+                    break;
+            }
+            await this.repo.createCustomField(insertData, ctx);
+        }
+        return Ok(undefined);
+    }
+    async hydrateEntity(entity, options, ctx) {
+        const hydrated = { ...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 = [];
+        }
+        if (options?.includePricing) {
+            try {
+                const pricingService = this.deps.services.pricing;
+                const priceResult = await pricingService.listPrices({ entityId: entity.id });
+                if (priceResult.ok && priceResult.value) {
+                    hydrated.pricing = priceResult.value.prices.map((p) => ({
+                        currency: p.currency,
+                        amount: p.amount,
+                        compareAtAmount: p.compareAtAmount ?? null,
+                    }));
+                }
+            }
+            catch {
+                // Pricing service may not be initialized — leave pricing undefined
+            }
+        }
+        return hydrated;
+    }
+    async create(input, actor, ctx) {
+        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");
+            const afterHooks = this.deps.hooks.resolve("catalog.afterCreate");
+            const logger = createLogger("catalog.create");
+            const context = 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, input, actor, ctx) {
+        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");
+            const afterHooks = this.deps.hooks.resolve("catalog.afterUpdate");
+            const context = 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 }
+                    : {}),
+                ...(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, actor, ctx) {
+        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, options, actor, ctx) {
+        const context = createHookContext({
+            actor: actor ?? null,
+            tx: ctx?.tx ?? null,
+            logger: createLogger("catalog.read"),
+            services: this.deps.services,
+        });
+        const beforeHooks = this.deps.hooks.resolve("catalog.beforeRead");
+        const afterHooks = this.deps.hooks.resolve("catalog.afterRead");
+        const readInput = {
+            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, options, actor, ctx) {
+        const context = createHookContext({
+            actor: actor ?? null,
+            tx: ctx?.tx ?? null,
+            logger: createLogger("catalog.read"),
+            services: this.deps.services,
+        });
+        const beforeHooks = this.deps.hooks.resolve("catalog.beforeRead");
+        const afterHooks = this.deps.hooks.resolve("catalog.afterRead");
+        const readInput = {
+            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, actor, ctx) {
+        const resolvedActor = actor ?? ctx?.actor ?? null;
+        const context = createHookContext({
+            actor: resolvedActor,
+            tx: ctx?.tx ?? null,
+            logger: createLogger("catalog.list"),
+            services: this.deps.services,
+        });
+        const beforeHooks = this.deps.hooks.resolve("catalog.beforeList");
+        const afterHooks = this.deps.hooks.resolve("catalog.afterList");
+        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 = [];
+                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 = [];
+            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);
+    }
+    async changeStatus(id, status, actor, ctx) {
+        const entity = await this.repo.findEntityById(id, ctx);
+        if (!entity)
+            return Err(new CommerceNotFoundError("Entity not found."));
+        assertPermission(actor, "catalog:update");
+        const updateData = { 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, actor, ctx) {
+        return this.changeStatus(id, "active", actor, ctx);
+    }
+    archive(id, actor, ctx) {
+        return this.changeStatus(id, "archived", actor, ctx);
+    }
+    discontinue(id, actor, ctx) {
+        return this.changeStatus(id, "discontinued", actor, ctx);
+    }
+    async setAttributes(entityId, locale, attrs, ctx) {
+        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, locale, ctx) {
+        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) {
+        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, actor, ctx) {
+        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, input, actor, ctx) {
+        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, actor, ctx) {
+        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, categoryId, ctx) {
+        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, categoryId, ctx) {
+        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) {
+        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, actor, ctx) {
+        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, input, actor, ctx) {
+        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, actor, ctx) {
+        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, brandId, ctx) {
+        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, brandId, ctx) {
+        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, actor, ctx) {
+        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, actor, ctx) {
+        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, actor, ctx) {
+        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 = [];
+        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, strategy, actor, ctx) {
+        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 = [];
+        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 = [];
+        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 = [];
+        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);
+    }
+}