@thorprovider/types 5.7.9 → 5.7.10

package/dist/index.d.mts

@@ -83,80 +83,6 @@ interface Country {
     numCode?: string;
 }
 
-/**
- * @thorprovider/types — Commerce contracts (type-only)
- *
- * Single-tenant, guest-only commerce shapes owned once by this module.
- * Validation lives in `@thorprovider/runtime/contracts` (pure Zod); this
- * module exports types only and emits no runtime values.
- *
- * Canonical product/variant/Money/cart/order shapes are NOT redefined here —
- * they stay owned by `./common`, `./product`, `./cart` and `./order`.
- *
- * @module commerce
- */
-
-/**
- * The validated single-store context — the multitenancy seam.
- *
- * Declares store identity, sales channel, region, and currency once and is
- * validated at the boundary before any commerce call. Multitenancy is
- * post-MVP; a future tenancy layer varies these values without redefining
- * the commerce shapes.
- */
-interface StoreContext {
-    /** Stable store identity. */
-    storeId: string;
-    /** Sales channel the store is scoped to (Medusa `sales_channel_id`). */
-    salesChannelId: string;
-    /** Backend region that supplies currency, countries and shipping. */
-    regionId: string;
-    /** ISO 4217 currency code from the validated context — never hardcoded. */
-    currencyCode: string;
-}
-/**
- * Issued guest shopper identity, scoped to a store.
- *
- * Backed by a cookie the Next host owns; it maps to a persisted backend guest
- * cart so a reload reattaches to the same cart and two shoppers stay isolated.
- */
-interface ShopperIdentity {
-    /** Opaque shopper identity issued by the host cookie. */
-    shopperId: string;
-    /** Store the identity is scoped to. */
-    storeId: string;
-}
-/**
- * A persisted backend guest cart session bound to a shopper identity.
- */
-interface CartSession {
-    /** Backend cart identifier. */
-    cartId: string;
-    /** Owning shopper identity. */
-    shopperId: string;
-    /** Store the session is scoped to. */
-    storeId: string;
-}
-/**
- * Safe, buyer/store-authorized order receipt projection.
- *
- * A minimal recoverable subset of the canonical `Order` (`./order`), used by
- * the guest receipt protocol. Access is authorized for the buyer or the
- * store; it is never granted by possession of a bare public order id.
- */
-interface OrderReceipt {
-    /** Backend order identifier. */
-    orderId: string;
-    /** Human-readable order number. */
-    orderNumber: string;
-    /** Buyer email the order was placed with. */
-    email: string;
-    /** Order total in major units. */
-    total: Money;
-    /** ISO 8601 creation timestamp. */
-    createdAt: string;
-}
-
 /**
  * Header Configuration Types
  *
@@ -977,201 +903,6 @@ interface FilterConfig {
     ranking?: number;
 }
 
-/**
- * @thorprovider/types — Canonical catalog query, truthful results, and facet support.
- *
- * Type-only module: no runtime code, constants, or schemas. These types are shared by
- * the URL boundary, the runtime commerce bridge, and the adapters so every product
- * listing asks the backend one well-formed question and reports truthfully what was
- * applied. Validation (Zod) lives in `@thorprovider/runtime/contracts`; translation to
- * backend parameters lives in the adapters.
- *
- * E2 `storefront-catalog-search-filters`. The canonical URL parameter contract is:
- * `q` (text), the route category scope plus `categories`/`collections`, `sort`
- * (`featured` | `name` | `newest`), `page`/`pageSize`, and the optional requested
- * facets `priceMin`/`priceMax`/`inStock`/`attr.<name>`.
- */
-
-/**
- * Canonical, backend-verified sort keys.
- *
- * Only these three are verified against Medusa v2: `featured` (server default),
- * `name` (translated to `title`), and `newest` (translated to `-created_at`). Global
- * price ordering and rating are not verified and are rejected by the boundary as a
- * typed unsupported-query error. An adapter advertises the subset it can actually
- * apply; the listing never offers a sort the backend cannot perform.
- */
-type CatalogSortKey = 'featured' | 'name' | 'newest';
-/**
- * Canonical catalog query crossing the URL boundary, the runtime bridge, and the
- * adapters.
- *
- * Fields mirror the fixed, lowercase URL namespace. They are optional because
- * documented defaults (`sort` = `featured`, `page` = `1`, `pageSize` = the chosen
- * target default) are resolved by the URL boundary and apply only to absent
- * parameters, never to invalid present values.
- */
-interface CatalogQuery {
-    /** Free-text term (`q`). Trimmed, bounded, and empty treated as absent. */
-    text?: string;
-    /**
-     * Category scope supplied by the route path (`/categorias/[[...slug]]`). The route
-     * scope is always retained, even when both optional features are removed.
-     */
-    categoryScope?: string;
-    /**
-     * Category handles requested by the `category-filters` feature. The effective
-     * scope is `categoryScope ∩ categories`; an empty intersection is a valid
-     * zero-result query, never an invalid-query error.
-     */
-    categories?: string[];
-    /** Collection handles requested by the `category-filters` feature. */
-    collections?: string[];
-    /** Canonical sort key; defaults are resolved at the URL boundary, not here. */
-    sort?: CatalogSortKey;
-    /** 1-based page; bounds are enforced at the URL boundary. */
-    page?: number;
-    /** Page size; bounds are enforced at the URL boundary. */
-    pageSize?: number;
-    /** Minimum price in major units; honored only when the price facet is demonstrated. */
-    priceMin?: number;
-    /** Maximum price in major units; honored only when the price facet is demonstrated. */
-    priceMax?: number;
-    /** In-stock only; honored only when demonstrated, otherwise a typed unsupported error. */
-    inStock?: boolean;
-    /** Requested attribute filters keyed by attribute name (`attr.<name>`). */
-    attributes?: Record<string, string[]>;
-}
-/**
- * Filters the backend actually applied to a successful result.
- *
- * A result is reported as success only when every requested filter appears here.
- */
-interface CatalogAppliedFilters {
-    /** Text term applied within the current scope. */
-    text?: string;
-    /** Category handles applied (the effective intersected scope). */
-    categories?: string[];
-    /** Collection handles applied. */
-    collections?: string[];
-    /** Minimum price applied. */
-    priceMin?: number;
-    /** Maximum price applied. */
-    priceMax?: number;
-    /** In-stock constraint applied. */
-    inStock?: boolean;
-    /** Attribute filters applied, keyed by attribute name. */
-    attributes?: Record<string, string[]>;
-}
-/**
- * Canonical filter identifiers used by the support descriptor.
- *
- * `attr.<name>` covers backend-advertised filterable attributes.
- */
-type CatalogFacetId = 'categories' | 'collections' | 'price' | 'inStock' | `attr.${string}`;
-/**
- * Real-endpoint demonstration source for an offered facet.
- *
- * Records the actual backend endpoint demonstrated with the applied query for the
- * current scope, not a capability flag or returned facet metadata.
- */
-interface CatalogFacetDemonstrationSource {
-    /** Real backend endpoint demonstrated with the applied query (e.g. `/store/products`). */
-    endpoint: string;
-    /** The query and scope the endpoint was demonstrated with. */
-    appliedQuery?: CatalogQuery;
-    /** Store/scope the demonstration applies to. */
-    scope?: string;
-    /** ISO-8601 timestamp of when support was demonstrated. */
-    demonstratedAt?: string;
-}
-/**
- * Truthful facet support descriptor: which filters the backend has demonstrated
- * (offered) versus which are undemonstrated and held, plus the demonstration source
- * for each offered filter.
- *
- * Contains no counts or ranges. Facet option counts and numeric ranges come only from
- * backend data returned for the current query and are never synthesized here.
- */
-interface FacetSupport {
-    /** Filters demonstrated against the real endpoint for the current scope. */
-    offered: CatalogFacetId[];
-    /** Filters not demonstrated; held and diagnosed, never silently offered. */
-    held: CatalogFacetId[];
-    /** Real-endpoint demonstration source per offered filter, keyed by filter id. */
-    demonstrations?: Record<string, CatalogFacetDemonstrationSource>;
-    /** Diagnostic reason per held filter, keyed by filter id. */
-    heldReasons?: Record<string, string>;
-}
-/**
- * Truthful catalog result for a fully applied query.
- *
- * When any requested filter cannot be applied, the query MUST return a typed
- * unsupported-query error (defined in `@thorprovider/runtime/contracts`) instead of
- * this shape; a partial result is never labelled success. `total` is present only
- * when the backend supplies it and is never manufactured.
- */
-interface CatalogResults {
-    /** Matching products for the requested scope, sort, and page. */
-    products: Product[];
-    /** Total matches supplied by the backend; absent when the backend returns none. */
-    total?: number;
-    /** Filters the backend actually applied. */
-    appliedFilters: CatalogAppliedFilters;
-    /** Facet support descriptor for the query and scope. */
-    facetSupport?: FacetSupport;
-}
-/**
- * Adapter-seam typed failure code for a canonical catalog query.
- *
- * `unsupported-query` is the code an adapter returns when a requested filter
- * cannot be applied to the backend. `invalid-query` and `unmounted-capability`
- * are produced by the URL boundary (`@thorprovider/runtime/contracts`); the
- * adapter seam mirrors them so the runtime bridge can surface either shape
- * without a translation layer.
- */
-type CatalogQueryFailureCode = 'invalid-query' | 'unsupported-query' | 'unmounted-capability';
-/**
- * Compact, structured repair metadata: the raw parameter names a host must drop
- * to reach a valid query. Structurally identical to the URL boundary's repair.
- */
-interface CatalogQueryFailureRepair {
-    /** Raw URL parameter names to remove (exactly the offending fields). */
-    remove: string[];
-}
-/**
- * Typed catalog-query failure returned across the adapter seam.
- *
- * Structurally identical to `CatalogQueryError` in
- * `@thorprovider/runtime/contracts`, so the two are mutually assignable and the
- * runtime bridge can pass one through as the other. `fields` names the
- * offending raw parameters; `feature` is present only for
- * `unmounted-capability`.
- */
-interface CatalogQueryFailure {
-    code: CatalogQueryFailureCode;
-    fields: string[];
-    message: string;
-    repair: CatalogQueryFailureRepair;
-    feature?: 'catalog-search' | 'category-filters';
-}
-/**
- * Discriminated outcome of a canonical catalog query against a provider.
- *
- * A provider returns `{ ok: true, results }` **only** when every requested
- * filter was applied. When any requested filter cannot be applied it returns
- * `{ ok: false, error }` with `code: 'unsupported-query'` naming the
- * unappliable fields; a partial result is never returned as success and a
- * requested filter is never silently dropped.
- */
-type CatalogQueryOutcome = {
-    ok: true;
-    results: CatalogResults;
-} | {
-    ok: false;
-    error: CatalogQueryFailure;
-};
-
 /**
  * @thorprovider/adapters v2.0
  * Cart types - unified interface for all commerce providers
@@ -1195,13 +926,6 @@ interface CartItem {
     stockStatus?: StockStatus;
     cost: {
         totalAmount: Money;
-        /**
-         * Backend unit price for a single quantity, when the backend supplies it.
-         *
-         * Carried so the display never derives a unit price locally; absent when
-         * the backend did not return one.
-         */
-        unitPrice?: Money;
     };
     merchandise: {
         id: string;
@@ -1212,20 +936,11 @@ interface CartItem {
 }
 /**
  * Cart cost breakdown
- *
- * Every amount is backend-authoritative: the adapter carries the backend's
- * value through unchanged (including a legitimate `"0"`) and never derives a
- * total locally. An optional amount is absent only when the backend did not
- * supply it.
  */
 interface CartCost {
     subtotalAmount: Money;
     totalAmount: Money;
     totalTaxAmount?: Money;
-    /** Backend discount total, when supplied. */
-    discountAmount?: Money;
-    /** Backend shipping total, when supplied. */
-    shippingAmount?: Money;
 }
 /**
  * Shipping method option
@@ -1260,30 +975,6 @@ interface Cart {
     stockValidation?: StockValidation;
     /** ISO timestamp when cart was completed/converted to order (undefined if active) */
     completedAt?: string;
-    /**
-     * Backend sales channel the cart is scoped to.
-     *
-     * Carried so the runtime can enforce that a cart belongs to the validated
-     * single-store context before it is mutated; absent when a provider does not
-     * expose it.
-     */
-    salesChannelId?: string;
-    /** Backend region the cart is scoped to (context enforcement). */
-    regionId?: string;
-    /** Backend currency code, uppercased (context enforcement). */
-    currencyCode?: string;
-    /** Backend id of the applied shipping method, when one is selected. */
-    selectedShippingMethodId?: string;
-    /**
-     * Backend id of the shipping option the applied method was created from.
-     *
-     * This is the identity the checkout shipping UI selects (the value passed to
-     * `addShippingMethod`), which is distinct from `selectedShippingMethodId`
-     * (the applied shipping-method record id). Absent when no method is applied.
-     */
-    selectedShippingOptionId?: string;
-    /** Platform-specific backend metadata, carried through unchanged. */
-    metadata?: Record<string, unknown>;
 }
 /**
  * Input for adding items to cart
@@ -1350,16 +1041,6 @@ interface GetCollectionsOptions {
     limit?: number;
     /** Search query to filter collections by title */
     query?: string;
