@thorprovider/adapters 3.0.2

package/src/admin/MetricsService.ts

@@ -0,0 +1,145 @@
+/**
+ * Metrics Calculation Service
+ * 
+ * Framework-agnostic business logic for calculating dashboard metrics
+ * from raw order and product data.
+ * 
+ * @remarks
+ * - L2: Pure business logic, no framework dependencies
+ * - Works with @thorprovider/types Order and Product interfaces
+ * - Stateless static methods for easy testing
+ * 
+ * @module admin/MetricsService
+ */
+
+import type { DashboardMetrics, ChartDataPoint } from '@thorprovider/types';
+
+/**
+ * Raw order data for metrics calculation
+ * 
+ * @remarks
+ * Minimal interface to avoid coupling to specific Order type fields.
+ * Accepts the common fields available across all commerce providers.
+ */
+export interface MetricsOrderInput {
+  total?: number;
+  status?: string;
+  created_at?: string;
+  createdAt?: string;
+}
+
+/**
+ * Raw product data for metrics calculation
+ */
+export interface MetricsProductInput {
+  id: string;
+  variants?: Array<{
+    quantityAvailable?: number;
+  }>;
+}
+
+/**
+ * Metrics Service
+ * 
+ * Calculates dashboard analytics from raw commerce data.
+ * All methods are static and pure (no side effects).
+ */
+export class MetricsService {
+  /** Threshold for low stock alerts */
+  static readonly LOW_STOCK_THRESHOLD = 10;
+
+  /**
+   * Calculate complete dashboard metrics from orders and products
+   * 
+   * @param orders - Array of order data
+   * @param products - Array of product data
+   * @returns Calculated DashboardMetrics
+   */
+  static calculate(
+    orders: MetricsOrderInput[],
+    products: MetricsProductInput[],
+  ): DashboardMetrics {
+    const now = new Date();
+    const today = new Date(now.getFullYear(), now.getMonth(), now.getDate());
+    const weekAgo = new Date(today.getTime() - 7 * 24 * 60 * 60 * 1000);
+    const monthAgo = new Date(today.getTime() - 30 * 24 * 60 * 60 * 1000);
+
+    // Calculate sales
+    const totalSales = orders.reduce((sum, o) => sum + (o.total || 0), 0);
+    const todaySales = orders
+      .filter((o) => new Date(o.created_at || o.createdAt || '') >= today)
+      .reduce((sum, o) => sum + (o.total || 0), 0);
+    const weekSales = orders
+      .filter((o) => new Date(o.created_at || o.createdAt || '') >= weekAgo)
+      .reduce((sum, o) => sum + (o.total || 0), 0);
+    const monthSales = orders
+      .filter((o) => new Date(o.created_at || o.createdAt || '') >= monthAgo)
+      .reduce((sum, o) => sum + (o.total || 0), 0);
+
+    // Calculate orders by status
+    const ordersByStatus = {
+      total: orders.length,
+      pending: orders.filter((o) => o.status === 'pending').length,
+      processing: orders.filter((o) => o.status === 'processing').length,
+      completed: orders.filter((o) => o.status === 'completed').length,
+    };
+
+    // Calculate products
+    const lowStockCount = products.filter((p) => {
+      const totalQty = (p.variants || []).reduce(
+        (sum, v) => sum + (v.quantityAvailable || 0),
+        0,
+      );
+      return totalQty < MetricsService.LOW_STOCK_THRESHOLD;
+    }).length;
+
+    const productsMetrics = {
+      total: products.length,
+      lowStock: lowStockCount,
+    };
+
+    // Generate chart data (last 7 days)
+    const chartData = MetricsService.generateChartData(orders, today);
+
+    return {
+      sales: {
+        total: totalSales,
+        today: todaySales,
+        week: weekSales,
+        month: monthSales,
+      },
+      orders: ordersByStatus,
+      products: productsMetrics,
+      chartData,
+    };
+  }
+
+  /**
+   * Generate chart data for the last 7 days
+   */
+  private static generateChartData(
+    orders: MetricsOrderInput[],
+    today: Date,
+  ): ChartDataPoint[] {
+    const chartData: ChartDataPoint[] = [];
+
+    for (let i = 6; i >= 0; i--) {
+      const date = new Date(today.getTime() - i * 24 * 60 * 60 * 1000);
+      const nextDate = new Date(date.getTime() + 24 * 60 * 60 * 1000);
+
+      const daySales = orders
+        .filter((o) => {
+          const orderDate = new Date(o.created_at || o.createdAt || '');
+          return orderDate >= date && orderDate < nextDate;
+        })
+        .reduce((sum, o) => sum + (o.total || 0), 0);
+
+      chartData.push({
+        date: date.toISOString().split('T')[0],
+        sales: daySales,
+      });
+    }
+
+    return chartData;
+  }
+}

