npm package: @sdslatam/clients
Description: <h1 align="center">   SDSLATAM Clients </h1> <h5 align="center">Collection of <i>ready-to-use</i> SDSLATAM Clients to access VTEX APIs</h5>
Latest version: 1.0.5

<h1 align="center">
  SDSLATAM Clients
</h1>
<h5 align="center">Collection of <i>ready-to-use</i> SDSLATAM Clients to access VTEX APIs</h5>

This exports **Clients** and Typescript **typings** to help you connecting a VTEX IO application with VTEX Core Commerce modules on Node.js services.

## Installing

```
yarn add @sdslatam/clients
```

## Available Clients

| **Client Name**     | **Implemented Methods**                                                                                                                                        | Observations                                                                                                                                                                                        |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| CatalogClient       | `getProductsAndSkus`, `getSkuById`, `changeNotification`, `createSeller`, `getSellerList`, `getSellerById`, `getSkuContext`, `getCategoryById`, `getBrandById` | This client is to be used on the current account and all subaccounts without AppKey and AppToken authentication                                                                                     |
| CrossCatalogClient  | `getProductsAndSkus`, `getSkuById`, `changeNotification`, `createSeller`, `getSellerList`, `getSellerById`, `getSkuContext`, `getCategoryById`, `getBrandById` | This client is to be used in another account and require AppKey and AppToken authentication                                                                                                         |
| CheckoutClient      | `getOrderFormConfiguration`, `setOrderFormConfiguration`, `setSingleCustomData`                                                                                | This client is to be used on the current account and all subaccounts without AppKey and AppToken Authentication                                                                                     |
| CrossCheckoutClient | `getOrderFormConfiguration`, `setOrderFormConfiguration`, `setSingleCustomData`                                                                                | This client is to be used in another account and require AppKey and AppToken authentication                                                                                                         |
| OMSClient           | `listOrders`, `userLastOrder`, `getOrdersFromUser`, `getOrders`, `orderNotification`, `cancelOrder`                                                            | This client is to be used on the current account and all subaccounts without AppKey and AppToken Authentication                                                                                     |
| CrossOMSClient      | `listOrders`, `userLastOrder`, `getOrdersFromUser`, `getOrders`, `orderNotification`, `cancelOrder`                                                            | This client is to be used in another account and require AppKey and AppToken authentication                                                                                                         |
| OMS Proxy           | `orders`, `orderFormId`, `customData`, `register`                                                                                                              | You will have to declare a dependency and a policy on your app. You can check out [this document](https://www.notion.so/How-to-use-the-OMS-API-Proxy-application-e82f11ff896247c58a7e2e658d631516). |

---

> Note: Some of the methods might need some policies to be inserted on your application's `manifest.json` file.

> Master Data Builder: There are two versions of Master Data Builder version 1.x and 2.x both can be used. Version 2.x presents a new feature to create schemas more intelligently, avoiding their excessive creation. To use version 2.x, it is important to make this explicit in the app's Manifest and pass the new major parameter in the masterDataFor function (e.g. masterDataFor<MyBookType>('books', undefined, 2))

## How to use

1. Install this package on the `node/` folder of your VTEX IO app:
   ```
   yarn add @sdslatam/clients
   ```

### Clients

1. Import the individual Client on your app's Clients configuration (`node/clients/index.ts`):
   ```typescript
   import { CatalogClient } from '@sdslatam/clients'
   ```
2. Add a new getter on the `Clients` class with the imported Client:
   ```typescript
     public get catalogClient() {
       return this.getOrSet('catalogClient', CatalogClient)
     }
   ```
3. Now, you can use the available client's on the app's _resolver functions_!
   ```typescript
   ctx.clients.catalogClient.getSkuById(...)
   ```

## Authorization

Every Client method excepts CrossClients should accept an option `authMethod` parameter that declares which token will be used on that HTTP call. By default, **the request will use the `authToken` of the app**.

Here are the available options for that parameter:
| **Option** | **Description** |
|-------------|--------------------------------------------------|
| AUTH*TOKEN | Use the current app's token *(default)\_ |
| STORE_TOKEN | Use the current authenticated store user's token |
| ADMIN_TOKEN | Use the current authenticated admin user's token |

## API Reference

To discover and learn more about VTEX Core Commerce APIs, read [VTEX Developer Portal](https://developers.vtex.com/reference).

## Develop

In order to test your new feature or fix using `vtex link` (command used for linking a service application in IO, for example), follow these steps:

- Guarantee that `@vtex/api` version is the same in both IO service and `@sdslatam/clients`;
- Run `yarn && yarn install-peers` in package;
- Run `yarn build && yarn unlink && yarn link` in package;
- Delete `node_modules` inside your service application (this step is not obligatory but might fix some issues);
- Run `yarn unlink @sdslatam/clients && yarn link @sdslatam/clients && yarn` in your repository;
- Make sure to use the same version of **@vtex/api** (6.x) in the target project
- Now you can link your service application with `vtex link`.
- Test and generate a PR to develop.

## Releasing

We have a Bitbucket Pipeline configured to **release the package on NPM for every Release tag** pushed into the repository. So, in order to have this project published:

1. Merge the Pull Request on the **develop branch**, after having your changes **approved**.
2. The pipeline will generate a release branch and publish a beta version in NPM register.
3. Install the beta version with `yarn add @sdslatam/clients@beta`.
4. Test the library.
5. A pipeline with manual step will be generated to publish the stable version to NPM and merge to Main and Develop Branchs.
6. Install the stable version on your project.

**Obs.: Don't forget to unlink the local project with `yarn unlink @sdslatam/clients`**

## 🤝 Colaboradores

Agradecemos às seguintes pessoas que contribuíram para este projeto:

- Gustavo Dinis Viana
- Yuri Silva