@thorprovider/types 3.2.0 → 3.3.0

package/dist/index.mjs

@@ -1,13 +1,9 @@
 // src/provider.ts
-var SupportedProviderType = /* @__PURE__ */ ((SupportedProviderType3) => {
-  SupportedProviderType3["Mock"] = "mock";
-  SupportedProviderType3["Medusa"] = "medusa";
-  SupportedProviderType3["Shopify"] = "shopify";
-  SupportedProviderType3["BigCommerce"] = "bigcommerce";
-  SupportedProviderType3["WooCommerce"] = "woocommerce";
-  SupportedProviderType3["Spree"] = "spree";
-  SupportedProviderType3["Magento"] = "magento";
-  return SupportedProviderType3;
+var SupportedProviderType = /* @__PURE__ */ ((SupportedProviderType2) => {
+  SupportedProviderType2["Mock"] = "mock";
+  SupportedProviderType2["Medusa"] = "medusa";
+  SupportedProviderType2["StelOrder"] = "stelorder";
+  return SupportedProviderType2;
 })(SupportedProviderType || {});
 var PROVIDER_METADATA = {
   mock: {
@@ -28,56 +24,15 @@ var PROVIDER_METADATA = {
     ],
     maxRetries: 3
   },
-  shopify: {
-    name: "Shopify",
-    description: "Shopify Storefront API (GraphQL)",
+  stelorder: {
+    name: "Stel Order",
+    description: "Stel Order ERP and sales document API",
     requiresStorefront: false,
     requiredEnvVars: [
-      "NEXT_PUBLIC_SHOPIFY_STORE_DOMAIN",
-      "NEXT_PUBLIC_SHOPIFY_STOREFRONT_TOKEN"
-    ],
-    maxRetries: 3
-  },
-  bigcommerce: {
-    name: "BigCommerce",
-    description: "BigCommerce REST Storefront API",
-    requiresStorefront: false,
-    requiredEnvVars: [
-      "BIGCOMMERCE_STORE_HASH",
-      "BIGCOMMERCE_STOREFRONT_API_TOKEN",
-      "BIGCOMMERCE_CHANNEL_ID"
-    ],
-    maxRetries: 3
-  },
-  woocommerce: {
-    name: "WooCommerce",
-    description: "WooCommerce Store API + REST API v3",
-    requiresStorefront: false,
-    requiredEnvVars: [
-      "WOOCOMMERCE_URL",
-      "WOOCOMMERCE_CONSUMER_KEY",
-      "WOOCOMMERCE_CONSUMER_SECRET"
-    ],
-    maxRetries: 3
-  },
-  spree: {
-    name: "Spree Commerce",
-    description: "Spree API v2 Storefront (JSON:API)",
-    requiresStorefront: false,
-    requiredEnvVars: [
-      "SPREE_API_URL"
-    ],
-    maxRetries: 3
-  },
-  magento: {
-    name: "Adobe Commerce (Magento)",
-    description: "Adobe Commerce GraphQL + REST API",
-    requiresStorefront: true,
-    requiredEnvVars: [
-      "MAGENTO_URL",
-      "MAGENTO_STORE_CODE"
+      "NEXT_PUBLIC_COMMERCE_API_URL",
+      "NEXT_PUBLIC_COMMERCE_API_KEY"
     ],
-    maxRetries: 3
+    maxRetries: 2
   }
 };
 function isSupportedProviderType(value) {
@@ -105,17 +60,10 @@ var StorefrontConfigError = class extends Error {
     this.requiredEnvVar = requiredEnvVar;
   }
 };
-
-// src/index.ts
-var SupportedProviderType2 = /* @__PURE__ */ ((SupportedProviderType3) => {
-  SupportedProviderType3["Mock"] = "mock";
-  SupportedProviderType3["Medusa"] = "medusa";
-  return SupportedProviderType3;
-})(SupportedProviderType2 || {});
 export {
   PROVIDER_METADATA,
   StorefrontConfigError,
-  SupportedProviderType2 as SupportedProviderType,
+  SupportedProviderType,
   getProviderMetadata,
   isSupportedProviderType
 };

package/dist/index.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/provider.ts","../src/storefront.ts","../src/index.ts"],"sourcesContent":["/**\n * @thorprovider/types — Supported Providers\n *\n * Centralized list of all supported commerce providers.\n * This is the single source of truth for provider types across the monorepo.\n *\n * @remarks\n * - L1 (Foundation): Defines the contract\n * - L2 (@thorprovider/adapters) imports from here to build the factory\n * - L5 (Starters) uses the factory which is bound to this enum\n *\n * When adding a new provider (e.g., Shopify):\n * 1. Add to SupportedProviderType enum below\n * 2. Update @thorprovider/adapters factory/index.ts with discriminated union\n * 3. Create packages/adapters/src/providers/shopify/\n * 4. Implement CommerceProvider interface\n * 5. Update StorefrontPlatformType in storefront.ts (automatically synced)\n */\n\n/**\n * All supported commerce platform providers.\n * `mock` is the backend-optional runtime provider used for layout/design mode.\n * `medusa` is fully implemented for real backend usage; others are placeholders for future expansion.\n *\n * @remarks Implementation status:\n * - ✅ mock: Fixture-backed provider for backend-optional storefronts\n * - ✅ medusa: Fully implemented\n * - 🟡 shopify: Planned (Phase 2)\n * - 🟡 bigcommerce: Planned (Phase 2)\n * - 🟡 woocommerce: Planned (Phase 3)\n * - 🟡 spree: Planned (Phase 3)\n * - 🟡 magento: Planned (Phase 3)\n */\nexport enum SupportedProviderType {\n  Mock = 'mock',\n  Medusa = 'medusa',\n  Shopify = 'shopify',\n  BigCommerce = 'bigcommerce',\n  WooCommerce = 'woocommerce',\n  Spree = 'spree',\n  Magento = 'magento',\n}\n\n/**\n * Union type of all supported provider string values.\n * Use this for type annotations when a provider type is expected.\n *\n * @example\n * ```typescript\n * function getProviderName(type: ProviderTypeString): string {\n *   // type is 'medusa'\n * }\n * ```\n */\nexport type ProviderTypeString = 'mock' | 'medusa' | 'shopify' | 'bigcommerce' | 'woocommerce' | 'spree' | 'magento';\n\n/**\n * Metadata about each provider.\n * Useful for UI, error messages, validation, and documentation.\n *\n * @internal\n */\nexport const PROVIDER_METADATA: Record<\n  ProviderTypeString,\n  {\n    name: string;\n    description: string;\n    requiresStorefront: boolean;\n    requiredEnvVars: string[];\n    maxRetries: number;\n  }\n> = {\n  mock: {\n    name: 'Mock',\n    description: 'Fixture-backed runtime provider for layout/design mode without a real backend',\n    requiresStorefront: false,\n    requiredEnvVars: [],\n    maxRetries: 0,\n  },\n  medusa: {\n    name: 'Medusa JS',\n    description: 'Medusa v2 commerce engine',\n    requiresStorefront: true,\n    requiredEnvVars: [\n      'NEXT_PUBLIC_COMMERCE_API_URL',\n      'NEXT_PUBLIC_COMMERCE_API_KEY',\n      'NEXT_PUBLIC_SALES_CHANNEL_ID',\n    ],\n    maxRetries: 3,\n  },\n  shopify: {\n    name: 'Shopify',\n    description: 'Shopify Storefront API (GraphQL)',\n    requiresStorefront: false,\n    requiredEnvVars: [\n      'NEXT_PUBLIC_SHOPIFY_STORE_DOMAIN',\n      'NEXT_PUBLIC_SHOPIFY_STOREFRONT_TOKEN',\n    ],\n    maxRetries: 3,\n  },\n  bigcommerce: {\n    name: 'BigCommerce',\n    description: 'BigCommerce REST Storefront API',\n    requiresStorefront: false,\n    requiredEnvVars: [\n      'BIGCOMMERCE_STORE_HASH',\n      'BIGCOMMERCE_STOREFRONT_API_TOKEN',\n      'BIGCOMMERCE_CHANNEL_ID',\n    ],\n    maxRetries: 3,\n  },\n  woocommerce: {\n    name: 'WooCommerce',\n    description: 'WooCommerce Store API + REST API v3',\n    requiresStorefront: false,\n    requiredEnvVars: [\n      'WOOCOMMERCE_URL',\n      'WOOCOMMERCE_CONSUMER_KEY',\n      'WOOCOMMERCE_CONSUMER_SECRET',\n    ],\n    maxRetries: 3,\n  },\n  spree: {\n    name: 'Spree Commerce',\n    description: 'Spree API v2 Storefront (JSON:API)',\n    requiresStorefront: false,\n    requiredEnvVars: [\n      'SPREE_API_URL',\n    ],\n    maxRetries: 3,\n  },\n  magento: {\n    name: 'Adobe Commerce (Magento)',\n    description: 'Adobe Commerce GraphQL + REST API',\n    requiresStorefront: true,\n    requiredEnvVars: [\n      'MAGENTO_URL',\n      'MAGENTO_STORE_CODE',\n    ],\n    maxRetries: 3,\n  },\n};\n\n/**\n * Check if a string is a valid provider type.\n *\n * @example\n * ```typescript\n * if (isSupportedProviderType(process.env.COMMERCE_PROVIDER)) {\n *   // type is narrowed to ProviderTypeString\n * }\n * ```\n */\nexport function isSupportedProviderType(\n  value: unknown\n): value is ProviderTypeString {\n  return (\n    typeof value === 'string' &&\n    Object.values(SupportedProviderType).includes(value as SupportedProviderType)\n  );\n}\n\n/**\n * Get metadata for a provider type.\n * Useful for validation, error messages, and logging.\n *\n * @example\n * ```typescript\n * const meta = getProviderMetadata('medusa');\n * console.log(`Using ${meta.name} with max ${meta.maxRetries} retries`);\n * ```\n */\nexport function getProviderMetadata(\n  type: ProviderTypeString\n): (typeof PROVIDER_METADATA)[ProviderTypeString] {\n  if (!isSupportedProviderType(type)) {\n    throw new Error(\n      `Unsupported provider: ${type}. Supported: ${Object.values(\n        SupportedProviderType\n      ).join(', ')}`\n    );\n  }\n  return PROVIDER_METADATA[type];\n}\n","/**\n * @thorprovider/types — Storefront Context\n *\n * Platform-agnostic representation of a \"sales channel\" or equivalent.\n * Abstracts differences between Medusa sales_channel, Shopify publications,\n * BigCommerce channels, WooCommerce sites, Spree stores, and Magento store views.\n *\n * @remarks\n * - Required for all multi-tenant deployments\n * - Returned by `CommerceProvider.getStorefrontContext()`\n * - MUST be validated on startup; errors should NOT be silently ignored\n */\n\n/**\n * Supported commerce platform types for storefront identification.\n *\n * @remarks\n * This type is automatically synced with SupportedProviderType from provider.ts.\n * When adding a new provider, update packages/types/src/provider.ts,\n * and this type will automatically reflect the new provider.\n *\n * Currently supported:\n * - ✅ 'mock': Backend-optional layout/design mode using fixture data\n * - ✅ 'medusa': Fully implemented\n *\n * Planned (not yet implemented):\n * - 🟡 'shopify': Phase 2\n * - 🟡 'bigcommerce': Phase 2\n * - 🟡 'woocommerce': Phase 3\n * - 🟡 'spree': Phase 3\n * - 🟡 'magento': Phase 3\n */\nexport type StorefrontPlatformType = 'mock' | 'medusa' | 'shopify' | 'bigcommerce' | 'woocommerce' | 'spree' | 'magento';\n\n/**\n * StorefrontContext\n *\n * Platform-agnostic representation of a \"sales channel\" or equivalent.\n *\n * @example\n * ```typescript\n * const ctx: StorefrontContext = {\n *   id: 'sc_01J...',\n *   name: 'B2C Storefront',\n *   platformType: 'medusa',\n *   requiresProductScoping: true,\n *   currencyCode: 'USD',\n * };\n * ```\n */\nexport interface StorefrontContext {\n  /**\n   * Unique identifier for this storefront across the system.\n   * Examples: \"sc_123\" (Medusa), \"gid://shopify/Channel/789\" (Shopify), \"1\" (WooCommerce)\n   */\n  id: string;\n\n  /**\n   * Human-readable name for logging and debugging.\n   */\n  name: string;\n\n  /**\n   * Platform this storefront belongs to.\n   */\n  platformType: StorefrontPlatformType;\n\n  /**\n   * Whether products must be explicitly linked/published to this storefront.\n   *\n   * @remarks\n   * - Medusa: true (products must be linked to sales channel)\n   * - Shopify: false (products visible by default unless unlisted)\n   * - WooCommerce: false (no scoping concept)\n   * - BigCommerce: false (products visible by default unless delisted)\n   * - Spree: true (products must be assigned per store)\n   * - Magento: true (products must be assigned per website)\n   */\n  requiresProductScoping: boolean;\n\n  /**\n   * Primary currency code for this storefront.\n   * Examples: \"USD\", \"EUR\", \"GBP\"\n   */\n  currencyCode: string;\n\n  /**\n   * Optional region or locale code.\n   * Examples: \"US\", \"EU\", \"en-US\", \"es-ES\"\n   */\n  locale?: string;\n\n  /**\n   * Optional: Store/Channel metadata from platform.\n   * @internal\n   */\n  metadata?: Record<string, unknown>;\n}\n\n/**\n * Storefront validation error.\n * Thrown when storefront configuration is invalid or missing.\n *\n * @example\n * ```typescript\n * throw new StorefrontConfigError(\n *   'Medusa requires NEXT_PUBLIC_SALES_CHANNEL_ID',\n *   'medusa',\n *   'NEXT_PUBLIC_SALES_CHANNEL_ID',\n * );\n * ```\n */\nexport class StorefrontConfigError extends Error {\n  public readonly platformType: string;\n  public readonly requiredEnvVar?: string;\n\n  constructor(\n    message: string,\n    platformType: string,\n    requiredEnvVar?: string,\n  ) {\n    super(message);\n    this.name = 'StorefrontConfigError';\n    this.platformType = platformType;\n    this.requiredEnvVar = requiredEnvVar;\n  }\n}\n","/**\n * @thorprovider/types v1.0\n * Shared TypeScript types for Thor Commerce ecosystem\n * \n * Pure type definitions with zero runtime dependencies.\n * Foundation for type-safe commerce operations following SOLID principles.\n */\n\n// ============================================\n// Common Types\n// ============================================\nexport type {\n  Money,\n  Image,\n  SEO,\n  Connection,\n  Edge,\n  PaginationOptions,\n  SortOptions,\n  Country,\n} from './common';\n\nexport type {\n  AuthorConfig,\n  BrandConfig,\n  ModulesConfig,\n  NavigationItem,\n  SiteConfig,\n  SocialConfig,\n} from './site-config';\n\nexport type { SiteConfigLabels } from './site-config-labels';\n\n// ============================================\n// Product Types\n// ============================================\nexport type {\n  Product,\n  ProductOption,\n  ProductVariant,\n  SelectedOption,\n  PriceRange,\n  GetProductsOptions,\n  ActiveFilter,\n  SortOption,\n  FilterSection,\n  FilterOption,\n  ProductPreview,\n  Review,\n  CompareProduct,\n  AdminProductVariant,\n  AdminProduct,\n  AdvancedSearchProductsOptions,\n  SearchResultMeta,\n  FilterConfig,\n} from './product';\n\n// ============================================\n// Cart Types\n// ============================================\nexport type {\n  Cart,\n  CartItem,\n  CartProduct,\n  CartCost,\n  CartLineInput,\n  CartLineUpdate,\n  ShippingMethod,\n  DiscountCode,\n} from './cart';\n\n// ============================================\n// Inventory & Fulfillment Types\n// ============================================\nexport type {\n  StockLocation,\n  InventoryLevel,\n  FulfillmentSet,\n  FulfillmentOption,\n  StockStatus,\n  StockValidation,\n} from './stock-location';\n\n// ============================================\n// Collection Types\n// ============================================\nexport type {\n  Collection,\n  CollectionProductsOptions,\n  GetCollectionsOptions,\n} from './collection';\n\n// ============================================\n// Category Types\n// ============================================\nexport type {\n  ProductCategory,\n  GetCategoriesOptions,\n  GetCategoriesCallback,\n} from './category';\n\n// ============================================\n// Customer Types\n// ============================================\nexport type {\n  Customer,\n  Address,\n  GetCustomersOptions,\n  GetCustomersCallback,\n} from './customer';\n\n// ============================================\n// Region Types\n// ============================================\nexport type {\n  Region,\n} from './region';\n\n// ============================================\n// Order Types\n// ============================================\nexport type {\n  Order,\n  OrderItem,\n  OrderStatus,\n  PaymentStatus,\n  FulfillmentStatus,\n  GetOrdersOptions,\n  GetOrdersCallback,\n} from './order';\n\n// ============================================\n// Provider Types (L1 - Source of Truth)\n// ============================================\nexport enum SupportedProviderType {\n  Mock = 'mock',\n  Medusa = 'medusa',\n}\n\n// Re-export provider types directly\nexport { type ProviderTypeString } from './provider';\n\nexport {\n  isSupportedProviderType,\n  getProviderMetadata,\n  PROVIDER_METADATA,\n} from './provider';\n\n// ============================================\n// Storefront Types\n// ============================================\nexport type {\n  StorefrontContext,\n  StorefrontPlatformType,\n} from './storefront';\n\nexport {\n  StorefrontConfigError,\n} from './storefront';\n\n// ============================================\n// Storefront Configuration Types\n// ============================================\nexport type {\n  StorefrontConfig,\n  StorefrontSeoDefaults,\n} from './storefront-config';\n\n// ============================================\n// Designer Configuration Types\n// ============================================\nexport type {\n  DesignerConfig,\n  DesignerThemeConfig,\n  DesignerThemePreset,\n  DesignerNavItem,\n  DesignerHistoryEntry,\n} from './designer-config';\n\n// ============================================\n// Auth Types\n// ============================================\nexport type {\n  AuthProvider,\n  AuthConfig,\n  AuthMethod,\n  AuthStorage,\n  LoginCredentials,\n  RegisterData,\n  AuthResponse,\n  UpdateCustomerData,\n  CreateAddressData,\n  PasswordResetRequest,\n  PasswordResetConfirm,\n} from './auth';\n\n// ============================================\n// Payment Types\n// ============================================\nexport type {\n  PaymentMethod,\n  PaymentMethodType,\n  PaymentMethodFeatures,\n  PaymentMethodsOptions,\n  CachedPaymentMethods,\n} from './payment';\n\n// ============================================\n// Commerce Provider Interface\n// ============================================\nexport type {\n  CommerceProvider,\n  BackendCapabilities,\n  ProviderConfig,\n} from './commerce-provider';\n\n// ============================================\n// Admin Types\n// ============================================\nexport type {\n  AdminUser,\n  AuditLog,\n  DashboardConfig,\n  DashboardMetrics,\n  SalesMetrics,\n  OrdersMetrics,\n  ProductsMetrics,\n  ChartDataPoint,\n  DashboardMetricsAdapter,\n  DashboardOrdersAdapter,\n  DashboardProductsAdapter,\n  AuditLogAdapter,\n  SiteConfigMetadata,\n  ConfigHistoryEntry,\n} from './admin';\n\n// ============================================\n// Header Configuration Types\n// ============================================\nexport type {\n  IconConfig,\n  NavigationCalloutItem,\n  NavigationLinkItem,\n  DynamicSource,\n  HeaderLinkItem,\n  AccountMenuItem,\n  AccountDropdownConfig,\n  SearchBarConfig,\n  HeaderNavigationConfig,\n} from './header-config';\n"],"mappings":";AAiCO,IAAK,wBAAL,kBAAKA,2BAAL;AACL,EAAAA,uBAAA,UAAO;AACP,EAAAA,uBAAA,YAAS;AACT,EAAAA,uBAAA,aAAU;AACV,EAAAA,uBAAA,iBAAc;AACd,EAAAA,uBAAA,iBAAc;AACd,EAAAA,uBAAA,WAAQ;AACR,EAAAA,uBAAA,aAAU;AAPA,SAAAA;AAAA,GAAA;AA6BL,IAAM,oBAST;AAAA,EACF,MAAM;AAAA,IACJ,MAAM;AAAA,IACN,aAAa;AAAA,IACb,oBAAoB;AAAA,IACpB,iBAAiB,CAAC;AAAA,IAClB,YAAY;AAAA,EACd;AAAA,EACA,QAAQ;AAAA,IACN,MAAM;AAAA,IACN,aAAa;AAAA,IACb,oBAAoB;AAAA,IACpB,iBAAiB;AAAA,MACf;AAAA,MACA;AAAA,MACA;AAAA,IACF;AAAA,IACA,YAAY;AAAA,EACd;AAAA,EACA,SAAS;AAAA,IACP,MAAM;AAAA,IACN,aAAa;AAAA,IACb,oBAAoB;AAAA,IACpB,iBAAiB;AAAA,MACf;AAAA,MACA;AAAA,IACF;AAAA,IACA,YAAY;AAAA,EACd;AAAA,EACA,aAAa;AAAA,IACX,MAAM;AAAA,IACN,aAAa;AAAA,IACb,oBAAoB;AAAA,IACpB,iBAAiB;AAAA,MACf;AAAA,MACA;AAAA,MACA;AAAA,IACF;AAAA,IACA,YAAY;AAAA,EACd;AAAA,EACA,aAAa;AAAA,IACX,MAAM;AAAA,IACN,aAAa;AAAA,IACb,oBAAoB;AAAA,IACpB,iBAAiB;AAAA,MACf;AAAA,MACA;AAAA,MACA;AAAA,IACF;AAAA,IACA,YAAY;AAAA,EACd;AAAA,EACA,OAAO;AAAA,IACL,MAAM;AAAA,IACN,aAAa;AAAA,IACb,oBAAoB;AAAA,IACpB,iBAAiB;AAAA,MACf;AAAA,IACF;AAAA,IACA,YAAY;AAAA,EACd;AAAA,EACA,SAAS;AAAA,IACP,MAAM;AAAA,IACN,aAAa;AAAA,IACb,oBAAoB;AAAA,IACpB,iBAAiB;AAAA,MACf;AAAA,MACA;AAAA,IACF;AAAA,IACA,YAAY;AAAA,EACd;AACF;AAYO,SAAS,wBACd,OAC6B;AAC7B,SACE,OAAO,UAAU,YACjB,OAAO,OAAO,qBAAqB,EAAE,SAAS,KAA8B;AAEhF;AAYO,SAAS,oBACd,MACgD;AAChD,MAAI,CAAC,wBAAwB,IAAI,GAAG;AAClC,UAAM,IAAI;AAAA,MACR,yBAAyB,IAAI,gBAAgB,OAAO;AAAA,QAClD;AAAA,MACF,EAAE,KAAK,IAAI,CAAC;AAAA,IACd;AAAA,EACF;AACA,SAAO,kBAAkB,IAAI;AAC/B;;;ACvEO,IAAM,wBAAN,cAAoC,MAAM;AAAA,EAC/B;AAAA,EACA;AAAA,EAEhB,YACE,SACA,cACA,gBACA;AACA,UAAM,OAAO;AACb,SAAK,OAAO;AACZ,SAAK,eAAe;AACpB,SAAK,iBAAiB;AAAA,EACxB;AACF;;;ACQO,IAAKC,yBAAL,kBAAKA,2BAAL;AACL,EAAAA,uBAAA,UAAO;AACP,EAAAA,uBAAA,YAAS;AAFC,SAAAA;AAAA,6BAAA;","names":["SupportedProviderType","SupportedProviderType"]}
+{"version":3,"sources":["../src/provider.ts","../src/storefront.ts"],"sourcesContent":["/**\n * @thorprovider/types — Supported Providers\n *\n * Centralized list of all supported commerce providers.\n * This is the single source of truth for provider types across the monorepo.\n *\n * @remarks\n * - L1 (Foundation): Defines the contract\n * - L2 (@thorprovider/adapters) imports from here to build the factory\n * - L5 (Starters) uses the factory which is bound to this enum\n *\n * When adding a new provider (e.g., Stel Order):\n * 1. Add to SupportedProviderType enum below\n * 2. Update @thorprovider/adapters factory/index.ts with discriminated union\n * 3. Create packages/adapters/src/providers/shopify/\n * 4. Implement CommerceProvider interface\n * 5. Update StorefrontPlatformType in storefront.ts\n */\n\n/**\n * All supported commerce platform providers.\n * `mock` is the backend-optional runtime provider used for layout/design mode.\n * `medusa` is fully implemented for real backend usage; others are placeholders for future expansion.\n *\n * @remarks Implementation status:\n * - ✅ mock: Fixture-backed provider for backend-optional storefronts\n * - ✅ medusa: Fully implemented\n * - 🟡 stelorder: In progress (ERP adapter v1)\n * - 🟡 shopify: Planned (Phase 2)\n * - 🟡 bigcommerce: Planned (Phase 2)\n * - 🟡 woocommerce: Planned (Phase 3)\n * - 🟡 spree: Planned (Phase 3)\n * - 🟡 magento: Planned (Phase 3)\n */\nexport enum SupportedProviderType {\n  Mock = 'mock',\n  Medusa = 'medusa',\n  StelOrder = 'stelorder',\n}\n\n/**\n * Union type of all supported provider string values.\n * Use this for type annotations when a provider type is expected.\n *\n * @example\n * ```typescript\n * function getProviderName(type: ProviderTypeString): string {\n *   // type is 'medusa'\n * }\n * ```\n */\nexport type ProviderTypeString = 'mock' | 'medusa' | 'stelorder';\n\n/**\n * Metadata about each provider.\n * Useful for UI, error messages, validation, and documentation.\n *\n * @internal\n */\nexport const PROVIDER_METADATA: Record<\n  ProviderTypeString,\n  {\n    name: string;\n    description: string;\n    requiresStorefront: boolean;\n    requiredEnvVars: string[];\n    maxRetries: number;\n  }\n> = {\n  mock: {\n    name: 'Mock',\n    description: 'Fixture-backed runtime provider for layout/design mode without a real backend',\n    requiresStorefront: false,\n    requiredEnvVars: [],\n    maxRetries: 0,\n  },\n  medusa: {\n    name: 'Medusa JS',\n    description: 'Medusa v2 commerce engine',\n    requiresStorefront: true,\n    requiredEnvVars: [\n      'NEXT_PUBLIC_COMMERCE_API_URL',\n      'NEXT_PUBLIC_COMMERCE_API_KEY',\n      'NEXT_PUBLIC_SALES_CHANNEL_ID',\n    ],\n    maxRetries: 3,\n  },\n  stelorder: {\n    name: 'Stel Order',\n    description: 'Stel Order ERP and sales document API',\n    requiresStorefront: false,\n    requiredEnvVars: [\n      'NEXT_PUBLIC_COMMERCE_API_URL',\n      'NEXT_PUBLIC_COMMERCE_API_KEY',\n    ],\n    maxRetries: 2,\n  },\n};\n\n/**\n * Check if a string is a valid provider type.\n *\n * @example\n * ```typescript\n * if (isSupportedProviderType(process.env.COMMERCE_PROVIDER)) {\n *   // type is narrowed to ProviderTypeString\n * }\n * ```\n */\nexport function isSupportedProviderType(\n  value: unknown\n): value is ProviderTypeString {\n  return (\n    typeof value === 'string' &&\n    Object.values(SupportedProviderType).includes(value as SupportedProviderType)\n  );\n}\n\n/**\n * Get metadata for a provider type.\n * Useful for validation, error messages, and logging.\n *\n * @example\n * ```typescript\n * const meta = getProviderMetadata('medusa');\n * console.log(`Using ${meta.name} with max ${meta.maxRetries} retries`);\n * ```\n */\nexport function getProviderMetadata(\n  type: ProviderTypeString\n): (typeof PROVIDER_METADATA)[ProviderTypeString] {\n  if (!isSupportedProviderType(type)) {\n    throw new Error(\n      `Unsupported provider: ${type}. Supported: ${Object.values(\n        SupportedProviderType\n      ).join(', ')}`\n    );\n  }\n  return PROVIDER_METADATA[type];\n}\n","/**\n * @thorprovider/types — Storefront Context\n *\n * Platform-agnostic representation of a \"sales channel\" or equivalent.\n * Abstracts differences between Medusa sales_channel, Shopify publications,\n * BigCommerce channels, WooCommerce sites, Spree stores, and Magento store views.\n *\n * @remarks\n * - Required for all multi-tenant deployments\n * - Returned by `CommerceProvider.getStorefrontContext()`\n * - MUST be validated on startup; errors should NOT be silently ignored\n */\n\n/**\n * Supported commerce platform types for storefront identification.\n *\n * @remarks\n * Keep this type in sync with SupportedProviderType from provider.ts.\n * When adding a new provider, update both packages/types/src/provider.ts\n * and this type.\n *\n * Currently supported:\n * - ✅ 'mock': Backend-optional layout/design mode using fixture data\n * - ✅ 'medusa': Fully implemented\n * - 🟡 'stelorder': ERP adapter v1\n *\n * Planned (not yet implemented):\n * - 🟡 'shopify': Phase 2\n * - 🟡 'bigcommerce': Phase 2\n * - 🟡 'woocommerce': Phase 3\n * - 🟡 'spree': Phase 3\n * - 🟡 'magento': Phase 3\n */\nexport type StorefrontPlatformType = 'mock' | 'medusa' | 'stelorder' | 'shopify' | 'bigcommerce' | 'woocommerce' | 'spree' | 'magento';\n\n/**\n * StorefrontContext\n *\n * Platform-agnostic representation of a \"sales channel\" or equivalent.\n *\n * @example\n * ```typescript\n * const ctx: StorefrontContext = {\n *   id: 'sc_01J...',\n *   name: 'B2C Storefront',\n *   platformType: 'medusa',\n *   requiresProductScoping: true,\n *   currencyCode: 'USD',\n * };\n * ```\n */\nexport interface StorefrontContext {\n  /**\n   * Unique identifier for this storefront across the system.\n   * Examples: \"sc_123\" (Medusa), \"gid://shopify/Channel/789\" (Shopify), \"1\" (WooCommerce)\n   */\n  id: string;\n\n  /**\n   * Human-readable name for logging and debugging.\n   */\n  name: string;\n\n  /**\n   * Platform this storefront belongs to.\n   */\n  platformType: StorefrontPlatformType;\n\n  /**\n   * Whether products must be explicitly linked/published to this storefront.\n   *\n   * @remarks\n   * - Medusa: true (products must be linked to sales channel)\n * - Shopify: false (products visible by default unless unlisted)\n * - Stel Order: false (single-company ERP model, no native channel scoping)\n * - WooCommerce: false (no scoping concept)\n * - BigCommerce: false (products visible by default unless delisted)\n * - Spree: true (products must be assigned per store)\n * - Magento: true (products must be assigned per website)\n   */\n  requiresProductScoping: boolean;\n\n  /**\n   * Primary currency code for this storefront.\n   * Examples: \"USD\", \"EUR\", \"GBP\"\n   */\n  currencyCode: string;\n\n  /**\n   * Optional region or locale code.\n   * Examples: \"US\", \"EU\", \"en-US\", \"es-ES\"\n   */\n  locale?: string;\n\n  /**\n   * Optional: Store/Channel metadata from platform.\n   * @internal\n   */\n  metadata?: Record<string, unknown>;\n}\n\n/**\n * Storefront validation error.\n * Thrown when storefront configuration is invalid or missing.\n *\n * @example\n * ```typescript\n * throw new StorefrontConfigError(\n *   'Medusa requires NEXT_PUBLIC_SALES_CHANNEL_ID',\n *   'medusa',\n *   'NEXT_PUBLIC_SALES_CHANNEL_ID',\n * );\n * ```\n */\nexport class StorefrontConfigError extends Error {\n  public readonly platformType: string;\n  public readonly requiredEnvVar?: string;\n\n  constructor(\n    message: string,\n    platformType: string,\n    requiredEnvVar?: string,\n  ) {\n    super(message);\n    this.name = 'StorefrontConfigError';\n    this.platformType = platformType;\n    this.requiredEnvVar = requiredEnvVar;\n  }\n}\n"],"mappings":";AAkCO,IAAK,wBAAL,kBAAKA,2BAAL;AACL,EAAAA,uBAAA,UAAO;AACP,EAAAA,uBAAA,YAAS;AACT,EAAAA,uBAAA,eAAY;AAHF,SAAAA;AAAA,GAAA;AAyBL,IAAM,oBAST;AAAA,EACF,MAAM;AAAA,IACJ,MAAM;AAAA,IACN,aAAa;AAAA,IACb,oBAAoB;AAAA,IACpB,iBAAiB,CAAC;AAAA,IAClB,YAAY;AAAA,EACd;AAAA,EACA,QAAQ;AAAA,IACN,MAAM;AAAA,IACN,aAAa;AAAA,IACb,oBAAoB;AAAA,IACpB,iBAAiB;AAAA,MACf;AAAA,MACA;AAAA,MACA;AAAA,IACF;AAAA,IACA,YAAY;AAAA,EACd;AAAA,EACA,WAAW;AAAA,IACT,MAAM;AAAA,IACN,aAAa;AAAA,IACb,oBAAoB;AAAA,IACpB,iBAAiB;AAAA,MACf;AAAA,MACA;AAAA,IACF;AAAA,IACA,YAAY;AAAA,EACd;AACF;AAYO,SAAS,wBACd,OAC6B;AAC7B,SACE,OAAO,UAAU,YACjB,OAAO,OAAO,qBAAqB,EAAE,SAAS,KAA8B;AAEhF;AAYO,SAAS,oBACd,MACgD;AAChD,MAAI,CAAC,wBAAwB,IAAI,GAAG;AAClC,UAAM,IAAI;AAAA,MACR,yBAAyB,IAAI,gBAAgB,OAAO;AAAA,QAClD;AAAA,MACF,EAAE,KAAK,IAAI,CAAC;AAAA,IACd;AAAA,EACF;AACA,SAAO,kBAAkB,IAAI;AAC/B;;;ACzBO,IAAM,wBAAN,cAAoC,MAAM;AAAA,EAC/B;AAAA,EACA;AAAA,EAEhB,YACE,SACA,cACA,gBACA;AACA,UAAM,OAAO;AACb,SAAK,OAAO;AACZ,SAAK,eAAe;AACpB,SAAK,iBAAiB;AAAA,EACxB;AACF;","names":["SupportedProviderType"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thorprovider/types",
-  "version": "3.2.0",
+  "version": "3.3.0",
   "description": "Shared TypeScript types for Thor Commerce ecosystem - Framework-agnostic type definitions",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -17,9 +17,10 @@
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "development": "./src/index.ts",
-      "import": "./dist/index.js",
-      "require": "./dist/index.js"
+      "development": "./dist/index.mjs",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js",
+      "default": "./dist/index.mjs"
     }
   },
   "scripts": {

package/src/admin/MultiTenantAdmin.ts

@@ -0,0 +1,295 @@
+/**
+ * @thorprovider/types — Multi-Tenant Admin Types
+ *
+ * Type definitions for admin operations on the Thor Commerce multi-tenant
+ * backend plugin (`/admin/thor/`).
+ *
+ * These types map 1:1 to the API contract defined in
+ * `multitenant-api-contract.md`.
+ *
+ * @module admin/MultiTenantAdmin
+ */
+
+// ============================================================
+// Sales Channel — Customers
+// ============================================================
+
+/**
+ * A customer entry as returned by the admin multi-tenant API.
+ */
+export interface AdminChannelCustomer {
+  id: string;
+  email: string;
+  first_name: string | null;
+  last_name: string | null;
+  phone: string | null;
+  created_at: string;
+}
+
+/** Response for `GET /admin/thor/sales-channels/:id/customers` */
+export interface GetChannelCustomersResponse {
+  customers: AdminChannelCustomer[];
+  count: number;
+  limit: number;
+  offset: number;
+}
+
+/** Options for paginating channel customers */
+export interface GetChannelCustomersOptions {
+  /** Max customers to return (default 20, max 100) */
+  limit?: number;
+  /** Pagination offset (default 0) */
+  offset?: number;
+}
+
+// ============================================================
+// Sales Channel — API Keys
+// ============================================================
+
+/**
+ * A publishable API key entry as returned by the admin multi-tenant API.
+ */
+export interface AdminApiKey {
+  id: string;
+  title: string;
+  token: string;
+  type: 'publishable' | string;
+  created_at: string;
+}
+
+/** Response for `GET /admin/thor/sales-channels/:id/api-keys` */
+export interface GetChannelApiKeysResponse {
+  api_keys: AdminApiKey[];
+}
+
+// ============================================================
+// Sales Channel — Categories
+// ============================================================
+
+/**
+ * A product category entry as returned by admin channel category endpoints.
+ */
+export interface AdminChannelCategory {
+  id: string;
+  name: string;
+  handle: string;
+  description: string | null;
+  parent_category_id: string | null;
+  rank: number;
+  metadata: Record<string, unknown>;
+}
+
+/** Response for `GET /admin/thor/sales-channels/:id/categories` */
+export interface GetChannelCategoriesResponse {
+  categories: AdminChannelCategory[];
+  count: number;
+}
+
+/** Options for listing channel categories */
+export interface GetChannelCategoriesOptions {
+  /** Max categories per page (default 20, max 100) */
+  limit?: number;
+  /** Pagination offset (default 0) */
+  offset?: number;
+  /** Expand child categories in nested tree */
+  include_descendants?: boolean;
+}
+
+/**
+ * A slim sales channel reference returned when listing channels for a resource.
+ */
+export interface AdminSalesChannelRef {
+  id: string;
+  name: string;
+  description?: string;
+}
+
+/** Response for `GET /admin/thor/categories/:id/sales-channels` */
+export interface GetCategorySalesChannelsResponse {
+  sales_channels: AdminSalesChannelRef[];
+}
+
+/** Body for `POST /admin/thor/categories/:id/sales-channels` */
+export interface AssignCategoriesToChannelsBody {
+  sales_channel_ids: string[];
+}
+
+/** Response for `POST /admin/thor/categories/:id/sales-channels` */
+export interface AssignCategoriesToChannelsResponse {
+  message: string;
+  linked: number;
+}
+
+/** Body for `DELETE /admin/thor/categories/:id/sales-channels` */
+export interface UnassignCategoriesFromChannelsBody {
+  sales_channel_ids: string[];
+}
+
+/** Response for `DELETE /admin/thor/categories/:id/sales-channels` */
+export interface UnassignCategoriesFromChannelsResponse {
+  message: string;
+  dismissed: number;
+}
+
+// ============================================================
+// Collections — Channel Mapping
+// ============================================================
+
+/** Response for `GET /admin/thor/collections/:id/sales-channels` */
+export interface GetCollectionSalesChannelsResponse {
+  sales_channels: AdminSalesChannelRef[];
+}
+
+/** Body for `POST /admin/thor/collections/:id/sales-channels` */
+export interface AssignCollectionsToChannelsBody {
+  sales_channel_ids: string[];
+}
+
+/** Response for `POST /admin/thor/collections/:id/sales-channels` */
+export interface AssignCollectionsToChannelsResponse {
+  message: string;
+  linked: number;
+}
+
+/** Body for `DELETE /admin/thor/collections/:id/sales-channels` */
+export interface UnassignCollectionsFromChannelsBody {
+  sales_channel_ids: string[];
+}
+
+/** Response for `DELETE /admin/thor/collections/:id/sales-channels` */
+export interface UnassignCollectionsFromChannelsResponse {
+  message: string;
+  dismissed: number;
+}
+
+// ============================================================
+// Storefront Config (Admin CRUD)
+// ============================================================
+
+/**
+ * SEO defaults as stored in the storefront config.
+ */
+export interface AdminStorefrontSeoDefaults {
+  title: string;
+  description: string;
+  ogImage?: string;
+}
+
+/**
+ * Full storefront config record as returned by admin endpoints.
+ * Uses snake_case to match the API contract response shape exactly.
+ */
+export interface AdminStorefrontConfig {
+  id: string;
+  sales_channel_id: string;
+  theme_accent_color: string;
+  logo_url: string;
+  currency_code: string;
+  seo_defaults: AdminStorefrontSeoDefaults;
+  frontend_webhook_url?: string;
+  created_at: string;
+  updated_at: string;
+}
+
+/** Response for `GET /admin/thor/storefront-config/:id` */
+export interface GetAdminStorefrontConfigResponse {
+  storefront_config: AdminStorefrontConfig;
+}
+
+/** Body for `PUT /admin/thor/storefront-config/:id` */
+export interface UpdateStorefrontConfigBody {
+  theme_accent_color: string;
+  logo_url: string;
+  currency_code: string;
+  seo_defaults: {
+    title: string;
+    description: string;
+    ogImage?: string;
+  };
+  frontend_webhook_url?: string;
+}
+
+/** Response for `PUT /admin/thor/storefront-config/:id` */
+export interface UpdateStorefrontConfigResponse {
+  storefront_config: AdminStorefrontConfig;
+}
+
+// ============================================================
+// Site Designer Config (Admin CRUD + History + Restore)
+// ============================================================
+
+/**
+ * A single history entry for the Site Designer config.
+ */
+export interface AdminSiteConfigHistoryEntry {
+  id?: string;
+  version: string;
+  createdAt: string;
+  createdBy?: string;
+}
+
+/**
+ * Full site config record as returned by admin endpoints.
+ * `config` is the free-form `DesignerConfig` JSON object.
+ */
+export interface AdminSiteConfig {
+  id: string;
+  sales_channel_id: string;
+  version: string;
+  /** Free-form DesignerConfig object managed by the Site Designer */
+  config: Record<string, unknown>;
+  history?: AdminSiteConfigHistoryEntry[];
+  created_at?: string;
+  updated_at?: string;
+}
+
+/** Response for `GET /admin/thor/site-config/:sales_channel_id` */
+export interface GetAdminSiteConfigResponse {
+  site_config: AdminSiteConfig;
+}
+
+/** Body for `PUT /admin/thor/site-config/:sales_channel_id` */
+export type UpdateSiteConfigBody = Record<string, unknown>;
+
+/** Response for `PUT /admin/thor/site-config/:sales_channel_id` */
+export interface UpdateSiteConfigResponse {
+  site_config: AdminSiteConfig;
+}
+
+/**
+ * A full history entry including the stored config snapshot.
+ */
+export interface AdminSiteConfigHistoryEntryFull {
+  id: string;
+  version: string;
+  config: Record<string, unknown>;
+  createdAt: string;
+  createdBy?: string;
+}
+
+/** Response for `GET /admin/thor/site-config/:sales_channel_id/history` */
+export interface GetAdminSiteConfigHistoryResponse {
+  history: AdminSiteConfigHistoryEntryFull[];
+  count: number;
+}
+
+/** Options for paginating site config history */
+export interface GetAdminSiteConfigHistoryOptions {
+  limit?: number;
+  offset?: number;
+}
+
+/** Response for `POST /admin/thor/site-config/:sales_channel_id/restore/:version` */
+export interface RestoreSiteConfigResponse {
+  site_config: AdminSiteConfig;
+}
+
+// ============================================================
+// Channel Link — Store endpoints
+// ============================================================
+
+/** Response for `POST /store/thor/customers/me/channels` */
+export interface LinkCustomerToChannelResponse {
+  linked: boolean;
+  reason?: 'already_linked';
+}

package/src/admin/index.ts

@@ -11,3 +11,4 @@ export * from './AuditLog';
 export * from './DashboardConfig';
 export * from './DashboardMetrics';
 export * from './SiteConfigMetadata';
+export * from './MultiTenantAdmin';

package/src/auth.ts

@@ -233,35 +233,22 @@ export interface AuthProvider {
    * Only implemented if capabilities.deleteAccount is true.
    */
   deleteCustomerAccount(): Promise<void>;
-  
+
   // ========================================
-  // Address Management
+  // Multi-Tenant — Channel Link
   // ========================================
-  
-  /**
-   * Get customer addresses
-   * @returns List of customer addresses
-   */
-  getAddresses(): Promise<Address[]>;
-  
-  /**
-   * Create new address for current customer
-   * @param data - Address data
-   * @returns Created address
-   */
-  createAddress(data: CreateAddressData): Promise<Address>;
-  
-  /**
-   * Update customer address
-   * @param addressId - Address ID
-   * @param data - Fields to update
-   * @returns Updated address
-   */
-  updateAddress(addressId: string, data: Partial<CreateAddressData>): Promise<Address>;
-  
+
   /**
-   * Delete customer address
-   * @param addressId - Address ID
-   */
-  deleteAddress(addressId: string): Promise<void>;
+   * Link the currently authenticated customer to the storefront's sales channel.
+   *
+   * Call immediately after a successful `login()` so the customer appears in the
+   * correct channel on the admin panel. Idempotent — repeated calls return
+   * `{ linked: false, reason: 'already_linked' }`.
+   *
+   * Implements `POST /store/thor/customers/me/channels`.
+   *
+   * @returns `{ linked: true }` when the link was created, or
+   *          `{ linked: false, reason: 'already_linked' }` when it already existed.
+   */
+  linkCustomerToChannel(): Promise<{ linked: boolean; reason?: string }>;
 }

package/src/index.ts

@@ -132,13 +132,7 @@ export type {
 // ============================================
 // Provider Types (L1 - Source of Truth)
 // ============================================
-export enum SupportedProviderType {
-  Mock = 'mock',
-  Medusa = 'medusa',
-}
-
-// Re-export provider types directly
-export { type ProviderTypeString } from './provider';
+export { SupportedProviderType, type ProviderTypeString } from './provider';
 
 export {
   isSupportedProviderType,
@@ -232,6 +226,41 @@ export type {
   AuditLogAdapter,
   SiteConfigMetadata,
   ConfigHistoryEntry,
+  // Multi-tenant admin types
+  AdminChannelCustomer,
+  GetChannelCustomersResponse,
+  GetChannelCustomersOptions,
+  AdminApiKey,
+  GetChannelApiKeysResponse,
+  AdminChannelCategory,
+  GetChannelCategoriesResponse,
+  GetChannelCategoriesOptions,
+  AdminSalesChannelRef,
+  GetCategorySalesChannelsResponse,
+  AssignCategoriesToChannelsBody,
+  AssignCategoriesToChannelsResponse,
+  UnassignCategoriesFromChannelsBody,
+  UnassignCategoriesFromChannelsResponse,
+  GetCollectionSalesChannelsResponse,
+  AssignCollectionsToChannelsBody,
+  AssignCollectionsToChannelsResponse,
+  UnassignCollectionsFromChannelsBody,
+  UnassignCollectionsFromChannelsResponse,
+  AdminStorefrontSeoDefaults,
+  AdminStorefrontConfig,
+  GetAdminStorefrontConfigResponse,
+  UpdateStorefrontConfigBody,
+  UpdateStorefrontConfigResponse,
+  AdminSiteConfigHistoryEntry,
+  AdminSiteConfig,
+  GetAdminSiteConfigResponse,
+  UpdateSiteConfigBody,
+  UpdateSiteConfigResponse,
+  AdminSiteConfigHistoryEntryFull,
+  GetAdminSiteConfigHistoryResponse,
+  GetAdminSiteConfigHistoryOptions,
+  RestoreSiteConfigResponse,
+  LinkCustomerToChannelResponse,
 } from './admin';
 
 // ============================================