@porulle/core 0.1.0

package/dist/modules/cart/service.d.ts

@@ -0,0 +1,87 @@
+import type { Actor } from "../../auth/types.js";
+import type { CommerceConfig } from "../../config/types.js";
+import type { HookRegistry } from "../../kernel/hooks/registry.js";
+import { type Result } from "../../kernel/result.js";
+import type { DatabaseAdapter } from "../../kernel/database/adapter.js";
+import type { TxContext } from "../../kernel/database/tx-context.js";
+import { CartRepository, type Cart, type CartLineItem } from "./repository/index.js";
+import type { CatalogRepository } from "../catalog/repository/index.js";
+export type { CreateCartInput, AddCartItemInput, UpdateCartItemInput, } from "./schemas.js";
+import type { CreateCartInput, AddCartItemInput, UpdateCartItemInput } from "./schemas.js";
+import { type CartItemMatcher } from "./matcher.js";
+export interface CartServiceDeps {
+    repository: CartRepository;
+    catalogRepository: CatalogRepository;
+    hooks: HookRegistry;
+    config: CommerceConfig;
+    services: Record<string, unknown>;
+    database: DatabaseAdapter;
+    cartItemMatcher?: CartItemMatcher;
+}
+export declare class CartService {
+    private deps;
+    private readonly repo;
+    private readonly catalogRepo;
+    constructor(deps: CartServiceDeps);
+    create(input: CreateCartInput, actor?: Actor | null, ctx?: TxContext): Promise<Result<Cart>>;
+    getById(id: string, actor?: Actor | null, ctx?: TxContext, secret?: string): Promise<Result<Cart & {
+        lineItems: CartLineItem[];
+    }>>;
+    addItem(input: AddCartItemInput, actor?: Actor | null, ctx?: TxContext): Promise<Result<CartLineItem>>;
+    removeItem(cartId: string, itemId: string, actor?: Actor | null, ctx?: TxContext): Promise<Result<void>>;
+    updateQuantity(input: UpdateCartItemInput, actor?: Actor | null, ctx?: TxContext): Promise<Result<CartLineItem>>;
+    merge(sourceCartId: string, targetCartId: string, actor?: Actor | null, ctx?: TxContext): Promise<Result<void>>;
+    abandon(cartId: string, actor?: Actor | null, ctx?: TxContext): Promise<Result<void>>;
+    markAsCheckedOut(cartId: string, actor?: Actor | null, ctx?: TxContext): Promise<Result<void>>;
+    /**
+     * Atomically transitions a cart from "active" to "checking_out".
+     * Returns Err if the cart was already claimed by a concurrent checkout.
+     * This prevents TOCTOU race conditions on double-checkout.
+     */
+    claimForCheckout(cartId: string, ctx?: TxContext): Promise<Result<Cart>>;
+    /**
+     * Creates an anonymous guest cart with a secret token for access control.
+     * The secret must be stored client-side (cookie/local storage) and sent
+     * with subsequent requests to identify the cart owner.
+     */
+    createGuestCart(currency?: string, ctx?: TxContext): Promise<Result<{
+        cart: Cart;
+        secret: string;
+    }>>;
+    /**
+     * Merges a guest (source) cart into an authenticated (target) cart on login.
+     * Uses addItem() internally so CartItemMatcher deduplication is applied.
+     * The source cart's secret must be provided for access control.
+     */
+    mergeCarts(targetCartId: string, sourceCartId: string, sourceSecret: string, actor: Actor, ctx?: TxContext): Promise<Result<Cart>>;
+    /**
+     * Resolves the actor's customer profile UUID.
+     * Returns null if actor is anonymous or has no associated customer profile.
+     * Cart.customerId is bound to the customer profile UUID, not the Better
+     * Auth user.id, so ownership checks must resolve the profile first.
+     */
+    private resolveActorCustomerId;
+    /**
+     * Cart-write ownership policy (used by addItem, updateQuantity, removeItem):
+     *   - Admin/staff (permissions include *:*) — bypass.
+     *   - Customer role: cart.customerId must match the actor's customer
+     *     profile UUID. Without this match, customer B was able to write
+     *     to customer A's cart by UUID (claude-glm finding).
+     *   - Guest cart (customerId null): only the cart-secret holder may write.
+     *     Without a presented secret, deny — the previous "anyone can write
+     *     to a guest cart" behavior allowed cross-customer hijack of the
+     *     post-A1-fix orphan carts.
+     */
+    private assertCartOwnership;
+    /**
+     * Cart-read access policy:
+     *   - *:* permission — bypass (admins).
+     *   - Customer cart (customerId set): authenticated actor's customer
+     *     profile UUID must match cart.customerId.
+     *   - Guest cart (customerId null): require the presented cart secret
+     *     to match, OR a staff/admin/agent actor with cart:read.
+     *   - Anonymous + customer cart, OR no secret + guest cart: forbidden.
+     */
+    private assertCartReadAccess;
+}
+//# sourceMappingURL=service.d.ts.map

