configuration-get-config 0.1.0

package/README.md

@@ -0,0 +1,43 @@
+# configuration-get-config
+
+Read scoped system configuration from **Adobe App Builder Database (ABDB)**.
+
+Provides `getConfig()` with Magento-style scope inheritance (`default` → `websites` → `stores`), AES-256-GCM decryption for sensitive values, and Commerce REST helpers for resolving website/store codes to numeric IDs.
+
+## Install
+
+```bash
+npm install configuration-get-config
+```
+
+Peer dependencies (App Builder runtime):
+
+```bash
+npm install @adobe/aio-lib-core-auth @adobe/aio-lib-db @adobe/aio-lib-ims dotenv
+```
+
+## Usage
+
+```js
+const { getConfig } = require('configuration-get-config')
+
+async function main (params) {
+  const apiUrl = await getConfig('sync_general/api/url', params, {
+    scope: 'websites',
+    scopeCode: 'base'
+  })
+}
+```
+
+## API
+
+| Export | Description |
+|--------|-------------|
+| `getConfig(path, params, options)` | Read a config value with scope inheritance |
+| `clearAbdbConfigCache()` | Clear the in-process lookup cache |
+
+Subpath exports: `./abdb`, `./config`, `./crypto`, `./shared`, `./oauth1a`
+
+## License
+
+Apache-2.0

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "configuration-get-config",
+  "version": "0.1.0",
+  "description": "Read scoped system configuration from Adobe App Builder Database (ABDB) with Magento-style inheritance, encryption, and Commerce REST scope resolution.",
+  "license": "Apache-2.0",
+  "author": "Adobe Inc.",
+  "keywords": [
+    "adobe-io",
+    "aio",
+    "app-builder",
+    "adobe-commerce",
+    "configuration",
+    "abdb",
+    "get-config"
+  ],
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./abdb": "./src/abdb-helper.js",
+    "./config": "./src/abdb-config.js",
+    "./crypto": "./src/system-config-crypto.js",
+    "./shared": "./src/system-config-shared.js",
+    "./oauth1a": "./src/oauth1a.js"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "peerDependencies": {
+    "@adobe/aio-lib-core-auth": "^1.1.0",
+    "@adobe/aio-lib-db": "^1.0.1",
+    "@adobe/aio-lib-ims": "^8.0.0",
+    "dotenv": "^16.4.5"
+  },
+  "dependencies": {
+    "got": "^11.8.5",
+    "oauth-1.0a": "^2.2.6"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/adobe/config-management-poc.git",
+    "directory": "packages/configuration-get-config"
+  }
+}

package/src/abdb-config.js

