medusa-product-helper 0.0.13 → 0.0.16

package/README.md

@@ -147,6 +147,17 @@ const plugins = [
         // Require products to have at least one review
         require_reviews: false,
       },
+      // Custom filter providers (optional)
+      filterProviders: [
+        // File path (relative to project root)
+        "./src/providers/margin-provider.ts",
+        // Or module reference
+        "@my-org/custom-filters/brand-provider",
+      ],
+      // Disable specific built-in providers (optional)
+      disableBuiltInProviders: [
+        // "rating", // Uncomment to disable rating filter provider
+      ],
     },
   },
 ]
@@ -230,6 +241,84 @@ Configure rating-based filtering:
 - `max`: Maximum rating (0-5)
 - `require_reviews`: Require at least one review
 
+#### Filter Providers
+
+Configure custom filter providers:
+- `filterProviders`: Array of file paths or module references to custom filter providers
+- `disableBuiltInProviders`: Array of provider identifiers to disable (e.g., `["rating"]`)
+
+See the [Provider Development Guide](./PROVIDER_DEVELOPMENT_GUIDE.md) for details on creating custom filter providers.
+
+## Dynamic Filter Provider System
+
+The plugin includes a provider-based dynamic filter system that allows you to extend product filtering capabilities without modifying the plugin code. All built-in filters (category, collection, metadata, price range, etc.) are implemented as filter providers, and you can add your own custom providers.
+
+### Built-in Filter Providers
+
+The plugin includes the following built-in filter providers:
+
+- **Category Filter** (`category_id`): Filter products by category IDs
+- **Collection Filter** (`collection_id`): Filter products by collection IDs
+- **Metadata Filter** (`metadata`): Filter products by metadata with allowlist validation
+- **Price Range Filter** (`price_range`): Filter products by price range (min/max)
+- **Promotion Window Filter** (`promotion_window`): Filter products by promotion date windows
+- **Availability Filter** (`availability`): Filter products by availability status
+- **Rating Filter** (`rating`): Filter products by rating (min/max)
+- **Base Product Filters** (`base_product`): Filter by ID, handle, tags, sales channel
+
+### Using Filters
+
+All filters are available through the `/store/product-helper/products` endpoint:
+
+```bash
+# Filter by category
+GET /store/product-helper/products?category_id=cat_123,cat_456
+
+# Filter by price range
+GET /store/product-helper/products?price_min=10&price_max=100
+
+# Filter by metadata (if filterable)
+GET /store/product-helper/products?metadata[brand]=nike&metadata[color]=red
+
+# Multiple filters
+GET /store/product-helper/products?category_id=cat_123&price_min=10&rating_min=4
+```
+
+### Custom Filter Providers
+
+You can create custom filter providers to add new filtering capabilities. See the [Provider Development Guide](./PROVIDER_DEVELOPMENT_GUIDE.md) for complete documentation.
+
+**Quick Example:**
+
+```typescript
+// src/providers/margin-provider.ts
+import { BaseFilterProvider } from "medusa-product-helper/providers/filter-providers"
+
+export class MarginFilterProvider extends BaseFilterProvider {
+  static readonly identifier = "margin"
+  static readonly displayName = "Margin Filter"
+  
+  apply(filters: Record<string, unknown>, value: unknown): Record<string, unknown> {
+    if (!value || typeof value !== "object") return filters
+    
+    const { min, max } = value as { min?: number; max?: number }
+    // Apply margin filter logic...
+    return filters
+  }
+}
+```
+
+Then register it in `medusa-config.ts`:
+
+```typescript
+{
+  resolve: "medusa-product-helper",
+  options: {
+    filterProviders: ["./src/providers/margin-provider.ts"],
+  },
+}
+```
+
 ## Wishlist Feature
 
 The plugin includes a comprehensive wishlist feature that allows customers to save products they're interested in and admins to view wishlist statistics.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "medusa-product-helper",
-  "version": "0.0.13",
+  "version": "0.0.16",
   "description": "A starter for Medusa plugins.",
   "author": "Medusa (https://medusajs.com)",
   "license": "MIT",
@@ -37,10 +37,10 @@
     "@medusajs/admin-sdk": "2.11.2",
     "@medusajs/cli": "2.11.2",
     "@medusajs/framework": "2.11.2",
+    "@medusajs/icons": "2.11.2",
     "@medusajs/medusa": "2.11.2",
     "@medusajs/test-utils": "2.11.2",
     "@medusajs/ui": "4.0.25",
-    "@medusajs/icons": "2.11.2",
     "@swc/core": "1.5.7",
     "@types/node": "^20.0.0",
     "@types/react": "^18.3.2",
@@ -68,4 +68,4 @@
   "engines": {
     "node": ">=20"
   }
-}
+}