@open-mercato/core 0.9.1-develop.7474.1.51db10479d → 0.9.1-develop.7475.1.28ca93ed97

package/src/modules/ecommerce/api/store-domain-bindings/route.ts

@@ -0,0 +1,73 @@
+import { z } from 'zod'
+import { withCreateConflictRecheck } from '../../lib/createConflictRecheck'
+import { domainBindingCrud, domainBindingListQuerySchema, domainBindingRouteMetadata } from './crud'
+import {
+  ecommerceStoreDomainBindingCreateSchema,
+  ecommerceStoreDomainBindingUpdateSchema,
+} from '../../data/validators'
+import { createEcommerceCrudOpenApi, createPagedListResponseSchema, defaultOkResponseSchema } from '../openapi'
+
+export const metadata = domainBindingRouteMetadata
+
+export const GET = domainBindingCrud.GET
+export const POST = withCreateConflictRecheck(domainBindingCrud.POST)
+export const PUT = domainBindingCrud.PUT
+export const DELETE = domainBindingCrud.DELETE
+
+const domainBindingMappingSchema = z.discriminatedUnion('state', [
+  z.object({
+    state: z.literal('found'),
+    hostname: z.string(),
+    status: z.string().describe('pending, verified, active, dns_failed or tls_failed. Only active serves.'),
+    lastDnsCheckAt: z.string().nullable(),
+    dnsFailureReason: z.string().nullable(),
+    tlsFailureReason: z.string().nullable(),
+  }),
+  z.object({ state: z.literal('removed') }),
+  z.object({ state: z.literal('unavailable') }),
+])
+
+export const domainBindingListItemSchema = z.object({
+  id: z.string().uuid(),
+  organizationId: z.string().uuid().nullable(),
+  tenantId: z.string().uuid().nullable(),
+  storeId: z.string().uuid(),
+  domainMappingId: z.string().uuid(),
+  pathPrefix: z.string().nullable(),
+  isPrimary: z.boolean(),
+  createdAt: z.string().nullable(),
+  updatedAt: z.string().nullable(),
+  _domainMapping: domainBindingMappingSchema
+    .optional()
+    .describe(
+      'Added by the ecommerce.store-domain-binding-mapping response enricher: the bound customer_accounts domain mapping as read through domainMappingService. state is removed when the mapping no longer exists and unavailable when it could not be read.',
+    ),
+})
+
+export const openApi = createEcommerceCrudOpenApi({
+  resourceName: 'StoreDomainBinding',
+  pluralName: 'StoreDomainBindings',
+  querySchema: domainBindingListQuerySchema,
+  listResponseSchema: createPagedListResponseSchema(domainBindingListItemSchema),
+  create: {
+    schema: ecommerceStoreDomainBindingCreateSchema,
+    responseSchema: z.object({
+      id: z.string().uuid().nullable(),
+      isPrimary: z
+        .boolean()
+        .describe('Whether the created binding is the primary binding of its store. False when a concurrent request won the promotion.'),
+    }),
+    description:
+      'Binds a customer_accounts domain mapping (any status) and optional path prefix to a store of the same organization. A duplicate domain and path prefix is rejected with a field-level 409. Requesting isPrimary clears the previous primary binding of the store.',
+  },
+  update: {
+    schema: ecommerceStoreDomainBindingUpdateSchema,
+    responseSchema: defaultOkResponseSchema,
+    description: 'Updates a store domain binding by id (id in the body). Setting isPrimary clears the previous primary binding of the store.',
+  },
+  del: {
+    schema: z.object({ id: z.string().uuid() }),
+    responseSchema: defaultOkResponseSchema,
+    description: 'Soft-deletes a store domain binding by id (?id= query parameter).',
+  },
+})

package/src/modules/ecommerce/api/storefront/categories/[slug]/route.ts

