configuration-management 0.1.2 → 0.1.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "configuration-management",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Schema-driven system configuration for Adobe Commerce App Builder sync apps. Magento-style scoped config in Adobe App Builder Database (ABDB) with encryption, Commerce REST helpers, and React Admin UI.",
   "license": "Apache-2.0",
   "author": "Adobe Inc.",
@@ -29,7 +29,9 @@
     "./shared": "./src/system-config-shared.js",
     "./oauth1a": "./src/oauth1a.js",
     "./web": "./web/index.js",
-    "./web/styles.css": "./web/styles.css",
+    "./web/index.js": "./web/index.js",
+    "./web/src/styles/index.css": "./web/src/styles/index.css",
+    "./web/styles.css": "./web/src/styles/index.css",
     "./actions/utils": "./actions/utils.js",
     "./actions/ext.config.yaml": "./actions/configurations/ext.config.yaml"
   },

package/README.md

@@ -1,199 +0,0 @@
-# configuration-management
-
-Schema-driven system configuration for **Adobe Commerce** and **Adobe App Builder** sync applications.
-
-Mirrors Magento's `core_config_data` model: scoped configuration (`default` / `websites` / `stores`) stored in **Adobe App Builder Database (ABDB)** with AES-256-GCM encryption for sensitive fields.
-
-## Install
-
-```bash
-npm install configuration-management
-```
-
-Your App Builder project must also have Adobe I/O runtime dependencies installed (peer dependencies):
-
-```bash
-npm install @adobe/aio-lib-core-auth @adobe/aio-lib-db @adobe/aio-lib-ims @adobe/aio-sdk dotenv
-```
-
-For the React Admin UI, also install Spectrum and React peers:
-
-```bash
-npm install react react-dom @adobe/react-spectrum @adobe/uix-guest @adobe/exc-app react-router-dom react-error-boundary @spectrum-icons/workflow
-```
-
-## Quick start
-
-Read a config value from ABDB inside an App Builder action:
-
-```js
-const { getConfig } = require('configuration-management')
-
-async function main (params) {
-  const apiUrl = await getConfig('sync_general/api/url', params, {
-    scope: 'websites',
-    scopeCode: 'base'
-  })
-  // ...
-}
-```
-
-## API
-
-### Config resolution
-
-| Export | Description |
-|--------|-------------|
-| `getConfig(path, params, options)` | Read a value with Magento-style scope inheritance |
-| `clearAbdbConfigCache()` | Clear the in-process lookup cache |
-
-### ABDB helpers (`configuration-management/abdb`)
-
-| Export | Description |
-|--------|-------------|
-| `getClient(params, options)` | Connect to ABDB using IMS credentials from action params |
-| `withDbClient(params, fn, options)` | Run work with auto-close |
-| `findOne`, `insertOne`, `updateOne`, … | Mongo-style collection helpers |
-
-### Scope / path model (`configuration-management/shared`)
-
-| Export | Description |
-|--------|-------------|
-| `toStateKey(scope, scopeId, path)` | Encode `section/group/field` as ABDB document `_id` |
-| `buildInheritanceChain(scope, scopeId, parentWebsiteId)` | Magento-style fallback chain |
-| `isValidPath`, `normalizeScope`, `normalizeScopeId` | Validation helpers |
-
-### Encryption (`configuration-management/crypto`)
-
-| Export | Description |
-|--------|-------------|
-| `encrypt(plaintext, params)` | AES-256-GCM encrypt for at-rest storage |
-| `decrypt(ciphertext, params)` | Decrypt stored values |
-| `isEncrypted(value)` | Detect `enc:v1:` wire format |
-
-### Commerce REST (`configuration-management/oauth1a`)
-
-| Export | Description |
-|--------|-------------|
-| `getCommerceOauthClient(options, logger)` | OAuth 1.0a client for Adobe Commerce REST API |
-
-### React Admin UI (`configuration-management/web`)
-
-Spectrum-based Commerce Admin extension UI for schema-driven system configuration.
-
-```js
-import { createRoot } from 'react-dom/client'
-import {
-  ConfigurationManagementApp,
-  configureWeb,
-  SystemConfig
-} from 'configuration-management/web'
-import actionUrls from './config.json' // deploy-time URLs from aio app deploy
-import 'configuration-management/web/styles.css'
-
-configureWeb({ actionUrls })
-
-createRoot(document.getElementById('root')).render(
-  <ConfigurationManagementApp runtime={runtime} ims={ims} />
-)
-```
-
-| Export | Description |
-|--------|-------------|
-| `ConfigurationManagementApp` | Full app shell (router + Spectrum provider + UIX registration) |
-| `SystemConfig` | Dynamic config form UI |
-| `SystemConfigSchemaEditor` | Schema designer |
-| `useSystemConfig`, `useSystemConfigSchema` | Data hooks |
-| `configureWeb({ actionUrls, extensionId, actionKeys })` | Wire deploy-time action URLs before render |
-
-Styles: `import 'configuration-management/web/styles.css'`
-
-### App Builder actions (`configuration-management/actions`)
-
-OpenWhisk runtime actions and the Commerce Admin extension manifest ship with the package.
-
-#### Automatic wiring on `npm install`
-
-The package runs a **postinstall** script that patches your project's `app.config.yaml`
-(if it exists) with:
-
-```yaml
-extensions:
-  commerce/backend-ui/1:
-    $include: node_modules/configuration-management/actions/configurations/ext.config.yaml
-```
-
-Requirements:
-
-- Run `npm install` from your App Builder project root (where `app.config.yaml` lives).
-- Do not use `npm install --ignore-scripts` (that skips postinstall).
-
-Opt out for a single install:
-
-```bash
-CONFIGURATION_MANAGEMENT_SKIP_SETUP=1 npm install configuration-management
-```
-
-Re-run manually anytime:
-
-```bash
-npx configuration-management-setup
-```
-
-#### Manual wiring
-
-If you prefer to edit `app.config.yaml` yourself:
-
-```yaml
-extensions:
-  commerce/backend-ui/1:
-    $include: node_modules/configuration-management/actions/configurations/ext.config.yaml
-```
-
-The bundled `ext.config.yaml` declares all actions under the `ConfigurationManagement` package
-(`system-config-list`, `system-config-save`, `system-config-schema`, `export-config`,
-`import-config`, `commerce-rest-get`, `sync-store-mappings-from-commerce`) plus admin menu
-`registration`. It expects a `web-src/` folder at your project root for the UI shell.
-
-**Minimal host project layout:**
-
-```
-my-app/
-├── app.config.yaml          ← $include ext.config from node_modules (above)
-├── web-src/
-│   ├── index.html
-│   └── src/
-│       ├── index.js         ← import ConfigurationManagementApp + configureWeb
-│       └── config.json      ← generated by aio app deploy
-├── .env
-└── package.json             ← depends on configuration-management
-```
-
-Action helper utilities are also exported for custom actions:
-
-```js
-const { errorResponse, checkMissingRequestInputs } = require('configuration-management/actions/utils')
-```
-
-## Environment / action inputs
-
-| Variable | Purpose |
-|----------|---------|
-| `AIO_DB_REGION` | ABDB region (`amer`, `emea`, …) |
-| `OAUTH_CLIENT_ID`, `OAUTH_CLIENT_SECRET`, `OAUTH_ORG_ID`, `OAUTH_SCOPES` | IMS credentials for ABDB |
-| `SYSTEM_CONFIG_CRYPT_KEY` | Preferred encryption key (fallback: `OAUTH_CLIENT_SECRET`) |
-| `COMMERCE_BASE_URL`, `COMMERCE_CONSUMER_*`, `COMMERCE_ACCESS_TOKEN*` | Commerce REST (for scope code resolution) |
-
-## Storage model
-
-Documents in the `system_config_data` collection:
-
-```
-{ _id, scope, scope_id, path, value, createdAt, updatedAt }
-```
-
-Config paths use the format `section/group/field` (e.g. `sync_general/api/url`).
-
-## License
-
-Apache-2.0

