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

package/src/modules/ecommerce/lib/storeContextService.ts

@@ -0,0 +1,71 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { runWithCacheTenant } from '@open-mercato/cache'
+import { composeStoreContext, resolveBuyerContext } from './buyerContext'
+import { buyerContextCache, ecommerceResolutionCache, ecommerceStoreTag, type CacheContainer } from './cacheKeys'
+import {
+  resolveStoreBySlug,
+  resolveStoreFromRequest,
+  type ResolveStoreBySlugOptions,
+  type ResolveStoreFromRequestOptions,
+} from './storeContext'
+import type { StoreContext } from './types'
+
+/**
+ * `storeContextService` (SPEC-029 §6): composes the store layer (`storeContext.ts`) and the
+ * buyer layer (`buyerContext.ts`) into a full `StoreContext`. Registered per request container.
+ */
+
+export type ResolveStoreContextBySlugOptions = ResolveStoreBySlugOptions & {
+  request?: Request | null
+}
+
+export type InvalidateStoreContextOptions = { tenantId?: string | null }
+
+export type StoreContextService = {
+  resolve(request: Request, opts?: ResolveStoreFromRequestOptions): Promise<StoreContext>
+  resolveBySlug(slug: string, opts?: ResolveStoreContextBySlugOptions): Promise<StoreContext>
+  invalidate(storeId: string, opts?: InvalidateStoreContextOptions): Promise<void>
+}
+
+type StoreTenantDatabase = {
+  ecommerce_stores: { id: string; tenant_id: string }
+}
+
+async function lookupStoreTenantId(container: CacheContainer, storeId: string): Promise<string | null> {
+  let em: EntityManager | null = null
+  try {
+    em = (container.resolve('em') as EntityManager | null | undefined) ?? null
+  } catch {
+    em = null
+  }
+  if (!em) return null
+  const row = await em
+    .getKysely<StoreTenantDatabase>()
+    .selectFrom('ecommerce_stores')
+    .select('tenant_id')
+    .where('id', '=', storeId)
+    .executeTakeFirst()
+  return row?.tenant_id ?? null
+}
+
+export function createStoreContextService(container: CacheContainer): StoreContextService {
+  return {
+    async resolve(request, opts) {
+      const store = await resolveStoreFromRequest(container, request, opts)
+      const buyer = await runWithCacheTenant(store.tenantId, () => resolveBuyerContext(container, store, request))
+      return composeStoreContext(store, buyer)
+    },
+    async resolveBySlug(slug, opts = {}) {
+      const { request = null, ...slugOptions } = opts
+      const store = await resolveStoreBySlug(container, slug, slugOptions)
+      const buyer = await runWithCacheTenant(store.tenantId, () => resolveBuyerContext(container, store, request))
+      return composeStoreContext(store, buyer)
+    },
+    async invalidate(storeId, opts = {}) {
+      const tags = [ecommerceStoreTag(storeId)]
+      await ecommerceResolutionCache(container).deleteByTags(tags)
+      const tenantId = opts.tenantId ?? (await lookupStoreTenantId(container, storeId))
+      if (tenantId) await buyerContextCache(container, { tenantId, storeId }).deleteByTags(tags)
+    },
+  }
+}

package/src/modules/ecommerce/lib/storeLocale.ts

