@thorprovider/types 5.7.8 → 5.7.9

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 (`/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.
+ */
+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

@@ -40,6 +40,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 +214,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 +264,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

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
 // ============================================
@@ -142,15 +169,10 @@ export type {
 } 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 +182,6 @@ export type {
   StorefrontPlatformType,
 } from './storefront';
 
-export {
-  StorefrontConfigError,
-} from './storefront';
-
 // ============================================
 // Storefront Configuration Types
 // ============================================
@@ -421,10 +439,6 @@ export type {
     ConvertDropshipperDraftOrderBody,
     ConvertDropshipperDraftOrderResponse,
     DeleteDropshipperDraftOrderResponse,
-    // Order totals preview
-    PreviewDropshipperOrderItem,
-    PreviewDropshipperOrderTotalsBody,
-    PreviewDropshipperOrderTotalsResponse,
     // Dropshipper addresses (channel-scoped)
     DropshipperAddressBody,
     DropshipperAddressResponse,

package/src/provider.ts

@@ -1,47 +1,22 @@
 /**
- * @thorprovider/types — Supported Providers
+ * @thorprovider/types — Supported Providers (type-only)
  *
- * Centralized list of all supported commerce providers.
- * This is the single source of truth for provider types across the monorepo.
+ * Defines the provider-type union contract shared across the monorepo.
  *
  * @remarks
- * - 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)
+ * - 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.
  */
-export 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.
@@ -55,142 +30,3 @@ export enum SupportedProviderType {
  * ```
  */
 export type ProviderTypeString = 'mock' | 'medusa' | 'stelorder' | 'shopify' | 'bigcommerce' | 'woocommerce' | 'spree' | 'magento';
-
-/**
- * Metadata about each provider.
- * Useful for UI, error messages, validation, and documentation.
- *
- * @internal
- */
-export const PROVIDER_METADATA: Record<
-  ProviderTypeString,
-  {
-    name: string;
-    description: string;
-    requiresStorefront: boolean;
-    requiredEnvVars: string[];
-    maxRetries: number;
-  }
-> = {
-  mock: {
-    name: 'Mock',
-    description: 'Fixture-backed runtime provider for layout/design mode without a real backend',
-    requiresStorefront: false,
-    requiredEnvVars: [],
-    maxRetries: 0,
-  },
-  medusa: {
-    name: 'Medusa JS',
-    description: 'Medusa v2 commerce engine',
-    requiresStorefront: true,
-    requiredEnvVars: [
-      'NEXT_PUBLIC_COMMERCE_API_URL',
-      'NEXT_PUBLIC_COMMERCE_API_KEY',
-      'NEXT_PUBLIC_SALES_CHANNEL_ID',
-    ],
-    maxRetries: 3,
-  },
-  stelorder: {
-    name: 'Stel Order',
-    description: 'Stel Order ERP and sales document API',
-    requiresStorefront: false,
-    requiredEnvVars: [
-      'NEXT_PUBLIC_COMMERCE_API_URL',
-      'NEXT_PUBLIC_COMMERCE_API_KEY',
-    ],
-    maxRetries: 2,
-  },
-  shopify: {
-    name: 'Shopify',
-    description: 'Shopify Storefront API (GraphQL)',
-    requiresStorefront: false,
-    requiredEnvVars: [
-      'NEXT_PUBLIC_SHOPIFY_STORE_DOMAIN',
-      'NEXT_PUBLIC_SHOPIFY_STOREFRONT_TOKEN',
-    ],
-    maxRetries: 3,
-  },
-  bigcommerce: {
-    name: 'BigCommerce',
-    description: 'BigCommerce REST Storefront API',
-    requiresStorefront: false,
-    requiredEnvVars: [
-      'BIGCOMMERCE_STORE_HASH',
-      'BIGCOMMERCE_STOREFRONT_API_TOKEN',
-      'BIGCOMMERCE_CHANNEL_ID',
-    ],
-    maxRetries: 3,
-  },
-  woocommerce: {
-    name: 'WooCommerce',
-    description: 'WooCommerce Store API + REST API v3',
-    requiresStorefront: false,
-    requiredEnvVars: [
-      'WOOCOMMERCE_URL',
-      'WOOCOMMERCE_CONSUMER_KEY',
-      'WOOCOMMERCE_CONSUMER_SECRET',
-    ],
-    maxRetries: 3,
-  },
-  spree: {
-    name: 'Spree Commerce',
-    description: 'Spree API v2 Storefront (JSON:API)',
-    requiresStorefront: false,
-    requiredEnvVars: [
-      'SPREE_API_URL',
-    ],
-    maxRetries: 3,
-  },
-  magento: {
-    name: 'Adobe Commerce (Magento)',
-    description: 'Adobe Commerce GraphQL + REST API',
-    requiresStorefront: true,
-    requiredEnvVars: [
-      'MAGENTO_URL',
-      'MAGENTO_STORE_CODE',
-    ],
-    maxRetries: 3,
-  },
-};
-
-/**
- * Check if a string is a valid provider type.
- *
- * @example
- * ```typescript
- * if (isSupportedProviderType(process.env.COMMERCE_PROVIDER)) {
- *   // type is narrowed to ProviderTypeString
- * }
- * ```
- */
-export function isSupportedProviderType(
-  value: unknown
-): value is ProviderTypeString {
-  return (
-    typeof value === 'string' &&
-    Object.values(SupportedProviderType).includes(value as SupportedProviderType)
-  );
-}
-
-/**
- * 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`);
- * ```
- */
-export function getProviderMetadata(
-  type: ProviderTypeString
-): (typeof PROVIDER_METADATA)[ProviderTypeString] {
-  if (!isSupportedProviderType(type)) {
-    throw new Error(
-      `Unsupported provider: ${type}. Supported: ${Object.values(
-        SupportedProviderType
-      ).join(', ')}`
-    );
-  }
-  return PROVIDER_METADATA[type];
-}