@thorprovider/types 2.0.2

package/src/header-config.ts

@@ -0,0 +1,197 @@
+/**
+ * Header Configuration Types
+ * 
+ * Type definitions for configurable header navigation system.
+ * Supports static links, mega menus, preset components (cart, account),
+ * dynamic data injection, and hybrid icon system.
+ */
+
+/**
+ * Icon configuration with hybrid support
+ * - Lucide: Reference by string name for lucide-react icons
+ * - Custom: Provide React component/element directly
+ */
+export type IconConfig = 
+  | { type: 'lucide'; name: string }
+  | { type: 'custom'; component: React.ReactNode };
+
+/**
+ * Navigation callout item (featured content in dropdown)
+ */
+export interface NavigationCalloutItem {
+  logo?: string;
+  image?: string;
+  heading: string;
+  description: string;
+  href: string;
+}
+
+/**
+ * Navigation link item
+ */
+export interface NavigationLinkItem {
+  title: string;
+  description?: string;
+  href: string;
+  badge?: {
+    content: number | string;
+    variant?: 'solid' | 'soft';
+    color?: string;
+  };
+}
+
+/**
+ * Dynamic data source for navigation content
+ * - 'categories': Fetch and inject categories from backend
+ * - 'collections': Fetch and inject collections from backend
+ */
+export type DynamicSource = 'categories' | 'collections';
+
+/**
+ * Header link item - extends NavigationMenuItem with additional features
+ */
+export type HeaderLinkItem =
+  | {
+      /** Simple direct link */
+      type: 'link';
+      label: string;
+      href: string;
+      icon?: IconConfig;
+      badge?: {
+        content: number | string;
+        variant?: 'solid' | 'soft';
+        color?: string;
+      };
+    }
+  | {
+      /** Dropdown menu with content */
+      type: 'dropdown';
+      label: string;
+      icon?: IconConfig;
+      badge?: {
+        content: number | string;
+        variant?: 'solid' | 'soft';
+        color?: string;
+      };
+      /** Optional dynamic data injection */
+      dynamicSource?: DynamicSource;
+      content: {
+        callout?: NavigationCalloutItem;
+        links: NavigationLinkItem[];
+        sideBanner?: NavigationCalloutItem;
+        columns?: number;
+        layout?: 'one' | 'two';
+      };
+    }
+  | {
+      /** Preset component (cart, account) */
+      type: 'preset';
+      preset: 'cart' | 'account';
+      /** Override default config for preset */
+      config?: Record<string, any>;
+    };
+
+/**
+ * Account dropdown menu item
+ */
+export type AccountMenuItem =
+  | {
+      /** Menu item label */
+      label: string;
+      /** Navigation href */
+      href?: string;
+      /** Icon configuration */
+      icon?: IconConfig;
+      /** Click handler (for actions like logout) */
+      onClick?: () => void;
+      /** Destructive action styling (e.g., logout, delete) */
+      destructive?: boolean;
+      divider?: never;
+    }
+  | {
+      /** Render as divider */
+      divider: true;
+      label?: never;
+      href?: never;
+      icon?: never;
+      onClick?: never;
+      destructive?: never;
+    };
+
+/**
+ * Account dropdown configuration
+ */
+export interface AccountDropdownConfig {
+  /** Enable account dropdown */
+  enabled: boolean;
+  /** Trigger label (e.g., "Mi cuenta") */
+  label?: string;
+  /** Trigger icon */
+  icon?: IconConfig;
+  /** Dropdown menu items */
+  items: AccountMenuItem[];
+  /** Logout handler */
+  onLogout?: () => void;
+}
+
+/**
+ * Search bar configuration
+ */
+export interface SearchBarConfig {
+  /** Enable search bar */
+  enabled?: boolean;
+  /** Fixed width in pixels */
+  width?: number;
+  /** Placeholder text */
+  placeholder?: string;
+  /** Minimum characters to trigger search */
+  minChars?: number;
+}
+
+
+/**
+ * Main header navigation configuration
+ */
+export interface HeaderNavigationConfig {
+  /** Logo configuration */
+  logo?: {
+    /** Logo image path */
+    src: string;
+    /** Logo alt text */
+    alt: string;
+    /** Logo width (px) */
+    width?: number;
+    /** Logo height (px) */
+    height?: number;
+    /** Logo link href */
+    href?: string;
+  };
+
+  /** Left navigation group (before search bar) */
+  leftLinks?: HeaderLinkItem[];
+
+  /** Right navigation group (after search bar) */
+  rightLinks?: HeaderLinkItem[];
+
+  /** Search bar configuration */
+  search?: SearchBarConfig;
+
+  /** Account dropdown configuration (if not using preset in rightLinks) */
+  account?: AccountDropdownConfig;
+
+  /** Cart configuration (if not using preset in rightLinks) */
+  cart?: {
+    /** Optional label rendered next to the cart icon in header (e.g., "Carrito") */
+    label?: string;
+    variant?: 'mini' | 'drawer';
+    composition?: 'compact' | 'detailed';
+    showBadge?: boolean;
+  };
+
+  /** Maximum container width (px) */
+  maxWidth?: number;
+
+  /** Enable overflow menu for excess links */
+  enableOverflow?: boolean;
+}
+

