configuration-management 0.1.0

package/web/src/index.js

@@ -0,0 +1,41 @@
+/*
+Copyright 2025 Adobe. All rights reserved.
+This file is licensed to you under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License. You may obtain a copy
+of the License at http://www.apache.org/licenses/LICENSE-2.0
+*/
+
+import App from './components/App'
+import { MainPage } from './components/MainPage'
+import ExtensionRegistration from './components/ExtensionRegistration'
+import SystemConfig from './components/SystemConfig'
+import SystemConfigSchemaEditor from './components/SystemConfigSchemaEditor'
+import AppSectionNav, { NAV_ITEMS } from './components/AppSectionNav'
+
+export { useSystemConfig } from './hooks/useSystemConfig'
+export { useSystemConfigSchema } from './hooks/useSystemConfigSchema'
+export { useConfirm } from './hooks/useConfirm'
+
+export * from './schema/systemConfigSchema'
+export { buildStoreMappingsFromCommercePayload } from './utils/storeMappingsFromCommerceRest'
+export { callAction } from './utils'
+export {
+  configureWeb,
+  getExtensionId,
+  getActionKey,
+  DEFAULT_ACTION_KEYS
+} from './settings'
+export { THEME, PALETTE, RADIUS, SHADOW, SPACE, FONT } from './theme'
+
+export {
+  App,
+  MainPage,
+  ExtensionRegistration,
+  SystemConfig,
+  SystemConfigSchemaEditor,
+  AppSectionNav,
+  NAV_ITEMS
+}
+
+/** Full Commerce Admin extension shell (router + Spectrum provider). */
+export { default as ConfigurationManagementApp } from './components/App'

package/web/src/schema/systemConfigSchema.js

@@ -0,0 +1,82 @@
+/*
+Copyright 2025 Adobe. All rights reserved.
+This file is licensed to you under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License. You may obtain a copy
+of the License at http://www.apache.org/licenses/LICENSE-2.0
+*/
+
+/**
+ * Schema is no longer defined statically — it is stored in App Builder DB
+ * and managed entirely through the Schema Designer UI. This module only
+ * exposes helpers for working with whatever schema shape is loaded at runtime.
+ *
+ * Schema shape (returned from the system-config-schema action):
+ * {
+ *   sections: [{
+ *     id, label,
+ *     groups: [{
+ *       id, label,
+ *       fields: [{
+ *         id, label, type, default,
+ *         showIn: ['default' | 'websites' | 'stores'],
+ *         sensitive?: boolean,
+ *         options?: [{ value, label }]   // type === 'select'
+ *       }]
+ *     }]
+ *   }]
+ * }
+ */
+
+export const FIELD_TYPES = ['text', 'textarea', 'password', 'number', 'select', 'boolean']
+export const SCOPES = ['default', 'websites', 'stores']
+
+const SENSITIVE_FIELD_TYPES = new Set(['password'])
+
+export function emptySchema () {
+  return { sections: [] }
+}
+
+export function getFieldPath (sectionId, groupId, fieldId) {
+  return `${sectionId}/${groupId}/${fieldId}`
+}
+
+export function isFieldSensitive (field) {
+  return !!field?.sensitive || SENSITIVE_FIELD_TYPES.has(field?.type)
+}
+
+export function isFieldVisibleAtScope (field, scope) {
+  const allowed = field?.showIn || ['default']
+  return allowed.includes(scope)
+}
+
+export function flattenFields (schema) {
+  const out = []
+  if (!schema || !Array.isArray(schema.sections)) return out
+  for (const section of schema.sections) {
+    if (!Array.isArray(section.groups)) continue
+    for (const group of section.groups) {
+      if (!Array.isArray(group.fields)) continue
+      for (const field of group.fields) {
+        out.push({
+          section,
+          group,
+          field,
+          path: getFieldPath(section.id, group.id, field.id),
+          sensitive: isFieldSensitive(field)
+        })
+      }
+    }
+  }
+  return out
+}
+
+export function coerceDefault (field) {
+  switch (field?.type) {
+    case 'boolean':
+      return !!field.default
+    case 'number':
+      return typeof field.default === 'number' ? field.default : Number(field.default) || 0
+    default:
+      return field?.default ?? ''
+  }
+}

