@thorprovider/types 2.0.2

package/src/payment.ts

@@ -0,0 +1,259 @@
+/**
+ * @thorprovider/adapters v2.0
+ * Payment Types - Unified payment method interface
+ * 
+ * Provides backend-agnostic types for payment methods and providers.
+ * Each backend transforms its payment providers to this common format.
+ * 
+ * @see packages/adapters/PAYMENT_METHODS_ARCHITECTURE.md
+ */
+
+/**
+ * Payment method type identifier
+ * Normalized across all backends
+ * 
+ * @example
+ * ```typescript
+ * // Medusa transforms:
+ * 'pp_stripe_stripe' → type: 'card'
+ * 'pp_paypal_paypal' → type: 'wallet'
+ * 'pp_system_default' → type: 'cash_on_delivery'
+ * ```
+ */
+export type PaymentMethodType =
+  | 'card'              // Credit/debit cards (Visa, Mastercard, Amex, etc.)
+  | 'wallet'            // Digital wallets (Apple Pay, Google Pay, PayPal)
+  | 'bank_transfer'     // Bank transfers (ACH, SEPA, wire transfer)
+  | 'buy_now_pay_later' // BNPL services (Klarna, Affirm, Afterpay)
+  | 'cash_on_delivery'  // Cash on delivery / Manual payment
+  | 'crypto'            // Cryptocurrency payments
+  | 'other';            // Custom or unclassified methods
+
+/**
+ * Payment method features and capabilities
+ * Describes what a payment method supports
+ */
+export interface PaymentMethodFeatures {
+  /**
+   * Supports saving payment method for future use
+   * 
+   * Example: Stripe allows saving cards, PayPal allows vaulting
+   */
+  saveForLater?: boolean;
+  
+  /**
+   * Requires 3D Secure authentication
+   * 
+   * Important for SCA compliance in EU
+   */
+  requires3DS?: boolean;
+  
+  /**
+   * Supports refunds
+   * 
+   * Some methods like COD may not support automatic refunds
+   */
+  supportsRefunds?: boolean;
+  
+  /**
+   * Minimum transaction amount (in smallest currency unit, e.g., cents)
+   * 
+   * Example: Stripe has minimum amounts per currency
+   */
+  minAmount?: number;
+  
+  /**
+   * Maximum transaction amount (in smallest currency unit, e.g., cents)
+   * 
+   * Example: Some BNPL providers have maximum limits
+   */
+  maxAmount?: number;
+  
+  /**
+   * Supported currencies (ISO 4217 codes)
+   * 
+   * If undefined, assumes all currencies supported
+   */
+  supportedCurrencies?: string[];
+  
+  /**
+   * Requires additional customer verification
+   * 
+   * Example: Bank transfers may require identity verification
+   */
+  requiresVerification?: boolean;
+}
+
+/**
+ * Payment method information
+ * Backend-agnostic representation of a payment provider
+ * 
+ * This is the normalized format that all backends transform their
+ * payment providers into, allowing the storefront to work with
+ * any backend without knowing provider-specific details.
+ * 
+ * @example
+ * ```typescript
+ * // Medusa Stripe provider:
+ * {
+ *   id: 'pp_stripe_stripe',
+ *   name: 'Stripe',
+ *   type: 'card',
+ *   isEnabled: true,
+ *   requiresSetup: true,
+ *   features: {
+ *     saveForLater: true,
+ *     requires3DS: true,
+ *     supportsRefunds: true
+ *   }
+ * }
+ * ```
+ */
+export interface PaymentMethod {
+  /**
+   * Unique identifier from backend
+   * 
+   * Format varies by backend:
+   * - Medusa: "pp_stripe_stripe", "pp_paypal_paypal", "pp_system_default"
+   * - Shopify: "shopify_payments", "paypal_express"
+   * - WooCommerce: "stripe", "paypal", "cod"
+   */
+  id: string;
+  
+  /**
+   * Display name for UI
+   * 
+   * Human-readable name shown to customers
+   * Example: "Credit Card", "PayPal", "Cash on Delivery"
+   */
+  name: string;
+  
+  /**
+   * Payment method type (normalized)
+   * 
+   * Used for categorization and UI rendering
+   */
+  type: PaymentMethodType;
+  
+  /**
+   * Whether this provider is currently enabled
+   * 
+   * Backend administrators control this setting
+   */
+  isEnabled: boolean;
+  
+  /**
+   * Whether this provider requires additional setup
+   * 
+   * Examples:
+   * - Card payments: requires entering card details
+   * - Wallets: requires authorizing wallet connection
+   * - COD: no setup required (false)
+   */
+  requiresSetup: boolean;
+  
+  /**
+   * Optional description for display
+   * 
+   * Additional information shown to customer
+   */
+  description?: string;
+  
+  /**
+   * Metadata from backend (provider-specific)
+   * 
+   * Contains original backend data for advanced use cases
+   * Structure varies by backend
+   */
+  metadata?: Record<string, unknown>;
+  
+  /**
+   * Supported features and capabilities
+   */
+  features?: PaymentMethodFeatures;
+  
+  /**
+   * Logo URL or icon identifier
+   * 
+   * Optional visual representation
+   */
+  logo?: string;
+}
+
+/**
+ * Payment methods query options
+ * 
+ * Used to filter/query available payment methods
+ * Different backends support different filters
+ */
+export interface PaymentMethodsOptions {
+  /**
+   * Region ID (for backends that support regional payments)
+   * 
+   * Example: Medusa requires region_id
+   * Required for: Medusa
+   * Optional for: Shopify (global), WooCommerce (may use)
+   */
+  regionId?: string;
+  
+  /**
+   * Cart ID (for cart-specific payment methods)
+   * 
+   * Some backends determine available methods based on cart contents
+   * Example: Certain methods only for high-value carts
+   */
+  cartId?: string;
+  
+  /**
+   * Currency code filter (ISO 4217)
+   * 
+   * Filter methods that support this currency
+   * Example: 'USD', 'EUR', 'GBP'
+   */
+  currencyCode?: string;
+  
+  /**
+   * Filter by enabled status
+   * 
+   * If true, only return enabled payment methods
+   * Default: true (recommended for checkout)
+   */
+  enabledOnly?: boolean;
+  
+  /**
+   * Force refresh from backend (ignore cache)
+   * 
+   * Set to true to bypass client-side cache
+   * Default: false
+   */
+  forceRefresh?: boolean;
+}
+
+/**
+ * Cached payment methods data
+ * 
+ * Used for client-side caching with TTL
+ */
+export interface CachedPaymentMethods {
+  /**
+   * Cache key (stringified options)
+   */
+  key: string;
+  
+  /**
+   * Cached payment methods
+   */
+  methods: PaymentMethod[];
+  
+  /**
+   * Timestamp when cached (milliseconds since epoch)
+   */
+  cachedAt: number;
+  
+  /**
+   * Time-to-live in milliseconds
+   * 
+   * Default: 5 minutes (300000ms)
+   */
+  ttl: number;
+}

