@adobedjangir/commerce-admin-management 0.0.2

package/actions/commerce-creds.js

@@ -0,0 +1,262 @@
+/*
+Copyright 2025 Adobe. All rights reserved.
+Licensed under the Apache License, Version 2.0 (the "License");
+*/
+
+// Centralized read/write/test for Adobe Commerce connection credentials.
+//
+// Storage: a single document in ABDB `system_config_data` at
+//   scope=default, scope_id=0, path=_system/commerce/connection
+// whose `value` is an encrypted JSON blob:
+//   { baseUrl, consumerKey, consumerSecret, accessToken, accessTokenSecret }
+//
+// Everything except `baseUrl` is sensitive; the whole blob is encrypted with
+// SYSTEM_CONFIG_CRYPT_KEY via system-config-crypto. We encrypt the JSON string
+// as a unit (one ciphertext) rather than per-field, since the blob is read
+// atomically and stored at a single key.
+
+const { getClient } = require('@adobedjangir/commerce-admin-management/abdb')
+const { toStateKey } = require('@adobedjangir/commerce-admin-management/shared')
+const { encrypt, decrypt, isEncrypted } = require('@adobedjangir/commerce-admin-management/crypto')
+const { getCommerceOauthClient } = require('@adobedjangir/commerce-admin-management/oauth1a')
+
+const COLLECTION = 'system_config_data'
+const SCOPE = 'default'
+const SCOPE_ID = '0'
+const PATH = '_system/commerce/connection'
+const DOC_ID = toStateKey(SCOPE, SCOPE_ID, PATH)
+
+// Per-cold-start cache so each action call doesn't pay ABDB+decrypt cost.
+let credsCache = null
+let credsCacheAt = 0
+const CACHE_TTL_MS = 5 * 60 * 1000
+
+function clearCommerceCredsCache () {
+  credsCache = null
+  credsCacheAt = 0
+}
+
+function normalizeBaseUrl (url) {
+  if (!url || typeof url !== 'string') return ''
+  const trimmed = url.trim()
+  if (!trimmed) return ''
+  return trimmed.endsWith('/') ? trimmed : trimmed + '/'
+}
+
+function toClientShape (creds) {
+  if (!creds) return null
+  return {
+    url: normalizeBaseUrl(creds.baseUrl),
+    consumerKey: creds.consumerKey,
+    consumerSecret: creds.consumerSecret,
+    accessToken: creds.accessToken,
+    accessTokenSecret: creds.accessTokenSecret
+  }
+}
+
+function maskCreds (creds) {
+  if (!creds) return null
+  const mask = (v) => (v ? '****' + String(v).slice(-4) : '')
+  return {
+    baseUrl: creds.baseUrl || '',
+    consumerKey: mask(creds.consumerKey),
+    consumerSecret: mask(creds.consumerSecret),
+    accessToken: mask(creds.accessToken),
+    accessTokenSecret: mask(creds.accessTokenSecret)
+  }
+}
+
+async function ensureCollection (client) {
+  try {
+    await client.createCollection(COLLECTION)
+  } catch (err) {
+    const msg = (err && err.message) ? String(err.message) : String(err)
+    if (!/exist|already|duplicate/i.test(msg)) throw err
+  }
+}
+
+async function tryFindOne (collection, query) {
+  try {
+    const arr = await collection.find(query).limit(1).toArray()
+    return arr && arr.length ? arr[0] : null
+  } catch (err) {
+    const msg = err && err.message ? String(err.message) : String(err)
+    if (/not found/i.test(msg)) return null
+    throw err
+  }
+}
+
+/**
+ * Load the saved commerce creds from ABDB. Returns null if not configured.
+ * Returned shape: { baseUrl, consumerKey, consumerSecret, accessToken, accessTokenSecret }
+ */
+async function readCommerceCreds (params, { fresh = false } = {}) {
+  const now = Date.now()
+  if (!fresh && credsCache && (now - credsCacheAt) < CACHE_TTL_MS) {
+    return credsCache
+  }
+
+  let handle
+  try {
+    handle = await getClient(params)
+  } catch (e) {
+    return null
+  }
+  try {
+    await ensureCollection(handle.client)
+    const collection = await handle.client.collection(COLLECTION)
+    const doc = await tryFindOne(collection, { _id: DOC_ID })
+    if (!doc || doc.value === undefined || doc.value === null || doc.value === '') {
+      credsCache = null
+      credsCacheAt = now
+      return null
+    }
+    let raw = doc.value
+    if (isEncrypted(raw)) {
+      raw = decrypt(raw, params)
+    }
+    let parsed
+    try {
+      parsed = typeof raw === 'string' ? JSON.parse(raw) : raw
+    } catch (_) {
+      return null
+    }
+    if (!parsed || !parsed.baseUrl) return null
+    credsCache = parsed
+    credsCacheAt = now
+    return parsed
+  } finally {
+    try { await handle.close() } catch (_) {}
+  }
+}
+
+/**
+ * Persist commerce creds (encrypted JSON blob). Caller is responsible for
+ * having validated the connection first.
+ */
+async function writeCommerceCreds (params, creds) {
+  if (!creds || !creds.baseUrl) {
+    throw new Error('baseUrl required')
+  }
+  const payload = JSON.stringify({
+    baseUrl: normalizeBaseUrl(creds.baseUrl),
+    consumerKey: String(creds.consumerKey || ''),
+    consumerSecret: String(creds.consumerSecret || ''),
+    accessToken: String(creds.accessToken || ''),
+    accessTokenSecret: String(creds.accessTokenSecret || '')
+  })
+  const encrypted = encrypt(payload, params)
+
+  const { client, close } = await getClient(params)
+  try {
+    await ensureCollection(client)
+    const collection = await client.collection(COLLECTION)
+    const now = new Date().toISOString()
+    try {
+      await collection.updateOne(
+        { _id: DOC_ID },
+        {
+          $set: { value: encrypted, updatedAt: now, scope: SCOPE, scope_id: SCOPE_ID, path: PATH },
+          $setOnInsert: { _id: DOC_ID, createdAt: now }
+        },
+        { upsert: true }
+      )
+    } catch (err) {
+      const msg = (err && err.message) ? String(err.message) : String(err)
+      if (!/upsert|unsupported|not implemented/i.test(msg)) throw err
+      const existing = await tryFindOne(collection, { _id: DOC_ID })
+      if (existing) {
+        await collection.updateOne({ _id: DOC_ID }, { $set: { value: encrypted, updatedAt: now } })
+      } else {
+        await collection.insertOne({
+          _id: DOC_ID, scope: SCOPE, scope_id: SCOPE_ID, path: PATH, value: encrypted, createdAt: now, updatedAt: now
+        })
+      }
+    }
+    clearCommerceCredsCache()
+  } finally {
+    try { await close() } catch (_) {}
+  }
+}
+
+/**
+ * Hit a lightweight authenticated Commerce REST endpoint to verify creds.
+ * Returns { ok, storeCount, message } and never throws on auth/network — it
+ * normalises the failure into the result envelope.
+ */
+async function testCommerceConnection (creds, logger) {
+  const errLogger = logger && typeof logger.error === 'function' ? logger : { error: () => {} }
+  const shape = toClientShape(creds)
+  if (!shape || !shape.url) {
+    return { ok: false, message: 'baseUrl is required' }
+  }
+  if (!shape.consumerKey || !shape.consumerSecret || !shape.accessToken || !shape.accessTokenSecret) {
+    return { ok: false, message: 'All OAuth fields are required' }
+  }
+  try {
+    const oauth = getCommerceOauthClient({ ...shape }, errLogger)
+    const stores = await oauth.get('store/storeConfigs')
+    const count = Array.isArray(stores) ? stores.length : 0
+    return { ok: true, storeCount: count, message: `Connected — ${count} store config(s) returned` }
+  } catch (err) {
+    const status = err && err.response && err.response.statusCode
+    const msg = (err && err.message) ? String(err.message) : 'Connection failed'
+    return { ok: false, message: status ? `HTTP ${status}: ${msg}` : msg }
+  }
+}
+
+/**
+ * Resolve commerce creds for any action that needs them.
+ * Precedence:
+ *   1. explicit creds supplied on params (legacy / local dev fallback)
+ *   2. ABDB-stored creds
+ *   3. process.env (purely a dev escape hatch)
+ *
+ * Throws when nothing is configured so the caller emits a clear 412.
+ */
+async function getCommerceCreds (params, logger) {
+  const fromParams = {
+    baseUrl: params.COMMERCE_BASE_URL,
+    consumerKey: params.COMMERCE_CONSUMER_KEY,
+    consumerSecret: params.COMMERCE_CONSUMER_SECRET,
+    accessToken: params.COMMERCE_ACCESS_TOKEN,
+    accessTokenSecret: params.COMMERCE_ACCESS_TOKEN_SECRET
+  }
+  if (fromParams.baseUrl && fromParams.consumerKey) {
+    return fromParams
+  }
+  const fromDb = await readCommerceCreds(params)
+  if (fromDb && fromDb.baseUrl) return fromDb
+  const fromEnv = {
+    baseUrl: process.env.COMMERCE_BASE_URL,
+    consumerKey: process.env.COMMERCE_CONSUMER_KEY,
+    consumerSecret: process.env.COMMERCE_CONSUMER_SECRET,
+    accessToken: process.env.COMMERCE_ACCESS_TOKEN,
+    accessTokenSecret: process.env.COMMERCE_ACCESS_TOKEN_SECRET
+  }
+  if (fromEnv.baseUrl && fromEnv.consumerKey) return fromEnv
+  const err = new Error('Commerce connection not configured. Complete the Commerce setup wizard first.')
+  err.code = 'COMMERCE_NOT_CONFIGURED'
+  throw err
+}
+
+/**
+ * Convenience: returns a ready-to-use OAuth1a client built from stored creds.
+ */
+async function getStoredCommerceOauthClient (params, logger) {
+  const creds = await getCommerceCreds(params, logger)
+  return getCommerceOauthClient(toClientShape(creds), logger || { error: () => {} })
+}
+
+module.exports = {
+  COMMERCE_CONNECTION_PATH: PATH,
+  COMMERCE_CONNECTION_DOC_ID: DOC_ID,
+  readCommerceCreds,
+  writeCommerceCreds,
+  testCommerceConnection,
+  getCommerceCreds,
+  getStoredCommerceOauthClient,
+  toClientShape,
+  maskCreds,
+  clearCommerceCredsCache
+}

