{"id":21835729,"url":"https://github.com/vtex/io-clients","last_synced_at":"2025-04-14T09:14:50.665Z","repository":{"id":40423913,"uuid":"288813889","full_name":"vtex/io-clients","owner":"vtex","description":null,"archived":false,"fork":false,"pushed_at":"2023-12-28T19:05:46.000Z","size":1565,"stargazers_count":28,"open_issues_count":5,"forks_count":19,"subscribers_count":21,"default_branch":"master","last_synced_at":"2025-04-14T09:14:44.078Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vtex.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-08-19T18:59:36.000Z","updated_at":"2024-11-28T20:18:58.000Z","dependencies_parsed_at":"2024-06-18T18:24:14.788Z","dependency_job_id":"d88e470f-5f96-4af2-84da-33e1cf72e91c","html_url":"https://github.com/vtex/io-clients","commit_stats":null,"previous_names":[],"tags_count":60,"template":false,"template_full_name":"tiagonapoli/node-package-boilerplate","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vtex%2Fio-clients","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vtex%2Fio-clients/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vtex%2Fio-clients/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vtex%2Fio-clients/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vtex","download_url":"https://codeload.github.com/vtex/io-clients/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248852183,"owners_count":21171842,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-27T20:24:00.419Z","updated_at":"2025-04-14T09:14:50.629Z","avatar_url":"https://github.com/vtex.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003e\n VTEX IO Clients\n\u003c/h1\u003e\n\u003ch5 align=\"center\"\u003eCollection of \u003ci\u003eready-to-use\u003c/i\u003e VTEX IO Clients to access VTEX APIs\u003c/h5\u003e\n\nThis exports **Clients**, **Client Factories** and Typescript **typings** to help you connecting a VTEX IO application with VTEX Core Commerce modules on Node.js services.\n\n## Installing\n\n```\nyarn add @vtex/clients\n```\n\n## Available Clients\n\n| **Client Name** | **Implemented Methods** | Observations |\n| ------------------ | --------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| Affiliate | `registerAffiliate`, `changeNotification`, `createSeller`, `getSellerList` | - |\n| Catalog | `getProductsAndSkus`, `getSkuById`, `changeNotification`, `createSeller`, `getSellerList`, `getSellerById`, `getSkuContext`, `getCategoryById`, `getBrandById` | - |\n| Checkout | `getOrderFormConfiguration`, `setOrderFormConfiguration`, `setSingleCustomData` | - |\n| Logistics | `getDockById`, `pickupById`, `listPickupPoints`, `nearPickupPoints`, `shipping`, `listInventoryBySku` | - |\n| OMS | `listOrders`, `userLastOrder`, `order`, `orderNotification`, `cancelOrder` | - |\n| 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). |\n| Rates and Benefits | `getAllBenefits`, `getPromotionById`, `createOrUpdatePromotion`, `createMultipleSkuPromotion`, `updateMultipleSkuPromotion` | Uses ADMIN_TOKEN as authMethod by default. |\n| Suggestions | `getAllSuggestions`, `getSuggestionById`, `sendSkuSuggestion`, `deleteSkuSuggestion`, `getAllVersions`, `getVersionById` | - |\n\n## Available Factories\n\n| **Factory** | **Implemented Methods** | Observations |\n| ----------- | ------------------------------------------------------------------------ | ---------------------------------------- |\n| Master Data | `get`, `save`, `update`, `saveOrUpdate`, `saveOrUpdatePartial`, `delete`, `search`, `searchRaw`, `scroll` | Use the `masterDataFor` helper function. |\n| VBase | `get`, `getRaw`, `getWithMetadata`, `save`, `trySaveIfhashMatches` | Use the `vbaseFor` helper function. |\n\n---\n\n\u003e Note: Some of the methods might need some policies to be inserted on your application's `manifest.json` file.\n\n\u003e 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\u003cMyBookType\u003e('books', undefined, 2))\n\n## How to use\n\n1. Install this package on the `node/` folder of your VTEX IO app:\n ```\n yarn add @vtex/clients\n ```\n\n### Clients\n\n1. Import the individual Client on your app's Clients configuration (`node/clients/index.ts`):\n ```typescript\n import { Catalog } from '@vtex/clients'\n ```\n2. Add a new getter on the `Clients` class with the imported Client:\n ```typescript\n public get catalog() {\n return this.getOrSet('catalog', Catalog)\n }\n ```\n3. Now, you can use the available client's on the app's _resolver functions_!\n ```typescript\n ctx.clients.catalog.getSkuById(...)\n ```\n\n### Factories\n\n1. Import the helper method for the Factory you want to use:\n\n```typescript\n import { masterDataFor, vbaseFor } from '@vtex/clients\n```\n\n2. Following the instructions for each factory, use its method to create a Client class.\n\n```typescript\nconst BooksClient = masterDataFor\u003cMyBookType\u003e('books')\nconst ContractsClient = vbaseFor\u003cstring, MyContractType\u003e('contracts')\n\n// Optional - Export the type to be able to use it as a type parameter\nexport type ContractsClient = InstanceType\u003ctypeof Contracts\u003e\n```\n\n\u003e 🚨 Warning: If you are NOT using the version 1.x of Masterdata builder, you should call masterDataFor passing the major version being used as the third parameter ```masterDataFor\u003cMyBookType\u003e('books', undefined, 2)```.\n\n3. Add new getters on the `Clients` class with the created Client:\n\n```typescript\n public get books() {\n return this.getOrSet('books', BooksClient)\n }\n\n public get contracts() {\n return this.getOrSet('contracts', ContractsClient)\n }\n```\n\n4. Now, you can use the client with the provided methods by the Factory on your app's resolvers.\n\n```typescript\nctx.clients.books.save({ name: 'Example Book' })\nctx.clients.contracts.save('example-key', { id: 'example-id' })\n```\n\nFor more information, read [How to use and create Clients on VTEX IO](https://www.notion.so/How-to-use-and-create-Clients-on-VTEX-IO-1dbd20c928c642d0ba059d5efbe7874b).\n\n## Authorization\n\nEvery Client method 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**.\n\nHere are the available options for that parameter:\n| **Option** | **Description** |\n|-------------|--------------------------------------------------|\n| AUTH_TOKEN | Use the current app's token _(default)_ |\n| STORE_TOKEN | Use the current authenticated store user's token |\n| ADMIN_TOKEN | Use the current authenticated admin user's token |\n\n## API Reference\n\nTo discover and learn more about VTEX Core Commerce APIs, read [VTEX Developer Portal](https://developers.vtex.com/reference).\n\n## Contributing\n\nFeel free to **submit new Clients** to this package, as long as they help to connect with VTEX Core Commerce APIs.\n\nIn 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:\n- Guarantee that `@vtex/api` version is the same in both IO service and `@vtex/clients`;\n- Run `yarn \u0026\u0026 yarn install-peers` in package;\n- Run `yarn build \u0026\u0026 yarn unlink \u0026\u0026 yarn link` in package;\n- Delete `node_modules` inside your service application (this step is not obligatory but might fix some issues);\n- You might need to remove the dependency `@vtex/clients` from your service's `package.json` to avoid conflicts;\n- Run `yarn unlink @vtex/clients \u0026\u0026 yarn link @vtex/clients \u0026\u0026 yarn` in your service;\n- Now you can link your service application with `vtex link`.\n\n## Releasing\n\nWe have a Github Action configured to **release the package on NPM for every Release tag** pushed into the repository. So, in order to have this project published:\n\n1. Merge the Pull Request on the main branch, after having your changes approved.\n2. Run `git checkout master \u0026\u0026 git pull` on your local repository.\n3. Use the [releasy](https://www.npmjs.com/package/releasy) tool to push a new release (_e.g_: `releasy minor --stable`).\n4. Check the result of the process on Github checking the status on the latest commit.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvtex%2Fio-clients","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvtex%2Fio-clients","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvtex%2Fio-clients/lists"}