-    /**
-     * Scope results to a specific sales channel / storefront channel.
-     * When provided, only collections 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;
 }
 /**
  * Options for fetching collection products
@@ -1763,24 +1444,48 @@ interface GetOrdersOptions {
 }
 
 /**
- * @thorprovider/types — Supported Providers (type-only)
+ * @thorprovider/types — Supported Providers
  *
- * Defines the provider-type union contract shared across the monorepo.
+ * Centralized list of all supported commerce providers.
+ * This is the single source of truth for provider types across the monorepo.
  *
  * @remarks
- * - L1 (Foundation): owns the `ProviderTypeString` union type only.
- * - L2 (@thorprovider/adapters) owns the runtime provider registry
- *   (`SupportedProviderType`, `PROVIDER_METADATA`, `isSupportedProviderType`,
- *   `getProviderMetadata`) in `@thorprovider/adapters`.
- *
- * When adding a new provider:
- * 1. Add the string to `ProviderTypeString` below.
- * 2. Add it to `SupportedProviderType` + `PROVIDER_METADATA` in
- *    packages/adapters/src/factory/provider-types.ts.
- * 3. Create packages/adapters/src/providers/[platform]/ and implement the
- *    `CommerceProvider` interface.
- * 4. Update `StorefrontPlatformType` in storefront.ts.
- */
+ * - 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., Stel Order):
+ * 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
+ */
+/**
+ * All supported commerce platform providers.
+ * `mock` is the backend-optional runtime provider used for layout/design mode.
+ * `medusa` is fully implemented for real backend usage; others are placeholders for future expansion.
+ *
+ * @remarks Implementation status:
+ * - ✅ mock: Fixture-backed provider for backend-optional storefronts
+ * - ✅ medusa: Fully implemented
+ * - 🟡 stelorder: In progress (ERP adapter v1)
+ * - 🟡 shopify: Planned (Phase 2)
+ * - 🟡 bigcommerce: Planned (Phase 2)
+ * - 🟡 woocommerce: Planned (Phase 3)
+ * - 🟡 spree: Planned (Phase 3)
+ * - 🟡 magento: Planned (Phase 3)
+ */
+declare enum SupportedProviderType {
+    Mock = "mock",
+    Medusa = "medusa",
+    StelOrder = "stelorder",
+    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.
@@ -1793,6 +1498,41 @@ interface GetOrdersOptions {
  * ```
  */
 type ProviderTypeString = 'mock' | 'medusa' | 'stelorder' | 'shopify' | 'bigcommerce' | 'woocommerce' | 'spree' | 'magento';
+/**
+ * Metadata about each provider.
+ * Useful for UI, error messages, validation, and documentation.
+ *
+ * @internal
+ */
+declare const PROVIDER_METADATA: Record<ProviderTypeString, {
+    name: string;
+    description: string;
+    requiresStorefront: boolean;
+    requiredEnvVars: string[];
+    maxRetries: number;
+}>;
+/**
+ * Check if a string is a valid provider type.
+ *
+ * @example
+ * ```typescript
+ * if (isSupportedProviderType(process.env.COMMERCE_PROVIDER)) {
+ *   // type is narrowed to ProviderTypeString
+ * }
+ * ```
+ */
+declare function isSupportedProviderType(value: unknown): value is ProviderTypeString;
+/**
+ * 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`);
+ * ```
+ */
+declare function getProviderMetadata(type: ProviderTypeString): (typeof PROVIDER_METADATA)[ProviderTypeString];
 
 /**
  * @thorprovider/types — Storefront Context
@@ -1810,11 +1550,9 @@ type ProviderTypeString = 'mock' | 'medusa' | 'stelorder' | 'shopify' | 'bigcomm
  * Supported commerce platform types for storefront identification.
  *
  * @remarks
- * Keep this type in sync with ProviderTypeString from provider.ts and the
- * runtime registry in @thorprovider/adapters
- * (packages/adapters/src/factory/provider-types.ts).
- * When adding a new provider, update packages/types/src/provider.ts, this
- * type, and the adapters registry.
+ * Keep this type in sync with SupportedProviderType from provider.ts.
+ * When adding a new provider, update both packages/types/src/provider.ts
+ * and this type.
  *
  * Currently supported:
  * - ✅ 'mock': Backend-optional layout/design mode using fixture data
@@ -1888,6 +1626,24 @@ interface StorefrontContext {
      */
     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',
+ * );
+ * ```
+ */
+declare class StorefrontConfigError extends Error {
+    readonly platformType: string;
+    readonly requiredEnvVar?: string;
+    constructor(message: string, platformType: string, requiredEnvVar?: string);
+}
 
 /**
  * @thorprovider/types — Storefront Configuration
@@ -2749,21 +2505,6 @@ interface CommerceProvider {
      * ```
      */
     readonly capabilities: BackendCapabilities;
-    /**
-     * Canonical catalog sort keys this provider can actually apply at the query
-     * level (E2 `storefront-catalog-search-filters`, design Decision 6).
-     *
-     * Advertises only backend-verified orderings — for Medusa, `featured`
-     * (server default), `name` (translated to `title`), and `newest` (translated
-     * to `-created_at`). A global price or rating sort is never advertised. The
-     * runtime query boundary consumes this set as `supportedSortKeys` and turns a
-     * requested sort outside it into a typed unsupported-query error, so the
-     * listing never offers an ordering the backend cannot perform.
-     *
-     * Optional and additive: when absent, no ordering beyond the canonical default
-     * is assumed from the advertisement.
-     */
-    readonly supportedCatalogSortKeys?: readonly CatalogSortKey[];
     /**
      * Whether this provider is backed by fixture/mock data instead of a live backend.
      *
@@ -2793,24 +2534,6 @@ interface CommerceProvider {
      * for layout/design workflows until a real backend is configured.
      */
     getProducts(options?: GetProductsOptions): Promise<Product[]>;
-    /**
-     * Run a canonical, validated catalog query against the real listing endpoint
-     * (OPTIONAL — E2 `storefront-catalog-search-filters`, task 2.2).
-     *
-     * The adapter translates the canonical `CatalogQuery` (text, the route
-     * category scope plus `categories`/`collections`, sort, pagination, and
-     * requested filters) into its backend's parameters and returns a truthful
-     * `CatalogQueryOutcome`: `{ ok: true, results }` only when **every** requested
-     * filter was applied, or `{ ok: false, error }` with `code:
-     * 'unsupported-query'` naming the fields it cannot apply. It never returns a
-     * partial result labelled success and never silently drops a requested filter.
-     *
-     * Optional and additive: providers that cannot forward a canonical query omit
-     * it and callers fall back to `getProducts`/`getCategoryProducts`. The legacy
-     * zero-argument and options-based methods keep their `Product[]` return and
-     * are unchanged. This is the typed seam the runtime catalog bridge consumes.
-     */
-    getCatalogProducts?(query: CatalogQuery): Promise<CatalogQueryOutcome>;
     /**
      * Get product recommendations for a given product
      * @param productId - Product ID
@@ -5051,6 +4774,8 @@ interface CreateDropshipperOrderBody {
     /** One selected option per shipping group (contract v2). Replaces `shipping_method_id`. */
     shipping_groups?: ShippingGroupInput[];
     payment_method_id: string;
+    /** Código de gift card (obligatorio si el método de pago es gift card). */
+    gift_card_code?: string;
     notes?: string;
 }
 /** Response for `POST /admin/thor/dropshipper/orders` */