package/src/admin/index.ts

@@ -0,0 +1,13 @@
+/**
+ * Admin Services
+ * 
+ * Central export point for all admin-related services.
+ * 
+ * @module admin
+ */
+
+export { AdminAuthService } from './AdminAuthService';
+export { AdminSessionService } from './AdminSessionService';
+export type { AdminSession } from './AdminSessionService';
+export { MetricsService } from './MetricsService';
+export type { MetricsOrderInput, MetricsProductInput } from './MetricsService';

package/src/backend/BackendMetadataAdapter.ts

@@ -0,0 +1,88 @@
+/**
+ * Backend Metadata Adapter Interface
+ * 
+ * Framework-agnostic interface for storing configuration in backend metadata fields.
+ * This replaces the need for a separate database (SQLite/Supabase).
+ * 
+ * Each backend (Medusa, Shopify, WordPress) implements this interface
+ * using their native metadata/metafields/postmeta capabilities.
+ * 
+ * @module backend/BackendMetadataAdapter
+ */
+
+/**
+ * Backend Metadata Adapter
+ * 
+ * @remarks
+ * Supported resource types by backend:
+ * - Medusa: `'sales_channel'`, `'customer'`, `'order'` (via admin API)
+ * - Shopify: Uses metafields API (TBD)
+ * - WordPress: Uses post_meta or user_meta (TBD)
+ * 
+ * Multi-tenant channel scoping:
+ * Use with `'customer'` / `'order'` resource types and the well-known key
+ * `'sales_channel_id'` to tag entities to a specific sales channel.
+ * See `@thorprovider/adapters/metadata/channel-scope` for helper utilities.
+ * 
+ * @example
+ * ```typescript
+ * // Store site configuration in Medusa sales channel metadata
+ * await adapter.setMetadata(
+ *   'sales_channel',
+ *   'sc_01HXXX',
+ *   'site_config',
+ *   { version: '2026-03-25', config: {...} }
+ * );
+ * 
+ * // Tag a customer to a sales channel (multi-tenant)
+ * await adapter.setMetadata(
+ *   'customer',
+ *   'cus_01HXXX',
+ *   'sales_channel_id',
+ *   'sc_01HXXX'
+ * );
+ * ```
+ */
+export interface BackendMetadataAdapter {
+  /**
+   * Get metadata value from backend resource
+   * 
+   * @param resourceType - Type of resource (`'sales_channel'` | `'customer'` | `'order'` | `'store'`)
+   * @param resourceId - ID of the resource
+   * @param key - Metadata key (e.g., `'site_config'`, `'sales_channel_id'`)
+   * @returns Metadata value or null if not found
+   */
+  getMetadata(
+    resourceType: string,
+    resourceId: string,
+    key: string
+  ): Promise<any | null>;
+
+  /**
+   * Set metadata value on backend resource
+   * 
+   * @param resourceType - Type of resource
+   * @param resourceId - ID of the resource
+   * @param key - Metadata key
+   * @param value - Metadata value (will be JSON serialized)
+   */
+  setMetadata(
+    resourceType: string,
+    resourceId: string,
+    key: string,
+    value: any
+  ): Promise<void>;
+
+  /**
+   * Delete metadata key from backend resource
+   * 
+   * @param resourceType - Type of resource
+   * @param resourceId - ID of the resource
+   * @param key - Metadata key
+   */
+  deleteMetadata(
+    resourceType: string,
+    resourceId: string,
+    key: string
+  ): Promise<void>;
+}

