chore: doc

docs/API.md

@@ -1,28 +1,40 @@
+## Constants
+
+<dl>
+<dt><a href="#createDataAccess">createDataAccess</a> ⇒ <code>object</code></dt>
+<dd><p>Creates a data access object.</p>
+</dd>
+</dl>
+
 ## Functions
 
 <dl>
 <dt><a href="#createClient">createClient(log, dbClient, docClient)</a> ⇒ <code>Object</code></dt>
 <dd><p>Creates a client object for interacting with DynamoDB.</p>
 </dd>
+<dt><a href="#isArray">isArray(value)</a> ⇒ <code>boolean</code></dt>
+<dd><p>Determines if the given parameter is an array.</p>
+</dd>
 <dt><a href="#isBoolean">isBoolean(value)</a> ⇒ <code>boolean</code></dt>
-<dd><p>Determines if the given value is a boolean or a string representation of a boolean.</p>
+<dd><p>Determines case-insensitively if the given value is a boolean or a string
+representation of a boolean.</p>
 </dd>
 <dt><a href="#isInteger">isInteger(value)</a> ⇒ <code>boolean</code></dt>
 <dd><p>Checks if the given value is an integer.</p>
 </dd>
 <dt><a href="#isNumber">isNumber(value)</a> ⇒ <code>boolean</code></dt>
 <dd><p>Determines if the given value is a number.</p>
 </dd>
-<dt><a href="#isObject">isObject(obj)</a> ⇒ <code>boolean</code></dt>
+<dt><a href="#isObject">isObject(value)</a> ⇒ <code>boolean</code></dt>
 <dd><p>Checks if the given parameter is an object and not an array or null.</p>
 </dd>
-<dt><a href="#isString">isString(str)</a> ⇒ <code>boolean</code></dt>
+<dt><a href="#isString">isString(value)</a> ⇒ <code>boolean</code></dt>
 <dd><p>Determines if the given parameter is a string.</p>
 </dd>
 <dt><a href="#hasText">hasText(str)</a> ⇒ <code>boolean</code></dt>
 <dd><p>Checks if the given string is not empty.</p>
 </dd>
-<dt><a href="#isValidDate">isValidDate(obj)</a> ⇒ <code>boolean</code></dt>
+<dt><a href="#isValidDate">isValidDate(value)</a> ⇒ <code>boolean</code></dt>
 <dd><p>Checks whether the given object is a valid JavaScript Date.</p>
 </dd>
 <dt><a href="#isIsoDate">isIsoDate(str)</a> ⇒ <code>boolean</code></dt>
@@ -41,10 +53,22 @@ following UTC time offsets format.</p>
 <dd><p>Converts a given value to a boolean. Throws an error if the value is not a boolean.</p>
 </dd>
 <dt><a href="#arrayEquals">arrayEquals(a, b)</a> ⇒ <code>boolean</code></dt>
-<dd><p>Compares two arrays for equality.</p>
+<dd><p>Compares two arrays for equality. Supports primitive array item types only.</p>
 </dd>
 </dl>
 
+<a name="createDataAccess"></a>
+
+## createDataAccess ⇒ <code>object</code>
+Creates a data access object.
+
+**Kind**: global constant  
+**Returns**: <code>object</code> - data access object  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| log | <code>Logger</code> | logger |
+
 <a name="createClient"></a>
 
 ## createClient(log, dbClient, docClient) ⇒ <code>Object</code>
@@ -57,12 +81,25 @@ Creates a client object for interacting with DynamoDB.
 | --- | --- | --- |
 | log | <code>Object</code> | The logging object, defaults to console. |
 | dbClient | <code>DynamoDB</code> | The AWS SDK DynamoDB client instance. |
-| docClient | <code>DynamoDBDocumentClient</code> | The AWS SDK DynamoDB Document client instance. |
+| docClient | <code>DynamoDBDocument</code> | The AWS SDK DynamoDB Document client instance. |
+
+<a name="isArray"></a>
+
+## isArray(value) ⇒ <code>boolean</code>
+Determines if the given parameter is an array.
+
+**Kind**: global function  
+**Returns**: <code>boolean</code> - True if the parameter is an array, false otherwise.  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| value | <code>\*</code> | The value to check. |
 
 <a name="isBoolean"></a>
 
 ## isBoolean(value) ⇒ <code>boolean</code>
-Determines if the given value is a boolean or a string representation of a boolean.
+Determines case-insensitively if the given value is a boolean or a string
+representation of a boolean.
 
 **Kind**: global function  
 **Returns**: <code>boolean</code> - True if the value is a boolean or a string representation of a boolean.  
@@ -97,27 +134,27 @@ Determines if the given value is a number.
 
 <a name="isObject"></a>
 
