# CardX Dynamo

CardX DynamoDB Helpers

Utilizes Dynamoose but helps abstract away some of the details for simple use cases.

## Installation

``` bash
npm --save install @cardx/dynamo
```

## Usage

``` javascript
import Dynamo from "@cardx/dynamo";

Dynamo.setLogger(log); // Optionally pass a @cardx/logger object
```

## Table Functions

### ENV-gateway-accounts

#### getGatewayAccount

``` javascript
const settings = await Dynamo.getGatewayAccount(
  account,
  {                          // Additional options
    fields: ["integration"]  // Limit responses to only top-level fields included in list
  }
);
```

#### scanAcquiringSolution

``` javascript
const merchants = await Dynamo.scanAcquiringSolution(
  acquiringSolution,  // E.g., "fiserv"
  // Additional options
  {
    // Limit responses to only top-level fields included in list
    fields: ["account", "merchantIdentifier", "acquiring-solution"],
  }
);
```
#### scanAllGatewayAccounts

``` javascript
const merchants = await Dynamo.scanAllGatewayAccounts(
  // Additional options
  {
    // Limit responses to only top-level fields included in list
    fields: ["account", "merchantIdentifier", "postauth-authority"],
  }
);
```

#### scanMerchantIdentifier

``` javascript
const merchants = await Dynamo.scanMerchantIdentifier(
  merchantIdentifier // eg. 1234567890
);
```

### updateGatewayAccount

``` javascript
await Dynamo.updateGatewayAccount({
  account,
  updateSchema // JS Object of key-value pairs to update
});
```

### ENV-merchant-mail-settings

#### getMailSettings

``` javascript
const settings = await Dynamo.getMailSettings(
  account,
  {                          // Additional options
    fields: ["integration"]  // Limit responses to only top-level fields included in list
  }
);
```

#### updateMailSettings

``` javascript
await Dynamo.updateMailSettings({
  account,
  updateSchema // JS Object of key-value pairs to update
});
```

### ENV-project-settings

#### getProjectSettings

``` javascript
const settings = await Dynamo.getProjectSettings(
  key,
  {                          // Additional options
    fields: [],              // Limit responses to only top-level fields included in list
    project = process.env.CARDX_PROJECT,
    scan: {                  // less-performant tablescan. find row by column value other than primary hash key
      keyName: "merchantIdentifier",
      value: "1234567890"
    }
  }
);
```

#### queryAllProjectSettings

``` javascript
const settings = await Dynamo.queryAllProjectSettings(
  {                             // Additional options
    fields: [],                 // Limit responses to only top-level fields included in list
    includeProjectField: false, // Include the "project" field in the response
    project = process.env.CARDX_PROJECT,
    renameKey = ""              // Allows you to rename the "key" field to something more meaningful
  }
);
```

## Core Functions

Usually not accessed directly but utilized by convenience functions such as `getGatewayAccount`

### get

``` javascript
const results = await Dynamo.get({
  // Required:
  query,               // DynamoDB query; e.g., { account: "cardxdemo" }
  table,               // DynamoDB table; e.g., sbx-pets
  schema,              // SimpleSchema-parsable object

  // Optional:
  fields = undefined,  // Limit responses to only top-level fields included in list, overrides `strict`
  merge = true,        // Merge the defaults provided in the `schema` object into the results
  strict = false       // Do not include fields not present in `schema`
});
```

### query

``` javascript
const results = await Dynamo.query({
  // Required:
  query,               // DynamoDB query; e.g., { account: "cardxdemo" }
  table,               // DynamoDB table; e.g., sbx-pets
  schema,              // SimpleSchema-parsable object

  // Optional:
  fields = undefined,  // Limit responses to only top-level fields included in list, overrides `strict`
  merge = true,        // Merge the defaults provided in the `schema` object into the results
  strict = false       // Do not include fields not present in `schema`
});
```

### scan

``` javascript
const results = await Dynamo.scan({
  // Required:
  scan,                // DynamoDB scan; e.g., { account: "cardxdemo" }
  table,               // DynamoDB table; e.g., sbx-pets
  schema,              // SimpleSchema-parsable object

  // Optional:
  fields = undefined,  // Limit responses to only top-level fields included in list, overrides `strict`
  merge = true,        // Merge the defaults provided in the `schema` object into the results
  strict = false       // Do not include fields not present in `schema`
});
```

### Update Functions

Pass the primary/hash key of the row and a JS Object of key-value pairs to update.
The key-value pairs to update are referred to as the `updateSchema`.
Here are some examples -
Imagine that a dynamo row currently has the following schema

``` json
{
  "color": "purple",
  "details": {
    "SKU": "ABC123",
    "weight": 1.2
  }
}
```

If you want to update the `color` value, and add a new key called `price`, send the following `updateSchema`:

``` javascript
const exampleUpdateSchema1 = {
  "color": "red",
  "price": 120,
};

```

If you want to update a nested key-value, include the nesting in your `updateSchema`. For example, this schema will update the `weight` value inside the `details` object.

``` javascript
const exampleUpdateSchema2 = {
  "details": {
    "weight": 2.5
  }
};
```

### Logging

``` javascript
Dynamo.setLogger(log);  // Optionally pass a @cardx/logger object
```

### SimpleSchema

Usually not accessed directly but utilized by underlying functions

> TODO: documentation needed

``` javascript
const dynamooseSchema = Dynamo.SimpleSchema.parse(simpleSchema)

Dynamo.SimpleSchema.String.HashKey;    // Special field for hash key strings
Dynamo.SimpleSchema.String.RangeKey;   // Special field for range key strings
Dynamo.SimpleSchema.String.Undefined;  // Special field for strings with no default value

Dynamo.SimpleSchema.merge({results, defaults: schema});

Dynamo.SimpleSchema.trim({ schema, fields });
```

## Changelog

* 0.1.0 - A minimum viable product
* 0.2.0 - Adds update functionality
* 0.3.0 - Supports getProjectSettings() (`ENV-project-settings` table)
* 0.4.0 - Adds core query() function, queryAllProjectSettings()
* 0.5.0 - Add core scan() function, scanAcquiringSolution()
* 1.1.0 - Adds getLightboxRequestToken() (updateLightboxRequestTokens() already added in previous version)
* 1.4.6 - Adds "integrations-api" project to -project-settings table

## License

© CardX. All rights reserved.