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

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

@@ -0,0 +1,99 @@
+import { NextResponse } from 'next/server'
+import { z } from 'zod'
+import { isCrudHttpError } from '@open-mercato/shared/lib/crud/errors'
+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 { ecommerceStoreBrandingSchema } from '../../../../data/validators'
+import {
+  buildBrandingDeclarations,
+  renderBrandingRootRule,
+  renderBrandingStyleBlock,
+} from '../../../../lib/brandingStyles'
+import { parseBrandingInput } from '../../../../lib/storeBranding'
+import { ecommerceInternalErrorBody } from '../../../../lib/crudSupport'
+import {
+  BRANDING_MANAGE_FEATURE,
+  requireScopedStore,
+  resolveBrandingRouteContext,
+  storeIdParamSchema,
+} from '../../../../lib/storeBrandingRoute'
+
+export const metadata = {
+  GET: { requireAuth: true, requireFeatures: [BRANDING_MANAGE_FEATURE] },
+}
+
+const logger = createLogger('ecommerce').child({ component: 'store-branding-preview-route' })
+
+type RouteParams = { params?: { id?: string } | Promise<{ id?: string }> }
+
+function readQueryValues(url: string): Record<string, string> {
+  const values: Record<string, string> = {}
+  for (const [key, value] of new URL(url).searchParams.entries()) values[key] = value
+  return values
+}
+
+export async function GET(req: Request, ctx: RouteParams) {
+  try {
+    const context = await resolveBrandingRouteContext(req)
+    const { translate } = await resolveTranslations()
+    const params = await ctx.params
+    const storeId = storeIdParamSchema.safeParse(params?.id)
+    if (!storeId.success) {
+      return NextResponse.json(
+        { error: translate('ecommerce.errors.storeNotFound', 'The selected store does not exist in this organization.') },
+        { status: 404 },
+      )
+    }
+    await requireScopedStore(context, storeId.data)
+
+    const parsed = parseBrandingInput(readQueryValues(req.url), translate)
+    if (!parsed.ok) {
+      const [message] = Object.values(parsed.fieldErrors)
+      return NextResponse.json({ error: message, fieldErrors: parsed.fieldErrors }, { status: 400 })
+    }
+
+    return NextResponse.json(
+      {
+        css: renderBrandingRootRule(parsed.branding),
+        styleBlock: renderBrandingStyleBlock(parsed.branding),
+        declarations: buildBrandingDeclarations(parsed.branding),
+      },
+      { headers: { 'Cache-Control': 'no-store' } },
+    )
+  } catch (err) {
+    if (isCrudHttpError(err)) return NextResponse.json(err.body, { status: err.status })
+    logger.error('ecommerce.stores.preview-branding.GET failed', { err })
+    return NextResponse.json(await ecommerceInternalErrorBody(), { status: 500 })
+  }
+}
+
+const previewResponseSchema = z.object({
+  css: z.string().describe('The :root rule that the storefront emits for these values.'),
+  styleBlock: z.string().describe('The same rule wrapped in the style element the storefront server-renders.'),
+  declarations: z.array(z.object({ property: z.string(), value: z.string() })),
+})
+
+const errorSchema = z.object({ error: z.string() }).passthrough()
+
+export const openApi: OpenApiRouteDoc = {
+  tag: 'Ecommerce',
+  summary: 'Store branding preview',
+  pathParams: z.object({ id: z.string().uuid() }),
+  methods: {
+    GET: {
+      summary: 'Preview the stylesheet for candidate branding values',
+      description:
+        'Validates the candidate branding values passed as query parameters with the same rules as the save route and returns the CSS the storefront would emit. Nothing is persisted. Requires ecommerce.branding.manage.',
+      tags: ['Ecommerce'],
+      query: ecommerceStoreBrandingSchema,
+      responses: [{ status: 200, description: 'Rendered branding stylesheet', schema: previewResponseSchema }],
+      errors: [
+        { status: 400, description: 'A branding value is invalid', schema: errorSchema },
+        { 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 },
+      ],
+    },
+  },
+}

package/src/modules/ecommerce/api/stores/crud.ts

