@thorprovider/types 2.0.2

package/src/common.ts

@@ -0,0 +1,95 @@
+/**
+ * @thorprovider/types v3.0
+ * Common types shared across all commerce providers
+ * Universal interfaces compatible with: Shopify, Medusa.js, WooCommerce, Magento, BigCommerce
+ */
+
+/**
+ * Monetary value with currency
+ * 
+ * Using string for amount prevents float precision errors.
+ * Compatible with:
+ * - Shopify: MoneyV2 (amount: Decimal, currencyCode: CurrencyCode)
+ * - Medusa: numbers (converted to string)
+ * - WooCommerce: strings ("21.99")
+ * - Magento: Float (converted to string)
+ */
+export interface Money {
+  amount: string;  // Decimal as string (e.g., "45.00")
+  currencyCode: string;  // ISO 4217 code (e.g., "USD", "EUR")
+}
+
+/**
+ * Image with metadata
+ * 
+ * Universal format for product/variant images.
+ * Compatible with all platforms (URLs are normalized in adapters).
+ */
+export interface Image {
+  id?: string;  // Optional platform-specific ID
+  url: string;
+  altText: string;
+  width?: number;  // Optional for platforms without dimensions
+  height?: number;
+}
+
+/**
+ * SEO metadata
+ */
+export interface SEO {
+  title: string;
+  description: string;
+}
+
+/**
+ * Generic connection type for paginated data
+ */
+export interface Connection<T> {
+  edges: Array<Edge<T>>;
+}
+
+export interface Edge<T> {
+  node: T;
+}
+
+/**
+ * Pagination options
+ */
+export interface PaginationOptions {
+  first?: number;
+  after?: string;
+  last?: number;
+  before?: string;
+}
+
+/**
+ * Sort options
+ */
+export interface SortOptions {
+  sortKey?: string;
+  reverse?: boolean;
+}
+
+/**
+ * Country information
+ * 
+ * Represents a country available in a region.
+ * Used for shipping address validation and checkout forms.
+ * Compatible with:
+ * - Medusa: Country entity with iso_2, name, display_name
+ * - Shopify: CountryCode enum
+ * - WooCommerce: WC_Countries
+ */
+export interface Country {
+  /** ISO 3166-1 alpha-2 country code (e.g., "US", "ES", "DE") */
+  code: string;
+  
+  /** Human-readable country name (e.g., "United States", "Spain") */
+  name: string;
+  
+  /** ISO 3166-1 alpha-3 country code (optional, e.g., "USA", "ESP") */
+  iso3?: string;
+  
+  /** ISO 3166-1 numeric code (optional, e.g., "840", "724") */
+  numCode?: string;
+}

package/src/customer.ts