package/web/src/settings.js

@@ -0,0 +1,57 @@
+/*
+Copyright 2025 Adobe. All rights reserved.
+This file is licensed to you under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License. You may obtain a copy
+of the License at http://www.apache.org/licenses/LICENSE-2.0
+*/
+
+/** Default OpenWhisk action keys (must match keys in deploy-time config.json). */
+export const DEFAULT_ACTION_KEYS = {
+  commerceRestGet: 'ConfigurationManagement/commerce-rest-get',
+  systemConfigList: 'ConfigurationManagement/system-config-list',
+  systemConfigSave: 'ConfigurationManagement/system-config-save',
+  systemConfigSchema: 'ConfigurationManagement/system-config-schema',
+  exportConfig: 'ConfigurationManagement/export-config',
+  importConfig: 'ConfigurationManagement/import-config',
+  syncStoreMappings: 'ConfigurationManagement/sync-store-mappings-from-commerce'
+}
+
+let extensionId = 'ConfigurationManagement'
+let actionUrls = {}
+let actionKeys = { ...DEFAULT_ACTION_KEYS }
+
+export function getExtensionId () {
+  return extensionId
+}
+
+export function getActionKey (name) {
+  return actionKeys[name] || name
+}
+
+export function getActionUrl (actionKey) {
+  return actionUrls[actionKey]
+}
+
+/**
+ * Configure the web UI before rendering.
+ *
+ * @param {object} [options]
+ * @param {string} [options.extensionId] - UIX guest extension id
+ * @param {Record<string, string>} [options.actionUrls] - map of action key → deployed URL (from config.json)
+ * @param {Partial<typeof DEFAULT_ACTION_KEYS>} [options.actionKeys] - override default action key names
+ */
+export function configureWeb ({
+  extensionId: nextExtensionId,
+  actionUrls: nextActionUrls,
+  actionKeys: nextActionKeys
+} = {}) {
+  if (nextExtensionId != null) {
+    extensionId = String(nextExtensionId)
+  }
+  if (nextActionUrls) {
+    actionUrls = { ...nextActionUrls }
+  }
+  if (nextActionKeys) {
+    actionKeys = { ...actionKeys, ...nextActionKeys }
+  }
+}

package/web/src/styles/index.css

