@thorprovider/adapters 3.0.2

package/src/core/logger.ts

@@ -0,0 +1,37 @@
+/**
+ * @thorprovider/adapters v2.0
+ * Core logger utility
+ */
+
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+
+export interface Logger {
+  debug(message: string, ...args: any[]): void;
+  info(message: string, ...args: any[]): void;
+  warn(message: string, ...args: any[]): void;
+  error(message: string, ...args: any[]): void;
+}
+
+/**
+ * Create a logger instance
+ */
+export function createLogger(
+  namespace: string,
+  enabled: boolean = false
+): Logger {
+  const log = (level: LogLevel, message: string, ...args: any[]) => {
+    if (!enabled && level !== 'error') return;
+    
+    const timestamp = new Date().toISOString();
+    const prefix = `[${timestamp}] [@thorprovider/adapters:${namespace}] ${level.toUpperCase()}:`;
+    
+    console[level](prefix, message, ...args);
+  };
+  
+  return {
+    debug: (message, ...args) => log('debug', message, ...args),
+    info: (message, ...args) => log('info', message, ...args),
+    warn: (message, ...args) => log('warn', message, ...args),
+    error: (message, ...args) => log('error', message, ...args),
+  };
+}

package/src/factory/index.ts

@@ -0,0 +1,102 @@
+/**
+ * @thorprovider/adapters v2.0
+ * Provider Factory - Create commerce providers dynamically
+ *
+ * This factory is bound to SupportedProviderType from @thorprovider/types (L1).
+ * When adding a new provider:
+ * 1. Update SupportedProviderType enum in packages/types/src/provider.ts
+ * 2. Add new discriminated union case here
+ * 3. Create packages/adapters/src/providers/[platform]/
+ * 4. Implement CommerceProvider interface
+ */
+
+import type { CommerceProvider } from '../types';
+import { MedusaProvider, type MedusaProviderConfig } from '../providers/medusa';
+import { ShopifyProvider, type ShopifyProviderConfig } from '../providers/shopify';
+import { BigCommerceProvider, type BigCommerceProviderConfig } from '../providers/bigcommerce';
+import { WooCommerceProvider, type WooCommerceProviderConfig } from '../providers/woocommerce';
+import { SpreeProvider, type SpreeProviderConfig } from '../providers/spree';
+import { MagentoProvider, type MagentoProviderConfig } from '../providers/magento';
+import { ProviderNotFoundError, ConfigurationError } from '../core/errors';
+import type { ProviderTypeString } from '@thorprovider/types';
+
+/**
+ * Supported provider types (imported from @thorprovider/types L1)
+ * Kept for backward compatibility; prefer ProviderTypeString from @thorprovider/types
+ */
+export type ProviderType = ProviderTypeString;
+
+/**
+ * Provider configuration discriminated union
+ */
+export type ProviderFactoryConfig =
+  | { provider: 'medusa'; config: MedusaProviderConfig }
+  | { provider: 'shopify'; config: ShopifyProviderConfig }
+  | { provider: 'bigcommerce'; config: BigCommerceProviderConfig }
+  | { provider: 'woocommerce'; config: WooCommerceProviderConfig }
+  | { provider: 'spree'; config: SpreeProviderConfig }
+  | { provider: 'magento'; config: MagentoProviderConfig };
+
+/**
+ * Runtime provider configuration (accepts any ProviderTypeString from env vars)
+ */
+export type RuntimeProviderConfig = {
+  provider: ProviderTypeString;
+  config: Record<string, unknown>;
+};
+
+/**
+ * Create a commerce provider instance
+ * 
+ * @example
+ * ```ts
+ * const commerce = createProvider({
+ *   provider: 'medusa',
+ *   config: {
+ *     baseUrl: process.env.MEDUSA_BACKEND_URL,
+ *     publishableKey: process.env.MEDUSA_PUBLISHABLE_KEY,
+ *   }
+ * });
+ * 
+ * const products = await commerce.getProducts();
+ * ```
+ */
+export function createProvider(options: ProviderFactoryConfig | RuntimeProviderConfig): CommerceProvider {
+  if (!options || !options.provider) {
+    throw new ConfigurationError('Provider type is required');
+  }
+  
+  if (!options.config) {
+    throw new ConfigurationError('Provider configuration is required');
+  }
+  
+  const config = options.config as any;
+  
+  switch (options.provider) {
+    case 'medusa':
+      return new MedusaProvider(config);
+    case 'shopify':
+      return new ShopifyProvider(config);
+    case 'bigcommerce':
+      return new BigCommerceProvider(config);
+    case 'woocommerce':
+      return new WooCommerceProvider(config);
+    case 'spree':
+      return new SpreeProvider(config);
+    case 'magento':
+      return new MagentoProvider(config);
+    
+    default:
+      throw new ProviderNotFoundError(String((options as any).provider));
+  }
+}
+
+/**
+ * Type guard to check if a provider is of a specific type
+ */
+export function isProviderType<T extends ProviderType>(
+  provider: CommerceProvider,
+  type: T
+): boolean {
+  return provider.name === type;
+}