@@ -0,0 +1,88 @@
+/**
+ * Storefront locale negotiation (SPEC-029 §4.1 step 7, §6.2): `?locale` → `X-Locale` →
+ * `Accept-Language` (q-values honored) → `store.defaultLocale`. A candidate is used only when it
+ * matches one of `store.supportedLocales`; an unsupported request falls back without failing.
+ */
+
+export type StoreLocaleSettings = {
+  defaultLocale: string
+  supportedLocales: string[]
+}
+
+export type StoreLocaleCandidates = {
+  queryLocale?: string | null
+  headerLocale?: string | null
+  acceptLanguage?: string | null
+}
+
+export type StoreLocaleResolution = {
+  effectiveLocale: string
+  requestedLocale: string | null
+}
+
+const LOCALE_TAG_PATTERN = /^[A-Za-z]{2,8}(?:-[A-Za-z0-9]{1,8})*$/
+const LOCALE_TAG_MAX_LENGTH = 35
+const ACCEPT_LANGUAGE_MAX_LENGTH = 1024
+const ACCEPT_LANGUAGE_MAX_ENTRIES = 20
+const QUALITY_PATTERN = /^q=([01](?:\.\d{0,3})?)$/i
+
+export function sanitizeLocaleTag(value: string | null | undefined): string | null {
+  if (typeof value !== 'string') return null
+  const trimmed = value.trim()
+  if (!trimmed.length || trimmed.length > LOCALE_TAG_MAX_LENGTH) return null
+  const normalized = trimmed.replace(/_/g, '-')
+  return LOCALE_TAG_PATTERN.test(normalized) ? normalized : null
+}
+
+export function parseAcceptLanguage(header: string | null | undefined): string[] {
+  if (typeof header !== 'string' || !header.trim().length) return []
+  const entries = header
+    .slice(0, ACCEPT_LANGUAGE_MAX_LENGTH)
+    .split(',')
+    .slice(0, ACCEPT_LANGUAGE_MAX_ENTRIES)
+    .map((part, index) => {
+      const [rawTag, ...params] = part.split(';')
+      let quality = 1
+      for (const param of params) {
+        const match = QUALITY_PATTERN.exec(param.trim())
+        if (match) quality = Number.parseFloat(match[1])
+      }
+      return { tag: sanitizeLocaleTag(rawTag), quality, index }
+    })
+    .filter((entry): entry is { tag: string; quality: number; index: number } => entry.tag !== null && entry.quality > 0)
+  entries.sort((left, right) => right.quality - left.quality || left.index - right.index)
+  return entries.map((entry) => entry.tag)
+}
+
+function baseLanguage(locale: string): string {
+  return locale.toLowerCase().split('-')[0]
+}
+
+export function matchSupportedLocale(candidate: string, supportedLocales: string[]): string | null {
+  const lowered = candidate.toLowerCase()
+  const exact = supportedLocales.find((locale) => locale.toLowerCase() === lowered)
+  if (exact) return exact
+  const base = baseLanguage(candidate)
+  const baseExact = supportedLocales.find((locale) => locale.toLowerCase() === base)
+  if (baseExact) return baseExact
+  return supportedLocales.find((locale) => baseLanguage(locale) === base) ?? null
+}
+
+export function resolveStoreLocale(
+  store: StoreLocaleSettings,
+  candidates: StoreLocaleCandidates,
+): StoreLocaleResolution {
+  const queryLocale = sanitizeLocaleTag(candidates.queryLocale)
+  const headerLocale = sanitizeLocaleTag(candidates.headerLocale)
+  const ordered = [
+    ...(queryLocale ? [queryLocale] : []),
+    ...(headerLocale ? [headerLocale] : []),
+    ...parseAcceptLanguage(candidates.acceptLanguage),
+  ]
+  const requestedLocale = queryLocale ?? headerLocale ?? null
+  for (const candidate of ordered) {
+    const matched = matchSupportedLocale(candidate, store.supportedLocales)
+    if (matched) return { effectiveLocale: matched, requestedLocale }
+  }
+  return { effectiveLocale: store.defaultLocale, requestedLocale }
+}

package/src/modules/ecommerce/lib/storeNotifications.ts