@@ -0,0 +1,326 @@
+/*
+Copyright 2025 Adobe. All rights reserved.
+This file is licensed to you under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License. You may obtain a copy
+of the License at http://www.apache.org/licenses/LICENSE-2.0
+*/
+
+/* =========================================================================
+   sync-management — single source of truth for the UI theme.
+
+   To re-skin the app, change values under :root. Components consume these
+   tokens either directly via CSS classes (.sm-*) or via the JS facade in
+   `web-src/src/theme.js` which re-exports them as `var(--sm-*)` strings.
+
+   Token naming:
+     --sm-color-*      colors
+     --sm-radius-*     border radii
+     --sm-space-*      spacing scale
+     --sm-shadow-*     elevation
+     --sm-font-*       typography
+     --sm-control-*    interactive control sizing
+   ========================================================================= */
+
+:root {
+  /* ---- Colors --------------------------------------------------------- */
+  --sm-color-bg:             #f7f8fa;
+  --sm-color-surface:        #ffffff;
+  --sm-color-surface-muted:  #f3f4f6;
+  --sm-color-surface-subtle: #fafbfc;
+  --sm-color-border:         #e5e7eb;
+  --sm-color-border-strong:  #d1d5db;
+  --sm-color-text:           #111827;
+  --sm-color-text-muted:     #6b7280;
+  --sm-color-text-inverse:   #ffffff;
+
+  --sm-color-accent:         #1473e6;
+  --sm-color-accent-hover:   #0f5fc4;
+  --sm-color-accent-soft:    #e8f1fc;
+
+  --sm-color-success:        #22863a;
+  --sm-color-success-hover:  #1a6e2f;
+  --sm-color-success-soft:   #ecfdf5;
+  --sm-color-warning:        #b58105;
+  --sm-color-warning-hover:  #946c04;
+  --sm-color-warning-soft:   #fff7ed;
+  --sm-color-warning-border: #fde68a;
+  --sm-color-warning-text:   #92400e;
+  --sm-color-warning-tint:   #fef3c7;
+  --sm-color-danger:         #c0392b;
+  --sm-color-danger-hover:   #a32d20;
+  --sm-color-danger-soft:    #fef2f2;
+  --sm-color-danger-tint:    #fee2e2;
+  --sm-color-accent-tint:    #dbeafe;
+
+  --sm-color-neutral-soft:   #eef2f7;
+  --sm-color-neutral-text:   #374151;
+
+  /* Surfaces used by the modal scaffolding (header text, body text, panel). */
+  --sm-color-text-strong:    #1f2937;
+  --sm-color-text-soft:      #475569;
+  --sm-color-surface-panel:  #f9fafb;
+
+  /* Modal / overlay scrim */
+  --sm-color-overlay:        rgba(15, 23, 42, 0.45);
+
+  /* ---- Radii ---------------------------------------------------------- */
+  --sm-radius-sm:    4px;
+  --sm-radius-md:    8px;
+  --sm-radius-lg:    10px;
+  --sm-radius-xl:    12px;
+  --sm-radius-2xl:   14px;
+  --sm-radius-pill:  999px;
+
+  /* ---- Spacing -------------------------------------------------------- */
+  --sm-space-1:  4px;
+  --sm-space-2:  8px;
+  --sm-space-3:  12px;
+  --sm-space-4:  16px;
+  --sm-space-5:  20px;
+  --sm-space-6:  24px;
+
+  /* ---- Shadows -------------------------------------------------------- */
+  --sm-shadow-xs:       0 1px 2px rgba(15, 23, 42, 0.03);
+  --sm-shadow-sm:       0 1px 4px rgba(15, 23, 42, 0.04);
+  --sm-shadow-md:       0 1px 3px rgba(15, 23, 42, 0.12), 0 1px 1px rgba(15, 23, 42, 0.06);
+  --sm-shadow-pill:     0 1px 3px rgba(15, 23, 42, 0.10), 0 1px 1px rgba(15, 23, 42, 0.06);
+  --sm-shadow-floating: 0 4px 14px rgba(15, 23, 42, 0.08);
+  --sm-shadow-dropdown: 0 12px 28px rgba(15, 23, 42, 0.16), 0 2px 4px rgba(15, 23, 42, 0.06);
+  --sm-shadow-modal:    0 24px 60px rgba(15, 23, 42, 0.25), 0 2px 8px rgba(15, 23, 42, 0.08);
+  --sm-shadow-inset:    inset 0 1px 2px rgba(15, 23, 42, 0.04);
+
+  /* ---- Typography ----------------------------------------------------- */
+  --sm-font-family: adobe-clean, 'Source Sans Pro', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+  --sm-font-mono:   ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+  --sm-font-size-xs:    11px;
+  --sm-font-size-sm:    12px;
+  --sm-font-size-md:    13px;
+  --sm-font-size-lg:    14px;
+  --sm-font-weight-regular: 400;
+  --sm-font-weight-medium:  500;
+  --sm-font-weight-semibold:600;
+  --sm-font-weight-bold:    700;
+
+  /* ---- Control sizing ------------------------------------------------- */
+  --sm-control-height-sm: 28px;
+  --sm-control-height-md: 32px;
+  --sm-control-height-lg: 40px;
+  --sm-control-padding-x: 16px;
+
+  /* ---- Z-index -------------------------------------------------------- */
+  --sm-z-nav: 30;
+  --sm-z-sticky: 20;
+  --sm-z-modal: 100;
+
+  /* =====================================================================
+     Spectrum token overrides — re-skin React-Spectrum widgets without
+     forking the theme. Keep these in sync with the --sm-* tokens above
+     so default Buttons / TextField / Picker pick up our accent automatically.
+     ===================================================================== */
+  --spectrum-accent-color-900: var(--sm-color-accent);
+  --spectrum-accent-color-1000: var(--sm-color-accent-hover);
+  /* Text colours are left to Spectrum so secondary/quiet buttons keep
+     their proper contrast on both light and dark surfaces. */
+
+  color-scheme: light;
+}
+
+/* =========================================================================
+   Base
+   ========================================================================= */
+html,
+body,
+#root {
+  margin: 0;
+  min-height: 100%;
+  background: var(--sm-color-bg);
+  color: var(--sm-color-text);
+  font-family: var(--sm-font-family);
+}
+
+/* React-Spectrum's <Provider> wraps its tree in a div. We mark it with
+   `UNSAFE_className="sm-provider"` and set its background here so the page
+   bg fills the whole iframe — but we only paint the wrapper, NOT any
+   descendants. Painting descendants stomps on inputs / buttons / pickers. */
+.sm-provider {
+  background: var(--sm-color-bg);
+  min-height: 100vh;
+}
+
+/* =========================================================================
+   Cards
+   ========================================================================= */
+.sm-card {
+  background: var(--sm-color-surface);
+  border: 1px solid var(--sm-color-border);
+  border-radius: var(--sm-radius-lg);
+  box-shadow: var(--sm-shadow-xs);
+  padding: var(--sm-space-5);
+}
+.sm-card--flush { padding: 0; }
+
+/* =========================================================================
+   Pills
+   ========================================================================= */
+.sm-pill {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--sm-space-1);
+  padding: 2px var(--sm-space-2);
+  border-radius: var(--sm-radius-pill);
+  background: var(--sm-color-neutral-soft);
+  color: var(--sm-color-neutral-text);
+  font-size: var(--sm-font-size-xs);
+  font-weight: var(--sm-font-weight-semibold);
+  line-height: 16px;
+  letter-spacing: 0.2px;
+  white-space: nowrap;
+}
+.sm-pill--accent  { background: var(--sm-color-accent-soft);   color: var(--sm-color-accent); }
+.sm-pill--success { background: var(--sm-color-success-soft);  color: var(--sm-color-success); }
+.sm-pill--warning { background: var(--sm-color-warning-soft);  color: var(--sm-color-warning); }
+.sm-pill--danger  { background: var(--sm-color-danger-soft);   color: var(--sm-color-danger); }
+
+/* =========================================================================
+   Tab bar (used by AppSectionNav)
+   ========================================================================= */
+.sm-tab-bar {
+  position: sticky;
+  top: 0;
+  z-index: var(--sm-z-nav);
+  background: var(--sm-color-surface);
+  border-bottom: 1px solid var(--sm-color-border);
+  padding: 10px var(--sm-space-4);
+  box-shadow: var(--sm-shadow-sm);
+  box-sizing: border-box;
+  max-width: 100%;
+}
+.sm-tab-bar__track {
+  display: inline-flex;
+  padding: var(--sm-space-1);
+  background: var(--sm-color-surface-muted);
+  border: 1px solid var(--sm-color-border);
+  border-radius: var(--sm-radius-pill);
+  box-shadow: var(--sm-shadow-inset);
+  gap: 2px;
+  font-family: var(--sm-font-family);
+}
+.sm-tab {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--sm-space-2);
+  padding: var(--sm-space-2) var(--sm-control-padding-x);
+  border: 0;
+  border-radius: var(--sm-radius-pill);
+  background: transparent;
+  color: var(--sm-color-neutral-text);
+  font-size: var(--sm-font-size-md);
+  font-weight: var(--sm-font-weight-semibold);
+  letter-spacing: 0.1px;
+  cursor: pointer;
+  transition: background 140ms ease, color 140ms ease, box-shadow 140ms ease;
+}
+.sm-tab:hover {
+  background: var(--sm-color-surface);
+  color: var(--sm-color-text);
+}
+.sm-tab.is-active {
+  background: var(--sm-color-surface);
+  color: var(--sm-color-accent);
+  font-weight: var(--sm-font-weight-bold);
+  box-shadow: var(--sm-shadow-pill);
+  cursor: default;
+}
+.sm-tab__icon { display: inline-flex; opacity: 0.75; }
+.sm-tab.is-active .sm-tab__icon { opacity: 1; }
+
+/* =========================================================================
+   Spectrum textareas inside the system-config field renderer
+   ========================================================================= */
+.sm-textarea textarea {
+  height: 160px !important;
+  max-height: 160px !important;
+  min-height: 160px !important;
+  overflow-y: auto !important;
+  resize: none !important;
+  font-family: var(--sm-font-mono);
+  font-size: var(--sm-font-size-sm);
+}
+
+/* =========================================================================
+   Note banner (used by ComingSoon, info callouts, etc.)
+   ========================================================================= */
+.sm-note {
+  margin-top: var(--sm-space-3);
+  padding: var(--sm-space-3);
+  border-radius: var(--sm-radius-md);
+  background: var(--sm-color-surface-muted);
+  border: 1px solid var(--sm-color-border);
+  color: var(--sm-color-text);
+  font-size: var(--sm-font-size-md);
+  white-space: pre-line;
+  font-family: var(--sm-font-mono);
+}
+.sm-note--warning {
+  background: var(--sm-color-warning-soft);
+  border-color: var(--sm-color-warning-border);
+  color: var(--sm-color-warning-text);
+  font-family: var(--sm-font-family);
+}
+
+/* =========================================================================
+   Animations (used by progress / status indicators)
+   ========================================================================= */
+@keyframes sm-pulse {
+  0%, 100% { opacity: 1; }
+  50%      { opacity: 0.3; }
+}
+@keyframes sm-indeterminate {
+  0%   { left: -40%; width: 40%; }
+  50%  { left: 30%;  width: 40%; }
+  100% { left: 100%; width: 40%; }
+}
+@keyframes sm-fade-in {
+  from { opacity: 0; }
+  to   { opacity: 1; }
+}
+@keyframes sm-pop-in {
+  from { opacity: 0; transform: translateY(8px) scale(0.98); }
+  to   { opacity: 1; transform: translateY(0)   scale(1); }
+}
+
+/* =========================================================================
+   Legacy SideNav classes (kept for backwards compat with any remaining
+   menu markup; safe to delete once nothing references them).
+   ========================================================================= */
+.SideNav {
+  list-style-type: none;
+  margin: 0;
+  padding: 0;
+  outline: none;
+  height: 100%;
+}
+.SideNav-item {
+  list-style-type: none;
+  margin: var(--spectrum-global-dimension-size-50) 0;
+}
+.SideNav-itemLink {
+  position: relative;
+  display: inline-flex;
+  align-items: center;
+  box-sizing: border-box;
+  width: 100%;
+  padding: var(--sm-space-2) var(--sm-space-3);
+  border-radius: var(--sm-radius-sm);
+  font-size: var(--sm-font-size-lg);
+  font-weight: var(--sm-font-weight-regular);
+  text-decoration: none;
+  word-break: break-word;
+  cursor: pointer;
+  background: transparent;
+  color: var(--sm-color-text);
+}
+.SideNav-itemLink.is-selected {
+  color: var(--sm-color-accent);
+  background: var(--sm-color-accent-soft);
+}