@@ -0,0 +1,122 @@
+/**
+ * @thorprovider/types v3.0
+ * Customer types - unified interface for all commerce providers
+ * Universal interfaces compatible with: Shopify, Medusa.js, WooCommerce, Magento, BigCommerce
+ */
+
+/**
+ * Customer address
+ * 
+ * Universal format using camelCase (JavaScript convention).
+ * 
+ * Platform mapping:
+ * - Shopify: MailingAddress (firstName, address1, zip, province, countryCodeV2)
+ * - Medusa: Address (first_name, address_1, postal_code, province, country_code)
+ * - WooCommerce: Address (first_name, address_1, postcode, state, country)
+ * - Magento: Address (firstname, street, postcode, region, country_id)
+ * 
+ * Adapters transform platform-specific snake_case to universal camelCase.
+ */
+export interface Address {
+  id?: string;
+  firstName: string;  // Shopify: firstName, Medusa: first_name, WooCommerce: first_name
+  lastName: string;  // Shopify: lastName, Medusa: last_name, WooCommerce: last_name
+  company?: string;
+  address1: string;  // Shopify: address1, Medusa: address_1, WooCommerce: address_1
+  address2?: string;  // Optional second address line
+  city: string;
+  province?: string;  // State/province (Shopify: province, WooCommerce: state, Magento: region)
+  postalCode: string;  // Shopify: zip, Medusa: postal_code, WooCommerce: postcode
+  countryCode: string;  // ISO 3166-1 alpha-2 code (e.g., "US", "CA", "GB")
+  phone?: string;
+  isDefault?: boolean;  // Whether this is the default/primary address for the customer
+  metadata?: Record<string, unknown>; // Flexible storage for platform-specific extras (label, etc.)
+}
+
+/**
+ * Customer
+ * 
+ * Universal customer format using camelCase.
+ * Adapters transform platform-specific naming to this format.
+ */
+export interface Customer {
+  id: string;
+  email: string;
+  firstName: string | null;  // Platform adapters transform first_name → firstName
+  lastName: string | null;  // Platform adapters transform last_name → lastName
+  phone?: string | null;
+  hasAccount?: boolean;  // Whether customer has a registered account
+  createdAt?: string;  // ISO 8601 timestamp
+  updatedAt?: string;
+  /**
+   * Flexible metadata storage.
+   *
+   * Multi-tenant convention: when `metadata.sales_channel_id` is present the
+   * customer is scoped to that channel.  See `@thorprovider/adapters/metadata` helpers.
+   */
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Custom fetcher callback for advanced customer queries.
+ *
+ * When provided, this callback replaces the default SDK logic entirely.
+ * Useful for: custom API endpoints, backend-specific filters, Module Link queries.
+ *
+ * @example
+ * ```typescript
+ * // Custom endpoint that filters by channel server-side
+ * const customFetcher = async (options: GetCustomersOptions) => {
+ *   const response = await fetch(`/api/admin/sales-channels/${options.salesChannelId}/customers`);
+ *   return response.json();
+ * };
+ *
+ * const customers = await provider.getCustomers({
+ *   salesChannelId: 'sc_123',
+ *   customFetcher,
+ * });
+ * ```
+ */
+export type GetCustomersCallback = (options: GetCustomersOptions) => Promise<Customer[]>;
+
+/**
+ * Options for querying a list of customers.
+ *
+ * Used by CommerceProvider.getCustomers() and admin list endpoints.
+ */
+export interface GetCustomersOptions {
+  /** Full-text search by name or email */
+  search?: string;
+  /** Maximum number of results */
+  limit?: number;
+  /** Zero-based offset for pagination */
+  offset?: number;
+  /** Field to sort results by */
+  sortBy?: 'createdAt' | 'email' | 'firstName';
+  /**
+   * Filter customers to a specific sales channel.
+   *
+   * When set, only customers whose `metadata.sales_channel_id` matches
+   * this value are returned.  Enables multi-tenant isolation for
+   * dropshippers who should only see their own customers.
+   *
+   * If omitted, all customers are returned (admin/super-admin view).
+   */
+  salesChannelId?: string;
+  /**
+   * Custom fetcher callback (optional).
+   *
+   * When provided, this callback is invoked instead of the default SDK logic.
+   * Allows backends to implement custom filters, Module Link queries, or
+   * call alternative endpoints (e.g., `/api/admin/sales-channels/{id}/customers`).
+   *
+   * This option enables:
+   * - **Medusa Module Link**: Query customers via custom module API
+   * - **Custom endpoints**: Call `/api/admin/sales-channels/{id}/customers` for server-side filtering
+   * - **Backend-specific optimizations**: Shopify/WooCommerce adapters can implement their own logic
+   *
+   * @default undefined (uses default SDK + in-memory filter)
+   * @see {@link GetCustomersCallback} for callback signature
+   */
+  customFetcher?: GetCustomersCallback;
+}

package/src/designer-config.ts

@@ -0,0 +1,106 @@
+/**
+ * @thorprovider/types — Site Designer Configuration
+ *
+ * Type definitions for the Site Designer feature.
+ * Describes the visual theme, navigation, and identity configuration
+ * managed through the admin Site Designer and served to storefronts
+ * via `GET /store/thor/site-config`.
+ *
+ * These types are the source of truth (L1) so that both L2 adapters
+ * and L3 components can depend on them without circular imports.
+ *
+ * @module designer-config
+ */
+
+/**
+ * Available theme presets for the Site Designer.
+ */
+export type DesignerThemePreset =
+  | 'electro'
+  | 'midnight'
+  | 'sunset'
+  | 'forest'
+  | 'custom';
+
+/**
+ * Theme configuration managed by the Site Designer.
+ */
+export interface DesignerThemeConfig {
+  /** Active theme preset */
+  preset: DesignerThemePreset;
+
+  /** Accent color name (e.g., "indigo", "blue", "crimson") */
+  accentColor: string;
+
+  /** Gray scale family */
+  grayColor: 'auto' | 'gray' | 'mauve' | 'slate' | 'sage' | 'olive' | 'sand';
+
+  /** Border radius scale */
+  radius: 'none' | 'small' | 'medium' | 'large' | 'full';
+
+  /** Color scheme */
+  appearance: 'light' | 'dark';
+
+  /** UI scaling factor */
+  scaling: '90%' | '95%' | '100%' | '105%' | '110%';
+}
+
+/**
+ * A single navigation item in the Site Designer menu.
+ */
+export interface DesignerNavItem {
+  /** Unique identifier for this nav entry */
+  id: string;
+
+  /** Display label */
+  label: string;
+
+  /** Target URL or path */
+  href: string;
+
+  /** Whether this item is visible to storefront visitors */
+  visible: boolean;
+}
+
+/**
+ * A version history entry for the Site Designer config.
+ */
+export interface DesignerHistoryEntry {
+  /** Version identifier (typically ISO 8601 timestamp) */
+  version: string;
+
+  /** ISO 8601 timestamp of when this version was created */
+  createdAt: string;
+}
+
+/**
+ * Complete Site Designer configuration.
+ *
+ * Persisted per sales channel in the backend and served to the
+ * storefront via `GET /store/thor/site-config`.
+ *
+ * @example
+ * ```typescript
+ * const result = await commerce.getDesignerConfig();
+ * if (result) {
+ *   const { config } = result;
+ *   console.log(config.theme.preset, config.siteName);
+ * }
+ * ```
+ */
+export interface DesignerConfig {
+  /** Theme visual settings */
+  theme: DesignerThemeConfig;
+
+  /** Navigation menu items */
+  navigation: DesignerNavItem[];
+
+  /** Storefront display name */
+  siteName: string;
+
+  /** Storefront description */
+  siteDescription: string;
+
+  /** Logo URL (optional, overrides StorefrontConfig.logoUrl) */
+  logo?: string;
+}

package/src/header-config.README.md

@@ -0,0 +1,321 @@
+# Header Configuration Types
+Type definitions for configurable header navigation in Thor Commerce.
+
+## Overview
+
+This module provides a complete type system for defining header navigation structure via configuration instead of hardcoded JSX. Enables CMS-like customization of site headers without modifying components.
+
+## Core Types
+
+### `HeaderNavigationConfig`
+
+Root configuration interface for the entire header structure.
+
+```typescript
+interface HeaderNavigationConfig {
+  logo: {
+    src: string
+    alt: string
+    width: number
+    height: number
+    href: string
+  }
+  leftLinks?: HeaderLinkItem[]
+  rightLinks?: HeaderLinkItem[]
+  search?: {
+    enabled: boolean
+    width: number
+    placeholder?: string
+  }
+  account?: {
+    items: AccountMenuItem[]
+  }
+  cart?: {
+    label?: string
+    variant?: 'mini' | 'drawer'
+    composition?: 'compact' | 'detailed'
+    showBadge?: boolean
+  }
+}
+```
+
+### `HeaderLinkItem`
+
+Discriminated union for different link types in the navigation.
+
+**Types:**
+1. **Direct Link** - Simple href navigation
+2. **Dropdown Menu** - Multi-item dropdown with optional dynamic data
+3. **Preset Component** - Pre-built components (cart, account)
+
+```typescript
+type HeaderLinkItem = 
+  | { type: 'link'; label: string; href: string; icon?: IconConfig }
+  | { 
+      type: 'dropdown'
+      trigger: { label: string; icon?: IconConfig }
+      items: NavigationMenuItem[]
+      dynamicSource?: DynamicSource
+    }
+  | { type: 'preset'; preset: PresetType }
+```
+
+**Discriminated Union Benefits:**
+- TypeScript enforces valid combinations at compile-time
+- IntelliSense provides accurate property suggestions based on `type`
+- Impossible to create invalid states (e.g., a link with dropdown items)
+
+### `AccountMenuItem`
+
+Discriminated union for account dropdown menu items.
+
+```typescript
+type AccountMenuItem =
+  | {
+      type: 'item'
+      label: string
+      href?: string
+      action?: string
+      icon?: IconConfig
+      destructive?: boolean
+      // Discriminator ensures divider can't have these
+      divider?: never
+    }
+  | {
+      type: 'divider'
+      // Discriminator ensures divider can't have item properties
+      label?: never
+      href?: never
+      action?: never
+      icon?: never
+      destructive?: never
+    }
+```
+
+**Usage:**
+```typescript
+const accountItems: AccountMenuItem[] = [
+  { type: 'item', label: 'Profile', href: '/profile' },
+  { type: 'divider' },
+  { type: 'item', label: 'Logout', action: 'logout', destructive: true }
+]
+```
+
+### `IconConfig`
+
+Hybrid type supporting both Lucide icon names and custom React nodes.
+
+```typescript
+type IconConfig = string | React.ReactNode
+```
+
+**Examples:**
+```typescript
+// Lucide icon name (resolved at runtime)
+icon: 'ShoppingBag'
+
+// Custom React component
+icon: <CustomIcon className="w-4 h-4" />
+```
+
+### `DynamicSource`
+
+Backend data sources for dynamic content injection.
+
+```typescript
+type DynamicSource = 'categories' | 'collections'
+```
+
+**Use Case:**
+```typescript
+{
+  type: 'dropdown',
+  trigger: { label: 'Categories' },
+  dynamicSource: 'categories', // Fetch from Medusa backend
+  items: [] // Will be populated at runtime
+}
+```
+
+### `PresetType`
+
+Type-safe identifiers for pre-built components.
+
+```typescript
+type PresetType = 'cart' | 'account'
+```
+
+**Rendering:**
+- `'cart'` → Renders `CartModule` (mini cart with badge)
+- `'account'` → Renders `AccountMenu` (dropdown with user actions)
+
+## Design Patterns
+
+### Discriminated Unions
+
+Used extensively to prevent invalid states at compile-time:
+
+```typescript
+// ✅ Valid
+const link: HeaderLinkItem = {
+  type: 'link',
+  label: 'Products',
+  href: '/products'
+}
+
+// ❌ TypeScript Error: 'items' not allowed on 'link' type
+const invalid: HeaderLinkItem = {
+  type: 'link',
+  label: 'Products',
+  href: '/products',
+  items: [] // Error!
+}
+```
+
+### Never Constraints
+
+Ensure mutually exclusive properties in discriminated unions:
+
+```typescript
+// Divider can't have label (enforced by `label?: never`)
+const divider: AccountMenuItem = {
+  type: 'divider',
+  label: 'Invalid' // TypeScript Error!
+}
+```
+
+## Type Guards
+
+Helper functions to narrow types at runtime:
+
+```typescript
+function isLinkItem(item: HeaderLinkItem): item is { type: 'link' } {
+  return item.type === 'link'
+}
+
+function isDropdownItem(item: HeaderLinkItem): item is { type: 'dropdown' } {
+  return item.type === 'dropdown'
+}
+```
+
+## Usage Example
+
+Complete header configuration in `site.config.ts`:
+
+```typescript
+import type { HeaderNavigationConfig } from '@thorprovider/types'
+
+export const siteConfig = {
+  header: {
+    logo: {
+      src: '/logo.svg',
+      alt: 'My Store',
+      width: 120,
+      height: 40,
+      href: '/'
+    },
+    leftLinks: [
+      { 
+        type: 'link', 
+        label: 'Products', 
+        href: '/products',
+        icon: 'ShoppingBag'
+      },
+      {
+        type: 'dropdown',
+        trigger: { label: 'Categories' },
+        dynamicSource: 'categories', // Fetches from backend
+        items: []
+      }
+    ],
+    rightLinks: [
+      { type: 'preset', preset: 'account' },
+      { type: 'preset', preset: 'cart' }
+    ],
+    search: {
+      enabled: true,
+      width: 400
+    },
+    account: {
+      items: [
+        { type: 'item', label: 'Profile', href: '/profile', icon: 'User' },
+        { type: 'item', label: 'Orders', href: '/orders', icon: 'Package' },
+        { type: 'divider' },
+        { 
+          type: 'item', 
+          label: 'Logout', 
+          action: 'logout',
+          destructive: true,
+          icon: 'LogOut'
+        }
+      ]
+    }
+  } satisfies HeaderNavigationConfig
+}
+```
+
+## Related Types
+
+This module imports navigation types from `@thorprovider/components`:
+
+```typescript
+import type { NavigationMenuItem } from '@thorprovider/components'
+```
+
+Used for dropdown item structure consistency across the application.
+
+## Type Safety Benefits
+
+1. **Compile-time validation**: Invalid configurations fail at build time
+2. **IntelliSense support**: Full autocomplete in IDEs
+3. **Refactoring safety**: Type changes propagate through the codebase
+4. **Self-documenting**: Types serve as inline documentation
+5. **Prevents runtime errors**: Impossible states caught before deployment
+
+## Migration Path
+
+**Before (untyped configuration):**
+```typescript
+const header = {
+  links: [
+    { label: 'Products', href: '/products', items: [] } // Ambiguous!
+  ]
+}
+```
+
+**After (type-safe):**
+```typescript
+const header = {
+  leftLinks: [
+    { type: 'link', label: 'Products', href: '/products' }
+  ]
+} satisfies HeaderNavigationConfig
+```
+
+TypeScript now enforces `HeaderLinkItem` shape, preventing mixed concerns.
+
+## Future Extensions
+
+Extend types to support new features:
+
+```typescript
+// Add new preset types
+type PresetType = 'cart' | 'account' | 'notifications' | 'search'
+
+// Add new dynamic sources
+type DynamicSource = 'categories' | 'collections' | 'pages' | 'blog-posts'
+
+// Add link badges
+interface HeaderLinkItem {
+  // ... existing properties
+  badge?: {
+    value: number | string
+    variant: 'solid' | 'soft' | 'outline'
+  }
+}
+```
+
+## See Also
+
+- **@thorprovider/components**: `NavigationMenu`, `AccountMenu`, `OverflowMenu` components
+- **@thorprovider/core**: `HeaderLayout` orchestrator consuming these types
+- **V0 Starter Layout README**: Implementation details and usage patterns