package/actions/configurations/commerce/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
+*/
+
+const { Core } = require('@adobe/aio-sdk')
+const { errorResponse, checkMissingRequestInputs } = require('../../utils')
+const { getStoredCommerceOauthClient } = require('../../commerce-creds')
+
+async function main (params) {
+  const logger = Core.Logger('main', { level: params.LOG_LEVEL || 'info' })
+
+  try {
+    const requiredParams = ['operation']
+    const requiredHeaders = ['Authorization']
+    const errorMessage = checkMissingRequestInputs(params, requiredParams, requiredHeaders)
+    if (errorMessage) {
+      return errorResponse(400, errorMessage, logger)
+    }
+
+    let oauth
+    try {
+      oauth = await getStoredCommerceOauthClient(params, logger)
+    } catch (e) {
+      if (e.code === 'COMMERCE_NOT_CONFIGURED') {
+        return errorResponse(412, e.message, logger)
+      }
+      throw e
+    }
+
+    const content = await oauth.get(params.operation)
+    return { statusCode: 200, body: content }
+  } catch (error) {
+    logger.error(error)
+    return errorResponse(500, error, logger)
+  }
+}
+
+exports.main = main

package/actions/configurations/commerce-connection-save/index.js

@@ -0,0 +1,53 @@
+/*
+Copyright 2025 Adobe. All rights reserved.
+Licensed under the Apache License, Version 2.0
+*/
+
+const { Core } = require('@adobe/aio-sdk')
+const { errorResponse, checkMissingRequestInputs } = require('../../utils')
+const {
+  testCommerceConnection,
+  writeCommerceCreds,
+  maskCreds
+} = require('../../commerce-creds')
+
+async function main (params) {
+  const logger = Core.Logger('commerce-connection-save', { level: params.LOG_LEVEL || 'info' })
+  try {
+    const missing = checkMissingRequestInputs(params, [
+      'baseUrl', 'consumerKey', 'consumerSecret', 'accessToken', 'accessTokenSecret'
+    ])
+    if (missing) return errorResponse(400, missing, logger)
+
+    const creds = {
+      baseUrl: params.baseUrl,
+      consumerKey: params.consumerKey,
+      consumerSecret: params.consumerSecret,
+      accessToken: params.accessToken,
+      accessTokenSecret: params.accessTokenSecret
+    }
+
+    // Validate before persisting unless the caller explicitly opted out.
+    const skipTest = params.skipTest === true || params.skipTest === 'true'
+    if (!skipTest) {
+      const test = await testCommerceConnection(creds, logger)
+      if (!test.ok) {
+        return {
+          statusCode: 200,
+          body: { ok: false, saved: false, message: test.message }
+        }
+      }
+    }
+
+    await writeCommerceCreds(params, creds)
+    return {
+      statusCode: 200,
+      body: { ok: true, saved: true, creds: maskCreds(creds) }
+    }
+  } catch (error) {
+    logger.error(error)
+    return errorResponse(500, error.message || 'save failed', logger)
+  }
+}
+
+exports.main = main

