@adobe/aio-lib-db 0.1.0-beta.6 → 0.2.0-beta.1

package/README.md

@@ -22,21 +22,47 @@ npm install @adobe/aio-lib-db
 
 **aio-lib-db** must be initialized in the region the workspace database was provisioned. Otherwise, the connection will fail.  To explicitly initialize the library in a specific region, pass the `{region: "<region>"}` argument to the `libDb.init()` method. Called with no arguments, `libDb.init()` will initialize the library either in the default `amer` region or in the region defined in the `AIO_DB_REGION` environment variable.
 
+**aio-lib-db** requires an IMS access token for authentication. Generate the token using `@adobe/aio-sdk` and pass the `{token : "<token>"}` argument to the `libDb.init()` method.
+
+```bash
+npm install @adobe/aio-sdk --save
+```
+
+To Add IMS credentials in your Runtime action parameter, set the action annotation `include-ims-credentials: true` in AIO App `app.config.yaml` file.
+
+```yaml
+actions:
+  action:
+    function: actions/generic/action.js
+    annotations:
+      include-ims-credentials: true
+      require-adobe-auth: true
+      final: true
+```
+
+> [!IMPORTANT]
+> Add **App Builder Data Services** to your project to add the required database scopes (`adobeio.abdata.write`, `adobeio.abdata.read`, `adobeio.abdata.manage`). (See [APIs and Services](https://developer.adobe.com/developer-console/docs/guides/apis-and-services) in the [Getting Started with Database Storage](https://developer.adobe.com/app-builder/docs/guides/app_builder_guides/storage/database) guide for details.)
+
 ### Basic Usage
 
 ```javascript
+const { generateAccessToken } = require('@adobe/aio-sdk').Core.AuthClient;
 const libDb = require('@adobe/aio-lib-db');
 
-async function main() {
+// Runtime action params
+async function main(params) {
   let client;
   try {
-    // initialize library with the default amer region or what is defined in AIO_DB_REGION
-    const db = await libDb.init();
+    // Generate access token
+    const token = await generateAccessToken(params);
 
-    // initialize library with an explicit region
-    // const db = await libDb.init({region: "emea"});
+    // Initialize library with token
+    const db = await libDb.init({ token: token });
 
-    // connect to the database
+    // or with explicit region, the default being amer or whatever is defined in AIO_DB_REGION
+    // const db = await libDb.init({ token: token, region: 'emea' });
+
+    // Connect to the database
     client = await db.connect();
 
     // Get a collection
@@ -277,21 +303,54 @@ const cursor = collection.aggregate()
 
 ### Storage Statics
 
+#### Individual database statistics:
+
 ```javascript
-// Get storage statistics for the database
+// Get storage statistics for the database with the default scale factor (bytes)
 const dbStats = client.dbStats()
+
+// Get storage statistics for the database with a scale factor (e.g. KB)
+const dbStatsKb = client.dbStats({ scale: 1024 })
+```
+| field returned | description                                                                                     |
+|----------------|-------------------------------------------------------------------------------------------------|
+| collections    | the number of collections                                                                       |
+| objects        | the number of objects/documents                                                                 |
+| views          | the number of views (not currently supported)                                                   |
+| indexes        | the number of indexes                                                                           |
+| dataSize       | the actual amount of storage used (default bytes)                                               |
+| storageSize    | space allocated for storage (default bytes)                                                     |
+| indexSize      | space allocated for indexes (default bytes)                                                     |
+| ok             | whether the request was successful                                                              |
+| scaleFactor    | the scale factor used for the size fields, ex: 1024 for kilobyte-scale (default is 1 for bytes) |
+| lastUpdated    | when the statistics were last updated                                                           |
+
+#### Organization storage statistics:
+
+```javascript
+// Get combined storage statistics across databases in the organization with the default scale factor (bytes)
+const orgStats = client.orgStats()
+
+// Get combined storage statistics across databases in the organization with a scale factor (e.g. MB)
+const orgStatsMb = client.orgStats({ scale: 1024 * 1024 })
 ```
-| field returned | description                                   |
-|----------------|-----------------------------------------------|
-| collections    | the number of collections                     |
-| objects        | the number of objects/documents               |
-| views          | the number of views (not currently supported) |
-| indexes        | the number of indexes                         |
-| dataSize       | the actual amount of storage used in bytes    |
-| storageSize    | space allocated for storage in bytes          |
-| indexSize      | space allocated for indexes in bytes          |
-| ok             | whether the request was successful            |
-| lastUpdated    | when the statistics where last updated        |
+| field returned            | description                                                                                                                |
+|---------------------------|----------------------------------------------------------------------------------------------------------------------------|
+| ok                        | whether the request was successful                                                                                         |
+| databases                 | the number of databases in the organization                                                                                |
+| collections               | the total number of collections across databases                                                                           |
+| dataSize                  | the total actual amount of storage used across databases (default bytes)                                                   |
+| storageSize               | space allocated for storage (default bytes)                                                                                |
+| indexSize                 | space allocated for indexes (default bytes)                                                                                |
+| scaleFactor               | the scale factor used for the size fields, ex: 1024 for kilobyte-scale (default is 1 for bytes)                            |
+| databaseStats             | an array of statistics for individual databases in the organization                                                        |
+| databaseStats.namespace   | the runtime namespace the database corresponds to                                                                          |
+| databaseStats.dataSize    | the actual amount of storage used by the database (default bytes)                                                          |
+| databaseStats.storageSize | space allocated for storage for the database (default bytes)                                                               |
+| databaseStats.indexSize   | space allocated for indexes for the database (default bytes)                                                               |
+| databaseStats.collections | the number of collections in the database                                                                                  |
+| databaseStats.scaleFactor | the scale factor used for the size fields in the databaseStats array, ex: 1024 for kilobyte-scale (default is 1 for bytes) |
+| databaseStats.lastUpdated | when the database statistics were last updated                                                                             |
 
 ### Indexing
 

package/lib/DbBase.js

@@ -24,23 +24,21 @@ class DbBase {
   /**
    * @param {string} region
    * @param {string} runtimeNamespace
-   * @param {string} runtimeAuth
+   * @param {string} token
    * @hideconstructor
    */
-  constructor(region, runtimeNamespace, runtimeAuth) {
-    this.runtimeAuth = runtimeAuth
-    if (!this.runtimeAuth) {
-      throw new DbError('Runtime auth is required')
-    }
-    if (!/.+:.+/.test(this.runtimeAuth)) {
-      throw new DbError("Invalid format for runtime auth, must be '<user>:<pass>'")
-    }
+  constructor(region, runtimeNamespace, token) {
 
     this.runtimeNamespace = runtimeNamespace
     if (!this.runtimeNamespace) {
       throw new DbError('Runtime namespace is required')
     }
 
+    this.accessToken = token
+    if (!this.accessToken) {
+      throw new DbError('Ims access token is required')
+    }
+
     this.region = region.toLowerCase()
     const env = process.env.AIO_DB_ENVIRONMENT || getCliEnv()
     const validRegions = ALLOWED_REGIONS[env]
@@ -78,16 +76,15 @@ class DbBase {
    *
    * @static
    * @constructs
-   * @param {Object=} config
+   * @param {Object} config
    * @param {string=} config.namespace required here or as __OW_API_NAMESPACE in .env
-   * @param {string=} config.apikey required here or as __OW_API_KEY in .env
    * @param {string=} config.region optional, default is 'amer'. Allowed prod values are 'amer', 'emea', 'apac', 'aus'
+   * @param {string} config.token required to be passed here for Ims authentication
    * @returns {Promise<DbBase>} a new DbBase instance
    * @memberof DbBase
    */
-  static async init(config = {}) {
+  static async init(config) {
     const namespace = config.namespace || process.env.__OW_NAMESPACE
-    const apikey = config.apikey || process.env.__OW_API_KEY
     let aioAppRegion = null
 
     try {
@@ -97,7 +94,8 @@ class DbBase {
     }
 
     const region = aioAppRegion || config.region || ALLOWED_REGIONS[getCliEnv()].at(0)
-    return new DbBase(region, namespace, apikey)
+    const token = config.token
+    return new DbBase(region, namespace, token)
   }
 
   /**

package/lib/DbClient.js

@@ -9,7 +9,7 @@ the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTA
 OF ANY KIND, either express or implied. See the License for the specific language
 governing permissions and limitations under the License.
 */
-const { dbStatsApi, listCollectionsApi, createCollectionApi } = require('./api/client')
+const { dbStatsApi, listCollectionsApi, createCollectionApi, orgStatsApi } = require('./api/client')
 const DbCollection = require('./DbCollection')
 
 class DbClient {
@@ -37,11 +37,23 @@ class DbClient {
   /**
    * Get the statistics for the scoped database
    *
+   * @param {Object=} options
+   * @returns {Promise<Object>}
+   * @throws {DbError}
+   */
+  async dbStats(options = {}) {
+    return dbStatsApi(this.db, options)
+  }
+
+  /**
+   * Gets the combined statistics for all databases that fall under the same organization as the scoped database
+   *
+   * @param {Object=} options
    * @returns {Promise<Object>}
    * @throws {DbError}
    */
-  async dbStats() {
-    return dbStatsApi(this.db)
+  async orgStats(options = {}) {
+    return orgStatsApi(this.db, options)
   }
 
   /**

package/lib/api/client.js

@@ -43,11 +43,24 @@ async function getClientApi(db, endpoint) {
  * Gets the statistics for the scoped database
  *
  * @param {DbBase} db
+ * @param {Object=} options
+ * @returns {Promise<Object>}
+ * @throws {DbError}
+ */
+async function dbStats(db, options = {}) {
+  return await postClientApi(db, 'dbStats', undefined, options)
+}
+
+/**
+ * Gets the combined statistics for all databases that fall under the same organization as the scoped database
+ *
+ * @param {DbBase} db
+ * @param {Object=} options
  * @returns {Promise<Object>}
  * @throws {DbError}
  */
-async function dbStats(db) {
-  return await getClientApi(db, 'dbStats')
+async function orgStats(db, options = {}) {
+  return await postClientApi(db, 'orgStats', undefined, options)
 }
 
 /**
@@ -90,6 +103,7 @@ async function close(db, axiosClient) {
 
 module.exports = {
   dbStatsApi: dbStats,
+  orgStatsApi: orgStats,
   closeApi: close,
   createCollectionApi: createCollection,
   listCollectionsApi: listCollections

package/lib/constants.js

@@ -13,6 +13,8 @@ require('dotenv/config')
 
 const RUNTIME_HEADER = 'x-runtime-namespace'
 const REQUEST_ID_HEADER = 'x-request-id'
+const IMS_AUTHORIZATION_HEADER = 'Authorization'
+const IMS_AUTHORIZATION_HEADER_PREFIX = 'Bearer '
 
 const CURSOR_INIT_ERR_MESSAGE = 'Cursor has already been initialized, cannot modify request.'
 
@@ -34,6 +36,8 @@ const PROD_ENDPOINT_EXTERNAL = 'https://storage-database-<region>.app-builder.ad
 module.exports = {
   RUNTIME_HEADER,
   REQUEST_ID_HEADER,
+  IMS_AUTHORIZATION_HEADER,
+  IMS_AUTHORIZATION_HEADER_PREFIX,
   CURSOR_INIT_ERR_MESSAGE,
   PROD_ENV,
   STAGE_ENV,

package/lib/init.js

@@ -18,18 +18,18 @@ require('dotenv/config')
  * Initializes and returns the ADP Storage Database SDK.
  *
  * To use the SDK you must either provide your OpenWhisk credentials in `config.ow` or in the environment variables
- * `__OW_NAMESPACE` and `__OW_API_KEY`.
+ * `__OW_NAMESPACE`.
  *
- * @param {Object=} [config] used to init the sdk
+ * @param {Object} config used to init the sdk
  * @param {('amer'|'apac'|'emea'|'aus')=} [config.region] optional region to use, default: `amer`
  * @param {Object=} [config.ow] Set those if you want to use ootb credentials to access the database service
  * @param {string=} [config.ow.namespace]
- * @param {string=} [config.ow.auth]
+ * @param {string} config.token Ims acccess token required here to authenticate
  * @returns {Promise<DbBase>} A DbBase instance
  */
-async function init (config = {}) {
-  const { auth: apikey, namespace } = (config.ow ?? {})
-  return DbBase.init({ apikey, namespace, region: config.region })
+async function init (config) {
+  const { namespace } = (config.ow ?? {})
+  return DbBase.init({ namespace, region: config.region, token: config.token })
 }
 
 module.exports = { init }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/aio-lib-db",
-  "version": "0.1.0-beta.6",
+  "version": "0.2.0-beta.1",
   "description": "An abstraction on top of Document DB storage",
   "main": "index.js",
   "scripts": {
@@ -26,7 +26,7 @@
     "tough-cookie": "^5.1.2"
   },
   "devDependencies": {
-    "jest": "^29.7.0",
+    "jest": "^30.2.0",
     "uuid": "^11.1.0"
   },
   "keywords": [

package/utils/apiRequest.js

@@ -9,7 +9,7 @@ the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTA
 OF ANY KIND, either express or implied. See the License for the specific language
 governing permissions and limitations under the License.
 */
-const { RUNTIME_HEADER, REQUEST_ID_HEADER } = require('../lib/constants')
+const { RUNTIME_HEADER, REQUEST_ID_HEADER, IMS_AUTHORIZATION_HEADER, IMS_AUTHORIZATION_HEADER_PREFIX } = require('../lib/constants')
 const DbError = require('../lib/DbError')
 const { EJSON } = require("bson")
 
@@ -60,15 +60,10 @@ async function apiRequest(db, axiosClient, apiPath, method, body = {}) {
   const fullUrl = `${db.serviceUrl}/${apiPath}`
   let res
   try {
-    const creds = db.runtimeAuth.split(/:(.*)/,2)
     /** @type {Object}
      * @mixes AxiosRequestConfig */
     const reqConfig = {
-      headers: { [RUNTIME_HEADER]: db.runtimeNamespace },
-      auth: {
-        username: creds[0],
-        password: creds[1]
-      }
+      headers: { [RUNTIME_HEADER]: db.runtimeNamespace, [IMS_AUTHORIZATION_HEADER]: IMS_AUTHORIZATION_HEADER_PREFIX + db.accessToken }
     }
     if (method === 'GET') {
       res = await axiosClient.get(fullUrl, reqConfig)