@@ -0,0 +1,241 @@
+/*
+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
+}

package/src/abdb-helper.js

@@ -0,0 +1,476 @@
+/*
+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
+
+Unless required by applicable law or agreed to in writing, software distributed under
+the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+OF ANY KIND, either express or implied. See the License for the specific language
+governing permissions and limitations under the License.
+*/
+
+const { generateAccessToken } = require('@adobe/aio-lib-core-auth')
+const libDb = require('@adobe/aio-lib-db')
+
+const COLLECTION_IMPORT_QUEUE = 'import_queue'
+const IMPORT_PIPELINE_COLLECTIONS = [COLLECTION_IMPORT_QUEUE]
+const ABDB_SCOPES = ['adobeio.abdata.read', 'adobeio.abdata.write', 'adobeio.abdata.manage']
+
+function isUnsetOauthInput (value) {
+  if (value == null || value === '') return true
+  const s = String(value).trim()
+  return s === '' || s.startsWith('$')
+}
+
+function normalizeScopesToArray (scopes) {
+  if (!scopes) return []
+  if (Array.isArray(scopes)) return scopes.filter(Boolean).map(String)
+  const s = String(scopes).trim()
+  if (!s) return []
+  return s.split(/[\s,]+/).filter(Boolean)
+}
+
+/**
+ * Get ABDB client. Requires action to have include-ims-credentials: true.
+ *
+ * Region resolution (first non-empty wins):
+ *   1. options.region              — explicit override at the call site
+ *   2. params.AIO_DB_REGION        — action input from ext.config.yaml
+ *   3. process.env.AIO_DB_REGION   — local .env when running aio app run
+ *
+ * Throws if none is configured — we never silently pick a region for you.
+ *
+ * @param {object} params - Action params (must contain OAuth credentials for generateAccessToken)
+ * @param {object} [options]
+ * @param {string} [options.region] - explicit region override
+ * @returns {Promise<{client: object, close: function}>}
+ */
+async function getClient (params, options = {}) {
+  const tokenResponse = await generateAccessToken(params)
+  const token = tokenResponse.access_token || tokenResponse
+  const region = options.region || params?.AIO_DB_REGION || process.env.AIO_DB_REGION
+  if (!region || typeof region !== 'string' || !region.trim()) {
+    throw new Error(
+      'ABDB region not configured: set AIO_DB_REGION in .env and pass it through ext.config.yaml inputs'
+    )
+  }
+
+  const db = await libDb.init({ token, region: region.trim() })
+  const client = await db.connect()
+
+  return {
+    client,
+    close: () => client.close()
+  }
+}
+
+/**
+ * Get collection by name
+ * @param {object} client - ABDB client from getClient()
+ * @param {string} collectionName - Collection name
+ * @returns {Promise<object>} MongoDB-style collection
+ */
+async function getCollection (client, collectionName) {
+  return client.collection(collectionName)
+}
+
+/**
+ * Get collection by name
+ * @param {object} client - ABDB client from getClient()
+ * @param {string} collectionName - Collection name
+ * @returns {Promise<object>} MongoDB-style collection
+ */
+function getCollectionByName (client,collectionName) {
+  return client.collection(collectionName)
+}
+
+/**
+ * Normalize listCollections API response to a Set of collection names.
+ * @param {*} raw
+ * @returns {Set<string>}
+ */
+function collectionNamesFromListResponse (raw) {
+  const out = new Set()
+  if (!raw) return out
+  const visit = (item) => {
+    if (typeof item === 'string') {
+      out.add(item)
+      return
+    }
+    if (item && typeof item === 'object') {
+      const n = item.name ?? item.collectionName
+      if (typeof n === 'string') out.add(n)
+    }
+  }
+  if (Array.isArray(raw)) {
+    raw.forEach(visit)
+    return out
+  }
+  if (typeof raw === 'object') {
+    const nested = raw.collections ?? raw.cursor?.firstBatch ?? raw.data
+    if (Array.isArray(nested)) {
+      nested.forEach(visit)
+    }
+  }
+  return out
+}
+
+/**
+ * Ensure import pipeline collections exist in ABDB (recreate if dropped in console).
+ * Uses listCollections when possible; falls back to createCollection with duplicate tolerance.
+ *
+ * @param {object} client - DbClient from getClient().client
+ * @param {object} [options]
+ * @param {{ info?: function, warn?: function }} [options.logger] - optional aio logger
+ * @returns {Promise<void>}
+ */
+async function ensureImportCollectionsExist (client, options = {}) {
+  const log = options.logger || { info: () => {}, warn: () => {} }
+  let existing = new Set()
+  try {
+    const raw = await client.listCollections({})
+    existing = collectionNamesFromListResponse(raw)
+  } catch (e) {
+    log.warn(`ensureImportCollectionsExist: listCollections failed (${e.message}); attempting createCollection for each pipeline collection`)
+  }
+
+  const created = []
+  for (const name of IMPORT_PIPELINE_COLLECTIONS) {
+    if (existing.has(name)) continue
+    try {
+      await client.createCollection(name)
+      created.push(name)
+    } catch (err) {
+      const m = (err && err.message) ? String(err.message) : String(err)
+      if (/exist|already|duplicate/i.test(m)) {
+        continue
+      }
+      throw err
+    }
+  }
+  if (created.length) {
+    log.info(`ensureImportCollectionsExist: created ABDB collections: ${created.join(', ')}`)
+  }
+}
+
+/**
+ * OAuth Server-to-Server (client_credentials) via @adobe/aio-lib-ims — same pattern as workspace .env OAUTH_*.
+ *
+ * @param {object} params - Must include OAUTH_CLIENT_ID, OAUTH_CLIENT_SECRET, OAUTH_ORG_ID; OAUTH_SCOPES merged with ABDB scopes
+ * @returns {Promise<string|null>} token or null if required params are missing
+ */
+async function fetchImsTokenFromClientCredentials (params = {}) {
+  const clientId = params.OAUTH_CLIENT_ID
+  const clientSecret = params.OAUTH_CLIENT_SECRET
+  const orgId = params.OAUTH_ORG_ID
+  if (isUnsetOauthInput(clientId) || isUnsetOauthInput(clientSecret) || isUnsetOauthInput(orgId)) {
+    return null
+  }
+  const extra = normalizeScopesToArray(params.OAUTH_SCOPES)
+  const scopes = [...new Set([...ABDB_SCOPES, ...extra])]
+  if (scopes.length === 0) {
+    throw new Error('No IMS scopes resolved for ABDB; set OAUTH_SCOPES or rely on default ABDB scopes')
+  }
+  const { Ims } = require('@adobe/aio-lib-ims')
+  const ims = new Ims()
+  const tokenResult = await ims.getAccessTokenByClientCredentials(clientId, clientSecret, orgId, scopes)
+  const token =
+    tokenResult?.access_token?.token ||
+    (typeof tokenResult?.payload?.access_token === 'string' ? tokenResult.payload.access_token : null)
+  if (!token) {
+    throw new Error(
+      `IMS client_credentials failed or returned no token: ${JSON.stringify(tokenResult?.payload || tokenResult)}`
+    )
+  }
+  return token
+}
+
+/**
+ * Resolve IMS bearer token for ABDB.
+ * Order: options.token → params access_token → AIO_DB_IMS_TOKEN → OAUTH_* client_credentials (@adobe/aio-lib-ims) → @adobe/aio-lib-core-auth
+ *
+ * @param {object} params - Runtime action params
+ * @param {object} options - { token?: string }
+ * @returns {Promise<string>}
+ */
+async function resolveImsToken (params = {}, options = {}) {
+  if (options.token != null && String(options.token).trim() !== '') {
+    return String(options.token).trim()
+  }
+  const fromParams = params.access_token || params.ACCESS_TOKEN || params.__oauth?.access_token
+  if (fromParams != null && String(fromParams).trim() !== '') {
+    return String(fromParams).trim()
+  }
+  if (process.env.AIO_DB_IMS_TOKEN != null && String(process.env.AIO_DB_IMS_TOKEN).trim() !== '') {
+    return String(process.env.AIO_DB_IMS_TOKEN).trim()
+  }
+  const fromOAuth = await fetchImsTokenFromClientCredentials(params)
+  if (fromOAuth) {
+    return fromOAuth
+  }
+  let generateAccessTokenFn
+  try {
+    ({ generateAccessToken: generateAccessTokenFn } = require('@adobe/aio-lib-core-auth'))
+  } catch {
+    throw new Error(
+      'ABDB IMS token missing: set OAUTH_CLIENT_ID, OAUTH_CLIENT_SECRET, OAUTH_ORG_ID, OAUTH_SCOPES on the action; ' +
+        'or pass access_token / options.token; or set AIO_DB_IMS_TOKEN; ' +
+        'or install @adobe/aio-lib-core-auth.'
+    )
+  }
+  const tokenResponse = await generateAccessTokenFn(params)
+  return tokenResponse.access_token?.token || tokenResponse.access_token || tokenResponse
+}
+
+/**
+ * Get ABDB client. Requires a valid IMS access token (see resolveImsToken).
+ *
+ * @param {object} params - Action params (for generateAccessToken when package is used)
+ * @param {object} options - { token?: string, region?: string, ow?: { namespace?: string } }
+ * @returns {Promise<{ db: object, client: object, close: () => Promise<void> }>}
+ */
+async function getClientAbdb (params = {}, options = {}) {
+  const token = await resolveImsToken(params, options)
+  const region = options.region || process.env.AIO_DB_REGION || 'amer'
+  const ow = options.ow
+
+  const db = await libDb.init({ token, region, ...(ow ? { ow } : {}) })
+  const client = await db.connect()
+
+  return {
+    db,
+    client,
+    close: async () => client.close()
+  }
+}
+
+/**
+ * Run work with a connected client; always closes the client in finally.
+ *
+ * @param {object} params
+ * @param {(client: object) => Promise<*>} fn
+ * @param {object} [options]
+ * @returns {Promise<*>}
+ */
+async function withDbClient (params, fn, options = {}) {
+  const { client, close } = await getClientAbdb(params, options)
+  try {
+    return await fn(client)
+  } finally {
+    await close()
+  }
+}
+// ——— DbClient (database-level) ———
+
+async function dbStats (client, options = {}) {
+  return client.dbStats(options)
+}
+
+async function orgStats (client, options = {}) {
+  return client.orgStats(options)
+}
+
+async function listCollections (client, filter = {}, options = {}) {
+  return client.listCollections(filter, options)
+}
+
+async function createCollection (client, name, options = {}) {
+  return client.createCollection(name, options)
+}
+
+// ——— DbCollection: writes ———
+
+async function insertOne (client, collectionName, document, options = {}) {
+  return getCollectionByName(client, collectionName).insertOne(document, options)
+}
+
+async function insertMany (client, collectionName, documents, options = {}) {
+  return getCollectionByName(client, collectionName).insertMany(documents, options)
+}
+
+async function updateOne (client, collectionName, filter, update, options = {}) {
+  return getCollectionByName(client, collectionName).updateOne(filter, update, options)
+}
+
+async function updateMany (client, collectionName, filter, update, options = {}) {
+  return getCollectionByName(client, collectionName).updateMany(filter, update, options)
+}
+
+async function replaceOne (client, collectionName, filter, replacement, options = {}) {
+  return getCollectionByName(client, collectionName).replaceOne(filter, replacement, options)
+}
+
+async function deleteOne (client, collectionName, filter, options = {}) {
+  return getCollectionByName(client, collectionName).deleteOne(filter, options)
+}
+
+async function deleteMany (client, collectionName, filter, options = {}) {
+  return getCollectionByName(client, collectionName).deleteMany(filter, options)
+}
+
+async function bulkWrite (client, collectionName, operations, options = {}) {
+  return getCollectionByName(client, collectionName).bulkWrite(operations, options)
+}
+
+async function findOneAndUpdate (client, collectionName, filter, update, options = {}) {
+  return getCollectionByName(client, collectionName).findOneAndUpdate(filter, update, options)
+}
+
+async function findOneAndReplace (client, collectionName, filter, replacement, options = {}) {
+  return getCollectionByName(client, collectionName).findOneAndReplace(filter, replacement, options)
+}
+
+async function findOneAndDelete (client, collectionName, filter, options = {}) {
+  return getCollectionByName(client, collectionName).findOneAndDelete(filter, options)
+}
+
+// ——— DbCollection: reads ———
+
+async function findOne (client, collectionName, filter, options = {}) {
+  return getCollectionByName(client, collectionName).findOne(filter, options)
+}
+
+/** ABDB findOne throws DbError with message "Document not found" when no match — unlike MongoDB null. */
+function isDocumentNotFoundDbError (err) {
+  const msg = err != null && typeof err.message === 'string' ? err.message : ''
+  return err?.name === 'DbError' && msg.includes('Document not found')
+}
+
+/**
+ * Like findOne, but returns null when no document matches (ABDB error → null).
+ *
+ * @returns {Promise<object|null>}
+ */
+async function findOneOrNull (client, collectionName, filter, options = {}) {
+  try {
+    return await findOne(client, collectionName, filter, options)
+  } catch (err) {
+    if (isDocumentNotFoundDbError(err)) {
+      return null
+    }
+    throw err
+  }
+}
+
+/**
+ * @returns {object} FindCursor — await cursor.close() when done (or call client.close()).
+ */
+function find (client, collectionName, filter = {}, options = {}) {
+  return getCollectionByName(client, collectionName).find(filter, options)
+}
+
+async function findArray (client, collectionName, filter = {}, options = {}) {
+  return getCollectionByName(client, collectionName).findArray(filter, options)
+}
+
+/** find() + toArray() with cursor closed after use. */
+async function findToArray (client, collectionName, filter = {}, options = {}) {
+  const cursor = find(client, collectionName, filter, options)
+  try {
+    return await cursor.toArray()
+  } finally {
+    await cursor.close()
+  }
+}
+
+async function countDocuments (client, collectionName, filter = {}, options = {}) {
+  return getCollectionByName(client, collectionName).countDocuments(filter, options)
+}
+
+async function estimatedDocumentCount (client, collectionName, options = {}) {
+  return getCollectionByName(client, collectionName).estimatedDocumentCount(options)
+}
+
+async function distinct (client, collectionName, field, filter = {}, options = {}) {
+  return getCollectionByName(client, collectionName).distinct(field, filter, options)
+}
+
+// ——— aggregate ———
+
+/**
+ * @returns {object} AggregateCursor — close when done.
+ */
+function aggregate (client, collectionName, pipeline = [], options = {}) {
+  return getCollectionByName(client, collectionName).aggregate(pipeline, options)
+}
+
+async function aggregateToArray (client, collectionName, pipeline = [], options = {}) {
+  const cursor = aggregate(client, collectionName, pipeline, options)
+  try {
+    return await cursor.toArray()
+  } finally {
+    await cursor.close()
+  }
+}
+
+// ——— indexes & collection admin ———
+
+async function getIndexes (client, collectionName) {
+  return getCollectionByName(client, collectionName).getIndexes()
+}
+
+async function createIndex (client, collectionName, specification, options = {}) {
+  return getCollectionByName(client, collectionName).createIndex(specification, options)
+}
+
+async function dropIndex (client, collectionName, index, options = {}) {
+  return getCollectionByName(client, collectionName).dropIndex(index, options)
+}
+
+async function collectionStats (client, collectionName, options = {}) {
+  return getCollectionByName(client, collectionName).stats(options)
+}
+
+async function dropCollection (client, collectionName, options = {}) {
+  return getCollectionByName(client, collectionName).drop(options)
+}
+
+async function renameCollection (client, collectionName, newCollectionName, options = {}) {
+  const col = getCollectionByName(client, collectionName)
+  await col.renameCollection(newCollectionName, options)
+  return col
+}
+
+module.exports = {
+  COLLECTION_IMPORT_QUEUE,
+  IMPORT_PIPELINE_COLLECTIONS,
+  getClient,
+  getCollection,
+  ensureImportCollectionsExist,
+  resolveImsToken,
+  getCollectionByName,
+  getClientAbdb,
+  withDbClient,
+  dbStats,
+  orgStats,
+  listCollections,
+  createCollection,
+  insertOne,
+  insertMany,
+  updateOne,
+  updateMany,
+  replaceOne,
+  deleteOne,
+  deleteMany,
+  bulkWrite,
+  findOneAndUpdate,
+  findOneAndReplace,
+  findOneAndDelete,
+  findOne,
+  findOneOrNull,
+  find,
+  findArray,
+  findToArray,
+  countDocuments,
+  estimatedDocumentCount,
+  distinct,
+  aggregate,
+  aggregateToArray,
+  getIndexes,
+  createIndex,
+  dropIndex,
+  collectionStats,
+  dropCollection,
+  renameCollection
+}

