ESHOPMAN Product Category Deletion Events: A Developer's Guide to Reliable Subscriptions

As an ESHOPMAN developer crafting custom functionalities or integrations, accurately subscribing to platform events is vital for dynamic storefront management within HubSpot. A common task involves reacting to product category deletions. However, a subtle challenge has emerged for developers implementing such event listeners.

The Challenge: Unreliable Product Category Deletion Event Subscriptions

Developers registering an ESHOPMAN subscriber for product category deletion events might find that using the exported constant ProductEvents.PRODUCT_CATEGORY_DELETED does not trigger their subscriber, while the literal event name "product-category.deleted" works. This discrepancy can lead to confusion in custom ESHOPMAN applications built with Node.js/TypeScript.

Reproduction Example:

Consider this ESHOPMAN subscriber configuration:

import type { SubscriberConfig } from "@eshopman/eshopman"
import { ProductEvents } from "@eshopman/framework/utils"

export const config: SubscriberC
  event: [
    ProductEvents.PRODUCT_CATEGORY_DELETED, // Often does not trigger
    "product-category.deleted",             // Reliably triggers
  ],
}

When a product category is deleted via the ESHOPMAN Admin API or HubSpot, the subscriber using ProductEvents.PRODUCT_CATEGORY_DELETED might fail to execute, unlike the one using the literal string.

The Root Cause: Event Name Mismatch

The issue stems from an internal event-name mismatch within the ESHOPMAN framework. The constant ProductEvents.PRODUCT_CATEGORY_DELETED is often generated with a module prefix (e.g., resolving to 'product.product-category.deleted'). However, the actual event emitted and consumed by external subscribers is the unprefixed version: 'product-category.deleted'.

The Solution: Embrace ESHOPMAN Workflow Events

For reliable event handling in ESHOPMAN, especially for critical actions, the recommended approach is to utilize Workflow Events. These events are specifically designed for external subscribers and trigger only after a complete workflow (like a deletion) has successfully concluded, offering superior reliability.

Instead of ProductEvents.PRODUCT_CATEGORY_DELETED, ESHOPMAN developers should use ProductCategoryWorkflowEvents.DELETED, imported from @eshopman/framework/utils. This constant correctly resolves to 'product-category.deleted', ensuring your subscribers are reliably triggered.

Corrected Subscriber Configuration:

import type { SubscriberConfig } from "@eshopman/eshopman"
import { ProductCategoryWorkflowEvents } from "@eshopman/framework/utils" // Import the correct enum

export const config: SubscriberC
  event: ProductCategoryWorkflowEvents.DELETED, // Use the Workflow Event
}

This best practice extends to other entity events; always prioritize WorkflowEvents (e.g., ProductWorkflowEvents, OrderWorkflowEvents) when building custom logic reacting to core ESHOPMAN operations.

Enhancing Developer Experience: Type Autocomplete Suggestions

To further improve the developer experience, particularly with various ESHOPMAN event types, a valuable suggestion involves enhancing the TypeScript typing for SubscriberConfig. By allowing for both known workflow events and arbitrary custom events while preserving autocomplete, developers can more easily discover and utilize correct event names.

A proposed type definition could look like this:

type TProductCategoryWorkflowEvents = typeof ProductCategoryWorkflowEvents;
type Event =
  | TProductCategoryWorkflowEvents[keyof TProductCategoryWorkflowEvents]
  // ...other known workflow events
  | (string & {}); // Allows custom strings & autocomplete

export type SubscriberC
    event: Event | Event[];
    // ...other config properties
};

This approach ensures ESHOPMAN developers benefit from strong typing and intelligent code completion, reducing the likelihood of using incorrect event constants.

Conclusion

Understanding the distinction between internal ProductEvents and reliable WorkflowEvents is crucial for building robust ESHOPMAN applications. By adopting ProductCategoryWorkflowEvents.DELETED and advocating for improved TypeScript definitions, the ESHOPMAN community can ensure smoother development and more reliable headless commerce solutions integrated with HubSpot CMS.

ESHOPMAN Event Handling: Ensuring Your Product Category Deletion Subscribers Trigger Reliably