@@ -5068,6 +4793,20 @@ interface CreateDropshipperOrderResponse {
 interface SetPaymentCollectorBody {
     payment_collected_by: 'dropshipper' | 'provider';
 }
+/** Body for `POST /admin/thor/dropshipper/gift-cards/validate` */
+interface ValidateGiftCardBody {
+    code: string;
+    /** Moneda de la orden: si se envía, se valida que la gift card coincida. */
+    currency_code?: string;
+}
+/** Response for `POST /admin/thor/dropshipper/gift-cards/validate` */
+interface ValidateGiftCardResponse {
+    valid: boolean;
+    /** Mensaje de usuario cuando `valid` es false. */
+    reason?: string;
+    balance?: number;
+    currency_code?: string;
+}
 /** Response for `POST /admin/thor/dropshipper/orders/:id/set-payment-collector` */
 interface SetPaymentCollectorResponse {
     order_id: string;
@@ -5179,6 +4918,8 @@ interface DropshipperDraftOrder {
     /** @deprecated legacy singular shipping method id; use `shipping_groups` instead. */
     shipping_method_id: string | null;
     payment_method_id: string | null;
+    /** Código de gift card persistido en el borrador (metadata). */
+    gift_card_code?: string | null;
     notes: string | null;
     converted_order_id: string | null;
     converted_at: string | null;
@@ -5235,6 +4976,7 @@ interface CreateDropshipperDraftOrderBody {
     /** @deprecated legacy singular shipping method id; use `shipping_groups` instead. */
     shipping_method_id?: string;
     payment_method_id?: string;
+    gift_card_code?: string;
     notes?: string;
 }
 /** Response for `POST /admin/thor/dropshipper/draft-orders` */
@@ -5257,6 +4999,7 @@ interface UpdateDropshipperDraftOrderBody {
     /** @deprecated legacy singular shipping method id; use `shipping_groups` instead. */
     shipping_method_id?: string;
     payment_method_id?: string;
+    gift_card_code?: string;
     notes?: string;
 }
 /** Response for `POST /admin/thor/dropshipper/draft-orders/:id` */
@@ -5278,6 +5021,32 @@ interface DeleteDropshipperDraftOrderResponse {
     id: string;
     deleted: boolean;
 }
+/** Item for `POST /admin/thor/dropshipper/orders/preview-totals` */
+interface PreviewDropshipperOrderItem {
+    variant_id: string;
+    quantity: number;
+    /** Sale price per unit the dropshipper intends to charge (honored over the catalog price). */
+    unit_price?: number;
+}
+/** Body for `POST /admin/thor/dropshipper/orders/preview-totals` */
+interface PreviewDropshipperOrderTotalsBody {
+    customer_id: string;
+    currency_code: string;
+    items: PreviewDropshipperOrderItem[];
+    shipping_address: DropshipperOrderShippingAddress;
+    /** One selected option per shipping group (contract v2). Required when any item needs shipping. */
+    shipping_groups?: ShippingGroupInput[];
+}
+/** Response for `POST /admin/thor/dropshipper/orders/preview-totals` */
+interface PreviewDropshipperOrderTotalsResponse {
+    subtotal: number;
+    items_subtotal: number;
+    shipping_subtotal: number;
+    shipping_total: number;
+    tax_total: number;
+    discount_total: number;
+    total: number;
+}
 /** A dropshipper custom category node */
 interface DropshipperCategory {
     id: string;
@@ -5837,6 +5606,8 @@ interface DashboardStats {
         total: number;
         profit: number;
         status: string;
+        /** Estado de cobro crudo del backend (captured/authorized/partially_captured/...). */
+        payment_status: string;
         created_at: string;
     }>;
     top_products_by_profit: DashboardTopProduct[];
@@ -6639,4 +6410,4 @@ type UpdateBusinessPolicyResponse = {
     business_policy: string;
 };
 
-export type { AccountDropdownConfig, AccountMenuItem, AcknowledgeCostPriceChangesResponse, ActiveFilter, AddOrderEditItemBody, AddOrderEditItemResponse, Address, AdminApiKey, AdminChannelCategory, AdminChannelCustomer, AdminDropshipperAccount, AdminDropshipperBalance, AdminProduct, AdminProductVariant, AdminSalesChannelRef, AdminSiteConfig, AdminSiteConfigHistoryEntry, AdminSiteConfigHistoryEntryFull, AdminStorefrontConfig, AdminStorefrontSeoDefaults, AdminUser, AdvancedSearchProductsOptions, AssignCategoriesToChannelsBody, AssignCategoriesToChannelsResponse, AssignCollectionsToChannelsBody, AssignCollectionsToChannelsResponse, AuditLog, AuditLogAdapter, AuthConfig, AuthMethod, AuthProvider, AuthResponse, AuthStorage, AuthorConfig, BackendCapabilities, BrandConfig, CachedPaymentMethods, CancelDropshipperOrderResponse, CancelMovementBody, CancelMovementResponse, CancelSettlementBody, Cart, CartCost, CartItem, CartLineInput, CartLineUpdate, CartProduct, CartSession, CatalogAppliedFilters, CatalogFacetDemonstrationSource, CatalogFacetId, CatalogQuery, CatalogQueryFailure, CatalogQueryFailureCode, CatalogQueryFailureRepair, CatalogQueryOutcome, CatalogResults, CatalogSortKey, CategoryMapping, ChartDataPoint, ChatAssistantHealthResponse, ChatIntent, ChatMessage, ChatRequest, ChatResponse, ChatSource, ChatSourceVariant, Collection, CollectionProductsOptions, CommerceProvider, CompareProduct, ConfigHistoryEntry, ConfirmMovementBody, ConfirmMovementResponse, ConfirmOrderEditResponse, ConfirmSettlementBody, Connection, ConvertDropshipperDraftOrderBody, ConvertDropshipperDraftOrderResponse, CostPriceChangeItem, CostPriceChangesCheckResponse, CostPriceChangesResponse, Country, CreateAddressData, CreateAjusteBody, CreateAjusteResponse, CreateCategoryMappingBody, CreateCategoryMappingResponse, CreateCobroBody, CreateCobroResponse, CreateCompensacionBody, CreateCompensacionResponse, CreateDropshipperCategoryBody, CreateDropshipperCustomerBody, CreateDropshipperCustomerResponse, CreateDropshipperDraftOrderBody, CreateDropshipperDraftOrderResponse, CreateDropshipperOrderBody, CreateDropshipperOrderResponse, CreateDropshipperPromotionBody, CreateOrderEditBody, CreateOrderEditResponse, CreateOrderItem, CreateOrderNoteBody, CreateOrderNoteResponse, CreatePagoBody, CreatePagoResponse, CreateReversoBody, CreateReversoResponse, CreateSettlementBody, CreateSettlementResponse, Customer, DashboardChanges, DashboardConfig, DashboardMetrics, DashboardMetricsAdapter, DashboardOrdersAdapter, DashboardPeriodMetrics, DashboardProductsAdapter, DashboardStats, DashboardTopProduct, DeleteCategoryMappingResponse, DeleteDropshipperCategoryResponse, DeleteDropshipperDraftOrderResponse, DeleteDropshipperPromotionResponse, DeleteOrderNoteResponse, DesignerConfig, DesignerHistoryEntry, DesignerNavItem, DesignerThemeConfig, DesignerThemePreset, DiscountCode, DropshipperAccount, DropshipperAccountRef, DropshipperAddressBody, DropshipperAddressResponse, DropshipperAttributeDefinition, DropshipperAttributeDefinitionValue, DropshipperBalance, DropshipperCategory, DropshipperCostTier, DropshipperCustomer, DropshipperCustomerAddress, DropshipperCustomerDetail, DropshipperCustomerFinancial, DropshipperCustomerStats, DropshipperDashboardCapabilities, DropshipperDraftOrder, DropshipperDraftOrderItem, DropshipperNotificationEventType, DropshipperNotificationPreference, DropshipperOrder, DropshipperOrderCustomer, DropshipperOrderDetail, DropshipperOrderItem, DropshipperOrderShippingAddress, DropshipperOrderTimelineEvent, DropshipperOrderTotals, DropshipperPayableOrder, DropshipperPaymentMethodConfig, DropshipperPendingOrders, DropshipperPriceItem, DropshipperPriceTier, DropshipperProduct, DropshipperProductAttachment, DropshipperProductAttribute, DropshipperProductAttributeValue, DropshipperProductImage, DropshipperProductOption, DropshipperProductOptionValue, DropshipperProductPrivateMedia, DropshipperProfile, DropshipperPromotion, DropshipperReceivableOrder, DropshipperSaleTier, DropshipperShippingGroup, DropshipperShippingGroupOption, DropshipperShippingOption, DropshipperVariant, DynamicSource, Edge, ExtendedCreateDropshipperOrderBody, ExtendedCreateDropshipperOrderResponse, FacetSupport, FilterConfig, FilterOption, FilterSection, FulfillmentOption, FulfillmentSet, FulfillmentStatus, GeoCity, GeoCountry, GeoProvince, GetAdminAccountBalanceResponse, GetAdminDropshipperAccountOrdersResponse, GetAdminDropshipperAccountSettlementsOptions, GetAdminDropshipperAccountSettlementsResponse, GetAdminDropshipperAccountsResponse, GetAdminPriceListsResponse, GetAdminSiteConfigHistoryOptions, GetAdminSiteConfigHistoryResponse, GetAdminSiteConfigResponse, GetAdminStorefrontConfigResponse, GetBusinessPolicyResponse, GetCategoriesCallback, GetCategoriesOptions, GetCategoryMappingsOptions, GetCategoryMappingsResponse, GetCategorySalesChannelsResponse, GetChannelApiKeysResponse, GetChannelCategoriesOptions, GetChannelCategoriesResponse, GetChannelCustomersOptions, GetChannelCustomersResponse, GetCollectionSalesChannelsResponse, GetCollectionsOptions, GetCustomersCallback, GetCustomersOptions, GetDashboardStatsOptions, GetDashboardStatsResponse, GetDropshipperAccountBalanceResponse, GetDropshipperAccountOrdersOptions, GetDropshipperAccountOrdersResponse, GetDropshipperAccountResponse, GetDropshipperAddressesResponse, GetDropshipperAttributesResponse, GetDropshipperCategoriesOptions, GetDropshipperCategoriesResponse, GetDropshipperCustomerDetailResponse, GetDropshipperCustomersOptions, GetDropshipperCustomersResponse, GetDropshipperDraftOrderDetailResponse, GetDropshipperDraftOrdersOptions, GetDropshipperDraftOrdersResponse, GetDropshipperOrderDetailResponse, GetDropshipperOrdersOptions, GetDropshipperOrdersResponse, GetDropshipperPayableResponse, GetDropshipperProductsOptions, GetDropshipperProductsResponse, GetDropshipperPromotionsOptions, GetDropshipperPromotionsResponse, GetDropshipperReceivableResponse, GetDropshipperShippingOptionsBody, GetDropshipperShippingOptionsResponse, GetFinancialAnalysisResponse, GetGeoCitiesResponse, GetGeoCountriesResponse, GetGeoProvincesResponse, GetMyProfileResponse, GetNotificationPreferencesResponse, GetNotificationsOptions, GetNotificationsResponse, GetOrderNotesResponse, GetOrdersCallback, GetOrdersOptions, GetProductAttributesResponse, GetProductsOptions, GetProviderCategoriesResponse, GetSettlementDetailResponse, GetSettlementsOptions, GetSettlementsResponse, GetStorefrontDropshipperCategoriesResponse, GetUserChannelResponse, HeaderLinkItem, HeaderNavigationConfig, IconConfig, Image, InterestCategory, InventoryLevel, LinkCustomerToChannelResponse, LoginCredentials, ManualAdminNotificationData, ModulesConfig, Money, NavigationCalloutItem, NavigationItem, NavigationLinkItem, NotificationData, OnboardDropshipperBody, OnboardDropshipperResponse, Order, OrderItem, OrderNote, OrderReceipt, OrderStatus, OrdersMetrics, PaginationOptions, PasswordResetConfirm, PasswordResetRequest, PaymentMethod$1 as PaymentMethod, PaymentMethodFeatures, PaymentMethodType, PaymentMethodsOptions, PaymentStatus, PriceRange, PriceUpdatedNotificationData, Product, ProductAssignedNotificationData, ProductCategory, ProductOption, ProductPreview, ProductVariant, ProductsMetrics, PromotionRule, ProviderCategory, ProviderConfig, ProviderTypeString, QueryEntitiesInput, QueryEntityInput, QueryErrors, QueryMeta, QueryResponse, QuerySortDirection, RawNotification, RecoveryConfirmResult, Region, RegisterData, RegisterPaymentBody, RegisterPaymentResponse, RequestedProfile, ResolveGuaranteeBody, ResolveGuaranteeResponse, RestoreSiteConfigResponse, Review, SEO, SalesChannelType, SalesMetrics, SearchBarConfig, SearchResultMeta, SelectedOption, SetPaymentCollectorBody, SetPaymentCollectorResponse, SetPaymentMethodBody, SetPaymentMethodResponse, SettlementRecord, SettlementStatus, ShippingGroupInput, ShippingMethod, ShopperIdentity, SiteConfig, SiteConfigLabels, SiteConfigMetadata, SocialConfig, SortOption, SortOptions, StockChangeNotificationData, StockLocation, StockStatus, StockValidation, StoreContext, StorefrontConfig, StorefrontContext, StorefrontPlatformType, StorefrontSeoDefaults, SubmitApplicationBody, SubmitApplicationConflictApplication, SubmitApplicationCreated, SubmitApplicationResponse, SubmitApplicationResult, SubmitApplicationSalesChannel, TokenVerifyResult, TokenVerifyState, UnassignCategoriesFromChannelsBody, UnassignCategoriesFromChannelsResponse, UnassignCollectionsFromChannelsBody, UnassignCollectionsFromChannelsResponse, UpdateBusinessPolicyBody, UpdateBusinessPolicyResponse, UpdateCustomerData, UpdateDropshipperCategoryBody, UpdateDropshipperCustomerBody, UpdateDropshipperCustomerResponse, UpdateDropshipperDraftOrderBody, UpdateDropshipperDraftOrderResponse, UpdateDropshipperPricesBody, UpdateDropshipperPricesResponse, UpdateDropshipperProductStatusBody, UpdateDropshipperProductStatusResponse, UpdateDropshipperPromotionBody, UpdateNotificationPreferencesBody, UpdateSettlementStatusResponse, UpdateSiteConfigBody, UpdateSiteConfigResponse, UpdateStorefrontConfigBody, UpdateStorefrontConfigResponse, ValidateCheckoutItemsRequest, ValidateCheckoutItemsResponse, ValidatedCheckoutItem };
+export { type AccountDropdownConfig, type AccountMenuItem, type AcknowledgeCostPriceChangesResponse, type ActiveFilter, type AddOrderEditItemBody, type AddOrderEditItemResponse, type Address, type AdminApiKey, type AdminChannelCategory, type AdminChannelCustomer, type AdminDropshipperAccount, type AdminDropshipperBalance, type AdminProduct, type AdminProductVariant, type AdminSalesChannelRef, type AdminSiteConfig, type AdminSiteConfigHistoryEntry, type AdminSiteConfigHistoryEntryFull, type AdminStorefrontConfig, type AdminStorefrontSeoDefaults, type AdminUser, type AdvancedSearchProductsOptions, type AssignCategoriesToChannelsBody, type AssignCategoriesToChannelsResponse, type AssignCollectionsToChannelsBody, type AssignCollectionsToChannelsResponse, type AuditLog, type AuditLogAdapter, type AuthConfig, type AuthMethod, type AuthProvider, type AuthResponse, type AuthStorage, type AuthorConfig, type BackendCapabilities, type BrandConfig, type CachedPaymentMethods, type CancelDropshipperOrderResponse, type CancelMovementBody, type CancelMovementResponse, type CancelSettlementBody, type Cart, type CartCost, type CartItem, type CartLineInput, type CartLineUpdate, type CartProduct, type CategoryMapping, type ChartDataPoint, type ChatAssistantHealthResponse, type ChatIntent, type ChatMessage, type ChatRequest, type ChatResponse, type ChatSource, type ChatSourceVariant, type Collection, type CollectionProductsOptions, type CommerceProvider, type CompareProduct, type ConfigHistoryEntry, type ConfirmMovementBody, type ConfirmMovementResponse, type ConfirmOrderEditResponse, type ConfirmSettlementBody, type Connection, type ConvertDropshipperDraftOrderBody, type ConvertDropshipperDraftOrderResponse, type CostPriceChangeItem, type CostPriceChangesCheckResponse, type CostPriceChangesResponse, type Country, type CreateAddressData, type CreateAjusteBody, type CreateAjusteResponse, type CreateCategoryMappingBody, type CreateCategoryMappingResponse, type CreateCobroBody, type CreateCobroResponse, type CreateCompensacionBody, type CreateCompensacionResponse, type CreateDropshipperCategoryBody, type CreateDropshipperCustomerBody, type CreateDropshipperCustomerResponse, type CreateDropshipperDraftOrderBody, type CreateDropshipperDraftOrderResponse, type CreateDropshipperOrderBody, type CreateDropshipperOrderResponse, type CreateDropshipperPromotionBody, type CreateOrderEditBody, type CreateOrderEditResponse, type CreateOrderItem, type CreateOrderNoteBody, type CreateOrderNoteResponse, type CreatePagoBody, type CreatePagoResponse, type CreateReversoBody, type CreateReversoResponse, type CreateSettlementBody, type CreateSettlementResponse, type Customer, type DashboardChanges, type DashboardConfig, type DashboardMetrics, type DashboardMetricsAdapter, type DashboardOrdersAdapter, type DashboardPeriodMetrics, type DashboardProductsAdapter, type DashboardStats, type DashboardTopProduct, type DeleteCategoryMappingResponse, type DeleteDropshipperCategoryResponse, type DeleteDropshipperDraftOrderResponse, type DeleteDropshipperPromotionResponse, type DeleteOrderNoteResponse, type DesignerConfig, type DesignerHistoryEntry, type DesignerNavItem, type DesignerThemeConfig, type DesignerThemePreset, type DiscountCode, type DropshipperAccount, type DropshipperAccountRef, type DropshipperAddressBody, type DropshipperAddressResponse, type DropshipperAttributeDefinition, type DropshipperAttributeDefinitionValue, type DropshipperBalance, type DropshipperCategory, type DropshipperCostTier, type DropshipperCustomer, type DropshipperCustomerAddress, type DropshipperCustomerDetail, type DropshipperCustomerFinancial, type DropshipperCustomerStats, type DropshipperDashboardCapabilities, type DropshipperDraftOrder, type DropshipperDraftOrderItem, type DropshipperNotificationEventType, type DropshipperNotificationPreference, type DropshipperOrder, type DropshipperOrderCustomer, type DropshipperOrderDetail, type DropshipperOrderItem, type DropshipperOrderShippingAddress, type DropshipperOrderTimelineEvent, type DropshipperOrderTotals, type DropshipperPayableOrder, type DropshipperPaymentMethodConfig, type DropshipperPendingOrders, type DropshipperPriceItem, type DropshipperPriceTier, type DropshipperProduct, type DropshipperProductAttachment, type DropshipperProductAttribute, type DropshipperProductAttributeValue, type DropshipperProductImage, type DropshipperProductOption, type DropshipperProductOptionValue, type DropshipperProductPrivateMedia, type DropshipperProfile, type DropshipperPromotion, type DropshipperReceivableOrder, type DropshipperSaleTier, type DropshipperShippingGroup, type DropshipperShippingGroupOption, type DropshipperShippingOption, type DropshipperVariant, type DynamicSource, type Edge, type ExtendedCreateDropshipperOrderBody, type ExtendedCreateDropshipperOrderResponse, type FilterConfig, type FilterOption, type FilterSection, type FulfillmentOption, type FulfillmentSet, type FulfillmentStatus, type GeoCity, type GeoCountry, type GeoProvince, type GetAdminAccountBalanceResponse, type GetAdminDropshipperAccountOrdersResponse, type GetAdminDropshipperAccountSettlementsOptions, type GetAdminDropshipperAccountSettlementsResponse, type GetAdminDropshipperAccountsResponse, type GetAdminPriceListsResponse, type GetAdminSiteConfigHistoryOptions, type GetAdminSiteConfigHistoryResponse, type GetAdminSiteConfigResponse, type GetAdminStorefrontConfigResponse, type GetBusinessPolicyResponse, type GetCategoriesCallback, type GetCategoriesOptions, type GetCategoryMappingsOptions, type GetCategoryMappingsResponse, type GetCategorySalesChannelsResponse, type GetChannelApiKeysResponse, type GetChannelCategoriesOptions, type GetChannelCategoriesResponse, type GetChannelCustomersOptions, type GetChannelCustomersResponse, type GetCollectionSalesChannelsResponse, type GetCollectionsOptions, type GetCustomersCallback, type GetCustomersOptions, type GetDashboardStatsOptions, type GetDashboardStatsResponse, type GetDropshipperAccountBalanceResponse, type GetDropshipperAccountOrdersOptions, type GetDropshipperAccountOrdersResponse, type GetDropshipperAccountResponse, type GetDropshipperAddressesResponse, type GetDropshipperAttributesResponse, type GetDropshipperCategoriesOptions, type GetDropshipperCategoriesResponse, type GetDropshipperCustomerDetailResponse, type GetDropshipperCustomersOptions, type GetDropshipperCustomersResponse, type GetDropshipperDraftOrderDetailResponse, type GetDropshipperDraftOrdersOptions, type GetDropshipperDraftOrdersResponse, type GetDropshipperOrderDetailResponse, type GetDropshipperOrdersOptions, type GetDropshipperOrdersResponse, type GetDropshipperPayableResponse, type GetDropshipperProductsOptions, type GetDropshipperProductsResponse, type GetDropshipperPromotionsOptions, type GetDropshipperPromotionsResponse, type GetDropshipperReceivableResponse, type GetDropshipperShippingOptionsBody, type GetDropshipperShippingOptionsResponse, type GetFinancialAnalysisResponse, type GetGeoCitiesResponse, type GetGeoCountriesResponse, type GetGeoProvincesResponse, type GetMyProfileResponse, type GetNotificationPreferencesResponse, type GetNotificationsOptions, type GetNotificationsResponse, type GetOrderNotesResponse, type GetOrdersCallback, type GetOrdersOptions, type GetProductAttributesResponse, type GetProductsOptions, type GetProviderCategoriesResponse, type GetSettlementDetailResponse, type GetSettlementsOptions, type GetSettlementsResponse, type GetStorefrontDropshipperCategoriesResponse, type GetUserChannelResponse, type HeaderLinkItem, type HeaderNavigationConfig, type IconConfig, type Image, type InterestCategory, type InventoryLevel, type LinkCustomerToChannelResponse, type LoginCredentials, type ManualAdminNotificationData, type ModulesConfig, type Money, type NavigationCalloutItem, type NavigationItem, type NavigationLinkItem, type NotificationData, type OnboardDropshipperBody, type OnboardDropshipperResponse, type Order, type OrderItem, type OrderNote, type OrderStatus, type OrdersMetrics, PROVIDER_METADATA, type PaginationOptions, type PasswordResetConfirm, type PasswordResetRequest, type PaymentMethod$1 as PaymentMethod, type PaymentMethodFeatures, type PaymentMethodType, type PaymentMethodsOptions, type PaymentStatus, type PreviewDropshipperOrderItem, type PreviewDropshipperOrderTotalsBody, type PreviewDropshipperOrderTotalsResponse, type PriceRange, type PriceUpdatedNotificationData, type Product, type ProductAssignedNotificationData, type ProductCategory, type ProductOption, type ProductPreview, type ProductVariant, type ProductsMetrics, type PromotionRule, type ProviderCategory, type ProviderConfig, type ProviderTypeString, type QueryEntitiesInput, type QueryEntityInput, type QueryErrors, type QueryMeta, type QueryResponse, type QuerySortDirection, type RawNotification, type RecoveryConfirmResult, type Region, type RegisterData, type RegisterPaymentBody, type RegisterPaymentResponse, type RequestedProfile, type ResolveGuaranteeBody, type ResolveGuaranteeResponse, type RestoreSiteConfigResponse, type Review, type SEO, type SalesChannelType, type SalesMetrics, type SearchBarConfig, type SearchResultMeta, type SelectedOption, type SetPaymentCollectorBody, type SetPaymentCollectorResponse, type SetPaymentMethodBody, type SetPaymentMethodResponse, type SettlementRecord, type SettlementStatus, type ShippingGroupInput, type ShippingMethod, type SiteConfig, type SiteConfigLabels, type SiteConfigMetadata, type SocialConfig, type SortOption, type SortOptions, type StockChangeNotificationData, type StockLocation, type StockStatus, type StockValidation, type StorefrontConfig, StorefrontConfigError, type StorefrontContext, type StorefrontPlatformType, type StorefrontSeoDefaults, type SubmitApplicationBody, type SubmitApplicationConflictApplication, type SubmitApplicationCreated, type SubmitApplicationResponse, type SubmitApplicationResult, type SubmitApplicationSalesChannel, SupportedProviderType, type TokenVerifyResult, type TokenVerifyState, type UnassignCategoriesFromChannelsBody, type UnassignCategoriesFromChannelsResponse, type UnassignCollectionsFromChannelsBody, type UnassignCollectionsFromChannelsResponse, type UpdateBusinessPolicyBody, type UpdateBusinessPolicyResponse, type UpdateCustomerData, type UpdateDropshipperCategoryBody, type UpdateDropshipperCustomerBody, type UpdateDropshipperCustomerResponse, type UpdateDropshipperDraftOrderBody, type UpdateDropshipperDraftOrderResponse, type UpdateDropshipperPricesBody, type UpdateDropshipperPricesResponse, type UpdateDropshipperProductStatusBody, type UpdateDropshipperProductStatusResponse, type UpdateDropshipperPromotionBody, type UpdateNotificationPreferencesBody, type UpdateSettlementStatusResponse, type UpdateSiteConfigBody, type UpdateSiteConfigResponse, type UpdateStorefrontConfigBody, type UpdateStorefrontConfigResponse, type ValidateCheckoutItemsRequest, type ValidateCheckoutItemsResponse, type ValidateGiftCardBody, type ValidateGiftCardResponse, type ValidatedCheckoutItem, getProviderMetadata, isSupportedProviderType };