@thorprovider/types 2.0.2

package/src/admin/SiteConfigMetadata.ts

@@ -0,0 +1,46 @@
+/**
+ * Site Config Metadata Types
+ * 
+ * Defines the structure for versioned site configuration storage.
+ * Uses Stripe-style date-based versioning for configuration history.
+ * Stored in backend metadata (no separate database).
+ * 
+ * @module admin/SiteConfigMetadata
+ */
+
+import type { SiteConfig } from '../site-config';
+
+/**
+ * Configuration History Entry
+ */
+export interface ConfigHistoryEntry {
+  /** Version identifier (date-based: YYYY-MM-DD) */
+  version: string;
+  
+  /** The site configuration at this version */
+  config: SiteConfig;
+  
+  /** ISO 8601 timestamp when this version was created */
+  createdAt: string;
+  
+  /** Admin ID who created this version (for future RBAC) */
+  createdBy?: string;
+}
+
+/**
+ * Site Configuration Metadata
+ * 
+ * @remarks
+ * Stored in backend metadata field (e.g., sales_channel.metadata['site_config'])
+ * Uses date-based versioning inspired by Stripe API versioning
+ */
+export interface SiteConfigMetadata {
+  /** Current version (date-based: YYYY-MM-DD) */
+  version: string;
+  
+  /** The current active site configuration */
+  config: SiteConfig;
+  
+  /** Configuration history (last 10 versions) */
+  history?: ConfigHistoryEntry[];
+}

package/src/admin/index.ts

@@ -0,0 +1,13 @@
+/**
+ * Admin Types
+ * 
+ * Central export point for all admin-related types.
+ * 
+ * @module admin
+ */
+
+export * from './AdminUser';
+export * from './AuditLog';
+export * from './DashboardConfig';
+export * from './DashboardMetrics';
+export * from './SiteConfigMetadata';

package/src/auth.ts