package/src/index.js

@@ -0,0 +1,20 @@
+/*
+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 abdbHelper = require('./abdb-helper')
+const abdbConfig = require('./abdb-config')
+const systemConfigShared = require('./system-config-shared')
+const systemConfigCrypto = require('./system-config-crypto')
+const oauth1a = require('./oauth1a')
+
+module.exports = {
+  ...abdbHelper,
+  ...abdbConfig,
+  ...systemConfigShared,
+  ...systemConfigCrypto,
+  ...oauth1a
+}

package/src/oauth1a.js

@@ -0,0 +1,135 @@
+/*
+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
+
+Unless required by applicable law or agreed to in writing, software distributed under
+the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+OF ANY KIND, either express or implied. See the License for the specific language
+governing permissions and limitations under the License.
+*/
+
+const Oauth1a = require('oauth-1.0a')
+const crypto = require('crypto')
+const got = require('got')
+
+function getOauthClient(options, logger) {
+  const instance = {}
+
+  // Remove trailing slash if any
+  const serverUrl = options.url
+  const apiVersion = options.version
+  const oauth = Oauth1a({
+    consumer: {
+      key: options.consumerKey,
+      secret: options.consumerSecret
+    },
+    signature_method: 'HMAC-SHA256',
+    hash_function: hashFunctionSha256
+  })
+  const token = {
+    key: options.accessToken,
+    secret: options.accessTokenSecret
+  }
+  const storeCode = options.storeCode || 'default'
+
+  function hashFunctionSha256(baseString, key) {
+    return crypto.createHmac('sha256', key).update(baseString).digest('base64')
+  }
+
+  async function apiCall(requestData, requestToken = '', customHeaders = {}) {
+    try {
+      const headers = {
+        ...(requestToken
+            ? { Authorization: 'Bearer ' + requestToken }
+            : oauth.toHeader(oauth.authorize(requestData, token))),
+        ...customHeaders
+      }
+
+      // Configure HTTPS options based on environment
+      const httpsOptions = {
+        method: requestData.method,
+        headers,
+        body: requestData.body,
+        responseType: 'json',
+      }
+
+      return await got(requestData.url, httpsOptions).json()
+    } catch (error) {
+      logger.error(error)
+
+      throw error
+    }
+  }
+
+  instance.consumerToken = async function (loginData) {
+    return apiCall({
+      url: createUrl('integration/customer/token', storeCode),
+      method: 'POST',
+      body: loginData
+    })
+  }
+
+  function createUrl (resourceUrl, store) {
+    const s = (store != null && String(store).trim()) ? String(store).trim() : storeCode
+    return serverUrl + s + '/' + apiVersion + '/' + resourceUrl
+  }
+
+  instance.get = async function (resourceUrl, requestToken = '', customHeaders = {}) {
+    const requestData = {
+      url: createUrl(resourceUrl, storeCode),
+      method: 'GET'
+    }
+    return apiCall(requestData, requestToken, customHeaders)
+  }
+
+  instance.post = async function (resourceUrl, data, requestToken = '', customHeaders = {}) {
+    const requestData = {
+      url: createUrl(resourceUrl, storeCode),
+      method: 'POST',
+      body: data
+    }
+    return apiCall(requestData, requestToken, customHeaders)
+  }
+
+  instance.put = async function (resourceUrl, data, requestToken = '', customHeaders = {}) {
+    const requestData = {
+      url: createUrl(resourceUrl, storeCode),
+      method: 'PUT',
+      body: data
+    }
+    return apiCall(requestData, requestToken, customHeaders)
+  }
+
+  instance.delete = async function (resourceUrl, requestToken = '', customHeaders = {}) {
+    const requestData = {
+      url: createUrl(resourceUrl, storeCode),
+      method: 'DELETE'
+    }
+    return apiCall(requestData, requestToken, customHeaders)
+  }
+
+  instance.deleteWithBody = async function (resourceUrl, data, requestToken = '', customHeaders = {}) {
+    const requestData = {
+      url: createUrl(resourceUrl, storeCode),
+      method: 'DELETE',
+      body: data
+    }
+    return apiCall(requestData, requestToken, customHeaders)
+  }
+
+  return instance
+}
+
+function getCommerceOauthClient(options, logger) {
+  options.version = 'V1'
+  const storePrefix = options.storeCode ? `${options.storeCode}/` : ''
+  options.url = options.url + 'rest/' + storePrefix
+  return getOauthClient(options, logger)
+}
+
+module.exports = {
+  getOauthClient,
+  getCommerceOauthClient
+}

