@thorprovider/adapters 5.0.8 → 5.0.9

package/docs/multi-tenant-channel-scoping.md

@@ -1,3 +1,9 @@
+---
+title: "Multi-Tenant Channel Scoping"
+purpose: "Backend-agnostic pattern for isolating customers, orders, and categories per sales channel using metadata"
+lastReviewed: "2026-09-28"
+---
+
 # Multi-Tenant Channel Scoping
 
 > Backend-agnostic pattern for isolating entities by sales channel using metadata.
@@ -147,10 +153,42 @@ The pattern is generic. To scope a new entity type:
 |-----------------|------------------------|------------------------|
 | Products        | ✅ `sales_channel_id`   | N/A (native)           |
 | Carts           | ✅ `sales_channel_id`   | N/A (native)           |
-| Categories      | ❌                      | ⚠️ Via product cross-ref |
-| **Customers**   | ❌                      | ✅ `metadata.sales_channel_id` |
-| **Orders**      | ❌                      | ✅ `metadata.sales_channel_id` |
-| Collections     | ❌ (linked via products) | Planned                |
+| Categories      | ✅ via `sales_channel` link (`/store/thor/categories`) | N/A (native) |
+| **Customers**   | ⚠️ native `customer_sales_channel` link in backend | ✅ `metadata.sales_channel_id` (adapter filter) |
+| **Orders**      | ✅ inherits `sales_channel_id` from cart | ✅ `metadata.sales_channel_id` (adapter filter) |
+| Collections     | ✅ via `sales_channel` link (`/store/thor/collections`) | N/A (native) |
+
+## Thor Commerce Plugin (Medusa) — Native Publishable-Key Scoping
+
+When the backend runs the Thor Commerce plugin (see `medusa-backend`, `src/api/store/thor/*`),
+scoping is resolved **server-side from the publishable API key** — no `sales_channel_id`
+query param is ever required from the storefront:
+
+- **Resolution:** Medusa core middleware maps `x-publishable-api-key` →
+  `sales_channel_ids`. A key bound to exactly one channel auto-injects that channel
+  into `/store/carts` bodies; a key bound to multiple channels requires the caller to
+  pass `sales_channel_id` explicitly.
+- **Products / carts / orders:** natively scoped by `sales_channel_id` (orders inherit
+  the cart's channel; a checkout workflow hook validates every line against the cart channel).
+- **Categories / collections:** scoped via their `sales_channel` M:M links. The adapter's
+  `getCategories` / `getCollections` call `GET /store/thor/categories` /
+  `GET /store/thor/collections` **unconditionally** — the endpoint resolves the channel
+  from the publishable key. The `salesChannelId` option (or
+  `NEXT_PUBLIC_SALES_CHANNEL_ID`) is only used for the legacy N+1 fallback when the
+  plugin endpoint is absent.
+- **Payment methods:** there is no channel concept for payment in Medusa. `getPaymentMethods`
+  is scoped by **region** (+ currency) only.
+- **createCart:** passes `sales_channel_id` into the payload when
+  `options.salesChannelId` or `NEXT_PUBLIC_SALES_CHANNEL_ID` is set (belt-and-suspenders —
+  the publishable key alone already scopes single-channel carts).
+- **Customers:** the backend auto-links customers to the channel (middleware on
+  `/store/carts*` and `/store/customers/me*`). The adapter still filters
+  `getCustomers` via `metadata.sales_channel_id`; for backends with the plugin, prefer
+  `GET /store/thor/customers` for fully server-scoped reads.
+
+> Note: backend-verified at Medusa v2.18.0 (`medusa-backend` repo). The plugin's
+> `/store/thor/*` routes accept only `x-publishable-api-key`; they return `400` if the
+> key resolves to no channel.
 
 ## When to Assign Channel Scope
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thorprovider/adapters",
-  "version": "5.0.8",
+  "version": "5.0.9",
   "description": "Framework-agnostic commerce adapters for Thor Commerce ecosystem - Multi-platform support with unified API",
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
@@ -29,7 +29,7 @@
   "dependencies": {
     "@medusajs/js-sdk": "2.16.0",
     "@medusajs/types": "2.16.0",
-    "@thorprovider/types": "^5.3.2",
+    "@thorprovider/types": "^5.6.3",
     "bcryptjs": "^3.0.3",
     "jose": "^6.2.2"
   },

package/src/providers/medusa/index.test.ts

@@ -220,6 +220,46 @@ describe('MedusaProvider — Cart', () => {
     expect(cart!.id).toBe('cart_01')
   })
 
+  it('getCart transforms flat v2 cart items (no nested variant.product)', async () => {
+    const flatCart = {
+      ...MEDUSA_CART,
+      items: [
+        {
+          id: 'cali_01',
+          variant_id: 'variant_01',
+          product_id: 'prod_01',
+          product_title: 'Cover Samsung Note 10 Plus',
+          product_handle: 'cover-samsung-note-10-plus',
+          variant_title: 'Cover Samsung Note 10 Plus - Negro',
+          title: 'Cover Samsung Note 10 Plus',
+          thumbnail: 'https://img.example.com/cover.png',
+          quantity: 2,
+          unit_price: 60,
+        },
+      ],
+      total: 120,
+      subtotal: 120,
+      totalQuantity: 2,
+    }
+    server.use(
+      http.get(`${BASE}/store/carts/cart_01`, () =>
+        HttpResponse.json({ cart: flatCart }),
+      ),
+    )
+
+    const provider = makeProvider()
+    const cart = await provider.getCart('cart_01')
+    const line = cart?.lines?.[0]
+
+    expect(line?.merchandise.id).toBe('variant_01')
+    expect(line?.merchandise.title).toBe('Cover Samsung Note 10 Plus - Negro')
+    expect(line?.merchandise.product.id).toBe('prod_01')
+    expect(line?.merchandise.product.handle).toBe('cover-samsung-note-10-plus')
+    expect(line?.merchandise.product.title).toBe('Cover Samsung Note 10 Plus')
+    expect(line?.merchandise.product.featuredImage.url).toBe('https://img.example.com/cover.png')
+    expect(line?.cost.totalAmount.amount).toBe('120.00')
+  })
+
   it('getCart returns undefined when cart not found (404)', async () => {
     server.use(
       http.get(`${BASE}/store/carts/cart_missing`, () =>

package/src/providers/medusa/index.ts

@@ -153,6 +153,7 @@ export class MedusaProvider implements CommerceProvider {
   private retryConfig: Required<RetryConfig>;
   private baseUrl: string;
   private publishableKey: string;
+  private regionId?: string;
 
   /** Secret API key for admin operations (if configured). */
   private adminApiKey?: string;
@@ -210,6 +211,7 @@ export class MedusaProvider implements CommerceProvider {
     this.currencyCode = config.currencyCode ?? 'USD';
     this.baseUrl = config.baseUrl;
     this.publishableKey = config.publishableKey;
+    this.regionId = config.regionId;
 
     // Store retry configuration
     this.retryConfig = {
@@ -389,10 +391,11 @@ export class MedusaProvider implements CommerceProvider {
     try {
       return await this.withRetry(
         async () => {
+          const regionId = options?.regionId ?? this.regionId;
           // calculated_price requires region_id in Medusa v2 — only request it when available
           const baseFields = '+variants,+variants.inventory_quantity,+options,+images,+tags';
           const pricingFields = ',+variants.calculated_price,+variants.prices';
-          const fields = options?.regionId ? baseFields + pricingFields : baseFields;
+          const fields = regionId ? baseFields + pricingFields : baseFields;
 
           const queryParams: any = {
             handle,
@@ -400,8 +403,8 @@ export class MedusaProvider implements CommerceProvider {
             fields,
           };
           // Add region_id for region-based pricing
-          if (options?.regionId) {
-            queryParams.region_id = options.regionId;
+          if (regionId) {
+            queryParams.region_id = regionId;
           }
 
           // Scope to storefront sales channel when configured.
@@ -439,10 +442,11 @@ export class MedusaProvider implements CommerceProvider {
     try {
       return await this.withRetry(
         async () => {
+          const regionId = options.regionId ?? this.regionId;
           // calculated_price requires region_id in Medusa v2 — only request it when available
           const baseFields = '+variants,+variants.inventory_quantity,+options,+images,+tags';
           const pricingFields = ',+variants.calculated_price,+variants.prices';
-          const fields = options.regionId ? baseFields + pricingFields : baseFields;
+          const fields = regionId ? baseFields + pricingFields : baseFields;
 
           // Map Thor SortOption values to Medusa /store/products `order` field names.
           // Native endpoint supports: title, -title, created_at, -created_at
@@ -473,8 +477,8 @@ export class MedusaProvider implements CommerceProvider {
           }
 
           // Add region_id for region-based pricing
-          if (options.regionId) {
-            queryParams.region_id = options.regionId;
+          if (regionId) {
+            queryParams.region_id = regionId;
           }
 
           // Basic category/collection filtering
@@ -987,6 +991,18 @@ export class MedusaProvider implements CommerceProvider {
 
       let result = collections.map(transformCollection);
 
+      // --- Sales channel scoping ---
+      // Applied unconditionally: the Thor Commerce plugin endpoint resolves the
+      // sales channel from the publishable key itself. An explicit channel id
+      // (options.salesChannelId ?? env) is only needed for the legacy N+1
+      // fallback on backends without the plugin.
+      const salesChannelId =
+        options?.salesChannelId ?? process.env.NEXT_PUBLIC_SALES_CHANNEL_ID;
+      const activeCollectionIds = await this._getChannelCollections(salesChannelId);
+      if (activeCollectionIds) {
+        result = result.filter((c: Collection) => activeCollectionIds.has(c.id));
+      }
+
       // Client-side search filtering (Medusa Store API lacks query param for collections)
       if (options?.query) {
         const q = options.query.toLowerCase();
@@ -1007,6 +1023,100 @@ export class MedusaProvider implements CommerceProvider {
     }
   }
 
+  /**
+   * Returns the set of product-collection IDs that have at least one product
+   * available in the given sales channel (legacy fallback).
+   *
+   * @deprecated Use `_getChannelCollections()` instead (backed by Thor Commerce plugin).
+   */
+  private async _getActiveCollectionIds(salesChannelId: string): Promise<Set<string>> {
+    this.logger.debug('_getActiveCollectionIds', { salesChannelId });
+    const collectionIds = new Set<string>();
+    const limit = 500;
+    let offset = 0;
+
+    // eslint-disable-next-line no-constant-condition
+    while (true) {
+      const { products } = (await this.sdk.store.product.list({
+        sales_channel_id: [salesChannelId],
+        fields: '+collections.id',
+        limit,
+        offset,
+      } as any)) as any;
+
+      for (const product of products ?? []) {
+        for (const col of product.collections ?? []) {
+          if (col?.id) collectionIds.add(col.id);
+        }
+      }
+
+      if (!products || products.length < limit) break;
+      offset += limit;
+    }
+
+    this.logger.debug('_getActiveCollectionIds result', { count: collectionIds.size });
+    return collectionIds;
+  }
+
+  /**
+   * Fetch channel-scoped collections from Thor Commerce plugin.
+   * Uses `GET /store/thor/collections` — the endpoint resolves the sales
+   * channel from the publishable key header itself.
+   *
+   * Falls back to `_getActiveCollectionIds()` (legacy N+1) when the plugin is
+   * not available; the legacy fallback needs an explicit `salesChannelId`.
+   * Returns `null` when no scoping could be performed.
+   */
+  private async _getChannelCollections(salesChannelId?: string): Promise<Set<string> | null> {
+    try {
+      const url = `${this.baseUrl}/store/thor/collections`;
+      const response = await fetchWithRetry(
+        url,
+        {
+          method: 'GET',
+          headers: {
+            'x-publishable-api-key': this.publishableKey,
+            'Content-Type': 'application/json',
+          },
+        },
+        this.retryConfig,
+      );
+
+      if (response.status === 404 || !response.ok) {
+        this.logger.debug('Thor plugin collections endpoint unavailable, falling back to legacy method');
+        return this._legacyChannelCollections(salesChannelId);
+      }
+
+      const data = await response.json();
+      const collectionIds = new Set<string>();
+      for (const col of data.collections ?? []) {
+        if (col?.id) collectionIds.add(col.id);
+      }
+
+      this.logger.debug('_getChannelCollections result (Thor plugin)', { count: collectionIds.size });
+      return collectionIds;
+    } catch (error) {
+      this.logger.warn('Failed to fetch channel collections from Thor plugin, falling back to legacy method', {
+        error: error instanceof Error ? error.message : String(error),
+      });
+      return this._legacyChannelCollections(salesChannelId);
+    }
+  }
+
+  /**
+   * Legacy fallback for `_getChannelCollections()` when the Thor plugin is not
+   * installed. Requires an explicit `salesChannelId`; returns `null` otherwise.
+   */
+  private async _legacyChannelCollections(salesChannelId?: string): Promise<Set<string> | null> {
+    if (!salesChannelId) {
+      this.logger.warn(
+        'Cannot scope collections: Thor plugin unavailable and no sales channel id provided; returning unscoped collections',
+      );
+      return null;
+    }
+    return this._getActiveCollectionIds(salesChannelId);
+  }
+
   async getCollectionProducts(
     handle: string,
     options: CollectionProductsOptions = {},
@@ -1125,10 +1235,20 @@ export class MedusaProvider implements CommerceProvider {
 
   /**
    * Fetch channel-scoped categories from Thor Commerce plugin.
-   * Uses `GET /store/thor/categories` — a single indexed query.
-   * Falls back to `_getActiveCategoryIds()` if the plugin is not available.
+   * Uses `GET /store/thor/categories` — a single indexed query. The endpoint
+   * resolves the sales channel from the publishable key header itself, so no
+   * explicit channel id is required when the plugin is installed.
+   *
+   * Falls back to `_getActiveCategoryIds()` (legacy N+1) when the plugin is
+   * not available. The legacy fallback needs an explicit `salesChannelId`;
+   * when none is provided and the plugin is unavailable, returns `null` to
+   * signal that scoping is not possible and the caller should skip filtering.
+   *
+   * @param salesChannelId - Only used by the legacy fallback (plugin absent).
+   * @returns Set of category IDs active in the channel, or `null` when no
+   * scoping could be performed.
    */
-  private async _getChannelCategories(salesChannelId: string): Promise<Set<string>> {
+  private async _getChannelCategories(salesChannelId?: string): Promise<Set<string> | null> {
     try {
       const url = `${this.baseUrl}/store/thor/categories`;
       const response = await fetchWithRetry(
@@ -1143,17 +1263,10 @@ export class MedusaProvider implements CommerceProvider {
         this.retryConfig,
       );
 
-      if (response.status === 404) {
+      if (response.status === 404 || !response.ok) {
         // Plugin not installed — fall back to legacy N+1 method
-        this.logger.debug('Thor plugin categories endpoint not found, falling back to legacy method');
-        return this._getActiveCategoryIds(salesChannelId);
-      }
-
-      if (!response.ok) {
-        this.logger.warn('Thor plugin categories endpoint returned non-OK status', {
-          status: response.status,
-        });
-        return this._getActiveCategoryIds(salesChannelId);
+        this.logger.debug('Thor plugin categories endpoint unavailable, falling back to legacy method');
+        return this._legacyChannelCategories(salesChannelId);
       }
 
       const data = await response.json();
@@ -1168,10 +1281,24 @@ export class MedusaProvider implements CommerceProvider {
       this.logger.warn('Failed to fetch channel categories from Thor plugin, falling back to legacy method', {
         error: error instanceof Error ? error.message : String(error),
       });
-      return this._getActiveCategoryIds(salesChannelId);
+      return this._legacyChannelCategories(salesChannelId);
     }
   }
 
+  /**
+   * Legacy fallback for `_getChannelCategories()` when the Thor plugin is not
+   * installed. Requires an explicit `salesChannelId`; returns `null` otherwise.
+   */
+  private async _legacyChannelCategories(salesChannelId?: string): Promise<Set<string> | null> {
+    if (!salesChannelId) {
+      this.logger.warn(
+        'Cannot scope categories: Thor plugin unavailable and no sales channel id provided; returning unscoped categories',
+      );
+      return null;
+    }
+    return this._getActiveCategoryIds(salesChannelId);
+  }
+
   async getCategories(options: GetCategoriesOptions = {}): Promise<ProductCategory[]> {
     this.logger.debug('getCategories', { options });
 
@@ -1202,12 +1329,14 @@ export class MedusaProvider implements CommerceProvider {
       let result = product_categories.map(transformCategory);
 
       // --- Sales channel scoping ---
-      // Prefer Thor Commerce plugin endpoint (single indexed query).
-      // Falls back to legacy N+1 method if plugin is not installed.
+      // Applied unconditionally: the Thor Commerce plugin endpoint resolves the
+      // sales channel from the publishable key itself. An explicit channel id
+      // (options.salesChannelId ?? env) is only needed for the legacy N+1
+      // fallback on backends without the plugin.
       const salesChannelId =
         options.salesChannelId ?? process.env.NEXT_PUBLIC_SALES_CHANNEL_ID;
-      if (salesChannelId) {
-        const activeCategoryIds = await this._getChannelCategories(salesChannelId);
+      const activeCategoryIds = await this._getChannelCategories(salesChannelId);
+      if (activeCategoryIds) {
         result = result.filter((c: ProductCategory) => activeCategoryIds.has(c.id));
       }
 
@@ -1254,6 +1383,11 @@ export class MedusaProvider implements CommerceProvider {
           '+variants,+variants.prices,+variants.calculated_prices,+variants.inventory_quantity,+options,+images,+tags',
       };
 
+      // Region-based pricing (calculated_price requires region_id in Medusa v2)
+      if (this.regionId) {
+        categoryQueryParams.region_id = this.regionId;
+      }
+
       // Scope to storefront sales channel when configured.
       const salesChannelId = process.env.NEXT_PUBLIC_SALES_CHANNEL_ID;
       if (salesChannelId) {
@@ -1279,8 +1413,11 @@ export class MedusaProvider implements CommerceProvider {
   // Cart Operations
   // ============================================
 
-  async createCart(options?: { regionId?: string }): Promise<Cart> {
-    this.logger.debug('createCart', { regionId: options?.regionId });
+  async createCart(options?: { regionId?: string; salesChannelId?: string }): Promise<Cart> {
+    this.logger.debug('createCart', {
+      regionId: options?.regionId,
+      salesChannelId: options?.salesChannelId,
+    });
 
     try {
       const createPayload: any = {};
@@ -1294,6 +1431,16 @@ export class MedusaProvider implements CommerceProvider {
         createPayload.currency_code = this.currencyCode.toLowerCase();
       }
 
+      // Explicit sales channel scope. Normally Medusa auto-injects the channel
+      // from the publishable key when it maps to exactly one channel, but
+      // passing it explicitly is required when the key maps to multiple
+      // channels (otherwise cart creation errors).
+      const salesChannelId =
+        options?.salesChannelId ?? process.env.NEXT_PUBLIC_SALES_CHANNEL_ID;
+      if (salesChannelId) {
+        createPayload.sales_channel_id = salesChannelId;
+      }
+
       const { cart } = await this.sdk.store.cart.create(createPayload);
 
       return transformCart(cart);
@@ -1347,16 +1494,12 @@ export class MedusaProvider implements CommerceProvider {
         retrieveCtx,
       );
 
-      console.log('retrieveResult =', JSON.stringify(retrieveResult, null, 2))
-      
       const backendCart = (retrieveResult as any)?.cart;
       if (!backendCart) {
         this.logger.warn('Cart not found before addToCart', { cartId });
         throw new ProviderAPIError('Cart not found. Please refresh and try again.', 'medusa', 404);
       }
 
-      console.log('backendCart =', JSON.stringify(backendCart, null, 2))
-
       if (!backendCart.region_id) {
         this.logger.warn('Attempted to add item to cart with no region_id', { cartId });
         throw new ProviderAPIError(
@@ -1416,8 +1559,6 @@ export class MedusaProvider implements CommerceProvider {
             );
           }
 
-          console.log('Found Variant:', JSON.stringify(foundVariant, null, 2));
-
           const variant = foundVariant;
           // Prefer calculated_price when present
           let hasPriceForRegion = false;
@@ -1432,10 +1573,6 @@ export class MedusaProvider implements CommerceProvider {
               ''
             ).toLowerCase();
 
-            console.log('calcCurrency =', calcCurrency);
-            console.log('cartCurrency =', cartCurrency);
-            console.log('this.currencyCode =', this.currencyCode)
-
             if (
               !cartCurrency ||
               calcCurrency === cartCurrency ||

package/src/providers/medusa/transforms.ts

@@ -291,7 +291,16 @@ export function transformCartItem(item: any, cartCurrencyCode?: string): CartIte
   const product = variant?.product;
   const currencyCode = resolveMedusaCartItemCurrencyCode(item, cartCurrencyCode);
   const totalCents = resolveMedusaCartItemTotal(item);
-  
+
+  // Medusa v2 store cart items return flat fields (product_title, variant_title,
+  // product_handle, thumbnail) instead of a nested variant.product object.
+  const merchandiseId = variant?.id ?? item.variant_id ?? '';
+  const merchandiseTitle = variant?.title ?? item.variant_title ?? '';
+  const productId = product?.id ?? item.product_id ?? '';
+  const productHandle = product?.handle ?? item.product_handle ?? '';
+  const productTitle = product?.title ?? item.product_title ?? '';
+  const thumbnail = product?.thumbnail ?? item.thumbnail ?? '';
+
   return {
     id: item.id,
     quantity: item.quantity ?? 1,
@@ -299,19 +308,18 @@ export function transformCartItem(item: any, cartCurrencyCode?: string): CartIte
       totalAmount: transformMoney(totalCents, currencyCode),
     },
     merchandise: {
-      id: variant?.id ?? '',
-      title: variant?.title ?? '',
-      selectedOptions: variant?.options?.map((opt: any) => ({
-        name: (opt as any).option?.title ?? '',
-        value: opt.value ?? '',
-      })) ?? [],
+      id: merchandiseId,
+      title: merchandiseTitle,
+      selectedOptions:
+        variant?.options?.map((opt: any) => ({
+          name: (opt as any).option?.title ?? '',
+          value: opt.value ?? '',
+        })) ?? [],
       product: {
-        id: product?.id ?? '',
-        handle: product?.handle ?? '',
-        title: product?.title ?? '',
-        featuredImage: product?.thumbnail
-          ? transformImage(product.thumbnail, product.title ?? '')
-          : transformImage('', ''),
+        id: productId,
+        handle: productHandle,
+        title: productTitle,
+        featuredImage: thumbnail ? transformImage(thumbnail, productTitle) : transformImage('', ''),
       },
     },
   };