@thorprovider/types 5.7.10 → 5.8.0

package/src/catalog.ts

@@ -0,0 +1,210 @@
+/**
+ * @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>`.
+ */
+
+import type { Product } from './product';
+
+/**
+ * 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.
+ */
+export 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.
+ */
+export interface CatalogQuery {
+  /** Free-text term (`q`). Trimmed, bounded, and empty treated as absent. */
+  text?: string;
+  /**
+   * Category scope supplied by the route path (`/categories/[[...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.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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`.
+ */
+export 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.
+ */
+export type CatalogQueryOutcome =
+  | { ok: true; results: CatalogResults }
+  | { ok: false; error: CatalogQueryFailure };

package/src/collection.ts

@@ -26,6 +26,16 @@ export 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;
 }
 
 /**

package/src/commerce-provider.ts

@@ -32,7 +32,12 @@ import type {
   GetCategoriesOptions
 } from './category';
 import type { Customer, Address, GetCustomersOptions } from './customer';
-import type { Order, GetOrdersOptions } from './order';
+import type {
+  Order,
+  GetOrdersOptions,
+  GetCustomerOrdersPageOptions,
+  CustomerOrdersPage,
+} from './order';
 import type { Region } from './region';
 import type { PaymentMethod, PaymentMethodsOptions } from './payment';
 import type { AuthProvider } from './auth';
@@ -40,6 +45,7 @@ import type { StorefrontContext } from './storefront';
 import type { StockLocation, InventoryLevel, StockValidation, FulfillmentOption } from './stock-location';
 import type { StorefrontConfig } from './storefront-config';
 import type { DesignerConfig, DesignerHistoryEntry } from './designer-config';
+import type { CatalogQuery, CatalogQueryOutcome, CatalogSortKey } from './catalog';
 
 /**
  * Backend capabilities interface
@@ -213,6 +219,22 @@ export 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.
    *
@@ -247,6 +269,25 @@ export 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
@@ -826,6 +867,22 @@ export interface CommerceProvider {
    * @returns Array of orders
    */
   getOrders?(options: GetOrdersOptions): Promise<Order[]>;
+
+  /**
+   * Get the authenticated customer's order history as a paginated window
+   * (OPTIONAL, additive).
+   *
+   * Returns `{ orders, count, limit, offset }`, where `count` is the backend's
+   * real total for the authenticated customer and the store's sales channel,
+   * computed after the server-side customer+channel filter and before
+   * pagination. The legacy array-returning `getOrders` stays unchanged for
+   * existing callers.
+   *
+   * A provider that does not implement this method (for example the mock data
+   * source) fails closed at the runtime boundary rather than pretending an
+   * empty history.
+   */
+  customerOrdersPage?(options: GetCustomerOrdersPageOptions): Promise<CustomerOrdersPage>;
   
   // ============================================
   // Payment Operations

package/src/commerce.ts