package/src/product.ts

@@ -0,0 +1,364 @@
+/**
+ * @thorprovider/adapters v2.0
+ * Product types - unified interface for all commerce providers
+ */
+
+import type { Image, Money, SEO } from './common';
+import type { InventoryLevel, StockStatus } from './stock-location';
+
+/**
+ * Product variant option (e.g., Size: Large, Color: Red)
+ */
+export interface ProductOption {
+  id: string;
+  name: string;
+  values: string[];
+}
+
+/**
+ * Selected option for a variant
+ */
+export interface SelectedOption {
+  name: string;
+  value: string;
+}
+
+/**
+ * Product variant (SKU)
+ * 
+ * Universal format compatible with:
+ * - Shopify: ProductVariant with price/compareAtPrice as MoneyV2
+ * - Medusa: StoreProductVariant with calculated_price
+ * - WooCommerce: Variation with price/regular_price
+ * - Magento: ConfigurableProductOptions
+ */
+export interface ProductVariant {
+  id: string;
+  title: string;
+  sku?: string;
+  availableForSale: boolean;
+  selectedOptions: SelectedOption[];
+  
+  // Pricing
+  price: Money;
+  compareAtPrice?: Money;  // Original price before discount (Shopify: compareAtPrice, WooCommerce: regular_price)
+  
+  // Inventory
+  quantityAvailable?: number;  // Available stock quantity
+  stockStatus?: StockStatus;
+  inventoryLevels?: InventoryLevel[];
+  
+  // Media
+  image?: Image;  // Variant-specific image
+}
+
+/**
+ * Price range for product
+ */
+export interface PriceRange {
+  minVariantPrice: Money;
+  maxVariantPrice: Money;
+}
+
+/**
+ * Main product type - normalized across all providers
+ * 
+ * Universal format compatible with:
+ * - Shopify: Product (Storefront API 2024-01)
+ * - Medusa.js: StoreProduct (v2)
+ * - WooCommerce: Product (REST API v3)
+ * - Magento/Adobe Commerce: ProductInterface (GraphQL)
+ * 
+ * Platform-specific fields are stored in metadata.
+ */
+export interface Product {
+  id: string;
+  handle: string;  // Shopify/Medusa: handle, WooCommerce: slug, Magento: url_key
+  title: string;  // Shopify/Medusa: title, WooCommerce/Magento: name
+  description: string;
+  descriptionHtml?: string;
+  availableForSale: boolean;  // Computed from platform-specific status/stock fields
+  
+  // Options and variants
+  options: ProductOption[];
+  variants: ProductVariant[];
+  
+  // Media
+  featuredImage?: Image;  // Shopify: featuredImage, Medusa: thumbnail, WooCommerce: images[0]
+  images: Image[];
+  
+  // Pricing
+  priceRange: PriceRange;
+  
+  // Organization (optional, platform-dependent)
+  collections?: Array<{ id: string; title: string; handle: string }>;  // Shopify/Medusa: collections, WooCommerce/Magento: categories
+  productType?: string;  // Shopify: productType, Medusa: type, WooCommerce: type (simple/variable)
+  vendor?: string;  // Shopify-specific, stored in metadata for others
+  tags?: string[];
+  
+  // SEO
+  seo?: SEO;
+  
+  // Dates
+  createdAt: string;  // ISO 8601 timestamp
+  updatedAt: string;
+  
+  // Platform-specific extensions
+  metadata?: Record<string, unknown>;  // Store platform-specific fields here
+}
+
+/**
+ * Options for fetching products
+ */
+export interface GetProductsOptions {
+  query?: string;
+  sortKey?: string;
+  reverse?: boolean;
+  first?: number;
+  skip?: number;
+  /** Cursor (string) or offset (number) for pagination */
+  after?: string | number;
+  regionId?: string;
+  /** Basic category filtering — backend IDs resolved from URL slugs */
+  categoryIds?: string[];
+  /** Basic collection filtering — backend IDs resolved from URL slugs */
+  collectionIds?: string[];
+}
+
+// ─────────────────────────────────────────────────────────────────────
+// UI/UX Types for Product Filtering and Display
+// ─────────────────────────────────────────────────────────────────────
+
+/**
+ * Represents a single active filter displayed as a chip
+ * Used in ActiveFiltersChips component
+ */
+export interface ActiveFilter {
+  /** Unique identifier (e.g., "material-wood") */
+  id: string;
+  /** Display category (e.g., "Material") */
+  category: string;
+  /** Display value (e.g., "Wood") */
+  label: string;
+  /** Raw value for tracking */
+  value: string | string[];
+}
+
+/**
+ * Sort options available for product listing
+ */
+export type SortOption =
+  | 'featured'
+  | 'price-asc'
+  | 'price-desc'
+  | 'name'
+  | 'newest'
+  | 'rating';
+
+/**
+ * A single option within a filter section (e.g., "Wood" under "Material")
+ */
+export interface FilterOption {
+  /** URL-friendly slug (human-readable). This is what goes in the URL. */
+  value: string;
+  /** Display label shown in the UI. */
+  label: string;
+  /**
+   * Backend identifier (e.g., database ID).
+   * Present when `value` is a human-readable slug that differs from the
+   * backend ID. Used by L5 page.tsx to resolve slug → ID before querying
+   * the adapter. Optional: when absent, `value` is used as the backend ID.
+   */
+  id?: string;
+  /** Optional facet count */
+  count?: number;
+}
+
+/**
+ * Represents a collapsible filter section in the sidebar
+ */
+export interface FilterSection {
+  id: string;
+  label: string;
+  type: 'checkbox' | 'range' | 'radio' | 'select';
+  options?: FilterOption[];
+  min?: number;
+  max?: number;
+  defaultExpanded?: boolean;
+}
+
+/**
+ * Simplified product preview for e-commerce patterns
+ * Used in ProductCard, QuickView, etc.
+ */
+export interface ProductPreview {
+  id: string;
+  name: string;
+  price: number;
+  originalPrice?: number;
+  image: string;
+  rating: number;
+  reviewCount: number;
+  isNew?: boolean;
+  isOnSale?: boolean;
+  isOutOfStock?: boolean;
+  discountPercent?: number;
+  stock?: number;
+  category?: string;
+  description?: string;
+}
+
+/**
+ * Product review type
+ */
+export interface Review {
+  id: string;
+  author: string;
+  rating: number;
+  date: string;
+  title: string;
+  body: string;
+  verified?: boolean;
+}
+
+/**
+ * Product compare item structure
+ */
+export interface CompareProduct {
+  id: string;
+  name: string;
+  image: string;
+  price: number;
+  attributes: Record<string, string>;
+}
+
+// ─────────────────────────────────────────────────────────────────────
+// Admin Types (Admin API — backend-agnostic)
+// ─────────────────────────────────────────────────────────────────────
+
+/**
+ * Product variant as returned by the admin API.
+ *
+ * Distinct from `ProductVariant` (storefront API) because admin variants
+ * carry backend-specific fields like inventory counts and raw prices.
+ */
+export interface AdminProductVariant {
+  id: string;
+  title: string;
+  sku?: string;
+  /** Total inventory quantity across all stock locations */
+  quantityAvailable?: number;
+  /** Prices available for this variant */
+  prices?: Array<{ amount: number; currencyCode: string }>;
+}
+
+/**
+ * Product as returned by the admin API.
+ *
+ * Intentionally separate from `Product` (storefront API) because:
+ * - The storefront API only returns published products and derives
+ *   `availableForSale` from stock/sales-channel rules — no explicit status.
+ * - The admin API returns ALL products (including draft, proposed, rejected)
+ *   with the backend-native `status` field.
+ *
+ * Use this type exclusively in admin dashboard contexts.
+ */
+export interface AdminProduct {
+  id: string;
+  handle: string;
+  title: string;
+  /** Optional product description */
+  description?: string;
+  /**
+   * Backend-native status string.
+   * Values are provider-specific — e.g. 'published' | 'draft' | 'proposed' | 'rejected'.
+   */
+  status: string;
+  variants: AdminProductVariant[];
+  /** URL of the product thumbnail image */
+  thumbnail?: string;
+  /** URLs of all product images */
+  images?: string[];
+}
+
+// ============================================
+// Advanced Search & Filter Types
+// ============================================
+
+/**
+ * Options for advanced product search (requires backend search engine support).
+ * Extends GetProductsOptions so it can be passed as a fallback to getProducts().
+ * Used with CommerceProvider.searchProductsAdvanced().
+ */
+export interface AdvancedSearchProductsOptions extends GetProductsOptions {
+  /** Filter by category IDs */
+  categoryIds?: string[];
+  /** Filter by collection IDs */
+  collectionIds?: string[];
+  /** Filter by tag IDs */
+  tagIds?: string[];
+  /** Minimum price (in major currency units) */
+  priceMin?: number;
+  /** Maximum price (in major currency units) */
+  priceMax?: number;
+  /** Currency code for price filtering */
+  currencyCode?: string;
+  /** Only include products with stock available */
+  inStockOnly?: boolean;
+  /** Attribute filters (e.g. RAM, brand) */
+  attributes?: Array<{ id: string; values: string[] }>;
+  /** Include variant-level data in results */
+  includeVariants?: boolean;
+}
+
+/**
+ * Metadata returned alongside advanced search results.
+ */
+export interface SearchResultMeta {
+  /** Total number of matching products */
+  total?: number;
+  /** Max results requested */
+  limit?: number;
+  /** Pagination offset */
+  offset?: number;
+  /** Backend search processing time in milliseconds */
+  processingTimeMs?: number;
+  /** Whether hybrid (vector + keyword) search was used */
+  hybridSearchUsed?: boolean;
+  /** Filters that were actually applied by the backend search engine */
+  appliedFilters?: Record<string, unknown>;
+  /** Price context used for price filtering */
+  priceContext?: {
+    currencyCode: string;
+    regionId?: string;
+  };
+}
+
+/**
+ * Filter configuration returned by CommerceProvider.getAvailableFilters().
+ * Represents one filterable dimension (e.g. Color, RAM, Price range).
+ *
+ * Types:
+ * - `checkbox` / `multi`  → multiple selectable options
+ * - `select` / `single`   → single selectable option
+ * - `range`               → numeric min/max range
+ * - `boolean`             → on/off toggle (e.g. "In Stock")
+ */
+export interface FilterConfig {
+  /** Unique filter identifier */
+  id: string;
+  /** Display label for the filter group */
+  label: string;
+  /** Filter UI type */
+  type: 'checkbox' | 'multi' | 'select' | 'single' | 'range' | 'boolean';
+  /** Selectable options (for checkbox/multi/select/single types) */
+  options?: FilterOption[];
+  /** Min value (for range type) */
+  min?: number;
+  /** Max value (for range type) */
+  max?: number;
+  /** Whether this filter is currently applied */
+  isActive?: boolean;
+  /** Sort priority — lower number = displayed first */
+  ranking?: number;
+}