package/actions/configurations/ext.config.yaml

@@ -1,151 +0,0 @@
-operations:
-  view:
-    - type: web
-      impl: index.html
-# Action sources live alongside this manifest (same directory).
-actions: .
-# Host App Builder apps override `web` to point at their UI shell (see README).
-web: ../../../../web-src
-runtimeManifest:
-  packages:
-    admin-ui-sdk:
-      license: Apache-2.0
-      actions:
-        registration:
-          function: registration/index.js
-          web: 'yes'
-          runtime: 'nodejs:20'
-          inputs:
-            LOG_LEVEL: debug
-          annotations:
-            require-adobe-auth: true
-            final: true
-    ConfigurationManagement:
-      license: Apache-2.0
-      actions:
-        commerce-rest-get:
-          function: commerce/index.js
-          web: 'yes'
-          runtime: 'nodejs:20'
-          inputs:
-            LOG_LEVEL: debug
-            COMMERCE_BASE_URL: $COMMERCE_BASE_URL
-            COMMERCE_CONSUMER_KEY: $COMMERCE_CONSUMER_KEY
-            COMMERCE_CONSUMER_SECRET: $COMMERCE_CONSUMER_SECRET
-            COMMERCE_ACCESS_TOKEN: $COMMERCE_ACCESS_TOKEN
-            COMMERCE_ACCESS_TOKEN_SECRET: $COMMERCE_ACCESS_TOKEN_SECRET
-          annotations:
-            require-adobe-auth: false
-            final: true
-        system-config-list:
-          function: system-config-list/index.js
-          web: 'yes'
-          runtime: 'nodejs:20'
-          inputs:
-            LOG_LEVEL: debug
-            SYSTEM_CONFIG_CRYPT_KEY: $SYSTEM_CONFIG_CRYPT_KEY
-            OAUTH_CLIENT_ID: $OAUTH_CLIENT_ID
-            OAUTH_CLIENT_SECRET: $OAUTH_CLIENT_SECRET
-            OAUTH_ORG_ID: $OAUTH_ORG_ID
-            OAUTH_SCOPES: $OAUTH_SCOPES
-            AIO_DB_REGION: $AIO_DB_REGION
-          annotations:
-            require-adobe-auth: false
-            include-ims-credentials: true
-            final: true
-        system-config-save:
-          function: system-config-save/index.js
-          web: 'yes'
-          runtime: 'nodejs:20'
-          inputs:
-            LOG_LEVEL: debug
-            SYSTEM_CONFIG_CRYPT_KEY: $SYSTEM_CONFIG_CRYPT_KEY
-            OAUTH_CLIENT_ID: $OAUTH_CLIENT_ID
-            OAUTH_CLIENT_SECRET: $OAUTH_CLIENT_SECRET
-            OAUTH_ORG_ID: $OAUTH_ORG_ID
-            OAUTH_SCOPES: $OAUTH_SCOPES
-            AIO_DB_REGION: $AIO_DB_REGION
-          annotations:
-            require-adobe-auth: false
-            include-ims-credentials: true
-            final: true
-        system-config-schema:
-          function: system-config-schema/index.js
-          web: 'yes'
-          runtime: 'nodejs:20'
-          inputs:
-            LOG_LEVEL: debug
-            OAUTH_CLIENT_ID: $OAUTH_CLIENT_ID
-            OAUTH_CLIENT_SECRET: $OAUTH_CLIENT_SECRET
-            OAUTH_ORG_ID: $OAUTH_ORG_ID
-            OAUTH_SCOPES: $OAUTH_SCOPES
-            AIO_DB_REGION: $AIO_DB_REGION
-          annotations:
-            require-adobe-auth: false
-            include-ims-credentials: true
-            final: true
-        export-config:
-          function: export-config/index.js
-          web: 'yes'
-          runtime: 'nodejs:20'
-          inputs:
-            LOG_LEVEL: debug
-            SYSTEM_CONFIG_CRYPT_KEY: $SYSTEM_CONFIG_CRYPT_KEY
-            OAUTH_CLIENT_ID: $OAUTH_CLIENT_ID
-            OAUTH_CLIENT_SECRET: $OAUTH_CLIENT_SECRET
-            OAUTH_ORG_ID: $OAUTH_ORG_ID
-            OAUTH_SCOPES: $OAUTH_SCOPES
-            AIO_DB_REGION: $AIO_DB_REGION
-            COMMERCE_BASE_URL: $COMMERCE_BASE_URL
-            COMMERCE_CONSUMER_KEY: $COMMERCE_CONSUMER_KEY
-            COMMERCE_CONSUMER_SECRET: $COMMERCE_CONSUMER_SECRET
-            COMMERCE_ACCESS_TOKEN: $COMMERCE_ACCESS_TOKEN
-            COMMERCE_ACCESS_TOKEN_SECRET: $COMMERCE_ACCESS_TOKEN_SECRET
-          annotations:
-            require-adobe-auth: false
-            include-ims-credentials: true
-            final: true
-        import-config:
-          function: import-config/index.js
-          web: 'yes'
-          runtime: 'nodejs:20'
-          limits:
-            timeout: 300000
-            memory: 512
-          inputs:
-            LOG_LEVEL: debug
-            SYSTEM_CONFIG_CRYPT_KEY: $SYSTEM_CONFIG_CRYPT_KEY
-            OAUTH_CLIENT_ID: $OAUTH_CLIENT_ID
-            OAUTH_CLIENT_SECRET: $OAUTH_CLIENT_SECRET
-            OAUTH_ORG_ID: $OAUTH_ORG_ID
-            OAUTH_SCOPES: $OAUTH_SCOPES
-            AIO_DB_REGION: $AIO_DB_REGION
-            COMMERCE_BASE_URL: $COMMERCE_BASE_URL
-            COMMERCE_CONSUMER_KEY: $COMMERCE_CONSUMER_KEY
-            COMMERCE_CONSUMER_SECRET: $COMMERCE_CONSUMER_SECRET
-            COMMERCE_ACCESS_TOKEN: $COMMERCE_ACCESS_TOKEN
-            COMMERCE_ACCESS_TOKEN_SECRET: $COMMERCE_ACCESS_TOKEN_SECRET
-          annotations:
-            require-adobe-auth: false
-            include-ims-credentials: true
-            final: true
-        sync-store-mappings-from-commerce:
-          function: sync-store-mappings-from-commerce/index.js
-          web: 'yes'
-          runtime: 'nodejs:20'
-          inputs:
-            LOG_LEVEL: debug
-            OAUTH_CLIENT_ID: $OAUTH_CLIENT_ID
-            OAUTH_CLIENT_SECRET: $OAUTH_CLIENT_SECRET
-            OAUTH_ORG_ID: $OAUTH_ORG_ID
-            OAUTH_SCOPES: $OAUTH_SCOPES
-            AIO_DB_REGION: $AIO_DB_REGION
-            COMMERCE_BASE_URL: $COMMERCE_BASE_URL
-            COMMERCE_CONSUMER_KEY: $COMMERCE_CONSUMER_KEY
-            COMMERCE_CONSUMER_SECRET: $COMMERCE_CONSUMER_SECRET
-            COMMERCE_ACCESS_TOKEN: $COMMERCE_ACCESS_TOKEN
-            COMMERCE_ACCESS_TOKEN_SECRET: $COMMERCE_ACCESS_TOKEN_SECRET
-          annotations:
-            require-adobe-auth: false
-            include-ims-credentials: true
-            final: true

