@open-mercato/core 0.9.1-develop.7473.1.de5b22888f → 0.9.1-develop.7475.1.28ca93ed97

package/src/modules/ecommerce/api/storefront/products/openapiSchemas.ts

@@ -0,0 +1,193 @@
+import { z } from 'zod'
+import { CATALOG_PRODUCT_TYPES } from '@open-mercato/core/modules/catalog/data/types'
+import {
+  ecommercePriceDisplayModeSchema,
+  ecommercePriceSortFallbackSchema,
+  ecommerceStorefrontProductSortSchema,
+} from '../../../data/validators'
+
+const availabilityStateSchema = z.enum(['in_stock', 'low_stock', 'out_of_stock', 'backorder', 'preorder', 'not_tracked'])
+
+export const storefrontPriceSchema = z.object({
+  currencyCode: z.string(),
+  displayMode: ecommercePriceDisplayModeSchema,
+  amount: z.number(),
+  formatted: z.string(),
+  isPromotion: z.boolean(),
+  originalAmount: z.number().nullable(),
+  formattedOriginal: z.string().nullable(),
+  lowestPriorAmount: z.number().nullable(),
+  formattedLowestPrior: z.string().nullable(),
+})
+
+export const storefrontPriceRangeSchema = z.object({
+  min: z.number(),
+  max: z.number(),
+  formattedMin: z.string(),
+  formattedMax: z.string(),
+})
+
+export const storefrontPriceTierSchema = z.object({
+  minQuantity: z.number(),
+  maxQuantity: z.number().nullable(),
+  amount: z.number(),
+  formatted: z.string(),
+})
+
+export const storefrontAvailabilitySchema = z.object({
+  state: availabilityStateSchema,
+  canFulfil: z.boolean(),
+  leadTimeDays: z.number().nullable(),
+  releaseAt: z.string().nullable(),
+})
+
+export const storefrontProductListItemSchema = z.object({
+  id: z.string().uuid(),
+  handle: z.string().nullable(),
+  title: z.string(),
+  subtitle: z.string().nullable(),
+  defaultMediaUrl: z.string().nullable(),
+  productType: z.string(),
+  isConfigurable: z.boolean(),
+  hasVariants: z.boolean(),
+  variantCount: z.number().int(),
+  categories: z.array(z.object({ id: z.string().uuid(), name: z.string(), slug: z.string().nullable() })),
+  tags: z.array(z.string()),
+  price: storefrontPriceSchema.nullable(),
+  priceRange: storefrontPriceRangeSchema.nullable(),
+  availability: storefrontAvailabilitySchema,
+  badges: z.array(z.string()),
+})
+
+const storefrontFacetsSchema = z.object({
+  categories: z.array(
+    z.object({
+      id: z.string().uuid(),
+      name: z.string(),
+      slug: z.string().nullable(),
+      depth: z.number().int(),
+      parentId: z.string().uuid().nullable(),
+      count: z.number().int(),
+    }),
+  ),
+  tags: z.array(z.object({ slug: z.string(), label: z.string(), count: z.number().int() })),
+  priceRange: z.object({ min: z.number(), max: z.number(), currencyCode: z.string() }).nullable(),
+  options: z.array(
+    z.object({
+      code: z.string(),
+      label: z.string(),
+      values: z.array(z.object({ code: z.string(), label: z.string(), count: z.number().int() })),
+    }),
+  ),
+  productTypes: z.array(z.object({ type: z.string(), label: z.string(), count: z.number().int() })),
+  availability: z.array(z.object({ state: availabilityStateSchema, count: z.number().int() })),
+  availabilityScope: z.literal('page'),
+  total: z.number().int(),
+})
+
+const storefrontAppliedFiltersSchema = z.object({
+  search: z.string().optional(),
+  category: z
+    .object({ id: z.string().uuid(), slug: z.string().nullable(), includesDescendants: z.literal(true) })
+    .optional(),
+  tagSlugs: z.array(z.string()).optional(),
+  price: z.object({ min: z.number().nullable(), max: z.number().nullable(), approximate: z.boolean() }).optional(),
+  options: z.record(z.string(), z.array(z.string())).optional(),
+  productType: z.enum(CATALOG_PRODUCT_TYPES).optional(),
+  availability: z.object({ value: z.enum(['in_stock', 'available']), scope: z.literal('page') }).optional(),
+})
+
+export const storefrontProductListResponseSchema = z.object({
+  items: z.array(storefrontProductListItemSchema),
+  total: z.number().int(),
+  page: z.number().int(),
+  pageSize: z.number().int(),
+  totalPages: z.number().int(),
+  facets: storefrontFacetsSchema.describe(
+    'Cross-excluded facet counts over the buyer assortment; priceRange is buyer-priced, availability counts the returned page',
+  ),
+  effectiveLocale: z.string(),
+  requestedLocale: z.string().nullable(),
+  currencyCode: z.string(),
+  taxMode: ecommercePriceDisplayModeSchema,
+  appliedFilters: storefrontAppliedFiltersSchema,
+  availableSorts: z.array(ecommerceStorefrontProductSortSchema),
+  appliedSort: ecommerceStorefrontProductSortSchema,
+  priceSort: z.object({ cap: z.number().int(), fallback: ecommercePriceSortFallbackSchema, capExceeded: z.boolean() }),
+  sortApproximate: z.boolean(),
+  sortUnavailable: z.boolean(),
+})
+
+const dimensionsSchema = z
+  .object({
+    length: z.number().nullable(),
+    width: z.number().nullable(),
+    height: z.number().nullable(),
+    unit: z.string().nullable(),
+  })
+  .nullable()
+
+const optionSchemaSchema = z
+  .object({
+    version: z.number().int().optional(),
+    name: z.string().nullable().optional(),
+    description: z.string().nullable().optional(),
+    options: z.array(
+      z.object({
+        code: z.string(),
+        label: z.string(),
+        description: z.string().nullable().optional(),
+        inputType: z.string(),
+        isRequired: z.boolean().optional(),
+        isMultiple: z.boolean().optional(),
+        choices: z.array(z.object({ code: z.string(), label: z.string().nullable().optional() })).optional(),
+      }),
+    ),
+  })
+  .nullable()
+
+export const storefrontProductDetailResponseSchema = storefrontProductListItemSchema
+  .omit({ categories: true })
+  .extend({
+    description: z.string().nullable(),
+    sku: z.string().nullable(),
+    media: z.array(z.object({ id: z.string(), url: z.string(), alt: z.string().nullable(), sortOrder: z.number().int() })),
+    dimensions: dimensionsSchema,
+    weightValue: z.number().nullable(),
+    weightUnit: z.string().nullable(),
+    categories: z.array(
+      z.object({ id: z.string().uuid(), name: z.string(), slug: z.string().nullable(), ancestorIds: z.array(z.string().uuid()) }),
+    ),
+    breadcrumb: z.array(z.object({ id: z.string().uuid(), name: z.string(), slug: z.string().nullable() })),
+    optionSchema: optionSchemaSchema,
+    variants: z.array(
+      z.object({
+        id: z.string().uuid(),
+        name: z.string(),
+        sku: z.string().nullable(),
+        optionValues: z.record(z.string(), z.string()),
+        isDefault: z.boolean(),
+        price: storefrontPriceSchema.nullable(),
+        priceTiers: z.array(storefrontPriceTierSchema).describe('Quantity tiers of this variant for this buyer'),
+        availability: storefrontAvailabilitySchema,
+        dimensions: dimensionsSchema,
+        weightValue: z.number().nullable(),
+        weightUnit: z.string().nullable(),
+      }),
+    ),
+    selectedVariantId: z
+      .string()
+      .uuid()
+      .nullable()
+      .describe('The requested variantId when it is one of variants, else the default variant, else null'),
+    quantityRules: z.object({
+      minOrderQuantity: z.number().nullable(),
+      maxOrderQuantity: z.number().nullable(),
+      quantityIncrement: z.number().nullable(),
+    }),
+    priceTiers: z
+      .array(storefrontPriceTierSchema)
+      .describe('Quantity tiers of selectedVariantId when one is selected, else of the product'),
+    relatedProducts: z.array(storefrontProductListItemSchema).max(8),
+    seo: z.object({ title: z.string().nullable(), description: z.string().nullable(), canonicalUrl: z.string().nullable() }),
+  })

