Commerce Layer SDK Utils

A JavaScript Library that makes even more easier to interact with Commerce Layer API using the official JavaScript SDK.

Installation and usage

import CommerceLayer from "@commercelayer/sdk"
import CommerceLayerUtils, { executeBatch } from '@commercelayer/sdk'

const cl = CommerceLayer({ organization, accessToken })
CommerceLayerUtils(cl)

await executeBatch(batch)

Table of helpers

Common functions

• executeBatch - execute a list of prepared API requests
• retrieveAll - fetch all existing resources
• updateAll - apply changes to a set of resources

Cleanups

• prepareCleanups - split a large cleanup in multiple small cleanups
• cleanupsToBatchTasks - translate a list of cleanups in executable batch tasks

Exports

• prepareExports - split a large export in multiple small exports
• exportsToBatchTasks - translate a list of exports in executable batch tasks

Imports

• prepareImports - split a large import in multiple small imports
• importsToBatchTasks - translate a list of imports in executable batch tasks

Webhooks

• denormalizePayload - parse a webhook payload and transform it in the appropriate SDK object

Common functions

executeBatch

This function allows to prepare and then execute a number of API calls without having to worry about current rate limits.

for (const emailAddress of emailList) {
    const task: Task = {
      resourceType: "customers",
      operation: "create",
      resource: { email: emailAddress } as CustomerCreate,
      onSuccess: { callback: sendEmail },
      onFailure: { errorHandler: handleError }
    }
    tasks.push(task)
  }

  const batch: Batch = {
    tasks,
    options: { refreshToken: refreshAccessToken }
  }


await executeBatch(batch)

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

It'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:

const task: Task = {
    resourceType: "customers",
    operation: "update",
    prepareResource: (res: TaskResourceParam, last: TaskResourceResult): TaskResourceParam => {
        return {
          ...res,
          id: res.id,
          reference: 'new-reference'
        }
      }
  }

retrieveAll

This function allows to fetch all existing resources of a specific type executing all necessary API requests respecting current API rate limits.

const skus = await retrieveAll<Sku>('skus')

updateAll

This function allows to modify a set of resources of a specific type, using a filter to identify them.

const skuData = { reference_origin: 'legacy-system-0' }

const filters = { created_at_lt: '2023-01-01' }

const updateResult = await updateAll('skus', skuData, { filters })

Cleanups

prepareCleanups

Split cleanup in multiple cleanups respecting the maximum limit of resources included

const clp: CleanupCreate = {
 resource_type: 'customers',
 filters: { created_at_gt: '2020-01-01'}
}

const prepClp = await prepareCleanups(clp)

cleanupsToBatchTasks

Convert a list of cleanups generated by prepareCleanups to a list of tasks that can be executed by the function executeBatch

const prepClp = await prepareCleanups(clp)

const tasks = cleanupsToBatchTasks(prepClp)

Exports

prepareExports

Split an export in multiple exports respecting the maximum limit of resources included

const exp: ExportCreate = {
 resource_type: 'customers',
 filters: { created_at_gt: '2020-01-01'}
}

const prepExp = await prepareExports(exp)

exportsToBatchTasks

Convert a list of exports generated by prepareExports to a list of tasks that can be executed by the function executeBatch

const prepExp = await prepareExports(exp)

const tasks = exportsToBatchTasks(prepExp)

Imports

prepareImports

Split an import in multiple imports respecting the maximum limit of inputs included

const exp: ImportCreate = {
 resource_type: 'customers',
 inputs: [
  { ... },
  { ... },
  ...
  { ... }
 ]
}

const prepImp = await prepareImports(imp)

importsToBatchTasks

Convert a list of imports generated by prepareImports to a list of tasks that can be executed by the function executeBatch

const prepImp = await prepareImports(imp)

const tasks = importsToBatchTasks(prepImp)

Webhooks

denormalizePayload

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

const shipment = denormalizePayload<Shipment>(webhookPayload)