@porulle/core 0.11.0 → 0.14.0

package/src/modules/catalog/entity-service.ts

@@ -1,4 +1,4 @@
-import { resolveOrgId } from "../../auth/org.js";
+import { resolveOrgIdForCommerce } from "../../auth/org.js";
 import { assertPermission } from "../../auth/permissions.js";
 import type { Actor } from "../../auth/types.js";
 import {
@@ -21,8 +21,12 @@ import type {
 import { Err, Ok, type Result } from "../../kernel/result.js";
 import { createLogger } from "../../utils/logger.js";
 import { paginate } from "../../utils/pagination.js";
+import type { JobsAdapter } from "../../kernel/jobs/adapter.js";
 import type { PluginDb } from "../../kernel/database/plugin-types.js";
-import type { TxContext } from "../../kernel/database/tx-context.js";
+import type { CatalogWriteContext, TxContext } from "../../kernel/database/tx-context.js";
+import { isWriteContextTransactional } from "../../kernel/database/tx-context.js";
+import { canReadUnpublishedCatalog, isCatalogEntityVisible } from "./read-policy.js";
+import { isValidFieldPath } from "./ownership.js";
 import type {
   CatalogServiceDeps,
   CatalogEntityHydrated,
@@ -52,6 +56,26 @@ function hookDatabaseArg(database: CatalogServiceDeps["database"]): { database:
   return { database: { db: database.db as PluginDb } };
 }
 
+const attributeFields = ["title", "subtitle", "description", "richDescription", "seoTitle", "seoDescription"] as const;
+
+function catalogHookContext(
+  deps: CatalogServiceDeps,
+  actor: Actor | null,
+  ctx: CatalogWriteContext | undefined,
+  operation: string,
+): HookContext {
+  return createHookContext({
+    actor,
+    tx: isWriteContextTransactional(ctx) ? ctx.tx : null,
+    logger: createLogger(`catalog.${operation}`),
+    services: deps.services,
+    ...(deps.services.jobs ? { jobs: deps.services.jobs as JobsAdapter } : {}),
+    context: { moduleName: "catalog", ...(ctx?.hookContext ?? {}) },
+    ...hookDatabaseArg(deps.database),
+    commerceConfig: deps.config,
+  });
+}
+
 type CatalogCreateBeforeHook = BeforeHook<CreateEntityInput>;
 type CatalogCreateAfterHook = AfterHook<SellableEntity>;
 type CatalogUpdateBeforeHook = BeforeHook<UpdateEntityInput>;
@@ -100,7 +124,7 @@ export class EntityService {
 
   private assertSameOrg(resource: { organizationId?: string | null } | undefined, actor: Actor | null): void {
     if (!resource) return;
-    const orgId = resolveOrgId(actor);
+    const orgId = resolveOrgIdForCommerce(actor, this.deps.config);
     if (resource.organizationId && resource.organizationId !== orgId) {
       throw new CommerceNotFoundError("Entity not found.");
     }
@@ -256,12 +280,12 @@ export class EntityService {
 
   async create(input: CreateEntityInput, actor: Actor | null, ctx?: TxContext): Promise<Result<CatalogEntityHydrated>> { try {
     assertPermission(actor, "catalog:create");
-    const orgId = resolveOrgId(actor);
+    const orgId = resolveOrgIdForCommerce(actor, this.deps.config);
     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 context: HookContext = createHookContext({ actor, tx: ctx?.tx ?? null, logger: createLogger("catalog.create"), services: this.deps.services, context: { moduleName: "catalog" }, ...hookDatabaseArg(this.deps.database) });
+    const context: HookContext = createHookContext({ actor, tx: ctx?.tx ?? null, logger: createLogger("catalog.create"), services: this.deps.services, context: { moduleName: "catalog" }, ...hookDatabaseArg(this.deps.database), commerceConfig: this.deps.config });
     const processedInput = await runBeforeHooks(beforeHooks, input, "create", context);
     if (processedInput.sourceStoreId != null) assertPermission(actor, "catalog:sync");
     const customFieldsResult = await this.validateCustomFields(processedInput.type, processedInput.customFields, actor, ctx);
@@ -278,23 +302,24 @@ export class EntityService {
     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 {
+  async update(id: string, input: UpdateEntityInput, actor: Actor | null, ctx?: CatalogWriteContext): Promise<Result<CatalogEntityHydrated>> { try {
+    const txCtx = isWriteContextTransactional(ctx) ? ctx : undefined;
     assertPermission(actor, "catalog:update");
-    const existing = await this.repo.findEntityById(id, ctx);
+    const existing = await this.repo.findEntityById(id, txCtx);
     if (!existing) return Err(new CommerceNotFoundError("Entity not found."));
     this.assertSameOrg(existing, actor);
     this.assertEntityWritable(existing, actor);
     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, context: { moduleName: "catalog" }, ...hookDatabaseArg(this.deps.database) });
+    const context: HookContext = catalogHookContext(this.deps, actor, ctx, "update");
     const processed = await runBeforeHooks(beforeHooks, input, "update", context);
-    const customFieldsResult = await this.validateCustomFields(existing.type, processed.customFields, actor, ctx);
+    const customFieldsResult = await this.validateCustomFields(existing.type, processed.customFields, actor, txCtx);
     if (!customFieldsResult.ok) return customFieldsResult;
-    const updated = await this.repo.updateEntity(id, { ...(processed.slug !== undefined ? { slug: processed.slug } : {}), ...(processed.status !== undefined ? { status: processed.status as SellableEntity["status"] } : {}), ...(processed.taxClass !== undefined ? { taxClass: processed.taxClass } : {}), ...(processed.metadata !== undefined ? { metadata: processed.metadata } : {}), ...(processed.isVisible !== undefined ? { isVisible: processed.isVisible } : {}) }, ctx);
+    const updated = await this.repo.updateEntity(id, { ...(processed.slug !== undefined ? { slug: processed.slug } : {}), ...(processed.status !== undefined ? { status: processed.status as SellableEntity["status"] } : {}), ...(processed.taxClass !== undefined ? { taxClass: processed.taxClass } : {}), ...(processed.metadata !== undefined ? { metadata: processed.metadata } : {}), ...(processed.isVisible !== undefined ? { isVisible: processed.isVisible } : {}) }, txCtx);
     if (!updated) return Err(new CommerceNotFoundError("Entity not found."));
-    await this.writeCustomFields(existing.id, customFieldsResult.value, ctx, true);
+    await this.writeCustomFields(existing.id, customFieldsResult.value, txCtx, true);
     const hookReport = await runAfterHooks(afterHooks, existing, updated, "update", context);
-    const hydrated = await this.hydrateEntity(updated, undefined, ctx);
+    const hydrated = await this.hydrateEntity(updated, undefined, txCtx);
     return Ok(hydrated, hookReport.hasErrors ? { hookErrors: hookReport.errors } : undefined);
   } catch (error) { return Err(toCommerceError(error)); } }
 
@@ -314,24 +339,27 @@ export class EntityService {
     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, context: { moduleName: "catalog" }, ...hookDatabaseArg(this.deps.database) });
+  async getById(id: string, options: GetOptions | undefined, actor: Actor | null, ctx?: TxContext): Promise<Result<CatalogEntityHydrated>> {
+    const resolvedActor = actor ?? ctx?.actor ?? null;
+    const orgId = resolveOrgIdForCommerce(resolvedActor, this.deps.config);
+    const context: HookContext = createHookContext({ actor: resolvedActor, tx: ctx?.tx ?? null, logger: createLogger("catalog.read"), services: this.deps.services, context: { moduleName: "catalog" }, ...hookDatabaseArg(this.deps.database), commerceConfig: this.deps.config });
     const globalBeforeHooks = this.deps.hooks.resolve("catalog.beforeRead") as CatalogReadBeforeHook[];
     const globalAfterHooks = this.deps.hooks.resolve("catalog.afterRead") as CatalogReadAfterHook[];
     let processed = await runBeforeHooks(globalBeforeHooks, { id, ...(options !== undefined ? { options } : {}) }, "read", context);
-    let entity = await this.repo.findEntityById(processed.id ?? id, ctx);
+    let entity = await this.repo.findEntityById(processed.id ?? id, ctx, orgId);
     if (!entity) return Err(new CommerceNotFoundError("Entity not found."));
+    if (!isCatalogEntityVisible(entity, resolvedActor)) return Err(new CommerceNotFoundError("Entity not found."));
     const entityBeforeHooks = this.deps.hooks.resolve(`catalog.${entity.type}.beforeRead`) as CatalogReadBeforeHook[];
     if (entityBeforeHooks.length > 0) {
       processed = await runBeforeHooks(entityBeforeHooks, { ...processed, id: entity.id }, "read", context);
       const resolvedId = processed.id ?? entity.id;
       if (resolvedId !== entity.id) {
-        const refetched = await this.repo.findEntityById(resolvedId, ctx);
+        const refetched = await this.repo.findEntityById(resolvedId, ctx, orgId);
         if (!refetched) return Err(new CommerceNotFoundError("Entity not found."));
+        if (!isCatalogEntityVisible(refetched, resolvedActor)) return Err(new CommerceNotFoundError("Entity not found."));
         entity = refetched;
       }
     }
-    const resolvedActor = actor ?? ctx?.actor ?? null;
     try {
       this.assertSameOrg(entity, resolvedActor);
     } catch (error) {
@@ -343,28 +371,48 @@ export class EntityService {
     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, context: { moduleName: "catalog" }, ...hookDatabaseArg(this.deps.database) });
+  /**
+   * Reads an entity for a trusted server pipeline after the request boundary
+   * has already authorized the caller. Organization scope is explicit; the
+   * storefront visibility policy is intentionally not applied, so an internal
+   * invariant check never depends on the caller's catalog permissions.
+   */
+  async getByIdForInternalUse(
+    id: string,
+    organizationId: string,
+    options?: GetOptions,
+    ctx?: TxContext,
+  ): Promise<Result<CatalogEntityHydrated>> {
+    const entity = await this.repo.findEntityById(id, ctx, organizationId);
+    if (!entity) return Err(new CommerceNotFoundError("Entity not found."));
+    return Ok(await this.hydrateEntity(entity, options, ctx));
+  }
+
+  async getBySlug(slug: string, options: GetOptions | undefined, 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, context: { moduleName: "catalog" }, ...hookDatabaseArg(this.deps.database), commerceConfig: this.deps.config });
     const globalBeforeHooks = this.deps.hooks.resolve("catalog.beforeRead") as CatalogReadBeforeHook[];
     const globalAfterHooks = this.deps.hooks.resolve("catalog.afterRead") as CatalogReadAfterHook[];
     let processed = await runBeforeHooks(globalBeforeHooks, { slug, ...(options !== undefined ? { options } : {}) }, "read", context);
     let resolvedSlug = processed.slug ?? slug;
-    const orgId = resolveOrgId(actor ?? null);
+    const orgId = resolveOrgIdForCommerce(actor ?? null, this.deps.config);
     let entity = await this.repo.findEntityBySlug(orgId, resolvedSlug, ctx);
     if (!entity) return Err(new CommerceNotFoundError("Entity not found."));
+    if (!isCatalogEntityVisible(entity, actor ?? null)) return Err(new CommerceNotFoundError("Entity not found."));
     const entityBeforeHooks = this.deps.hooks.resolve(`catalog.${entity.type}.beforeRead`) as CatalogReadBeforeHook[];
     if (entityBeforeHooks.length > 0) {
       processed = await runBeforeHooks(entityBeforeHooks, { ...processed, id: entity.id }, "read", context);
       const nextId = processed.id ?? entity.id;
       const nextSlug = processed.slug ?? resolvedSlug;
       if (nextId !== entity.id) {
-        const refetched = await this.repo.findEntityById(nextId, ctx);
+        const refetched = await this.repo.findEntityById(nextId, ctx, orgId);
         if (!refetched) return Err(new CommerceNotFoundError("Entity not found."));
+        if (!isCatalogEntityVisible(refetched, actor ?? null)) return Err(new CommerceNotFoundError("Entity not found."));
         entity = refetched;
         resolvedSlug = nextSlug;
       } else if (nextSlug !== resolvedSlug) {
         const refetched = await this.repo.findEntityBySlug(orgId, nextSlug, ctx);
         if (!refetched) return Err(new CommerceNotFoundError("Entity not found."));
+        if (!isCatalogEntityVisible(refetched, actor ?? null)) return Err(new CommerceNotFoundError("Entity not found."));
         entity = refetched;
       }
     }
@@ -374,9 +422,9 @@ export class EntityService {
     return Ok(result, report.hasErrors ? { hookErrors: report.errors } : undefined);
   }
 
-  async list(params: ListParams, actor?: Actor | null, ctx?: TxContext): Promise<Result<CatalogListResult>> {
+  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, context: { moduleName: "catalog" }, ...hookDatabaseArg(this.deps.database) });
+    const context: HookContext = createHookContext({ actor: resolvedActor, tx: ctx?.tx ?? null, logger: createLogger("catalog.list"), services: this.deps.services, context: { moduleName: "catalog" }, ...hookDatabaseArg(this.deps.database), commerceConfig: this.deps.config });
     const globalBeforeHooks = this.deps.hooks.resolve("catalog.beforeList") as CatalogListBeforeHook[];
     const globalAfterHooks = this.deps.hooks.resolve("catalog.afterList") as CatalogListAfterHook[];
     let processed = await runBeforeHooks(globalBeforeHooks, params, "list", context);
@@ -385,20 +433,28 @@ export class EntityService {
       const entityBeforeHooks = this.deps.hooks.resolve(`catalog.${initialTypeFilter}.beforeList`) as CatalogListBeforeHook[];
       if (entityBeforeHooks.length > 0) processed = await runBeforeHooks(entityBeforeHooks, processed, "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);
+    const listOrgId = resolveOrgIdForCommerce(resolvedActor, this.deps.config);
+    const canReadUnpublished = canReadUnpublishedCatalog(resolvedActor);
+    let entities = await this.repo.findEntities(listOrgId, {
+      ...(processed.filter?.type ? { type: processed.filter.type } : {}),
+      ...(canReadUnpublished
+        ? (processed.filter?.status ? { status: processed.filter.status } : {})
+        : { status: "active", isVisible: true }),
+    }, ctx);
+    const isUUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
     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 && isUUID.test(catInput)) category = await this.repo.findCategoryById(catInput, ctx, listOrgId);
       if (!category) return Err(new CommerceValidationError(`Category not found: "${catInput}".`));
       const entityIds = await this.repo.findEntitiesByCategory(category.id, ctx);
       entities = entities.filter((e) => new Set(entityIds).has(e.id));
     }
     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 && isUUID.test(processed.filter.brand)) {
+        brand = await this.repo.findBrandById(processed.filter.brand, ctx, listOrgId);
+      }
       if (brand) {
         const brandEntityIds: string[] = [];
         for (const entity of entities) {
@@ -454,19 +510,45 @@ export class EntityService {
   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, actor: Actor | null, ctx?: TxContext): Promise<Result<void>> {
+  async setAttributes(entityId: string, locale: string, attrs: SetAttributesInput, actor: Actor | null, ctx?: CatalogWriteContext): Promise<Result<void>> {
     try { assertPermission(actor, "catalog:update"); } catch (error) { return Err(toCommerceError(error)); }
-    const entity = await this.repo.findEntityById(entityId, ctx);
+    const txCtx = isWriteContextTransactional(ctx) ? ctx : undefined;
+    const entity = await this.repo.findEntityById(entityId, txCtx);
     if (!entity) return Err(new CommerceNotFoundError("Entity not found."));
     try { this.assertSameOrg(entity, actor); } catch (error) { return Err(toCommerceError(error)); }
-    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);
+    const beforeAttr = await this.repo.findAttributeByLocale(entityId, locale, txCtx);
+    const changedFieldPaths: string[] = [];
+    for (const field of attributeFields) {
+      if (attrs[field] === undefined) continue;
+      const before = beforeAttr?.[field] ?? null;
+      const after = attrs[field] ?? null;
+      if (before !== after) {
+        const path = `attributes.${locale}.${field}`;
+        if (isValidFieldPath(path)) changedFieldPaths.push(path);
+      }
+    }
+    await this.repo.upsertAttribute(entityId, locale, { title: attrs.title, subtitle: attrs.subtitle, description: attrs.description, richDescription: attrs.richDescription, seoTitle: attrs.seoTitle, seoDescription: attrs.seoDescription }, txCtx);
+    if (changedFieldPaths.length > 0) {
+      const afterHooks = this.deps.hooks.resolve("catalog.afterUpdate") as CatalogUpdateAfterHook[];
+      const context = catalogHookContext(this.deps, actor, ctx, "update");
+      context.context.changedFieldPaths = changedFieldPaths;
+      await runAfterHooks(afterHooks, entity, entity, "update", context);
+    }
     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 getAttributes(entityId: string, locale: string, actor: Actor | null, ctx?: TxContext): Promise<Result<SellableAttribute>> {
+    try {
+      assertPermission(actor, "catalog:read");
+      const entity = await this.repo.findEntityById(entityId, ctx, resolveOrgIdForCommerce(actor, this.deps.config));
+      if (!entity) return Err(new CommerceNotFoundError("Entity not found."));
+      if (!isCatalogEntityVisible(entity, actor)) return Err(new CommerceNotFoundError("Entity not found."));
+      const attr = await this.repo.findAttributeByLocale(entity.id, locale, ctx);
+      if (!attr) return Err(new CommerceNotFoundError(`Attributes for locale ${locale} not found.`));
+      return Ok(attr);
+    } catch (error) {
+      return Err(toCommerceError(error));
+    }
   }
 
   async createOptionType(input: CreateOptionTypeInput, actor: Actor | null, ctx?: TxContext): Promise<Result<OptionType>> {

package/src/modules/catalog/read-policy.ts

@@ -0,0 +1,16 @@
+import { hasPermission } from "../../auth/permissions.js";
+import type { Actor } from "../../auth/types.js";
+
+type CatalogVisibility = {
+  status: string;
+  isVisible: boolean;
+};
+
+export function canReadUnpublishedCatalog(actor: Actor | null): boolean {
+  return hasPermission(actor, "catalog:read:unpublished");
+}
+
+export function isCatalogEntityVisible(entity: CatalogVisibility, actor: Actor | null): boolean {
+  return canReadUnpublishedCatalog(actor) ||
+    (entity.status === "active" && entity.isVisible);
+}

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

@@ -124,6 +124,7 @@ export class CatalogRepository {
     filter?: {
       type?: string;
       status?: string;
+      isVisible?: boolean;
       ids?: string[];
     },
     ctx?: TxContext,
@@ -139,6 +140,9 @@ export class CatalogRepository {
         eq(sellableEntities.status, filter.status as SellableEntity["status"]),
       );
     }
+    if (filter?.isVisible !== undefined) {
+      conditions.push(eq(sellableEntities.isVisible, filter.isVisible));
+    }
     if (filter?.ids && filter.ids.length > 0) {
       conditions.push(inArray(sellableEntities.id, filter.ids));
     }
@@ -811,12 +815,17 @@ export class CatalogRepository {
   async findCategoryById(
     id: string,
     ctx?: TxContext,
+    orgId?: string,
   ): Promise<Category | undefined> {
     const db = this.getDb(ctx);
     const rows = await db
       .select()
       .from(categories)
-      .where(eq(categories.id, id));
+      .where(
+        orgId
+          ? and(eq(categories.id, id), eq(categories.organizationId, orgId))
+          : eq(categories.id, id),
+      );
     return rows[0];
   }
 
@@ -963,9 +972,16 @@ export class CatalogRepository {
   // Brands
   // ─────────────────────────────────────────────────────────────────────────────
 
-  async findBrandById(id: string, ctx?: TxContext): Promise<Brand | undefined> {
+  async findBrandById(id: string, ctx?: TxContext, orgId?: string): Promise<Brand | undefined> {
     const db = this.getDb(ctx);
-    const rows = await db.select().from(brands).where(eq(brands.id, id));
+    const rows = await db
+      .select()
+      .from(brands)
+      .where(
+        orgId
+          ? and(eq(brands.id, id), eq(brands.organizationId, orgId))
+          : eq(brands.id, id),
+      );
     return rows[0];
   }
 

package/src/modules/catalog/service.ts

@@ -1,5 +1,5 @@
 import type { Actor } from "../../auth/types.js";
-import { resolveOrgId } from "../../auth/org.js";
+import { resolveOrgIdForCommerce } from "../../auth/org.js";
 import { assertPermission } from "../../auth/permissions.js";
 import type { CommerceConfig } from "../../config/types.js";
 import type { EntityFieldDefinition, FieldType } from "../../config/types.js";
@@ -8,7 +8,7 @@ import { Err, Ok, type Result } from "../../kernel/result.js";
 import { CommerceConflictError, CommerceNotFoundError, CommerceValidationError, toCommerceError } from "../../kernel/errors.js";
 import type { Pagination } from "../../utils/pagination.js";
 import type { DatabaseAdapter } from "../../kernel/database/adapter.js";
-import { createTxContext, type TxContext } from "../../kernel/database/tx-context.js";
+import { createTxContext, type CatalogWriteContext, isWriteContextTransactional, resolveWriteContextHookContext, type TxContext } from "../../kernel/database/tx-context.js";
 import {
   CatalogRepository,
   type SellableEntity,
@@ -159,7 +159,7 @@ export interface CatalogService {
     id: string,
     input: UpdateEntityInput,
     actor: Actor | null,
-    ctx?: TxContext,
+    ctx?: CatalogWriteContext,
   ): Promise<Result<CatalogEntityHydrated>>;
   delete(
     id: string,
@@ -168,17 +168,23 @@ export interface CatalogService {
   ): Promise<Result<void>>;
   getById(
     id: string,
+    options: GetOptions | undefined,
+    actor: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<CatalogEntityHydrated>>;
+  getByIdForInternalUse(
+    id: string,
+    organizationId: string,
     options?: GetOptions,
-    actor?: Actor | null,
     ctx?: TxContext,
   ): Promise<Result<CatalogEntityHydrated>>;
   getBySlug(
     slug: string,
-    options?: GetOptions,
-    actor?: Actor | null,
+    options: GetOptions | undefined,
+    actor: Actor | null,
     ctx?: TxContext,
   ): Promise<Result<CatalogEntityHydrated>>;
-  list(params: ListParams, actor?: Actor | null, ctx?: TxContext): Promise<Result<CatalogListResult>>;
+  list(params: ListParams, actor: Actor | null, ctx?: TxContext): Promise<Result<CatalogListResult>>;
   /** Returns undefined when no concrete ownership row applies to the field. */
   resolveFieldOwner(
     entityId: string,
@@ -234,7 +240,7 @@ export interface CatalogService {
     locale: string,
     attrs: SetAttributesInput,
     actor: Actor | null,
-    ctx?: TxContext,
+    ctx?: CatalogWriteContext,
   ): Promise<Result<void>>;
   approveCustomField(
     entityId: string,
@@ -253,6 +259,7 @@ export interface CatalogService {
   getAttributes(
     entityId: string,
     locale: string,
+    actor: Actor | null,
     ctx?: TxContext,
   ): Promise<Result<SellableAttribute>>;
   listCategories(
@@ -470,7 +477,7 @@ export class CatalogServiceImpl implements CatalogService {
   ): Promise<EntityFieldDefinition[]> {
     const orgId = typeof actorOrOrg === "string"
       ? actorOrOrg
-      : resolveOrgId(actorOrOrg ?? ctx?.actor ?? null);
+      : resolveOrgIdForCommerce(actorOrOrg ?? ctx?.actor ?? null, this.config);
     const codeFields = this.config.entities?.[entityType]?.fields ?? [];
     const merged = new Map(codeFields.map((field) => [field.name, { ...field }]));
     const runtimeFields = await this.repository.findActiveEntityFieldDefinitions(orgId, entityType, ctx);
@@ -500,7 +507,7 @@ export class CatalogServiceImpl implements CatalogService {
     entityType?: string,
     ctx?: TxContext,
   ): Promise<Result<EntityFieldDefinitionRecord[]>> {
-    const orgId = resolveOrgId(actor ?? ctx?.actor ?? null);
+    const orgId = resolveOrgIdForCommerce(actor ?? ctx?.actor ?? null, this.config);
     return this.withMutationResult(actor ?? ctx?.actor ?? null, ctx, async (txCtx) =>
       Ok(await this.repository.findEntityFieldDefinitions(orgId, entityType, txCtx)),
     );
@@ -515,7 +522,7 @@ export class CatalogServiceImpl implements CatalogService {
       return Promise.resolve(Err(new CommerceValidationError("Entity type and field name are required.")));
     }
     assertPermission(actor, "catalog:update");
-    const orgId = resolveOrgId(actor ?? ctx?.actor ?? null);
+    const orgId = resolveOrgIdForCommerce(actor ?? ctx?.actor ?? null, this.config);
     return this.withMutationResult(actor, ctx, async (txCtx) => {
       const codeField = this.codeFieldDefinition(input.entityType, input.name);
       if (codeField && input.type !== codeField.type) {
@@ -553,7 +560,7 @@ export class CatalogServiceImpl implements CatalogService {
     ctx?: TxContext,
   ): Promise<Result<EntityFieldDefinitionRecord>> {
     assertPermission(actor, "catalog:update");
-    const orgId = resolveOrgId(actor ?? ctx?.actor ?? null);
+    const orgId = resolveOrgIdForCommerce(actor ?? ctx?.actor ?? null, this.config);
     return this.withMutationResult(actor, ctx, async (txCtx) => {
       const existing = await this.repository.findEntityFieldDefinitionById(orgId, id, txCtx);
       if (!existing) return Err(new CommerceNotFoundError("Entity field definition not found."));
@@ -584,7 +591,7 @@ export class CatalogServiceImpl implements CatalogService {
     ctx?: TxContext,
   ): Promise<Result<EntityFieldDefinitionRecord>> {
     assertPermission(actor, "catalog:update");
-    const orgId = resolveOrgId(actor ?? ctx?.actor ?? null);
+    const orgId = resolveOrgIdForCommerce(actor ?? ctx?.actor ?? null, this.config);
     return this.withMutationResult(actor, ctx, async (txCtx) => {
       const existing = await this.repository.findEntityFieldDefinitionById(orgId, id, txCtx);
       if (!existing) return Err(new CommerceNotFoundError("Entity field definition not found."));
@@ -600,13 +607,17 @@ export class CatalogServiceImpl implements CatalogService {
 
   private async withMutation<T>(
     actor: Actor | null,
-    ctx: TxContext | undefined,
+    ctx: CatalogWriteContext | undefined,
     fn: (txCtx: TxContext) => Promise<T>,
   ): Promise<T> {
-    if (ctx?.tx != null) return fn(ctx);
+    if (isWriteContextTransactional(ctx)) return fn(ctx);
+    const hookContext = resolveWriteContextHookContext(ctx);
     for (let attempt = 0; attempt < 3; attempt += 1) {
       try {
-        return await this.database.transaction(async (tx) => fn(createTxContext(tx, { actor })));
+        return await this.database.transaction(async (tx) => fn(createTxContext(tx, {
+          actor,
+          ...(hookContext ? { hookContext } : {}),
+        })));
       } catch (error) {
         if (!isUniqueViolation(error) || attempt === 2) throw error;
       }
@@ -616,7 +627,7 @@ export class CatalogServiceImpl implements CatalogService {
 
   private async withMutationResult<T>(
     actor: Actor | null,
-    ctx: TxContext | undefined,
+    ctx: CatalogWriteContext | undefined,
     fn: (txCtx: TxContext) => Promise<Result<T>>,
   ): Promise<Result<T>> {
     try {
@@ -640,7 +651,7 @@ export class CatalogServiceImpl implements CatalogService {
     const revisionActor = actor ?? ctx.actor;
     const organizationId = typeof snapshot.entity.organizationId === "string"
       ? snapshot.entity.organizationId
-      : resolveOrgId(revisionActor);
+      : resolveOrgIdForCommerce(revisionActor, this.config);
     return this.repository.createRevision({
       organizationId,
       entityId,
@@ -664,7 +675,7 @@ export class CatalogServiceImpl implements CatalogService {
         assertPermission(revisionActor, "catalog:update");
         const entity = await this.repository.findEntityById(entityId, txCtx);
         if (!entity) return Err(new CommerceNotFoundError("Entity not found."));
-        if (entity.organizationId !== resolveOrgId(revisionActor)) {
+        if (entity.organizationId !== resolveOrgIdForCommerce(revisionActor, this.config)) {
           return Err(new CommerceNotFoundError("Entity not found."));
         }
         return Ok(await this.captureRevision(entityId, revisionActor, reason, txCtx));
@@ -784,7 +795,7 @@ export class CatalogServiceImpl implements CatalogService {
         assertPermission(revisionActor, "catalog:update");
         const entity = await this.repository.findEntityById(entityId, txCtx);
         if (!entity) return Err(new CommerceNotFoundError("Entity not found."));
-        if (entity.organizationId !== resolveOrgId(revisionActor)) {
+        if (entity.organizationId !== resolveOrgIdForCommerce(revisionActor, this.config)) {
           return Err(new CommerceNotFoundError("Entity not found."));
         }
         if (entity.sourceStoreId != null) assertPermission(revisionActor, "catalog:sync");
@@ -816,7 +827,7 @@ export class CatalogServiceImpl implements CatalogService {
         const revisionActor = actor ?? txCtx.actor;
         assertPermission(revisionActor, "catalog:update");
         const cutoff = new Date(Date.now() - olderThanDays * 24 * 60 * 60 * 1000);
-        return Ok(await this.repository.deleteRevisionsOlderThan(resolveOrgId(revisionActor), cutoff, txCtx));
+        return Ok(await this.repository.deleteRevisionsOlderThan(resolveOrgIdForCommerce(revisionActor, this.config), cutoff, txCtx));
       });
     } catch (error) {
       return Err(toCommerceError(error));
@@ -831,7 +842,7 @@ export class CatalogServiceImpl implements CatalogService {
     });
   }
 
-  update(id: string, input: UpdateEntityInput, actor: Actor | null, ctx?: TxContext): Promise<Result<CatalogEntityHydrated>> {
+  update(id: string, input: UpdateEntityInput, actor: Actor | null, ctx?: CatalogWriteContext): Promise<Result<CatalogEntityHydrated>> {
     return this.withMutationResult(actor, ctx, async (txCtx) => {
       const result = await this.entities.update(id, input, actor, txCtx);
       if (result.ok) await this.captureRevision(id, actor, "update", txCtx);
@@ -843,15 +854,19 @@ export class CatalogServiceImpl implements CatalogService {
     return this.entities.delete(id, actor, ctx);
   }
 
-  getById(id: string, options?: GetOptions, actor?: Actor | null, ctx?: TxContext): Promise<Result<CatalogEntityHydrated>> {
+  getById(id: string, options: GetOptions | undefined, actor: Actor | null, ctx?: TxContext): Promise<Result<CatalogEntityHydrated>> {
     return this.entities.getById(id, options, actor, ctx);
   }
 
-  getBySlug(slug: string, options?: GetOptions, actor?: Actor | null, ctx?: TxContext): Promise<Result<CatalogEntityHydrated>> {
+  getByIdForInternalUse(id: string, organizationId: string, options?: GetOptions, ctx?: TxContext): Promise<Result<CatalogEntityHydrated>> {
+    return this.entities.getByIdForInternalUse(id, organizationId, options, ctx);
+  }
+
+  getBySlug(slug: string, options: GetOptions | undefined, actor: Actor | null, ctx?: TxContext): Promise<Result<CatalogEntityHydrated>> {
     return this.entities.getBySlug(slug, options, actor, ctx);
   }
 
-  list(params: ListParams, actor?: Actor | null, ctx?: TxContext): Promise<Result<CatalogListResult>> {
+  list(params: ListParams, actor: Actor | null, ctx?: TxContext): Promise<Result<CatalogListResult>> {
     return this.entities.list(params, actor, ctx);
   }
 
@@ -910,7 +925,7 @@ export class CatalogServiceImpl implements CatalogService {
       validateFieldPath(fieldPath);
       const entity = await this.repository.findEntityById(entityId, txCtx);
       if (!entity) return Err(new CommerceNotFoundError("Entity not found."));
-      if (entity.organizationId !== resolveOrgId(setter)) {
+      if (entity.organizationId !== resolveOrgIdForCommerce(setter, this.config)) {
         return Err(new CommerceNotFoundError("Entity not found."));
       }
       if (entity.sourceStoreId != null) assertPermission(setter, "catalog:sync");
@@ -937,7 +952,7 @@ export class CatalogServiceImpl implements CatalogService {
       assertPermission(reader, "catalog:read");
       const entity = await this.repository.findEntityById(entityId, txCtx);
       if (!entity) return Err(new CommerceNotFoundError("Entity not found."));
-      if (entity.organizationId !== resolveOrgId(reader)) {
+      if (entity.organizationId !== resolveOrgIdForCommerce(reader, this.config)) {
         return Err(new CommerceNotFoundError("Entity not found."));
       }
       return Ok(await this.repository.findFieldOwnership(entityId, txCtx, storeId));
@@ -989,7 +1004,7 @@ export class CatalogServiceImpl implements CatalogService {
     });
   }
 
-  setAttributes(entityId: string, locale: string, attrs: SetAttributesInput, actor: Actor | null, ctx?: TxContext): Promise<Result<void>> {
+  setAttributes(entityId: string, locale: string, attrs: SetAttributesInput, actor: Actor | null, ctx?: CatalogWriteContext): Promise<Result<void>> {
     return this.withMutationResult(actor, ctx, async (txCtx) => {
       const result = await this.entities.setAttributes(entityId, locale, attrs, actor, txCtx);
       if (result.ok) await this.captureRevision(entityId, actor, "update", txCtx);
@@ -1010,7 +1025,7 @@ export class CatalogServiceImpl implements CatalogService {
       assertPermission(reviewer, "catalog:update");
       const entity = await this.repository.findEntityById(entityId, txCtx);
       if (!entity) return Err(new CommerceNotFoundError("Entity not found."));
-      if (entity.organizationId !== resolveOrgId(reviewer)) {
+      if (entity.organizationId !== resolveOrgIdForCommerce(reviewer, this.config)) {
         return Err(new CommerceNotFoundError("Entity not found."));
       }
       if (entity.sourceStoreId != null) assertPermission(reviewer, "catalog:sync");
@@ -1057,8 +1072,8 @@ export class CatalogServiceImpl implements CatalogService {
     return this.reviewCustomField("rejected", entityId, fieldName, locale, actor, ctx);
   }
 
-  getAttributes(entityId: string, locale: string, ctx?: TxContext): Promise<Result<SellableAttribute>> {
-    return this.entities.getAttributes(entityId, locale, ctx);
+  getAttributes(entityId: string, locale: string, actor: Actor | null, ctx?: TxContext): Promise<Result<SellableAttribute>> {
+    return this.entities.getAttributes(entityId, locale, actor, ctx);
   }
 
   listCategories(ctx?: TxContext, opts?: { includeArchived?: boolean }): Promise<Result<CategorySummary[]>> {

package/src/modules/customers/module.ts

@@ -1,3 +1,4 @@
+import type { CommerceConfig } from "../../config/types.js";
 import type { DrizzleDatabase } from "../../kernel/database/drizzle-db.js";
 import { defineModule } from "../../kernel/module/index.js";
 import { CustomersRepository } from "./repository/index.js";
@@ -21,6 +22,7 @@ export const customersModule = defineModule({
     new CustomerService({
       repository: new CustomersRepository(deps.db.db as DrizzleDatabase),
       hooks: deps.hooks,
+      config: deps.config as CommerceConfig,
       services: deps.services,
       database: deps.db,
     }),