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. |

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('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):

   import { CatalogClient } from '@sdslatam/clients'

2. Add a new getter on the Clients class with the imported Client:

     public get catalogClient() {
       return this.getOrSet('catalogClient', CatalogClient)
     }

3. Now, you can use the available client's on the app's resolver functions!

   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.

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