package/web/src/theme.js

@@ -0,0 +1,104 @@
+/*
+Copyright 2025 Adobe. All rights reserved.
+This file is licensed to you under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License. You may obtain a copy
+of the License at http://www.apache.org/licenses/LICENSE-2.0
+*/
+
+/**
+ * JS facade for the design tokens defined in `index.css`.
+ *
+ * Every value here is a CSS `var()` reference. Use these in inline styles
+ * (`style={{ color: THEME.color.accent }}`) so the rendered value resolves
+ * through CSS at runtime — changing the variable in `web/src/styles/index.css` re-skins
+ * everything that uses this object without touching any JS.
+ *
+ * Naming mirrors the CSS variable structure: --sm-color-accent → color.accent.
+ */
+export const THEME = {
+  color: {
+    bg:            'var(--sm-color-bg)',
+    surface:       'var(--sm-color-surface)',
+    surfaceMuted:  'var(--sm-color-surface-muted)',
+    surfaceSubtle: 'var(--sm-color-surface-subtle)',
+    border:        'var(--sm-color-border)',
+    borderStrong:  'var(--sm-color-border-strong)',
+    text:          'var(--sm-color-text)',
+    textMuted:     'var(--sm-color-text-muted)',
+    textStrong:    'var(--sm-color-text-strong)',
+    textSoft:      'var(--sm-color-text-soft)',
+    textInverse:   'var(--sm-color-text-inverse)',
+    surfacePanel:  'var(--sm-color-surface-panel)',
+    accent:        'var(--sm-color-accent)',
+    accentHover:   'var(--sm-color-accent-hover)',
+    accentSoft:    'var(--sm-color-accent-soft)',
+    accentTint:    'var(--sm-color-accent-tint)',
+    success:       'var(--sm-color-success)',
+    successHover:  'var(--sm-color-success-hover)',
+    successSoft:   'var(--sm-color-success-soft)',
+    warning:       'var(--sm-color-warning)',
+    warningHover:  'var(--sm-color-warning-hover)',
+    warningSoft:   'var(--sm-color-warning-soft)',
+    warningBorder: 'var(--sm-color-warning-border)',
+    warningText:   'var(--sm-color-warning-text)',
+    warningTint:   'var(--sm-color-warning-tint)',
+    danger:        'var(--sm-color-danger)',
+    dangerHover:   'var(--sm-color-danger-hover)',
+    dangerSoft:    'var(--sm-color-danger-soft)',
+    dangerTint:    'var(--sm-color-danger-tint)',
+    neutralSoft:   'var(--sm-color-neutral-soft)',
+    neutralText:   'var(--sm-color-neutral-text)',
+    overlay:       'var(--sm-color-overlay)'
+  },
+  radius: {
+    sm:   'var(--sm-radius-sm)',
+    md:   'var(--sm-radius-md)',
+    lg:   'var(--sm-radius-lg)',
+    xl:   'var(--sm-radius-xl)',
+    xxl:  'var(--sm-radius-2xl)',
+    pill: 'var(--sm-radius-pill)'
+  },
+  space: {
+    1: 'var(--sm-space-1)',
+    2: 'var(--sm-space-2)',
+    3: 'var(--sm-space-3)',
+    4: 'var(--sm-space-4)',
+    5: 'var(--sm-space-5)',
+    6: 'var(--sm-space-6)'
+  },
+  shadow: {
+    xs:       'var(--sm-shadow-xs)',
+    sm:       'var(--sm-shadow-sm)',
+    md:       'var(--sm-shadow-md)',
+    pill:     'var(--sm-shadow-pill)',
+    floating: 'var(--sm-shadow-floating)',
+    dropdown: 'var(--sm-shadow-dropdown)',
+    modal:    'var(--sm-shadow-modal)',
+    inset:    'var(--sm-shadow-inset)'
+  },
+  font: {
+    family:        'var(--sm-font-family)',
+    mono:          'var(--sm-font-mono)',
+    sizeXs:        'var(--sm-font-size-xs)',
+    sizeSm:        'var(--sm-font-size-sm)',
+    sizeMd:        'var(--sm-font-size-md)',
+    sizeLg:        'var(--sm-font-size-lg)',
+    weightRegular: 'var(--sm-font-weight-regular)',
+    weightMedium:  'var(--sm-font-weight-medium)',
+    weightSemi:    'var(--sm-font-weight-semibold)',
+    weightBold:    'var(--sm-font-weight-bold)'
+  }
+}
+
+/**
+ * Flat alias of `THEME.color` — every colour token reachable as `PALETTE.x`.
+ *
+ * Components should use this for inline styles so there is exactly one
+ * facade for the design system: change a CSS variable in `web/src/styles/index.css` →
+ * every reference here resolves to the new value at runtime.
+ */
+export const PALETTE = { ...THEME.color }
+export const RADIUS  = { ...THEME.radius }
+export const SHADOW  = { ...THEME.shadow }
+export const SPACE   = { ...THEME.space }
+export const FONT    = { ...THEME.font }