package/src/index.ts

@@ -0,0 +1,249 @@
+/**
+ * @thorprovider/types v1.0
+ * Shared TypeScript types for Thor Commerce ecosystem
+ * 
+ * Pure type definitions with zero runtime dependencies.
+ * Foundation for type-safe commerce operations following SOLID principles.
+ */
+
+// ============================================
+// Common Types
+// ============================================
+export type {
+  Money,
+  Image,
+  SEO,
+  Connection,
+  Edge,
+  PaginationOptions,
+  SortOptions,
+  Country,
+} from './common';
+
+export type {
+  AuthorConfig,
+  BrandConfig,
+  ModulesConfig,
+  NavigationItem,
+  SiteConfig,
+  SocialConfig,
+} from './site-config';
+
+export type { SiteConfigLabels } from './site-config-labels';
+
+// ============================================
+// Product Types
+// ============================================
+export type {
+  Product,
+  ProductOption,
+  ProductVariant,
+  SelectedOption,
+  PriceRange,
+  GetProductsOptions,
+  ActiveFilter,
+  SortOption,
+  FilterSection,
+  FilterOption,
+  ProductPreview,
+  Review,
+  CompareProduct,
+  AdminProductVariant,
+  AdminProduct,
+  AdvancedSearchProductsOptions,
+  SearchResultMeta,
+  FilterConfig,
+} from './product';
+
+// ============================================
+// Cart Types
+// ============================================
+export type {
+  Cart,
+  CartItem,
+  CartProduct,
+  CartCost,
+  CartLineInput,
+  CartLineUpdate,
+  ShippingMethod,
+  DiscountCode,
+} from './cart';
+
+// ============================================
+// Inventory & Fulfillment Types
+// ============================================
+export type {
+  StockLocation,
+  InventoryLevel,
+  FulfillmentSet,
+  FulfillmentOption,
+  StockStatus,
+  StockValidation,
+} from './stock-location';
+
+// ============================================
+// Collection Types
+// ============================================
+export type {
+  Collection,
+  CollectionProductsOptions,
+  GetCollectionsOptions,
+} from './collection';
+
+// ============================================
+// Category Types
+// ============================================
+export type {
+  ProductCategory,
+  GetCategoriesOptions,
+  GetCategoriesCallback,
+} from './category';
+
+// ============================================
+// Customer Types
+// ============================================
+export type {
+  Customer,
+  Address,
+  GetCustomersOptions,
+  GetCustomersCallback,
+} from './customer';
+
+// ============================================
+// Region Types
+// ============================================
+export type {
+  Region,
+} from './region';
+
+// ============================================
+// Order Types
+// ============================================
+export type {
+  Order,
+  OrderItem,
+  OrderStatus,
+  PaymentStatus,
+  FulfillmentStatus,
+  GetOrdersOptions,
+  GetOrdersCallback,
+} from './order';
+
+// ============================================
+// Provider Types (L1 - Source of Truth)
+// ============================================
+export enum SupportedProviderType {
+  Medusa = 'medusa',
+}
+
+// Re-export provider types directly
+export { type ProviderTypeString } from './provider';
+
+export {
+  isSupportedProviderType,
+  getProviderMetadata,
+  PROVIDER_METADATA,
+} from './provider';
+
+// ============================================
+// Storefront Types
+// ============================================
+export type {
+  StorefrontContext,
+  StorefrontPlatformType,
+} from './storefront';
+
+export {
+  StorefrontConfigError,
+} from './storefront';
+
+// ============================================
+// Storefront Configuration Types
+// ============================================
+export type {
+  StorefrontConfig,
+  StorefrontSeoDefaults,
+} from './storefront-config';
+
+// ============================================
+// Designer Configuration Types
+// ============================================
+export type {
+  DesignerConfig,
+  DesignerThemeConfig,
+  DesignerThemePreset,
+  DesignerNavItem,
+  DesignerHistoryEntry,
+} from './designer-config';
+
+// ============================================
+// Auth Types
+// ============================================
+export type {
+  AuthProvider,
+  AuthConfig,
+  AuthMethod,
+  AuthStorage,
+  LoginCredentials,
+  RegisterData,
+  AuthResponse,
+  UpdateCustomerData,
+  CreateAddressData,
+  PasswordResetRequest,
+  PasswordResetConfirm,
+} from './auth';
+
+// ============================================
+// Payment Types
+// ============================================
+export type {
+  PaymentMethod,
+  PaymentMethodType,
+  PaymentMethodFeatures,
+  PaymentMethodsOptions,
+  CachedPaymentMethods,
+} from './payment';
+
+// ============================================
+// Commerce Provider Interface
+// ============================================
+export type {
+  CommerceProvider,
+  BackendCapabilities,
+  ProviderConfig,
+} from './commerce-provider';
+
+// ============================================
+// Admin Types
+// ============================================
+export type {
+  AdminUser,
+  AuditLog,
+  DashboardConfig,
+  DashboardMetrics,
+  SalesMetrics,
+  OrdersMetrics,
+  ProductsMetrics,
+  ChartDataPoint,
+  DashboardMetricsAdapter,
+  DashboardOrdersAdapter,
+  DashboardProductsAdapter,
+  AuditLogAdapter,
+  SiteConfigMetadata,
+  ConfigHistoryEntry,
+} from './admin';
+
+// ============================================
+// Header Configuration Types
+// ============================================
+export type {
+  IconConfig,
+  NavigationCalloutItem,
+  NavigationLinkItem,
+  DynamicSource,
+  HeaderLinkItem,
+  AccountMenuItem,
+  AccountDropdownConfig,
+  SearchBarConfig,
+  HeaderNavigationConfig,
+} from './header-config';

