Skip to main content

Client

package:@deity/falcon-commercetools-module

Introduction​

The Commercetools Client ctpClient allows you to connect to the SDK in the name of user or integration. The Commercetools Session ctpSession is used for authentication.

API root​

You can make use of the by Commercetools TypeScript SDK through the apiRoot. Our ctpClient provides two methods to fetch a pre-configured client that can be use to create the apiRoot in which all required authorization and session refreshing are handled:

  • getIntegrationClient() To make requests in the name of the commercetools project, use the getCustomerClient method. This is for all requests where a signed-in user is not required.
  • getCustomerClient() To make requests in name of the customer, use the customerApiRoot.

Authorization​

Requests made to Commercetools API are authenticated through auth middlewares. In our ctpClient the createAuthMiddlewareWithExistingToken middleware is used, where a Bearer token is set to the request header.

Authorization Token​

When you don't need a full apiRoot, but you want access to integration or customer tokens, you can directly request them through the ctpClient:

const integrationToken = await this.ctpClient.getIntegrationToken();
const customerToken = await this.ctpClient.getCustomerToken();
caution

Although you can also access the customerToken directly from the ctpSession, we strongly advice to use the asynchronous method as shown above. Only then you are sure the returned token is validated and refreshed when necessary.

Integration API root​

Scopes​

Our integration client only works correctly if the correct scopes has been assigned to it. Make sure you check the following when generating your accessToken in the Commercetools dashboard:

  • view_project_settings
  • view_categories
  • view_published_products
  • view_products
  • manage_orders
  • manage_payments
  • manage_customers
  • view_customers

Example for fetching and using the integration API root​

@injectable()
class ExampleIntegrationDatasource {
    constructor(@inject('CtpClient') protected ctpClient: CtpClient) {}

    async findById(id: string): Promise<CtpCategory> {
        const integrationApiRoot = createApiBuilderFromCtpClient(await this.ctpClient.integration(), this.config.url);
        const { body: category } = await integrationApiRoot
            .withProjectKey({ projectKey: this.config.projectKey })
            .categories()
            .withId({ ID: id })
            .get()
            .execute();

        return category;
    }
}

Customer API root​

When using this.ctpClient.getCustomerClient() you don't need to worry about refreshing sessions. Our ctpClient will refresh the CtpAuthToken when needed and store fresh token in our session.

Scopes​

When a customer authenticates through our middleware, the following set of scopes will be requested:

  • view_stores
  • view_orders
  • view_payments
  • view_shopping_lists
  • manage_my_profile
  • manage_orders
  • manage_customers
  • manage_my_orders
  • manage_my_payments
  • manage_my_shopping_lists

Example for fetching and using the customer API root​

A cart belongs to a customer, whether this is a signed in customer or a guest filling his cart, we will interact with the API in the same way through the customerApiRoot.

@injectable()
class ExampleCustomerDatasource {
    constructor(@inject('CtpClient') protected ctpClient: CtpClient) {}

    async myCart() {
        const customerApiRoot = createApiBuilderFromCtpClient(await this.ctpClient.getCustomerClient(), this.config.url);
        const { body: cart } = await customerApiRoot
            .withProjectKey({ projectKey: this.config.projectKey })
            .me()
            .activeCart()
            .get()
            .execute();

        return cart;
    }
}