package/actions/configurations/commerce-connection-status/index.js

@@ -0,0 +1,27 @@
+/*
+Copyright 2025 Adobe. All rights reserved.
+Licensed under the Apache License, Version 2.0
+*/
+
+const { Core } = require('@adobe/aio-sdk')
+const { errorResponse } = require('../../utils')
+const { readCommerceCreds, maskCreds } = require('../../commerce-creds')
+
+async function main (params) {
+  const logger = Core.Logger('commerce-connection-status', { level: params.LOG_LEVEL || 'info' })
+  try {
+    const creds = await readCommerceCreds(params, { fresh: params.fresh === true || params.fresh === 'true' })
+    return {
+      statusCode: 200,
+      body: {
+        configured: !!(creds && creds.baseUrl),
+        creds: creds ? maskCreds(creds) : null
+      }
+    }
+  } catch (error) {
+    logger.error(error)
+    return errorResponse(500, error.message || 'status failed', logger)
+  }
+}
+
+exports.main = main

package/actions/configurations/commerce-connection-test/index.js

@@ -0,0 +1,47 @@
+/*
+Copyright 2025 Adobe. All rights reserved.
+Licensed under the Apache License, Version 2.0
+*/
+
+const { Core } = require('@adobe/aio-sdk')
+const { errorResponse, checkMissingRequestInputs } = require('../../utils')
+const { testCommerceConnection, readCommerceCreds } = require('../../commerce-creds')
+
+async function main (params) {
+  const logger = Core.Logger('commerce-connection-test', { level: params.LOG_LEVEL || 'info' })
+  try {
+    // Allow testing either the form values being entered OR the currently saved creds.
+    let creds = {
+      baseUrl: params.baseUrl,
+      consumerKey: params.consumerKey,
+      consumerSecret: params.consumerSecret,
+      accessToken: params.accessToken,
+      accessTokenSecret: params.accessTokenSecret
+    }
+    const allBlank = !creds.baseUrl && !creds.consumerKey && !creds.consumerSecret &&
+      !creds.accessToken && !creds.accessTokenSecret
+    if (allBlank) {
+      const saved = await readCommerceCreds(params, { fresh: true })
+      if (!saved) {
+        return errorResponse(412, 'No creds supplied and none saved', logger)
+      }
+      creds = saved
+    } else {
+      const missing = checkMissingRequestInputs(params, [
+        'baseUrl', 'consumerKey', 'consumerSecret', 'accessToken', 'accessTokenSecret'
+      ])
+      if (missing) return errorResponse(400, missing, logger)
+    }
+
+    const result = await testCommerceConnection(creds, logger)
+    return {
+      statusCode: result.ok ? 200 : 200, // surface failures in body, not HTTP
+      body: result
+    }
+  } catch (error) {
+    logger.error(error)
+    return errorResponse(500, error.message || 'test failed', logger)
+  }
+}
+
+exports.main = main