package/src/order.ts

@@ -0,0 +1,188 @@
+/**
+ * @thorprovider/types v3.0
+ * Order types - unified interface for all commerce providers
+ * Universal interfaces compatible with: Shopify, Medusa.js, WooCommerce, Magento, BigCommerce
+ */
+
+import type { Money, Image } from './common';
+import type { Address, Customer } from './customer';
+
+/**
+ * Order status (overall)
+ * 
+ * Platform mapping:
+ * - Shopify: Derived from financialStatus + fulfillmentStatus
+ * - Medusa: status field
+ * - WooCommerce: status (pending/processing/completed/cancelled/refunded)
+ * - Magento: status
+ */
+export type OrderStatus = 
+  | 'pending'
+  | 'processing'
+  | 'completed'
+  | 'cancelled'
+  | 'refunded';
+
+/**
+ * Payment status (separate from order status)
+ * 
+ * Platform mapping:
+ * - Shopify: financialStatus (PENDING, AUTHORIZED, PAID, REFUNDED, etc.)
+ * - Medusa: payment_status
+ * - WooCommerce: Derived from order status
+ * - Magento: payment status
+ */
+export type PaymentStatus =
+  | 'pending'
+  | 'authorized'
+  | 'paid'
+  | 'partially_refunded'
+  | 'refunded';
+
+/**
+ * Fulfillment status
+ * 
+ * Platform mapping:
+ * - Shopify: fulfillmentStatus (FULFILLED, UNFULFILLED, etc.)
+ * - Medusa: fulfillment_status
+ * - WooCommerce: Derived from order status
+ * - Magento: shipping_status
+ */
+export type FulfillmentStatus =
+  | 'unfulfilled'
+  | 'partially_fulfilled'
+  | 'fulfilled'
+  | 'returned';
+
+/**
+ * Order line item
+ * 
+ * Universal format for order items across platforms.
+ */
+export interface OrderItem {
+  id: string;
+  title: string;  // Product title
+  variantTitle?: string;  // Variant title (e.g., "Large / Red")
+  quantity: number;
+  price: Money;  // Unit price
+  total: Money;  // Line total (quantity * price)
+  sku?: string;
+  image?: Image;
+  
+  // Product references
+  productId?: string;
+  variantId?: string;
+}
+
+/**
+ * Order
+ * 
+ * Universal format compatible with:
+ * - Shopify: Order (Storefront API)
+ * - Medusa: StoreOrder (v2)
+ * - WooCommerce: Order (REST API)
+ * - Magento: Order (GraphQL)
+ */
+export interface Order {
+  id: string;
+  orderNumber: string;  // Human-readable order number (e.g., "#1000", "727")
+  email: string;
+  
+  // Status (3 separate statuses for granular control)
+  status: OrderStatus;
+  paymentStatus: PaymentStatus;
+  fulfillmentStatus: FulfillmentStatus;
+  
+  // Customer
+  customerId?: string;
+  customer?: Customer;
+  
+  // Items
+  items: OrderItem[];
+  
+  // Pricing
+  subtotal: Money;
+  total: Money;
+  tax?: Money;
+  shipping?: Money;
+  discount?: Money;  // Total discount applied
+  
+  // Addresses
+  shippingAddress?: Address;
+  billingAddress?: Address;
+  
+  // Dates
+  createdAt: string;  // ISO 8601 timestamp
+  updatedAt: string;
+  completedAt?: string;  // When order was completed/fulfilled
+  cancelledAt?: string;  // When order was cancelled
+  
+  // Draft status
+  isDraft?: boolean;  // True if this is a draft order (not yet completed or placed)
+  
+  // Platform-specific extensions
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Custom fetcher callback for advanced order 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 orders by channel server-side
+ * const customFetcher = async (options: GetOrdersOptions) => {
+ *   const response = await fetch(
+ *     `/api/admin/sales-channels/${options.salesChannelId}/orders`
+ *   );
+ *   return response.json();
+ * };
+ *
+ * const orders = await provider.getOrders({
+ *   salesChannelId: 'sc_123',
+ *   customFetcher,
+ * });
+ * ```
+ */
+export type GetOrdersCallback = (options: GetOrdersOptions) => Promise<Order[]>;
+
+/**
+ * Options for querying a list of orders.
+ *
+ * Used by CommerceProvider.getOrders() and admin list endpoints.
+ */
+export interface GetOrdersOptions {
+  /** Customer ID to filter orders by */
+  customerId?: string;
+  /** Maximum number of results */
+  limit?: number;
+  /** Zero-based offset for pagination */
+  offset?: number;
+  /**
+   * Filter orders to a specific sales channel.
+   *
+   * When set, only orders whose `metadata.sales_channel_id` matches
+   * this value are returned.  Enables multi-tenant isolation.
+   *
+   * If omitted, orders are returned unfiltered (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}/orders`).
+   *
+   * This option enables:
+   * - **Medusa Module Link**: Query orders via custom module API
+   * - **Custom endpoints**: Call `/api/admin/sales-channels/{id}/orders` 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 GetOrdersCallback} for callback signature
+   */
+  customFetcher?: GetOrdersCallback;
+}