package/web/src/utils/storeMappingsFromCommerceRest.js

@@ -0,0 +1,73 @@
+/*
+Copyright 2025 Adobe. All rights reserved.
+This file is licensed to you under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License. You may obtain a copy
+of the License at http://www.apache.org/licenses/LICENSE-2.0
+*/
+
+/** @param {string} locale e.g. en_US → en */
+function localeToLanguageCode (locale) {
+  if (locale == null || locale === '') return null
+  const s = String(locale).trim()
+  const head = s.split(/[-_]/u)[0]
+  if (head && /^[a-zA-Z]{2,8}$/.test(head)) return head.toLowerCase()
+  return null
+}
+
+/** e.g. en_ch → en, de_ch → de */
+function inferLanguageFromStoreCode (code) {
+  if (typeof code !== 'string') return null
+  const m = /^([a-z]{2})[-_]/i.exec(code)
+  return m ? m[1].toLowerCase() : null
+}
+
+/**
+ * Build `general/settings/store_mappings` shape from Commerce REST payloads
+ * (same shape as server middleware expects: keyed by store view id string).
+ *
+ * @param {object[]|null|undefined} websitesRaw from `store/websites`
+ * @param {object[]|null|undefined} storeViewsRaw from `store/storeViews`
+ * @param {object[]|null|undefined} storeConfigsRaw from `store/storeConfigs` (optional)
+ * @returns {Record<string, { code: string, language_code: string, website_code: string, website_id: string }>}
+ */
+export function buildStoreMappingsFromCommercePayload (websitesRaw, storeViewsRaw, storeConfigsRaw) {
+  const websiteIdToCode = new Map()
+  if (Array.isArray(websitesRaw)) {
+    for (const w of websitesRaw) {
+      if (w && w.id != null && w.code != null) {
+        websiteIdToCode.set(String(w.id), String(w.code))
+      }
+    }
+  }
+
+  const storeCodeToLocale = new Map()
+  if (Array.isArray(storeConfigsRaw)) {
+    for (const cfg of storeConfigsRaw) {
+      if (cfg && cfg.code != null && cfg.locale != null) {
+        storeCodeToLocale.set(String(cfg.code), String(cfg.locale))
+      }
+    }
+  }
+
+  const mappings = {}
+  if (!Array.isArray(storeViewsRaw)) return mappings
+
+  for (const s of storeViewsRaw) {
+    if (!s || s.id == null || s.code == null) continue
+    const id = String(s.id)
+    const code = String(s.code)
+    const websiteId = s.website_id != null ? String(s.website_id) : ''
+    const websiteCode = websiteIdToCode.get(websiteId) || ''
+    const languageCode =
+      localeToLanguageCode(storeCodeToLocale.get(code)) ||
+      inferLanguageFromStoreCode(code) ||
+      'en'
+    mappings[id] = {
+      code,
+      language_code: languageCode,
+      website_code: websiteCode,
+      website_id: websiteId
+    }
+  }
+  return mappings
+}