feat(product-category): add external_id to product-category

It is available on both /admin and /store, and can be used as filter.

fix: add missing snapshot

test: fix race condition in test

chore: clean up test-cases. Remove dead code

chore: cleanup tests

Author: asgerjensen

.changeset/yummy-teams-matter.md

@@ -0,0 +1,8 @@
+---
+"@medusajs/product": patch
+"integration-tests-http": patch
+"@medusajs/types": patch
+"@medusajs/medusa": patch
+---
+
+add external_id to product-category

integration-tests/http/__tests__/product-category/admin/product-category.spec.ts

@@ -53,6 +53,7 @@ medusaIntegrationTestRunner({
               name: "category-0",
               parent_category_id: productCategoryParent.id,
               rank: 0,
+              external_id: "ext-id-0",
               description: "category-0",
             },
             adminHeaders
@@ -110,6 +111,7 @@ medusaIntegrationTestRunner({
             id: productCategory.id,
             name: productCategory.name,
             handle: productCategory.handle,
+            external_id: productCategory.external_id,
             parent_category_id: productCategoryParent.id,
             category_children: [
               expect.objectContaining({
@@ -226,6 +228,7 @@ medusaIntegrationTestRunner({
             "/admin/product-categories",
             {
               name: "sweater",
+              external_id: "ext-id-sweater",
               parent_category_id: productCategoryParent.id,
               is_internal: true,
             },
@@ -365,6 +368,8 @@ medusaIntegrationTestRunner({
         expect(response.data.product_categories).toHaveLength(7) // created in beforeEach
       })
 
+
+
       it("gets list of product category with immediate children and parents", async () => {
         // BREAKING: To get the children tree, the query param include_descendants_tree must be used
         const path = `/admin/product-categories?limit=7`
@@ -638,6 +643,18 @@ medusaIntegrationTestRunner({
         )
       })
 
+      it('filters based on external id', async () => {  
+
+        const response = await api.get(
+          `/admin/product-categories?external_id=${productCategory.external_id}`,
+          adminHeaders
+        ) 
+
+        expect(response.status).toEqual(200)
+        expect(response.data.product_categories).toHaveLength(1)
+        expect(response.data.product_categories[0].id).toEqual(productCategory.id)
+      });
+
       it("filters based on parent category", async () => {
         const response = await api.get(
           `/admin/product-categories?parent_category_id=${productCategoryParent.id}&limit=7`,
@@ -839,6 +856,46 @@ medusaIntegrationTestRunner({
         )
       })
 
+      it("successfully creates a product category with an external id", async () => {
+        const payload = {
+          name: "test",
+          handle: "test",
+          is_internal: true,
+          parent_category_id: productCategory.id,
+          description: "test",
+          external_id: "ext-id-0",
+        }
+
+        const response = await api.post(
+          `/admin/product-categories`,
+          payload,
+          adminHeaders
+        )
+
+        expect(response.status).toEqual(200)
+        expect(response.data).toEqual(
+          expect.objectContaining({
+            product_category: expect.objectContaining({
+              name: payload.name,
+              description: payload.description,
+              handle: payload.handle,
+              is_internal: payload.is_internal,
+              is_active: false,
+              external_id: payload.external_id,
+              created_at: expect.any(String),
+              updated_at: expect.any(String),
+              parent_category: expect.objectContaining({
+                id: productCategory.id,
+              }),
+              category_children: [],
+              rank: 0,
+            }),
+          })
+        )
+      })
+
+
+
       it("successfully creates a product category with a rank", async () => {
         const payload = {
           name: "test",
@@ -1202,6 +1259,7 @@ medusaIntegrationTestRunner({
             handle: "test",
             is_internal: true,
             is_active: true,
+            external_id: "ext-id-2",
             parent_category_id: productCategory.id,
           },
           adminHeaders
@@ -1220,6 +1278,7 @@ medusaIntegrationTestRunner({
               parent_category_id: productCategory.id,
               category_children: [],
               rank: 1,
+              external_id: "ext-id-2",
             }),
           })
         )

integration-tests/http/__tests__/product-category/store/product-category.spec.ts

@@ -0,0 +1,145 @@
+import { medusaIntegrationTestRunner } from "@medusajs/test-utils"
+import { IStoreModuleService } from "@medusajs/types"
+import {
+    Modules
+} from "@medusajs/utils"
+import qs from "qs"
+import {
+    adminHeaders,
+    createAdminUser,
+    generatePublishableKey,
+    generateStoreHeaders,
+} from "../../../../helpers/create-admin-user"
+import { createAuthenticatedCustomer } from "../../../../modules/helpers/create-authenticated-customer"
+
+jest.setTimeout(30000)
+
+medusaIntegrationTestRunner({
+  testSuite: ({ dbConnection, api, getContainer }) => {
+    let store
+    let appContainer
+    let productCategory1
+    let productCategory2
+    let storeHeaders
+    let publishableKey
+    let storeHeadersWithCustomer
+    let customer
+
+    const createCategory = async (data, productIds) => {
+      const response = await api.post(
+        "/admin/product-categories",
+        data,
+        adminHeaders
+      )
+
+      await api.post(
+        `/admin/product-categories/${response.data.product_category.id}/products`,
+        { add: productIds },
+        adminHeaders
+      )
+
+      const response2 = await api.get(
+        `/admin/product-categories/${response.data.product_category.id}?fields=*products`,
+        adminHeaders
+      )
+
+      return response2.data.product_category
+    }
+
+
+    beforeEach(async () => {
+      appContainer = getContainer()
+      publishableKey = await generatePublishableKey(appContainer)
+      storeHeaders = generateStoreHeaders({ publishableKey })
+      await createAdminUser(dbConnection, adminHeaders, appContainer)
+      const result = await createAuthenticatedCustomer(api, storeHeaders, {
+        first_name: "tony",
+        last_name: "stark",
+        email: "tony@stark-industries.com",
+      })
+
+      customer = result.customer
+      storeHeadersWithCustomer = {
+        headers: {
+          ...storeHeaders.headers,
+          authorization: `Bearer ${result.jwt}`,
+        },
+      }
+
+      const storeModule: IStoreModuleService = appContainer.resolve(
+        Modules.STORE
+      )
+      // A default store is created when the app is started, so we want to delete that one and create one specifically for our tests.
+      const defaultId = (await api.get("/admin/stores", adminHeaders)).data
+        .stores?.[0]?.id
+      if (defaultId) {
+        await storeModule.deleteStores(defaultId)
+      }
+
+      store = await storeModule.createStores({
+        name: "New store",
+        supported_currencies: [
+          { currency_code: "usd", is_default: true },
+          { currency_code: "dkk" },
+        ],
+      })
+
+    })
+
+    describe("Get product-categories based on publishable key", () => {
+
+      beforeEach(async () => {
+
+        productCategory1 = await createCategory(
+          { name: "test", is_internal: false, is_active: true, external_id: "ext-id-1" },
+          []
+        )
+
+
+        productCategory2 = await createCategory(
+          { name: "test2", is_internal: false, is_active: true, handle: 'test-2', external_id: "ext-id-2" },
+          []
+        )
+      })
+
+       it("returns the external_id on id lookups", async () => {
+        const response = await api.get(
+          `/store/product-categories/${productCategory1.id}`,
+          storeHeaders
+        )
+
+        expect(response.status).toBe(200)
+        expect(response.data.product_category).toEqual(
+          expect.objectContaining({
+            id: productCategory1.id,
+            external_id: "ext-id-1",
+          })
+        )
+      })
+
+      it("it filters on the external_id field", async () => {
+
+
+
+        const searchParam = qs.stringify({
+            external_id: "ext-id-2",
+        })
+
+        const response = await api.get(
+          `/store/product-categories?${searchParam}`,
+          storeHeaders
+        )
+
+        expect(response.status).toBe(200)
+        expect(response.data.product_categories).toEqual(
+          expect.arrayContaining([
+            expect.objectContaining({
+              id: productCategory2.id,
+              external_id: "ext-id-2",
+            }),
+          ])
+        )
+      })      
+    })
+  },
+})

packages/core/types/src/http/product-category/admin/payloads.ts

@@ -30,6 +30,10 @@ export interface AdminCreateProductCategory {
    * The category's ranking among its sibling categories.
    */
   rank?: number
+  /**
+   * An external identifier for the product category.
+   */
+  external_id?: string | null
   /**
    * Key-value pairs of custom data.
    */
@@ -68,6 +72,10 @@ export interface AdminUpdateProductCategory {
    * The category's ranking among its sibling categories.
    */
   rank?: number
+  /**
+   * An external identifier for the product category.
+   */
+  external_id?: string | null
   /**
    * Key-value pairs of custom data.
    */

packages/core/types/src/http/product-category/common.ts

@@ -32,6 +32,10 @@ export interface BaseProductCategory {
    * The category's ranking among sibling categories.
    */
   rank: number | null
+  /**
+   * An external identifier for the product category.
+   */
+  external_id: string | null
   /**
    * The ID of the category's parent.
    */
@@ -93,6 +97,10 @@ export interface BaseProductCategoryListParams
    * Filter by the category's handle(s).
    */
   handle?: string | string[]
+  /**
+   * Filter by the category's external ID(s).
+   */
+  external_id?: string | string[] | null
   /**
    * Filter by whether the category is active.
    */

packages/core/types/src/product/common.ts

@@ -310,6 +310,10 @@ export interface ProductCategoryDTO {
    * The ranking of the product category among sibling categories.
    */
   rank: number
+  /**
+   * An external identifier for the product category, such as an ID from a third-party system.
+   */
+  external_id: string | null
   /**
    * The ranking of the product category among sibling categories.
    */
@@ -384,6 +388,10 @@ export interface CreateProductCategoryDTO {
    * The ID of the parent product category, if it has any.
    */
   parent_category_id?: string | null
+  /**
+   * An external identifier for the product category, such as an ID from a third-party system.
+   */
+  external_id?: string | null
   /**
    * Holds custom data in key-value pairs.
    */
@@ -431,6 +439,10 @@ export interface UpdateProductCategoryDTO {
    * The ID of the parent product category, if it has any.
    */
   parent_category_id?: string | null
+  /**
+   * An external identifier for the product category, such as an ID from a third-party system.
+   */
+  external_id?: string | null
   /**
    * Holds custom data in key-value pairs.
    */
@@ -989,6 +1001,10 @@ export interface FilterableProductCategoryProps
    * Filter product categories by whether they're internal.
    */
   is_internal?: boolean
+  /**
+   * Filter product categories by external ID.
+   */
+  external_id?: string | string[] | null
   /**
    * Whether to include children of retrieved product categories.
    */

packages/medusa/src/api/admin/product-categories/query-config.ts

@@ -10,6 +10,7 @@ export const defaults = [
   "is_active",
   "is_internal",
   "rank",
+  "external_id",
   "parent_category_id",
   "created_at",
   "updated_at",
@@ -26,6 +27,7 @@ export const allowed = [
   "is_active",
   "is_internal",
   "rank",
+  "external_id",
   "parent_category_id",
   "created_at",
   "updated_at",

packages/medusa/src/api/admin/product-categories/validators.ts

@@ -26,6 +26,7 @@ export const AdminProductCategoriesParamsFields = z.object({
   description: z.union([z.string(), z.array(z.string())]).optional(),
   handle: z.union([z.string(), z.array(z.string())]).optional(),
   parent_category_id: z.union([z.string(), z.array(z.string())]).optional(),
+  external_id: z.union([z.string(), z.array(z.string()), z.null()]).optional(),
   include_ancestors_tree: booleanString().optional(),
   include_descendants_tree: booleanString().optional(),
   is_internal: booleanString().optional(),
@@ -53,6 +54,7 @@ export const CreateProductCategory = z
     is_internal: z.boolean().optional(),
     is_active: z.boolean().optional(),
     parent_category_id: z.string().nullish(),
+    external_id: z.string().nullish(),
     metadata: z.record(z.unknown()).nullish(),
     rank: z.number().nonnegative().optional(),
   })
@@ -74,6 +76,7 @@ export const UpdateProductCategory = z
     is_internal: z.boolean().optional(),
     is_active: z.boolean().optional(),
     parent_category_id: z.string().nullish(),
+    external_id: z.string().nullish(),
     metadata: z.record(z.unknown()).nullish(),
     rank: z.number().nonnegative().optional(),
   })