@thorprovider/types 2.0.2

package/src/provider.ts

@@ -0,0 +1,174 @@
+/**
+ * @thorprovider/types — Supported Providers
+ *
+ * Centralized list of all supported commerce providers.
+ * This is the single source of truth for provider types across the monorepo.
+ *
+ * @remarks
+ * - L1 (Foundation): Defines the contract
+ * - L2 (@thorprovider/adapters) imports from here to build the factory
+ * - L5 (Starters) uses the factory which is bound to this enum
+ *
+ * When adding a new provider (e.g., Shopify):
+ * 1. Add to SupportedProviderType enum below
+ * 2. Update @thorprovider/adapters factory/index.ts with discriminated union
+ * 3. Create packages/adapters/src/providers/shopify/
+ * 4. Implement CommerceProvider interface
+ * 5. Update StorefrontPlatformType in storefront.ts (automatically synced)
+ */
+
+/**
+ * All supported commerce platform providers.
+ * Currently only 'medusa' is implemented; others are placeholders for future expansion.
+ *
+ * @remarks Implementation status:
+ * - ✅ medusa: Fully implemented
+ * - 🟡 shopify: Planned (Phase 2)
+ * - 🟡 bigcommerce: Planned (Phase 2)
+ * - 🟡 woocommerce: Planned (Phase 3)
+ * - 🟡 spree: Planned (Phase 3)
+ * - 🟡 magento: Planned (Phase 3)
+ */
+export enum SupportedProviderType {
+  Medusa = 'medusa',
+  Shopify = 'shopify',
+  BigCommerce = 'bigcommerce',
+  WooCommerce = 'woocommerce',
+  Spree = 'spree',
+  Magento = 'magento',
+}
+
+/**
+ * Union type of all supported provider string values.
+ * Use this for type annotations when a provider type is expected.
+ *
+ * @example
+ * ```typescript
+ * function getProviderName(type: ProviderTypeString): string {
+ *   // type is 'medusa'
+ * }
+ * ```
+ */
+export type ProviderTypeString = 'medusa' | 'shopify' | 'bigcommerce' | 'woocommerce' | 'spree' | 'magento';
+
+/**
+ * Metadata about each provider.
+ * Useful for UI, error messages, validation, and documentation.
+ *
+ * @internal
+ */
+export const PROVIDER_METADATA: Record<
+  ProviderTypeString,
+  {
+    name: string;
+    description: string;
+    requiresStorefront: boolean;
+    requiredEnvVars: string[];
+    maxRetries: number;
+  }
+> = {
+  medusa: {
+    name: 'Medusa JS',
+    description: 'Medusa v2 commerce engine',
+    requiresStorefront: true,
+    requiredEnvVars: [
+      'NEXT_PUBLIC_COMMERCE_API_URL',
+      'NEXT_PUBLIC_COMMERCE_API_KEY',
+      'NEXT_PUBLIC_SALES_CHANNEL_ID',
+    ],
+    maxRetries: 3,
+  },
+  shopify: {
+    name: 'Shopify',
+    description: 'Shopify Storefront API (GraphQL)',
+    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',
+    ],
+    maxRetries: 3,
+  },
+};
+
+/**
+ * Check if a string is a valid provider type.
+ *
+ * @example
+ * ```typescript
+ * if (isSupportedProviderType(process.env.COMMERCE_PROVIDER)) {
+ *   // type is narrowed to ProviderTypeString
+ * }
+ * ```
+ */
+export function isSupportedProviderType(
+  value: unknown
+): value is ProviderTypeString {
+  return (
+    typeof value === 'string' &&
+    Object.values(SupportedProviderType).includes(value as SupportedProviderType)
+  );
+}
+
+/**
+ * Get metadata for a provider type.
+ * Useful for validation, error messages, and logging.
+ *
+ * @example
+ * ```typescript
+ * const meta = getProviderMetadata('medusa');
+ * console.log(`Using ${meta.name} with max ${meta.maxRetries} retries`);
+ * ```
+ */
+export function getProviderMetadata(
+  type: ProviderTypeString
+): (typeof PROVIDER_METADATA)[ProviderTypeString] {
+  if (!isSupportedProviderType(type)) {
+    throw new Error(
+      `Unsupported provider: ${type}. Supported: ${Object.values(
+        SupportedProviderType
+      ).join(', ')}`
+    );
+  }
+  return PROVIDER_METADATA[type];
+}