@@ -0,0 +1,94 @@
+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 {
+  ecommerceStorefrontCategoryLandingQuerySchema,
+  ecommerceStorefrontCategoryParamsSchema,
+} from '../../../../data/validators'
+import { enforceStorefrontRateLimit } from '../../../../lib/storefrontRateLimit'
+import type { StoreContextService } from '../../../../lib/storeContextService'
+import { cachedGetStorefrontCategoryLanding } from '../../../../lib/storefrontCategoryCache'
+import { parseStorefrontCategoryLandingQuery } from '../../../../lib/storefrontQuery'
+import {
+  storefrontErrorResponse,
+  storefrontErrorSchema,
+  storefrontInvalidQueryErrorSchema,
+  storefrontRouteErrorResponse,
+  storefrontSuccessHeaders,
+  runInStoreCacheTenant,
+} from '../../storefrontRouteSupport'
+import { storefrontCategoryLandingResponseSchema } from '../openapiSchemas'
+
+export const metadata = {
+  path: '/ecommerce/storefront/categories/[slug]',
+  GET: {
+    requireAuth: false,
+  },
+}
+
+const ANONYMOUS_CACHE_CONTROL = 'public, max-age=30, stale-while-revalidate=30'
+const CATEGORY_NOT_FOUND = { error: 'category_not_found' } as const
+
+type CategoryRouteParams = { slug?: string }
+
+type CategoryRouteContext = { params?: CategoryRouteParams | Promise<CategoryRouteParams> }
+
+export async function GET(req: Request, routeContext: CategoryRouteContext = {}) {
+  try {
+    const query = parseStorefrontCategoryLandingQuery(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, 'categoryLanding')
+      if (rateLimited) return rateLimited
+      const params = ecommerceStorefrontCategoryParamsSchema.safeParse((await routeContext.params) ?? {})
+      if (!params.success) return storefrontErrorResponse(404, { ...CATEGORY_NOT_FOUND })
+      const landing = await cachedGetStorefrontCategoryLanding(container, context, params.data.slug, query)
+      if (!landing) return storefrontErrorResponse(404, { ...CATEGORY_NOT_FOUND })
+      const headers = storefrontSuccessHeaders(context, ANONYMOUS_CACHE_CONTROL)
+      if (landing.products.sortApproximate) headers['X-Sort-Approximate'] = 'true'
+      if (landing.products.sortUnavailable) headers['X-Sort-Unavailable'] = 'true'
+      return NextResponse.json(landing, { headers })
+    })
+  } catch (error) {
+    return storefrontRouteErrorResponse(error, {
+      message: 'Storefront category landing failed',
+      code: 'ecommerce.storefront_category_landing_failed',
+    })
+  }
+}
+
+export default GET
+
+const storefrontCategoryTag = 'Ecommerce'
+
+const storefrontCategoryGetDoc: OpenApiMethodDoc = {
+  summary: 'Get one storefront category landing for the current buyer',
+  description:
+    'Public. Resolves the store from the Host header and the optional portal session, then returns the category by slug with its breadcrumb, visible non-empty children and descendant-inclusive `productCount` within the buyer\'s assortment (null past 10 000 products in the assortment), plus a full `GET /products` response filtered to the category (`products`, same query grammar except `categoryId` / `categorySlug`). A slug that does not exist, is inactive, deleted, of another tenant, under an inactive ancestor or outside the buyer\'s effective assortment answers the same 404 `{ "error": "category_not_found" }`. `seo` fields are null until the catalog stores category SEO data. Anonymous responses are `public, max-age=30, stale-while-revalidate=30`; authenticated responses are `private, no-store`. The category block is cached server-side for 60 s per assortment scope; the embedded listing shares the `GET /products` cache. Rate limited per IP and store.',
+  tags: [storefrontCategoryTag],
+  pathParams: ecommerceStorefrontCategoryParamsSchema,
+  query: ecommerceStorefrontCategoryLandingQuerySchema,
+  responses: [
+    { status: 200, description: 'The category landing as this buyer sees it.', schema: storefrontCategoryLandingResponseSchema },
+  ],
+  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, or the category is not visible to this buyer', 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: storefrontCategoryTag,
+  summary: 'Public storefront category landing',
+  methods: {
+    GET: storefrontCategoryGetDoc,
+  },
+}

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