-## isObject(obj) ⇒ <code>boolean</code>
+## isObject(value) ⇒ <code>boolean</code>
 Checks if the given parameter is an object and not an array or null.
 
 **Kind**: global function  
 **Returns**: <code>boolean</code> - True if the parameter is an object, false otherwise.  
 
 | Param | Type | Description |
 | --- | --- | --- |
-| obj | <code>\*</code> | The object to check. |
+| value | <code>\*</code> | The value to check. |
 
 <a name="isString"></a>
 
-## isString(str) ⇒ <code>boolean</code>
+## isString(value) ⇒ <code>boolean</code>
 Determines if the given parameter is a string.
 
 **Kind**: global function  
 **Returns**: <code>boolean</code> - True if the parameter is a string, false otherwise.  
 
 | Param | Type | Description |
 | --- | --- | --- |
-| str | <code>\*</code> | The string to check. |
+| value | <code>\*</code> | The value to check. |
 
 <a name="hasText"></a>
 
@@ -133,15 +170,15 @@ Checks if the given string is not empty.
 
 <a name="isValidDate"></a>
 
-## isValidDate(obj) ⇒ <code>boolean</code>
+## isValidDate(value) ⇒ <code>boolean</code>
 Checks whether the given object is a valid JavaScript Date.
 
 **Kind**: global function  
 **Returns**: <code>boolean</code> - True if the given object is a valid Date object, false otherwise.  
 
 | Param | Type | Description |
 | --- | --- | --- |
-| obj | <code>\*</code> | The object to check. |
+| value | <code>\*</code> | The value to check. |
 
 <a name="isIsoDate"></a>
 
@@ -201,7 +238,7 @@ Converts a given value to a boolean. Throws an error if the value is not a boole
 <a name="arrayEquals"></a>
 
 ## arrayEquals(a, b) ⇒ <code>boolean</code>
-Compares two arrays for equality.
+Compares two arrays for equality. Supports primitive array item types only.
 
 **Kind**: global function  
 **Returns**: <code>boolean</code> - True if the arrays are equal, false otherwise.  

packages/spacecat-shared-data-access/README.md

@@ -1,2 +1,80 @@
-# Data Access Module
+# SpaceCat Shared Data Access
 
+This Node.js module, `spacecat-shared-data-access`, is a comprehensive data access layer for managing sites and their audits, leveraging Amazon DynamoDB. It's tailored for the `StarCatalogue` model, ensuring efficient querying and robust data manipulation.
+
+## Installation
+
+```bash
+npm install @adobe/spacecat-shared-data-access
+```
+
+## Entities
+
+### Sites
+- **id** (String): Unique identifier for a site.
+- **baseURL** (String): Base URL of the site.
+- **imsOrgId** (String): Organization ID associated with the site.
+- **createdAt** (String): Timestamp of creation.
+- **updatedAt** (String): Timestamp of the last update.
+- **GSI1PK** (String): Partition key for the Global Secondary Index.
+
+### Audits
+- **siteId** (String): Identifier of the site being audited.
+- **SK** (String): Sort key, typically a composite of audit type and timestamp.
+- **auditedAt** (String): Timestamp of the audit.
+- **auditResult** (Map): Results of the audit.
+- **auditType** (String): Type of the audit.
+- **expiresAt** (Number): Expiry timestamp of the audit.
+- **fullAuditRef** (String): Reference to the full audit details.
+
+## DynamoDB Data Model
+
+The module is designed to work with the following DynamoDB tables:
+
+1. **Sites Table**: Manages site records.
+2. **Audits Table**: Stores audit information for each site.
+3. **Latest Audits Table**: Holds only the latest audit for each site for quick access.
+
+Each table is designed with scalability and efficient querying in mind, utilizing both key and non-key attributes effectively.
+
+For a detailed schema, refer to `docs/schema.json`. This schema is importable to Amazon NoSQL Workbench and used by the integration tests.
+
+## Integration Testing
+
+The module includes comprehensive integration tests embedding a local DynamoDB server with in-memory storage for testing:
+
+```bash
+npm run test:it
+```
+
+These tests create the schema, generate sample data, and test the data access patterns against the local DynamoDB instance.
+
+## Data Access API
+
+The module provides two main DAOs:
+
+### Site Functions
+- `getSites`
+- `getSitesToAudit`
+- `getSitesWithLatestAudit`
+- `getSiteByBaseURL`
+- `getSiteByBaseURLWithAuditInfo`
+- `getSiteByBaseURLWithAudits`
+- `getSiteByBaseURLWithLatestAudit`
+- `addSite`
+- `updateSite`
+
+### Audit Functions
+- `getAuditsForSite`
+- `getAuditForSite`
+- `getLatestAudits`
+- `getLatestAuditForSite`
+- `addAudit`
+
+## Contributing
+
+Contributions to `spacecat-shared-data-access` are welcome. Please adhere to the standard Git workflow and submit pull requests for proposed changes.
+
+## License
+
+Licensed under the Apache-2.0 License.