@adobedjangir/commerce-admin-management 0.0.18 → 0.0.20
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +85 -78
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -29,18 +29,20 @@ and an extension point for host apps to add their own pages and actions.
|
|
|
29
29
|
|
|
30
30
|
## What you get
|
|
31
31
|
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
|
32
|
+
|
|
33
|
+
| Capability | Where it lives |
|
|
34
|
+
| ------------------------------------------------------------------------------- | --------------------------------------------------- |
|
|
35
|
+
| Schema-driven config form (sections / groups / fields) | UI: `SystemConfig` page (built-in tab) |
|
|
35
36
|
| Per-scope values (`default → websites → stores`) with Magento-style inheritance | Action: `system-config-list` / `system-config-save` |
|
|
36
|
-
| AES-256-GCM encryption of sensitive fields at rest
|
|
37
|
-
| Adobe Commerce REST/OAuth1a client helper
|
|
38
|
-
| First-run setup wizard for Commerce credentials (saved encrypted in ABDB)
|
|
39
|
-
| Bulk JSON export/import with cross-environment website/store id remapping
|
|
40
|
-
| App Builder Database (ABDB) auto-provisioning on deploy
|
|
41
|
-
| Host-extensible nav and pages
|
|
42
|
-
| Auto-scaffolded host scaffold on `npm install`
|
|
43
|
-
| Auto-bump host React/Spectrum/Adobe deps to React-18 floor
|
|
37
|
+
| AES-256-GCM encryption of sensitive fields at rest | `system-config-crypto` module |
|
|
38
|
+
| Adobe Commerce REST/OAuth1a client helper | `commerce-creds` module |
|
|
39
|
+
| First-run setup wizard for Commerce credentials (saved encrypted in ABDB) | UI: `CommerceSetupWizard` |
|
|
40
|
+
| Bulk JSON export/import with cross-environment website/store id remapping | Actions: `export-config`, `import-config` |
|
|
41
|
+
| App Builder Database (ABDB) auto-provisioning on deploy | `ext.config.yaml` |
|
|
42
|
+
| Host-extensible nav and pages | `configureWeb({ extraNav, extraPages })` |
|
|
43
|
+
| Auto-scaffolded host scaffold on `npm install` | `scripts/setup.js` (postinstall hook) |
|
|
44
|
+
| Auto-bump host React/Spectrum/Adobe deps to React-18 floor | `scripts/setup.js` mutates host `package.json` |
|
|
45
|
+
|
|
44
46
|
|
|
45
47
|
---
|
|
46
48
|
|
|
@@ -53,22 +55,17 @@ cd my-commerce-admin
|
|
|
53
55
|
|
|
54
56
|
# 2. Install with --legacy-peer-deps on first install.
|
|
55
57
|
# aio's default template pins React 16; this package requires React 18.
|
|
56
|
-
npm install
|
|
58
|
+
npm install @adobedjangir/commerce-admin-management
|
|
57
59
|
|
|
58
60
|
# 3. Run the setup helper. Bumps host deps to React 18 / Spectrum 4 floor,
|
|
59
61
|
# scaffolds web-src/, removes the dx/excshell/1 boilerplate, and
|
|
60
62
|
# generates AIO_DB_REGION + SYSTEM_CONFIG_CRYPT_KEY in .env.
|
|
61
|
-
npx
|
|
63
|
+
npx commerce-admin-management-setup
|
|
62
64
|
|
|
63
65
|
# 4. Apply the bumped versions
|
|
64
|
-
rm -rf node_modules package-lock.json
|
|
65
66
|
npm install
|
|
66
67
|
|
|
67
|
-
# 5.
|
|
68
|
-
# auto-generated by step 3.
|
|
69
|
-
$EDITOR .env
|
|
70
|
-
|
|
71
|
-
# 6. Deploy. ABDB is auto-provisioned; actions + web assets ship to CDN.
|
|
68
|
+
# 5. Deploy. ABDB is auto-provisioned; actions + web assets ship to CDN.
|
|
72
69
|
aio app deploy
|
|
73
70
|
```
|
|
74
71
|
|
|
@@ -90,13 +87,15 @@ aio app run
|
|
|
90
87
|
The package's `postinstall` runs `scripts/setup.js`, which idempotently
|
|
91
88
|
materializes a host scaffold:
|
|
92
89
|
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
|
96
|
-
| `
|
|
97
|
-
| `web-src/src/
|
|
98
|
-
| `web-src/src/
|
|
99
|
-
| `web-src/src/pages/
|
|
90
|
+
|
|
91
|
+
| Path | First install | Subsequent installs |
|
|
92
|
+
| ------------------------------ | -------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
|
|
93
|
+
| `app.config.yaml` | Adds `extensions: commerce/backend-ui/1: $include …` if absent | No-op |
|
|
94
|
+
| `web-src/src/index.js` | Writes the package-wired bootstrap | Re-syncs if the marker is present; left alone if the host imported `@adobedjangir/commerce-admin-management/web` and removed the marker |
|
|
95
|
+
| `web-src/src/nav.json` | Writes a starter entry → `#/welcome` | Never overwritten |
|
|
96
|
+
| `web-src/src/pages/index.js` | Writes a registry that imports `Welcome` | Never overwritten |
|
|
97
|
+
| `web-src/src/pages/Welcome.js` | Writes a React-Spectrum starter page | Never overwritten |
|
|
98
|
+
|
|
100
99
|
|
|
101
100
|
> The "never overwritten" rule means you can edit those files freely;
|
|
102
101
|
> upgrading the package will not lose your changes.
|
|
@@ -109,14 +108,16 @@ bundle has a ready-to-consume artifact.
|
|
|
109
108
|
|
|
110
109
|
## Required `.env` values
|
|
111
110
|
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
|
115
|
-
| `
|
|
116
|
-
| `
|
|
117
|
-
| `
|
|
118
|
-
| `
|
|
119
|
-
| `
|
|
111
|
+
|
|
112
|
+
| Variable | Purpose |
|
|
113
|
+
| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
114
|
+
| `OAUTH_CLIENT_ID` | Adobe IMS Server-to-Server credentials — for ABDB token |
|
|
115
|
+
| `OAUTH_CLIENT_SECRET` | same |
|
|
116
|
+
| `OAUTH_ORG_ID` | same |
|
|
117
|
+
| `OAUTH_SCOPES` | should include `AdobeID, openid, read_organizations, additional_info.projectedProductContext, additional_info.roles, adobeio_api, read_client_secret, manage_client_secrets, event_receiver_api, commerce.accs` |
|
|
118
|
+
| `AIO_DB_REGION` | One of `amer | emea | apac | aus`. Must match the region where the App Builder Database service is entitled. |
|
|
119
|
+
| `SYSTEM_CONFIG_CRYPT_KEY` | At least 8 chars. **Generate once with `openssl rand -base64 32` and never rotate** — rotating breaks every encrypted value already in ABDB. |
|
|
120
|
+
|
|
120
121
|
|
|
121
122
|
Commerce REST creds (`COMMERCE_BASE_URL`, `COMMERCE_CONSUMER_KEY`, …) are
|
|
122
123
|
**no longer set via `.env`**. They are entered in the in-app wizard and
|
|
@@ -163,20 +164,22 @@ encrypted into ABDB under `default/_system/commerce/connection`.
|
|
|
163
164
|
|
|
164
165
|
## Built-in actions
|
|
165
166
|
|
|
166
|
-
All under runtime package
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
|
171
|
-
| `commerce-
|
|
172
|
-
| `commerce-connection-
|
|
173
|
-
| `commerce-connection-
|
|
174
|
-
| `
|
|
175
|
-
| `system-config-
|
|
176
|
-
| `system-config-
|
|
177
|
-
| `
|
|
178
|
-
| `
|
|
179
|
-
| `
|
|
167
|
+
All under runtime package `**CommerceAdminManagement**`.
|
|
168
|
+
|
|
169
|
+
|
|
170
|
+
| Action | Verb | Description |
|
|
171
|
+
| ----------------------------------- | ---- | ------------------------------------------------------------------------------------------------ |
|
|
172
|
+
| `commerce-rest-get` | POST | Proxy any Commerce REST GET via OAuth1a using stored creds |
|
|
173
|
+
| `commerce-connection-status` | POST | `{ configured: bool, creds: masked }` |
|
|
174
|
+
| `commerce-connection-test` | POST | Verifies form values OR saved creds against `store/storeConfigs` |
|
|
175
|
+
| `commerce-connection-save` | POST | Tests then encrypts + upserts creds in ABDB |
|
|
176
|
+
| `system-config-list` | POST | Reads paths with Magento-style scope inheritance, decrypts sensitive fields |
|
|
177
|
+
| `system-config-save` | POST | Upserts values, encrypts sensitive paths |
|
|
178
|
+
| `system-config-schema` | POST | CRUD on the schema document |
|
|
179
|
+
| `export-config` | POST | Dumps schema + values (sensitive decrypted) as portable JSON |
|
|
180
|
+
| `import-config` | POST | Re-imports a dump, re-encrypts with the target's key, remaps website/store ids via Commerce REST |
|
|
181
|
+
| `sync-store-mappings-from-commerce` | POST | Refreshes the `general/settings/store_mappings` blob from Commerce |
|
|
182
|
+
|
|
180
183
|
|
|
181
184
|
All actions are `require-adobe-auth: false` and `include-ims-credentials: true`,
|
|
182
185
|
so they receive the host's OAuth credentials via env-injection — they don't
|
|
@@ -203,7 +206,7 @@ ABDB collection `system_config_data` — one document per (scope, scope_id, path
|
|
|
203
206
|
- `_id` is `sysconfig__<scope>__<scopeId>__<path-with-/-as-__>`
|
|
204
207
|
- Inheritance chain: `stores:<storeId> → websites:<websiteId> → default:0`
|
|
205
208
|
- Sensitive `value`s carry the prefix `enc:v1:<salt>:<iv>:<tag>:<ct>` (all
|
|
206
|
-
|
|
209
|
+
base64url) — see [Encryption](#encryption).
|
|
207
210
|
|
|
208
211
|
Schema is stored separately in `system_config_schema` (single doc `_id: 'v1'`).
|
|
209
212
|
|
|
@@ -222,12 +225,12 @@ isEncrypted('enc:v1:...') // → true
|
|
|
222
225
|
```
|
|
223
226
|
|
|
224
227
|
- Per-record `salt` ⇒ same plaintext under same key produces a different
|
|
225
|
-
|
|
228
|
+
ciphertext each save (no oracle attacks).
|
|
226
229
|
- Wire format is versioned (`v1`) so the algorithm can be rotated without
|
|
227
|
-
|
|
230
|
+
breaking existing values.
|
|
228
231
|
- A fallback to `OAUTH_CLIENT_SECRET` exists for first-touch convenience but
|
|
229
|
-
|
|
230
|
-
|
|
232
|
+
is **strongly discouraged in production** — your IMS client secret rotates;
|
|
233
|
+
your at-rest data must not.
|
|
231
234
|
|
|
232
235
|
---
|
|
233
236
|
|
|
@@ -309,7 +312,7 @@ export default pages
|
|
|
309
312
|
props for use with `callAction`.
|
|
310
313
|
|
|
311
314
|
**Icon names** come from a Spectrum-icon registry in
|
|
312
|
-
[
|
|
315
|
+
`[web/src/nav-icons.js](web/src/nav-icons.js)`. Built-in: `Settings`,
|
|
313
316
|
`Properties`, `Data`, `User`, `ShoppingCart`, `Box`, `Folder`. To add more,
|
|
314
317
|
extend that file and rebuild the package (`node scripts/build-web.js`).
|
|
315
318
|
|
|
@@ -497,15 +500,17 @@ import '@adobedjangir/commerce-admin-management/web/styles.css'
|
|
|
497
500
|
|
|
498
501
|
## Configuration override matrix
|
|
499
502
|
|
|
500
|
-
|
|
501
|
-
|
|
502
|
-
|
|
|
503
|
-
| ABDB
|
|
504
|
-
|
|
|
505
|
-
|
|
|
506
|
-
|
|
|
507
|
-
| Built-in
|
|
508
|
-
|
|
|
503
|
+
|
|
504
|
+
| Setting | Default lives in | Override location | Override mechanism |
|
|
505
|
+
| ---------------------------------- | --------------------------------------------------------------------------- | --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
506
|
+
| ABDB auto-provision | package `ext.config.yaml` (`runtimeManifest.database.auto-provision: true`) | host `app.config.yaml` | `application: runtimeManifest: database: auto-provision: false` |
|
|
507
|
+
| ABDB region | package `ext.config.yaml` (literal `emea`) | host `app.config.yaml` | `application: runtimeManifest: database: region: amer` (and update `AIO_DB_REGION` in `.env` to match) |
|
|
508
|
+
| Runtime IMS token | computed by `aio-lib-core-auth` | n/a | The action runtime injects via `include-ims-credentials: true` |
|
|
509
|
+
| Action keys (URL paths) | `web/src/settings.js` (`DEFAULT_ACTION_KEYS`) | host bootstrap | `configureWeb({ actionKeys: { ... } })` |
|
|
510
|
+
| Built-in nav entries | package `web/src/nav.json` | host `web-src/src/nav.json` | extras merge after built-ins; host wins on id collision |
|
|
511
|
+
| Built-in pages | package `web/src/pages/index.js` | host `web-src/src/pages/index.js` | extras merge; host wins on id collision |
|
|
512
|
+
| Bootstrap (`web-src/src/index.js`) | package generator | own the file | Either remove the marker comment **and** import from `@adobedjangir/commerce-admin-management/web`, **or** edit freely while keeping the marker (loses on next install) |
|
|
513
|
+
|
|
509
514
|
|
|
510
515
|
---
|
|
511
516
|
|
|
@@ -517,10 +522,10 @@ import '@adobedjangir/commerce-admin-management/web/styles.css'
|
|
|
517
522
|
value becomes undecryptable. If you must:
|
|
518
523
|
|
|
519
524
|
1. Export with the old key: `POST /export-config { schemaOnly: false }` — the
|
|
520
|
-
|
|
525
|
+
dump contains plaintext values for sensitive fields (v2+ dump format).
|
|
521
526
|
2. Update `SYSTEM_CONFIG_CRYPT_KEY` in `.env` and redeploy.
|
|
522
527
|
3. Re-import the dump: `POST /import-config { dump, overwrite: true }` — the
|
|
523
|
-
|
|
528
|
+
importer re-encrypts sensitive paths with the new key.
|
|
524
529
|
|
|
525
530
|
For cross-environment migration (different key on each side), pass
|
|
526
531
|
`sourceCryptKey: '<old-key>'` to `import-config` so it can decrypt the
|
|
@@ -530,9 +535,9 @@ ciphertext with the old key before re-encrypting with the new one.
|
|
|
530
535
|
|
|
531
536
|
1. Update `AIO_DB_REGION` in `.env`.
|
|
532
537
|
2. Update `region:` literal under `runtimeManifest.database` in
|
|
533
|
-
|
|
538
|
+
`app.config.yaml` (host overrides the package default).
|
|
534
539
|
3. Ensure the workspace has App Builder Database entitled in that region in
|
|
535
|
-
|
|
540
|
+
the Adobe Developer Console.
|
|
536
541
|
4. `aio app deploy`.
|
|
537
542
|
|
|
538
543
|
### Promote a deploy
|
|
@@ -569,16 +574,18 @@ aio app run
|
|
|
569
574
|
|
|
570
575
|
## Troubleshooting
|
|
571
576
|
|
|
572
|
-
|
|
573
|
-
|
|
574
|
-
|
|
|
575
|
-
| `
|
|
576
|
-
|
|
|
577
|
-
|
|
|
578
|
-
|
|
|
579
|
-
|
|
|
580
|
-
|
|
|
581
|
-
|
|
|
577
|
+
|
|
578
|
+
| Symptom | Likely cause | Fix |
|
|
579
|
+
| ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
580
|
+
| `Database not provisioned` | App Builder Database not entitled on the workspace, **or** never ran `aio app deploy` since adding the package | Add the service in the Developer Console (region must match `AIO_DB_REGION`), then `aio app deploy` |
|
|
581
|
+
| `Invalid region '$AIO_DB_REGION'` | Tried to use `$VAR` substitution in `runtimeManifest.database.region` | aio substitutes `$VAR` only inside action `inputs:`. Use a literal region in YAML |
|
|
582
|
+
| Blank page at `#/<anything>` | Route table doesn't include a catch-all | Already fixed — `App.js` uses `path="*"`. If you forked it, add `<Route path="*" element={…}>` |
|
|
583
|
+
| Stuck on "Checking Commerce connection…" forever | Running outside Experience Cloud iframe; `@adobe/uix-guest`'s `attach()` was blocking | Already fixed — MainPage's `attach()` now races a 2-second timeout |
|
|
584
|
+
| Reports tab blank but System Configurations works | `pages/index.js` used CommonJS `require('./X').default` interop | Use ES `import X from './X'` instead |
|
|
585
|
+
| Nav button overflows below tabs | CSS not picked up | Make sure the package's `dist/index.css` is loaded (the bootstrap imports it automatically) |
|
|
586
|
+
| Encryption errors after env change | `SYSTEM_CONFIG_CRYPT_KEY` was rotated and there are old `enc:v1:` values | Either restore the old key, or perform the export/import re-encryption flow above |
|
|
587
|
+
| `npm install` overwrote my bootstrap | Marker comment still present | Remove the marker comment line, **and** ensure your file imports from `@adobedjangir/commerce-admin-management/web` so setup recognizes host-managed mode |
|
|
588
|
+
|
|
582
589
|
|
|
583
590
|
---
|
|
584
591
|
|
|
@@ -645,4 +652,4 @@ packages/commerce-admin-management/
|
|
|
645
652
|
|
|
646
653
|
## License
|
|
647
654
|
|
|
648
|
-
Apache-2.0 © Adobe Inc.
|
|
655
|
+
Apache-2.0 © Adobe Inc.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@adobedjangir/commerce-admin-management",
|
|
3
|
-
"version": "0.0.
|
|
3
|
+
"version": "0.0.20",
|
|
4
4
|
"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.",
|
|
5
5
|
"license": "Apache-2.0",
|
|
6
6
|
"author": "Adobe Inc.",
|
|
@@ -70,7 +70,7 @@
|
|
|
70
70
|
}
|
|
71
71
|
},
|
|
72
72
|
"dependencies": {
|
|
73
|
-
"@adobedjangir/commerce-admin-get-config": "^0.0.
|
|
73
|
+
"@adobedjangir/commerce-admin-get-config": "^0.0.2",
|
|
74
74
|
"esbuild": "^0.25.12"
|
|
75
75
|
},
|
|
76
76
|
"repository": {
|