package/src/backend/factory.ts

@@ -0,0 +1,107 @@
+/**
+ * Backend Metadata Adapter Factory
+ *
+ * Framework-agnostic factory to create backend metadata adapters for admin/dashboard.
+ * Keeps vendor-specific code in L2, prevents lock-in in L5.
+ *
+ * @remarks
+ * This factory is distinct from the main provider factory (createProvider).
+ * It's used for admin operations that require metadata/catalog access.
+ * Provider types are imported from @thorprovider/types (L1) to maintain sync.
+ *
+ * @module backend/factory
+ */
+
+import Medusa from '@medusajs/js-sdk';
+import { MedusaMetadataAdapter } from './medusa/MedusaMetadataAdapter';
+import type { BackendMetadataAdapter } from './BackendMetadataAdapter';
+import type { ProviderTypeString } from '@thorprovider/types';
+
+/**
+ * Configuration for creating a backend metadata adapter
+ *
+ * @remarks
+ * Currently only 'medusa' is implemented. When adding Shopify/WooCommerce metadata adapters:
+ * 1. Uncomment the provider type in packages/types/src/provider.ts
+ * 2. Update this interface to accept the new provider type
+ * 3. Implement ShopifyMetadataAdapter, WooCommerceMetadataAdapter
+ * 4. Add cases to createBackendMetadataAdapter() switch
+ */
+export interface BackendMetadataAdapterConfig {
+  /** Backend provider type (from @thorprovider/types L1) */
+  provider: ProviderTypeString;
+  
+  /** Backend base URL */
+  baseUrl: string;
+  
+  /** Publishable API key (for storefront access) */
+  publishableKey?: string;
+  
+  /** Enable debug logging */
+  debug?: boolean;
+
+  /**
+   * Secret admin API key (from COMMERCE_ADMIN_API_KEY).
+   * When provided, the metadata adapter SDK instance will send
+   * `x-medusa-access-token` header on all admin requests.
+   * Required for getMetadata/setMetadata to work after removing email/password auth.
+   */
+  adminApiKey?: string;
+}
+
+/**
+ * Create a backend metadata adapter (Factory Pattern)
+ * 
+ * Keeps vendor-specific code in L2, prevents lock-in in L5.
+ * L5 only provides configuration from env vars.
+ * 
+ * @param config - Adapter configuration
+ * @returns BackendMetadataAdapter instance
+ * 
+ * @example
+ * ```typescript
+ * // In L5 (starters)
+ * import { createBackendMetadataAdapter } from '@thorprovider/adapters';
+ * 
+ * export const metadataAdapter = createBackendMetadataAdapter({
+ *   provider: process.env.NEXT_PUBLIC_COMMERCE_PROVIDER as any,
+ *   baseUrl: process.env.NEXT_PUBLIC_COMMERCE_API_URL!,
+ *   publishableKey: process.env.NEXT_PUBLIC_COMMERCE_API_KEY!,
+ * });
+ * ```
+ * 
+ * @throws {Error} If provider is not supported
+ */
+export function createBackendMetadataAdapter(
+  config: BackendMetadataAdapterConfig
+): BackendMetadataAdapter {
+  const { provider, baseUrl, publishableKey, debug } = config;
+
+  if (provider === 'medusa') {
+    const { adminApiKey } = config;
+
+    // Create Medusa SDK client instance
+    const medusa = new Medusa({
+      baseUrl,
+      publishableKey,
+      debug: debug ?? false,
+      // When adminApiKey is provided: sends x-medusa-access-token on all requests.
+      // When not provided: requests are unauthenticated — admin routes will 401.
+      ...(adminApiKey && { apiKey: adminApiKey }),
+    });
+
+    return new MedusaMetadataAdapter(medusa);
+  }
+
+  if (provider === 'shopify') {
+    // TODO: Implement Shopify metadata adapter
+    throw new Error('Shopify metadata adapter not yet implemented');
+  }
+
+  if (provider === 'woocommerce') {
+    // TODO: Implement WooCommerce metadata adapter
+    throw new Error('WooCommerce metadata adapter not yet implemented');
+  }
+
+  throw new Error(`Unsupported provider: ${provider}`);
+}

