medusa-product-helper 0.0.12 → 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.
@@ -448,11 +537,12 @@ import {
 #### Example Usage
 
 ```typescript
+// Recommended: Using Bearer token for authentication
 const options: HelperTransportOptions = {
   baseUrl: "https://store.example.com",
   publishableApiKey: "pk_your_publishable_api_key",
   headers: {
-    Cookie: "connect.sid=...", // or Authorization header
+    Authorization: "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", // Customer JWT token
   },
 }
 
@@ -466,23 +556,44 @@ const { wishlist } = await getWishlist({ includeDetails: true }, options)
 await removeFromWishlist({ product_id: "prod_123" }, options)
 ```
 
+**Alternative: Using session cookie**
+```typescript
+const options: HelperTransportOptions = {
+  baseUrl: "https://store.example.com",
+  publishableApiKey: "pk_your_publishable_api_key",
+  headers: {
+    Cookie: "connect.sid=...", // Session cookie (browser-based)
+  },
+}
+```
+
 #### Configuration Options
 
 All helper calls accept the following options:
 
 - `publishableApiKey`: Required for public storefront calls when not passing a Medusa JS client. Add it from **Settings → API Keys** in the Medusa dashboard.
-- `client`: Medusa JS/SDK client instance. When provided, network requests are delegated to `client.request` and the client’s publishable key is reused.
+- `client`: Medusa JS/SDK client instance. When provided, network requests are delegated to `client.request` and the client's publishable key is reused.
 - `baseUrl`: Base URL for the Store API (e.g., `https://store.example.com`). Required when a client is not provided.
 - `fetchImpl`: Custom `fetch` implementation for SSR or React Native environments. Defaults to `globalThis.fetch`.
-- `headers`: Additional headers appended to every request (useful for `Cookie` / `Authorization` headers).
+- `headers`: Additional headers appended to every request. **Required for authenticated endpoints** - include `Authorization: Bearer <token>` for customer authentication:
+  ```ts
+  headers: {
+    "Authorization": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
+  }
+  ```
+
+**Note:** All wishlist endpoints require customer authentication. Pass the Bearer token via the `headers` option.
 
 You can also generate pre-configured helpers:
 
 ```typescript
+// Recommended: Using Bearer token
 const wishlist = createWishlistHelpers({
   baseUrl: "https://store.example.com",
   publishableApiKey: "pk_your_publishable_api_key",
-  headers: { Cookie: "connect.sid=..." },
+  headers: {
+    Authorization: "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+  },
 })
 
 await wishlist.addToWishlist({ product_id: "prod_123" })
@@ -490,6 +601,33 @@ const { wishlist: items } = await wishlist.getWishlist({ includeDetails: true })
 await wishlist.removeFromWishlist({ product_id: "prod_123" })
 ```
 
+**Getting the Bearer Token:**
+```typescript
+// Login to get JWT token
+const loginResponse = await fetch("https://store.example.com/store/auth/customer/emailpass", {
+  method: "POST",
+  headers: {
+    "Content-Type": "application/json",
+    "x-publishable-api-key": "pk_your_publishable_api_key",
+  },
+  body: JSON.stringify({
+    email: "customer@example.com",
+    password: "password123",
+  }),
+})
+
+const { token } = await loginResponse.json()
+
+// Use token in wishlist helpers
+const wishlist = createWishlistHelpers({
+  baseUrl: "https://store.example.com",
+  publishableApiKey: "pk_your_publishable_api_key",
+  headers: {
+    Authorization: `Bearer ${token}`,
+  },
+})
+```
+
 ### Using Workflows Directly
 
 You can also use the workflows directly in your custom code:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "medusa-product-helper",
-  "version": "0.0.12",
+  "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"
   }
-}
+}