@@ -0,0 +1,88 @@
+/**
+ * @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
+ */
+
+import type { Money } from './common';
+
+/**
+ * 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.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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;
+}

package/src/index.ts

@@ -20,6 +20,16 @@ export type {
   Country,
 } from './common';
 
+// ============================================
+// Commerce Contracts (single-store context + guest shapes)
+// ============================================
+export type {
+  StoreContext,
+  ShopperIdentity,
+  CartSession,
+  OrderReceipt,
+} from './commerce';
+
 export type {
   AuthorConfig,
   BrandConfig,
@@ -43,6 +53,23 @@ export type {
   QueryResponse,
 } from './query';
 
+// ============================================
+// Catalog Query & Facet Support Types
+// ============================================
+export type {
+  CatalogSortKey,
+  CatalogQuery,
+  CatalogAppliedFilters,
+  CatalogFacetId,
+  CatalogFacetDemonstrationSource,
+  FacetSupport,
+  CatalogResults,
+  CatalogQueryFailureCode,
+  CatalogQueryFailureRepair,
+  CatalogQueryFailure,
+  CatalogQueryOutcome,
+} from './catalog';
+
 // ============================================
 // Product Types
 // ============================================
@@ -139,18 +166,15 @@ export type {
   FulfillmentStatus,
   GetOrdersOptions,
   GetOrdersCallback,
+  GetCustomerOrdersPageOptions,
+  CustomerOrdersPage,
 } from './order';
 
 // ============================================
-// Provider Types (L1 - Source of Truth)
+// Provider Types (L1 - type-only)
+// Runtime provider registry lives in @thorprovider/adapters
 // ============================================
-export { SupportedProviderType, type ProviderTypeString } from './provider';
-
-export {
-  isSupportedProviderType,
-  getProviderMetadata,
-  PROVIDER_METADATA,
-} from './provider';
+export type { ProviderTypeString } from './provider';
 
 // ============================================
 // Storefront Types
@@ -160,10 +184,6 @@ export type {
   StorefrontPlatformType,
 } from './storefront';
 
-export {
-  StorefrontConfigError,
-} from './storefront';
-
 // ============================================
 // Storefront Configuration Types
 // ============================================
@@ -332,8 +352,6 @@ export type {
   SetPaymentCollectorResponse,
   SetPaymentMethodBody,
   SetPaymentMethodResponse,
-  ValidateGiftCardBody,
-  ValidateGiftCardResponse,
   DropshipperCategory,
   GetDropshipperCategoriesOptions,
   GetDropshipperCategoriesResponse,
@@ -423,10 +441,6 @@ export type {
     ConvertDropshipperDraftOrderBody,
     ConvertDropshipperDraftOrderResponse,
     DeleteDropshipperDraftOrderResponse,
-    // Order totals preview
-    PreviewDropshipperOrderItem,
-    PreviewDropshipperOrderTotalsBody,
-    PreviewDropshipperOrderTotalsResponse,
     // Dropshipper addresses (channel-scoped)
     DropshipperAddressBody,
     DropshipperAddressResponse,

package/src/order.ts

@@ -186,3 +186,36 @@ export interface GetOrdersOptions {
    */
   customFetcher?: GetOrdersCallback;
 }
+
+/**
+ * Options for the additive paginated order-history contract.
+ *
+ * Unlike {@link GetOrdersOptions}, this carries an explicit 1-based `page` and
+ * `pageSize` so a caller can request a bounded window of the authenticated
+ * customer's channel-scoped history. `salesChannelId` is the store's configured
+ * channel and is validated against the backend's channel scoping; a provider
+ * MUST NOT fall back to a blind first channel id when it is absent.
+ */
+export interface GetCustomerOrdersPageOptions {
+  /** 1-based page number (default 1). */
+  page?: number;
+  /** Rows per page (default 10, bounded by the provider's canonical limit). */
+  pageSize?: number;
+  /** The store's configured sales channel id (explicit; never a blind first id). */
+  salesChannelId?: string;
+}
+
+/**
+ * The additive paginated order-history result.
+ *
+ * `count` is the backend's real total for the authenticated customer and the
+ * store's sales channel, computed after the server-side customer+channel filter
+ * and before pagination — never a page length or a `limit`-floored estimate.
+ * `limit`/`offset` echo the backend's applied window.
+ */
+export interface CustomerOrdersPage {
+  orders: Order[];
+  count: number;
+  limit: number;
+  offset: number;
+}

package/src/product.ts

@@ -92,6 +92,7 @@ export interface Product {
   
   // Organization (optional, platform-dependent)
   collections?: Array<{ id: string; title: string; handle: string }>;  // Shopify/Medusa: collections, WooCommerce/Magento: categories
+  categories?: Array<{ id: string; name: string; handle: string; parentCategoryId?: string }>;  // Product's category references (Medusa: categories; carries hierarchy for breadcrumbs)
   productType?: string;  // Shopify: productType, Medusa: type, WooCommerce: type (simple/variable)
   vendor?: string;  // Shopify-specific, stored in metadata for others
   tags?: string[];