package/dist/modules/cart/service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../../../src/modules/cart/service.ts"],"names":[],"mappings":"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"}

package/dist/modules/cart/service.js

@@ -0,0 +1,454 @@
+import { resolveOrgId } from "../../auth/org.js";
+import { assertPermission } from "../../auth/permissions.js";
+import { CommerceForbiddenError, 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 { defaultCartItemMatcher } from "./matcher.js";
+function makeContext(actor, services, database, tx = null) {
+    return createHookContext({
+        actor,
+        tx,
+        logger: createLogger("cart"),
+        services,
+        context: { moduleName: "cart" },
+        database: { db: database.db },
+    });
+}
+function isExpired(cart) {
+    return cart.expiresAt.getTime() < Date.now();
+}
+export class CartService {
+    deps;
+    repo;
+    catalogRepo;
+    constructor(deps) {
+        this.deps = deps;
+        this.repo = deps.repository;
+        this.catalogRepo = deps.catalogRepository;
+    }
+    async create(input, actor, ctx) {
+        try {
+            assertPermission(actor ?? null, "cart:create");
+        }
+        catch (error) {
+            return Err(toCommerceError(error));
+        }
+        const ttlMinutes = this.deps.config.cart?.ttlMinutes ?? 60 * 24 * 7;
+        const now = new Date();
+        const orgId = resolveOrgId(actor ?? null);
+        // SECURITY: cart.customerId is service-managed.
+        //
+        // VAPT r2 (claude-glm) follow-up: the previous "set null for customer
+        // role" fix made every customer cart a "guest cart", which the cart
+        // ownership check treated as accessible-to-anyone-with-the-UUID.
+        // Cross-customer cart hijack was the consequence — customer B could
+        // read/add/update/delete items on customer A's cart by knowing the UUID.
+        //
+        // The right model: customer-role actors get cart.customerId resolved
+        // from their session via the customers service (lookup-or-create). The
+        // ownership check in assertCartReadAccess and assertCartOwnership then
+        // matches actor.userId against the customer profile owned by that user.
+        // Staff / admin / agent: trusted, may supply customerId for POS / agent
+        // assist. Anonymous (no actor): null customerId, secret-gated.
+        const STAFF_ROLES = new Set(["staff", "admin", "owner", "ai_agent", "service"]);
+        const isStaffActor = actor != null &&
+            typeof actor.role === "string" &&
+            STAFF_ROLES.has(actor.role);
+        let resolvedCustomerId = null;
+        if (isStaffActor) {
+            resolvedCustomerId = input.customerId ?? null;
+        }
+        else if (actor?.userId) {
+            // Customer-role actor: bind cart to their customer profile UUID.
+            // customers.getByUserId is lookup-or-create; subsequent reads/writes
+            // can match the cart's customerId against the same UUID via this
+            // service to assert ownership.
+            const customers = this.deps.services.customers;
+            if (customers?.getByUserId) {
+                const profileResult = await customers.getByUserId(actor.userId, actor, ctx);
+                if (profileResult.ok) {
+                    resolvedCustomerId = profileResult.value.id;
+                }
+            }
+        }
+        const cart = await this.repo.create({
+            organizationId: orgId,
+            status: "active",
+            currency: input.currency ?? "USD",
+            metadata: input.metadata ?? {},
+            expiresAt: new Date(now.getTime() + ttlMinutes * 60 * 1000),
+            ...(resolvedCustomerId !== null ? { customerId: resolvedCustomerId } : {}),
+        }, ctx);
+        return Ok(cart);
+    }
+    async getById(id, actor, ctx, secret) {
+        // VAPT r2 (codex) finding: cart.getById had no permission gate AND
+        // assertCartOwnership returned early for guest carts (customerId == null)
+        // and for anonymous actors. Anyone who knew or guessed a cart UUID could
+        // read any cart's contents, prices, line items, and metadata. This now
+        // requires either an authenticated owner/staff actor OR the cart's
+        // secret token (returned only at createGuest()).
+        const orgId = resolveOrgId(actor ?? ctx?.actor ?? null);
+        const cart = await this.repo.findById(orgId, id, ctx);
+        if (!cart)
+            return Err(new CommerceNotFoundError("Cart not found."));
+        try {
+            await this.assertCartReadAccess(actor ?? null, cart, secret, ctx);
+        }
+        catch (error) {
+            return Err(toCommerceError(error));
+        }
+        if (isExpired(cart) && cart.status === "active") {
+            await this.repo.updateStatus(cart.id, "abandoned", ctx);
+            cart.status = "abandoned";
+        }
+        const lineItems = await this.repo.findLineItemsByCartId(id, ctx);
+        return Ok({
+            ...cart,
+            lineItems,
+        });
+    }
+    async addItem(input, actor, ctx) {
+        try {
+            assertPermission(actor ?? null, "cart:update");
+        }
+        catch (error) {
+            return Err(toCommerceError(error));
+        }
+        const orgId = resolveOrgId(actor ?? null);
+        const cart = await this.repo.findById(orgId, input.cartId, ctx);
+        if (!cart)
+            return Err(new CommerceNotFoundError("Cart not found."));
+        try {
+            await this.assertCartOwnership(actor ?? null, cart, ctx);
+        }
+        catch (error) {
+            return Err(toCommerceError(error));
+        }
+        if (cart.status !== "active") {
+            return Err(new CommerceValidationError("Cart is not active."));
+        }
+        const quantity = input.quantity ?? 1;
+        if (quantity <= 0) {
+            return Err(new CommerceValidationError("Quantity must be greater than zero."));
+        }
+        // Validate entity exists
+        const entity = await this.catalogRepo.findEntityById(input.entityId, ctx);
+        if (!entity)
+            return Err(new CommerceNotFoundError("Entity not found."));
+        // Check if entity has variants
+        const entityVariants = await this.catalogRepo.findVariantsByEntityId(input.entityId, ctx);
+        const hasVariants = entityVariants.length > 0;
+        if (hasVariants && !input.variantId) {
+            const variantIds = entityVariants.map((v) => v.id);
+            return Err(new CommerceValidationError(`Entity "${entity.slug}" has variants enabled, but no variantId was provided.`, [
+                {
+                    field: "variantId",
+                    message: `Available variants: ${variantIds.join(", ")}`,
+                },
+            ]));
+        }
+        const context = makeContext(actor ?? null, this.deps.services, this.deps.database, ctx?.tx);
+        const beforeHooks = this.deps.hooks.resolve("cart.beforeAddItem");
+        const afterHooks = this.deps.hooks.resolve("cart.afterAddItem");
+        const processed = await runBeforeHooks(beforeHooks, input, "addItem", context);
+        // CartItemMatcher: deduplicate by merging quantity into existing matching item
+        const matcher = this.deps.cartItemMatcher ?? defaultCartItemMatcher;
+        const existingItems = await this.repo.findLineItemsByCartId(input.cartId, ctx);
+        const match = existingItems.find((existing) => matcher({
+            existingItem: existing,
+            newItem: {
+                ...processed,
+                variantId: processed.variantId ?? null,
+            },
+        }));
+        let item;
+        if (match) {
+            const updated = await this.repo.updateLineItem(match.id, { quantity: match.quantity + quantity }, ctx);
+            item = updated;
+        }
+        else {
+            item = await this.repo.createLineItem({
+                cartId: input.cartId,
+                entityId: processed.entityId,
+                quantity,
+                unitPriceSnapshot: processed.unitPriceSnapshot ?? 1000,
+                currency: processed.currency ?? cart.currency,
+                metadata: processed.metadata ?? {},
+                ...(processed.variantId !== undefined
+                    ? { variantId: processed.variantId }
+                    : {}),
+            }, ctx);
+        }
+        await runAfterHooks(afterHooks, null, item, "addItem", context);
+        return Ok(item);
+    }
+    async removeItem(cartId, itemId, actor, ctx) {
+        try {
+            assertPermission(actor ?? null, "cart:update");
+        }
+        catch (error) {
+            return Err(toCommerceError(error));
+        }
+        const orgId = resolveOrgId(actor ?? null);
+        const cart = await this.repo.findById(orgId, cartId, ctx);
+        if (!cart)
+            return Err(new CommerceNotFoundError("Cart not found."));
+        try {
+            await this.assertCartOwnership(actor ?? null, cart, ctx);
+        }
+        catch (error) {
+            return Err(toCommerceError(error));
+        }
+        const existing = await this.repo.findLineItemById(itemId, ctx);
+        if (!existing || existing.cartId !== cartId) {
+            return Err(new CommerceNotFoundError("Cart item not found."));
+        }
+        const context = makeContext(actor ?? null, this.deps.services, this.deps.database, ctx?.tx);
+        const beforeHooks = this.deps.hooks.resolve("cart.beforeRemoveItem");
+        const afterHooks = this.deps.hooks.resolve("cart.afterRemoveItem");
+        await runBeforeHooks(beforeHooks, existing, "removeItem", context);
+        await this.repo.deleteLineItem(itemId, ctx);
+        await runAfterHooks(afterHooks, existing, existing, "removeItem", context);
+        return Ok(undefined);
+    }
+    async updateQuantity(input, actor, ctx) {
+        try {
+            assertPermission(actor ?? null, "cart:update");
+        }
+        catch (error) {
+            return Err(toCommerceError(error));
+        }
+        const orgId = resolveOrgId(actor ?? null);
+        const cart = await this.repo.findById(orgId, input.cartId, ctx);
+        if (!cart)
+            return Err(new CommerceNotFoundError("Cart not found."));
+        try {
+            await this.assertCartOwnership(actor ?? null, cart, ctx);
+        }
+        catch (error) {
+            return Err(toCommerceError(error));
+        }
+        const item = await this.repo.findLineItemById(input.itemId, ctx);
+        if (!item || item.cartId !== input.cartId) {
+            return Err(new CommerceNotFoundError("Cart item not found."));
+        }
+        if (input.quantity <= 0) {
+            return Err(new CommerceValidationError("Quantity must be greater than zero."));
+        }
+        const context = makeContext(actor ?? null, this.deps.services, this.deps.database, ctx?.tx);
+        const beforeHooks = this.deps.hooks.resolve("cart.beforeUpdateQuantity");
+        const afterHooks = this.deps.hooks.resolve("cart.afterUpdateQuantity");
+        await runBeforeHooks(beforeHooks, input, "update", context);
+        const updated = await this.repo.updateLineItem(input.itemId, { quantity: input.quantity }, ctx);
+        if (!updated) {
+            return Err(new CommerceNotFoundError("Cart item not found."));
+        }
+        await runAfterHooks(afterHooks, item, updated, "update", context);
+        return Ok(updated);
+    }
+    async merge(sourceCartId, targetCartId, actor, ctx) {
+        try {
+            assertPermission(actor ?? null, "cart:update");
+        }
+        catch (error) {
+            return Err(toCommerceError(error));
+        }
+        const orgId = resolveOrgId(actor ?? null);
+        const source = await this.repo.findById(orgId, sourceCartId, ctx);
+        const target = await this.repo.findById(orgId, targetCartId, ctx);
+        if (!source || !target)
+            return Err(new CommerceNotFoundError("Cart not found."));
+        const sourceItems = await this.repo.findLineItemsByCartId(sourceCartId, ctx);
+        // Move items from source to target
+        for (const item of sourceItems) {
+            await this.repo.createLineItem({
+                cartId: targetCartId,
+                entityId: item.entityId,
+                variantId: item.variantId,
+                quantity: item.quantity,
+                unitPriceSnapshot: item.unitPriceSnapshot,
+                currency: item.currency,
+                metadata: item.metadata ?? {},
+            }, ctx);
+        }
+        // Clear source cart items and mark as merged
+        await this.repo.deleteLineItemsByCartId(sourceCartId, ctx);
+        await this.repo.updateStatus(sourceCartId, "merged", ctx);
+        return Ok(undefined);
+    }
+    async abandon(cartId, actor, ctx) {
+        const orgId = resolveOrgId(actor ?? ctx?.actor ?? null);
+        const cart = await this.repo.findById(orgId, cartId, ctx);
+        if (!cart)
+            return Err(new CommerceNotFoundError("Cart not found."));
+        await this.repo.updateStatus(cartId, "abandoned", ctx);
+        return Ok(undefined);
+    }
+    async markAsCheckedOut(cartId, actor, ctx) {
+        const orgId = resolveOrgId(actor ?? ctx?.actor ?? null);
+        const cart = await this.repo.findById(orgId, cartId, ctx);
+        if (!cart)
+            return Err(new CommerceNotFoundError("Cart not found."));
+        await this.repo.updateStatus(cartId, "checked_out", ctx);
+        return Ok(undefined);
+    }
+    /**
+     * Atomically transitions a cart from "active" to "checking_out".
+     * Returns Err if the cart was already claimed by a concurrent checkout.
+     * This prevents TOCTOU race conditions on double-checkout.
+     */
+    async claimForCheckout(cartId, ctx) {
+        const claimed = await this.repo.transitionToCheckingOut(cartId, ctx);
+        if (!claimed) {
+            return Err(new CommerceValidationError("Cart is not available for checkout. It may have already been checked out by a concurrent request."));
+        }
+        return Ok(claimed);
+    }
+    /**
+     * Creates an anonymous guest cart with a secret token for access control.
+     * The secret must be stored client-side (cookie/local storage) and sent
+     * with subsequent requests to identify the cart owner.
+     */
+    async createGuestCart(currency = "USD", ctx) {
+        const secret = crypto.randomUUID();
+        const ttlMinutes = this.deps.config.cart?.ttlMinutes ?? 60 * 24 * 7;
+        const now = new Date();
+        const cart = await this.repo.create({
+            organizationId: resolveOrgId(null),
+            customerId: undefined,
+            status: "active",
+            currency,
+            secret,
+            metadata: {},
+            expiresAt: new Date(now.getTime() + ttlMinutes * 60 * 1000),
+        }, ctx);
+        return Ok({ cart, secret });
+    }
+    /**
+     * Merges a guest (source) cart into an authenticated (target) cart on login.
+     * Uses addItem() internally so CartItemMatcher deduplication is applied.
+     * The source cart's secret must be provided for access control.
+     */
+    async mergeCarts(targetCartId, sourceCartId, sourceSecret, actor, ctx) {
+        const orgId = resolveOrgId(actor);
+        const sourceCart = await this.repo.findById(orgId, sourceCartId, ctx);
+        if (!sourceCart || sourceCart.secret !== sourceSecret) {
+            return Err(new CommerceValidationError("Invalid cart or cart secret."));
+        }
+        const targetCart = await this.repo.findById(orgId, targetCartId, ctx);
+        if (!targetCart) {
+            return Err(new CommerceNotFoundError("Target cart not found."));
+        }
+        const sourceItems = await this.repo.findLineItemsByCartId(sourceCartId, ctx);
+        for (const item of sourceItems) {
+            await this.addItem({
+                cartId: targetCartId,
+                entityId: item.entityId,
+                quantity: item.quantity,
+                ...(item.variantId != null ? { variantId: item.variantId } : {}),
+                unitPriceSnapshot: item.unitPriceSnapshot,
+                currency: item.currency,
+                metadata: item.metadata ?? {},
+            }, actor, ctx);
+        }
+        // Mark source cart as merged
+        await this.repo.updateStatus(sourceCartId, "merged", ctx);
+        const mergedCart = await this.repo.findById(orgId, targetCartId, ctx);
+        return Ok(mergedCart);
+    }
+    /**
+     * Resolves the actor's customer profile UUID.
+     * Returns null if actor is anonymous or has no associated customer profile.
+     * Cart.customerId is bound to the customer profile UUID, not the Better
+     * Auth user.id, so ownership checks must resolve the profile first.
+     */
+    async resolveActorCustomerId(actor, ctx) {
+        if (!actor?.userId)
+            return null;
+        const customers = this.deps.services.customers;
+        if (!customers?.getByUserId)
+            return null;
+        const result = await customers.getByUserId(actor.userId, actor, ctx);
+        return result.ok ? result.value.id : null;
+    }
+    /**
+     * Cart-write ownership policy (used by addItem, updateQuantity, removeItem):
+     *   - Admin/staff (permissions include *:*) — bypass.
+     *   - Customer role: cart.customerId must match the actor's customer
+     *     profile UUID. Without this match, customer B was able to write
+     *     to customer A's cart by UUID (claude-glm finding).
+     *   - Guest cart (customerId null): only the cart-secret holder may write.
+     *     Without a presented secret, deny — the previous "anyone can write
+     *     to a guest cart" behavior allowed cross-customer hijack of the
+     *     post-A1-fix orphan carts.
+     */
+    async assertCartOwnership(actor, cart, ctx, presentedSecret) {
+        if (actor && actor.permissions.includes("*:*"))
+            return;
+        // Staff / admin / ai_agent / service may modify any cart in their org
+        // (POS, AI assist). They already cleared cart:update at the entry to
+        // the calling method.
+        const STAFF = new Set(["staff", "admin", "owner", "ai_agent", "service"]);
+        const role = actor?.role;
+        if (actor && role && STAFF.has(role))
+            return;
+        if (cart.customerId == null) {
+            // Guest cart — must present the cart secret to write.
+            if (presentedSecret && cart.secret && presentedSecret === cart.secret) {
+                return;
+            }
+            throw new CommerceForbiddenError("Cart secret required to modify guest cart.");
+        }
+        if (!actor) {
+            throw new CommerceForbiddenError("Authentication required to modify customer cart.");
+        }
+        const profileId = await this.resolveActorCustomerId(actor, ctx);
+        if (profileId !== cart.customerId) {
+            throw new CommerceForbiddenError("You do not have access to this resource.");
+        }
+    }
+    /**
+     * Cart-read access policy:
+     *   - *:* permission — bypass (admins).
+     *   - Customer cart (customerId set): authenticated actor's customer
+     *     profile UUID must match cart.customerId.
+     *   - Guest cart (customerId null): require the presented cart secret
+     *     to match, OR a staff/admin/agent actor with cart:read.
+     *   - Anonymous + customer cart, OR no secret + guest cart: forbidden.
+     */
+    async assertCartReadAccess(actor, cart, presentedSecret, ctx) {
+        if (actor && actor.permissions.includes("*:*"))
+            return;
+        if (cart.customerId != null) {
+            if (!actor) {
+                throw new CommerceForbiddenError("Authentication required to read customer cart.");
+            }
+            const profileId = await this.resolveActorCustomerId(actor, ctx);
+            if (profileId !== cart.customerId) {
+                throw new CommerceForbiddenError("You do not have access to this resource.");
+            }
+            return;
+        }
+        // Guest cart — secret-gated.
+        if (presentedSecret && cart.secret && presentedSecret === cart.secret) {
+            return;
+        }
+        // Staff / admin / ai_agent / service may inspect any guest cart with cart:read.
+        if (actor) {
+            try {
+                assertPermission(actor, "cart:read");
+                const role = actor.role;
+                const STAFF = new Set(["staff", "admin", "owner", "ai_agent", "service"]);
+                if (role && STAFF.has(role))
+                    return;
+            }
+            catch {
+                // fall through to forbidden
+            }
+        }
+        throw new CommerceForbiddenError("Cart secret required to access guest cart.");
+    }
+}

package/dist/modules/catalog/brand-service.d.ts

@@ -0,0 +1,18 @@
+import type { Actor } from "../../auth/types.js";
+import { type Result } from "../../kernel/result.js";
+import type { TxContext } from "../../kernel/database/tx-context.js";
+import type { CatalogServiceDeps, CreateBrandInput, UpdateBrandInput } from "./service.js";
+import type { Brand } from "./repository/index.js";
+export declare class BrandService {
+    private readonly deps;
+    constructor(deps: CatalogServiceDeps);
+    private get repo();
+    private assertSameOrg;
+    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, actor: Actor | null, ctx?: TxContext): Promise<Result<void>>;
+    removeFromBrand(entityId: string, brandId: string, actor: Actor | null, ctx?: TxContext): Promise<Result<void>>;
+}
+//# sourceMappingURL=brand-service.d.ts.map