@@ -0,0 +1,63 @@
+import { z } from 'zod'
+import { storefrontProductListResponseSchema } from '../products/openapiSchemas'
+
+export type StorefrontCategoryNodeSchema = {
+  id: string
+  name: string
+  slug: string | null
+  description: string | null
+  depth: number
+  parentId: string | null
+  productCount: number | null
+  hasChildren: boolean
+  children: StorefrontCategoryNodeSchema[]
+}
+
+export const storefrontCategoryNodeSchema: z.ZodType<StorefrontCategoryNodeSchema> = z.lazy(() =>
+  z.object({
+    id: z.string().uuid(),
+    name: z.string(),
+    slug: z.string().nullable(),
+    description: z.string().nullable(),
+    depth: z.number().int(),
+    parentId: z.string().uuid().nullable(),
+    productCount: z
+      .number()
+      .int()
+      .nullable()
+      .describe(
+        'Products of the buyer\'s effective assortment in this category or a descendant; null when the assortment is too large to count',
+      ),
+    hasChildren: z.boolean(),
+    children: z.array(storefrontCategoryNodeSchema),
+  }),
+)
+
+export const storefrontCategoryTreeResponseSchema = z.object({
+  tree: z.array(storefrontCategoryNodeSchema),
+  effectiveLocale: z.string(),
+})
+
+export const storefrontCategoryLandingResponseSchema = z.object({
+  category: z.object({
+    id: z.string().uuid(),
+    name: z.string(),
+    slug: z.string().nullable(),
+    description: z.string().nullable(),
+    depth: z.number().int(),
+    parentId: z.string().uuid().nullable(),
+    ancestorIds: z.array(z.string().uuid()),
+    breadcrumb: z.array(z.object({ id: z.string().uuid(), name: z.string(), slug: z.string().nullable() })),
+    children: z.array(
+      z.object({ id: z.string().uuid(), name: z.string(), slug: z.string().nullable(), productCount: z.number().int().nullable() }),
+    ),
+    productCount: z.number().int().nullable(),
+    seo: z.object({
+      title: z.string().nullable(),
+      description: z.string().nullable(),
+      canonicalUrl: z.string().nullable(),
+    }),
+  }),
+  products: storefrontProductListResponseSchema.describe('Identical to GET /products with the category filter applied'),
+  effectiveLocale: z.string(),
+})

package/src/modules/ecommerce/api/storefront/categories/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 { ecommerceStorefrontCategoryTreeQuerySchema } from '../../../data/validators'
+import { enforceStorefrontRateLimit } from '../../../lib/storefrontRateLimit'
+import type { StoreContextService } from '../../../lib/storeContextService'
+import { cachedGetStorefrontCategoryTree } from '../../../lib/storefrontCategoryCache'
+import { parseStorefrontCategoryTreeQuery } from '../../../lib/storefrontQuery'
+import {
+  storefrontErrorSchema,
+  storefrontInvalidQueryErrorSchema,
+  storefrontRouteErrorResponse,
+  storefrontSuccessHeaders,
+  runInStoreCacheTenant,
+} from '../storefrontRouteSupport'
+import { storefrontCategoryTreeResponseSchema } from './openapiSchemas'
+
+export const metadata = {
+  path: '/ecommerce/storefront/categories',
+  GET: {
+    requireAuth: false,
+  },
+}
+
+const ANONYMOUS_CACHE_CONTROL = 'public, max-age=300, stale-while-revalidate=60'
+
+export async function GET(req: Request) {
+  try {
+    const query = parseStorefrontCategoryTreeQuery(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, 'categories')
+      if (rateLimited) return rateLimited
+      const body = await cachedGetStorefrontCategoryTree(container, context, query)
+      return NextResponse.json(body, { headers: storefrontSuccessHeaders(context, ANONYMOUS_CACHE_CONTROL) })
+    })
+  } catch (error) {
+    return storefrontRouteErrorResponse(error, {
+      message: 'Storefront category tree failed',
+      code: 'ecommerce.storefront_categories_failed',
+    })
+  }
+}
+
+export default GET
+
+const storefrontCategoriesTag = 'Ecommerce'
+
+const storefrontCategoriesGetDoc: OpenApiMethodDoc = {
+  summary: 'List the storefront category tree for the current buyer',
+  description:
+    'Public. Resolves the store from the Host header and the optional portal session, then returns the visible category tree below `parentId` (the roots when omitted), `depth` levels deep (all levels when omitted). `productCount` is descendant-inclusive and counts only products inside the buyer\'s effective assortment; categories the buyer cannot browse are absent, and empty categories are absent unless `includeEmpty=true`. Past 10 000 products in the assortment the counts are not computed: every `productCount` is null and no category is dropped as empty. A `parentId` that is unknown or not visible to the buyer yields an empty tree, identical to a nonexistent one. A nested node beyond `depth` has empty `children` and `hasChildren: true`. Anonymous responses are `public, max-age=300, stale-while-revalidate=60`; authenticated responses are `private, no-store`. Cached server-side for 300 s per assortment scope. Rate limited per IP and store.',
+  tags: [storefrontCategoriesTag],
+  query: ecommerceStorefrontCategoryTreeQuerySchema,
+  responses: [
+    { status: 200, description: 'The category tree within the buyer\'s assortment.', schema: storefrontCategoryTreeResponseSchema },
+  ],
+  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: storefrontCategoriesTag,
+  summary: 'Public storefront category tree',
+  methods: {
+    GET: storefrontCategoriesGetDoc,
+  },
+}

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