@@ -0,0 +1,457 @@
+import { z } from 'zod'
+import type { EntityManager, FilterQuery } from '@mikro-orm/postgresql'
+import type { CrudCtx } from '@open-mercato/shared/lib/crud/factory'
+import { makeCrudRoute } from '@open-mercato/shared/lib/crud/factory'
+import { isUniqueViolation } from '@open-mercato/shared/lib/crud/errors'
+import { parseBooleanToken } from '@open-mercato/shared/lib/boolean'
+import { buildIlikeTerm } from '@open-mercato/shared/lib/db/buildIlikeTerm'
+import { resolveTranslations } from '@open-mercato/shared/lib/i18n/server'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+import { getTelemetryRuntime } from '@open-mercato/shared/lib/telemetry/runtime'
+import { E } from '#generated/entities.ids.generated'
+import * as F from '#generated/entities/ecommerce_store'
+import { EcommerceStore } from '../../data/entities'
+import {
+  ecommerceStoreCreateSchema,
+  ecommerceStoreStatusSchema,
+  ecommerceStoreUpdateSchema,
+  type EcommerceStoreCreateInput,
+  type EcommerceStoreSettings,
+  type EcommerceStoreSettingsPatch,
+  type EcommerceStoreUpdateInput,
+} from '../../data/validators'
+import {
+  assertRecordInWriteScope,
+  fieldError,
+  hasOwn,
+  resolveScopeOrganizationId,
+  resolveWriteScope,
+  type Translate,
+} from '../../lib/crudSupport'
+import { clearCreateConflictRecheck, registerCreateConflictRecheck } from '../../lib/createConflictRecheck'
+import {
+  assignExclusiveFlag,
+  promoteExclusiveFlag,
+  type ExclusiveFlagConfig,
+} from '../../lib/exclusiveFlag'
+import {
+  announceStoresUpdated,
+  buildStoreEventPayload,
+  ECOMMERCE_EVENTS_MODULE,
+  STORE_EVENT_ENTITY,
+} from '../../lib/crudEvents'
+import { announceStoreBindingCascade, cascadeStoreBindingDelete } from '../../lib/storeBindingCascade'
+
+const logger = createLogger('ecommerce').child({ component: 'store-crud' })
+
+const rawBodySchema = z.object({}).passthrough()
+type RawStoreInput = z.infer<typeof rawBodySchema>
+
+export const storeListQuerySchema = z
+  .object({
+    page: z.coerce.number().min(1).default(1),
+    pageSize: z.coerce.number().min(1).max(100).default(50),
+    id: z.string().uuid().optional(),
+    search: z.string().optional(),
+    status: ecommerceStoreStatusSchema.optional(),
+    isPrimary: z.string().optional(),
+    sortField: z.string().optional(),
+    sortDir: z.enum(['asc', 'desc']).optional(),
+  })
+  .passthrough()
+
+export type StoreListQuery = z.infer<typeof storeListQuerySchema>
+
+export const storeRouteMetadata = {
+  GET: { requireAuth: true, requireFeatures: ['ecommerce.stores.view'] },
+  POST: { requireAuth: true, requireFeatures: ['ecommerce.stores.manage'] },
+  PUT: { requireAuth: true, requireFeatures: ['ecommerce.stores.manage'] },
+  DELETE: { requireAuth: true, requireFeatures: ['ecommerce.stores.manage'] },
+}
+
+export const STORE_CODE_UNIQUE_CONSTRAINT = 'ecommerce_stores_tenant_code_unique'
+export const STORE_SLUG_UNIQUE_CONSTRAINT = 'ecommerce_stores_tenant_slug_unique'
+export const STORE_PRIMARY_UNIQUE_CONSTRAINT = 'ecommerce_stores_org_primary_unique'
+
+const storePrimaryFlag: ExclusiveFlagConfig<EcommerceStore> = {
+  entity: EcommerceStore,
+  flag: 'isPrimary',
+  constraint: STORE_PRIMARY_UNIQUE_CONSTRAINT,
+}
+
+function codeDuplicateMessage(translate: Translate): string {
+  return translate('ecommerce.errors.codeDuplicate', 'A store with this code already exists.')
+}
+
+function slugDuplicateMessage(translate: Translate): string {
+  return translate('ecommerce.errors.slugDuplicate', 'A store with this slug already exists.')
+}
+
+function primaryConflict(translate: Translate) {
+  return fieldError(409, {
+    isPrimary: translate(
+      'ecommerce.errors.primaryConflict',
+      'Another store was made primary at the same time. Reload and try again.',
+    ),
+  })
+}
+
+export function toStoreUniqueConflict(err: unknown, translate: Translate): unknown {
+  if (isUniqueViolation(err, STORE_CODE_UNIQUE_CONSTRAINT)) return fieldError(409, { code: codeDuplicateMessage(translate) })
+  if (isUniqueViolation(err, STORE_SLUG_UNIQUE_CONSTRAINT)) return fieldError(409, { slug: slugDuplicateMessage(translate) })
+  if (isUniqueViolation(err, STORE_PRIMARY_UNIQUE_CONSTRAINT)) return primaryConflict(translate)
+  return err
+}
+
+export type StoreIdentifierCheck = {
+  tenantId: string
+  storeId: string | null
+  code?: string
+  slug?: string
+}
+
+export async function assertStoreIdentifiersAvailable(
+  em: EntityManager,
+  check: StoreIdentifierCheck,
+  translate: Translate,
+): Promise<void> {
+  const fieldErrors: Record<string, string> = {}
+  const taken = async (field: 'code' | 'slug', value: string): Promise<boolean> => {
+    const where: Record<string, unknown> = { tenantId: check.tenantId, [field]: value, deletedAt: null }
+    if (check.storeId) where.id = { $ne: check.storeId }
+    return (await em.count(EcommerceStore, where as FilterQuery<EcommerceStore>)) > 0
+  }
+  if (check.code !== undefined && (await taken('code', check.code))) fieldErrors.code = codeDuplicateMessage(translate)
+  if (check.slug !== undefined && (await taken('slug', check.slug))) fieldErrors.slug = slugDuplicateMessage(translate)
+  if (Object.keys(fieldErrors).length) throw fieldError(409, fieldErrors)
+}
+
+function canonicalBranding(value: unknown): string {
+  if (!value || typeof value !== 'object') return '[]'
+  const entries = Object.entries(value as Record<string, unknown>)
+    .filter(([, entry]) => entry !== undefined && entry !== null && entry !== '')
+    .sort(([left], [right]) => left.localeCompare(right))
+  return JSON.stringify(entries)
+}
+
+export const BRANDING_MANAGE_FEATURE = 'ecommerce.branding.manage'
+
+type FeatureChecker = {
+  userHasAllFeatures(
+    userId: string,
+    required: string[],
+    scope: { tenantId: string | null; organizationId: string | null },
+  ): Promise<boolean>
+}
+
+export async function assertCreateBrandingAllowed(
+  settings: Partial<EcommerceStoreSettings> | null | undefined,
+  ctx: CrudCtx,
+  scope: { tenantId: string; organizationId: string },
+  translate: Translate,
+): Promise<void> {
+  if (canonicalBranding(settings?.branding) === canonicalBranding(undefined)) return
+  const subject = ctx.auth?.sub ?? null
+  let rbac: FeatureChecker | undefined
+  try {
+    rbac = ctx.container.resolve('rbacService') as FeatureChecker | undefined
+  } catch {
+    rbac = undefined
+  }
+  if (subject && rbac && (await rbac.userHasAllFeatures(subject, [BRANDING_MANAGE_FEATURE], scope))) return
+  throw fieldError(403, {
+    'settings.branding': translate(
+      'ecommerce.errors.brandingPermissionRequired',
+      'You do not have permission to set the store branding.',
+    ),
+  })
+}
+
+export function assertBrandingUnchanged(
+  current: Partial<EcommerceStoreSettings> | null | undefined,
+  patch: EcommerceStoreSettingsPatch | undefined,
+  translate: Translate,
+): void {
+  if (!patch?.branding) return
+  if (canonicalBranding(patch.branding) === canonicalBranding(current?.branding)) return
+  throw fieldError(400, {
+    'settings.branding': translate(
+      'ecommerce.errors.brandingRouteRequired',
+      'Branding cannot be changed here. Save it through the branding endpoint (PUT /api/ecommerce/stores/{id}/branding).',
+    ),
+  })
+}
+
+export function mergeStoreSettings(
+  current: Partial<EcommerceStoreSettings> | null | undefined,
+  patch: EcommerceStoreSettingsPatch,
+): EcommerceStoreSettings {
+  return {
+    branding: current?.branding ?? {},
+    contact: patch.contact ?? current?.contact ?? {},
+    display: {
+      priceDisplayModeDefault: 'gross',
+      enableSearch: true,
+      ...current?.display,
+      ...patch.display,
+    },
+    seo: patch.seo ?? current?.seo ?? {},
+  }
+}
+
+export function assertLocalesConsistent(store: EcommerceStore, input: EcommerceStoreUpdateInput, translate: Translate): void {
+  const defaultLocale = input.defaultLocale ?? store.defaultLocale
+  const supportedLocales = input.supportedLocales ?? store.supportedLocales
+  if (supportedLocales.includes(defaultLocale)) return
+  const field = input.supportedLocales !== undefined && input.defaultLocale === undefined ? 'supportedLocales' : 'defaultLocale'
+  throw fieldError(400, {
+    [field]: translate('ecommerce.validation.defaultLocaleNotSupported', 'The default locale must be one of the supported locales.'),
+  })
+}
+
+export function assertStatusTransitionAllowed(store: EcommerceStore, input: EcommerceStoreUpdateInput, translate: Translate): void {
+  if (store.status !== 'archived' || input.status === undefined || input.status === 'archived') return
+  throw fieldError(400, {
+    status: translate('ecommerce.validation.archivedStoreTerminal', 'An archived store cannot be reopened. Create a new store instead.'),
+  })
+}
+
+function parseCreateInput(input: RawStoreInput, ctx: CrudCtx): EcommerceStoreCreateInput {
+  return ecommerceStoreCreateSchema.parse({ ...input, ...resolveWriteScope(ctx) })
+}
+
+function parseUpdateInput(input: RawStoreInput, ctx: CrudCtx): EcommerceStoreUpdateInput {
+  return ecommerceStoreUpdateSchema.parse({ ...input, ...resolveWriteScope(ctx) })
+}
+
+function toStoreEntityData(input: EcommerceStoreCreateInput): Record<string, unknown> {
+  return {
+    organizationId: input.organizationId,
+    tenantId: input.tenantId,
+    code: input.code,
+    name: input.name,
+    slug: input.slug,
+    status: input.status,
+    defaultLocale: input.defaultLocale,
+    supportedLocales: input.supportedLocales,
+    defaultCurrencyCode: input.defaultCurrencyCode,
+    isPrimary: false,
+    settings: input.settings,
+  }
+}
+
+function applyStoreUpdate(store: EcommerceStore, input: EcommerceStoreUpdateInput): void {
+  if (input.code !== undefined) store.code = input.code
+  if (input.name !== undefined) store.name = input.name
+  if (input.slug !== undefined) store.slug = input.slug
+  if (input.status !== undefined) store.status = input.status
+  if (input.defaultLocale !== undefined) store.defaultLocale = input.defaultLocale
+  if (input.supportedLocales !== undefined) store.supportedLocales = input.supportedLocales
+  if (input.defaultCurrencyCode !== undefined) store.defaultCurrencyCode = input.defaultCurrencyCode
+  if (input.isPrimary !== undefined) store.isPrimary = input.isPrimary
+  if (hasOwn(input, 'settings') && input.settings) store.settings = mergeStoreSettings(store.settings, input.settings)
+}
+
+function primaryScope(store: Pick<EcommerceStore, 'tenantId' | 'organizationId'>): Record<string, string> {
+  return { tenantId: store.tenantId, organizationId: store.organizationId }
+}
+
+const clearedPrimaryByUpdate = new WeakMap<EcommerceStore, EcommerceStore[]>()
+
+type StoreListRow = Record<string, unknown>
+
+export function toStoreListItem(row: StoreListRow): Record<string, unknown> {
+  return {
+    id: row[F.id],
+    organizationId: row[F.organization_id] ?? null,
+    tenantId: row[F.tenant_id] ?? null,
+    code: row[F.code],
+    name: row[F.name],
+    slug: row[F.slug],
+    status: row[F.status],
+    defaultLocale: row[F.default_locale],
+    supportedLocales: row[F.supported_locales] ?? [],
+    defaultCurrencyCode: row[F.default_currency_code],
+    isPrimary: row[F.is_primary] === true,
+    settings: row[F.settings] ?? null,
+    createdAt: row[F.created_at] ?? null,
+    updatedAt: row[F.updated_at] ?? null,
+  }
+}
+
+const NOT_FOUND = { key: 'ecommerce.errors.storeNotFound', fallback: 'The selected store does not exist in this organization.' }
+
+export const storeCrud = makeCrudRoute<RawStoreInput, RawStoreInput, StoreListQuery>({
+  metadata: storeRouteMetadata,
+  orm: {
+    entity: EcommerceStore,
+    idField: 'id',
+    orgField: 'organizationId',
+    tenantField: 'tenantId',
+    softDeleteField: 'deletedAt',
+  },
+  indexer: { entityType: E.ecommerce.ecommerce_store },
+  enrichers: { entityId: E.ecommerce.ecommerce_store },
+  list: {
+    schema: storeListQuerySchema,
+    entityId: E.ecommerce.ecommerce_store,
+    fields: [
+      F.id,
+      F.organization_id,
+      F.tenant_id,
+      F.code,
+      F.name,
+      F.slug,
+      F.status,
+      F.default_locale,
+      F.supported_locales,
+      F.default_currency_code,
+      F.is_primary,
+      F.settings,
+      F.created_at,
+      F.updated_at,
+    ],
+    sortFieldMap: {
+      name: F.name,
+      code: F.code,
+      slug: F.slug,
+      status: F.status,
+      createdAt: F.created_at,
+      updatedAt: F.updated_at,
+    },
+    defaultSort: { field: 'name', dir: 'asc' },
+    tiebreakSortField: F.id,
+    buildFilters: async (query, ctx) => {
+      const filters: Record<string, unknown> = {}
+      const scopeOrganizationId = resolveScopeOrganizationId(ctx)
+      if (scopeOrganizationId) filters[F.organization_id] = { $eq: scopeOrganizationId }
+      if (query.id) filters[F.id] = { $eq: query.id }
+      if (query.search) {
+        const pattern = buildIlikeTerm(query.search)
+        filters.$or = [{ [F.code]: { $ilike: pattern } }, { [F.name]: { $ilike: pattern } }, { [F.slug]: { $ilike: pattern } }]
+      }
+      if (query.status) filters[F.status] = { $eq: query.status }
+      const isPrimary = parseBooleanToken(query.isPrimary)
+      if (isPrimary !== null) filters[F.is_primary] = { $eq: isPrimary }
+      return filters
+    },
+    transformItem: (item: StoreListRow) => toStoreListItem(item),
+  },
+  events: {
+    module: ECOMMERCE_EVENTS_MODULE,
+    entity: STORE_EVENT_ENTITY,
+    persistent: true,
+    buildPayload: (emitCtx) => buildStoreEventPayload(emitCtx.entity as EcommerceStore),
+  },
+  create: {
+    schema: rawBodySchema,
+    mapToEntity: (input, ctx) => toStoreEntityData(parseCreateInput(input, ctx)),
+    response: (entity) => {
+      const store = entity as EcommerceStore
+      return { id: store.id, isPrimary: store.isPrimary }
+    },
+  },
+  update: {
+    schema: rawBodySchema,
+    getId: (input) => (typeof input.id === 'string' ? input.id : ''),
+    applyToEntity: async (entity, input, ctx) => {
+      const store = entity as EcommerceStore
+      const parsed = parseUpdateInput(input, ctx)
+      const em = ctx.container.resolve('em') as EntityManager
+      const { translate } = await resolveTranslations()
+      assertBrandingUnchanged(store.settings, parsed.settings, translate)
+      assertStatusTransitionAllowed(store, parsed, translate)
+      assertLocalesConsistent(store, parsed, translate)
+      await assertStoreIdentifiersAvailable(
+        em,
+        {
+          tenantId: store.tenantId,
+          storeId: store.id,
+          code: parsed.code !== undefined && parsed.code !== store.code ? parsed.code : undefined,
+          slug: parsed.slug !== undefined && parsed.slug !== store.slug ? parsed.slug : undefined,
+        },
+        translate,
+      )
+      if (parsed.isPrimary === true && !store.isPrimary) {
+        clearedPrimaryByUpdate.set(
+          store,
+          await assignExclusiveFlag(em, storePrimaryFlag, primaryScope(store), store.id, () => primaryConflict(translate)),
+        )
+      }
+      applyStoreUpdate(store, parsed)
+      try {
+        await em.flush()
+      } catch (err) {
+        throw toStoreUniqueConflict(err, translate)
+      }
+    },
+    response: () => ({ ok: true }),
+  },
+  del: { idFrom: 'query', softDelete: true, response: () => ({ ok: true }) },
+  hooks: {
+    beforeUpdate: async (input, ctx) => {
+      await assertRecordInWriteScope(ctx, EcommerceStore, (input as { id?: unknown }).id, NOT_FOUND)
+    },
+    beforeDelete: async (id, ctx) => {
+      await assertRecordInWriteScope(ctx, EcommerceStore, id, NOT_FOUND)
+    },
+    beforeCreate: async (input, ctx) => {
+      const result = ecommerceStoreCreateSchema.safeParse({ ...input, ...resolveWriteScope(ctx) })
+      if (!result.success) return
+      const { translate } = await resolveTranslations()
+      await assertCreateBrandingAllowed(
+        result.data.settings,
+        ctx,
+        { tenantId: result.data.tenantId, organizationId: result.data.organizationId },
+        translate,
+      )
+      const check: StoreIdentifierCheck = {
+        tenantId: result.data.tenantId,
+        storeId: null,
+        code: result.data.code,
+        slug: result.data.slug,
+      }
+      await assertStoreIdentifiersAvailable((ctx.container.resolve('em') as EntityManager).fork(), check, translate)
+      registerCreateConflictRecheck(ctx.request, () =>
+        assertStoreIdentifiersAvailable((ctx.container.resolve('em') as EntityManager).fork(), check, translate),
+      )
+    },
+    afterCreate: async (entity, ctx) => {
+      clearCreateConflictRecheck(ctx.request)
+      const store = entity as EcommerceStore
+      if (parseCreateInput(ctx.input, ctx).isPrimary !== true) return
+      const now = new Date()
+      const em = ctx.container.resolve('em') as EntityManager
+      const { promoted, cleared } = await promoteExclusiveFlag(em, storePrimaryFlag, primaryScope(store), store.id, now)
+      if (!promoted) return
+      store.isPrimary = true
+      store.updatedAt = now
+      await announceStoresUpdated(ctx.container, cleared)
+    },
+    afterUpdate: async (entity, ctx) => {
+      const store = entity as EcommerceStore
+      const cleared = clearedPrimaryByUpdate.get(store)
+      if (!cleared) return
+      clearedPrimaryByUpdate.delete(store)
+      await announceStoresUpdated(ctx.container, cleared)
+    },
+    afterDelete: async (id, ctx) => {
+      const em = ctx.container.resolve('em') as EntityManager
+      const cascade = await cascadeStoreBindingDelete(em, id, ctx)
+      try {
+        await announceStoreBindingCascade(ctx.container, cascade)
+      } catch (err) {
+        logger.error('[internal] store binding cascade committed but could not be announced', {
+          storeId: id,
+          domainBindingCount: cascade.domainBindings.length,
+          channelBindingCount: cascade.channelBindings.length,
+          err,
+        })
+        getTelemetryRuntime()?.reportError(err, {
+          module: 'ecommerce',
+          code: 'ecommerce.store_binding_cascade_announce_failed',
+        })
+      }
+    },
+  },
+})