package/dist/modules/catalog/brand-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"brand-service.d.ts","sourceRoot":"","sources":["../../../src/modules/catalog/brand-service.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AAMjD,OAAO,EAAW,KAAK,MAAM,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qCAAqC,CAAC;AACrE,OAAO,KAAK,EACV,kBAAkB,EAClB,gBAAgB,EAChB,gBAAgB,EACjB,MAAM,cAAc,CAAC;AACtB,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,uBAAuB,CAAC;AACnD,qBAAa,YAAY;IACX,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAAJ,IAAI,EAAE,kBAAkB;IAErD,OAAO,KAAK,IAAI,GAEf;IAED,OAAO,CAAC,aAAa;IAQf,UAAU,CAAC,GAAG,CAAC,EAAE,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC;IAKrD,WAAW,CAAC,KAAK,EAAE,gBAAgB,EAAE,KAAK,EAAE,KAAK,GAAG,IAAI,EAAE,GAAG,CAAC,EAAE,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAYlG,WAAW,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,gBAAgB,EAAE,KAAK,EAAE,KAAK,GAAG,IAAI,EAAE,GAAG,CAAC,EAAE,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAc9G,WAAW,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,GAAG,IAAI,EAAE,GAAG,CAAC,EAAE,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAUpF,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,GAAG,IAAI,EAAE,GAAG,CAAC,EAAE,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAgB1G,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,GAAG,IAAI,EAAE,GAAG,CAAC,EAAE,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;CAYtH"}