package/src/backend/index.ts

@@ -0,0 +1,12 @@
+/**
+ * Backend Metadata Adapters
+ * 
+ * Central export point for all backend metadata adapters.
+ * Framework-agnostic factory pattern to prevent vendor lock-in in L5.
+ * 
+ * @module backend
+ */
+
+export * from './BackendMetadataAdapter';
+export * from './factory';
+export * from './medusa/MedusaMetadataAdapter';

package/src/backend/medusa/MedusaMetadataAdapter.ts

@@ -0,0 +1,139 @@
+/**
+ * Medusa Metadata Adapter
+ * 
+ * Implementation of BackendMetadataAdapter for Medusa.js v2.
+ * Uses Medusa's native metadata fields on sales_channel, customer, and order resources.
+ * 
+ * Supported resource types:
+ * - `'sales_channel'` — site config, channel-level settings
+ * - `'customer'`       — multi-tenant scoping (`sales_channel_id` key)
+ * - `'order'`          — multi-tenant scoping (`sales_channel_id` key)
+ * 
+ * All operations require admin-level JWT authentication.
+ * 
+ * @module backend/medusa/MedusaMetadataAdapter
+ */
+
+import type Medusa from '@medusajs/js-sdk';
+import type { BackendMetadataAdapter } from '../BackendMetadataAdapter';
+
+/**
+ * Medusa Metadata Adapter
+ * 
+ * @remarks
+ * - Supports 'sales_channel' and 'store' resource types
+ * - Uses Medusa admin API (requires admin token)
+ * - Metadata is stored as JSON in the metadata field
+ * 
+ * @example
+ * ```typescript
+ * const adapter = new MedusaMetadataAdapter(medusaClient);
+ * 
+ * // Store site configuration
+ * await adapter.setMetadata(
+ *   'sales_channel',
+ *   'sc_01HXXX',
+ *   'site_config',
+ *   { version: '2026-03-25', config: {...} }
+ * );
+ * ```
+ */
+export class MedusaMetadataAdapter implements BackendMetadataAdapter {
+  constructor(private sdk: Medusa) {}
+
+  /**
+   * Get metadata value from Medusa resource
+   */
+  async getMetadata(
+    resourceType: string,
+    resourceId: string,
+    key: string
+  ): Promise<any | null> {
+    try {
+      if (resourceType === 'sales_channel') {
+        const { sales_channel } = await this.sdk.admin.salesChannel.retrieve(
+          resourceId
+        );
+        return sales_channel.metadata?.[key] ?? null;
+      }
+
+      if (resourceType === 'customer') {
+        const result = await (this.sdk as any).admin.customer.retrieve(resourceId);
+        return result?.customer?.metadata?.[key] ?? null;
+      }
+
+      if (resourceType === 'order') {
+        const result = await (this.sdk as any).admin.order.retrieve(resourceId);
+        return result?.order?.metadata?.[key] ?? null;
+      }
+
+      // Note: Store API in Medusa v2 requires store ID
+      // Store support can be added when we have a reliable way to get the store ID
+
+      throw new Error(
+        `Unsupported resource type: ${resourceType}. ` +
+        `Supported: 'sales_channel', 'customer', 'order'.`
+      );
+    } catch (error: any) {
+      // If resource not found or metadata key doesn't exist, return null
+      if (error.response?.status === 404 || error.status === 404) {
+        return null;
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Set metadata value on Medusa resource
+   */
+  async setMetadata(
+    resourceType: string,
+    resourceId: string,
+    key: string,
+    value: any
+  ): Promise<void> {
+    if (resourceType === 'sales_channel') {
+      await this.sdk.admin.salesChannel.update(resourceId, {
+        metadata: { [key]: value },
+      });
+      return;
+    }
+
+    if (resourceType === 'customer') {
+      await (this.sdk as any).admin.customer.update(resourceId, {
+        metadata: { [key]: value },
+      });
+      return;
+    }
+
+    if (resourceType === 'order') {
+      await (this.sdk as any).admin.order.update(resourceId, {
+        metadata: { [key]: value },
+      });
+      return;
+    }
+
+    // Note: Store API in Medusa v2 requires store ID
+    // Store support can be added when we have a reliable way to get the store ID
+
+    throw new Error(
+      `Unsupported resource type: ${resourceType}. ` +
+      `Supported: 'sales_channel', 'customer', 'order'.`
+    );
+  }
+
+  /**
+   * Delete metadata key from Medusa resource
+   * 
+   * @remarks
+   * Medusa deletes metadata keys by setting them to undefined or null
+   */
+  async deleteMetadata(
+    resourceType: string,
+    resourceId: string,
+    key: string
+  ): Promise<void> {
+    // Set to null to delete the key
+    await this.setMetadata(resourceType, resourceId, key, null);
+  }
+}

package/src/core/errors.js

@@ -0,0 +1,161 @@
+"use strict";
+/**
+ * @thorprovider/adapters v2.0
+ * Core errors
+ */
+var __extends = (this && this.__extends) || (function () {
+    var extendStatics = function (d, b) {
+        extendStatics = Object.setPrototypeOf ||
+            ({ __proto__: [] } instanceof Array && function (d, b) { d.__proto__ = b; }) ||
+            function (d, b) { for (var p in b) if (Object.prototype.hasOwnProperty.call(b, p)) d[p] = b[p]; };
+        return extendStatics(d, b);
+    };
+    return function (d, b) {
+        if (typeof b !== "function" && b !== null)
+            throw new TypeError("Class extends value " + String(b) + " is not a constructor or null");
+        extendStatics(d, b);
+        function __() { this.constructor = d; }
+        d.prototype = b === null ? Object.create(b) : (__.prototype = b.prototype, new __());
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ProviderAPIError = exports.ResourceNotFoundError = exports.ConfigurationError = exports.ProviderNotFoundError = exports.CommerceError = void 0;
+exports.extractErrorMessage = extractErrorMessage;
+/**
+ * Base error class for commerce providers
+ */
+var CommerceError = /** @class */ (function (_super) {
+    __extends(CommerceError, _super);
+    function CommerceError(message, code, status) {
+        var _this = _super.call(this, message) || this;
+        _this.code = code;
+        _this.status = status;
+        _this.name = 'CommerceError';
+        return _this;
+    }
+    return CommerceError;
+}(Error));
+exports.CommerceError = CommerceError;
+/**
+ * Provider not found error
+ */
+var ProviderNotFoundError = /** @class */ (function (_super) {
+    __extends(ProviderNotFoundError, _super);
+    function ProviderNotFoundError(providerName) {
+        var _this = _super.call(this, "Provider not found: ".concat(providerName), 'PROVIDER_NOT_FOUND') || this;
+        _this.name = 'ProviderNotFoundError';
+        return _this;
+    }
+    return ProviderNotFoundError;
+}(CommerceError));
+exports.ProviderNotFoundError = ProviderNotFoundError;
+/**
+ * Configuration error
+ */
+var ConfigurationError = /** @class */ (function (_super) {
+    __extends(ConfigurationError, _super);
+    function ConfigurationError(message) {
+        var _this = _super.call(this, message, 'CONFIGURATION_ERROR') || this;
+        _this.name = 'ConfigurationError';
+        return _this;
+    }
+    return ConfigurationError;
+}(CommerceError));
+exports.ConfigurationError = ConfigurationError;
+/**
+ * Resource not found error
+ */
+var ResourceNotFoundError = /** @class */ (function (_super) {
+    __extends(ResourceNotFoundError, _super);
+    function ResourceNotFoundError(resource, identifier) {
+        var _this = _super.call(this, "".concat(resource, " not found: ").concat(identifier), 'RESOURCE_NOT_FOUND', 404) || this;
+        _this.name = 'ResourceNotFoundError';
+        return _this;
+    }
+    return ResourceNotFoundError;
+}(CommerceError));
+exports.ResourceNotFoundError = ResourceNotFoundError;
+/**
+ * API error from provider
+ */
+var ProviderAPIError = /** @class */ (function (_super) {
+    __extends(ProviderAPIError, _super);
+    function ProviderAPIError(message, provider, status) {
+        var _this = _super.call(this, message, 'PROVIDER_API_ERROR', status) || this;
+        _this.provider = provider;
+        _this.name = 'ProviderAPIError';
+        return _this;
+    }
+    return ProviderAPIError;
+}(CommerceError));
+exports.ProviderAPIError = ProviderAPIError;
+/**
+ * Extract error message from various error types
+ * Handles standard Error objects, API responses, and unknown error types
+ */
+function extractErrorMessage(error) {
+    var _a, _b, _c, _d, _e, _f;
+    // Standard Error object
+    if (error instanceof Error && error.message) {
+        // Don't return generic messages if there's more data
+        if (error.message !== 'An unknown error occurred.') {
+            return error.message;
+        }
+    }
+    // Object with message property
+    if (typeof error === 'object' && error !== null) {
+        var err = error;
+        // Check for response body (common in fetch errors)
+        if (err.body) {
+            if (typeof err.body === 'string')
+                return err.body;
+            if (err.body.message)
+                return String(err.body.message);
+            if ((_a = err.body.error) === null || _a === void 0 ? void 0 : _a.message)
+                return String(err.body.error.message);
+        }
+        // Check for response object
+        if (err.response) {
+            if ((_b = err.response.data) === null || _b === void 0 ? void 0 : _b.message)
+                return String(err.response.data.message);
+            if ((_c = err.response.data) === null || _c === void 0 ? void 0 : _c.error)
+                return String(err.response.data.error);
+            if (err.response.statusText)
+                return "".concat(err.response.status || '', " ").concat(err.response.statusText).trim();
+        }
+        // Check for data property
+        if ((_d = err.data) === null || _d === void 0 ? void 0 : _d.message)
+            return String(err.data.message);
+        if ((_e = err.data) === null || _e === void 0 ? void 0 : _e.error)
+            return String(err.data.error);
+        // Check for error property
+        if ((_f = err.error) === null || _f === void 0 ? void 0 : _f.message)
+            return String(err.error.message);
+        // Check for statusText with status code
+        if (err.status && err.statusText) {
+            return "HTTP ".concat(err.status, ": ").concat(err.statusText);
+        }
+        if (err.status && !err.statusText) {
+            return "HTTP ".concat(err.status, " Error");
+        }
+        // Check for message property (not generic)
+        if (err.message && err.message !== 'An unknown error occurred.') {
+            return String(err.message);
+        }
+        // Try to stringify the error object
+        try {
+            var stringified = JSON.stringify(error);
+            if (stringified !== '{}')
+                return stringified;
+        }
+        catch (_g) {
+            // Ignore JSON.stringify errors
+        }
+    }
+    // String error
+    if (typeof error === 'string') {
+        return error;
+    }
+    // Fallback
+    return 'An unknown error occurred';
+}