@@ -0,0 +1,203 @@
+import { NextResponse } from 'next/server'
+import { z } from 'zod'
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import { findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import type { OpenApiMethodDoc, OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
+import { rateLimitErrorSchema } from '@open-mercato/shared/lib/ratelimit/helpers'
+import { CustomerUser } from '@open-mercato/core/modules/customer_accounts/data/entities'
+import { CustomerEntity } from '@open-mercato/core/modules/customers/data/entities'
+import { ecommercePriceDisplayModeSchema, ecommerceStorefrontContextQuerySchema } from '../../../data/validators'
+import { parseStorefrontContextQuery } from '../../../lib/storefrontQuery'
+import { enforceStorefrontRateLimit } from '../../../lib/storefrontRateLimit'
+import type { StoreContextService } from '../../../lib/storeContextService'
+import type { StoreContext } from '../../../lib/types'
+import {
+  runInStoreCacheTenant,
+  storefrontErrorSchema,
+  storefrontInvalidQueryErrorSchema,
+  storefrontRouteErrorResponse,
+  storefrontSuccessHeaders,
+} from '../storefrontRouteSupport'
+
+export const metadata = {
+  path: '/ecommerce/storefront/context',
+  GET: {
+    requireAuth: false,
+  },
+}
+
+const ANONYMOUS_CACHE_CONTROL = 'public, max-age=60'
+
+export type StorefrontBuyerNames = {
+  displayName: string | null
+  companyName: string | null
+}
+
+export type StorefrontContextResponse = {
+  store: {
+    id: string
+    code: string
+    name: string
+    slug: string
+    status: 'active'
+    defaultLocale: string
+    supportedLocales: string[]
+    defaultCurrencyCode: string
+    settings: StoreContext['store']['settings']
+  }
+  effectiveLocale: string
+  requestedLocale: string | null
+  supportedLocales: string[]
+  currencyCode: string
+  buyer: {
+    isAuthenticated: boolean
+    taxMode: StoreContext['buyer']['taxMode']
+    displayName: string | null
+    companyName: string | null
+    allowPurchaseOnAccount: boolean
+  }
+}
+
+export function projectStorefrontContext(context: StoreContext, names: StorefrontBuyerNames): StorefrontContextResponse {
+  const { store, buyer } = context
+  return {
+    store: {
+      id: store.id,
+      code: store.code,
+      name: store.name,
+      slug: store.slug,
+      status: store.status,
+      defaultLocale: store.defaultLocale,
+      supportedLocales: [...store.supportedLocales],
+      defaultCurrencyCode: store.defaultCurrencyCode,
+      settings: store.settings,
+    },
+    effectiveLocale: context.effectiveLocale,
+    requestedLocale: context.requestedLocale,
+    supportedLocales: [...store.supportedLocales],
+    currencyCode: context.currencyCode,
+    buyer: {
+      isAuthenticated: buyer.isAuthenticated,
+      taxMode: buyer.taxMode,
+      displayName: buyer.isAuthenticated ? names.displayName : null,
+      companyName: buyer.isAuthenticated ? names.companyName : null,
+      allowPurchaseOnAccount: buyer.allowPurchaseOnAccount,
+    },
+  }
+}
+
+function nonEmptyOrNull(value: string | null | undefined): string | null {
+  return typeof value === 'string' && value.trim().length > 0 ? value : null
+}
+
+async function loadBuyerNames(em: EntityManager, context: StoreContext): Promise<StorefrontBuyerNames> {
+  const { buyer } = context
+  if (!buyer.isAuthenticated || !buyer.customerUserId) return { displayName: null, companyName: null }
+  const scope = { tenantId: context.tenantId, organizationId: context.organizationId }
+  const user = await findOneWithDecryption(
+    em,
+    CustomerUser,
+    { id: buyer.customerUserId, ...scope, deletedAt: null },
+    undefined,
+    scope,
+  )
+  const company = buyer.companyId
+    ? await findOneWithDecryption(
+        em,
+        CustomerEntity,
+        { id: buyer.companyId, ...scope, deletedAt: null },
+        undefined,
+        scope,
+      )
+    : null
+  return {
+    displayName: nonEmptyOrNull(user?.displayName),
+    companyName: nonEmptyOrNull(company?.displayName),
+  }
+}
+
+export async function GET(req: Request) {
+  try {
+    const query = parseStorefrontContextQuery(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, 'context')
+      if (rateLimited) return rateLimited
+      const em = container.resolve('em') as EntityManager
+      const names = await loadBuyerNames(em, context)
+      const body = projectStorefrontContext(context, names)
+      return NextResponse.json(body, { headers: storefrontSuccessHeaders(context, ANONYMOUS_CACHE_CONTROL) })
+    })
+  } catch (error) {
+    return storefrontRouteErrorResponse(error, {
+      message: 'Storefront context resolution failed',
+      code: 'ecommerce.storefront_context_failed',
+    })
+  }
+}
+
+export default GET
+
+const storefrontContextTag = 'Ecommerce'
+
+export const storefrontContextResponseSchema = z.object({
+  store: z.object({
+    id: z.string().uuid(),
+    code: z.string(),
+    name: z.string(),
+    slug: z.string(),
+    status: z.literal('active'),
+    defaultLocale: z.string(),
+    supportedLocales: z.array(z.string()),
+    defaultCurrencyCode: z.string(),
+    settings: z.record(z.string(), z.unknown()),
+  }),
+  effectiveLocale: z.string(),
+  requestedLocale: z.string().nullable(),
+  supportedLocales: z.array(z.string()),
+  currencyCode: z.string(),
+  buyer: z.object({
+    isAuthenticated: z.boolean(),
+    taxMode: ecommercePriceDisplayModeSchema,
+    displayName: z.string().nullable(),
+    companyName: z.string().nullable(),
+    allowPurchaseOnAccount: z.boolean(),
+  }),
+})
+
+const storefrontContextBadRequestSchema = z.union([storefrontInvalidQueryErrorSchema, storefrontErrorSchema])
+
+const storefrontContextGetDoc: OpenApiMethodDoc = {
+  summary: 'Resolve the storefront context for the current host',
+  description:
+    'Public, unauthenticated. Resolves the store from the Host header (or `storeSlug` when OM_ECOMMERCE_DEV_STORE_SLUG=true) and the optional portal session, and returns a safe projection of the store and buyer context. Anonymous responses are `public, max-age=60`; authenticated responses are `private, no-store`. Rate limited per IP and store.',
+  tags: [storefrontContextTag],
+  query: ecommerceStorefrontContextQuerySchema,
+  responses: [
+    { status: 200, description: 'Storefront context resolved.', schema: storefrontContextResponseSchema },
+  ],
+  errors: [
+    {
+      status: 400,
+      description: 'Unknown, repeated or malformed query parameters, or storeSlug used while the development flag is off',
+      schema: storefrontContextBadRequestSchema,
+    },
+    { 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: storefrontContextTag,
+  summary: 'Public storefront context',
+  methods: {
+    GET: storefrontContextGetDoc,
+  },
+}

package/src/modules/ecommerce/api/storefront/products/[idOrHandle]/route.ts

@@ -0,0 +1,94 @@
+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 {
+  ecommerceStorefrontProductDetailQuerySchema,
+  ecommerceStorefrontProductParamsSchema,
+} from '../../../../data/validators'
+import { enforceStorefrontRateLimit } from '../../../../lib/storefrontRateLimit'
+import type { StoreContextService } from '../../../../lib/storeContextService'
+import { cachedGetStorefrontProductDetail } from '../../../../lib/storefrontProductCache'
+import { parseStorefrontProductDetailQuery } from '../../../../lib/storefrontQuery'
+import {
+  storefrontErrorResponse,
+  storefrontErrorSchema,
+  storefrontInvalidQueryErrorSchema,
+  storefrontRouteErrorResponse,
+  storefrontSuccessHeaders,
+  runInStoreCacheTenant,
+} from '../../storefrontRouteSupport'
+import { storefrontProductDetailResponseSchema } from '../openapiSchemas'
+
+export const metadata = {
+  path: '/ecommerce/storefront/products/[idOrHandle]',
+  GET: {
+    requireAuth: false,
+  },
+}
+
+const ANONYMOUS_CACHE_CONTROL = 'public, max-age=60'
+const PRODUCT_NOT_FOUND = { error: 'product_not_found' } as const
+
+type ProductRouteParams = { idOrHandle?: string }
+
+type ProductRouteContext = { params?: ProductRouteParams | Promise<ProductRouteParams> }
+
+export async function GET(req: Request, routeContext: ProductRouteContext = {}) {
+  try {
+    const query = parseStorefrontProductDetailQuery(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, 'productDetail')
+      if (rateLimited) return rateLimited
+      const params = ecommerceStorefrontProductParamsSchema.safeParse((await routeContext.params) ?? {})
+      if (!params.success) return storefrontErrorResponse(404, { ...PRODUCT_NOT_FOUND })
+      const detail = await cachedGetStorefrontProductDetail(container, context, params.data.idOrHandle, {
+        variantId: query.variantId ?? null,
+        locale: query.locale ?? null,
+      })
+      if (!detail) return storefrontErrorResponse(404, { ...PRODUCT_NOT_FOUND })
+      return NextResponse.json(detail, { headers: storefrontSuccessHeaders(context, ANONYMOUS_CACHE_CONTROL) })
+    })
+  } catch (error) {
+    return storefrontRouteErrorResponse(error, {
+      message: 'Storefront product detail failed',
+      code: 'ecommerce.storefront_product_detail_failed',
+    })
+  }
+}
+
+export default GET
+
+const storefrontProductTag = 'Ecommerce'
+
+const storefrontProductGetDoc: OpenApiMethodDoc = {
+  summary: 'Get one storefront product for the current buyer',
+  description:
+    'Public. Resolves the store from the Host header and the optional portal session, then returns the product by UUID or handle with buyer-resolved prices per variant. A product that does not exist, is inactive, deleted, of another tenant or outside the buyer\'s effective assortment answers the same 404 `{ "error": "product_not_found" }`. `variantId` preselects a variant; top-level `priceTiers` are the selected variant\'s tiers. Anonymous responses are `public, max-age=60`; authenticated responses are `private, no-store`. Cached server-side for 60 s per buyer context digest. Rate limited per IP and store.',
+  tags: [storefrontProductTag],
+  pathParams: ecommerceStorefrontProductParamsSchema,
+  query: ecommerceStorefrontProductDetailQuerySchema,
+  responses: [
+    { status: 200, description: 'The product as this buyer sees it.', schema: storefrontProductDetailResponseSchema },
+  ],
+  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, or the product is not visible to this buyer', 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: storefrontProductTag,
+  summary: 'Public storefront product detail',
+  methods: {
+    GET: storefrontProductGetDoc,
+  },
+}