npm package: @ritani/shopify-ring-builder
Description: Library for building complete rings from shopify diamonds and settings
Author: GuttermanA
Latest version: 1.5.3

## About

This package was built for use in the Ritani Shopify store. It takes 3 from the Shopify GraphQL API: a diamondId, settingId, and a settingVariant. It then fetches those products, processes and combines their data into a new complete ring product.

The goal of this package is to ensure consistency in the ring building process accross all applications. Currently, this package is used in customer ring building, PLA ring building for Google shopping feeds, and the Ring Recommender.

### Built With

This section should list any major frameworks that you built your project using. Leave any add-ons/plugins for the acknowledgements section. Here are a few examples.

* [GraphQL](https://graphql.org/)
* [Shopify GraphQL API](https://shopify.dev/docs/admin-api/graphql/reference)

## Getting Started

To get a local copy up and running follow these simple example steps.

### Prerequisites

Install node 12.x (Erbium)

### Local Installation

1. Clone the repo

```sh
git clone https://github.com/NEWECX/shopify-ring-builder.git
```

2. Install packages

```sh
yarn install
```

3. Create .env and add credentials

```
SHOPIFY_STORE_URL=*your store url*
SHOPIFY_ACCESS_TOKEN=*your shopify api password*
```

## Project Installation

To add the package to another project, run:

```sh
yarn add @ritani/shopify-ring-builder
```

This will also install the [dotenv](https://github.com/motdotla/dotenv) package. Then create a .env file and add the following:

```
SHOPIFY_STORE_URL=*your store url*
SHOPIFY_ACCESS_TOKEN=*your shopify api password*
```

## Usage

There are 2 exposed functions and exposed type definition in this package:

```JS
const { buildRingById, buildRingByJSON, TYPES } = require("@ritani/shopify-ring-builder")
```

### Constant TYPES

This is a set of product type definitions for Shopify. These definitions ensure consistency of product types in any new applications using this package.

```JS
export const CUSTOMER_COMPLETE_RING = "Customer Complete Rings";
export const PLA_EARTH_COMPLETE_RINGS = "PLA Earth Complete Rings";
export const PLA_LAB_COMPLETE_RINGS = "PLA Lab Complete Rings";
export const RING_RECOMMENDER_COMPLETE_RINGS = "Ring Recommender Complete Rings";
export const TEST_COMPLETE_RING = "TEST Complete Ring";
```

To access:

```JS
const { TYPES } = require("@ritani/shopify-ring-builder")
const productType = TYPES.CUSTOMER_COMPLETE_RING
```

### Function buildRingById

This function will get the diamond and setting in the complete ring and generate the complete ring product end to end. The easiet way to build a complete ring.

It accepts an object as an argument:

```ts
buildRingById {
    diamondId!: string;
    settingId!: string;
    settingVariant?: string OR array of string variant options;
    productType!: TYPE;
    additionalInputFields?: object;
    additionalMedia?: array,
}
```

* **diamondId** - Required type of string. In the Shopify GraphQL ID format.
* **settingId** - Required type of string. In the Shopify GraphQL ID format.
* **settingVariant** - Optional type of string OR array of string
  * STRING - In the Shopify GraphQL ID format
  * ARRAY OF STRINGS - Up to 3 variant option string: EX) ```["18kt White Gold", "Cushion"]```
  * If ommited, defaults to first setting variant
* **productType** - Required one of TYPE definitions found in the TYPES section
* **additionalInputFields** - Optional object with shape of [productCreate](https://shopify.dev/docs/admin-api/graphql/reference/mutation/productcreate) in API docs
  * When populated, this will be merged from the complete ring generator functions that combine the selected diamond and setting
* **addtionalMedia** - Optional array of objects with shape of [CreateMediaInput](https://shopify.dev/docs/admin-api/graphql/reference/mutation/input-object/createmediainput)
  * When populated, this will be merged with the media array created by the complete ring generator functions

### Function buildRingByJSON

If you don't need to fetch the diamond and the setting, then use buildRingByJSON.

```ts
buildRingByJSON {
    diamond!: object;
    setting!: object;
    settingVariant?: string OR array of string variant options;
    productType!: TYPE;
    additionalInputFields?: object;
    additionalMedia?: array,
}
```

* **diamond** - Required type of object with shape get GraphQL [query](src/requests/get-product-data/graphql-queries.js) under the diamond namespace
* **setting** - Required type of object with shape get GraphQL [query](src/requests/get-product-data/graphql-queries.js) under the setting namespace
* **settingVariant** - Optional type of string OR array of string
  * STRING - In the Shopify GraphQL ID format
  * ARRAY OF STRINGS - Up to 3 variant option string: EX) ```["18kt White Gold", "Cushion"]```
  * If ommited, defaults to first setting variant* **productType** - Required one of TYPE definitions found in the TYPES section
* **additionalInputFields** - Optional object with shape of [productCreate](https://shopify.dev/docs/admin-api/graphql/reference/mutation/productcreate) in API docs
  * When populated, this will be merged from the complete ring generator functions that combine the selected diamond and setting
* **addtionalMedia** - Optional array of objects with shape of [CreateMediaInput](https://shopify.dev/docs/admin-api/graphql/reference/mutation/input-object/createmediainput)
  * When populated, this will be merged with the media array created by the complete ring generator functions

This function has additional validators that ensure that the input diamond and setting are in the correct shape before the ring is created.