package/src/modules/ecommerce/api/stores/route.ts

@@ -0,0 +1,66 @@
+import { z } from 'zod'
+import { withCreateConflictRecheck } from '../../lib/createConflictRecheck'
+import { storeCrud, storeListQuerySchema, storeRouteMetadata } from './crud'
+import { ecommerceStoreCreateSchema, ecommerceStoreUpdateSchema } from '../../data/validators'
+import { createEcommerceCrudOpenApi, createPagedListResponseSchema, defaultOkResponseSchema } from '../openapi'
+
+export const metadata = storeRouteMetadata
+
+export const GET = storeCrud.GET
+export const POST = withCreateConflictRecheck(storeCrud.POST)
+export const PUT = storeCrud.PUT
+export const DELETE = storeCrud.DELETE
+
+export const storeListItemSchema = z.object({
+  id: z.string().uuid(),
+  organizationId: z.string().uuid().nullable(),
+  tenantId: z.string().uuid().nullable(),
+  code: z.string(),
+  name: z.string(),
+  slug: z.string(),
+  status: z.enum(['draft', 'active', 'archived']),
+  defaultLocale: z.string(),
+  supportedLocales: z.array(z.string()),
+  defaultCurrencyCode: z.string(),
+  isPrimary: z.boolean(),
+  settings: z.record(z.string(), z.unknown()).nullable(),
+  createdAt: z.string().nullable(),
+  updatedAt: z.string().nullable(),
+  _ecommerce: z
+    .object({
+      primaryDomain: z.object({ hostname: z.string(), pathPrefix: z.string().nullable() }).nullable(),
+      defaultChannel: z.object({ id: z.string().uuid(), name: z.string() }).nullable(),
+    })
+    .optional()
+    .describe('Response enricher: the hostname of the primary domain binding and the name of the default sales channel binding.'),
+})
+
+export const openApi = createEcommerceCrudOpenApi({
+  resourceName: 'Store',
+  pluralName: 'Stores',
+  querySchema: storeListQuerySchema,
+  listResponseSchema: createPagedListResponseSchema(storeListItemSchema),
+  create: {
+    schema: ecommerceStoreCreateSchema,
+    responseSchema: z.object({
+      id: z.string().uuid().nullable(),
+      isPrimary: z
+        .boolean()
+        .describe('Whether the created store is the organization primary store. False when a concurrent request won the promotion.'),
+    }),
+    description:
+      'Creates a store in the selected organization. Requesting isPrimary clears the previous primary store of the organization. A duplicate code or slug is rejected with a field-level 409. A non-empty settings.branding requires ecommerce.branding.manage and is otherwise rejected with a 403 field error.',
+  },
+  update: {
+    schema: ecommerceStoreUpdateSchema,
+    responseSchema: defaultOkResponseSchema,
+    description:
+      'Updates a store by id (id in the body). Any change to settings.branding is rejected with a 400 field error: branding is written through PUT /api/ecommerce/stores/{id}/branding. Setting isPrimary clears the previous primary store of the organization.',
+  },
+  del: {
+    schema: z.object({ id: z.string().uuid() }),
+    responseSchema: defaultOkResponseSchema,
+    description:
+      'Soft-deletes a store by id (?id= query parameter). Its live domain and channel bindings are soft-deleted with it, releasing their domain and path prefix, and each emits its own deleted event.',
+  },
+})