package/src/abdb-config.js

@@ -1,241 +0,0 @@
-/*
-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 { getCommerceOauthClient } = require('./oauth1a')
-const {
-  isValidPath,
-  toStateKey,
-  buildInheritanceChain,
-  normalizeScope,
-  normalizeScopeId
-} = require('./system-config-shared')
-const { getClient } = require('./abdb-helper')
-const { isEncrypted, decrypt } = require('./system-config-crypto')
-
-const COLLECTION = 'system_config_data'
-const CACHE_TTL_MS = 5 * 60 * 1000
-
-// Per-lookup result cache.
-const cache = new Map() // key: `${scope}:${scopeId}:${path}` → { value, expiresAt }
-
-// Commerce code → numeric id maps. Refreshed at most every CACHE_TTL_MS.
-let websiteCodeToId = null     // Map<code, id>
-let websiteCodeToIdAt = 0
-let storeCodeToId = null       // Map<code, id> + parentWebsiteId
-let storeCodeToIdAt = 0
-
-function maybeParseJson (value) {
-  if (typeof value !== 'string') return value
-  const trimmed = value.trim()
-  if (!trimmed) return value
-  if (!(trimmed.startsWith('{') || trimmed.startsWith('['))) return value
-  try { return JSON.parse(trimmed) } catch { return value }
-}
-
-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
-  }
-}
-
-function pickCommerceCreds (params) {
-  return {
-    url: params.COMMERCE_BASE_URL || process.env.COMMERCE_BASE_URL,
-    consumerKey: params.COMMERCE_CONSUMER_KEY || process.env.COMMERCE_CONSUMER_KEY,
-    consumerSecret: params.COMMERCE_CONSUMER_SECRET || process.env.COMMERCE_CONSUMER_SECRET,
-    accessToken: params.COMMERCE_ACCESS_TOKEN || process.env.COMMERCE_ACCESS_TOKEN,
-    accessTokenSecret: params.COMMERCE_ACCESS_TOKEN_SECRET || process.env.COMMERCE_ACCESS_TOKEN_SECRET
-  }
-}
-
-async function loadWebsiteCodeMap (params) {
-  const now = Date.now()
-  if (websiteCodeToId && (now - websiteCodeToIdAt) < CACHE_TTL_MS) return websiteCodeToId
-
-  const creds = pickCommerceCreds(params)
-  if (!creds.url) return websiteCodeToId || new Map()
-
-  try {
-    const oauth = getCommerceOauthClient(creds, { error: () => {}, info: () => {} })
-    const websites = await oauth.get('store/websites')
-    const map = new Map()
-    if (Array.isArray(websites)) {
-      for (const w of websites) {
-        if (w && w.code != null && w.id != null) {
-          map.set(String(w.code), String(w.id))
-        }
-      }
-    }
-    websiteCodeToId = map
-    websiteCodeToIdAt = now
-    return map
-  } catch (_) {
-    return websiteCodeToId || new Map()
-  }
-}
-
-async function loadStoreViewCodeMap (params) {
-  const now = Date.now()
-  if (storeCodeToId && (now - storeCodeToIdAt) < CACHE_TTL_MS) return storeCodeToId
-
-  const creds = pickCommerceCreds(params)
-  if (!creds.url) return storeCodeToId || new Map()
-
-  try {
-    const oauth = getCommerceOauthClient(creds, { error: () => {}, info: () => {} })
-    const stores = await oauth.get('store/storeViews')
-    const map = new Map()
-    if (Array.isArray(stores)) {
-      for (const s of stores) {
-        if (s && s.code != null && s.id != null) {
-          map.set(String(s.code), { id: String(s.id), websiteId: s.website_id != null ? String(s.website_id) : null })
-        }
-      }
-    }
-    storeCodeToId = map
-    storeCodeToIdAt = now
-    return map
-  } catch (_) {
-    return storeCodeToId || new Map()
-  }
-}
-
-/**
- * Resolve a scope code (e.g. website 'ch', store view 'en_ch') to its numeric
- * id via Commerce REST. Returns null when the code can't be resolved AND no
- * verbatim fallback is wanted.
- */
-async function resolveScopeId (scope, code, params) {
-  if (!code) return null
-  if (scope === 'websites') {
-    const map = await loadWebsiteCodeMap(params)
-    return map.get(String(code)) || null
-  }
-  if (scope === 'stores') {
-    const map = await loadStoreViewCodeMap(params)
-    return map.get(String(code))?.id || null
-  }
-  return null
-}
-
-/**
- * Look up a single config value from ABDB.
- *
- * @param {string} path     `<section>/<group>/<field>` (e.g. 'campaign_general/url/url')
- * @param {object} [params] action params containing OAuth + crypto + Commerce creds.
- *                          Falls back to process.env when omitted.
- * @param {object} [options]
- * @param {string} [options.scope='default']        'default' | 'websites' | 'stores'
- * @param {string} [options.scopeId]                website / store id (numeric string); takes precedence over scopeCode
- * @param {string} [options.scopeCode]              website / store-view CODE — resolved to numeric id via Commerce REST
- * @param {string|number} [options.parentWebsiteId] used when scope='stores' to fall back to the parent website
- * @param {string} [options.parentWebsiteCode]      same as parentWebsiteId but resolved from a website code
- * @param {boolean} [options.fresh]                 bypass the cache
- * @returns {Promise<*|null>}
- */
-async function getConfig (path, params = {}, options = {}) {
-  if (!isValidPath(path)) return null
-
-  let scope
-  try {
-    scope = normalizeScope(options.scope)
-  } catch (_) {
-    return null
-  }
-
-  // 1. Resolve the active scope id (numeric).
-  let resolvedScopeId
-  if (scope === 'default') {
-    resolvedScopeId = '0'
-  } else if (options.scopeId != null && options.scopeId !== '') {
-    resolvedScopeId = String(options.scopeId)
-  } else if (options.scopeCode) {
-    const fromCommerce = await resolveScopeId(scope, options.scopeCode, params)
-    // If Commerce isn't reachable, fall back to using the code verbatim — the
-    // value still gets queried, and the legacy `getSystemConfig` shim writes
-    // under the literal code so this keeps working.
-    resolvedScopeId = fromCommerce || String(options.scopeCode)
-  } else {
-    return null
-  }
-
-  // 2. Resolve the parent website id for store-scope inheritance.
-  let parentWebsiteId = options.parentWebsiteId
-  if (parentWebsiteId == null && options.parentWebsiteCode) {
-    parentWebsiteId =
-      await resolveScopeId('websites', options.parentWebsiteCode, params) ||
-      String(options.parentWebsiteCode)
-  }
-  // Auto-derive parentWebsiteId from the store view itself when not given.
-  if (parentWebsiteId == null && scope === 'stores' && options.scopeCode) {
-    const sMap = await loadStoreViewCodeMap(params)
-    parentWebsiteId = sMap.get(String(options.scopeCode))?.websiteId || undefined
-  }
-
-  let normalizedScopeId
-  try {
-    normalizedScopeId = normalizeScopeId(scope, resolvedScopeId)
-  } catch (_) {
-    return null
-  }
-
-  const cacheKey = `${scope}:${normalizedScopeId}:${path}`
-  const now = Date.now()
-  if (!options.fresh) {
-    const c = cache.get(cacheKey)
-    if (c && c.expiresAt > now) return c.value
-  }
-
-  let handle
-  try {
-    handle = await getClient(params)
-  } catch (_) {
-    return null
-  }
-
-  try {
-    const collection = await handle.client.collection(COLLECTION)
-    const chain = buildInheritanceChain(scope, normalizedScopeId, parentWebsiteId)
-
-    let resolved = null
-    for (const link of chain) {
-      const id = toStateKey(link.scope, link.scopeId, path)
-      const doc = await tryFindOne(collection, { _id: id })
-      if (!doc || doc.value === undefined) continue
-      let value = doc.value
-      if (isEncrypted(value)) {
-        try { value = decrypt(value, params) } catch (_) { /* keep raw */ }
-      }
-      value = maybeParseJson(value)
-      resolved = value
-      break
-    }
-
-    cache.set(cacheKey, { value: resolved, expiresAt: now + CACHE_TTL_MS })
-    return resolved
-  } finally {
-    try { await handle.close() } catch (_) { /* noop */ }
-  }
-}
-
-/** Clear the entire in-process cache (e.g. after a re-migration). */
-function clearAbdbConfigCache () {
-  cache.clear()
-  websiteCodeToId = null
-  storeCodeToId = null
-}
-
-module.exports = {
-  COLLECTION,
-  getConfig,
-  clearAbdbConfigCache
-}