configuration-management 0.1.3 → 0.1.6

package/README.md

@@ -0,0 +1,216 @@
+# 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 React from 'react'
+import { createRoot } from 'react-dom/client'
+import {
+  ConfigurationManagementApp,
+  configureWeb
+} from 'configuration-management/web'
+import actionUrls from './config.json'
+import 'configuration-management/web/styles.css'
+
+configureWeb({ actionUrls })
+
+createRoot(document.getElementById('root')).render(
+  React.createElement(ConfigurationManagementApp, { runtime, ims })
+)
+```
+
+The web UI is **pre-built** in the package (`web/dist/index.js`), so no Parcel
+`includeNodeModules` or webpack aliases are required in your host `package.json`.
+
+| 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:
+
+1. Patches your project's `app.config.yaml` (if present) with:
+
+```yaml
+extensions:
+  commerce/backend-ui/1:
+    $include: node_modules/configuration-management/actions/configurations/ext.config.yaml
+```
+
+2. Scaffolds a minimal `web-src/` bootstrap (if missing or previously auto-generated):
+
+```
+web-src/
+├── index.html
+└── src/
+    ├── index.js       ← imports ConfigurationManagementApp from the package
+    ├── exc-runtime.js
+    └── config.json    ← created empty; filled by aio app deploy
+```
+
+Custom `web-src` files are left untouched unless they were created by a prior install
+(files containing the `configuration-management: auto-generated bootstrap` marker, or
+an older bootstrap that imports `configuration-management/web`).
+
+- 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

@@ -0,0 +1,151 @@
+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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "configuration-management",
-  "version": "0.1.3",
+  "version": "0.1.6",
   "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.",
@@ -16,10 +16,12 @@
   ],
   "main": "./src/index.js",
   "bin": {
-    "configuration-management-setup": "./scripts/setup-app-config.js"
+    "configuration-management-setup": "./scripts/setup.js"
   },
   "scripts": {
-    "postinstall": "node ./scripts/setup-app-config.js"
+    "build": "node ./scripts/build-web.js",
+    "prepublishOnly": "node ./scripts/build-web.js",
+    "postinstall": "node ./scripts/build-web.js && node ./scripts/setup.js"
   },
   "exports": {
     ".": "./src/index.js",
@@ -28,10 +30,10 @@
     "./crypto": "./src/system-config-crypto.js",
     "./shared": "./src/system-config-shared.js",
     "./oauth1a": "./src/oauth1a.js",
-    "./web": "./web/index.js",
-    "./web/index.js": "./web/index.js",
-    "./web/src/styles/index.css": "./web/src/styles/index.css",
+    "./web": "./web/dist/index.js",
+    "./web/index.js": "./web/dist/index.js",
     "./web/styles.css": "./web/src/styles/index.css",
+    "./web/src/styles/index.css": "./web/src/styles/index.css",
     "./actions/utils": "./actions/utils.js",
     "./actions/ext.config.yaml": "./actions/configurations/ext.config.yaml"
   },
@@ -61,6 +63,7 @@
     "react-router-dom": "^6.8.1"
   },
   "dependencies": {
+    "esbuild": "^0.25.12",
     "got": "^11.8.5",
     "oauth-1.0a": "^2.2.6"
   },

package/scripts/build-web.js

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+/*
+Copyright 2025 Adobe. All rights reserved.
+Licensed under the Apache License, Version 2.0
+*/
+
+const fs = require('fs')
+const path = require('path')
+
+async function main () {
+  let esbuild
+  try {
+    esbuild = require('esbuild')
+  } catch {
+    console.error('[configuration-management] esbuild is required to build the web UI. Run npm install in the package directory.')
+    process.exit(1)
+  }
+
+  const pkgRoot = path.join(__dirname, '..')
+  const entry = path.join(pkgRoot, 'web/src/index.js')
+  const outdir = path.join(pkgRoot, 'web/dist')
+  const outfile = path.join(outdir, 'index.js')
+
+  fs.mkdirSync(outdir, { recursive: true })
+
+  await esbuild.build({
+    entryPoints: [entry],
+    bundle: true,
+    format: 'esm',
+    platform: 'browser',
+    outfile,
+    packages: 'external',
+    jsx: 'automatic',
+    loader: { '.js': 'jsx' },
+    target: ['chrome79', 'firefox85', 'safari13'],
+    logLevel: 'info'
+  })
+
+  console.log('[configuration-management] built web/dist/index.js')
+}
+
+if (require.main === module) {
+  main().catch((err) => {
+    console.error('[configuration-management] build-web failed:', err.message)
+    process.exit(1)
+  })
+}
+
+module.exports = { main }