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

package/src/modules/ecommerce/components/storeBrandingForm.ts

@@ -0,0 +1,230 @@
+import { z } from 'zod'
+import { ecommerceStoreBrandingSchema, isSafeAssetUrl } from '../data/validators'
+import {
+  ECOMMERCE_BRANDING_COLOR_KEYS,
+  ECOMMERCE_BRANDING_DEFAULTS,
+  ECOMMERCE_BRANDING_FONT_KEYS,
+  findEcommerceBrandingFont,
+  isValidBorderRadius,
+  normalizeBrandingColor,
+  renderBrandingRootRule,
+  type EcommerceBrandingColorKey,
+  type EcommerceBrandingFontKey,
+} from '../lib/brandingStyles'
+import type { StoreAdminRecord } from './storeAdmin'
+
+export const BRANDING_COLOR_KEYS = ECOMMERCE_BRANDING_COLOR_KEYS
+export const BRANDING_FONT_KEYS = ECOMMERCE_BRANDING_FONT_KEYS
+export const BRANDING_ASSET_KEYS = ['logoUrl', 'faviconUrl'] as const
+
+export type BrandingAssetKey = (typeof BRANDING_ASSET_KEYS)[number]
+export type StoreBrandingFormKey =
+  | EcommerceBrandingColorKey
+  | EcommerceBrandingFontKey
+  | BrandingAssetKey
+  | 'borderRadius'
+
+export type StoreBrandingFormValues = Record<StoreBrandingFormKey, string>
+
+export type StoreBrandingPayload = Partial<Record<StoreBrandingFormKey, string>>
+
+export const BRANDING_FONT_INHERIT = 'inherit'
+export const DEFAULT_BASE_FONT_ID = 'inter'
+export const RADIUS_SLIDER_MIN = 0
+export const RADIUS_SLIDER_MAX = 5
+export const RADIUS_SLIDER_STEP = 0.125
+const PX_PER_REM = 16
+
+export const STORE_BRANDING_API_PATH = (storeId: string) => `/api/ecommerce/stores/${encodeURIComponent(storeId)}/branding`
+
+const ALL_KEYS: readonly StoreBrandingFormKey[] = [
+  ...BRANDING_COLOR_KEYS,
+  'borderRadius',
+  ...BRANDING_FONT_KEYS,
+  ...BRANDING_ASSET_KEYS,
+]
+
+function readStoredBranding(store: Pick<StoreAdminRecord, 'settings'>): Record<string, unknown> {
+  const branding = store.settings?.branding
+  return typeof branding === 'object' && branding !== null && !Array.isArray(branding)
+    ? (branding as Record<string, unknown>)
+    : {}
+}
+
+function readStoredString(stored: Record<string, unknown>, key: string): string {
+  const value = stored[key]
+  return typeof value === 'string' ? value : ''
+}
+
+export function buildStoreBrandingInitialValues(store: Pick<StoreAdminRecord, 'settings'>): StoreBrandingFormValues {
+  const stored = readStoredBranding(store)
+  const values = {} as StoreBrandingFormValues
+  for (const key of BRANDING_COLOR_KEYS) {
+    values[key] = readStoredString(stored, key) || ECOMMERCE_BRANDING_DEFAULTS[key]
+  }
+  values.borderRadius = readStoredString(stored, 'borderRadius') || ECOMMERCE_BRANDING_DEFAULTS.borderRadius
+  values.fontFamilyBase = readStoredString(stored, 'fontFamilyBase') || DEFAULT_BASE_FONT_ID
+  values.fontFamilyHeading = readStoredString(stored, 'fontFamilyHeading') || BRANDING_FONT_INHERIT
+  values.logoUrl = readStoredString(stored, 'logoUrl')
+  values.faviconUrl = readStoredString(stored, 'faviconUrl')
+  return values
+}
+
+function readFormString(values: Record<string, unknown>, key: string): string {
+  const value = values[key]
+  return typeof value === 'string' ? value.trim() : ''
+}
+
+function defaultValueFor(key: StoreBrandingFormKey): string | null {
+  if (key === 'fontFamilyBase') return DEFAULT_BASE_FONT_ID
+  if (key === 'fontFamilyHeading') return BRANDING_FONT_INHERIT
+  if (key === 'logoUrl' || key === 'faviconUrl') return null
+  return ECOMMERCE_BRANDING_DEFAULTS[key]
+}
+
+export function buildStoreBrandingInput(values: Record<string, unknown>): StoreBrandingPayload {
+  const input: StoreBrandingPayload = {}
+  for (const key of ALL_KEYS) {
+    const value = readFormString(values, key)
+    if (value === '' || value === BRANDING_FONT_INHERIT) continue
+    input[key] = value
+  }
+  return input
+}
+
+export function buildStoreBrandingPayload(
+  values: Record<string, unknown>,
+  store: Pick<StoreAdminRecord, 'settings'>,
+): StoreBrandingPayload {
+  const stored = readStoredBranding(store)
+  const input = buildStoreBrandingInput(values)
+  const payload: StoreBrandingPayload = {}
+  for (const key of ALL_KEYS) {
+    const value = input[key]
+    if (value === undefined) continue
+    const wasStored = readStoredString(stored, key) !== ''
+    if (!wasStored && value === defaultValueFor(key)) continue
+    payload[key] = value
+  }
+  return payload
+}
+
+const brandingFormShape = {
+  primaryColor: z.string(),
+  primaryForeground: z.string(),
+  accentColor: z.string(),
+  accentForeground: z.string(),
+  backgroundColor: z.string(),
+  foregroundColor: z.string(),
+  borderRadius: z.string(),
+  fontFamilyBase: z.string(),
+  fontFamilyHeading: z.string(),
+  logoUrl: z.string(),
+  faviconUrl: z.string(),
+} satisfies Record<StoreBrandingFormKey, z.ZodString>
+
+export const storeBrandingFormSchema = z.object(brandingFormShape).superRefine((values, context) => {
+  const result = ecommerceStoreBrandingSchema.safeParse(buildStoreBrandingInput(values))
+  if (result.success) return
+  for (const issue of result.error.issues) {
+    context.addIssue({ code: 'custom', path: issue.path, message: issue.message })
+  }
+})
+
+export function parseRadiusRem(value: string): number {
+  const trimmed = value.trim()
+  if (trimmed === '0') return 0
+  const match = /^(\d+(?:\.\d+)?|\.\d+)(rem|px)$/.exec(trimmed)
+  if (!match) return parseRadiusRem(ECOMMERCE_BRANDING_DEFAULTS.borderRadius)
+  const amount = Number(match[1])
+  const rem = match[2] === 'px' ? amount / PX_PER_REM : amount
+  return Math.min(RADIUS_SLIDER_MAX, Math.max(RADIUS_SLIDER_MIN, rem))
+}
+
+export function formatRadiusRem(rem: number): string {
+  if (rem <= 0) return '0'
+  return `${Number(rem.toFixed(3))}rem`
+}
+
+export type SanitizedPreviewBranding = Partial<Record<StoreBrandingFormKey, string>>
+
+export function sanitizePreviewBranding(values: Record<string, unknown>): SanitizedPreviewBranding {
+  const input = buildStoreBrandingInput(values)
+  const sanitized: SanitizedPreviewBranding = {}
+  for (const key of BRANDING_COLOR_KEYS) {
+    const raw = input[key]
+    const normalized = raw === undefined ? null : normalizeBrandingColor(raw)
+    if (normalized !== null) sanitized[key] = normalized
+  }
+  const radius = input.borderRadius
+  if (radius !== undefined && isValidBorderRadius(radius)) sanitized.borderRadius = radius
+  for (const key of BRANDING_FONT_KEYS) {
+    const raw = input[key]
+    if (raw !== undefined && findEcommerceBrandingFont(raw)) sanitized[key] = raw
+  }
+  const logo = input.logoUrl
+  if (logo !== undefined && isSafeAssetUrl(logo)) sanitized.logoUrl = logo
+  return sanitized
+}
+
+export type BrandingPreviewLabels = {
+  storeName: string
+  navShop: string
+  navCategories: string
+  navCart: string
+  heroTitle: string
+  heroText: string
+  heroButton: string
+  productName: string
+  productPrice: string
+}
+
+const HTML_ESCAPES: Readonly<Record<string, string>> = {
+  '&': '&amp;',
+  '<': '&lt;',
+  '>': '&gt;',
+  '"': '&quot;',
+  "'": '&#39;',
+}
+
+export function escapeHtml(value: string): string {
+  return value.replace(/[&<>"']/g, (character) => HTML_ESCAPES[character] ?? character)
+}
+
+const PREVIEW_CONTENT_SECURITY_POLICY = "default-src 'none'; style-src 'unsafe-inline'; img-src http: https:"
+
+const PREVIEW_STATIC_CSS = [
+  '*{box-sizing:border-box}',
+  'body{margin:0;background:var(--background);color:var(--foreground);font-family:var(--font-base);font-size:14px;line-height:1.5}',
+  'h1,.brand{font-family:var(--font-heading)}',
+  '.bar{display:flex;align-items:center;justify-content:space-between;gap:12px;padding:12px 20px;border-bottom:1px solid color-mix(in oklch,var(--foreground) 15%,transparent)}',
+  '.brand{display:flex;align-items:center;gap:8px;font-size:16px;font-weight:700}',
+  '.brand img{max-width:120px;max-height:28px}',
+  'nav{display:flex;gap:16px;opacity:.7}',
+  '.hero{padding:28px 20px;background:var(--accent);color:var(--accent-foreground)}',
+  '.hero h1{margin:0 0 8px;font-size:24px;line-height:1.2}',
+  '.hero p{margin:0 0 16px;max-width:36ch}',
+  '.btn{display:inline-block;padding:8px 16px;border-radius:var(--radius);background:var(--primary);color:var(--primary-foreground);font-weight:600}',
+  '.grid{display:grid;grid-template-columns:repeat(3,1fr);gap:12px;padding:20px}',
+  '.card{overflow:hidden;border:1px solid color-mix(in oklch,var(--foreground) 15%,transparent);border-radius:var(--radius)}',
+  '.thumb{height:56px;background:color-mix(in oklch,var(--primary) 20%,var(--background))}',
+  '.card-body{padding:10px}',
+  '.price{font-weight:600}',
+].join('')
+
+export function buildBrandingPreviewDocument(values: Record<string, unknown>, labels: BrandingPreviewLabels): string {
+  const branding = sanitizePreviewBranding(values)
+  const rootRule = renderBrandingRootRule(branding)
+  const logo = branding.logoUrl ? `<img src="${escapeHtml(branding.logoUrl)}" alt="">` : ''
+  const card = `<div class="card"><div class="thumb"></div><div class="card-body"><div>${escapeHtml(labels.productName)}</div><div class="price">${escapeHtml(labels.productPrice)}</div></div></div>`
+  return [
+    '<!doctype html><html><head><meta charset="utf-8">',
+    `<meta http-equiv="Content-Security-Policy" content="${PREVIEW_CONTENT_SECURITY_POLICY}">`,
+    `<style>${rootRule}</style><style>${PREVIEW_STATIC_CSS}</style></head><body>`,
+    `<header class="bar"><div class="brand">${logo}<span>${escapeHtml(labels.storeName)}</span></div>`,
+    `<nav><span>${escapeHtml(labels.navShop)}</span><span>${escapeHtml(labels.navCategories)}</span><span>${escapeHtml(labels.navCart)}</span></nav></header>`,
+    `<section class="hero"><h1>${escapeHtml(labels.heroTitle)}</h1><p>${escapeHtml(labels.heroText)}</p><span class="btn">${escapeHtml(labels.heroButton)}</span></section>`,
+    `<section class="grid">${card}${card}${card}</section>`,
+    '</body></html>',
+  ].join('')
+}

package/src/modules/ecommerce/components/storeChannels.ts

@@ -0,0 +1,210 @@
+import { z } from 'zod'
+import type { StatusBadgeVariant } from '@open-mercato/ui/primitives/status-badge'
+
+export const CHANNEL_BINDINGS_API_PATH = 'ecommerce/store-channel-bindings'
+export const CHANNEL_BINDINGS_API_URL = `/api/${CHANNEL_BINDINGS_API_PATH}`
+export const CHANNEL_BINDINGS_PAGE_SIZE = 100
+export const ASSORTMENT_COUNT_DEBOUNCE_MS = 400
+export const PRICE_SORT_CAP = 5000
+
+export const PRICE_SORT_FALLBACKS = ['approximate', 'unavailable'] as const
+
+export type PriceSortFallback = (typeof PRICE_SORT_FALLBACKS)[number]
+
+export const DEFAULT_PRICE_SORT_FALLBACK: PriceSortFallback = 'approximate'
+
+export const SCOPE_ID_FIELDS = [
+  'categoryIds',
+  'tagIds',
+  'excludeProductIds',
+  'excludeCategoryIds',
+  'excludeTagIds',
+] as const
+
+export type ScopeIdField = (typeof SCOPE_ID_FIELDS)[number]
+
+export type ChannelAssortmentScope = Partial<Record<ScopeIdField, string[]>>
+
+export type ChannelBindingRecord = {
+  id: string
+  storeId: string
+  salesChannelId: string
+  priceKindId: string | null
+  assortmentScope: ChannelAssortmentScope | null
+  priceSortFallback: PriceSortFallback
+  isDefault: boolean
+  requireAuthentication: boolean
+  createdAt: string | null
+  updatedAt: string | null
+}
+
+export type ChannelBindingListResponse = {
+  items: ChannelBindingRecord[]
+  total: number
+  totalPages: number
+}
+
+export type AssortmentCountResult = {
+  count: number
+  scopeSource: 'saved' | 'draft'
+  requireAuthentication: boolean
+  reducedByAuthentication: boolean
+  countWithoutAuthentication: number
+  unindexedCount: number
+}
+
+export type AssortmentCountDraft = {
+  scope: ChannelAssortmentScope | null
+  requireAuthentication: boolean
+}
+
+export type ChannelBindingWritePayload = {
+  salesChannelId: string
+  priceKindId: string | null
+  assortmentScope: ChannelAssortmentScope | null
+  priceSortFallback: PriceSortFallback
+  requireAuthentication: boolean
+  isDefault?: boolean
+}
+
+export const PRICE_SORT_FALLBACK_LABELS: Record<PriceSortFallback, { key: string; fallback: string }> = {
+  approximate: {
+    key: 'ecommerce.backend.store.channels.priceSortFallback.approximate',
+    fallback: 'Approximate order from the default price kind',
+  },
+  unavailable: {
+    key: 'ecommerce.backend.store.channels.priceSortFallback.unavailable',
+    fallback: 'Withdraw price sorting',
+  },
+}
+
+export const PRICE_SORT_FALLBACK_VARIANTS: Record<PriceSortFallback, StatusBadgeVariant> = {
+  approximate: 'neutral',
+  unavailable: 'info',
+}
+
+export function isPriceSortFallback(value: unknown): value is PriceSortFallback {
+  return typeof value === 'string' && (PRICE_SORT_FALLBACKS as readonly string[]).includes(value)
+}
+
+function normalizeIds(value: unknown): string[] {
+  if (!Array.isArray(value)) return []
+  const seen = new Set<string>()
+  const ids: string[] = []
+  for (const entry of value) {
+    if (typeof entry !== 'string') continue
+    const trimmed = entry.trim()
+    if (!trimmed || seen.has(trimmed)) continue
+    seen.add(trimmed)
+    ids.push(trimmed)
+  }
+  return ids
+}
+
+/**
+ * Builds the `assortment_scope` sent to the server from the picker values. A cleared picker is
+ * omitted rather than sent as `[]`, and a scope with every picker cleared is `null` (no
+ * restriction), so clearing never reads as "hide everything" (US-E1).
+ */
+export function buildAssortmentScope(values: Partial<Record<ScopeIdField, unknown>>): ChannelAssortmentScope | null {
+  const scope: ChannelAssortmentScope = {}
+  for (const field of SCOPE_ID_FIELDS) {
+    const ids = normalizeIds(values[field])
+    if (ids.length > 0) scope[field] = ids
+  }
+  return Object.keys(scope).length > 0 ? scope : null
+}
+
+export function countScopeRules(scope: ChannelAssortmentScope | null | undefined): number {
+  if (!scope) return 0
+  return SCOPE_ID_FIELDS.reduce((total, field) => total + (scope[field]?.length ?? 0), 0)
+}
+
+export function buildChannelBindingInitialValues(
+  binding: ChannelBindingRecord | null,
+  options: { firstBinding: boolean },
+): ChannelBindingFormValues {
+  const scope = binding?.assortmentScope ?? null
+  return {
+    salesChannelId: binding?.salesChannelId ?? '',
+    priceKindId: binding?.priceKindId ?? '',
+    isDefault: binding ? binding.isDefault : options.firstBinding,
+    requireAuthentication: binding?.requireAuthentication ?? false,
+    priceSortFallback: isPriceSortFallback(binding?.priceSortFallback)
+      ? binding.priceSortFallback
+      : DEFAULT_PRICE_SORT_FALLBACK,
+    categoryIds: normalizeIds(scope?.categoryIds),
+    tagIds: normalizeIds(scope?.tagIds),
+    excludeProductIds: normalizeIds(scope?.excludeProductIds),
+    excludeCategoryIds: normalizeIds(scope?.excludeCategoryIds),
+    excludeTagIds: normalizeIds(scope?.excludeTagIds),
+  }
+}
+
+function buildWritePayload(values: ChannelBindingFormValues): ChannelBindingWritePayload {
+  const priceKindId = typeof values.priceKindId === 'string' ? values.priceKindId.trim() : ''
+  return {
+    salesChannelId: values.salesChannelId.trim(),
+    priceKindId: priceKindId.length > 0 ? priceKindId : null,
+    assortmentScope: buildAssortmentScope(values),
+    priceSortFallback: isPriceSortFallback(values.priceSortFallback) ? values.priceSortFallback : DEFAULT_PRICE_SORT_FALLBACK,
+    requireAuthentication: values.requireAuthentication === true,
+  }
+}
+
+export function buildChannelBindingCreatePayload(
+  storeId: string,
+  values: ChannelBindingFormValues,
+): ChannelBindingWritePayload & { storeId: string; isDefault: boolean } {
+  return { storeId, ...buildWritePayload(values), isDefault: values.isDefault === true }
+}
+
+/**
+ * The default mark is only ever promoted from this form: un-ticking it on the current default
+ * would leave the store without a default binding (a `503` for every storefront request), so the
+ * update omits `isDefault` unless it asks for the promotion.
+ */
+export function buildChannelBindingUpdatePayload(
+  bindingId: string,
+  values: ChannelBindingFormValues,
+): ChannelBindingWritePayload & { id: string } {
+  const payload: ChannelBindingWritePayload & { id: string } = { id: bindingId, ...buildWritePayload(values) }
+  if (values.isDefault === true) payload.isDefault = true
+  return payload
+}
+
+export function buildAssortmentCountDraft(
+  values: Partial<Record<ScopeIdField | 'requireAuthentication', unknown>>,
+): AssortmentCountDraft {
+  return {
+    scope: buildAssortmentScope(values),
+    requireAuthentication: values.requireAuthentication === true,
+  }
+}
+
+export function buildAssortmentCountUrl(bindingId: string, draft: AssortmentCountDraft | null): string {
+  const base = `${CHANNEL_BINDINGS_API_URL}/${encodeURIComponent(bindingId)}/assortment-count`
+  if (!draft) return base
+  const params = new URLSearchParams({
+    draftScope: JSON.stringify(draft.scope),
+    draftRequireAuthentication: draft.requireAuthentication ? 'true' : 'false',
+  })
+  return `${base}?${params.toString()}`
+}
+
+const REQUIRED_MESSAGE = 'ui.forms.errors.required'
+
+export const channelBindingFormSchema = z.object({
+  salesChannelId: z.string().trim().min(1, REQUIRED_MESSAGE),
+  priceKindId: z.string().default(''),
+  isDefault: z.boolean().default(false),
+  requireAuthentication: z.boolean().default(false),
+  priceSortFallback: z.enum(PRICE_SORT_FALLBACKS).default(DEFAULT_PRICE_SORT_FALLBACK),
+  categoryIds: z.array(z.string()).default([]),
+  tagIds: z.array(z.string()).default([]),
+  excludeProductIds: z.array(z.string()).default([]),
+  excludeCategoryIds: z.array(z.string()).default([]),
+  excludeTagIds: z.array(z.string()).default([]),
+})
+
+export type ChannelBindingFormValues = z.infer<typeof channelBindingFormSchema>

package/src/modules/ecommerce/components/storeDomains.ts

@@ -0,0 +1,221 @@
+import { z } from 'zod'
+import type { StatusBadgeVariant } from '@open-mercato/ui/primitives/status-badge'
+import type { DomainBindingMappingState } from '../data/enrichers'
+import { ecommerceStoreDomainBindingCreateSchema, normalizePathPrefix } from '../data/validators'
+import { isDomainMappingStatus, type DomainMappingStatus, type DomainMappingSummary } from '../lib/domainMappingSummaries'
+
+export const DOMAIN_BINDINGS_API_PATH = 'ecommerce/store-domain-bindings'
+export const DOMAIN_BINDINGS_API_URL = `/api/${DOMAIN_BINDINGS_API_PATH}`
+export const DOMAIN_MAPPINGS_API_URL = '/api/ecommerce/domain-mappings'
+export const DOMAIN_SETTINGS_HREF = '/backend/customer_accounts/settings/domain'
+export const DOMAIN_BINDINGS_PAGE_SIZE = 100
+
+export type DomainBindingRecord = {
+  id: string
+  storeId: string
+  domainMappingId: string
+  pathPrefix: string | null
+  isPrimary: boolean
+  createdAt: string | null
+  updatedAt: string | null
+  _domainMapping?: DomainBindingMappingState
+}
+
+export type DomainBindingListResponse = {
+  items: DomainBindingRecord[]
+  total: number
+  totalPages: number
+}
+
+export type DomainMappingListResponse = {
+  items: DomainMappingSummary[]
+  total: number
+}
+
+export type DomainBindingFormValues = {
+  domainMappingId: string
+  pathPrefix: string
+  isPrimary: boolean
+}
+
+export const DOMAIN_STATUS_VARIANTS: Record<DomainMappingStatus, StatusBadgeVariant> = {
+  pending: 'info',
+  verified: 'info',
+  active: 'success',
+  dns_failed: 'error',
+  tls_failed: 'warning',
+}
+
+export const DOMAIN_STATUS_LABELS: Record<DomainMappingStatus, { key: string; fallback: string }> = {
+  pending: { key: 'ecommerce.backend.store.domains.status.pending', fallback: 'Pending' },
+  verified: { key: 'ecommerce.backend.store.domains.status.verified', fallback: 'Verified' },
+  active: { key: 'ecommerce.backend.store.domains.status.active', fallback: 'Active' },
+  dns_failed: { key: 'ecommerce.backend.store.domains.status.dnsFailed', fallback: 'DNS failed' },
+  tls_failed: { key: 'ecommerce.backend.store.domains.status.tlsFailed', fallback: 'TLS failed' },
+}
+
+export type DomainFailureReasonLabel = { key: string; fallback: string; params: Record<string, string> }
+
+type DomainFailureReasonPattern = {
+  pattern: RegExp
+  key: string
+  fallback: string
+  params: readonly string[]
+}
+
+const DOMAIN_FAILURE_REASON_PATTERNS: readonly DomainFailureReasonPattern[] = [
+  {
+    pattern: /^HTTP (\d{3})$/,
+    key: 'ecommerce.backend.store.domains.failure.httpStatus',
+    fallback: 'The TLS health check returned HTTP {status}',
+    params: ['status'],
+  },
+  {
+    pattern: /^TLS health check timed out$/,
+    key: 'ecommerce.backend.store.domains.failure.tlsTimeout',
+    fallback: 'The TLS health check timed out',
+    params: [],
+  },
+  {
+    pattern: /^TLS health check failed$/,
+    key: 'ecommerce.backend.store.domains.failure.tlsFailed',
+    fallback: 'The TLS health check failed',
+    params: [],
+  },
+  {
+    pattern: /^DNS lookup error \((CNAME|A)\): /,
+    key: 'ecommerce.backend.store.domains.failure.dnsLookup',
+    fallback: 'The DNS lookup for the {recordType} record failed',
+    params: ['recordType'],
+  },
+  {
+    pattern: /^CNAME points to (.+) instead of (.+)$/,
+    key: 'ecommerce.backend.store.domains.failure.cnameMismatch',
+    fallback: 'The CNAME record points to {actual} instead of {expected}',
+    params: ['actual', 'expected'],
+  },
+  {
+    pattern: /^No CNAME or A record found for /,
+    key: 'ecommerce.backend.store.domains.failure.noRecords',
+    fallback: 'No CNAME or A record was found',
+    params: [],
+  },
+  {
+    pattern: /^A record points to a known proxy IP, but reverse-resolve over HTTPS did not reach our server$/,
+    key: 'ecommerce.backend.store.domains.failure.proxyUnreachable',
+    fallback: 'The domain is behind a proxy that does not forward traffic to this platform',
+    params: [],
+  },
+  {
+    pattern: /^A record points to (.+) instead of (.+)$/,
+    key: 'ecommerce.backend.store.domains.failure.aRecordMismatch',
+    fallback: 'The A record points to {actual} instead of {expected}',
+    params: ['actual', 'expected'],
+  },
+  {
+    pattern: /^A record points to (.+) but apex-domain registration is not enabled on this deployment$/,
+    key: 'ecommerce.backend.store.domains.failure.apexNotEnabled',
+    fallback: 'The A record points to {actual}, but apex domains are not enabled on this deployment',
+    params: ['actual'],
+  },
+]
+
+export function describeDomainFailureReason(reason: string): DomainFailureReasonLabel | null {
+  for (const entry of DOMAIN_FAILURE_REASON_PATTERNS) {
+    const match = entry.pattern.exec(reason)
+    if (!match) continue
+    const params: Record<string, string> = {}
+    entry.params.forEach((name, index) => {
+      params[name] = match[index + 1] ?? ''
+    })
+    return { key: entry.key, fallback: entry.fallback, params }
+  }
+  return null
+}
+
+export function isServingStatus(status: string): boolean {
+  return status === 'active'
+}
+
+export function describeDomainStatus(status: string): { variant: StatusBadgeVariant; key: string; fallback: string } {
+  if (isDomainMappingStatus(status)) {
+    return { variant: DOMAIN_STATUS_VARIANTS[status], ...DOMAIN_STATUS_LABELS[status] }
+  }
+  return { variant: 'neutral', key: '', fallback: status }
+}
+
+export function formatBindingAddress(hostname: string, pathPrefix: string | null): string {
+  return `${hostname}${pathPrefix ?? ''}`
+}
+
+export function normalizeBindingPrefix(value: string | null | undefined): string | null {
+  const normalized = normalizePathPrefix(value ?? null)
+  return typeof normalized === 'string' && normalized.length > 0 ? normalized : null
+}
+
+export function findDuplicateBinding(
+  bindings: readonly DomainBindingRecord[],
+  candidate: { domainMappingId: string; pathPrefix: string | null },
+  ignoreBindingId: string | null,
+): DomainBindingRecord | null {
+  return (
+    bindings.find(
+      (binding) =>
+        binding.id !== ignoreBindingId &&
+        binding.domainMappingId === candidate.domainMappingId &&
+        (binding.pathPrefix ?? null) === candidate.pathPrefix,
+    ) ?? null
+  )
+}
+
+export function findPreviousPrimary(
+  bindings: readonly DomainBindingRecord[],
+  nextPrimaryId: string,
+): DomainBindingRecord | null {
+  return bindings.find((binding) => binding.isPrimary && binding.id !== nextPrimaryId) ?? null
+}
+
+const REQUIRED_MESSAGE = 'ui.forms.errors.required'
+
+export const domainBindingFormSchema = z.object({
+  domainMappingId: z.string().trim().min(1, REQUIRED_MESSAGE),
+  pathPrefix: z
+    .string()
+    .superRefine((value, ctx) => {
+      const parsed = ecommerceStoreDomainBindingCreateSchema.shape.pathPrefix.safeParse(value)
+      if (!parsed.success) ctx.addIssue({ code: 'custom', message: 'ecommerce.validation.pathPrefixInvalid' })
+    }),
+  isPrimary: z.boolean(),
+})
+
+export function buildDomainBindingInitialValues(binding: DomainBindingRecord | null): DomainBindingFormValues {
+  return {
+    domainMappingId: binding?.domainMappingId ?? '',
+    pathPrefix: binding?.pathPrefix ?? '',
+    isPrimary: binding?.isPrimary ?? false,
+  }
+}
+
+export function buildDomainBindingCreatePayload(
+  storeId: string,
+  values: DomainBindingFormValues,
+): { storeId: string; domainMappingId: string; pathPrefix: string | null; isPrimary: boolean } {
+  return {
+    storeId,
+    domainMappingId: values.domainMappingId,
+    pathPrefix: normalizeBindingPrefix(values.pathPrefix),
+    isPrimary: values.isPrimary === true,
+  }
+}
+
+export function buildDomainBindingUpdatePayload(
+  bindingId: string,
+  values: DomainBindingFormValues,
+): { id: string; domainMappingId: string; pathPrefix: string | null; isPrimary: boolean } {
+  return {
+    id: bindingId,
+    domainMappingId: values.domainMappingId,
+    pathPrefix: normalizeBindingPrefix(values.pathPrefix),
+    isPrimary: values.isPrimary === true,
+  }
+}