updated-new-function

Creating a New namespace tool Function in @commercetools/agent-essentials

This document outlines the steps taken to implement a new function in @commercetools/agent-essentials to connect to commercetools API.

The following steps are defining implementation of an example products.create. So the (namespace) here refers to product.

Implementation Steps

1. Gather info regarding the (namespace)

• Search commercetools docs at https://docs.commercetools.com/api and find the (namespace)
• In this example https://docs.commercetools.com/api/projects/products and ProductDraft

1. Define Parameter Schema

   • Using the namespace fetched in previous step , Created createProductParameters in typescript/src/shared/(namespace)/parameters.ts
   • Used Zod for type validation
   • Included all required and optional fields from ProductDraft
   • Created a separate productVariantDraft schema for reusability

2. Create a base.functions.ts file in the namespace directory. This file will export a couple of basic CRUD functions that will be used inside other files in this namespace. you can extract this base functions from current functions.ts file in the namespace.

   • IMPORTANT: base functions should be generic as possible, e.g. instead of having a separate function for query cart for a specific user and another one for user in a store, we create one that accepts a "where" clause.
   • 3.1: sometimes the commercetools SDK has different endpoint when a parameter is present, like query in store (look to the code sample below). in that case, we check that parameter inside the base function but keep the function as simple as possible and low complexity.
   • 3.2: No delete operation.
   • 3.3: in the base update, call the base get function to fetch the version from the entity and use it in the update call.
   • GOAL: the goal of this step is maximize reusability.
   • example: base functions created for 'cart.read' are: readCartById, readCartByKey, queryCart, queryCarts.
   • file example: typescript/src/shared/cart/base.functions.ts IMPORTANT: functions.ts usually exports 3 functions: read, create and update. If there are more ways to read the entity (by id or key or query), embed all in one "read" exported function and adjust the parameters and prompts as well.