package/src/region.ts

@@ -0,0 +1,43 @@
+/**
+ * @thorprovider/types v3.0
+ * Region types - geographic region configuration
+ * Universal interfaces compatible with: Shopify Markets, Medusa Regions, WooCommerce Zones
+ */
+
+/**
+ * Geographic region configuration
+ * 
+ * Represents a regional market with specific currency, tax, and payment settings.
+ * 
+ * Platform mapping:
+ * - Shopify: Market (primaryDomain, regions, currencySettings)
+ * - Medusa: Region (currency_code, countries, payment_providers, tax_rate)
+ * - WooCommerce: Shipping Zone + Tax Settings (combined concept)
+ * 
+ * Adapters transform platform-specific region data to this universal format.
+ */
+export interface Region {
+  /** Unique region identifier */
+  id: string;
+  
+  /** Region name (e.g., "United States", "Europe", "North America") */
+  name: string;
+  
+  /** ISO 3166-1 alpha-2 country codes included in this region (e.g., ["US", "CA"]) */
+  countryCodes: string[];
+  
+  /** Default currency for this region (ISO 4217 code, e.g., "USD", "EUR") */
+  currency: string;
+  
+  /** Available payment provider IDs in this region */
+  paymentProviders?: string[];
+  
+  /** Tax rate for this region (as decimal, e.g., 0.08 for 8%) */
+  taxRate?: number;
+  
+  /** Whether this region is enabled and available for customers */
+  isEnabled?: boolean;
+  
+  /** Additional region metadata for platform-specific features */
+  metadata?: Record<string, unknown>;
+}

package/src/site-config-labels.ts

@@ -0,0 +1,87 @@
+/**
+ * SiteConfigLabels - All translatable strings from site-config
+ *
+ * Maps to messages/siteConfig.* namespace in next-intl.
+ * Used in L5 to provide i18n-aware labels to components that otherwise use siteConfig.
+ *
+ * IMPORTANT: This interface contains ONLY translatable text — no hrefs, images, or structural config.
+ * Structural config (hrefs, images, module presets) stays in site-config.ts.
+ *
+ * Footer/featuredCategories labels are simple string arrays mapped by index to
+ * the corresponding entries in siteConfig.footerLinks / siteConfig.featuredCategories.
+ *
+ * @see packages/core/messages/en.json (siteConfig namespace)
+ * @see packages/core/hooks/use-site-config-labels.ts
+ */
+export interface SiteConfigLabels {
+  title: string;
+  description: string;
+  tagline: string;
+  header: {
+    products: {
+      label: string;
+      newArrivals: {
+        heading: string;
+        description: string;
+      };
+      summerSale: {
+        heading: string;
+        description: string;
+      };
+      links: {
+        allProducts: string;
+        allProductsDescription: string;
+        newArrivals: string;
+        newArrivalsDescription: string;
+        bestSellers: string;
+        bestSellersDescription: string;
+        sale: string;
+        saleDescription: string;
+      };
+    };
+    categories: {
+      label: string;
+    };
+    account: {
+      label: string;
+      items: {
+        profile: string;
+        orders: string;
+        logout: string;
+      };
+    };
+    cart: {
+      label: string;
+    };
+    search: {
+      placeholder: string;
+    };
+  };
+  footer: {
+    shopTitle: string;
+    supportTitle: string;
+    companyTitle: string;
+    shop: string[];
+    support: string[];
+    company: string[];
+    legal: string[];
+  };
+  hero: {
+    badge: string;
+    title: string;
+    description: string;
+    primaryCta: string;
+    secondaryCta: string;
+  };
+  promo: {
+    badge: string;
+    title: string;
+    description: string;
+    emailPlaceholder: string;
+    ctaText: string;
+  };
+  featuredCategories: string[];
+  copyright: {
+    text: string;
+  };
+}