package/src/modules/ecommerce/api/storefront/products/route.ts

@@ -0,0 +1,81 @@
+import { NextResponse } from 'next/server'
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import type { OpenApiMethodDoc, OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
+import { rateLimitErrorSchema } from '@open-mercato/shared/lib/ratelimit/helpers'
+import { ecommerceStorefrontProductListQuerySchema } from '../../../data/validators'
+import { enforceStorefrontRateLimit } from '../../../lib/storefrontRateLimit'
+import type { StoreContextService } from '../../../lib/storeContextService'
+import { cachedListStorefrontProducts } from '../../../lib/storefrontProductCache'
+import { parseStorefrontProductListQuery } from '../../../lib/storefrontQuery'
+import {
+  storefrontErrorSchema,
+  storefrontInvalidQueryErrorSchema,
+  storefrontRouteErrorResponse,
+  storefrontSuccessHeaders,
+  runInStoreCacheTenant,
+} from '../storefrontRouteSupport'
+import { storefrontProductListResponseSchema } from './openapiSchemas'
+
+export const metadata = {
+  path: '/ecommerce/storefront/products',
+  GET: {
+    requireAuth: false,
+  },
+}
+
+const ANONYMOUS_CACHE_CONTROL = 'public, max-age=30, stale-while-revalidate=30'
+
+export async function GET(req: Request) {
+  try {
+    const query = parseStorefrontProductListQuery(new URL(req.url).searchParams)
+    const container = await createRequestContainer()
+    const service = container.resolve('storeContextService') as StoreContextService
+    const context = await service.resolve(req, { pathname: query.path ?? '/' })
+    return await runInStoreCacheTenant(context, async () => {
+      const rateLimited = await enforceStorefrontRateLimit(container, req, context, 'products')
+      if (rateLimited) return rateLimited
+      const body = await cachedListStorefrontProducts(container, context, query)
+      const headers = storefrontSuccessHeaders(context, ANONYMOUS_CACHE_CONTROL)
+      if (body.sortApproximate) headers['X-Sort-Approximate'] = 'true'
+      if (body.sortUnavailable) headers['X-Sort-Unavailable'] = 'true'
+      return NextResponse.json(body, { headers })
+    })
+  } catch (error) {
+    return storefrontRouteErrorResponse(error, {
+      message: 'Storefront product listing failed',
+      code: 'ecommerce.storefront_products_failed',
+    })
+  }
+}
+
+export default GET
+
+const storefrontProductsTag = 'Ecommerce'
+
+const storefrontProductsGetDoc: OpenApiMethodDoc = {
+  summary: 'List storefront products for the current buyer',
+  description:
+    'Public. Resolves the store from the Host header and the optional portal session, then lists the products of the buyer\'s effective assortment with buyer-resolved prices. Unknown, repeated or malformed parameters are rejected with 400. Options use bracket notation (`options[color]=red,blue`). `availability=` is page-scoped: `total` counts the pre-availability set and a page may be short. Facets count each dimension against every other active filter (cross-exclusion); category, tag, option and product-type counts are shared per assortment scope (and empty past 10 000 products in the search universe), `priceRange` spans the buyer\'s own prices over the filtered set without the price filter, and `availability` counts the returned page only. `X-Sort-Approximate: true` marks a price order past the sort cap; `X-Sort-Unavailable: true` marks a declined price sort. Anonymous responses are `public, max-age=30, stale-while-revalidate=30`; authenticated responses are `private, no-store`. Cached server-side for 30 s per buyer context digest. Rate limited per IP and store.',
+  tags: [storefrontProductsTag],
+  query: ecommerceStorefrontProductListQuerySchema,
+  responses: [
+    { status: 200, description: 'Products of the buyer\'s effective assortment.', schema: storefrontProductListResponseSchema },
+  ],
+  errors: [
+    { status: 400, description: 'Unknown, repeated or malformed query parameters', schema: storefrontInvalidQueryErrorSchema },
+    { status: 401, description: 'Portal session invalid or issued for another tenant or organization', schema: storefrontErrorSchema },
+    { status: 403, description: 'Draft store (only when OM_ECOMMERCE_DEV_STORE_SLUG=true)', schema: storefrontErrorSchema },
+    { status: 404, description: 'No store serves this host or path', schema: storefrontErrorSchema },
+    { status: 410, description: 'Store archived', schema: storefrontErrorSchema },
+    { status: 429, description: 'Too many requests', schema: rateLimitErrorSchema },
+    { status: 503, description: 'Store misconfigured (no default channel binding)', schema: storefrontErrorSchema },
+  ],
+}
+
+export const openApi: OpenApiRouteDoc = {
+  tag: storefrontProductsTag,
+  summary: 'Public storefront product listing',
+  methods: {
+    GET: storefrontProductsGetDoc,
+  },
+}

package/src/modules/ecommerce/api/storefront/search/suggest/openapiSchemas.ts

@@ -0,0 +1,25 @@
+import { z } from 'zod'
+
+export const storefrontSearchSuggestResponseSchema = z.object({
+  products: z.array(
+    z.object({
+      id: z.string().uuid(),
+      handle: z.string().nullable(),
+      title: z.string(),
+      defaultMediaUrl: z.string().nullable(),
+      formattedPrice: z
+        .string()
+        .nullable()
+        .describe('The buyer\'s resolved price (the lowest variant price for products priced per variant)'),
+    }),
+  ),
+  categories: z.array(
+    z.object({
+      id: z.string().uuid(),
+      name: z.string(),
+      slug: z.string().nullable(),
+    }),
+  ),
+  suggestions: z.array(z.string()).describe('Query completions; always empty in this phase'),
+  effectiveLocale: z.string(),
+})

package/src/modules/ecommerce/api/storefront/search/suggest/route.ts

@@ -0,0 +1,78 @@
+import { NextResponse } from 'next/server'
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import type { OpenApiMethodDoc, OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
+import { rateLimitErrorSchema } from '@open-mercato/shared/lib/ratelimit/helpers'
+import { ecommerceStorefrontSearchSuggestQuerySchema } from '../../../../data/validators'
+import { enforceStorefrontRateLimit } from '../../../../lib/storefrontRateLimit'
+import type { StoreContextService } from '../../../../lib/storeContextService'
+import { parseStorefrontSearchSuggestQuery } from '../../../../lib/storefrontQuery'
+import { cachedSuggestStorefrontSearch } from '../../../../lib/storefrontSearchCache'
+import {
+  storefrontErrorSchema,
+  storefrontInvalidQueryErrorSchema,
+  storefrontRouteErrorResponse,
+  storefrontSuccessHeaders,
+  runInStoreCacheTenant,
+} from '../../storefrontRouteSupport'
+import { storefrontSearchSuggestResponseSchema } from './openapiSchemas'
+
+export const metadata = {
+  path: '/ecommerce/storefront/search/suggest',
+  GET: {
+    requireAuth: false,
+  },
+}
+
+const ANONYMOUS_CACHE_CONTROL = 'public, max-age=30, stale-while-revalidate=30'
+
+export async function GET(req: Request) {
+  try {
+    const query = parseStorefrontSearchSuggestQuery(new URL(req.url).searchParams)
+    const container = await createRequestContainer()
+    const service = container.resolve('storeContextService') as StoreContextService
+    const context = await service.resolve(req, { pathname: query.path ?? '/' })
+    return await runInStoreCacheTenant(context, async () => {
+      const rateLimited = await enforceStorefrontRateLimit(container, req, context, 'searchSuggest')
+      if (rateLimited) return rateLimited
+      const body = await cachedSuggestStorefrontSearch(container, context, query)
+      return NextResponse.json(body, { headers: storefrontSuccessHeaders(context, ANONYMOUS_CACHE_CONTROL) })
+    })
+  } catch (error) {
+    return storefrontRouteErrorResponse(error, {
+      message: 'Storefront search suggest failed',
+      code: 'ecommerce.storefront_search_suggest_failed',
+    })
+  }
+}
+
+export default GET
+
+const storefrontSearchTag = 'Ecommerce'
+
+const storefrontSearchSuggestGetDoc: OpenApiMethodDoc = {
+  summary: 'Typeahead suggestions for the current buyer',
+  description:
+    'Public. Resolves the store from the Host header and the optional portal session, then returns up to `limit` products of the buyer\'s effective assortment matching `q`, with the buyer\'s formatted price, and up to `limit` visible categories whose localized name matches `q`. Products are ranked by the `tokens` or `pgvector` search strategy with the assortment scope inside the ranking query, or by the escaped `ILIKE` match when neither is available; the payload is identical either way. A `q` shorter than 2 characters returns empty arrays, never an error. Products whose availability policy hides them when out of stock are omitted. No facets are computed. Anonymous responses are `public, max-age=30, stale-while-revalidate=30`; authenticated responses are `private, no-store`. Cached server-side for 30 s per buyer context digest. Rate limited per IP and store.',
+  tags: [storefrontSearchTag],
+  query: ecommerceStorefrontSearchSuggestQuerySchema,
+  responses: [
+    { status: 200, description: 'Products and categories matching the query.', schema: storefrontSearchSuggestResponseSchema },
+  ],
+  errors: [
+    { status: 400, description: 'Missing `q`, or unknown, repeated or malformed query parameters', schema: storefrontInvalidQueryErrorSchema },
+    { status: 401, description: 'Portal session invalid or issued for another tenant or organization', schema: storefrontErrorSchema },
+    { status: 403, description: 'Draft store (only when OM_ECOMMERCE_DEV_STORE_SLUG=true)', schema: storefrontErrorSchema },
+    { status: 404, description: 'No store serves this host or path', schema: storefrontErrorSchema },
+    { status: 410, description: 'Store archived', schema: storefrontErrorSchema },
+    { status: 429, description: 'Too many requests', schema: rateLimitErrorSchema },
+    { status: 503, description: 'Store misconfigured (no default channel binding)', schema: storefrontErrorSchema },
+  ],
+}
+
+export const openApi: OpenApiRouteDoc = {
+  tag: storefrontSearchTag,
+  summary: 'Public storefront search suggestions',
+  methods: {
+    GET: storefrontSearchSuggestGetDoc,
+  },
+}

package/src/modules/ecommerce/api/storefront/storefrontRouteSupport.ts

@@ -0,0 +1,68 @@
+import { NextResponse } from 'next/server'
+import { z } from 'zod'
+import { runWithCacheTenant } from '@open-mercato/cache'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+import { getTelemetryRuntime } from '@open-mercato/shared/lib/telemetry/runtime'
+import { isStorefrontResolutionError } from '../../lib/storeContext'
+import { isStorefrontQueryError, type StorefrontQueryError } from '../../lib/storefrontQuery'
+import type { StoreContext } from '../../lib/types'
+
+export const STOREFRONT_VARY_HEADER = 'Cookie, Authorization, X-Locale, Accept-Language'
+export const STOREFRONT_PRIVATE_CACHE_CONTROL = 'private, no-store'
+export const STOREFRONT_ERROR_CACHE_CONTROL = 'no-store'
+
+export const storefrontErrorSchema = z.object({ error: z.string() })
+
+export const storefrontInvalidQueryErrorSchema = z.object({
+  error: z.literal('invalid_query'),
+  fields: z.record(z.string(), z.string()),
+})
+
+const logger = createLogger('ecommerce').child({ component: 'storefront-route' })
+
+export function storefrontErrorResponse(status: number, body: Record<string, unknown>): NextResponse {
+  return NextResponse.json(body, {
+    status,
+    headers: { 'Cache-Control': STOREFRONT_ERROR_CACHE_CONTROL, Vary: STOREFRONT_VARY_HEADER },
+  })
+}
+
+export function storefrontInvalidQueryResponse(error: StorefrontQueryError): NextResponse {
+  const fields: Record<string, string> = {}
+  for (const issue of error.issues) {
+    if (!(issue.parameter in fields)) fields[issue.parameter] = issue.message
+  }
+  return storefrontErrorResponse(400, { error: 'invalid_query', fields })
+}
+
+/**
+ * Authenticated responses are never stored by a browser or CDN (`private, no-store`); anonymous
+ * ones may be, for the given policy. The server-side cache applies to both, keyed on the digest.
+ */
+export function storefrontSuccessHeaders(context: StoreContext, anonymousCacheControl: string): Record<string, string> {
+  return {
+    'Cache-Control': context.buyer.isAuthenticated ? STOREFRONT_PRIVATE_CACHE_CONTROL : anonymousCacheControl,
+    Vary: STOREFRONT_VARY_HEADER,
+  }
+}
+
+export type StorefrontRouteFailure = { message: string; code: string }
+
+/** Query grammar → 400, store resolution → its status with `{ error: code }`, anything else → reported 500. */
+export function storefrontRouteErrorResponse(error: unknown, failure: StorefrontRouteFailure): NextResponse {
+  if (isStorefrontQueryError(error)) return storefrontInvalidQueryResponse(error)
+  if (isStorefrontResolutionError(error)) return storefrontErrorResponse(error.status, { error: error.code })
+  logger.error(failure.message, { err: error })
+  getTelemetryRuntime()?.reportError(error, { module: 'ecommerce', code: failure.code })
+  return storefrontErrorResponse(500, { error: 'internal_error' })
+}
+
+/**
+ * Runs the rest of a storefront request in the resolved store's cache tenant. Admin writes invalidate
+ * cached values (module config, Omnibus results, CRUD lists) in their tenant's namespace; an
+ * unauthenticated storefront request would otherwise read the global namespace and keep serving a
+ * copy those invalidations never reach.
+ */
+export function runInStoreCacheTenant<T>(context: Pick<StoreContext, 'tenantId'>, fn: () => Promise<T>): Promise<T> {
+  return runWithCacheTenant(context.tenantId, fn)
+}

package/src/modules/ecommerce/api/stores/[id]/branding/route.ts

@@ -0,0 +1,205 @@
+import { NextResponse } from 'next/server'
+import { z } from 'zod'
+import { CommandBus } from '@open-mercato/shared/lib/commands'
+import { getCommandInterceptorHttpRejection } from '@open-mercato/shared/lib/commands/errors'
+import { serializeOperationMetadata } from '@open-mercato/shared/lib/commands/operationMetadata'
+import { isCrudHttpError } from '@open-mercato/shared/lib/crud/errors'
+import {
+  bridgeLegacyGuard,
+  runMutationGuards,
+  type MutationGuard,
+} from '@open-mercato/shared/lib/crud/mutation-guard-registry'
+import { getAllMutationGuardInstances } from '@open-mercato/shared/lib/crud/mutation-guard-store'
+import { resolveTranslations } from '@open-mercato/shared/lib/i18n/server'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
+import type { StoreBrandingUpdateInput, StoreBrandingUpdateResult } from '../../../../commands/stores'
+import { ecommerceStoreBrandingSchema, type EcommerceStoreBranding } from '../../../../data/validators'
+import {
+  BRANDING_MANAGE_FEATURE,
+  resolveBrandingRouteContext,
+  resolveGrantedFeatures,
+  storeIdParamSchema,
+} from '../../../../lib/storeBrandingRoute'
+import {
+  parseBrandingInput,
+  STORE_BRANDING_RESOURCE_KIND,
+  STORE_BRANDING_UPDATE_COMMAND_ID,
+} from '../../../../lib/storeBranding'
+import { ecommerceInternalErrorBody } from '../../../../lib/crudSupport'
+
+export const metadata = {
+  PUT: { requireAuth: true, requireFeatures: [BRANDING_MANAGE_FEATURE] },
+}
+
+const logger = createLogger('ecommerce').child({ component: 'store-branding-route' })
+
+type RouteParams = { params?: { id?: string } | Promise<{ id?: string }> }
+
+async function readStoreId(ctx: RouteParams): Promise<string | null> {
+  const params = await ctx.params
+  const parsed = storeIdParamSchema.safeParse(params?.id)
+  return parsed.success ? parsed.data : null
+}
+
+async function readJsonBody(req: Request): Promise<{ ok: true; body: unknown } | { ok: false }> {
+  const text = await req.text()
+  if (text.trim().length === 0) return { ok: true, body: {} }
+  try {
+    return { ok: true, body: JSON.parse(text) }
+  } catch {
+    return { ok: false }
+  }
+}
+
+function invalidBranding(fieldErrors: Record<string, string>) {
+  const [message] = Object.values(fieldErrors)
+  return NextResponse.json({ error: message, fieldErrors }, { status: 400 })
+}
+
+export async function PUT(req: Request, ctx: RouteParams) {
+  try {
+    const context = await resolveBrandingRouteContext(req)
+    const { translate } = await resolveTranslations()
+    const storeId = await readStoreId(ctx)
+    if (!storeId) return NextResponse.json({ error: translate('ecommerce.errors.storeNotFound', 'The selected store does not exist in this organization.') }, { status: 404 })
+
+    const raw = await readJsonBody(req)
+    if (!raw.ok) {
+      return NextResponse.json(
+        { error: translate('ecommerce.errors.invalidJsonBody', 'The request body is not valid JSON.') },
+        { status: 400 },
+      )
+    }
+    const parsed = parseBrandingInput(raw.body, translate)
+    if (!parsed.ok) return invalidBranding(parsed.fieldErrors)
+    let branding: EcommerceStoreBranding = parsed.branding
+
+    const legacyGuard = bridgeLegacyGuard(context.container)
+    const guards: MutationGuard[] = [...getAllMutationGuardInstances()]
+    if (legacyGuard) guards.push(legacyGuard)
+    const guardInput = {
+      tenantId: context.tenantId,
+      organizationId: context.organizationId,
+      userId: context.auth.sub ?? '',
+      resourceKind: STORE_BRANDING_RESOURCE_KIND,
+      resourceId: storeId,
+      operation: 'update' as const,
+      requestMethod: req.method,
+      requestHeaders: req.headers,
+    }
+    const guardResult = await runMutationGuards(
+      guards,
+      { ...guardInput, mutationPayload: { ...branding } },
+      { userFeatures: await resolveGrantedFeatures(context) },
+    )
+    if (!guardResult.ok) {
+      const blocked = guardResult.errorBody ?? {
+        error: translate('ecommerce.errors.operationBlocked', 'This change was blocked. Review the store and try again.'),
+      }
+      return NextResponse.json(blocked, {
+        status: guardResult.errorStatus ?? 422,
+      })
+    }
+    if (guardResult.modifiedPayload) {
+      const merged = parseBrandingInput({ ...branding, ...guardResult.modifiedPayload }, translate)
+      if (!merged.ok) return invalidBranding(merged.fieldErrors)
+      branding = merged.branding
+    }
+
+    const commandBus = context.container.resolve('commandBus') as CommandBus
+    const { result, logEntry } = await commandBus.execute<StoreBrandingUpdateInput, StoreBrandingUpdateResult>(
+      STORE_BRANDING_UPDATE_COMMAND_ID,
+      {
+        input: { id: storeId, tenantId: context.tenantId, organizationId: context.organizationId, branding },
+        ctx: context.commandCtx,
+      },
+    )
+
+    for (const callback of guardResult.afterSuccessCallbacks) {
+      if (!callback.guard.afterSuccess) continue
+      try {
+        await callback.guard.afterSuccess({ ...guardInput, metadata: callback.metadata ?? null })
+      } catch (callbackError) {
+        logger.error('Mutation guard afterSuccess callback failed', {
+          guardId: callback.guard.id,
+          err: callbackError,
+        })
+      }
+    }
+
+    const response = NextResponse.json({ id: result.id, updatedAt: result.updatedAt, branding: result.branding })
+    if (logEntry?.undoToken && logEntry?.id && logEntry?.commandId) {
+      response.headers.set(
+        'x-om-operation',
+        serializeOperationMetadata({
+          id: logEntry.id,
+          undoToken: logEntry.undoToken,
+          commandId: logEntry.commandId,
+          actionLabel: logEntry.actionLabel ?? null,
+          resourceKind: logEntry.resourceKind ?? STORE_BRANDING_RESOURCE_KIND,
+          resourceId: logEntry.resourceId ?? result.id,
+          executedAt:
+            logEntry.createdAt instanceof Date
+              ? logEntry.createdAt.toISOString()
+              : typeof logEntry.createdAt === 'string'
+                ? logEntry.createdAt
+                : new Date().toISOString(),
+        }),
+      )
+    }
+    return response
+  } catch (err) {
+    if (isCrudHttpError(err)) return NextResponse.json(err.body, { status: err.status })
+    const interceptorRejection = getCommandInterceptorHttpRejection(err)
+    if (interceptorRejection) {
+      return NextResponse.json(interceptorRejection.body, { status: interceptorRejection.status })
+    }
+    logger.error('ecommerce.stores.branding.PUT failed', { err })
+    return NextResponse.json(await ecommerceInternalErrorBody(), { status: 500 })
+  }
+}
+
+const brandingResponseSchema = z.object({
+  id: z.string().uuid(),
+  updatedAt: z.string().describe('The store updated_at after the write; send it as the expected version of the next save.'),
+  branding: ecommerceStoreBrandingSchema,
+})
+
+const errorSchema = z.object({ error: z.string() }).passthrough()
+
+const fieldErrorsSchema = z.object({
+  error: z.string(),
+  fieldErrors: z.record(z.string(), z.string()),
+})
+
+const conflictSchema = z.object({
+  error: z.string(),
+  code: z.string(),
+  currentUpdatedAt: z.string(),
+  expectedUpdatedAt: z.string(),
+})
+
+export const openApi: OpenApiRouteDoc = {
+  tag: 'Ecommerce',
+  summary: 'Store branding',
+  pathParams: z.object({ id: z.string().uuid() }),
+  methods: {
+    PUT: {
+      summary: 'Replace the branding of a store',
+      description:
+        'Command route behind the Branding tab. Replaces settings.branding with the validated body (omitted or empty keys are cleared) and merges it into the stored settings server-side, so contact, display and SEO values are never touched. Requires ecommerce.branding.manage. Runs the mutation guard registry as an update, honours the x-om-ext-optimistic-lock-expected-updated-at header against the store updated_at (409 on a stale version), is undoable, and emits ecommerce.store.branding_updated, which evicts the storefront caches of the store.',
+      tags: ['Ecommerce'],
+      requestBody: { schema: ecommerceStoreBrandingSchema },
+      responses: [{ status: 200, description: 'Branding saved', schema: brandingResponseSchema }],
+      errors: [
+        { status: 400, description: 'A branding value is invalid; fieldErrors maps each rejected key to a message', schema: fieldErrorsSchema },
+        { status: 401, description: 'Unauthorized', schema: errorSchema },
+        { status: 403, description: 'Missing ecommerce.branding.manage', schema: errorSchema },
+        { status: 404, description: 'The store does not exist in the selected organization', schema: errorSchema },
+        { status: 409, description: 'The store changed since it was loaded (optimistic lock)', schema: conflictSchema },
+        { status: 422, description: 'Blocked by a mutation guard', schema: errorSchema },
+      ],
+    },
+  },
+}