{"id":22542147,"url":"https://github.com/commercelayer/commercelayer-sdk-utils","last_synced_at":"2025-07-10T19:03:46.186Z","repository":{"id":95989479,"uuid":"452318686","full_name":"commercelayer/commercelayer-sdk-utils","owner":"commercelayer","description":null,"archived":false,"fork":false,"pushed_at":"2025-04-29T15:09:34.000Z","size":923,"stargazers_count":1,"open_issues_count":4,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-06-16T01:20:04.893Z","etag":null,"topics":["commercelayer"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/commercelayer.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","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":"2022-01-26T14:59:52.000Z","updated_at":"2025-04-14T15:43:21.000Z","dependencies_parsed_at":"2024-01-10T17:16:48.834Z","dependency_job_id":"757ccc3e-3904-4387-9c64-2eeaffd538fa","html_url":"https://github.com/commercelayer/commercelayer-sdk-utils","commit_stats":null,"previous_names":[],"tags_count":35,"template":false,"template_full_name":null,"purl":"pkg:github/commercelayer/commercelayer-sdk-utils","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/commercelayer%2Fcommercelayer-sdk-utils","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/commercelayer%2Fcommercelayer-sdk-utils/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/commercelayer%2Fcommercelayer-sdk-utils/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/commercelayer%2Fcommercelayer-sdk-utils/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/commercelayer","download_url":"https://codeload.github.com/commercelayer/commercelayer-sdk-utils/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/commercelayer%2Fcommercelayer-sdk-utils/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264638104,"owners_count":23642109,"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":["commercelayer"],"created_at":"2024-12-07T13:08:41.427Z","updated_at":"2025-07-10T19:03:46.167Z","avatar_url":"https://github.com/commercelayer.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Commerce Layer SDK Utils\n\n[![Version](https://img.shields.io/npm/v/@commercelayer/sdk-utils.svg)](https://npmjs.org/package/@commercelayer/sdk-utils)\n[![Downloads/week](https://img.shields.io/npm/dw/@commercelayer/sdk-utils.svg)](https://npmjs.org/package/@commercelayer/sdk-utils)\n[![License](https://img.shields.io/npm/l/@commercelayer/sdk-utils.svg)](https://github.com/commercelayer/commercelayer-sdk-utils/blob/master/package.json)\n[![semantic-release: angular](https://img.shields.io/badge/semantic--release-angular-e10079?logo=semantic-release)](https://github.com/semantic-release/semantic-release)\n[![Release](https://github.com/commercelayer/commercelayer-sdk-utils/actions/workflows/semantic-release.yml/badge.svg)](https://github.com/commercelayer/commercelayer-sdk-utils/actions/workflows/semantic-release.yml)\n[![CodeQL](https://github.com/commercelayer/commercelayer-cli/actions/workflows/codeql-analysis.yml/badge.svg)](https://github.com/commercelayer/commercelayer-cli/actions/workflows/codeql-analysis.yml)\n[![TypeScript](https://img.shields.io/badge/%3C%2F%3E-TypeScript%205-%230074c1.svg)](https://www.typescriptlang.org/)\n\nA JavaScript Library that makes even more easier to interact with [Commerce Layer API](https://docs.commercelayer.io/developers) using the official [JavaScript SDK](https://github.com/commercelayer/commercelayer-sdk).\n\n## Installation and usage\n\n```ts\nimport CommerceLayer from \"@commercelayer/sdk\"\nimport CommerceLayerUtils, { executeBatch } from '@commercelayer/sdk'\n\nconst cl = CommerceLayer({ organization, accessToken })\nCommerceLayerUtils(cl)\n\nawait executeBatch(batch)\n```\n\n---\n\n## Table of helpers\n\nCommon functions\n\n- [executeBatch](#executebatch) - execute a list of prepared API requests\n- [retrieveAll](#retrieveall) - fetch all existing resources\n- [updateAll](#updateall) - apply changes to a set of resources\n- [deleteAll](#deleteall) - delete a set of resources\n- [retrievePage](#retrievepage) - retrieve a custom page of resources\n\nCleanups\n\n- [splitCleanup](#splitcleanup) - split a large cleanup in multiple small cleanups\n- [executeCleanup](#executecleanup) - split a large cleanup in multiple small cleanups and execute them\n- [cleanupsToBatchTasks](#cleanupstobatchtasks) - translate a list of cleanups in executable batch tasks\n\nExports\n\n- [splitExport](#splitexport) - split a large export in multiple small exports\n- [executeExport](#executeexport) - split a large export in multiple small exports and execute them\n- [exportsToBatchTasks](#exportstobatchtasks) - translate a list of exports in executable batch tasks\n\nImports\n\n- [splitImport](#splitimport) - split a large import in multiple small imports\n- [executeImport](#executeimport) - split a large import in multiple small imports and execute them\n- [importsToBatchTasks](#importstobatchtasks) - translate a list of imports in executable batch tasks\n\nWebhooks\n\n- [denormalizePayload](#denormalizepayload) - parse a webhook payload and transform it in the appropriate SDK object\n\n\n---\n\n### Common functions\n\n##### executeBatch\n\nThis function allows to prepare and then execute a number of API calls without having to worry about current rate limits.\n\n```ts\nfor (const emailAddress of emailList) {\n    const task: Task = {\n      resourceType: \"customers\",\n      operation: \"create\",\n      resource: { email: emailAddress } as CustomerCreate,\n      onSuccess: { callback: sendEmail },\n      onFailure: { errorHandler: handleError }\n    }\n    tasks.push(task)\n  }\n\n  const batch: Batch = {\n    tasks,\n    options: { refreshToken: refreshAccessToken }\n  }\n\n\nawait executeBatch(batch)\n```\n\nIn the example above the `onSuccess` and `onFailure` callbacks have been used to handle the task result in case of success or failure of the execution.\n\nIt's also possible to fill the resource attributes taking values from the result of the previous batch step. In the following example we are updating a resource taking its id from a previous `retrieve` or `create` task:\n\n```ts\nconst task: Task = {\n    resourceType: \"customers\",\n    operation: \"update\",\n    prepareResource: (res: TaskResourceParam, last: TaskResourceResult): TaskResourceParam =\u003e {\n        return {\n          ...res,\n          id: last.id,\n          reference: 'new-reference'\n        }\n      }\n  }\n```\n\n##### retrieveAll\n\nThis function allows to fetch all existing resources of a specific type executing all necessary API requests respecting current API rate limits.\nThe `limit` option can be used to retrieve only a limited number of resources.\n\n```ts\nconst skus = await retrieveAll\u003cSku\u003e('skus', { limit: 100 })\n```\n\n##### updateAll\n\nThis function allows to modify a set of resources of a specific type, using a filter to identify them.\n\n```ts\nconst skuData = { reference_origin: 'legacy-system-0' }\n\nconst filters = { created_at_lt: '2023-01-01' }\n\nconst updateResult = await updateAll('skus', skuData, { filters })\n```\n\n##### deleteAll\n\nThis function allows to delete a set of resources of a specific type, using a filter to identify them.\n\n```ts\n\nconst filters = { created_at_lt: '2023-01-01', reference_origin_eq: 'legacy-system-0' }\n\nconst deleteResult = await deleteAll('skus', { filters })\n```\n\n##### retrievePage\n\nThis function allows to fetch a specific subset of resources defining page attributes that are not permitted by the API and using all the standard common filters.\nAn error will be thrown if the page parameters are not compatible with the number of existing resources.\n\n```ts\n const skus = await retrievePage\u003cSku\u003e('skus', { pageNumber: 16, pageSize: 139, sort: ['code'] })\n```\n\n---\n\n### Cleanups\n\n##### splitCleanup\n\nSplit cleanup in multiple cleanups respecting the maximum limit of resources included\n\n```ts\nconst clp: CleanupCreate = {\n resource_type: 'customers',\n filters: { created_at_gt: '2020-01-01'}\n}\n\nconst splitClp: CleanupCreate[] = await splitCleanup(clp)\n```\n\n##### executeCleanup\n\nSplit cleanup in multiple cleanups respecting the maximum limit of resources included and execute them\n\n```ts\nconst clp: CleanupCreate = {\n resource_type: 'customers',\n filters: { created_at_gt: '2020-01-01'}\n}\n\nconst execClp: CleanupResult[] = await executeCleanup(clp)\n```\n\n##### cleanupsToBatchTasks\n\nConvert a list of cleanups generated by `splitCleanup` to a list of tasks that can be executed by the function `executeBatch`\n\n\n```ts\nconst clps = await splitCleanup(clp)\n\nconst tasks = cleanupsToBatchTasks(clps)\n```\n\n---\n\n### Exports\n\n##### splitExport\n\nSplit an export in multiple exports respecting the maximum limit of resources included\n\n```ts\nconst exp: ExportCreate = {\n resource_type: 'customers',\n filters: { created_at_gt: '2020-01-01'}\n}\n\nconst splitExp: ExportCreate[] = await splitExport(exp)\n```\n\n##### executeExport\n\nSplit an export in multiple exports respecting the maximum limit of resources included and execute them\n\n```ts\nconst exp: ExportCreate = {\n resource_type: 'customers',\n filters: { created_at_gt: '2020-01-01'}\n}\n\nconst execExp: ExportResult[] = await executeExport(exp)\n```\n\n##### exportsToBatchTasks\n\nConvert a list of exports generated by `splitExport` to a list of tasks that can be executed by the function `executeBatch`\n\n```ts\nconst exps = await splitExport(exp)\n\nconst tasks = exportsToBatchTasks(exps)\n```\n\n---\n\n### Imports\n\n##### splitImport\n\nSplit an import in multiple imports respecting the maximum limit of inputs included\n\n```ts\nconst exp: ImportCreate = {\n resource_type: 'customers',\n inputs: [\n  { ... },\n  { ... },\n  ...\n  { ... }\n ]\n}\n\nconst splitImp: ImportCreate[] = await splitImport(imp)\n```\n\n##### executeImport\n\nSplit an import in multiple imports respecting the maximum limit of inputs included and execute them\n\n```ts\nconst exp: ImportCreate = {\n resource_type: 'customers',\n inputs: [\n  { ... },\n  { ... },\n  ...\n  { ... }\n ]\n}\n\nconst execImp: ImportResult[] = await executeImport(imp)\n```\n\n##### importsToBatchTasks\n\nConvert a list of imports generated by `splitImport` to a list of tasks that can be executed by the function `executeBatch`\n\n\n```ts\nconst imps = await splitImport(imp)\n\nconst tasks = importsToBatchTasks(imps)\n```\n\n---\n\n\n### Webhooks\n\n##### denormalizePayload\n\nThis function takes in input the payload of a webhook in JSON format and transform it in the appropriate typed resource to be used with the official Typescript SDK.\n\n```ts\nconst shipment = denormalizePayload\u003cShipment\u003e(webhookPayload)\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcommercelayer%2Fcommercelayer-sdk-utils","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcommercelayer%2Fcommercelayer-sdk-utils","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcommercelayer%2Fcommercelayer-sdk-utils/lists"}