@@ -0,0 +1,55 @@
+import { buildFeatureNotificationFromType } from '../../notifications/lib/notificationBuilder'
+import type { NotificationService } from '../../notifications/lib/notificationService'
+import { E } from '#generated/entities.ids.generated'
+import { notificationTypes } from '../notifications'
+import {
+  asPayloadRecord,
+  readEventScope,
+  readPayloadString,
+  tryResolveService,
+  type EcommerceSubscriberContext,
+} from './subscriberSupport'
+
+/**
+ * Store-manager alerts (SPEC-029 §9.4) delivered through `NotificationService.createForFeature`.
+ * Emitters already throttle per hour; the `groupKey` (store + UTC hour) additionally makes a
+ * retried or duplicated delivery refresh the recipient's existing notification instead of adding one.
+ */
+
+export const STORE_NOTIFICATION_FEATURE = 'ecommerce.stores.manage'
+
+export type StoreNotificationType = 'ecommerce.store.channel_binding_missing' | 'ecommerce.store.assortment_empty'
+
+type FeatureNotifier = Pick<NotificationService, 'createForFeature'>
+
+export function storeNotificationGroupKey(storeId: string, now: Date): string {
+  return `${storeId}:${now.toISOString().slice(0, 13)}`
+}
+
+export async function notifyStoreManagers(
+  payload: unknown,
+  ctx: EcommerceSubscriberContext,
+  type: StoreNotificationType,
+  now: Date = new Date(),
+): Promise<boolean> {
+  const record = asPayloadRecord(payload)
+  const storeId = readPayloadString(record, 'storeId') ?? readPayloadString(record, 'id')
+  const { tenantId, organizationId } = readEventScope(record, ctx)
+  if (!storeId || !tenantId || !organizationId) return false
+  const notificationService = tryResolveService<FeatureNotifier>(ctx, 'notificationService')
+  if (!notificationService) return false
+  const typeDef = notificationTypes.find((definition) => definition.type === type)
+  if (!typeDef) return false
+  const input = buildFeatureNotificationFromType(typeDef, {
+    requiredFeature: STORE_NOTIFICATION_FEATURE,
+    sourceEntityType: E.ecommerce.ecommerce_store,
+    sourceEntityId: storeId,
+    linkHref: `/backend/config/ecommerce/${encodeURIComponent(storeId)}`,
+    groupKey: storeNotificationGroupKey(storeId, now),
+  })
+  await notificationService.createForFeature(
+    { ...input, restrictRecipientsToOrganization: true },
+    { tenantId, organizationId },
+  )
+  return true
+}

package/src/modules/ecommerce/lib/storefrontCatalogSupport.ts