package/src/index.ts

@@ -0,0 +1,205 @@
+/**
+ * @thorprovider/adapters v2.0
+ * Main package exports
+ * 
+ * Unified commerce adapters for Thor Commerce ecosystem
+ * Supports multiple e-commerce platforms through a common interface
+ */
+
+// ============================================
+// Types
+// ============================================
+export type * from './types';
+
+// ============================================
+// Commerce Provider Interface (from @thorprovider/types)
+// ============================================
+// Re-export for backward compatibility
+export type {
+  CommerceProvider,
+  BackendCapabilities,
+  ProviderConfig,
+  StorefrontContext,
+  StorefrontPlatformType,
+  StorefrontConfig,
+  StorefrontSeoDefaults,
+  DesignerConfig,
+  DesignerThemeConfig,
+  DesignerThemePreset,
+  DesignerNavItem,
+  DesignerHistoryEntry,
+} from '@thorprovider/types';
+
+export {
+  StorefrontConfigError,
+} from '@thorprovider/types';
+
+// ============================================
+// Capabilities
+// ============================================
+export {
+  MEDUSA_CAPABILITIES,
+  SHOPIFY_CAPABILITIES,
+  BIGCOMMERCE_CAPABILITIES,
+  WOOCOMMERCE_CAPABILITIES,
+  SPREE_CAPABILITIES,
+  MAGENTO_CAPABILITIES,
+  isBackendCapabilities,
+  getCapabilityDescription,
+} from './types/capabilities.types';
+
+// ============================================
+// Core Utilities
+// ============================================
+export {
+  CommerceError,
+  ProviderNotFoundError,
+  ConfigurationError,
+  ResourceNotFoundError,
+  ProviderAPIError,
+  createLogger,
+  type Logger,
+  type LogLevel,
+} from './core';
+
+// ============================================
+// Resilience Patterns
+// ============================================
+export {
+  CircuitBreaker,
+  backendCircuitBreaker,
+  CircuitBreakerOpenError,
+  type CircuitState,
+  type CircuitBreakerConfig,
+  type CircuitBreakerStats,
+} from './resilience';
+
+// ============================================
+// Transformation Utilities
+// ============================================
+export {
+  moneyToNumber,
+  numberToMoney,
+  moneyToNumberSafe,
+} from './lib/money-transform';
+
+// ============================================
+// Payment Utilities
+// ============================================
+export {
+  getBackendProviderId,
+  validatePaymentId,
+  type BackendMapping,
+} from './utils/payment-utils';
+
+// ============================================
+// Inventory & Fulfillment Utilities
+// ============================================
+export {
+  calculateDistance,
+  geocodeAddress,
+  type Coordinates,
+} from './utils/geolocation';
+
+export {
+  planFulfillment,
+  type FulfillmentGroup,
+  type FulfillmentPlan,
+  type PlanFulfillmentShippingAddress,
+} from './providers/medusa/fulfillment-planner';
+
+export {
+  transformStockLocation,
+  transformInventoryLevel,
+  transformFulfillmentOption,
+  transformStorefrontConfig,
+} from './providers/medusa/transforms';
+
+// ============================================
+// Admin Services
+// ============================================
+export {
+  AdminAuthService,
+  AdminSessionService,
+  MetricsService,
+} from './admin';
+
+export type {
+  AdminSession,
+  MetricsOrderInput,
+  MetricsProductInput,
+} from './admin';
+
+// ============================================
+// Backend Metadata Adapters
+// ============================================
+export type {
+  BackendMetadataAdapter,
+} from './backend/BackendMetadataAdapter';
+
+export type {
+  BackendMetadataAdapterConfig,
+} from './backend/factory';
+
+export {
+  createBackendMetadataAdapter,
+} from './backend/factory';
+
+export {
+  MedusaMetadataAdapter,
+} from './backend/medusa/MedusaMetadataAdapter';
+
+// ============================================
+// Channel Scope (Multi-Tenant Metadata Helpers)
+// ============================================
+export {
+  CHANNEL_SCOPE_KEY,
+  CHANNEL_ASSIGNED_AT_KEY,
+  CHANNEL_ASSIGNED_BY_KEY,
+  buildChannelScopeMetadata,
+  getChannelScope,
+  isScopedToChannel,
+  isGlobalEntity,
+  filterByChannel,
+  filterGlobalOnly,
+  partitionByChannel,
+  ChannelScopeValidationError,
+  validateChannelId,
+  validateEntityId,
+  validateAssignedBy,
+  validateChannelScopeAssignment,
+  assertEntityBelongsToChannel,
+} from './metadata';
+
+export type {
+  ChannelScopeable,
+  ChannelScopeMetadata,
+} from './metadata';
+
+// ============================================
+// Factory
+// ============================================
+export {
+  createProvider,
+  isProviderType,
+  type ProviderType,
+  type ProviderFactoryConfig,
+} from './factory';
+
+// ============================================
+// Providers
+// ============================================
+export {
+  MedusaProvider,
+  type MedusaProviderConfig,
+  ShopifyProvider,
+  type ShopifyProviderConfig,
+  BigCommerceProvider,
+  type BigCommerceProviderConfig,
+  WooCommerceProvider,
+  type WooCommerceProviderConfig,
+  SpreeProvider,
+  type SpreeProviderConfig,
+  MagentoProvider,
+  type MagentoProviderConfig,
+} from './providers';