package/src/site-config.ts

@@ -0,0 +1,148 @@
+/**
+ * Site Configuration Types
+ * 
+ * Foundation for multi-tenant, framework-agnostic site configuration.
+ * Defines the structure for branding, metadata, navigation, and module presets.
+ * 
+ * @module site-config
+ */
+
+import type { HeaderNavigationConfig } from './header-config';
+
+/**
+ * Brand Information
+ */
+export interface BrandConfig {
+  name: string;
+  title: string;
+  description: string;
+  tagline?: string;
+  logo?: string;
+  logoDark?: string;
+  preset?: string;
+}
+
+/**
+ * Site Metadata & Authorship
+ */
+export interface AuthorConfig {
+  /** Name of the author or organization */
+  name: string;
+  
+  /** Primary contact email */
+  email: string;
+}
+
+/**
+ * Social Media Links
+ */
+export type SocialConfig = Record<string, string>;
+
+/**
+ * Navigation Item (Simple)
+ */
+export interface NavigationItem {
+  /** Display name of the link or button */
+  name: string;
+  
+  /** URL or anchor for the link */
+  href: string;
+}
+
+/**
+ * Footer link categorization
+ */
+export interface FooterLinksConfig {
+  /** Customer shopping shortcuts */
+  shop: NavigationItem[];
+  
+  /** Customer service and support links */
+  support: NavigationItem[];
+  
+  /** Corporate and information links */
+  company: NavigationItem[];
+  
+  /** Legal, privacy, and policy links */
+  legal: NavigationItem[];
+}
+
+/**
+ * Copyright information for the site
+ */
+export interface CopyrightConfig {
+  /** Current year or range (e.g., "2024" or "2023-2024") */
+  year: string | number;
+  
+  /** Legal text following the year */
+  text: string;
+}
+
+/**
+ * Module-specific configurations
+ */
+export interface ModulesConfig {
+  cart: {
+    mini: {
+      variant: 'mini';
+      composition: 'compact' | 'full' | 'separate-pages';
+    };
+    page: {
+      variant: 'page';
+      composition: 'compact' | 'full';
+    };
+  };
+  checkout: {
+    default: {
+      variant: 'simple' | 'standard' | 'complete';
+      composition: 'accordion' | 'wizard' | 'single-page';
+    };
+  };
+  profile: {
+    default: {
+      variant: 'basic' | 'standard' | 'complete';
+      composition: 'tabs' | 'accordion' | 'separate-pages' | 'side';
+    };
+  };
+}
+
+/**
+ * Complete Site Configuration
+ * 
+ * Centralized interface for site-wide settings.
+ * Supports merging with database-stored overrides via Developer Dashboard.
+ */
+export interface SiteConfig {
+  /** Brand identity and basic info */
+  name: string;
+  title: string;
+  description: string;
+  tagline?: string;
+  logo?: string;
+  logoDark?: string;
+  preset?: string;
+
+  /** URLs and social */
+  url?: string;
+  author?: AuthorConfig;
+  social?: SocialConfig;
+  
+  /** Navigation structures */
+  navigation?: NavigationItem[];
+  header?: HeaderNavigationConfig;
+  
+  /** Footer content and links */
+  footerLinks: FooterLinksConfig;
+  
+  /** Copyright statement */
+  copyright: CopyrightConfig;
+  
+  /** Module behavior & UI variants */
+  modules: ModulesConfig;
+
+  /** 
+   * Extension point for custom properties 
+   * Necessary for experimental features before they are formally typed
+   */
+  [key: string]: any;
+}
+

