Commercetools Composable Commerce (Improved) TypeScript SDK client

This is the new and improved Typescript SDK client.

Usage examples

1npm install --save @commercetools/ts-client
2npm install --save @commercetools/platform-sdk
3
4or
5
6yarn add @commercetools/ts-client
7yarn add @commercetools/platform-sdk

1import {
2  type Next,
3  type HttpMiddlewareOptions,
4  type AuthMiddlewareBaseOptions,
5  type ClientRequest,
6  type MiddlewareRequest,
7  type MiddlewareResponse,
8  type Client,
9  createHttpMiddleware,
10  createConcurrentModificationMiddleware,
11  createAuthMiddlewareForClientCredentialsFlow,
12  ClientBuilder,
13} from '@commercetools/ts-client'
14import { createApiBuilderFromCtpClient } from '@commercetools/platform-sdk'
15
16const projectKey = 'mc-project-key'
17const authMiddlewareOptions = {
18  host: 'https://auth.europe-west1.gcp.commercetools.com',
19  projectKey,
20  credentials: {
21    clientId: 'mc-client-id',
22    clientSecret: 'mc-client-secrets',
23  },
24  oauthUri: '/oauth/token', // - optional: custom oauthUri
25  scopes: [`manage_project:${projectKey}`],
26  httpClient: fetch,
27}
28
29const httpMiddlewareOptions = {
30  host: 'https://api.europe-west1.gcp.commercetools.com',
31  httpClient: fetch,
32}
33
34const retryOptions = {
35  maxRetries: 3,
36  retryDelay: 200,
37  backoff: true,
38  retryCodes: [503],
39}
40
41const loggerFn = (response) => {
42  // log response object
43  console.log(response)
44}
45
46// custom middleware
47function middleware(options) {
48  return (next: Next) =>
49    async (request: MiddlewareRequest): Promise<MiddlewareResponse> => {
50      const { response, ...rest } = request
51
52      // other actions can also be carried out here e.g logging,
53      // error handling, injecting custom headers to http requests etc.
54      console.log({ response, rest })
55      return next({ ...request })
56    }
57}
58
59const client: Client = new ClientBuilder()
60  .withPasswordFlow(authMiddlewareOptions)
61  .withLoggerMiddleware({ loggerFn })
62  .withCorrelationIdMiddleware({
63    generate: () => 'fake-correlation-id' + Math.floor(Math.random() + 2),
64  })
65  .withHttpMiddleware(httpMiddlewareOptions)
66  .withMiddleware(middleware({})) // <<<------------------- add the custom middleware here
67  .build()
68
69const apiRoot = createApiBuilderFromCtpClient(client)
70
71// calling the Composable Commerce `api` functions
72// get project details
73apiRoot
74  .withProjectKey({ projectKey })
75  .get()
76  .execute()
77  .then((x) => {
78    /*...*/
79  })
80
81// create a productType
82apiRoot
83  .withProjectKey({ projectKey })
84  .productTypes()
85  .post({
86    body: { name: 'product-type-name', description: 'some description' },
87  })
88  .execute()
89  .then((x) => {
90    /*...*/
91  })
92
93// create a product
94apiRoot
95  .withProjectKey({ projectKey })
96  .products()
97  .post({
98    body: {
99      name: { en: 'our-great-product-name' },
100      productType: {
101        typeId: 'product-type',
102        id: 'some-product-type-id',
103      },
104      slug: { en: 'some-slug' },
105    },
106  })
107  .execute()
108  .then((x) => {
109    /*...*/
110  })

Create a client

To create a client, use the ClientBuilder class. The ClientBuilder class provides a fluent API to configure the client.

1const authMiddlewareOptions = {
2  credentials: {
3    clientId: 'xxx',
4    clientSecret: 'xxx',
5  },
6  host: 'https://auth.europe-west1.gcp.commercetools.com',
7  projectKey: 'xxx',
8}
9
10const httpMiddlewareOptions = {
11  host: 'https://api.europe-west1.gcp.commercetools.com',
12  httpClient: fetch,
13}
14
15const client = new ClientBuilder()
16  .withHttpMiddleware(httpMiddlewareOptions)
17  .withConcurrentModificationMiddleware()
18  .withClientCredentialsFlow(authMiddlewareOptions)
19  .build()

The withMiddleware method can be used to add middleware functions (both built-in and custom middleware) in an ordered fashion.

1// Example
2const authMiddlewareOptions = {
3  credentials: {
4    clientId: 'xxx',
5    clientSecret: 'xxx',
6  },
7  host: 'https://auth.europe-west1.gcp.commercetools.com',
8  projectKey: 'xxx',
9}
10
11const httpMiddlewareOptions = {
12  host: 'https://api.europe-west1.gcp.commercetools.com',
13  httpClient: fetch,
14}
15
16const logger = () => {
17  return (next) => async (request) => {
18    // log request object
19    console.log('Request:', request)
20    const response = await next(request)
21
22    // log response object
23    console.log('Response', response)
24    return response
25  }
26}
27
28const client = new ClientBuilder()
29  .withMiddleware(
30    createAuthMiddlewareForClientCredentialsFlow(authMiddlewareOptions)
31  )
32  .withMiddleware(createHttpMiddleware(httpMiddlewareOptions))
33  .withMiddleware(createConcurrentModificationMiddleware())
34  .withMiddleware(logger())
35  .build()

This will add the middleware in an ordered fashion starting with the:

1. createAuthMiddlewareForClientCredentialsFlow
2. createHttpMiddleware
3. createConcurrentModificationMiddleware
4. logger

Note that when using the withMiddleware function to add a custom middleware along side other in built middleware functions, it will add the custom middleware to the start of the execution chain.

1// Example
2const authMiddlewareOptions = {
3  credentials: {
4    clientId: 'xxx',
5    clientSecret: 'xxx',
6  },
7  host: 'https://auth.europe-west1.gcp.commercetools.com',
8  projectKey: 'xxx',
9}
10
11const httpMiddlewareOptions = {
12  host: 'https://api.europe-west1.gcp.commercetools.com',
13  httpClient: fetch,
14}
15
16const logger = () => {
17  return (next) => async (request) => {
18    // log request object
19    console.log('Request:', request)
20    const response = await next(request)
21
22    // log response object
23    console.log('Response', response)
24    return response
25  }
26}
27
28const client = new ClientBuilder()
29  .withClientCredentialsFlow(authMiddlewareOptions)
30  .withHttpMiddleware(httpMiddlewareOptions)
31  .withConcurrentModificationMiddleware()
32  .withMiddleware(logger())
33  .build()

The order of execution is as follows:

1. withMiddleware <------ the custom middleware
2. withClientCredentialsFlow
3. withHttpMiddleware
4. withConcurrentModificationMiddleware