package/src/lib/money-transform.ts

@@ -0,0 +1,80 @@
+/**
+ * @thorprovider/adapters
+ * Money transformation utilities
+ * 
+ * Handles conversion between domain Money types (string decimals) and
+ * UI-ready number representations (smallest currency unit, e.g., cents).
+ */
+
+import type { Money } from '@thorprovider/types';
+
+/**
+ * Converts Money object to number in smallest currency unit
+ * 
+ * Money.amount is a decimal string (e.g., "45.99").
+ * This function converts it to smallest unit (e.g., 4599 cents).
+ * 
+ * @param money - Money object with decimal string amount
+ * @returns Amount in smallest currency unit (e.g., cents for USD)
+ * 
+ * @example
+ * ```typescript
+ * moneyToNumber({ amount: "45.99", currencyCode: "USD" })  // => 4599
+ * moneyToNumber({ amount: "100.00", currencyCode: "EUR" }) // => 10000
+ * moneyToNumber({ amount: "0.50", currencyCode: "USD" })   // => 50
+ * ```
+ */
+export function moneyToNumber(money: Money): number {
+  // Parse decimal string and convert to cents (multiply by 100)
+  const amountInMajorUnits = parseFloat(money.amount);
+  const amountInMinorUnits = Math.round(amountInMajorUnits * 100);
+  return amountInMinorUnits;
+}
+
+/**
+ * Converts number (smallest unit) to Money object
+ * 
+ * Takes an amount in smallest currency unit (e.g., cents) and
+ * converts it to a Money object with decimal string amount.
+ * 
+ * @param amount - Amount in smallest currency unit (e.g., cents)
+ * @param currency - ISO 4217 currency code (e.g., 'USD', 'EUR')
+ * @returns Money object with decimal string amount
+ * 
+ * @example
+ * ```typescript
+ * numberToMoney(4599, 'USD')  // => { amount: "45.99", currencyCode: "USD" }
+ * numberToMoney(10000, 'EUR') // => { amount: "100.00", currencyCode: "EUR" }
+ * numberToMoney(50, 'USD')    // => { amount: "0.50", currencyCode: "USD" }
+ * ```
+ */
+export function numberToMoney(amount: number, currency: string): Money {
+  // Convert cents to dollars and format as decimal string
+  const amountInMajorUnits = amount / 100;
+  const formattedAmount = amountInMajorUnits.toFixed(2);
+  
+  return {
+    amount: formattedAmount,
+    currencyCode: currency,
+  };
+}
+
+/**
+ * Safely converts Money to number, returning 0 for null/undefined
+ * 
+ * Useful for optional Money fields that might not always be present.
+ * 
+ * @param money - Money object or null/undefined
+ * @returns Amount in smallest unit, or 0 if money is null/undefined
+ * 
+ * @example
+ * ```typescript
+ * moneyToNumberSafe({ amount: "10.00", currencyCode: "USD" }) // => 1000
+ * moneyToNumberSafe(undefined) // => 0
+ * moneyToNumberSafe(null)      // => 0
+ * ```
+ */
+export function moneyToNumberSafe(money: Money | null | undefined): number {
+  if (!money) return 0;
+  return moneyToNumber(money);
+}

package/src/metadata/channel-scope-validation.js

