feat(medusa): allow category list api to be filtered by handle (#3825)

what:

- Introduce a filter to the list endpoint to query by handle

why:

- Storefronts mostly interact through handles and not IDs for readability and seo purposes - Take an example of a url `site.com/category/mens-wear`

RESOLVES CORE-1325

.changeset/little-panthers-tell.md

@@ -0,0 +1,5 @@
+---
+"@medusajs/medusa": patch
+---
+
+feat(medusa): allow category api to be filtered by handle

integration-tests/api/__tests__/admin/product-category.ts

@@ -305,6 +305,19 @@ describe("/admin/product-categories", () => {
       expect(response.data.product_categories[0].id).toEqual(productCategory.id)
     })
 
+    it("filters based on handle attribute of the data model", async () => {
+      const api = useApi()
+
+      const response = await api.get(
+        `/admin/product-categories?handle=${productCategory.handle}`,
+        adminHeaders,
+      )
+
+      expect(response.status).toEqual(200)
+      expect(response.data.count).toEqual(1)
+      expect(response.data.product_categories[0].id).toEqual(productCategory.id)
+    })
+
     it("filters based on free text on name and handle columns", async () => {
       const api = useApi()
 

integration-tests/api/__tests__/store/product-category.ts

@@ -300,6 +300,18 @@ describe("/store/product-categories", () => {
       expect(response.data.product_categories[0].id).toEqual(productCategoryParent.id)
     })
 
+    it("filters based on handle attribute of the data model", async () => {
+      const api = useApi()
+
+      const response = await api.get(
+        `/store/product-categories?handle=${productCategory.handle}`,
+      )
+
+      expect(response.status).toEqual(200)
+      expect(response.data.count).toEqual(1)
+      expect(response.data.product_categories[0].id).toEqual(productCategory.id)
+    })
+
     it("filters based on parent category", async () => {
       const api = useApi()
 

packages/generated/client-types/src/lib/models/AdminGetProductCategoriesParams.ts

@@ -5,9 +5,13 @@ import { SetRelation, Merge } from "../core/ModelUtils"
 
 export interface AdminGetProductCategoriesParams {
   /**
-   * Query used for searching product category names orhandles.
+   * Query used for searching product category names or handles.
    */
   q?: string
+  /**
+   * Query used for searching product category by handle.
+   */
+  handle?: string
   /**
    * Search for only internal categories.
    */

packages/generated/client-types/src/lib/models/StoreGetProductCategoriesParams.ts

@@ -8,6 +8,10 @@ export interface StoreGetProductCategoriesParams {
    * Query used for searching product category names or handles.
    */
   q?: string
+  /**
+   * Query used for searching product category by handle.
+   */
+  handle?: string
   /**
    * Returns categories scoped by parent
    */

packages/medusa/src/api/routes/admin/product-categories/list-product-categories.ts

@@ -13,7 +13,8 @@ import { optionalBooleanMapper } from "../../../../utils/validators/is-boolean"
  * description: "Retrieve a list of product categories."
  * x-authenticated: true
  * parameters:
- *   - (query) q {string} Query used for searching product category names orhandles.
+ *   - (query) q {string} Query used for searching product category names or handles.
+ *   - (query) handle {string} Query used for searching product category by handle.
  *   - (query) is_internal {boolean} Search for only internal categories.
  *   - (query) is_active {boolean} Search for only active categories
  *   - (query) include_descendants_tree {boolean} Include all nested descendants of category
@@ -94,6 +95,10 @@ export class AdminGetProductCategoriesParams extends extendedFindParamsMixin({
   @IsOptional()
   q?: string
 
+  @IsString()
+  @IsOptional()
+  handle?: string
+
   @IsBoolean()
   @IsOptional()
   @Transform(({ value }) => optionalBooleanMapper.get(value))

packages/medusa/src/api/routes/store/product-categories/list-product-categories.ts

@@ -15,6 +15,7 @@ import { defaultStoreCategoryScope } from "."
  * x-authenticated: false
  * parameters:
  *   - (query) q {string} Query used for searching product category names or handles.
+ *   - (query) handle {string} Query used for searching product category by handle.
  *   - (query) parent_category_id {string} Returns categories scoped by parent
  *   - (query) include_descendants_tree {boolean} Include all nested descendants of category
  *   - (query) offset=0 {integer} How many product categories to skip in the result.
@@ -96,6 +97,10 @@ export class StoreGetProductCategoriesParams extends extendedFindParamsMixin({
   @IsOptional()
   q?: string
 
+  @IsString()
+  @IsOptional()
+  handle?: string
+
   @IsString()
   @IsOptional()
   @Transform(({ value }) => {