@thorprovider/types 5.7.9 → 5.7.10

package/src/catalog.ts

@@ -1,210 +0,0 @@
-/**
- * @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/commerce.ts

@@ -1,88 +0,0 @@
-/**
- * @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;
-}