package/src/stock-location.ts

@@ -0,0 +1,65 @@
+/**
+ * Inventory & fulfillment types
+ *
+ * Foundation layer (L1) types used by adapters, UI, and starters.
+ */
+
+import type { Money } from './common';
+
+export interface StockLocation {
+  id: string;
+  name: string;
+  address?: {
+    address1: string;
+    address2?: string;
+    city: string;
+    countryCode: string;
+    postalCode: string;
+    province?: string;
+  };
+  metadata?: {
+    lat?: number;
+    lng?: number;
+    timezone?: string;
+  };
+}
+
+export interface InventoryLevel {
+  locationId: string;
+  locationName: string;
+  availableQuantity: number;
+  reservedQuantity: number;
+  incomingQuantity?: number;
+  stockedQuantity: number;
+}
+
+export interface FulfillmentSet {
+  id: string;
+  name: string;
+  type: 'shipping' | 'pickup' | 'return';
+  location: StockLocation;
+}
+
+export interface FulfillmentOption {
+  id: string;
+  providerId: string;
+  name: string;
+  description?: string;
+  price: Money;
+  estimatedDays?: string;
+  stockLocation: StockLocation;
+  fulfillmentSet?: FulfillmentSet;
+  distance?: number;
+}
+
+export type StockStatus = 'in_stock' | 'out_of_stock' | 'low_stock';
+
+export interface StockValidation {
+  allAvailable: boolean;
+  unavailableItems: Array<{
+    variantId: string;
+    productName: string;
+    requestedQuantity: number;
+    availableQuantity: number;
+  }>;
+}

package/src/storefront-config.ts

@@ -0,0 +1,65 @@
+/**
+ * @thorprovider/types — Storefront Configuration
+ *
+ * Type definitions for per-channel storefront configuration
+ * returned by the Thor Commerce backend plugin.
+ *
+ * Consumed by `CommerceProvider.getStorefrontConfig()` in L2 adapters.
+ * Replaces legacy environment variables: NEXT_PUBLIC_ACCENT_COLOR,
+ * NEXT_PUBLIC_LOGO_URL, NEXT_PUBLIC_CURRENCY_CODE.
+ *
+ * @module storefront-config
+ */
+
+/**
+ * SEO default values for a storefront channel.
+ */
+export interface StorefrontSeoDefaults {
+  /** Default page title */
+  title: string;
+
+  /** Default meta description */
+  description: string;
+
+  /** Default Open Graph image URL */
+  ogImage?: string;
+}
+
+/**
+ * Per-channel storefront configuration.
+ *
+ * Returned by `GET /store/thor/config` (resolved via publishable API key).
+ *
+ * @example
+ * ```typescript
+ * const config = await commerce.getStorefrontConfig();
+ * if (config) {
+ *   console.log(config.logoUrl, config.themeAccentColor);
+ * }
+ * ```
+ */
+export interface StorefrontConfig {
+  /** Unique identifier for this storefront config entry */
+  id: string;
+
+  /** Sales channel this config belongs to */
+  salesChannelId: string;
+
+  /** Theme accent color name (e.g., "indigo", "blue", "red") */
+  themeAccentColor: string;
+
+  /** Logo image URL */
+  logoUrl: string;
+
+  /** Default currency code (e.g., "EUR", "USD") */
+  currencyCode: string;
+
+  /** SEO default values */
+  seoDefaults: StorefrontSeoDefaults;
+
+  /** ISO 8601 creation timestamp */
+  createdAt: string;
+
+  /** ISO 8601 last update timestamp */
+  updatedAt: string;
+}

package/src/storefront.ts