@@ -0,0 +1,427 @@
+import type { AwilixContainer } from 'awilix'
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { sql } from 'kysely'
+import {
+  availabilityItemKey,
+  resolveAvailability,
+  type AvailabilityItemResult,
+  type AvailabilityModuleConfigReader,
+  type AvailabilityState,
+} from '@open-mercato/shared/lib/availability'
+import { parseBooleanFromUnknown } from '@open-mercato/shared/lib/boolean'
+import { findWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import type { AssortmentScope, EffectiveAssortmentScope } from '@open-mercato/shared/lib/catalog-visibility'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+import { getTelemetryRuntime } from '@open-mercato/shared/lib/telemetry/runtime'
+import { AttachmentPartition } from '@open-mercato/core/modules/attachments/data/entities'
+import { CatalogProductCategory } from '@open-mercato/core/modules/catalog/data/entities'
+import { batchLoadTranslationsMany } from '@open-mercato/core/modules/translations/lib/batch'
+import type { StorefrontPrice, StorefrontPriceRange, StorefrontProductPricing } from './storefrontPricing'
+import type { StoreContext } from './types'
+
+const logger = createLogger('ecommerce')
+
+export const STOREFRONT_PRODUCT_ENTITY_TYPE = 'catalog:catalog_product'
+export const STOREFRONT_VARIANT_ENTITY_TYPE = 'catalog:catalog_product_variant'
+export const STOREFRONT_CATEGORY_ENTITY_TYPE = 'catalog:catalog_product_category'
+export const STOREFRONT_TAG_ENTITY_TYPE = 'catalog:catalog_product_tag'
+export const STOREFRONT_OPTION_SCHEMA_ENTITY_TYPE = 'catalog:catalog_option_schema_template'
+
+export type StorefrontAvailability = {
+  state: AvailabilityState
+  canFulfil: boolean
+  leadTimeDays: number | null
+  releaseAt: string | null
+}
+
+export type StorefrontProductListItem = {
+  id: string
+  handle: string | null
+  title: string
+  subtitle: string | null
+  defaultMediaUrl: string | null
+  productType: string
+  isConfigurable: boolean
+  hasVariants: boolean
+  variantCount: number
+  categories: Array<{ id: string; name: string; slug: string | null }>
+  tags: string[]
+  price: StorefrontPrice | null
+  priceRange: StorefrontPriceRange | null
+  availability: StorefrontAvailability
+  badges: string[]
+}
+
+export type CategoryLineage = { id: string; ancestorIds: string[]; descendantIds: string[] }
+
+export type CategoryRef = { id: string; name: string; slug: string | null }
+
+export type TagRef = { id: string; label: string }
+
+export type TranslationOverlay = Record<string, Record<string, unknown>>
+
+export type TranslationMap = Map<string, TranslationOverlay>
+
+export type StorefrontPolicyResolutionScope = {
+  tenantId: string
+  organizationId: string
+  storeId: string | null
+  productId: string
+  variantId: string | null
+}
+
+type ResolvedPolicyField<T> = { value: T } | null | undefined
+
+export type StorefrontResolvedPolicy = {
+  hideWhenOutOfStock?: ResolvedPolicyField<boolean>
+  minOrderQuantity?: ResolvedPolicyField<number | null>
+  maxOrderQuantity?: ResolvedPolicyField<number | null>
+  quantityIncrement?: ResolvedPolicyField<number | null>
+}
+
+export type StorefrontPolicyResolver = {
+  resolveMany(
+    em: EntityManager,
+    scopes: StorefrontPolicyResolutionScope[],
+  ): Promise<Array<StorefrontResolvedPolicy | null | undefined>>
+}
+
+export type StorefrontAvailabilityTarget = { productId: string; variantId: string | null }
+
+export type ResolvedStorefrontAvailability = {
+  result: AvailabilityItemResult | null
+  policy: StorefrontResolvedPolicy | null
+}
+
+export function tryResolve<T>(container: AwilixContainer, name: string): T | null {
+  try {
+    return (container.resolve(name) as T | null | undefined) ?? null
+  } catch {
+    return null
+  }
+}
+
+export function referenceId(value: unknown): string | null {
+  if (typeof value === 'string') return value.length ? value : null
+  if (value && typeof value === 'object' && 'id' in value) {
+    const id = (value as { id: unknown }).id
+    return typeof id === 'string' && id.length ? id : null
+  }
+  return null
+}
+
+export function stringList(value: unknown): string[] {
+  return Array.isArray(value) ? value.filter((entry): entry is string => typeof entry === 'string' && entry.length > 0) : []
+}
+
+export function nonEmptyString(value: unknown): string | null {
+  return typeof value === 'string' && value.trim().length > 0 ? value : null
+}
+
+function categoryBranchAdmits(branch: AssortmentScope, lineage: Set<string>, reach: Set<string>): boolean {
+  const included = stringList(branch.categoryIds)
+  if (included.length > 0 && !included.some((id) => reach.has(id))) return false
+  if (stringList(branch.excludeCategoryIds).some((id) => lineage.has(id))) return false
+  return (branch.allOf ?? []).every((nested) => categoryBranchAdmits(nested, lineage, reach))
+}
+
+/**
+ * Whether a category can hold any product the effective assortment admits: one of its own subtree
+ * or ancestors is granted by some branch, and neither it nor an ancestor is excluded there. Tag and
+ * product conditions are product-level and do not decide a category's visibility.
+ */
+export function isCategoryInAssortment(category: CategoryLineage, scope: EffectiveAssortmentScope): boolean {
+  if (scope === null) return true
+  const lineage = new Set([category.id, ...category.ancestorIds])
+  const reach = new Set([...lineage, ...category.descendantIds])
+  return scope.some((branch) => categoryBranchAdmits(branch, lineage, reach))
+}
+
+export type ActiveCategoryAncestor = { id: string; name: string; slug: string | null; ancestorIds: string[] }
+
+/**
+ * Which of the given categories have every ancestor active and not deleted — the rule the category
+ * tree applies, so a category hidden there under an inactive parent is hidden everywhere. Ancestors
+ * listed in `known` (already checked active) need no lookup; the rest cost one categories query, and
+ * none when every category is a root or has only known ancestors. `ancestors` holds the active
+ * ancestor rows, fetched and known, for callers that render them (breadcrumbs).
+ */
+export async function selectCategoriesWithActiveAncestors(
+  em: EntityManager,
+  ctx: Pick<StoreContext, 'tenantId' | 'organizationId'>,
+  categories: Array<{ id: string; ancestorIds: string[] }>,
+  known: { activeIds?: Iterable<string>; ancestors?: Map<string, ActiveCategoryAncestor> } = {},
+): Promise<{ visibleIds: Set<string>; ancestors: Map<string, ActiveCategoryAncestor> }> {
+  const ancestors = new Map(known.ancestors ?? [])
+  const active = new Set([...(known.activeIds ?? []), ...ancestors.keys()])
+  const unknown = Array.from(
+    new Set(categories.flatMap((category) => category.ancestorIds.filter((id) => !active.has(id)))),
+  )
+  if (unknown.length > 0) {
+    const rows = await findWithDecryption(
+      em,
+      CatalogProductCategory,
+      { id: { $in: unknown }, tenantId: ctx.tenantId, organizationId: ctx.organizationId, deletedAt: null, isActive: true },
+      { fields: ['id', 'name', 'slug', 'ancestorIds'] },
+      { tenantId: ctx.tenantId, organizationId: ctx.organizationId },
+    )
+    for (const row of rows) {
+      active.add(row.id)
+      ancestors.set(row.id, { id: row.id, name: row.name, slug: row.slug ?? null, ancestorIds: stringList(row.ancestorIds) })
+    }
+  }
+  const visibleIds = new Set(
+    categories.filter((category) => category.ancestorIds.every((id) => active.has(id))).map((category) => category.id),
+  )
+  return { visibleIds, ancestors }
+}
+
+export function localize(
+  base: unknown,
+  translations: TranslationOverlay | undefined,
+  field: string,
+  locales: string[],
+): string | null {
+  for (const locale of locales) {
+    const value = nonEmptyString(translations?.[locale]?.[field])
+    if (value !== null) return value
+  }
+  return nonEmptyString(base)
+}
+
+export function localeChain(ctx: StoreContext, preferredLocale?: string | null): string[] {
+  const head = preferredLocale && ctx.store.supportedLocales.includes(preferredLocale) ? preferredLocale : ctx.effectiveLocale
+  return Array.from(new Set([head, ctx.store.defaultLocale].filter((locale): locale is string => !!locale)))
+}
+
+export function toStorefrontAvailability(result: AvailabilityItemResult | null): StorefrontAvailability {
+  if (!result) return { state: 'not_tracked', canFulfil: true, leadTimeDays: null, releaseAt: null }
+  return {
+    state: result.state,
+    canFulfil: result.canFulfil,
+    leadTimeDays: result.leadTimeDays,
+    releaseAt: result.releaseAt,
+  }
+}
+
+export function storefrontAvailabilityKey(target: StorefrontAvailabilityTarget): string {
+  return availabilityItemKey({ catalogProductId: target.productId, catalogVariantId: target.variantId })
+}
+
+/**
+ * One batched `resolveAvailability` (state) and one `policyResolutionService.resolveMany` (quantity
+ * rules, `hideWhenOutOfStock`) for every product and variant of a response, keyed by
+ * `storefrontAvailabilityKey`. A missing policy service yields `policy: null`.
+ */
+export async function resolveStorefrontAvailability(
+  container: AwilixContainer,
+  ctx: StoreContext,
+  em: EntityManager,
+  targets: StorefrontAvailabilityTarget[],
+): Promise<Map<string, ResolvedStorefrontAvailability>> {
+  const results = new Map<string, ResolvedStorefrontAvailability>()
+  if (!targets.length) return results
+  const items = targets.map((target) => ({
+    catalogProductId: target.productId,
+    catalogVariantId: target.variantId,
+    quantity: 1,
+  }))
+  const moduleConfig = tryResolve<AvailabilityModuleConfigReader>(container, 'moduleConfigService')
+  const policyResolver = tryResolve<StorefrontPolicyResolver>(container, 'policyResolutionService')
+  const [availability, policies] = await Promise.all([
+    resolveAvailability(
+      {
+        tenantId: ctx.tenantId,
+        organizationId: ctx.organizationId,
+        storeId: ctx.store.id,
+        channelId: ctx.channel?.salesChannelId ?? null,
+        items,
+      },
+      moduleConfig ? { moduleConfig, container } : { container },
+    ),
+    policyResolver
+      ? policyResolver.resolveMany(
+          em,
+          targets.map((target) => ({
+            tenantId: ctx.tenantId,
+            organizationId: ctx.organizationId,
+            storeId: ctx.store.id,
+            productId: target.productId,
+            variantId: target.variantId,
+          })),
+        )
+      : Promise.resolve([]),
+  ])
+  targets.forEach((target, index) => {
+    const key = storefrontAvailabilityKey(target)
+    results.set(key, { result: availability.byItem[key] ?? null, policy: policies[index] ?? null })
+  })
+  return results
+}
+
+/**
+ * The response's translation overlays in one query (Storefront Public API §7.2: one call per
+ * response), keyed by entity type. A failure degrades to base fields and is reported.
+ */
+export async function loadStorefrontTranslations(
+  em: EntityManager,
+  ctx: StoreContext,
+  requests: Array<{ entityType: string; ids: string[] }>,
+): Promise<Map<string, TranslationMap>> {
+  const pending = requests.filter((request) => request.ids.length > 0)
+  if (!pending.length) return new Map()
+  try {
+    return await batchLoadTranslationsMany(
+      em.getKysely(),
+      pending.map((request) => ({ entityType: request.entityType, entityIds: request.ids })),
+      { tenantId: ctx.tenantId, organizationId: ctx.organizationId },
+    )
+  } catch (err) {
+    logger.error('[internal] ecommerce storefront translation overlay failed', {
+      tenantId: ctx.tenantId,
+      organizationId: ctx.organizationId,
+      storeId: ctx.store.id,
+      err,
+    })
+    getTelemetryRuntime()?.reportError(err, {
+      module: 'ecommerce',
+      code: 'ecommerce.storefront_translations_failed',
+      attributes: { entityTypes: pending.length },
+    })
+    return new Map()
+  }
+}
+
+export function isImageMimeType(mimeType: string | null | undefined): boolean {
+  return typeof mimeType === 'string' && mimeType.trim().toLowerCase().startsWith('image/')
+}
+
+/** The codes among `codes` naming a public attachment partition visible to the store's tenant and organization. */
+export async function loadPublicPartitionCodes(em: EntityManager, ctx: StoreContext, codes: string[]): Promise<Set<string>> {
+  if (!codes.length) return new Set()
+  const partitions = await findWithDecryption(
+    em,
+    AttachmentPartition,
+    {
+      code: { $in: codes },
+      isPublic: true,
+      $and: [
+        { $or: [{ tenantId: null }, { tenantId: ctx.tenantId }] },
+        { $or: [{ organizationId: null }, { organizationId: ctx.organizationId }] },
+      ],
+    },
+    { fields: ['id', 'code'] },
+    { tenantId: ctx.tenantId, organizationId: ctx.organizationId },
+  )
+  return new Set(partitions.map((partition) => partition.code))
+}
+
+export type StorefrontDefaultMediaRef = { id: string; defaultMediaId?: unknown; defaultMediaUrl?: unknown }
+
+type PublicMediaDatabase = {
+  attachments: {
+    id: string
+    tenant_id: string | null
+    organization_id: string | null
+    partition_code: string
+    mime_type: string
+  }
+  attachment_partitions: {
+    code: string
+    is_public: boolean
+    tenant_id: string | null
+    organization_id: string | null
+  }
+}
+
+/**
+ * Card `defaultMediaUrl`s held to the gallery rule of the product detail: a product's stored URL is
+ * returned only while its `defaultMediaId` names an `image/*` attachment of the store's tenant and
+ * organization in a public partition; otherwise it is `null`. One query for the whole page (the
+ * attachments joined to their partitions, plain non-encrypted columns), none when no product
+ * carries a default media id.
+ */
+export async function resolvePublicDefaultMediaUrls(
+  em: EntityManager,
+  ctx: StoreContext,
+  refs: StorefrontDefaultMediaRef[],
+): Promise<Map<string, string | null>> {
+  const urls = new Map<string, string | null>()
+  const pending: Array<{ productId: string; mediaId: string; url: string }> = []
+  for (const ref of refs) {
+    urls.set(ref.id, null)
+    const url = nonEmptyString(ref.defaultMediaUrl)
+    const mediaId = nonEmptyString(ref.defaultMediaId)
+    if (url && mediaId) pending.push({ productId: ref.id, mediaId, url })
+  }
+  if (!pending.length) return urls
+  const mediaIds = Array.from(new Set(pending.map((entry) => entry.mediaId)))
+  const rows = await em
+    .getKysely<PublicMediaDatabase>()
+    .selectFrom('attachments as a')
+    .innerJoin('attachment_partitions as p', 'p.code', 'a.partition_code')
+    .select(['a.id as id', 'a.mime_type as mime_type'])
+    .where(sql<boolean>`${sql.ref('a.id')} = any(${mediaIds}::uuid[])`)
+    .where('a.tenant_id', '=', ctx.tenantId)
+    .where('a.organization_id', '=', ctx.organizationId)
+    .where('p.is_public', '=', true)
+    .where((eb) => eb.or([eb('p.tenant_id', 'is', null), eb('p.tenant_id', '=', ctx.tenantId)]))
+    .where((eb) => eb.or([eb('p.organization_id', 'is', null), eb('p.organization_id', '=', ctx.organizationId)]))
+    .execute()
+  const publicIds = new Set(rows.filter((row) => isImageMimeType(row.mime_type)).map((row) => row.id))
+  for (const entry of pending) if (publicIds.has(entry.mediaId)) urls.set(entry.productId, entry.url)
+  return urls
+}
+
+export type StorefrontListItemSource = {
+  id: string
+  handle?: unknown
+  title?: unknown
+  subtitle?: unknown
+  defaultMediaUrl?: unknown
+  productType?: unknown
+  isConfigurable?: unknown
+}
+
+export type StorefrontListItemParts = {
+  locales: string[]
+  overlay?: TranslationOverlay
+  variantCount: number
+  categories: CategoryRef[]
+  categoryTranslations?: TranslationMap
+  tags: TagRef[]
+  tagTranslations?: TranslationMap
+  pricing?: StorefrontProductPricing
+  availability: StorefrontAvailability
+}
+
+export function buildStorefrontListItem(
+  source: StorefrontListItemSource,
+  parts: StorefrontListItemParts,
+): StorefrontProductListItem {
+  const { locales, overlay } = parts
+  const price = parts.pricing?.price ?? null
+  return {
+    id: source.id,
+    handle: nonEmptyString(source.handle),
+    title: localize(source.title, overlay, 'title', locales) ?? '',
+    subtitle: localize(source.subtitle, overlay, 'subtitle', locales),
+    defaultMediaUrl: nonEmptyString(source.defaultMediaUrl),
+    productType: nonEmptyString(source.productType) ?? 'simple',
+    isConfigurable: parseBooleanFromUnknown(source.isConfigurable) === true,
+    hasVariants: parts.variantCount > 0,
+    variantCount: parts.variantCount,
+    categories: parts.categories.map((category) => ({
+      id: category.id,
+      name: localize(category.name, parts.categoryTranslations?.get(category.id), 'name', locales) ?? category.name,
+      slug: category.slug,
+    })),
+    tags: parts.tags.map(
+      (tag) => localize(tag.label, parts.tagTranslations?.get(tag.id), 'label', locales) ?? tag.label,
+    ),
+    price,
+    priceRange: parts.pricing?.priceRange ?? null,
+    availability: parts.availability,
+    badges: price?.isPromotion ? ['sale'] : [],
+  }
+}