package/src/system-config-crypto.js

@@ -0,0 +1,113 @@
+/*
+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
+*/
+
+// Equivalent of Magento's env.php `crypt.key`: a project-wide secret used to
+// derive an AES-256-GCM key that protects sensitive system_config values at
+// rest in App Builder DB (aio-lib-state).
+//
+// Key material is taken from action params/env (never from request payload):
+//   SYSTEM_CONFIG_CRYPT_KEY   – preferred, dedicated secret
+//   OAUTH_CLIENT_SECRET       – fallback, the workspace's client secret
+//
+// Wire format for ciphertext (string):
+//   enc:v1:<base64url(salt)>:<base64url(iv)>:<base64url(tag)>:<base64url(ct)>
+// `v1` lets us rotate the algorithm later without breaking previously stored
+// values. `salt` is per-record so the derived key changes even if the same
+// master secret is reused across records.
+
+const crypto = require('crypto')
+
+const ENC_PREFIX = 'enc:v1:'
+const KEY_BYTES = 32
+const IV_BYTES = 12
+const SALT_BYTES = 16
+const SCRYPT_PARAMS = { N: 16384, r: 8, p: 1 }
+
+function b64uEncode (buf) {
+  return Buffer.from(buf).toString('base64url')
+}
+
+function b64uDecode (str) {
+  return Buffer.from(str, 'base64url')
+}
+
+function resolveMasterSecret (params = {}) {
+  const secret =
+    params.SYSTEM_CONFIG_CRYPT_KEY ||
+    params.OAUTH_CLIENT_SECRET ||
+    process.env.SYSTEM_CONFIG_CRYPT_KEY ||
+    process.env.OAUTH_CLIENT_SECRET ||
+    ''
+  if (!secret || typeof secret !== 'string' || secret.length < 8) {
+    throw new Error(
+      'Encryption key not configured: set SYSTEM_CONFIG_CRYPT_KEY or OAUTH_CLIENT_SECRET'
+    )
+  }
+  return secret
+}
+
+function deriveKey (masterSecret, salt) {
+  return crypto.scryptSync(masterSecret, salt, KEY_BYTES, SCRYPT_PARAMS)
+}
+
+function isEncrypted (value) {
+  return typeof value === 'string' && value.startsWith(ENC_PREFIX)
+}
+
+function encrypt (plaintext, params) {
+  if (plaintext == null || plaintext === '') {
+    return plaintext
+  }
+  const text = typeof plaintext === 'string' ? plaintext : String(plaintext)
+  const secret = resolveMasterSecret(params)
+  const salt = crypto.randomBytes(SALT_BYTES)
+  const iv = crypto.randomBytes(IV_BYTES)
+  const key = deriveKey(secret, salt)
+  const cipher = crypto.createCipheriv('aes-256-gcm', key, iv)
+  const ct = Buffer.concat([cipher.update(text, 'utf8'), cipher.final()])
+  const tag = cipher.getAuthTag()
+  return [
+    ENC_PREFIX,
+    b64uEncode(salt),
+    ':',
+    b64uEncode(iv),
+    ':',
+    b64uEncode(tag),
+    ':',
+    b64uEncode(ct)
+  ].join('')
+}
+
+function decrypt (encrypted, params) {
+  if (!isEncrypted(encrypted)) {
+    return encrypted
+  }
+  const body = encrypted.slice(ENC_PREFIX.length)
+  const parts = body.split(':')
+  if (parts.length !== 4) {
+    throw new Error('Malformed encrypted value')
+  }
+  const [saltB64, ivB64, tagB64, ctB64] = parts
+  const secret = resolveMasterSecret(params)
+  const salt = b64uDecode(saltB64)
+  const iv = b64uDecode(ivB64)
+  const tag = b64uDecode(tagB64)
+  const ct = b64uDecode(ctB64)
+  const key = deriveKey(secret, salt)
+  const decipher = crypto.createDecipheriv('aes-256-gcm', key, iv)
+  decipher.setAuthTag(tag)
+  const pt = Buffer.concat([decipher.update(ct), decipher.final()])
+  return pt.toString('utf8')
+}
+
+module.exports = {
+  ENC_PREFIX,
+  isEncrypted,
+  encrypt,
+  decrypt,
+  resolveMasterSecret
+}