package/src/modules/ecommerce/backend/config/ecommerce/[id]/page.meta.ts

@@ -0,0 +1,12 @@
+export const metadata = {
+  requireAuth: true,
+  requireFeatures: ['ecommerce.stores.view'],
+  navHidden: true,
+  pageTitle: 'Store',
+  pageTitleKey: 'ecommerce.backend.store.entityType',
+  pageContext: 'settings' as const,
+  breadcrumb: [
+    { label: 'Stores', labelKey: 'ecommerce.module.title', href: '/backend/config/ecommerce' },
+    { label: 'Store', labelKey: 'ecommerce.backend.store.entityType' },
+  ],
+} as const

package/src/modules/ecommerce/backend/config/ecommerce/[id]/page.tsx

@@ -0,0 +1,5 @@
+import { StoreEditPage } from '../../../../components/StoreEditPage'
+
+export default function EcommerceStoreEditPage({ params }: { params?: { id?: string } }) {
+  return <StoreEditPage storeId={params?.id} />
+}

package/src/modules/ecommerce/backend/config/ecommerce/page.meta.ts

@@ -0,0 +1,12 @@
+export const metadata = {
+  requireAuth: true,
+  requireFeatures: ['ecommerce.stores.view'],
+  pageTitle: 'Stores',
+  pageTitleKey: 'ecommerce.module.title',
+  pageGroup: 'Module Configs',
+  pageGroupKey: 'settings.sections.moduleConfigs',
+  pageOrder: 25,
+  pageContext: 'settings' as const,
+  icon: 'store',
+  breadcrumb: [{ label: 'Stores', labelKey: 'ecommerce.module.title' }],
+} as const

package/src/modules/ecommerce/backend/config/ecommerce/page.tsx

@@ -0,0 +1,5 @@
+import { StoreListPage } from '../../../components/StoreListPage'
+
+export default function EcommerceStoresPage() {
+  return <StoreListPage />
+}