@thorprovider/adapters 5.0.11 → 5.0.12

package/src/providers/medusa/index.ts

@@ -31,6 +31,8 @@ import type {
   Customer,
   GetCustomersOptions,
   GetOrdersOptions,
+  GetCustomerOrdersPageOptions,
+  CustomerOrdersPage,
   AdminProduct,
   Region,
   Address,
@@ -62,13 +64,42 @@ import { MedusaAuthProvider } from './auth';
 import { getPaymentMethods } from './payment';
 import {
   buildChannelScopeMetadata,
-  filterByChannel,
   validateChannelScopeAssignment,
 } from '../../metadata';
 
 const MEDUSA_CART_RETRIEVE_FIELDS =
   '+items,+items.variant,+items.variant.product,+items.variant.product.thumbnail,+items.variant.options,+items.variant.options.option,+items.total,+items.unit_price,+items.item_subtotal,+items.item_total,+shipping_methods,+shipping_methods.id,+shipping_methods.shipping_option_id';
 
+/** Default window size for the channel-scoped order-history route. */
+const CUSTOMER_ORDERS_DEFAULT_PAGE_SIZE = 10;
+
+/**
+ * Upper bound on a single order-history window. The route is never asked for an
+ * unbounded/all-orders result (design D14); a caller requesting more is clamped.
+ */
+const CUSTOMER_ORDERS_MAX_PAGE_SIZE = 100;
+
+/**
+ * Normalize a 1-based page + pageSize into the backend's `limit`/`offset`.
+ * Non-integer or non-positive values fall back to the canonical defaults and the
+ * page size is clamped to {@link CUSTOMER_ORDERS_MAX_PAGE_SIZE}.
+ */
+function normalizeCustomerOrdersPage(options: GetCustomerOrdersPageOptions): {
+  page: number;
+  pageSize: number;
+  limit: number;
+  offset: number;
+} {
+  const page =
+    Number.isInteger(options.page) && (options.page as number) > 0 ? (options.page as number) : 1;
+  const requested =
+    Number.isInteger(options.pageSize) && (options.pageSize as number) > 0
+      ? (options.pageSize as number)
+      : CUSTOMER_ORDERS_DEFAULT_PAGE_SIZE;
+  const pageSize = Math.min(requested, CUSTOMER_ORDERS_MAX_PAGE_SIZE);
+  return { page, pageSize, limit: pageSize, offset: (page - 1) * pageSize };
+}
+
 /**
  * Fields requested when completing a cart into an order.
  *
@@ -777,7 +808,7 @@ export class MedusaProvider implements CommerceProvider, CartCompletionCapable {
   /** Fields needed to price a product variant for the current region. */
   private buildProductFields(regionId?: string): string {
     // calculated_price requires region_id in Medusa v2 — only request it when available
-    const baseFields = '+variants,+variants.inventory_quantity,+options,+images,+tags';
+    const baseFields = '+variants,+variants.inventory_quantity,+options,+images,+tags,+categories.*';
     const pricingFields = ',+variants.calculated_price,+variants.prices';
     return regionId ? baseFields + pricingFields : baseFields;
   }
@@ -2862,13 +2893,17 @@ export class MedusaProvider implements CommerceProvider, CartCompletionCapable {
   // ============================================
 
   /**
-   * Get all orders for a customer (storefront).
+   * Get all orders for a customer (storefront) as an array (legacy surface).
    *
-   * Note: This retrieves orders from the storefront API (store.order.list),
-   * which returns orders only for the authenticated customer in the JWT.
+   * Delegates to the channel-scoped paginated contract
+   * ({@link customerOrdersPage}) and returns that window's orders. The backend
+   * (`GET /store/thor/orders`) scopes by BOTH the authenticated customer and
+   * the sales channel resolved from the publishable key, so cross-channel
+   * orders are excluded by the backend before pagination and **no client-side
+   * channel filter runs**.
    *
-   * @param options - Order query options (supports callbacks for custom backends)
-   * @returns Array of orders for the authenticated customer
+   * @param options - Order query options (supports a custom fetcher)
+   * @returns Array of orders for the authenticated customer on the store channel
    *
    * @example
    * ```typescript
@@ -2885,40 +2920,87 @@ export class MedusaProvider implements CommerceProvider, CartCompletionCapable {
       return customFetcher(options);
     }
 
-    this.logger.info('Getting orders for authenticated customer');
+    const page = await this.customerOrdersPage({
+      page: 1,
+      pageSize: options.limit ?? CUSTOMER_ORDERS_MAX_PAGE_SIZE,
+      salesChannelId,
+    });
+    return page.orders;
+  }
+
+  /**
+   * Channel-scoped, paginated order history for the authenticated customer.
+   *
+   * Calls the backend route `GET /store/thor/orders`, which requires the
+   * customer session and scopes `order` by `customer_id` **and** the
+   * `sales_channel_id` resolved from the publishable key, returning
+   * `{ orders, count, limit, offset }` with the backend's real total computed
+   * before pagination.
+   *
+   * The `salesChannelId` option is the store's explicitly configured channel.
+   * When supplied, every returned order is asserted to belong to it; a
+   * foreign-channel order (for example from a multi-channel publishable key that
+   * silently resolved an arbitrary first id) fails closed with a typed error
+   * rather than being presented as the customer's history.
+   *
+   * @param options - Bounded pagination window and the store's sales channel
+   * @returns The backend's `{ orders, count, limit, offset }`
+   */
+  async customerOrdersPage(
+    options: GetCustomerOrdersPageOptions = {},
+  ): Promise<CustomerOrdersPage> {
+    const { page, pageSize, limit, offset } = normalizeCustomerOrdersPage(options);
+    const { salesChannelId } = options;
+
+    this.logger.info('Getting channel-scoped customer orders', { page, pageSize });
 
     try {
-      const result = await this.withRetry(
+      const response = await this.withRetry(
         async () =>
-          this.sdk.store.order.list({
-            // Medusa v2 JS-SDK automatically includes authorization header if JWT is present
-            fields: '+items,+items.variant,+items.variant.product,+shipping_address,+billing_address,+customer',
+          this.sdk.client.fetch<{
+            orders?: any[];
+            count?: number;
+            limit?: number;
+            offset?: number;
+          }>('/store/thor/orders', {
+            method: 'GET',
+            query: { limit, offset },
           }),
-        'getOrders',
+        'customerOrdersPage',
         {},
       );
 
-      const orders = result.orders ?? [];
-      this.logger.debug(`Found ${orders.length} orders for customer`);
+      const rawOrders = response.orders ?? [];
+      this.logger.debug(`Found ${rawOrders.length} channel-scoped orders for customer`);
 
-      const transformed: Order[] = orders.map((order: any) => transformOrder(order));
-
-      // Multi-tenant: filter by sales channel if requested
-      const channelId = salesChannelId ?? process.env.NEXT_PUBLIC_SALES_CHANNEL_ID;
-      if (channelId) {
-        const scoped = filterByChannel<Order>(transformed, channelId);
-        this.logger.debug(
-          `Channel scoping: ${scoped.length}/${transformed.length} orders match channel ${channelId}`,
+      // Fail closed if the backend scoped to a channel other than the store's
+      // configured one (a multi-channel key must never be silently accepted).
+      if (salesChannelId) {
+        const foreign = rawOrders.find(
+          (order: any) =>
+            typeof order?.sales_channel_id === 'string' &&
+            order.sales_channel_id !== salesChannelId,
         );
-        return scoped;
+        if (foreign) {
+          throw new ProviderAPIError(
+            `Channel-scoped order history returned an order outside the store's sales channel (${salesChannelId}).`,
+            'medusa',
+          );
+        }
       }
 
-      return transformed;
+      return {
+        orders: rawOrders.map((order: any) => transformOrder(order)),
+        count: typeof response.count === 'number' ? response.count : rawOrders.length,
+        limit: typeof response.limit === 'number' ? response.limit : limit,
+        offset: typeof response.offset === 'number' ? response.offset : offset,
+      };
     } catch (error) {
+      if (error instanceof ProviderAPIError) throw error;
       const status = (error as any)?.status || (error as any)?.statusCode;
       const errorMessage = extractErrorMessage(error);
 
-      this.logger.error('Error getting orders', { error: errorMessage });
+      this.logger.error('Error getting channel-scoped orders', { error: errorMessage });
       throw new ProviderAPIError(
         `Failed to fetch orders: ${errorMessage}`,
         'medusa',

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

@@ -174,4 +174,49 @@ describe('transformProduct', () => {
     expect(product.priceRange.minVariantPrice.amount).toBe('')
     expect(product.priceRange.maxVariantPrice.amount).toBe('')
   })
+
+  it('maps the backend category relation, preserving hierarchy', () => {
+    const product = transformProduct({
+      id: 'prod_cat',
+      handle: 'with-categories',
+      title: 'With Categories',
+      description: '',
+      images: [],
+      options: [],
+      variants: [],
+      categories: [
+        { id: 'cat_tools', name: 'Tools', handle: 'tools' },
+        {
+          id: 'cat_drills',
+          name: 'Drills',
+          handle: 'drills',
+          parent_category_id: 'cat_tools',
+        },
+      ],
+    })
+
+    expect(product.categories).toEqual([
+      { id: 'cat_tools', name: 'Tools', handle: 'tools', parentCategoryId: undefined },
+      {
+        id: 'cat_drills',
+        name: 'Drills',
+        handle: 'drills',
+        parentCategoryId: 'cat_tools',
+      },
+    ])
+  })
+
+  it('omits categories when the backend supplies none (never fabricated)', () => {
+    const product = transformProduct({
+      id: 'prod_no_cat',
+      handle: 'no-categories',
+      title: 'No Categories',
+      description: '',
+      images: [],
+      options: [],
+      variants: [],
+    })
+
+    expect(product.categories).toBeUndefined()
+  })
 })

package/src/providers/medusa/transforms.ts

@@ -278,6 +278,13 @@ export function transformProduct(
       handle: product.collection.handle ?? '',
     }] : undefined,
     
+    categories: product.categories?.map((category: any) => ({
+      id: category.id,
+      name: category.name ?? '',
+      handle: category.handle ?? '',
+      parentCategoryId: category.parent_category_id ?? undefined,
+    })),
+    
     productType: product.type?.value ?? undefined,
     vendor: undefined,  // Medusa doesn't have vendor field
     tags: product.tags?.map((t: any) => t.value ?? '') ?? [],

package/src/providers/mock/catalog-query.test.ts

@@ -70,9 +70,11 @@ describe('MockProvider.getCatalogProducts — scope', () => {
   it('returns the full fixture catalog with no filters (no filter leak)', async () => {
     const outcome = await makeProvider().getCatalogProducts({})
 
-    expect(handles(outcome)).toEqual(FIXTURE_ORDER)
+    const productHandles = handles(outcome)
+    expect(productHandles.slice(0, 4)).toEqual(FIXTURE_ORDER)
+    expect(productHandles).toHaveLength(39)
     if (!outcome.ok) return
-    expect(outcome.results.total).toBe(4)
+    expect(outcome.results.total).toBe(39)
   })
 
   it('retains the route category scope and resolves the handle to its products', async () => {
@@ -80,10 +82,15 @@ describe('MockProvider.getCatalogProducts — scope', () => {
       categoryScope: 'jackets',
     })
 
-    expect(handles(outcome)).toEqual(['aurora-jacket'])
+    expect(handles(outcome)).toContain('aurora-jacket')
     if (!outcome.ok) return
     expect(outcome.results.appliedFilters.categories).toEqual(['jackets'])
-    expect(outcome.results.total).toBe(1)
+    expect(outcome.results.total).toBe(12)
+    expect(
+      outcome.results.products.every(
+        (product) => product.metadata?.categoryHandle === 'jackets',
+      ),
+    ).toBe(true)
   })
 
   it('intersects the categories filter with the route scope', async () => {
@@ -92,9 +99,14 @@ describe('MockProvider.getCatalogProducts — scope', () => {
       categories: ['jackets', 'dresses'],
     })
 
-    expect(handles(outcome)).toEqual(['aurora-jacket'])
+    expect(handles(outcome)).toContain('aurora-jacket')
     if (!outcome.ok) return
     expect(outcome.results.appliedFilters.categories).toEqual(['jackets'])
+    expect(
+      outcome.results.products.every(
+        (product) => product.metadata?.categoryHandle === 'jackets',
+      ),
+    ).toBe(true)
   })
 
   it('treats an empty route-scope ∩ categories intersection as zero results, not unfiltered', async () => {
@@ -128,12 +140,20 @@ describe('MockProvider.getCatalogProducts — scope', () => {
       collections: ['mock-collection-best-sellers'],
     })
 
-    expect(handles(byHandle)).toEqual(['aurora-jacket', 'helios-lamp'])
-    expect(handles(byId)).toEqual(['aurora-jacket', 'helios-lamp'])
+    expect(handles(byHandle)).toEqual(handles(byId))
+    expect(handles(byHandle)).toContain('aurora-jacket')
+    expect(handles(byHandle)).toContain('helios-lamp')
     if (!byHandle.ok) return
     expect(byHandle.results.appliedFilters.collections).toEqual([
       'best-sellers',
     ])
+    expect(
+      byHandle.results.products.every((product) =>
+        (product.collections ?? []).some(
+          (collection) => collection.handle === 'best-sellers',
+        ),
+      ),
+    ).toBe(true)
   })
 
   it('treats an unknown collection handle as zero results, not unfiltered', async () => {
@@ -161,8 +181,14 @@ describe('MockProvider.getCatalogProducts — text', () => {
       text: 'dress',
     })
 
-    expect(handles(unscoped)).toEqual(['solis-dress'])
+    expect(handles(unscoped)).toContain('solis-dress')
     expect(handles(scoped)).toEqual([])
+    if (!unscoped.ok) return
+    expect(
+      unscoped.results.products.every(
+        (product) => product.metadata?.categoryHandle === 'dresses',
+      ),
+    ).toBe(true)
   })
 
   it('excludes the other category for a term that matches two categories (CU-09)', async () => {
@@ -208,11 +234,11 @@ describe('MockProvider.getCatalogProducts — global ordering before pagination'
       pageSize: 2,
     })
 
-    expect(handles(page1)).toEqual(['aurora-jacket', 'helios-lamp'])
-    expect(handles(page2)).toEqual(['luna-bag', 'solis-dress'])
+    expect(handles(page1)).toEqual(['alpine-jacket', 'amber-dress'])
+    expect(handles(page2)).toEqual(['atlas-lamp', 'aurora-jacket'])
     if (!page1.ok || !page2.ok) return
-    expect(page1.results.total).toBe(4)
-    expect(page2.results.total).toBe(4)
+    expect(page1.results.total).toBe(39)
+    expect(page2.results.total).toBe(39)
   })
 
   it('orders by newest (fixture createdAt desc) across pages', async () => {
@@ -261,15 +287,17 @@ describe('MockProvider.getCatalogProducts — global ordering before pagination'
       pageSize: 1,
     })
 
-    expect(handles(page1)).toEqual(['aurora-jacket'])
-    expect(handles(page2)).toEqual(['helios-lamp'])
+    expect(handles(page1)).toEqual(['alpine-jacket'])
+    expect(handles(page2)).toEqual(['aurora-jacket'])
     if (!page1.ok) return
-    expect(page1.results.total).toBe(2)
+    expect(page1.results.total).toBe(17)
   })
 
   it('defaults to page 1 and the canonical page size of 50', async () => {
     const outcome = await makeProvider().getCatalogProducts({})
-    expect(handles(outcome)).toEqual(FIXTURE_ORDER)
+    const productHandles = handles(outcome)
+    expect(productHandles).toHaveLength(39)
+    expect(productHandles.slice(0, 4)).toEqual(FIXTURE_ORDER)
   })
 })
 
@@ -282,7 +310,14 @@ describe('MockProvider.getCatalogProducts — truthfulness', () => {
       collections: ['best-sellers'],
     })
 
-    expect(handles(outcome)).toEqual(['aurora-jacket'])
+    expect(handles(outcome)).toEqual([
+      'aurora-jacket',
+      'alpine-jacket',
+      'boreal-jacket',
+      'ember-jacket',
+      'meridian-jacket',
+      'vantage-jacket',
+    ])
     if (!outcome.ok) return
     expect(outcome.results.appliedFilters).toEqual({
       text: 'jacket',
@@ -353,3 +388,104 @@ describe('MockProvider.getCatalogProducts — truthfulness', () => {
     expect(outcome.error.fields).toContain('inStock')
   })
 })
+
+describe('MockProvider.getCatalogProducts — enriched demo seed (storefront-mock-demo-catalog)', () => {
+  const SEEDED_CATEGORIES = ['jackets', 'dresses', 'home', 'accessories']
+  const SEEDED_COLLECTIONS = ['new-arrivals', 'best-sellers', 'studio-essentials']
+
+  it('seeds every category with 8-12 products', async () => {
+    const provider = makeProvider()
+
+    for (const category of SEEDED_CATEGORIES) {
+      const outcome = await provider.getCatalogProducts({ categories: [category] })
+      if (!outcome.ok) throw new Error(outcome.error.message)
+      expect(outcome.results.total).toBeGreaterThanOrEqual(8)
+      expect(outcome.results.total).toBeLessThanOrEqual(12)
+      // The default page size (50) holds the whole category, so page length
+      // equals the real match count.
+      expect(outcome.results.products.length).toBe(outcome.results.total)
+    }
+  })
+
+  it('mints unique handles, ids, and titles across the whole seed', async () => {
+    const outcome = await makeProvider().getCatalogProducts({})
+    if (!outcome.ok) throw new Error(outcome.error.message)
+
+    const { products } = outcome.results
+    const handles = products.map((product) => product.handle)
+    const ids = products.map((product) => product.id)
+    const titles = products.map((product) => product.title)
+
+    expect(products.length).toBe(39)
+    expect(new Set(handles).size).toBe(handles.length)
+    expect(new Set(ids).size).toBe(ids.length)
+    expect(new Set(titles).size).toBe(titles.length)
+  })
+
+  it('spreads products across collections (each >= 2, at least one in two)', async () => {
+    const provider = makeProvider()
+
+    for (const collection of SEEDED_COLLECTIONS) {
+      const outcome = await provider.getCatalogProducts({ collections: [collection] })
+      if (!outcome.ok) throw new Error(outcome.error.message)
+      expect(outcome.results.total).toBeGreaterThanOrEqual(2)
+    }
+
+    const all = await provider.getCatalogProducts({})
+    if (!all.ok) throw new Error(all.error.message)
+    expect(
+      all.results.products.some((product) => (product.collections?.length ?? 0) >= 2),
+    ).toBe(true)
+  })
+
+  it('narrows the result set with a text query', async () => {
+    const provider = makeProvider()
+    const all = await provider.getCatalogProducts({})
+    const narrowed = await provider.getCatalogProducts({ text: 'jacket' })
+    if (!all.ok || !narrowed.ok) throw new Error('expected ok outcome')
+
+    expect(narrowed.results.total).toBeGreaterThan(0)
+    expect(narrowed.results.total ?? 0).toBeLessThan(all.results.total ?? 0)
+  })
+
+  it('produces different orderings for different sort keys', async () => {
+    const provider = makeProvider()
+    const featured = await provider.getCatalogProducts({ sort: 'featured' })
+    const name = await provider.getCatalogProducts({ sort: 'name' })
+    const newest = await provider.getCatalogProducts({ sort: 'newest' })
+    if (!featured.ok || !name.ok || !newest.ok) throw new Error('expected ok outcome')
+
+    // Featured keeps the seeded heroes first, name reorders alphabetically.
+    expect(featured.results.products[0]?.handle).toBe('aurora-jacket')
+    expect(name.results.products[0]?.handle).toBe('alpine-jacket')
+    expect(newest.results.products[0]?.handle).toBe('aurora-jacket')
+    expect(name.results.products[0]?.handle).not.toBe(
+      featured.results.products[0]?.handle,
+    )
+  })
+
+  it('returns a filtered category as a strict subset of the unfiltered catalog', async () => {
+    const provider = makeProvider()
+    const all = await provider.getCatalogProducts({})
+    const jackets = await provider.getCatalogProducts({ categories: ['jackets'] })
+    if (!all.ok || !jackets.ok) throw new Error('expected ok outcome')
+
+    const allHandles = new Set(all.results.products.map((product) => product.handle))
+    expect(jackets.results.total ?? 0).toBeLessThan(all.results.total ?? 0)
+    for (const product of jackets.results.products) {
+      expect(allHandles.has(product.handle)).toBe(true)
+      expect(product.metadata?.categoryHandle).toBe('jackets')
+    }
+  })
+
+  it('resolves a collection filter to a different set than the category filter', async () => {
+    const provider = makeProvider()
+    const jackets = await provider.getCatalogProducts({ categories: ['jackets'] })
+    const bestSellers = await provider.getCatalogProducts({
+      collections: ['best-sellers'],
+    })
+    if (!jackets.ok || !bestSellers.ok) throw new Error('expected ok outcome')
+
+    expect(handles(bestSellers)).not.toEqual(handles(jackets))
+  })
+})

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

@@ -45,3 +45,22 @@ describe('MockProvider — selected shipping option', () => {
     ).rejects.toThrow()
   })
 })
+
+describe('MockProvider — product category references', () => {
+  it('exposes the seed category reference on products', async () => {
+    const provider = new MockProvider({ currencyCode: 'USD' })
+    const products = await provider.getProducts({ first: 100 })
+    const withCategory = products.find(
+      (product) => product.categories && product.categories.length > 0,
+    )
+
+    expect(withCategory).toBeDefined()
+    expect(withCategory?.categories?.[0]).toEqual(
+      expect.objectContaining({
+        id: expect.any(String),
+        name: expect.any(String),
+        handle: expect.any(String),
+      }),
+    )
+  })
+})