package/src/system-config-shared.js

@@ -0,0 +1,89 @@
+/*
+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
+*/
+
+// Mirrors Magento's core_config_data: (scope, scope_id, path, value).
+// aio-lib-state keys allow [a-zA-Z0-9_-] only, so we encode
+//   scope=`default` scopeId=0  path=`web/secure/base_url`
+// as the state key
+//   sysconfig__default__0__web__secure__base_url
+
+const STATE_KEY_PREFIX = 'sysconfig__'
+const SCOPES = ['default', 'websites', 'stores']
+const PATH_SEGMENT = /^[a-zA-Z0-9_-]+$/
+const SCOPE_ID_RE = /^[a-zA-Z0-9_-]+$/
+const SENSITIVE_PLACEHOLDER = '__SENSITIVE_UNCHANGED__'
+const USE_DEFAULT_SENTINEL = '__USE_DEFAULT__'
+
+function isValidPath (path) {
+  if (typeof path !== 'string') return false
+  const parts = path.split('/')
+  if (parts.length !== 3) return false
+  return parts.every((p) => PATH_SEGMENT.test(p))
+}
+
+function normalizeScope (scope) {
+  if (!scope) return 'default'
+  if (!SCOPES.includes(scope)) {
+    throw new Error(`Invalid scope "${scope}". Expected one of: ${SCOPES.join(', ')}`)
+  }
+  return scope
+}
+
+function normalizeScopeId (scope, scopeId) {
+  if (scope === 'default') return '0'
+  const id = String(scopeId ?? '').trim()
+  if (!id || !SCOPE_ID_RE.test(id)) {
+    throw new Error(`Invalid scopeId "${scopeId}" for scope "${scope}"`)
+  }
+  return id
+}
+
+function toStateKey (scope, scopeId, path) {
+  if (!isValidPath(path)) {
+    throw new Error(`Invalid config path: ${path}`)
+  }
+  const s = normalizeScope(scope)
+  const sid = normalizeScopeId(s, scopeId)
+  return [STATE_KEY_PREFIX, s, '__', sid, '__', path.split('/').join('__')].join('')
+}
+
+/**
+ * Magento-style fallback chain. When reading at store scope we look up:
+ *   stores:<storeId>  →  websites:<websiteId>  →  default:0
+ * `parentWebsiteId` is supplied by the caller (resolved from /rest/V1/store/storeViews).
+ */
+function buildInheritanceChain (scope, scopeId, parentWebsiteId) {
+  const s = normalizeScope(scope)
+  if (s === 'default') {
+    return [{ scope: 'default', scopeId: '0' }]
+  }
+  if (s === 'websites') {
+    return [
+      { scope: 'websites', scopeId: normalizeScopeId('websites', scopeId) },
+      { scope: 'default', scopeId: '0' }
+    ]
+  }
+  // stores
+  const chain = [{ scope: 'stores', scopeId: normalizeScopeId('stores', scopeId) }]
+  if (parentWebsiteId !== undefined && parentWebsiteId !== null && String(parentWebsiteId) !== '') {
+    chain.push({ scope: 'websites', scopeId: normalizeScopeId('websites', parentWebsiteId) })
+  }
+  chain.push({ scope: 'default', scopeId: '0' })
+  return chain
+}
+
+module.exports = {
+  STATE_KEY_PREFIX,
+  SCOPES,
+  SENSITIVE_PLACEHOLDER,
+  USE_DEFAULT_SENTINEL,
+  isValidPath,
+  normalizeScope,
+  normalizeScopeId,
+  toStateKey,
+  buildInheritanceChain
+}