@@ -0,0 +1,267 @@
+/**
+ * @fileoverview Authentication types for Thor Commerce adapters
+ * @module @thorprovider/adapters/types/auth
+ * 
+ * Framework-agnostic authentication types that work across all commerce providers.
+ * Follows Thor Commerce principles: decoupling, agnostic configuration.
+ */
+
+import type { Customer, Address } from './customer';
+
+/**
+ * Authentication method configuration
+ */
+export type AuthMethod = 'jwt' | 'session';
+
+/**
+ * Authentication storage strategy
+ */
+export type AuthStorage = 'cookie' | 'localStorage' | 'sessionStorage' | 'memory';
+
+/**
+ * Authentication configuration
+ */
+export interface AuthConfig {
+  /**
+   * Authentication method to use
+   * - 'jwt': JWT token in Authorization header (good for mobile, SPAs)
+   * - 'session': Cookie-based session (good for server-side rendering)
+   */
+  method: AuthMethod;
+  
+  /**
+   * Where to store authentication tokens/session
+   * - 'cookie': Browser cookies (automatic with fetch)
+   * - 'localStorage': Browser localStorage (manual management)
+   * - 'sessionStorage': Browser sessionStorage (clears on tab close)
+   * - 'memory': In-memory only (for server-side or testing)
+   */
+  storage: AuthStorage;
+  
+  /**
+   * Custom storage implementation (optional)
+   * Useful for React Native or non-browser environments
+   */
+  customStorage?: {
+    getItem: (key: string) => Promise<string | null> | string | null;
+    setItem: (key: string, value: string) => Promise<void> | void;
+    removeItem: (key: string) => Promise<void> | void;
+  };
+}
+
+/**
+ * Login credentials for email/password authentication
+ */
+export interface LoginCredentials {
+  email: string;
+  password: string;
+}
+
+/**
+ * Registration data for new customer
+ */
+export interface RegisterData {
+  email: string;
+  password: string;
+  first_name: string;
+  last_name: string;
+  phone?: string;
+}
+
+/**
+ * Authentication response from login/register
+ */
+export interface AuthResponse {
+  /**
+   * JWT token (if using JWT authentication)
+   */
+  token?: string;
+  
+  /**
+   * Customer object (if registration was successful)
+   */
+  customer?: Customer;
+  
+  /**
+   * Whether authentication requires additional steps (e.g., OAuth)
+   */
+  requiresAction?: boolean;
+  
+  /**
+   * Redirect URL for OAuth flows
+   */
+  redirectUrl?: string;
+}
+
+/**
+ * Authentication response (used internally by providers)
+ */
+export interface AuthResponse {
+  customer?: Customer;
+  token?: string;
+}
+
+// Re-export Customer type for convenience
+export type { Customer };
+
+/**
+ * Update customer data
+ */
+export interface UpdateCustomerData {
+  first_name?: string;
+  last_name?: string;
+  phone?: string | null;
+  email?: string;
+  password?: string;
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Create address data (camelCase for universal compatibility)
+ */
+export interface CreateAddressData {
+  firstName: string;
+  lastName: string;
+  company?: string;
+  address1: string;
+  address2?: string;
+  city: string;
+  province?: string;
+  postalCode: string;
+  countryCode: string;
+  phone?: string;
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Password reset request
+ */
+export interface PasswordResetRequest {
+  email: string;
+}
+
+/**
+ * Password reset confirmation
+ */
+export interface PasswordResetConfirm {
+  token: string;
+  password: string;
+}
+
+/**
+ * Authentication provider interface
+ * 
+ * All commerce providers must implement this interface to support authentication.
+ * This enables framework-agnostic auth across Medusa, Shopify, WooCommerce, etc.
+ */
+export interface AuthProvider {
+  // ========================================
+  // Authentication Methods
+  // ========================================
+  
+  /**
+   * Login customer with email and password
+   * @param credentials - Email and password
+   * @returns Authentication response with token/customer
+   */
+  login(credentials: LoginCredentials): Promise<AuthResponse>;
+  
+  /**
+   * Register new customer
+   * @param data - Registration data
+   * @returns Authentication response
+   */
+  register(data: RegisterData): Promise<AuthResponse>;
+  
+  /**
+   * Logout current customer
+   * Clears authentication token/session
+   */
+  logout(): Promise<void>;
+  
+  // ========================================
+  // Password Management
+  // ========================================
+  
+  /**
+   * Request password reset email
+   * @param email - Customer email
+   */
+  requestPasswordReset(email: string): Promise<void>;
+  
+  /**
+   * Reset password with token
+   * @param token - Password reset token from email (provider-specific format)
+   * @param password - New password
+   * @param metadata - Optional metadata for provider-specific requirements
+   */
+  resetPassword(token: string, password: string, metadata?: Record<string, unknown>): Promise<void>;
+  
+  // ========================================
+  // Session Management
+  // ========================================
+  
+  /**
+   * Get current authenticated customer
+   * @returns Customer object or null if not authenticated
+   */
+  getCurrentCustomer(): Promise<Customer | null>;
+  
+  /**
+   * Update current customer profile
+   * @param data - Fields to update
+   * @returns Updated customer
+   */
+  updateCustomer(data: UpdateCustomerData): Promise<Customer>;
+  
+  /**
+   * Check if customer is authenticated
+   * @returns true if authenticated, false otherwise
+   */
+  isAuthenticated(): Promise<boolean>;
+  
+  /**
+   * Get current authentication token (if using JWT)
+   * @returns JWT token or null
+   */
+  getAuthToken(): string | null;
+
+  /**
+   * Delete current customer account
+   * 
+   * WARNING: This is a permanent action and cannot be undone.
+   * Only implemented if capabilities.deleteAccount is true.
+   */
+  deleteCustomerAccount(): Promise<void>;
+  
+  // ========================================
+  // Address Management
+  // ========================================
+  
+  /**
+   * 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>;
+}

package/src/cart.ts

@@ -0,0 +1,130 @@
+/**
+ * @thorprovider/adapters v2.0
+ * Cart types - unified interface for all commerce providers
+ */
+
+import type { Image, Money } from './common';
+import type { SelectedOption } from './product';
+import type { FulfillmentOption, StockStatus, StockValidation } from './stock-location';
+
+/**
+ * Product reference in cart
+ */
+export interface CartProduct {
+  id: string;
+  handle: string;
+  title: string;
+  featuredImage: Image;
+}
+
+/**
+ * Cart line item
+ */
+export interface CartItem {
+  id: string | undefined;
+  quantity: number;
+  stockStatus?: StockStatus;
+  cost: {
+    totalAmount: Money;
+  };
+  merchandise: {
+    id: string;
+    title: string;
+    selectedOptions: SelectedOption[];
+    product: CartProduct;
+  };
+}
+
+/**
+ * Cart cost breakdown
+ */
+export interface CartCost {
+  subtotalAmount: Money;
+  totalAmount: Money;
+  totalTaxAmount?: Money;
+}
+
+/**
+ * Shipping method option
+ * Used during checkout to display available shipping methods
+ */
+export interface ShippingMethod {
+  /** Unique identifier for the shipping method */
+  id: string;
+  
+  /** Display name (e.g., 'Standard Shipping', 'Express') */
+  name: string;
+  
+  /** Price for this shipping method */
+  price: Money;
+  
+  /** Optional description */
+  description?: string;
+  
+  /** Estimated delivery time (e.g., '3-5 business days') */
+  estimatedDays?: string;
+}
+
+/**
+ * Main cart type - normalized across all providers
+ */
+export interface Cart {
+  id: string | undefined;
+  checkoutUrl: string;
+  cost: CartCost;
+  lines: CartItem[];
+  totalQuantity: number;
+  fulfillmentOptions?: FulfillmentOption[];
+  stockValidation?: StockValidation;
+  /** ISO timestamp when cart was completed/converted to order (undefined if active) */
+  completedAt?: string;
+}
+
+/**
+ * Input for adding items to cart
+ */
+export interface CartLineInput {
+  merchandiseId: string;
+  quantity: number;
+}
+
+/**
+ * Input for updating cart items
+ */
+export interface CartLineUpdate {
+  id: string;
+  merchandiseId: string;
+  quantity: number;
+}
+
+/**
+ * Discount code applied to the cart
+ * 
+ * Universal format for discount/promo codes across all providers.
+ * Adapters transform platform-specific discount formats to this interface.
+ */
+export interface DiscountCode {
+  /** Discount code string (e.g., "SUMMER2024") */
+  code: string;
+  
+  /** Discount value (amount or percentage) */
+  value: number;
+  
+  /** Whether the value is a percentage (true) or fixed amount (false) */
+  isPercentage: boolean;
+  
+  /** Human-readable description of the discount */
+  description?: string;
+  
+  /** Minimum purchase amount required */
+  minimumAmount?: Money;
+  
+  /** Expiration date */
+  expiresAt?: Date;
+  
+  /** Maximum number of uses allowed */
+  maxUses?: number;
+  
+  /** Current number of times this code has been used */
+  usageCount?: number;
+}

package/src/category.ts

@@ -0,0 +1,88 @@
+/**
+ * @thorprovider/types v2.0
+ * Product Category types - unified interface for all commerce providers
+ */
+
+/**
+ * Product category (hierarchical taxonomy)
+ */
+export interface ProductCategory {
+  /** Unique identifier */
+  id: string;
+  /** Category name */
+  name: string;
+  /** URL-safe handle/slug */
+  handle: string;
+  /** Category description */
+  description?: string;
+  /** Parent category ID (null for root categories) */
+  parentCategoryId?: string;
+  /** Number of products in category */
+  productCount?: number;
+  /** Category image URL */
+  image?: string;
+  /** Metadata */
+  metadata?: Record<string, any>;
+}
+
+/**
+ * Custom fetcher callback for advanced category 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 categories by channel server-side
+ * const customFetcher = async (options: GetCategoriesOptions) => {
+ *   const response = await fetch(`/api/admin/sales-channels/${options.salesChannelId}/categories`);
+ *   return response.json();
+ * };
+ *
+ * const categories = await provider.getCategories({
+ *   salesChannelId: 'sc_123',
+ *   customFetcher,
+ * });
+ * ```
+ */
+export type GetCategoriesCallback = (options: GetCategoriesOptions) => Promise<ProductCategory[]>;
+
+/**
+ * Options for fetching categories
+ */
+export interface GetCategoriesOptions {
+  /** Include child categories */
+  includeDescendants?: boolean;
+  /** Parent category ID to filter by */
+  parentCategoryId?: string;
+  /** Maximum number of categories to return */
+  limit?: number;
+  /** Search query to filter categories by name/handle */
+  query?: string;
+  /**
+   * Scope results to a specific sales channel / storefront channel.
+   * When provided, only categories that contain at least one product available
+   * in the given channel will be returned.
+   *
+   * Maps to: Medusa `sales_channel_id`, Shopify Sales Channel, etc.
+   * Adapters that support native server-side filtering should prefer it;
+   * others may fall back to a client-side post-filter pass.
+   */
+  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}/categories`).
+   *
+   * This option enables:
+   * - **Medusa Module Link**: Query categories via custom module API
+   * - **Custom endpoints**: Call `/api/admin/sales-channels/{id}/categories` 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 GetCategoriesCallback} for callback signature
+   */
+  customFetcher?: GetCategoriesCallback;
+}

package/src/collection.ts

@@ -0,0 +1,39 @@
+/**
+ * @thorprovider/adapters v2.0
+ * Collection types - unified interface for all commerce providers
+ */
+
+import type { SEO } from './common';
+
+/**
+ * Product collection/category
+ */
+export interface Collection {
+  id: string;
+  handle: string;
+  title: string;
+  description: string;
+  seo?: SEO;
+  path: string;
+  updatedAt: string;
+}
+
+/**
+ * Options for fetching collections
+ */
+export interface GetCollectionsOptions {
+  /** Maximum number of collections to return */
+  limit?: number;
+  /** Search query to filter collections by title */
+  query?: string;
+}
+
+/**
+ * Options for fetching collection products
+ */
+export interface CollectionProductsOptions {
+  sortKey?: string;
+  reverse?: boolean;
+  first?: number;
+  after?: string;
+}