package/actions/configurations/export-config/index.js

@@ -0,0 +1,256 @@
+/*
+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
+*/
+
+// Export the entire system_config (schema + values) to a portable JSON
+// document. The result includes:
+//   - schema  : the document stored under system_config_schema._id = 'v1'
+//   - values  : every row in system_config_data, as { scope, scope_id, path, value }
+//   - meta    : timestamp + counts so the operator can sanity-check the dump
+//
+// Sensitive fields are exported as their ENCRYPTED ciphertext so the dump is
+// safe to share, but it can only be re-imported into a workspace whose
+// SYSTEM_CONFIG_CRYPT_KEY matches the one used when these values were saved.
+//
+// Trigger from the UI's "Export → JSON" button, or invoke directly:
+//   POST .../system-config-export
+//   body: {}                         → full dump
+//   body: { schemaOnly: true }       → omit values
+//   body: { valuesOnly: true }       → omit schema
+//   body: { scopes: ['default','websites'] } → filter by scope tuple
+//
+// Response: { ok, dump }, where `dump` is the JSON the caller saves as a file.
+
+const { Core } = require('@adobe/aio-sdk')
+const { errorResponse } = require('../../utils')
+const { getClient } = require('@adobedjangir/commerce-admin-management/abdb')
+const { isEncrypted, decrypt } = require('@adobedjangir/commerce-admin-management/crypto')
+const { readCommerceCreds, toClientShape } = require('../../commerce-creds')
+const { getCommerceOauthClient } = require('@adobedjangir/commerce-admin-management/oauth1a')
+
+const SCHEMA_COLLECTION = 'system_config_schema'
+const SCHEMA_DOC_ID = 'v1'
+const DATA_COLLECTION = 'system_config_data'
+// Bumped to v2 when we started decrypting sensitive values into plaintext on
+// export. Importers ≥ v2 know to re-encrypt with the target env's key.
+const EXPORT_VERSION = 2
+
+/**
+ * Walk a schema doc and return the set of "section/group/field" paths whose
+ * field is marked `sensitive: true`. Used by both export (decide what to
+ * decrypt) and import (decide what to re-encrypt against the target's key).
+ */
+function deriveLanguageCode (code) {
+  const m = String(code || '').toLowerCase().match(/^([a-z]{2})_/)
+  return m ? m[1] : 'en'
+}
+
+/**
+ * Build a Commerce-style store_mappings blob from live REST data:
+ *   { storeId: { code, language_code, website_code, website_id } }
+ * Returns null if Commerce credentials aren't configured or the call fails.
+ * Embedding this in every export lets cross-env imports translate
+ * website_id / store_id by matching `website_code` / store `code` against the
+ * target env's own Commerce, regardless of whether sync-store-mappings was
+ * ever run on the source.
+ */
+async function fetchSourceStoreMappingsFromCommerce (params, logger) {
+  const creds = await readCommerceCreds(params).catch(() => null)
+  const shape = toClientShape(creds)
+  if (!shape || !shape.url || !shape.consumerKey) return null
+  try {
+    const oauth = getCommerceOauthClient(shape, logger)
+    const [storeViews, websites] = await Promise.all([
+      oauth.get('store/storeViews'),
+      oauth.get('store/websites')
+    ])
+    const websiteById = new Map()
+    for (const w of websites || []) {
+      if (w && w.id != null) websiteById.set(String(w.id), w)
+    }
+    const mapping = {}
+    for (const sv of storeViews || []) {
+      if (!sv || sv.id == null) continue
+      const storeId = String(sv.id)
+      if (storeId === '0' || sv.code === 'admin') continue
+      const websiteId = sv.website_id != null ? String(sv.website_id) : ''
+      const website = websiteById.get(websiteId)
+      mapping[storeId] = {
+        code: String(sv.code || ''),
+        language_code: deriveLanguageCode(sv.code),
+        website_code: website ? String(website.code || '') : '',
+        website_id: websiteId
+      }
+    }
+    return Object.keys(mapping).length ? mapping : null
+  } catch (err) {
+    if (logger) logger.warn(`Export: Commerce store_mappings lookup failed: ${err.message}`)
+    return null
+  }
+}
+
+function collectSensitivePaths (schema) {
+  const out = new Set()
+  if (!schema || !Array.isArray(schema.sections)) return out
+  for (const s of schema.sections) {
+    if (!s || !Array.isArray(s.groups)) continue
+    for (const g of s.groups) {
+      if (!g || !Array.isArray(g.fields)) continue
+      for (const f of g.fields) {
+        if (f && f.sensitive) out.add(`${s.id}/${g.id}/${f.id}`)
+      }
+    }
+  }
+  return out
+}
+
+async function tryFindOne (collection, query) {
+  try {
+    const arr = await collection.find(query).limit(1).toArray()
+    return arr && arr.length ? arr[0] : null
+  } catch (err) {
+    const msg = err && err.message ? String(err.message) : String(err)
+    if (/not found/i.test(msg)) return null
+    throw err
+  }
+}
+
+async function main (params) {
+  const logger = Core.Logger('export-config', { level: params.LOG_LEVEL || 'info' })
+
+  const schemaOnly = params.schemaOnly === true || params.schemaOnly === 'true'
+  const valuesOnly = params.valuesOnly === true || params.valuesOnly === 'true'
+  const scopeFilter = Array.isArray(params.scopes) && params.scopes.length
+    ? new Set(params.scopes.map(String))
+    : null
+
+  let dbHandle
+  try {
+    dbHandle = await getClient(params)
+  } catch (e) {
+    logger.error(`ABDB connect failed: ${e.message}`)
+    return errorResponse(500, `ABDB connect failed: ${e.message}`, logger)
+  }
+  const { client, close } = dbHandle
+
+  try {
+    let schema = null
+    if (!valuesOnly) {
+      const schemaCol = await client.collection(SCHEMA_COLLECTION)
+      const doc = await tryFindOne(schemaCol, { _id: SCHEMA_DOC_ID })
+      schema = doc && doc.schema ? doc.schema : { sections: [] }
+    }
+
+    // We need the schema to know which paths are sensitive, even when the
+    // caller asked for valuesOnly — load it locally without including it in
+    // the dump.
+    let schemaForFlags = schema
+    if (!schemaForFlags) {
+      try {
+        const schemaCol = await client.collection(SCHEMA_COLLECTION)
+        const doc = await tryFindOne(schemaCol, { _id: SCHEMA_DOC_ID })
+        schemaForFlags = doc && doc.schema ? doc.schema : null
+      } catch (_) { /* ok if missing */ }
+    }
+    const sensitivePaths = collectSensitivePaths(schemaForFlags)
+
+    // Always pull the SOURCE env's Commerce mapping so we can stamp every
+    // website/store-scoped row with its scope_code (website_code / store
+    // view code). The importer then needs only the target's Commerce — no
+    // separate storeMappings blob has to be carried between envs.
+    const storeMappingsFromCommerce = await fetchSourceStoreMappingsFromCommerce(params, logger)
+    // Build quick lookup tables: websiteId → website_code, storeId → store code.
+    const websiteCodeById = new Map()
+    const storeCodeById = new Map()
+    if (storeMappingsFromCommerce) {
+      for (const [storeId, m] of Object.entries(storeMappingsFromCommerce)) {
+        if (!m) continue
+        if (m.website_id != null && m.website_code) {
+          websiteCodeById.set(String(m.website_id), String(m.website_code))
+        }
+        if (m.code) storeCodeById.set(String(storeId), String(m.code))
+      }
+    }
+
+    let values = []
+    let decryptedCount = 0
+    let decryptFailedCount = 0
+    if (!schemaOnly) {
+      const dataCol = await client.collection(DATA_COLLECTION)
+      const docs = await dataCol.find({}).toArray().catch(() => [])
+      for (const d of docs) {
+        if (!d || typeof d.path !== 'string') continue
+        if (scopeFilter && !scopeFilter.has(d.scope)) continue
+        let value = d.value
+        // Decrypt sensitive ciphertext using THIS env's key so the dump is
+        // portable to any other workspace. The recipient will re-encrypt
+        // with its own key based on schema.sensitive flags. This means the
+        // exported JSON file contains plaintext secrets — treat it as
+        // sensitive.
+        if (isEncrypted(value)) {
+          try {
+            value = decrypt(value, params)
+            decryptedCount++
+          } catch (e) {
+            // Couldn't decrypt — keep the ciphertext envelope so a target
+            // workspace with the matching key can still pick it up via the
+            // legacy sourceCryptKey path.
+            decryptFailedCount++
+            logger.warn(`Export: failed to decrypt ${d.path} @ ${d.scope}:${d.scope_id}: ${e.message}`)
+          }
+        }
+        // Tag the row with the source env's code (website_code or store
+        // view code). At import time the recipient looks up its own Commerce
+        // and resolves scope_code → target scope_id directly, with no need
+        // to ship a separate storeMappings blob.
+        let scopeCode
+        if (d.scope === 'websites') scopeCode = websiteCodeById.get(String(d.scope_id))
+        else if (d.scope === 'stores') scopeCode = storeCodeById.get(String(d.scope_id))
+        values.push({
+          scope: d.scope,
+          scope_id: d.scope_id,
+          ...(scopeCode ? { scope_code: scopeCode } : {}),
+          path: d.path,
+          value
+        })
+      }
+      // Stable ordering for diffable dumps.
+      values.sort((a, b) => {
+        if (a.scope !== b.scope) return a.scope.localeCompare(b.scope)
+        if (a.scope_id !== b.scope_id) return String(a.scope_id).localeCompare(String(b.scope_id))
+        return a.path.localeCompare(b.path)
+      })
+    }
+
+    const dump = {
+      __format: 'adobe-commerce-app-builder/system-config-export',
+      __version: EXPORT_VERSION,
+      exportedAt: new Date().toISOString(),
+      // List of sensitive paths so the importer can re-encrypt them with the
+      // target env's key without needing to re-derive from the schema.
+      sensitivePaths: Array.from(sensitivePaths),
+      sensitiveDecrypted: decryptedCount,
+      sensitiveDecryptFailed: decryptFailedCount,
+      counts: {
+        sections: schema ? (schema.sections || []).length : 0,
+        values: values.length,
+        scopeCoded: values.filter(v => v.scope_code).length
+      },
+      ...(valuesOnly ? {} : { schema }),
+      ...(schemaOnly ? {} : { values })
+    }
+
+    logger.info(`Exported: ${dump.counts.sections} section(s), ${dump.counts.values} value(s)`)
+    return { statusCode: 200, body: { ok: true, dump } }
+  } catch (error) {
+    logger.error(error)
+    return errorResponse(500, error.message || 'Export failed', logger)
+  } finally {
+    try { await close() } catch (_) {}
+  }
+}
+
+exports.main = main