@porulle/core 0.10.8 → 0.13.0

package/src/modules/channels/adapter.ts

@@ -10,6 +10,7 @@ export interface ChannelConnectorCapabilities {
   readonly importCatalog: boolean;
   readonly importInventory: boolean;
   readonly pushOrder: boolean;
+  readonly pushCatalog?: boolean;
   readonly receiveWebhooks: boolean;
   readonly reserve?: boolean;
 }
@@ -24,11 +25,49 @@ export interface ChannelStore {
   webhookSecret: string | null;
 }
 
+export interface ChannelCatalogLocalizedAttributes {
+  locale: string;
+  title: string;
+  subtitle?: string;
+  description?: string;
+  richDescription?: unknown;
+  seoTitle?: string;
+  seoDescription?: string;
+}
+
+export interface ChannelCatalogImage {
+  externalId?: string;
+  url: string;
+  alt?: string;
+  role: "primary" | "gallery" | "thumbnail" | "video" | "document";
+  sortOrder?: number;
+  variantExternalIds?: string[];
+}
+
+export interface ChannelCatalogOptionType {
+  name: string;
+  displayName: string;
+  sortOrder?: number;
+  values: Array<{
+    value: string;
+    displayValue: string;
+    sortOrder?: number;
+  }>;
+}
+
+export interface ChannelCatalogPrice {
+  currency: string;
+  amount: number;
+  compareAtAmount?: number;
+}
+
 export interface ChannelCatalogVariant {
   externalId: string;
   sku?: string;
   barcode?: string;
   metadata?: Record<string, unknown>;
+  optionValues?: Record<string, string>;
+  prices?: ChannelCatalogPrice[];
 }
 
 export interface ChannelCatalogItem {
@@ -38,6 +77,13 @@ export interface ChannelCatalogItem {
   description?: string;
   variants: ChannelCatalogVariant[];
   metadata?: Record<string, unknown>;
+  attributes?: ChannelCatalogLocalizedAttributes[];
+  images?: ChannelCatalogImage[];
+  options?: ChannelCatalogOptionType[];
+  tags?: string[];
+  brand?: string;
+  categories?: string[];
+  status?: "draft" | "active" | "archived" | "discontinued";
 }
 
 export interface ChannelCatalogPage {
@@ -76,6 +122,54 @@ export interface ChannelPushOrderResult {
   remoteUrl?: string;
 }
 
+export type ChannelPushCatalogIntent = "filterable" | "display" | "tag";
+
+export interface ChannelPushCatalogField {
+  fieldPath: string;
+  intent: ChannelPushCatalogIntent;
+  value: unknown;
+  locale?: string;
+  remoteKey?: string;
+}
+
+export interface ChannelPushCatalogImage {
+  externalId?: string;
+  url: string;
+  alt?: string;
+  role: "primary" | "gallery" | "thumbnail" | "video" | "document";
+  sortOrder?: number;
+  variantExternalIds?: string[];
+}
+
+export interface ChannelPushCatalogVariant {
+  externalId: string;
+  fields: ChannelPushCatalogField[];
+}
+
+export interface ChannelPushCatalogItem {
+  externalId: string;
+  variants?: ChannelPushCatalogVariant[];
+  fields: ChannelPushCatalogField[];
+  images?: ChannelPushCatalogImage[];
+}
+
+export interface ChannelPushCatalogPreviousField {
+  fieldPath: string;
+  value: unknown;
+}
+
+export interface ChannelPushCatalogItemOutcome {
+  externalId: string;
+  ok: boolean;
+  error?: ChannelConnectorError;
+  remoteUpdatedAt?: string;
+  previousFields?: ChannelPushCatalogPreviousField[];
+}
+
+export interface ChannelPushCatalogResult {
+  outcomes: ChannelPushCatalogItemOutcome[];
+}
+
 export interface ChannelOrderStatus {
   status: "pending" | "confirmed" | "failed" | "cancelled" | "fulfilled";
 }
@@ -113,6 +207,11 @@ export interface ChannelConnector {
   importCatalog(store: ChannelStore, cursor?: string): Promise<Result<ChannelCatalogPage>>;
   fetchInventory(store: ChannelStore, ids?: string[]): Promise<Result<ChannelInventoryLevel[]>>;
   pushOrder(store: ChannelStore, slice: ChannelOrderSlice): Promise<Result<ChannelPushOrderResult, ChannelConnectorError>>;
+  pushCatalog?(
+    store: ChannelStore,
+    items: ChannelPushCatalogItem[],
+    opts?: { dryRun?: boolean },
+  ): Promise<Result<ChannelPushCatalogResult, ChannelConnectorError>>;
   fetchOrderStatus(store: ChannelStore, remoteId: string): Promise<Result<ChannelOrderStatus, ChannelConnectorError>>;
   verifyWebhook(store: ChannelStore, request: Request): Promise<Result<ChannelWebhookEvent>>;
   verifyAppWebhook?(
@@ -135,5 +234,12 @@ export interface ChannelConnector {
 }
 
 export function defineChannelConnector<T extends ChannelConnector>(connector: T): T {
-  return connector;
+  if (connector.capabilities.pushCatalog !== undefined) return connector;
+  return {
+    ...connector,
+    capabilities: {
+      ...connector.capabilities,
+      pushCatalog: false,
+    },
+  } as T;
 }

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,
     }),

package/src/modules/customers/service.ts

@@ -1,6 +1,7 @@
-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 type { CommerceConfig } from "../../config/types.js";
 import { CommerceNotFoundError, toCommerceError } from "../../kernel/errors.js";
 import { runAfterHooks } from "../../kernel/hooks/executor.js";
 import { createHookContext } from "../../kernel/hooks/create-context.js";
@@ -22,6 +23,7 @@ import type {
 interface CustomerServiceDeps {
   repository: CustomersRepository;
   hooks: HookRegistry;
+  config: CommerceConfig;
   services: Record<string, unknown>;
   database: DatabaseAdapter;
 }
@@ -30,6 +32,7 @@ function hookContext(
   actor: Actor | null,
   services: Record<string, unknown>,
   database: DatabaseAdapter,
+  config: CommerceConfig,
   tx: unknown,
 ): HookContext {
   return createHookContext({
@@ -39,6 +42,7 @@ function hookContext(
     services,
     context: { moduleName: "customers" },
     database: { db: database.db as PluginDb },
+    commerceConfig: config,
   });
 }
 
@@ -73,7 +77,7 @@ export class CustomerService {
       return Err(toCommerceError(error));
     }
 
-    const orgId = resolveOrgId(actor ?? ctx?.actor ?? null);
+    const orgId = resolveOrgIdForCommerce(actor ?? ctx?.actor ?? null, this.deps.config);
     const isWalkIn = input.userId === undefined;
     const userId = input.userId ?? `anonymous_${crypto.randomUUID()}`;
     const metadata = {
@@ -97,7 +101,7 @@ export class CustomerService {
     const afterHooks = this.deps.hooks.resolve(
       "customers.afterCreate",
     ) as AfterHook<Customer>[];
-    const hctx = hookContext(actor ?? null, this.deps.services, this.deps.database, ctx?.tx ?? null);
+    const hctx = hookContext(actor ?? null, this.deps.services, this.deps.database, this.deps.config, ctx?.tx ?? null);
     await runAfterHooks(afterHooks, null, customer, "create", hctx);
 
     return Ok(customer);
@@ -107,7 +111,7 @@ export class CustomerService {
 
   async listInteractions(customerId: string, actor?: Actor | null, ctx?: TxContext): Promise<Result<CustomerInteraction[]>> {
     try { assertPermission(actor ?? null, "customers:read"); } catch (error) { return Err(toCommerceError(error)); }
-    const orgId = resolveOrgId(actor ?? ctx?.actor ?? null);
+    const orgId = resolveOrgIdForCommerce(actor ?? ctx?.actor ?? null, this.deps.config);
     return Ok(await this.repo.listInteractions(orgId, customerId, ctx));
   }
 
@@ -118,7 +122,7 @@ export class CustomerService {
     ctx?: TxContext,
   ): Promise<Result<CustomerInteraction>> {
     try { assertPermission(actor ?? null, "customers:update"); } catch (error) { return Err(toCommerceError(error)); }
-    const orgId = resolveOrgId(actor ?? ctx?.actor ?? null);
+    const orgId = resolveOrgIdForCommerce(actor ?? ctx?.actor ?? null, this.deps.config);
     const customer = await this.repo.findById(orgId, customerId, ctx);
     if (!customer) return Err(new CommerceNotFoundError("Customer not found."));
     const interaction = await this.repo.createInteraction(
@@ -144,7 +148,7 @@ export class CustomerService {
     ctx?: TxContext,
   ): Promise<Result<CustomerInteraction>> {
     try { assertPermission(actor ?? null, "customers:update"); } catch (error) { return Err(toCommerceError(error)); }
-    const orgId = resolveOrgId(actor ?? ctx?.actor ?? null);
+    const orgId = resolveOrgIdForCommerce(actor ?? ctx?.actor ?? null, this.deps.config);
     const existing = await this.repo.findInteractionById(orgId, interactionId, ctx);
     if (!existing || existing.customerId !== customerId) return Err(new CommerceNotFoundError("Interaction not found."));
     const patch = {
@@ -160,7 +164,7 @@ export class CustomerService {
 
   async deleteInteraction(customerId: string, interactionId: string, actor?: Actor | null, ctx?: TxContext): Promise<Result<void>> {
     try { assertPermission(actor ?? null, "customers:update"); } catch (error) { return Err(toCommerceError(error)); }
-    const orgId = resolveOrgId(actor ?? ctx?.actor ?? null);
+    const orgId = resolveOrgIdForCommerce(actor ?? ctx?.actor ?? null, this.deps.config);
     const existing = await this.repo.findInteractionById(orgId, interactionId, ctx);
     if (!existing || existing.customerId !== customerId) return Err(new CommerceNotFoundError("Interaction not found."));
     await this.repo.deleteInteraction(orgId, interactionId, ctx);
@@ -190,7 +194,7 @@ export class CustomerService {
     const afterHooks = this.deps.hooks.resolve(
       "customers.afterCreate",
     ) as AfterHook<Customer>[];
-    const hctx = hookContext(actor, this.deps.services, this.deps.database, ctx?.tx ?? null);
+    const hctx = hookContext(actor, this.deps.services, this.deps.database, this.deps.config, ctx?.tx ?? null);
     await runAfterHooks(afterHooks, null, customer, "create", hctx);
 
     return customer;
@@ -200,7 +204,7 @@ export class CustomerService {
     actor?: Actor | null,
     ctx?: TxContext,
   ): Promise<Result<Customer[]>> {
-    const orgId = resolveOrgId(actor ?? ctx?.actor ?? null);
+    const orgId = resolveOrgIdForCommerce(actor ?? ctx?.actor ?? null, this.deps.config);
     const customers = await this.repo.findAll(orgId, ctx);
     return Ok(customers);
   }
@@ -210,7 +214,7 @@ export class CustomerService {
     actor?: Actor | null,
     ctx?: TxContext,
   ): Promise<Result<Customer>> {
-    const orgId = resolveOrgId(actor ?? ctx?.actor ?? null);
+    const orgId = resolveOrgIdForCommerce(actor ?? ctx?.actor ?? null, this.deps.config);
     const customer = await this.repo.findById(orgId, id, ctx);
     if (!customer) return Err(new CommerceNotFoundError("Customer not found."));
     return Ok(customer);
@@ -221,7 +225,7 @@ export class CustomerService {
     actor?: Actor | null,
     ctx?: TxContext,
   ): Promise<Result<Customer>> {
-    const orgId = resolveOrgId(actor ?? ctx?.actor ?? null);
+    const orgId = resolveOrgIdForCommerce(actor ?? ctx?.actor ?? null, this.deps.config);
     const resolvedActor = actor ?? ctx?.actor ?? null;
     const customer = await this.getOrCreateByUserId(
       orgId,
@@ -247,7 +251,7 @@ export class CustomerService {
       return Err(toCommerceError(error));
     }
 
-    const orgId = resolveOrgId(actor ?? ctx?.actor ?? null);
+    const orgId = resolveOrgIdForCommerce(actor ?? ctx?.actor ?? null, this.deps.config);
     const existing = await this.repo.findById(orgId, id, ctx);
     if (!existing) return Err(new CommerceNotFoundError("Customer not found."));
 
@@ -271,10 +275,7 @@ export class CustomerService {
       "customers.afterUpdate",
     ) as AfterHook<Customer>[];
     const hctx = hookContext(
-      actor ?? ctx?.actor ?? null,
-      this.deps.services,
-      this.deps.database,
-      ctx?.tx ?? null,
+      actor ?? ctx?.actor ?? null, this.deps.services, this.deps.database, this.deps.config, ctx?.tx ?? null,
     );
     await runAfterHooks(afterHooks, existing, updated, "update", hctx);
 
@@ -289,7 +290,7 @@ export class CustomerService {
     actor?: Actor | null,
     ctx?: TxContext,
   ): Promise<Result<Customer>> {
-    const orgId = resolveOrgId(actor ?? ctx?.actor ?? null);
+    const orgId = resolveOrgIdForCommerce(actor ?? ctx?.actor ?? null, this.deps.config);
     const resolvedActor = actor ?? ctx?.actor ?? null;
     const customer = await this.getOrCreateByUserId(
       orgId,
@@ -306,7 +307,7 @@ export class CustomerService {
     const afterHooks = this.deps.hooks.resolve(
       "customers.afterUpdate",
     ) as AfterHook<Customer>[];
-    const hctx = hookContext(resolvedActor, this.deps.services, this.deps.database, ctx?.tx ?? null);
+    const hctx = hookContext(resolvedActor, this.deps.services, this.deps.database, this.deps.config, ctx?.tx ?? null);
     await runAfterHooks(afterHooks, customer, updated, "update", hctx);
 
     return Ok(updated);
@@ -317,7 +318,7 @@ export class CustomerService {
     actor?: Actor | null,
     ctx?: TxContext,
   ): Promise<Result<CustomerAddress[]>> {
-    const orgId = resolveOrgId(actor ?? ctx?.actor ?? null);
+    const orgId = resolveOrgIdForCommerce(actor ?? ctx?.actor ?? null, this.deps.config);
     const resolvedActor = actor ?? ctx?.actor ?? null;
     const customer = await this.getOrCreateByUserId(
       orgId,
@@ -338,7 +339,7 @@ export class CustomerService {
     actor?: Actor | null,
     ctx?: TxContext,
   ): Promise<Result<CustomerAddress>> {
-    const orgId = resolveOrgId(actor ?? ctx?.actor ?? null);
+    const orgId = resolveOrgIdForCommerce(actor ?? ctx?.actor ?? null, this.deps.config);
     const resolvedActor = actor ?? ctx?.actor ?? null;
     const customer = await this.getOrCreateByUserId(
       orgId,
@@ -376,7 +377,7 @@ export class CustomerService {
     actor?: Actor | null,
     ctx?: TxContext,
   ): Promise<Result<void>> {
-    const orgId = resolveOrgId(actor ?? ctx?.actor ?? null);
+    const orgId = resolveOrgIdForCommerce(actor ?? ctx?.actor ?? null, this.deps.config);
     const resolvedActor = actor ?? ctx?.actor ?? null;
     const customer = await this.getOrCreateByUserId(
       orgId,
@@ -403,7 +404,7 @@ export class CustomerService {
     actor?: Actor | null,
     ctx?: TxContext,
   ): Promise<{ id: string; name: string } | null> {
-    const orgId = resolveOrgId(actor ?? ctx?.actor ?? null);
+    const orgId = resolveOrgIdForCommerce(actor ?? ctx?.actor ?? null, this.deps.config);
     const user = await this.repo.findByPosPin(orgId, hashedPin, ctx);
     if (!user) return null;
     return {

package/src/modules/documents/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 { DocumentsRepository } from "./repository/index.js";
@@ -15,5 +16,6 @@ export const documentsModule = defineModule<
     new DocumentsService({
       repository: new DocumentsRepository(deps.db.db as DrizzleDatabase),
       services: deps.services as Record<string, unknown>,
+      config: deps.config as CommerceConfig,
     }),
 });

package/src/modules/documents/service.ts

@@ -1,7 +1,9 @@
-import { resolveOrgId } from "../../auth/org.js";
+import { resolveOrgIdForCommerce } from "../../auth/org.js";
 import type { Actor } from "../../auth/types.js";
+import type { CommerceConfig } from "../../config/types.js";
 import type { TxContext } from "../../kernel/database/tx-context.js";
-import { CommerceValidationError } from "../../kernel/errors.js";
+import { hasPermission } from "../../auth/permissions.js";
+import { CommerceForbiddenError, CommerceValidationError } from "../../kernel/errors.js";
 import { Err, Ok, type Result } from "../../kernel/result.js";
 import type { HydratedOrder, OrderService } from "../orders/service.js";
 import type { SettingsService } from "../settings/service.js";
@@ -19,6 +21,15 @@ interface DocumentsServiceDeps {
   // The shared kernel service container — orders/settings/email are resolved
   // at call time (they may instantiate after this module).
   services: Record<string, unknown>;
+  config: CommerceConfig;
+}
+
+interface CustomerLookup {
+  getById(
+    id: string,
+    actor?: Actor | null,
+    ctx?: TxContext,
+  ): Promise<{ ok: true; value: { email: string | null } } | { ok: false }>;
 }
 
 interface EmailAdapter {
@@ -33,10 +44,12 @@ const DEFAULT_INVOICE_PREFIX = "INV-";
 export class DocumentsService {
   private repository: DocumentsRepository;
   private services: Record<string, unknown>;
+  private config: CommerceConfig;
 
   constructor(deps: DocumentsServiceDeps) {
     this.repository = deps.repository;
     this.services = deps.services;
+    this.config = deps.config;
   }
 
   private get orders(): OrderService {
@@ -90,16 +103,18 @@ export class DocumentsService {
     orderId: string,
     actor: Actor | null,
     ctx?: TxContext,
+    guestCredential?: string,
   ): Promise<Result<HydratedOrder>> {
-    return this.orders.getById(orderId, actor, ctx);
+    return this.orders.getById(orderId, actor, ctx, guestCredential);
   }
 
   async renderInvoiceHtml(
     orderId: string,
     actor: Actor | null,
     ctx?: TxContext,
+    guestCredential?: string,
   ): Promise<Result<{ html: string; invoiceNumber: string }>> {
-    const order = await this.loadOrder(orderId, actor, ctx);
+    const order = await this.loadOrder(orderId, actor, ctx, guestCredential);
     if (!order.ok) return order;
     const branding = await this.brandingFor(order.value.organizationId, ctx);
     const doc = await this.issueInvoiceNumber(order.value, ctx);
@@ -113,8 +128,9 @@ export class DocumentsService {
     orderId: string,
     actor: Actor | null,
     ctx?: TxContext,
+    guestCredential?: string,
   ): Promise<Result<{ pdf: Uint8Array; invoiceNumber: string }>> {
-    const order = await this.loadOrder(orderId, actor, ctx);
+    const order = await this.loadOrder(orderId, actor, ctx, guestCredential);
     if (!order.ok) return order;
     const branding = await this.brandingFor(order.value.organizationId, ctx);
     const doc = await this.issueInvoiceNumber(order.value, ctx);
@@ -130,39 +146,86 @@ export class DocumentsService {
     orderId: string,
     actor: Actor | null,
     ctx?: TxContext,
+    guestCredential?: string,
   ): Promise<Result<{ html: string }>> {
-    const order = await this.loadOrder(orderId, actor, ctx);
+    const order = await this.loadOrder(orderId, actor, ctx, guestCredential);
     if (!order.ok) return order;
     const branding = await this.brandingFor(order.value.organizationId, ctx);
     return Ok({ html: receiptHtml({ order: order.value, branding }) });
   }
 
+  /**
+   * The address that belongs to this order: its customer profile's email.
+   * A guest order has no customer profile and therefore no address of its own.
+   */
+  private async orderEmail(
+    order: HydratedOrder,
+    actor: Actor | null,
+    ctx?: TxContext,
+  ): Promise<string | null> {
+    if (!order.customerId) return null;
+    const customers = this.services.customers as CustomerLookup | undefined;
+    if (!customers) return null;
+    const customer = await customers.getById(order.customerId, actor, ctx);
+    return customer.ok ? (customer.value.email ?? null) : null;
+  }
+
   /**
    * Emails the invoice via the configured email adapter. The adapter's
    * template contract is (template, to, data) — the rendered HTML and the
    * fiscal number ride in `data` so template-based adapters can use either.
+   *
+   * The destination is the order's own address, not the caller's choice. A
+   * cart secret authorizes reading an order, and a caller-supplied `to` turned
+   * that read into delivery: items, totals and shipping address mailed to any
+   * address, with nothing left in the shopper's inbox. Only staff holding
+   * org-wide `orders:read` may name a different recipient.
    */
   async emailInvoice(
     orderId: string,
     to: string,
     actor: Actor | null,
     ctx?: TxContext,
+    guestCredential?: string,
   ): Promise<Result<{ sent: true; invoiceNumber: string; to: string }>> {
     const email = this.services.email as EmailAdapter | undefined;
     if (!email) {
       return Err(new CommerceValidationError("No email adapter is configured."));
     }
-    const rendered = await this.renderInvoiceHtml(orderId, actor, ctx);
+    const rendered = await this.renderInvoiceHtml(orderId, actor, ctx, guestCredential);
     if (!rendered.ok) return rendered;
 
-    const order = await this.loadOrder(orderId, actor, ctx);
+    const order = await this.loadOrder(orderId, actor, ctx, guestCredential);
     if (!order.ok) return order;
 
+    const ownAddress = await this.orderEmail(order.value, actor, ctx);
+    const mayDirect = hasPermission(actor, "orders:read");
+    const requested = to.trim();
+
+    let destination: string;
+    if (mayDirect && requested.length > 0) {
+      destination = requested;
+    } else if (ownAddress === null) {
+      return Err(
+        new CommerceValidationError(
+          "This order has no email address of its own. Render the invoice instead, or send it as staff.",
+        ),
+      );
+    } else if (requested.length > 0 && requested.toLowerCase() !== ownAddress.toLowerCase()) {
+      return Err(
+        new CommerceForbiddenError(
+          "An invoice can only be emailed to the address on the order.",
+        ),
+      );
+    } else {
+      destination = ownAddress;
+    }
+
     await email.send({
       template: "order-invoice",
-      to,
+      to: destination,
       data: {
-        orgId: resolveOrgId(actor ?? ctx?.actor ?? null),
+        orgId: resolveOrgIdForCommerce(actor ?? ctx?.actor ?? null, this.config),
         orderId,
         orderNumber: order.value.orderNumber,
         invoiceNumber: rendered.value.invoiceNumber,
@@ -171,6 +234,6 @@ export class DocumentsService {
         html: rendered.value.html,
       },
     });
-    return Ok({ sent: true, invoiceNumber: rendered.value.invoiceNumber, to });
+    return Ok({ sent: true, invoiceNumber: rendered.value.invoiceNumber, to: destination });
   }
 }

package/src/modules/fulfillment/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 type { InventoryService } from "../inventory/service.js";
@@ -36,6 +37,7 @@ export const fulfillmentModule = defineModule<
       ordersRepository: new OrdersRepository(deps.db.db as DrizzleDatabase),
       inventoryService: deps.services.inventory,
       hooks: deps.hooks,
+      config: deps.config as CommerceConfig,
       services: deps.services,
       database: deps.db,
     }),

package/src/modules/fulfillment/service.ts

@@ -1,10 +1,12 @@
 import { createHmac } from "node:crypto";
-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 type { CommerceConfig } from "../../config/types.js";
 import type { DatabaseAdapter } from "../../kernel/database/adapter.js";
 import type { PluginDb } from "../../kernel/database/plugin-types.js";
 import type { TxContext } from "../../kernel/database/tx-context.js";
-import { CommerceNotFoundError, CommerceValidationError } from "../../kernel/errors.js";
+import { CommerceNotFoundError, CommerceValidationError, toCommerceError } from "../../kernel/errors.js";
 import { runAfterHooks } from "../../kernel/hooks/executor.js";
 import { createHookContext } from "../../kernel/hooks/create-context.js";
 import type { HookRegistry } from "../../kernel/hooks/registry.js";
@@ -48,6 +50,7 @@ interface FulfillmentServiceDeps {
   ordersRepository: OrdersRepository;
   inventoryService?: InventoryServiceLike;
   hooks: HookRegistry;
+  config: CommerceConfig;
   services: Record<string, unknown>;
   database: DatabaseAdapter;
 }
@@ -259,7 +262,7 @@ export class FulfillmentService {
   }
 
   async fulfillOrder(orderId: string, actor?: Actor | null, ctx?: TxContext): Promise<Result<void>> {
-    const orgId = resolveOrgId(actor ?? ctx?.actor ?? null);
+    const orgId = resolveOrgIdForCommerce(actor ?? ctx?.actor ?? null, this.deps.config);
     const order = await this.deps.ordersRepository.findById(orgId, orderId, ctx);
     if (!order) return Err(new CommerceNotFoundError("Order not found."));
 
@@ -326,6 +329,7 @@ export class FulfillmentService {
         services: this.deps.services,
         context: { moduleName: "fulfillment" },
         database: { db: this.deps.database.db as PluginDb },
+        commerceConfig: this.deps.config,
       });
       await runAfterHooks(afterHooks, null, record, "create", hookCtx);
 
@@ -365,7 +369,13 @@ export class FulfillmentService {
     actor?: Actor | null,
     ctx?: TxContext,
   ): Promise<Result<FulfillmentRecord>> {
-    const orgId = resolveOrgId(actor ?? ctx?.actor ?? null);
+    try {
+      assertPermission(actor ?? null, "orders:update");
+    } catch (error) {
+      return Err(toCommerceError(error));
+    }
+
+    const orgId = resolveOrgIdForCommerce(actor ?? ctx?.actor ?? null, this.deps.config);
     const order = await this.deps.ordersRepository.findById(orgId, input.orderId, ctx);
     if (!order) return Err(new CommerceNotFoundError("Order not found."));
 
@@ -432,7 +442,7 @@ export class FulfillmentService {
         fulfillmentId: created.id,
         eventType: "created",
         toStatus: status,
-        ...(actor?.userId !== undefined ? { actorId: actor.userId } : {}),
+        ...(actor?.userId != null ? { actorId: actor.userId } : {}),
         description: input.trackingNumber
           ? `Shipment recorded (${input.trackingNumber})`
           : "Fulfillment recorded",
@@ -478,6 +488,7 @@ export class FulfillmentService {
       services: this.deps.services,
       context: { moduleName: "fulfillment" },
       database: { db: this.deps.database.db as PluginDb },
+      commerceConfig: this.deps.config,
     });
     await runAfterHooks(afterHooks, null, record, "create", hookCtx);
 
@@ -563,7 +574,7 @@ export class FulfillmentService {
       return Err(new CommerceNotFoundError("Digital download not found."));
     }
 
-    const orgId = resolveOrgId(actor ?? ctx?.actor ?? null);
+    const orgId = resolveOrgIdForCommerce(actor ?? ctx?.actor ?? null, this.deps.config);
     const order = await this.deps.ordersRepository.findById(orgId, orderId, ctx);
     if (!order || order.customerId !== userId) {
       return Err(new CommerceNotFoundError("Order not found."));