@thorprovider/adapters 4.0.1 → 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,10 +1,10 @@
 {
   "name": "@thorprovider/adapters",
-  "version": "4.0.1",
+  "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",
-    "access": "restricted"
+    "access": "public"
   },
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

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/lib/auth-storage.ts

@@ -0,0 +1,101 @@
+import type { AuthConfig } from '@thorprovider/types';
+
+type StoredValue = string | null;
+
+function isBrowserStorageAvailable(): boolean {
+  return typeof window !== 'undefined';
+}
+
+function getStorage(config: AuthConfig): Storage | null {
+  if (!isBrowserStorageAvailable()) {
+    return null;
+  }
+
+  switch (config.storage) {
+    case 'localStorage':
+      return window.localStorage;
+    case 'sessionStorage':
+      return window.sessionStorage;
+    default:
+      return null;
+  }
+}
+
+export class AuthStorage {
+  private memory = new Map<string, string>();
+
+  constructor(
+    private readonly config: AuthConfig,
+    private readonly namespace: string,
+  ) {}
+
+  private key(suffix: string): string {
+    return `${this.namespace}:${suffix}`;
+  }
+
+  async getString(suffix: string): Promise<StoredValue> {
+    const key = this.key(suffix);
+
+    if (this.config.customStorage) {
+      return (await this.config.customStorage.getItem(key)) ?? null;
+    }
+
+    const browserStorage = getStorage(this.config);
+    if (browserStorage) {
+      return browserStorage.getItem(key);
+    }
+
+    return this.memory.get(key) ?? null;
+  }
+
+  async setString(suffix: string, value: string): Promise<void> {
+    const key = this.key(suffix);
+
+    if (this.config.customStorage) {
+      await this.config.customStorage.setItem(key, value);
+      return;
+    }
+
+    const browserStorage = getStorage(this.config);
+    if (browserStorage) {
+      browserStorage.setItem(key, value);
+      return;
+    }
+
+    this.memory.set(key, value);
+  }
+
+  async remove(suffix: string): Promise<void> {
+    const key = this.key(suffix);
+
+    if (this.config.customStorage) {
+      await this.config.customStorage.removeItem(key);
+      return;
+    }
+
+    const browserStorage = getStorage(this.config);
+    if (browserStorage) {
+      browserStorage.removeItem(key);
+      return;
+    }
+
+    this.memory.delete(key);
+  }
+
+  async getJson<T>(suffix: string): Promise<T | null> {
+    const value = await this.getString(suffix);
+    if (!value) {
+      return null;
+    }
+
+    try {
+      return JSON.parse(value) as T;
+    } catch {
+      return null;
+    }
+  }
+
+  async setJson(suffix: string, value: unknown): Promise<void> {
+    await this.setString(suffix, JSON.stringify(value));
+  }
+}

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';