dancecard-email-schemas/README.md

Schemas for objects for Dancecard Email Nurturing System

# Dancecard Email Schemas
NPM Package that defines schemas for objects used in the Dancecard Email/Lead Nurturing API. Allows for validation of objects.


- [Quickstart](#quickstart)
  - [Installation](#installation)
  - [Usage](#usage)
- [Objects](#objects)
  - [Template](#template)
  - [TemplateBlock](#template-block)
    - [TemplateBlockSubtype](#template-block-subtype)
      - [TextBlockSubtype](#text-block-subtype)
      - [CTABlockSubtype](#cta-block-subtype)
      - [VideoBlockSubtype](#video-block-subtype)
      - [GalleryBlockSubtype](#gallery-block-subtype)
      - [FileBlockSubtype](#file-block-subtype)
  - [Token](#token)
  - [Email](#email)
    - [EmailSubtype](#email-subtype)
      - [FirstEmailSubtype](#first-email-subtype)
      - [SingleEmailSubtype](#single-email-subtype)
      - [OptInEmailSubtype](#opt-in-email-subtype)
  - [Program](#program)
  - [Outcome](#outcome)
- [Validation](#validation)
- [Building](#building)


# Quickstart

### Installation
```
npm install dancecard-email-schemas
```

### Usage
```javascript
import {
  Template, TemplateBlock, Token,
  Email, EmailSubtype, Program,
  Outcome
} from dancecard-email-schemas;
```

# Objects

## Template

| property | type | description | required |
|----|---|---|---|
| _id | string | Unique ID generated by database. | yes |
| template_name | string | User provided Template ID/Name | yes |
| template_type | string(enum) | String: either "Email" or "Page Behind" | yes |
| url | string | URL where Jinja email template is stored | yes |
| page_behind | [Template](#template) | Object that denotes the name of the page behind template and its Unique ID generated by database. | yes |
| blocks | Array<[TemplateBlock](#template-block)> | List of all blocks that are in this email. | yes |

## Template Block

Template Block object modeled from the following mockup.
https://projects.invisionapp.com/freehand/document/7DJGRFO3e

| property | type | description | required |
|----|---|---|---|
| block_name | string | User provided Template Block ID/Name | yes |
| block_short_name | string | User provided short version of Template Block ID/Name | yes |
| placeholder | string | Block name used in templates | yes |
| block_type | string(enum) | String: Either "Text", "CTA", "Video", "Gallery", or "File" | yes |
| subtype_fields | [TemplateBlockSubtype](#template-block-subtype) | An object that will contain any custom fields associated with a specific template block subtype | yes |
| order | int | Relative ordering of block in relation to other blocks for this Template. Starts indexing at 0. | yes |

### Template Block Subtype

| property | type | description | required |
|----|---|---|---|
| text_block_fields | [TextBlockSubtype](#text-block-subtype) or **null** | All fields for a Template Block with block_type == "Text" otherwise this property will be **null** | yes |
| cta_block_fields | [CTABlockSubtype](#cta-block-subtype) or **null** | All fields for a Template Block with block_type == "CTA" otherwise this property will be **null** | yes |
| video_block_fields | [VideoBlockSubtype](#video-block-subtype) or **null** | All fields for a Template Block with block_type == "Video" otherwise this property will be **null** | yes |
| gallery_block_fields | [GalleryBlockSubtype](#gallery-block-subtype) or **null** | All fields for a Template Block with block_type == "Gallery" | yes |
| file_block_fields | [FileBlockSubtype](#file-block-subtype) or **null** | All fields for a Template Block with block_type == "File" | yes |

#### Text Block Subtype

| property | type | description | required |
|----|---|---|---|
| formal | string | Formal text sent in an email | yes |
| casual | string | Casual form of text sent in an email | yes |


#### CTA Block Subtype

| property | type | description | required |
|----|---|---|---|

#### Video Block Subtype

| property | type | description | required |
|----|---|---|---|

#### Gallery Block Subtype

| property | type | description | required |
|----|---|---|---|

#### File Block Subtype

| property | type | description | required |
|----|---|---|---|

## Token

| property | type | description | required |
|----|---|---|---|
| _id | string | Unique ID generated by database. | yes |
| token_name | string | User provided Token ID/Name | yes |
| placeholder | string | Token placeholder used in email templates. | yes |
| jinja_placeholder | string | Token placeholder used in the **Jinja** email templates. | yes |
| end_user_visibility | boolean | If true show this token to end users in list of available tokens. If false do not show to end users in their list of available tokens. | yes |
| all_program_visibility | boolean | If true show this token in list of available tokens for all programs. If false this token is to be shown only in the selected programs. | yes |
| programs | Array<[Program](#program)> | List of programs this token is visible for. | yes |

## Email

| property | type | description | required |
|----|---|---|---|
| _id | string | Unique ID generated by database. | yes |
| email_name | string | User provided Template ID/Name. | yes |
| template | [Template](#template) | Template that this Email is using. | yes |
| cta_type | string(enum) | String: either "Gallery", "Video", or "Case Study" | yes |
| cta_override | boolean | TODO: Talk to Colin about this | yes |
| email_type | string(enum) | String: Either "First Email", "2+ Email", "Lifecycle Email", "Single Email", or "Opt-In Email" | yes |
| subtype_fields | [EmailSubtype](#email-subtype) | An object that will contain any custom fields associated with a specific email subtype | yes |
| order | int | Relative ordering of this email versus other emails of the same email_type. For example if there are 8 total emails with 3 "first emails" and 5 "2+ emails" then the 3 first emails will have order ids of 0, 1, 2 and the 2+ emails will have order ids of 0, 1, 2, 3, 4 | yes |


### Email Subtype

| property | type | description | required |
|----|---|---|---|
| first_email_fields | [FirstEmailSubtype](#first-email-subtype) or **null** | All fields for an email with email_type == "First Email" otherwise this property will be **null** | yes |
| single_email_fields | [SingleEmailSubtype](#single-email-subtype) or **null**  | All fields for an email with email_type == "Single Email" otherwise this property will be **null** | yes |
| opt_in_email_fields | [OptInEmailSubtype](#opt-in-email-subtype) or **null** | All fields for an email with email_type == "Opt-In Email" otherwise this property will be **null** | yes |

#### First Email Subtype

| property | type | description | required |
|----|---|---|---|
| outcome | [Outcome](#outcome) | An outcome object that this email is associated with. | yes |

#### Single Email Subtype

| property | type | description | required |
|----|---|---|---|
| subject | string | Subject line for single email. | yes |
| salutation | string | Salutation used for single email. | yes |
| body | string | Body of email used for single email. |
| signature | string | Signature used for single email. | yes |

#### Opt-In Email Subtype

| property | type | description | required |
|----|---|---|---|
| subject | string | Subject line for opt-in email. | yes |
| salutation | string | Salutation used for opt-in email. | yes |
| body | string | Body of email used for opt-in email. | yes |
| signature | string | Signature used for opt-in email. | yes |

## Program

| property | type | description | required |
|----|---|---|---|
| _id | string | Unique ID generated by database. | yes |
| program_name | string | User provided Program ID/Name. | yes |
| created_on | int | Unix timestamp of creation date | yes |
| created_on_friendly | string | MM/DD/YYYY date string of creation date. | yes |
| updated_on | int | Unix timestamp of last update date. | yes |
| updated_on_friendly | string | MM/DD/YYYY date string of last update date. | yes |
| active | boolean | True if this program is active. False if this program is not active. | yes |
| emails | Array<[Email](#email)> | List of all emails in this program. | yes |

## Outcome

These outcomes are setup in Dancecard.

| property | type | description | required |
|----|---|---|---|
| _id | string | Unique ID generated by database for outcome. | yes |
| outcome_name | string | User provided name for outcome. | yes |

# Validation
To validate an object after constructing it you simply need to import the ```EmailSchemasValidator``` object and the associated object schema. Once you have done that you can get a validation object by running the ```validate()``` function of the validator.

Following is an example of constructing and validating a Token object.


```javascript
import { EmailSchemasValidator, Token } from 'dancecard-email-schemas'
let t = {
  _id = "atestid",
  token_name: "A test token",
  placeholder: "test placeholder",
  jinja_placeholder: "{test_token}",
  end_user_visibility: true,
  all_program_visibility: true,
  programs: []
}

console.log(EmailSchemasValidator.validate(t, Token))
```

# Building
```
npm run build
```

# Testing
```
npm run test
```