@thorprovider/adapters 4.1.0 → 4.2.0

package/docs/getting-started.md

@@ -1,23 +1,25 @@
-# Getting Started
-
 ---
+title: "Getting started"
+purpose: "Provide a quick setup guide for integrating Thor adapters in mock or live backend mode"
+lastReviewed: "2026-05-01"
 type: how-to
 tags: [setup, installation, adapters, medusa, configuration]
 related:
   - services-overview.md
   - providers-overview.md
   - authentication.md
-updated: 2026-02-28
 ---
 
-Quick setup guide for integrating Thor adapters into our project.
+# Getting Started
+
+Quick setup guide for integrating Thor adapters into our project. Start with `mock` for backend-optional development, or configure a real backend immediately.
 
 ## Prerequisites
 
 - Node.js 18+
 - Yarn 4+ (PnP mode)
-- Access to a Medusa.js v2 backend
-- Medusa Publishable API Key
+- Optional: access to a Medusa.js v2 backend
+- Optional: Medusa Publishable API Key
 
 ## Quick Example
 
@@ -25,6 +27,14 @@ Quick setup guide for integrating Thor adapters into our project.
 import { createProvider } from '@thorprovider/adapters';
 
 const commerce = createProvider({
+  provider: 'mock',
+  config: {
+    currencyCode: 'USD',
+  },
+});
+
+// Or use a real backend
+const liveCommerce = createProvider({
   provider: 'medusa',
   config: {
     baseUrl: process.env.NEXT_PUBLIC_COMMERCE_API_URL!,
@@ -53,6 +63,14 @@ Create a shared instance for our application.
 import { createProvider } from '@thorprovider/adapters';
 
 export const commerce = createProvider({
+  provider: 'mock',
+  config: {
+    debug: process.env.NODE_ENV === 'development',
+  },
+});
+
+// Switch to a real backend when ready
+export const liveCommerce = createProvider({
   provider: 'medusa',
   config: {
     baseUrl: process.env.NEXT_PUBLIC_COMMERCE_API_URL!,
@@ -64,14 +82,17 @@ export const commerce = createProvider({
 
 ### Step 3: Configure Environment Variables
 
-Create `.env.local` to store backend credentials.
+Create `.env.local` to store runtime configuration.
 
 ```env
-# Backend Configuration
-NEXT_PUBLIC_COMMERCE_PROVIDER=medusa
+# Mock-first configuration
+NEXT_PUBLIC_COMMERCE_PROVIDER=mock
+NEXT_PUBLIC_DEFAULT_CURRENCY=USD
+
+# Live backend configuration (only required for real providers)
+# NEXT_PUBLIC_COMMERCE_PROVIDER=medusa
 NEXT_PUBLIC_COMMERCE_API_URL=http://localhost:9000
 NEXT_PUBLIC_COMMERCE_API_KEY=your_publishable_key_here
-NEXT_PUBLIC_DEFAULT_CURRENCY=USD
 ```
 
 ### Step 4: Use in Server Components (Next.js)
@@ -96,7 +117,7 @@ export default async function ProductsPage() {
 ## ✅ DO's
 
 1. **Use Singleton Pattern:** Create one instance of the provider and export it.
-2. **Handle Environment Variables:** Always use `!` or validation to ensure `baseUrl` exists.
+2. **Handle Environment Variables:** Require `baseUrl` only for real backends.
 3. **Prefer Server-Side:** Fetch data in Server Components whenever possible.
 4. **Use TypeScript Types:** Leverage the exported types from `@thorprovider/adapters` for better DX.
 5. **Configure Debug Mode:** Enable `debug: true` during development to trace API issues.

package/docs/providers-overview.md

@@ -1,15 +1,17 @@
-# Providers Overview
-
 ---
+title: "Providers overview"
+purpose: "Describe the supported commerce providers and how Thor Adapters abstracts them behind a unified interface"
+lastReviewed: "2026-05-01"
 type: guide
 tags: [architecture, providers, medusa, shopify, roadmap]
 related:
   - capabilities-system.md
   - services-overview.md
   - getting-started.md
-updated: 2026-02-28
 ---
 
+# Providers Overview
+
 Overview of the e-commerce platforms supported by Thor Adapters and how they are abstracted into a unified interface.
 
 ## Overview
@@ -28,6 +30,10 @@ Thor Adapters eliminate these problems by wrapping the data layer in a consisten
 
 ## Current Support Matrix
 
+### Mock
+**Status:** ✅ Production Ready
+Fixture-backed provider for local development, previews, design-mode storefront work, and backend-optional scaffolds.
+
 ### Medusa (v2.0)
 **Status:** ✅ Production Ready
 Our primary integration, highly optimized for headless performance.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thorprovider/adapters",
-  "version": "4.1.0",
+  "version": "4.2.0",
   "description": "Framework-agnostic commerce adapters for Thor Commerce ecosystem - Multi-platform support with unified API",
   "publishConfig": {
     "registry": "https://registry.npmjs.org",

package/src/factory/index.ts

@@ -17,6 +17,7 @@ import { BigCommerceProvider, type BigCommerceProviderConfig } from '../provider
 import { WooCommerceProvider, type WooCommerceProviderConfig } from '../providers/woocommerce';
 import { SpreeProvider, type SpreeProviderConfig } from '../providers/spree';
 import { MagentoProvider, type MagentoProviderConfig } from '../providers/magento';
+import { MockProvider, type MockProviderConfig } from '../providers/mock';
 import { ProviderNotFoundError, ConfigurationError } from '../core/errors';
 import type { ProviderTypeString } from '@thorprovider/types';
 
@@ -30,6 +31,7 @@ export type ProviderType = ProviderTypeString;
  * Provider configuration discriminated union
  */
 export type ProviderFactoryConfig =
+  | { provider: 'mock'; config: MockProviderConfig }
   | { provider: 'medusa'; config: MedusaProviderConfig }
   | { provider: 'shopify'; config: ShopifyProviderConfig }
   | { provider: 'bigcommerce'; config: BigCommerceProviderConfig }
@@ -73,6 +75,8 @@ export function createProvider(options: ProviderFactoryConfig | RuntimeProviderC
   const config = options.config as any;
   
   switch (options.provider) {
+    case 'mock':
+      return new MockProvider(config);
     case 'medusa':
       return new MedusaProvider(config);
     case 'shopify':

package/src/index.ts

@@ -38,6 +38,7 @@ export {
 // Capabilities
 // ============================================
 export {
+  MOCK_CAPABILITIES,
   MEDUSA_CAPABILITIES,
   SHOPIFY_CAPABILITIES,
   BIGCOMMERCE_CAPABILITIES,
@@ -192,6 +193,8 @@ export {
 export {
   MedusaProvider,
   type MedusaProviderConfig,
+  MockProvider,
+  type MockProviderConfig,
   ShopifyProvider,
   type ShopifyProviderConfig,
   BigCommerceProvider,

package/src/providers/index.ts

@@ -20,3 +20,6 @@ export type { SpreeProviderConfig } from './spree';
 
 export { MagentoProvider } from './magento';
 export type { MagentoProviderConfig } from './magento';
+
+export { MockProvider } from './mock';
+export type { MockProviderConfig } from './mock';

package/src/providers/mock/index.ts

@@ -0,0 +1,427 @@
+import type {
+  Cart,
+  CartLineInput,
+  CartLineUpdate,
+  Collection,
+  CollectionProductsOptions,
+  GetCategoriesOptions,
+  GetCollectionsOptions,
+  GetOrdersOptions,
+  GetProductsOptions,
+  InventoryLevel,
+  Order,
+  PaymentMethodsOptions,
+  Product,
+  ProductCategory,
+  Region,
+  ShippingMethod,
+  StockLocation,
+  StockValidation,
+  StorefrontContext,
+  FulfillmentOption,
+  PaymentMethod,
+} from '@thorprovider/types';
+import type { CommerceProvider, ProviderConfig } from '../../types/provider';
+import { ProviderAPIError, ResourceNotFoundError } from '../../core/errors';
+import { MOCK_CAPABILITIES } from '../../types/capabilities.types';
+import {
+  buildMockCart,
+  completeMockCheckout,
+  createMockCart,
+  getMockAdminOrders,
+  getMockAdminRegions,
+  getMockCategories,
+  getMockCategory,
+  getMockCollection,
+  getMockCollections,
+  getMockCartState,
+  getMockFulfillmentOptions,
+  getMockInventoryLevels,
+  getMockOrder,
+  getMockPaymentMethods,
+  getMockProduct,
+  getMockProductRecommendations,
+  getMockProducts,
+  getMockRegionCountries,
+  getMockRegions,
+  getMockShippingMethods,
+  getMockStockLocations,
+  saveMockCartState,
+  saveMockOrder,
+  validateMockCartStock,
+} from './mock';
+
+export interface MockProviderConfig extends ProviderConfig {
+  currencyCode?: string;
+  siteUrl?: string;
+}
+
+export class MockProvider implements CommerceProvider {
+  readonly name = 'mock';
+  readonly version = '1.0.0';
+  readonly capabilities = MOCK_CAPABILITIES;
+  readonly isMock = true;
+
+  private readonly currencyCode: string;
+  private readonly siteUrl: string;
+
+  constructor(config: MockProviderConfig = {}) {
+    this.currencyCode = config.currencyCode ?? 'USD';
+    this.siteUrl = config.siteUrl ?? 'https://mock.thorcommerce.local';
+  }
+
+  private hasVariant(merchandiseId: string, regionId?: string): boolean {
+    return getMockProducts({
+      currencyCode: this.currencyCode,
+      regionId,
+    }).some((product) =>
+      product.variants.some((variant) => variant.id === merchandiseId)
+    );
+  }
+
+  async getProduct(handle: string, options?: { regionId?: string }): Promise<Product | undefined> {
+    return getMockProduct(handle, options?.regionId);
+  }
+
+  async getProducts(options?: GetProductsOptions): Promise<Product[]> {
+    return getMockProducts({
+      currencyCode: this.currencyCode,
+      query: options?.query,
+      sortKey: options?.sortKey,
+      reverse: options?.reverse,
+      first: options?.first,
+      skip: options?.skip,
+      categoryIds: options?.categoryIds,
+      collectionIds: options?.collectionIds,
+      regionId: options?.regionId,
+    });
+  }
+
+  async getProductRecommendations(productId: string): Promise<Product[]> {
+    return getMockProductRecommendations(productId);
+  }
+
+  async getCollection(handle: string): Promise<Collection | undefined> {
+    return getMockCollection(handle);
+  }
+
+  async getCollections(options?: GetCollectionsOptions): Promise<Collection[]> {
+    const collections = getMockCollections();
+    const query = options?.query?.trim().toLowerCase();
+    const filtered = query
+      ? collections.filter((collection) =>
+          [collection.title, collection.description, collection.handle]
+            .join(' ')
+            .toLowerCase()
+            .includes(query)
+        )
+      : collections;
+
+    return filtered.slice(0, options?.limit ?? filtered.length);
+  }
+
+  async getCollectionProducts(handle: string, options?: CollectionProductsOptions): Promise<Product[]> {
+    const collection = getMockCollection(handle);
+    if (!collection) {
+      return [];
+    }
+
+    return getMockProducts({
+      currencyCode: this.currencyCode,
+      collectionIds: [collection.id],
+      sortKey: options?.sortKey,
+      reverse: options?.reverse,
+      first: options?.first,
+    });
+  }
+
+  async getCategory(idOrHandle: string): Promise<ProductCategory | undefined> {
+    return getMockCategory(idOrHandle);
+  }
+
+  async getCategories(options?: GetCategoriesOptions): Promise<ProductCategory[]> {
+    const categories = getMockCategories();
+    const query = options?.query?.trim().toLowerCase();
+
+    let filtered = query
+      ? categories.filter((category) =>
+          [category.name, category.description ?? '', category.handle]
+            .join(' ')
+            .toLowerCase()
+            .includes(query)
+        )
+      : categories;
+
+    if (options?.parentCategoryId) {
+      filtered = filtered.filter((category) => category.parentCategoryId === options.parentCategoryId);
+    }
+
+    return filtered.slice(0, options?.limit ?? filtered.length);
+  }
+
+  async getCategoryProducts(handle: string, options?: CollectionProductsOptions): Promise<Product[]> {
+    const category = getMockCategory(handle);
+    if (!category) {
+      return [];
+    }
+
+    return getMockProducts({
+      currencyCode: this.currencyCode,
+      categoryIds: [category.id],
+      sortKey: options?.sortKey,
+      reverse: options?.reverse,
+      first: options?.first,
+    });
+  }
+
+  async createCart(options?: { regionId?: string }): Promise<Cart> {
+    const cart = createMockCart(options?.regionId);
+    return buildMockCart(cart, this.currencyCode, this.siteUrl);
+  }
+
+  async getCart(cartId: string): Promise<Cart | undefined> {
+    const cart = getMockCartState(cartId);
+    return cart ? buildMockCart(cart, this.currencyCode, this.siteUrl) : undefined;
+  }
+
+  async addToCart(cartId: string, lines: CartLineInput[]): Promise<Cart> {
+    const cart = getMockCartState(cartId);
+    if (!cart) {
+      throw new ResourceNotFoundError('cart', cartId);
+    }
+
+    for (const line of lines) {
+      if (!this.hasVariant(line.merchandiseId, cart.regionId)) {
+        throw new ResourceNotFoundError('variant', line.merchandiseId);
+      }
+    }
+
+    const nextLines = [...cart.lines];
+    for (const line of lines) {
+      const existing = nextLines.find((item) => item.merchandiseId === line.merchandiseId);
+      if (existing) {
+        existing.quantity += line.quantity;
+      } else {
+        nextLines.push({
+          id: `mock-line-${line.merchandiseId}`,
+          merchandiseId: line.merchandiseId,
+          quantity: line.quantity,
+        });
+      }
+    }
+
+    const saved = saveMockCartState({ ...cart, lines: nextLines });
+    return buildMockCart(saved, this.currencyCode, this.siteUrl);
+  }
+
+  async removeFromCart(cartId: string, lineIds: string[]): Promise<Cart> {
+    const cart = getMockCartState(cartId);
+    if (!cart) {
+      throw new ResourceNotFoundError('cart', cartId);
+    }
+
+    const saved = saveMockCartState({
+      ...cart,
+      lines: cart.lines.filter((line) => !lineIds.includes(line.id)),
+    });
+
+    return buildMockCart(saved, this.currencyCode, this.siteUrl);
+  }
+
+  async updateCart(cartId: string, lines: CartLineUpdate[]): Promise<Cart> {
+    const cart = getMockCartState(cartId);
+    if (!cart) {
+      throw new ResourceNotFoundError('cart', cartId);
+    }
+
+    for (const line of lines) {
+      if (!this.hasVariant(line.merchandiseId, cart.regionId)) {
+        throw new ResourceNotFoundError('variant', line.merchandiseId);
+      }
+    }
+
+    const updates = new Map(lines.map((line) => [line.id, line]));
+    const nextLines = cart.lines
+      .map((line) => {
+        const update = updates.get(line.id);
+        if (!update) {
+          return line;
+        }
+
+        return {
+          ...line,
+          merchandiseId: update.merchandiseId,
+          quantity: update.quantity,
+        };
+      })
+      .filter((line) => line.quantity > 0);
+
+    const saved = saveMockCartState({ ...cart, lines: nextLines });
+    return buildMockCart(saved, this.currencyCode, this.siteUrl);
+  }
+
+  async getRegions(): Promise<Array<{ id: string; name: string; currency_code: string; countries?: Array<{ id: string; iso_2: string; name: string; display_name?: string }> }>> {
+    return getMockRegions();
+  }
+
+  async completeCheckout(cartId: string): Promise<Order> {
+    const cart = getMockCartState(cartId);
+    if (!cart) {
+      throw new ResourceNotFoundError('cart', cartId);
+    }
+
+    const order = completeMockCheckout(cart, this.currencyCode, this.siteUrl);
+    return order;
+  }
+
+  async getShippingMethods(cartId: string): Promise<ShippingMethod[]> {
+    const cart = getMockCartState(cartId);
+    return getMockShippingMethods(cart?.regionId);
+  }
+
+  async getRegionCountries(regionId: string) {
+    return getMockRegionCountries(regionId);
+  }
+
+  async addShippingMethod(cartId: string, methodId: string): Promise<Cart> {
+    const cart = getMockCartState(cartId);
+    if (!cart) {
+      throw new ResourceNotFoundError('cart', cartId);
+    }
+
+    const allowed = getMockShippingMethods(cart.regionId).some((method) => method.id === methodId);
+    if (!allowed) {
+      throw new ProviderAPIError(`Unknown mock shipping method: ${methodId}`, 'mock', 400);
+    }
+
+    const saved = saveMockCartState({ ...cart, shippingMethodId: methodId });
+    return buildMockCart(saved, this.currencyCode, this.siteUrl);
+  }
+
+  async initiatePaymentSession(cartId: string, providerId: string): Promise<void> {
+    const cart = getMockCartState(cartId);
+    if (!cart) {
+      throw new ResourceNotFoundError('cart', cartId);
+    }
+
+    const allowed = getMockPaymentMethods(this.currencyCode).some((method) => method.id === providerId);
+    if (!allowed) {
+      throw new ProviderAPIError(`Unknown mock payment method: ${providerId}`, 'mock', 400);
+    }
+
+    saveMockCartState({ ...cart, paymentProviderId: providerId });
+  }
+
+  async applyDiscountCode(cartId: string, code: string): Promise<Cart> {
+    const cart = getMockCartState(cartId);
+    if (!cart) {
+      throw new ResourceNotFoundError('cart', cartId);
+    }
+
+    const normalized = code.trim();
+    if (!normalized) {
+      throw new ProviderAPIError('Discount code is required.', 'mock', 400);
+    }
+
+    const saved = saveMockCartState({ ...cart, discountCode: normalized });
+    return buildMockCart(saved, this.currencyCode, this.siteUrl);
+  }
+
+  async removeDiscountCode(cartId: string, _code: string): Promise<Cart> {
+    const cart = getMockCartState(cartId);
+    if (!cart) {
+      throw new ResourceNotFoundError('cart', cartId);
+    }
+
+    const saved = saveMockCartState({ ...cart, discountCode: undefined });
+    return buildMockCart(saved, this.currencyCode, this.siteUrl);
+  }
+
+  async getOrders(_options: GetOrdersOptions): Promise<Order[]> {
+    return getMockAdminOrders().orders;
+  }
+
+  async getPaymentMethods(options: PaymentMethodsOptions): Promise<PaymentMethod[]> {
+    return getMockPaymentMethods(options.currencyCode ?? this.currencyCode);
+  }
+
+  async getStockLocations(): Promise<StockLocation[]> {
+    return getMockStockLocations();
+  }
+
+  async checkInventoryLevels(variantId: string): Promise<InventoryLevel[]> {
+    return getMockInventoryLevels(variantId);
+  }
+
+  async validateCartStock(cartId: string): Promise<StockValidation> {
+    const cart = getMockCartState(cartId);
+    if (!cart) {
+      throw new ResourceNotFoundError('cart', cartId);
+    }
+
+    return validateMockCartStock(cart);
+  }
+
+  async getFulfillmentOptions(cartId: string, _salesChannelId: string): Promise<FulfillmentOption[]> {
+    const cart = getMockCartState(cartId);
+    return getMockFulfillmentOptions(cart?.regionId);
+  }
+
+  async cancelOrder(orderId: string): Promise<Order> {
+    const order = getMockOrder(orderId);
+    if (!order) {
+      throw new ResourceNotFoundError('order', orderId);
+    }
+
+    return saveMockOrder({
+      ...order,
+      status: 'cancelled',
+      updatedAt: new Date().toISOString(),
+      cancelledAt: new Date().toISOString(),
+    });
+  }
+
+  async createFulfillment(_orderId: string, _items?: Array<{ id: string; quantity: number }>): Promise<void> {
+    return;
+  }
+
+  async createRefund(orderId: string, _amount?: number, _reason?: string): Promise<void> {
+    const order = getMockOrder(orderId);
+    if (!order) {
+      throw new ResourceNotFoundError('order', orderId);
+    }
+
+    saveMockOrder({
+      ...order,
+      status: 'refunded',
+      paymentStatus: 'refunded',
+      updatedAt: new Date().toISOString(),
+    });
+  }
+
+  async getAdminOrders(): Promise<{ orders: Order[]; count: number }> {
+    return getMockAdminOrders();
+  }
+
+  async getAdminRegions(): Promise<Region[]> {
+    return getMockAdminRegions();
+  }
+
+  async getStorefrontContext(): Promise<StorefrontContext> {
+    return {
+      id: 'mock-storefront',
+      name: 'Mock Storefront',
+      platformType: 'mock',
+      requiresProductScoping: false,
+      currencyCode: this.currencyCode,
+      locale: 'en-US',
+      metadata: {
+        mode: 'design',
+      },
+    };
+  }
+
+  isStorefrontRequired(): boolean {
+    return false;
+  }
+}