@@ -0,0 +1,136 @@
+"use strict";
+/**
+ * Channel Scope Validation — Pure TypeScript (no external deps)
+ *
+ * Validates channel-scope metadata before it is written to the backend.
+ * Keeps all validation logic in L2 so that L5 starters don't duplicate checks.
+ *
+ * @module metadata/channel-scope-validation
+ */
+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.ChannelScopeValidationError = void 0;
+exports.validateChannelId = validateChannelId;
+exports.validateEntityId = validateEntityId;
+exports.validateAssignedBy = validateAssignedBy;
+exports.validateChannelScopeAssignment = validateChannelScopeAssignment;
+exports.assertEntityBelongsToChannel = assertEntityBelongsToChannel;
+var channel_scope_1 = require("./channel-scope");
+// ────────────────────────────────────────────────────────────────────
+// Errors
+// ────────────────────────────────────────────────────────────────────
+/**
+ * Thrown when channel-scope validation fails.
+ *
+ * Consumers can catch this specific type to provide user-friendly feedback
+ * without leaking internal details.
+ */
+var ChannelScopeValidationError = /** @class */ (function (_super) {
+    __extends(ChannelScopeValidationError, _super);
+    function ChannelScopeValidationError(message, field, value) {
+        var _this = _super.call(this, message) || this;
+        _this.name = 'ChannelScopeValidationError';
+        _this.field = field;
+        _this.value = value;
+        return _this;
+    }
+    return ChannelScopeValidationError;
+}(Error));
+exports.ChannelScopeValidationError = ChannelScopeValidationError;
+// ────────────────────────────────────────────────────────────────────
+// Validation functions
+// ────────────────────────────────────────────────────────────────────
+/**
+ * Validate that a channel ID is a non-empty string.
+ *
+ * Does **not** enforce a specific prefix (e.g. `"sc_"`) because different
+ * backends use different conventions:
+ * - Medusa: `"sc_01HXXX"`
+ * - Shopify: `"gid://shopify/Channel/789"`
+ * - WooCommerce: `"1"` (numeric string)
+ *
+ * @throws {ChannelScopeValidationError}
+ */
+function validateChannelId(channelId) {
+    if (typeof channelId !== 'string' || channelId.trim().length === 0) {
+        throw new ChannelScopeValidationError('Channel ID must be a non-empty string', 'channelId', channelId);
+    }
+    // Sanity upper-bound for ID length (guards against payload abuse)
+    if (channelId.length > 256) {
+        throw new ChannelScopeValidationError('Channel ID exceeds maximum length (256)', 'channelId', channelId);
+    }
+}
+/**
+ * Validate that an entity ID is a non-empty string.
+ *
+ * @throws {ChannelScopeValidationError}
+ */
+function validateEntityId(entityId, label) {
+    if (label === void 0) { label = 'entityId'; }
+    if (typeof entityId !== 'string' || entityId.trim().length === 0) {
+        throw new ChannelScopeValidationError("".concat(label, " must be a non-empty string"), label, entityId);
+    }
+}
+/**
+ * Validate that the `assignedBy` value (if provided) is a reasonable string.
+ *
+ * @throws {ChannelScopeValidationError}
+ */
+function validateAssignedBy(assignedBy) {
+    if (assignedBy === undefined || assignedBy === null)
+        return;
+    if (typeof assignedBy !== 'string') {
+        throw new ChannelScopeValidationError('assignedBy must be a string', 'assignedBy', assignedBy);
+    }
+    if (assignedBy.length > 512) {
+        throw new ChannelScopeValidationError('assignedBy exceeds maximum length (512)', 'assignedBy', assignedBy);
+    }
+}
+/**
+ * Full validation for a channel-scope assignment operation.
+ *
+ * Call before writing channel scope metadata to any entity.
+ *
+ * @throws {ChannelScopeValidationError} with descriptive field + value
+ *
+ * @example
+ * ```typescript
+ * validateChannelScopeAssignment('cus_123', 'sc_01HXXX', 'admin@store.com');
+ * // If no error, safe to proceed
+ * ```
+ */
+function validateChannelScopeAssignment(entityId, channelId, assignedBy) {
+    validateEntityId(entityId, 'entityId');
+    validateChannelId(channelId);
+    validateAssignedBy(assignedBy);
+}
+/**
+ * Validate that an entity is currently scoped to the expected channel.
+ *
+ * Useful as a guard before performing operations that should only
+ * affect entities within the caller's channel (e.g. a dropshipper editing
+ * a customer that must belong to their channel).
+ *
+ * @throws {ChannelScopeValidationError} if entity does not belong to expectedChannelId
+ */
+function assertEntityBelongsToChannel(entity, expectedChannelId) {
+    var _a;
+    var actual = (_a = entity.metadata) === null || _a === void 0 ? void 0 : _a[channel_scope_1.CHANNEL_SCOPE_KEY];
+    if (actual !== expectedChannelId) {
+        throw new ChannelScopeValidationError("Entity \"".concat(entity.id, "\" does not belong to channel \"").concat(expectedChannelId, "\" (actual: \"").concat(actual !== null && actual !== void 0 ? actual : 'none', "\")"), channel_scope_1.CHANNEL_SCOPE_KEY, actual);
+    }
+}