@@ -0,0 +1,126 @@
+/**
+ * @thorprovider/types — Storefront Context
+ *
+ * Platform-agnostic representation of a "sales channel" or equivalent.
+ * Abstracts differences between Medusa sales_channel, Shopify publications,
+ * BigCommerce channels, WooCommerce sites, Spree stores, and Magento store views.
+ *
+ * @remarks
+ * - Required for all multi-tenant deployments
+ * - Returned by `CommerceProvider.getStorefrontContext()`
+ * - MUST be validated on startup; errors should NOT be silently ignored
+ */
+
+/**
+ * Supported commerce platform types for storefront identification.
+ *
+ * @remarks
+ * This type is automatically synced with SupportedProviderType from provider.ts.
+ * When adding a new provider, update packages/types/src/provider.ts,
+ * and this type will automatically reflect the new provider.
+ *
+ * Currently supported:
+ * - ✅ 'medusa': Fully implemented
+ *
+ * Planned (not yet implemented):
+ * - 🟡 'shopify': Phase 2
+ * - 🟡 'bigcommerce': Phase 2
+ * - 🟡 'woocommerce': Phase 3
+ * - 🟡 'spree': Phase 3
+ * - 🟡 'magento': Phase 3
+ */
+export type StorefrontPlatformType = 'medusa' | 'shopify' | 'bigcommerce' | 'woocommerce' | 'spree' | 'magento';
+
+/**
+ * StorefrontContext
+ *
+ * Platform-agnostic representation of a "sales channel" or equivalent.
+ *
+ * @example
+ * ```typescript
+ * const ctx: StorefrontContext = {
+ *   id: 'sc_01J...',
+ *   name: 'B2C Storefront',
+ *   platformType: 'medusa',
+ *   requiresProductScoping: true,
+ *   currencyCode: 'USD',
+ * };
+ * ```
+ */
+export interface StorefrontContext {
+  /**
+   * Unique identifier for this storefront across the system.
+   * Examples: "sc_123" (Medusa), "gid://shopify/Channel/789" (Shopify), "1" (WooCommerce)
+   */
+  id: string;
+
+  /**
+   * Human-readable name for logging and debugging.
+   */
+  name: string;
+
+  /**
+   * Platform this storefront belongs to.
+   */
+  platformType: StorefrontPlatformType;
+
+  /**
+   * Whether products must be explicitly linked/published to this storefront.
+   *
+   * @remarks
+   * - Medusa: true (products must be linked to sales channel)
+   * - Shopify: false (products visible by default unless unlisted)
+   * - WooCommerce: false (no scoping concept)
+   * - BigCommerce: false (products visible by default unless delisted)
+   * - Spree: true (products must be assigned per store)
+   * - Magento: true (products must be assigned per website)
+   */
+  requiresProductScoping: boolean;
+
+  /**
+   * Primary currency code for this storefront.
+   * Examples: "USD", "EUR", "GBP"
+   */
+  currencyCode: string;
+
+  /**
+   * Optional region or locale code.
+   * Examples: "US", "EU", "en-US", "es-ES"
+   */
+  locale?: string;
+
+  /**
+   * Optional: Store/Channel metadata from platform.
+   * @internal
+   */
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Storefront validation error.
+ * Thrown when storefront configuration is invalid or missing.
+ *
+ * @example
+ * ```typescript
+ * throw new StorefrontConfigError(
+ *   'Medusa requires NEXT_PUBLIC_SALES_CHANNEL_ID',
+ *   'medusa',
+ *   'NEXT_PUBLIC_SALES_CHANNEL_ID',
+ * );
+ * ```
+ */
+export class StorefrontConfigError extends Error {
+  public readonly platformType: string;
+  public readonly requiredEnvVar?: string;
+
+  constructor(
+    message: string,
+    platformType: string,
+    requiredEnvVar?: string,
+  ) {
+    super(message);
+    this.name = 'StorefrontConfigError';
+    this.platformType = platformType;
+    this.requiredEnvVar = requiredEnvVar;
+  }
+}