Cursor rule

1---
2description: Refactoring a tool Function in @commercetools/agent-essentials
3globs: 
4alwaysApply: false
5---
6# Refactoring a tool Function in @commercetools/agent-essentials
7 
8This document outlines the steps taken to refactor a function in @commercetools/agent-essentials to connect to commercetools API.
9 
10The following steps are defining implementation of an example `cart.read`. So the `(namespace)` here refers to `cart`.
11 
12# NOTES: 
13    1. CRUD functions are read, update and create. do not add delete functions.
14    2. DO NOT MODIFY `parameters.ts` or `prompts.ts` or `tools.ts`
15    3. when creating update base functions, use get (by id or key) base functions to first fetch the entity, and use the version from the fetched entity in the update payload
16 
17# Refactor steps
18 
191. 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.
20    - 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" cluase.
21    - Note: 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.
22    - GOAL: the goal of this step is maximize reusability.
23    - example: base functions created for 'cart.read' are: readCartById, readCartByKey, queryCart, queryCarts.
24    - file example: `typescript/src/shared/cart/base.functions.ts`
25    - code sample:
26 
27```ts
28    const queryCart = async (
29        apiRoot: ApiRoot,
30        projectKey: string,
31        queryArgs: any,
32        storeKey?: string
33        ) => {
34        if (storeKey) {
35            const carts = await apiRoot
36            .withProjectKey({projectKey})
37            .inStoreKeyWithStoreKeyValue({storeKey})
38            .carts()
39            .get({queryArgs})
40            .execute();
41            return carts.body;
42        }
43        const carts = await apiRoot
44            .withProjectKey({projectKey})
45            .carts()
46            .get({queryArgs})
47            .execute();
48        return carts.body;
49        };
50```
51 
522. Create a `customer.functions.ts` in the namespace directory. This file, uses `base.functions.ts`. it has CRUD functions when `context.customerId` is present.
53    - GOAL: these functions are to limit the operations to the specific customerId.
54    - example: when querying carts, it should always inject `context.customerId` to the query. If not possible, it should check the entity after it's fetched.
55    - file example: `typescript/src/shared/cart/customer.functions.ts`
56 
573. Create a `store.functions.ts` in the namespace directory. This file, uses `base.functions.ts`. it has CRUD functions when `context.storeKey` is present.
58    - GOAL: these functions are to limit the operations to the specific store.
59    - example: Limit carts fetched to a store.
60 
614. Create a `admin.functions.ts` in the namespace directory. This file, uses `base.functions.ts`. it has CRUD functions when `context.isAdmin` is present.
62    - GOAL: these functions doesn't have any limitations.
63    - file example: `typescript/src/shared/cart/admin.functions.ts`
64 
655. Modify `functions.ts` to import all exported methods from customer, admin and store. create a method called `contextTo<namespace>FunctionMapping` which accepts the context and returns an object of name to method mapping.
66    - IMPORTANT: if no context is there, empty object should return
67    - IMPORTANT: use type `Context` from `typescript/src/types/configuration.ts`
68    - example: 
69```ts
70    export const contextToCartFunctionMapping = (context?: Context) => {
71        if (context?.customerId) {
72            return {
73            read_cart: customer.readCart,
74            // create_cart: customer.createCart,
75            // update_cart: customer.updateCart,
76            // replicate_cart: customer.replicateCart,
77            };
78        }
79        if (context?.storeKey) {
80            return {
81            read_cart: store.readCart,
82            // create_cart: store.createCart,
83            // update_cart: store.updateCart,
84            // replicate_cart: store.replicateCart,
85            };
86        }
87        if (context?.isAdmin) { // IMPORTANT
88            return {
89                read_cart: admin.readCart,
90                // create_cart: admin.createAdminCart,
91                // update_cart: admin.updateAdminCart,
92                // replicate_cart: admin.replicateAdminCart,
93            };
94        }
95        };
96```
97 
986. create a test file to check if correct context is loading right functions from  `contextTo<namespace>FunctionMapping` and if none is provided, it should be empty
997. update current tests to match the function calls
1008. refactor `typescript/src/shared/functions.ts` and import `import {contextToCartFunctionMapping} from './cart/functions';` then update  this method return 
1019. confirm that this method call `apiRoot.withProjectKey()` is only being called from base functions not in `customer.functions.ts` and not in `customer` and `admin`. if usage of `apiRoot.withProjectKey` found, move the method to base and reused from base functions.  
102```
103export const contextToFunctionMapping = (context?: Context) => {
104  return {
105    ...contextToOrderFunctionMapping(context),
106    ...contextToCartFunctionMapping(context),
107  };
108};
109```