@01.software/sdk 0.27.0 → 0.29.0

package/dist/{server-_zvihptw.d.ts → server-Cv0Q4dPQ.d.ts}

@@ -1,10 +1,10 @@
 import * as _tanstack_react_query from '@tanstack/react-query';
-import { QueryClient, InfiniteData } from '@tanstack/react-query';
-import { O as Order, d as Cart, e as CartItem, f as Product, l as OrderItem, m as Transaction, n as Fulfillment, o as Return } from './payload-types-BPvUmPAq.js';
+import { QueryClient, InfiniteData, UseQueryResult } from '@tanstack/react-query';
+import { O as Order, d as Cart, e as CartItem, f as Product, l as OrderItem, m as Transaction, n as Fulfillment, o as Return } from './payload-types-Ci-ZA7aM.js';
 import { Sort, Where } from 'payload';
 import { Metadata } from 'next';
-import { C as CollectionType } from './types-BLdthWiW.js';
-import { P as PublicCollection, d as ServerCollection } from './const-D-xucnw4.js';
+import { C as CollectionType } from './types-BWq_WlbB.js';
+import { P as PublicCollection, d as ServerCollection } from './const-DAjQYNuM.js';
 
 declare function resolveApiUrl(): string;
 interface ClientConfig {
@@ -88,12 +88,51 @@ interface ApiQueryOptions {
     page?: number;
     limit?: number;
     sort?: Sort;
+    /**
+     * Filter documents. Id-based relation filters (`where: { product: { equals: id } }`) are the
+     * most reliable pattern. Dotted-path relation filters (`where: { 'product.slug': { equals } }`)
+     * are Payload-native but may silently return empty when access control restricts the related
+     * document or when the relation is polymorphic. String shorthand (`where: { slug: 'x' }`)
+     * silently matches nothing — always use `{ slug: { equals: 'x' } }`.
+     */
     where?: Where;
+    /**
+     * Controls how deeply relationship fields are populated. This is the primary control for
+     * populating relationships like `category`, `images`, `brand`. The configured Payload default
+     * applies when unset.
+     */
     depth?: number;
     select?: Record<string, boolean>;
-    /** Per-collection field selection for populated relationships (keyed by collection slug) */
+    /**
+     * Controls which fields are returned for already-populated relationships, keyed by collection
+     * slug. Does NOT control which relationships to populate — that is `depth`.
+     *
+     * @example
+     * // depth: 2 populates category; populate trims which fields come back
+     * populate: { categories: { title: true, slug: true } }
+     */
     populate?: Record<string, boolean | Record<string, boolean>>;
-    /** Join field control: pagination/filter per join, or false to disable */
+    /**
+     * Controls Payload `type: 'join'` virtual reverse-relation fields only (pagination, sort,
+     * filter, count per join field, or `false` to disable all join-field population).
+     *
+     * Does NOT populate normal relationship fields like `category`, `images`, or `brand`.
+     * For normal relationship population use `depth` (and optionally `populate` for field
+     * selection).
+     *
+     * Pass `joins: false` to disable all join-field population — useful for lightweight list
+     * queries where join fields are not needed.
+     *
+     * @example
+     * // `article-authors` has a `type: 'join'` field `articles` (reverse-relation)
+     * joins: { articles: { limit: 10, sort: '-publishedAt' } }
+     *
+     * // depth: 2 populates product.category — joins has no effect on this
+     * depth: 2
+     *
+     * // Disable all join-field population
+     * joins: false
+     */
     joins?: Record<string, {
         limit?: number;
         page?: number;
@@ -850,9 +889,7 @@ type EntityID = string;
 type RelationshipValue = string | number | null | undefined | {
     id?: string | number | null;
 };
-type MediaValue = {
-    id?: EntityID | null;
-} | EntityID | null | undefined;
+type MediaValue = ProductDetailMedia | null | undefined;
 interface ProductOptionValueShape {
     id?: string | number | null;
     option?: RelationshipValue;
@@ -867,6 +904,7 @@ interface ProductOptionValueShape {
 interface ProductOptionShape {
     id?: string | number | null;
     title?: string | null;
+    slug?: string | null;
     _order?: string | null;
     '_product-options_options_order'?: string | null;
     values?: {
@@ -894,6 +932,7 @@ interface ProductListingProductShape {
 type ProductOptionMatrixValue = {
     id: string;
     optionId: string;
+    optionSlug: string;
     label: string;
     slug: string | null;
     swatchColor?: string | null;
@@ -904,6 +943,7 @@ type ProductOptionMatrixValue = {
 type ProductOptionMatrixOption = {
     id: string;
     title: string;
+    slug: string;
     order: string;
     values: ProductOptionMatrixValue[];
 };
@@ -911,14 +951,18 @@ type ProductOptionMatrixVariant<TVariant extends ProductVariantShape = ProductVa
     id: string;
     optionValueIds: string[];
     optionValueByOptionId: Map<string, string>;
+    optionValueByOptionSlug: Map<string, string>;
     source: TVariant;
 };
 type ProductOptionMatrix<TVariant extends ProductVariantShape = ProductVariantShape> = {
     options: ProductOptionMatrixOption[];
     optionIds: string[];
+    optionSlugs: string[];
     optionById: Map<string, ProductOptionMatrixOption>;
+    optionBySlug: Map<string, ProductOptionMatrixOption>;
     valueById: Map<string, ProductOptionMatrixValue>;
     valueToOptionId: Map<string, string>;
+    valueToOptionSlug: Map<string, string>;
     variants: ProductOptionMatrixVariant<TVariant>[];
 };
 type ProductListingProjection = {
@@ -945,14 +989,90 @@ type ProductListingGroup<TVariant extends ProductVariantShape = ProductVariantSh
     variants: TVariant[];
     listing: ProductListingProjection;
 };
+type ProductSelectionByOptionValue = string | number | null | undefined | {
+    valueId?: string | number | null;
+    valueSlug?: string | null;
+};
+type ProductSelectionInput = {
+    variantId?: string | number | null;
+    byOptionSlug?: Record<string, ProductSelectionByOptionValue>;
+    byOptionId?: Record<string, ProductSelectionByOptionValue>;
+    valueIds?: Iterable<unknown>;
+    search?: string | URLSearchParams | URL | null;
+};
+type NormalizedProductSelection = {
+    byOptionSlug: Record<string, string>;
+    byOptionId: Record<string, string>;
+    valueIds: string[];
+    variantId: string | null;
+};
+type LegacyProductSelectionParamEvent = {
+    optionId: string;
+    optionSlug: string;
+    valueSlug: string;
+    searchParam: string;
+};
+type ProductSelectionCodecOptions = {
+    onLegacyOptionIdParam?: (event: LegacyProductSelectionParamEvent) => void;
+};
+type ProductSelectionAvailableValue = {
+    valueId: string;
+    value: string;
+    slug: string;
+    selected: boolean;
+    available: boolean;
+    swatchColor?: string | null;
+    thumbnail?: MediaValue;
+    images?: MediaValue[] | null;
+};
+type ProductSelectionResolution = {
+    normalizedSelection: NormalizedProductSelection;
+    selectedVariant: ProductDetailVariant | null;
+    matchingVariants: ProductDetailVariant[];
+    partialVariants: ProductDetailVariant[];
+    availableValuesByOptionSlug: Record<string, ProductSelectionAvailableValue[]>;
+    availableValuesByOptionId: Record<string, ProductSelectionAvailableValue[]>;
+    allOptionsSelected: boolean;
+    price: {
+        min: number | null;
+        max: number | null;
+        compareAtMin: number | null;
+        compareAtMax: number | null;
+        isRange: boolean;
+    };
+    media: {
+        primaryImage: ProductDetailMedia | null;
+        images: ProductDetailMedia[];
+    };
+    stock: {
+        availableForSale: boolean;
+        isUnlimited: boolean;
+        stock: number | null;
+        reservedStock: number | null;
+        availableStock: number | null;
+    };
+};
+declare class ProductSelectionCodecError extends Error {
+    code: string;
+    constructor(message: string);
+}
 declare function buildProductOptionMatrix<TVariant extends ProductVariantShape = ProductVariantShape>({ options, variants, }: {
     options: ProductOptionShape[];
     variants?: TVariant[];
 }): ProductOptionMatrix<TVariant>;
+declare function buildProductOptionMatrixFromDetail(detail: ProductDetail): ProductOptionMatrix<ProductDetailVariant>;
 declare function getSelectedValueByOptionId<TVariant extends ProductVariantShape = ProductVariantShape>(matrix: ProductOptionMatrix<TVariant>, selectedValueIds: Iterable<unknown>): Map<string, string>;
 declare function normalizeSelectedValueIds<TVariant extends ProductVariantShape = ProductVariantShape>(matrix: ProductOptionMatrix<TVariant>, selectedValueIds: Iterable<unknown>): string[];
 declare function getAvailableOptionValues<TVariant extends ProductVariantShape = ProductVariantShape>(matrix: ProductOptionMatrix<TVariant>, optionId: string, selectedValueIds: Iterable<unknown>): ProductOptionMatrixValue[];
 declare function resolveVariantForSelection<TVariant extends ProductVariantShape = ProductVariantShape>(matrix: ProductOptionMatrix<TVariant>, selectedValueIds: Iterable<unknown>): ProductOptionMatrixVariant<TVariant> | undefined;
+declare function normalizeProductSelection(detail: ProductDetail, selection?: ProductSelectionInput, options?: ProductSelectionCodecOptions): NormalizedProductSelection;
+declare function parseProductSelection(detail: ProductDetail, search: string | URLSearchParams | URL | null | undefined, options?: ProductSelectionCodecOptions): NormalizedProductSelection;
+declare function stringifyProductSelection(detail: ProductDetail, selection?: ProductSelectionInput, options?: ProductSelectionCodecOptions): string;
+declare function createProductSelectionCodec(detail: ProductDetail, options?: ProductSelectionCodecOptions): {
+    parse: (search: string | URLSearchParams | URL | null | undefined) => NormalizedProductSelection;
+    stringify: (selection?: ProductSelectionInput) => string;
+};
+declare function resolveProductSelection(detail: ProductDetail, selection?: ProductSelectionInput, options?: ProductSelectionCodecOptions): ProductSelectionResolution;
 declare function buildProductListingProjection(product: ProductListingProductShape | null | undefined, variants: ProductVariantShape[]): ProductListingProjection;
 /**
  * Builds product-first listing groups for one primary option.
@@ -998,6 +1118,170 @@ type ProductListingGroupsItem = {
 type ProductListingGroupsResponse = {
     docs: ProductListingGroupsItem[];
 };
+type ProductDetailParams = {
+    slug: string;
+} | {
+    id: string;
+};
+interface ProductDetailVariantOptionValue {
+    optionId: string | number;
+    optionSlug: string;
+    valueId: string | number;
+    valueSlug: string;
+    value?: string | null;
+}
+type ProductDetailMedia = string | number | {
+    id?: string | number | null;
+    url?: string | null;
+    alt?: string | null;
+    width?: number | null;
+    height?: number | null;
+};
+interface ProductDetailVariant {
+    id: string | number;
+    optionKey: string;
+    title?: string | null;
+    displayName: string;
+    sku?: string | null;
+    price: number;
+    compareAtPrice?: number | null;
+    stock: number;
+    reservedStock: number;
+    isUnlimited: boolean;
+    isActive: boolean;
+    thumbnail?: ProductDetailMedia | null;
+    images?: ProductDetailMedia[];
+    optionValues: ProductDetailVariantOptionValue[];
+}
+interface ProductDetailOptionValue {
+    id: string | number;
+    value: string;
+    slug: string;
+    swatchColor?: string | null;
+    thumbnail?: ProductDetailMedia | null;
+    images?: ProductDetailMedia[] | null;
+}
+interface ProductDetailOption {
+    id: string | number;
+    title: string;
+    slug: string;
+    values: ProductDetailOptionValue[];
+}
+interface ProductDetailBrand {
+    id: string | number;
+    name: string;
+    slug?: string | null;
+    logo?: unknown | null;
+}
+interface ProductDetailCategory {
+    id: string | number;
+    title: string;
+    slug?: string | null;
+}
+interface ProductDetailTag {
+    id: string | number;
+    title: string;
+    slug?: string | null;
+}
+interface ProductDetailImage {
+    id: string | number;
+    url?: string | null;
+    alt?: string | null;
+    width?: number | null;
+    height?: number | null;
+}
+interface ProductDetailVideo {
+    id: string | number;
+    url?: string | null;
+}
+interface ProductDetailListing {
+    minPrice?: number | null;
+    maxPrice?: number | null;
+    minCompareAtPrice?: number | null;
+    maxCompareAtPrice?: number | null;
+    isPriceRange?: boolean | null;
+    primaryImage?: ProductDetailMedia | null;
+    availableForSale?: boolean | null;
+    selectionHintVariant?: string | number | null;
+}
+interface ProductDetail {
+    product: {
+        id: string | number;
+        slug: string;
+        title: string;
+        subtitle?: string | null;
+        description?: string | null;
+        content?: unknown;
+        publishedAt?: string | null;
+        status: string;
+        totalInventory: number;
+        totalVariants: number;
+        hasOnlyDefaultVariant: boolean;
+    };
+    variants: ProductDetailVariant[];
+    options: ProductDetailOption[];
+    brand: ProductDetailBrand | null;
+    categories: ProductDetailCategory[];
+    tags: ProductDetailTag[];
+    images: ProductDetailImage[];
+    videos: ProductDetailVideo[];
+    listing: ProductDetailListing;
+}
+type ProductUpsertOptionValueInput = {
+    id?: string;
+    value: string;
+    slug?: string;
+    swatchColor?: string | null;
+    thumbnail?: string | null;
+    images?: string[];
+    metadata?: unknown;
+};
+type ProductUpsertOptionInput = {
+    id?: string;
+    title: string;
+    slug?: string;
+    values: ProductUpsertOptionValueInput[];
+};
+type ProductUpsertVariantOptionValue = string | {
+    valueSlug?: string;
+    valueId?: string;
+    value?: string;
+};
+type ProductUpsertVariantInput = {
+    id?: string;
+    optionValues?: Record<string, ProductUpsertVariantOptionValue> | string[];
+    sku?: string | null;
+    title?: string | null;
+    price: number;
+    compareAtPrice?: number | null;
+    stock?: number;
+    isUnlimited?: boolean;
+    weight?: number | null;
+    requiresShipping?: boolean;
+    barcode?: string | null;
+    externalId?: string | null;
+    isActive?: boolean;
+    thumbnail?: string | null;
+    images?: string[];
+    metadata?: unknown;
+};
+type ProductUpsertParams = {
+    product: Record<string, unknown> & {
+        id?: string;
+        title?: string;
+    };
+    options?: ProductUpsertOptionInput[];
+    variants?: ProductUpsertVariantInput[];
+};
+type ProductUpsertResponse = {
+    ok: true;
+    product: Product;
+} | {
+    ok: false;
+    failedEntity: 'product' | 'option' | 'option-value' | 'variant';
+    failedIndex?: number;
+    message: string;
+};
 declare class ProductApi extends BaseApi {
     constructor(options: ProductApiOptions);
     /**
@@ -1007,6 +1291,20 @@ declare class ProductApi extends BaseApi {
      */
     stockCheck(params: StockCheckParams): Promise<StockCheckResponse>;
     listingGroups(params: ListingGroupsParams): Promise<ProductListingGroupsResponse>;
+    /**
+     * Fetch full product detail by slug or id.
+     * Returns `null` on 404 regardless of reason (`not_found` / `not_published` /
+     * `tenant_mismatch` / `feature_disabled`). For the reason behind a null,
+     * inspect `client.lastRequestId` against backend logs.
+     */
+    detail(params: ProductDetailParams): Promise<ProductDetail | null>;
+    /**
+     * Atomically create or update a product together with its options,
+     * option-values, and variants in a single transaction. Mirrors Shopify's
+     * `productSet` shape and is the canonical write path for the MCP
+     * `product-upsert` tool.
+     */
+    upsert(params: ProductUpsertParams): Promise<ProductUpsertResponse>;
 }
 
 type DiscountApiOptions = ServerApiOptions;
@@ -1196,6 +1494,8 @@ declare class ServerCommerceClient {
     readonly product: {
         stockCheck: (params: StockCheckParams) => Promise<StockCheckResponse>;
         listingGroups: (params: ListingGroupsParams) => Promise<ProductListingGroupsResponse>;
+        detail: (params: ProductDetailParams) => Promise<ProductDetail | null>;
+        upsert: (params: ProductUpsertParams) => Promise<ProductUpsertResponse>;
     };
     readonly cart: {
         get: (cartId: string) => Promise<Cart>;
@@ -1371,9 +1671,15 @@ type ReadOnlyQueryHooks = Omit<QueryHooks, 'useCreate' | 'useUpdate' | 'useRemov
  * Composes CollectionHooks + CustomerHooks into a single API surface.
  * All methods are delegated; no logic lives here.
  */
+interface ProductDetailCallable {
+    product: {
+        detail: (params: ProductDetailParams) => Promise<ProductDetail | null>;
+    };
+}
 declare class QueryHooks extends CollectionHooks {
     private _customer;
-    constructor(queryClient: QueryClient, collectionClient: CollectionClient, customerAuth?: CustomerAuth);
+    private _commerce?;
+    constructor(queryClient: QueryClient, collectionClient: CollectionClient, customerAuth?: CustomerAuth, commerceClient?: ProductDetailCallable);
     useCustomerMe: CustomerHooks['useCustomerMe'];
     useCustomerLogin: CustomerHooks['useCustomerLogin'];
     useCustomerRegister: CustomerHooks['useCustomerRegister'];
@@ -1388,7 +1694,7 @@ declare class QueryHooks extends CollectionHooks {
     setCustomerData: CustomerHooks['setCustomerData'];
     useProductListingGroupsQuery<TData = PayloadFindResponse<ProductListingGroupsItem>>(params: {
         options?: ProductListingGroupsQueryOptions;
-    }, options?: QueryOptions<PayloadFindResponse<ProductListingGroupsItem>, TData>): _tanstack_react_query.UseQueryResult<_tanstack_react_query.NoInfer<TData>, Error>;
+    }, options?: QueryOptions<PayloadFindResponse<ProductListingGroupsItem>, TData>): UseQueryResult<_tanstack_react_query.NoInfer<TData>, Error>;
     useSuspenseProductListingGroupsQuery<TData = PayloadFindResponse<ProductListingGroupsItem>>(params: {
         options?: ProductListingGroupsQueryOptions;
     }, options?: SuspenseQueryOptions<PayloadFindResponse<ProductListingGroupsItem>, TData>): _tanstack_react_query.UseSuspenseQueryResult<TData, Error>;
@@ -1412,6 +1718,19 @@ declare class QueryHooks extends CollectionHooks {
         pages?: number;
         staleTime?: number;
     }): Promise<void>;
+    useProductDetail(params: {
+        slug: string;
+    } | {
+        id: string;
+    }, options?: {
+        enabled?: boolean;
+    }): UseQueryResult<ProductDetail | null>;
+    useProductDetailBySlug(slug: string, options?: {
+        enabled?: boolean;
+    }): UseQueryResult<ProductDetail | null>;
+    useProductDetailById(id: string, options?: {
+        enabled?: boolean;
+    }): UseQueryResult<ProductDetail | null>;
 }
 
 declare class ServerClient {
@@ -1440,4 +1759,4 @@ declare class ServerClient {
  */
 declare function createServerClient(options: ClientServerConfig): ServerClient;
 
-export { type CustomerLoginData as $, type AddItemParams as A, type BanCustomerParams as B, CustomerAuth as C, CollectionClient as D, type CollectionDetailQueryParams as E, CollectionHooks as F, type CollectionInfiniteQueryParams as G, CollectionQueryBuilder as H, type CollectionQueryParams as I, type CommunityBan as J, type CommunityClientOptions as K, type ListingGroupsParams as L, type CommunityPost as M, ConfigError as N, type ConfirmPaymentParams as O, type ProductListingGroupsResponse as P, type ConfirmPaymentResponse as Q, type RemoveItemParams as R, type StockCheckParams as S, ConflictError as T, type UpdateItemParams as U, type ValidateDiscountParams as V, type CreateFulfillmentParams as W, type CreateOrderParams as X, type CreateReturnParams as Y, type CustomerAuthResponse as Z, CustomerHooks as _, type CustomerAuthOptions as a, type UpdateReturnParams as a$, type CustomerProfile as a0, type CustomerRefreshResponse as a1, type CustomerRegisterData as a2, type CustomerRegisterResponse as a3, type CustomerSnapshot as a4, type DebugConfig as a5, type DeepPartial as a6, DiscountApi as a7, type DiscountApiOptions as a8, type ExtractArrayType as a9, QueryHooks as aA, type QueryOptions as aB, RateLimitError as aC, type ReadOnlyQueryBuilder as aD, type RequestOptions as aE, type RetryConfig as aF, type ReturnItem as aG, type ReturnReason as aH, type ReturnWithRefundParams as aI, SDKError as aJ, type ServerApiOptions as aK, ServerClient as aL, ServerCollectionClient as aM, ServerCollectionQueryBuilder as aN, ServerCommerceClient as aO, type ServerCommerceClientOptions as aP, ServiceUnavailableError as aQ, ShippingApi as aR, type ShippingApiOptions as aS, type StockCheckResult as aT, type SuspenseInfiniteQueryOptions as aU, type SuspenseQueryOptions as aV, TimeoutError as aW, type UnbanCustomerParams as aX, type UpdateFulfillmentParams as aY, type UpdateOrderParams as aZ, type UpdateProfileData as a_, type GenerateMetadataOptions as aa, GoneError as ab, type InfiniteQueryOptions as ac, ModerationApi as ad, type ModerationApiOptions as ae, NetworkError as af, NotFoundError as ag, OrderApi as ah, type OrderApiOptions as ai, type PaginationMeta as aj, type PayloadMutationResponse as ak, PermissionError as al, ProductApi as am, type ProductApiOptions as an, type ProductListingGroup as ao, type ProductListingGroupSummary as ap, type ProductListingGroupsItem as aq, type ProductListingProductShape as ar, type ProductListingProjection as as, type ProductOptionMatrix as at, type ProductOptionMatrixOption as au, type ProductOptionMatrixValue as av, type ProductOptionMatrixVariant as aw, type ProductOptionShape as ax, type ProductOptionValueShape as ay, type ProductVariantShape as az, type StockCheckResponse as b, type UpdateTransactionParams as b0, UsageLimitError as b1, ValidationError as b2, buildProductListingGroupsByOption as b3, buildProductListingProjection as b4, buildProductOptionMatrix as b5, createAuthError as b6, createConflictError as b7, createNotFoundError as b8, createPermissionError as b9, createRateLimitError as ba, createServerClient as bb, getAvailableOptionValues as bc, getSelectedValueByOptionId as bd, isApiError as be, isAuthError as bf, isConfigError as bg, isConflictError as bh, isGoneError as bi, isNetworkError as bj, isNotFoundError as bk, isPermissionError as bl, isRateLimitError as bm, isSDKError as bn, isServiceUnavailableError as bo, isTimeoutError as bp, isUsageLimitError as bq, isValidationError as br, normalizeSelectedValueIds as bs, resolveApiUrl as bt, resolveVariantForSelection as bu, type ApplyDiscountParams as c, type RemoveDiscountParams as d, type ClearCartParams as e, type CheckoutParams as f, type PayloadFindResponse as g, type ValidateDiscountResult as h, type CalculateShippingParams as i, type CalculateShippingResult as j, type ApiQueryOptions as k, type ProductListingGroupsQueryOptions as l, CommunityClient as m, type ReadOnlyQueryHooks as n, ReadOnlyCollectionClient as o, type ClientState as p, type ClientConfig as q, ApiError as r, AuthError as s, BaseApi as t, type BulkImportFulfillmentsParams as u, type BulkImportFulfillmentsResponse as v, CartApi as w, type CartApiOptions as x, type ClientMetadata as y, type ClientServerConfig as z };
+export { type CustomerAuthResponse as $, type AddItemParams as A, type BanCustomerParams as B, CustomerAuth as C, type ClientMetadata as D, type ClientServerConfig as E, CollectionClient as F, type CollectionDetailQueryParams as G, CollectionHooks as H, type CollectionInfiniteQueryParams as I, CollectionQueryBuilder as J, type CollectionQueryParams as K, type ListingGroupsParams as L, type CommunityBan as M, type CommunityClientOptions as N, type CommunityPost as O, type ProductListingGroupsResponse as P, ConfigError as Q, type RemoveItemParams as R, type StockCheckParams as S, type ConfirmPaymentParams as T, type UpdateItemParams as U, type ValidateDiscountParams as V, type ConfirmPaymentResponse as W, ConflictError as X, type CreateFulfillmentParams as Y, type CreateOrderParams as Z, type CreateReturnParams as _, type CustomerAuthOptions as a, type ReturnItem as a$, CustomerHooks as a0, type CustomerLoginData as a1, type CustomerProfile as a2, type CustomerRefreshResponse as a3, type CustomerRegisterData as a4, type CustomerRegisterResponse as a5, type CustomerSnapshot as a6, type DebugConfig as a7, type DeepPartial as a8, DiscountApi as a9, type ProductDetailVariant as aA, type ProductDetailVariantOptionValue as aB, type ProductDetailVideo as aC, type ProductListingGroup as aD, type ProductListingGroupSummary as aE, type ProductListingGroupsItem as aF, type ProductListingProductShape as aG, type ProductListingProjection as aH, type ProductOptionMatrix as aI, type ProductOptionMatrixOption as aJ, type ProductOptionMatrixValue as aK, type ProductOptionMatrixVariant as aL, type ProductOptionShape as aM, type ProductOptionValueShape as aN, type ProductSelectionAvailableValue as aO, type ProductSelectionByOptionValue as aP, ProductSelectionCodecError as aQ, type ProductSelectionCodecOptions as aR, type ProductSelectionInput as aS, type ProductSelectionResolution as aT, type ProductVariantShape as aU, QueryHooks as aV, type QueryOptions as aW, RateLimitError as aX, type ReadOnlyQueryBuilder as aY, type RequestOptions as aZ, type RetryConfig as a_, type DiscountApiOptions as aa, type ExtractArrayType as ab, type GenerateMetadataOptions as ac, GoneError as ad, type InfiniteQueryOptions as ae, type LegacyProductSelectionParamEvent as af, ModerationApi as ag, type ModerationApiOptions as ah, NetworkError as ai, type NormalizedProductSelection as aj, NotFoundError as ak, OrderApi as al, type OrderApiOptions as am, type PaginationMeta as an, type PayloadMutationResponse as ao, PermissionError as ap, ProductApi as aq, type ProductApiOptions as ar, type ProductDetailBrand as as, type ProductDetailCategory as at, type ProductDetailImage as au, type ProductDetailListing as av, type ProductDetailMedia as aw, type ProductDetailOption as ax, type ProductDetailOptionValue as ay, type ProductDetailTag as az, type StockCheckResponse as b, type ReturnReason as b0, type ReturnWithRefundParams as b1, SDKError as b2, type ServerApiOptions as b3, ServerClient as b4, ServerCollectionClient as b5, ServerCollectionQueryBuilder as b6, ServerCommerceClient as b7, type ServerCommerceClientOptions as b8, ServiceUnavailableError as b9, getSelectedValueByOptionId as bA, isApiError as bB, isAuthError as bC, isConfigError as bD, isConflictError as bE, isGoneError as bF, isNetworkError as bG, isNotFoundError as bH, isPermissionError as bI, isRateLimitError as bJ, isSDKError as bK, isServiceUnavailableError as bL, isTimeoutError as bM, isUsageLimitError as bN, isValidationError as bO, normalizeProductSelection as bP, normalizeSelectedValueIds as bQ, parseProductSelection as bR, resolveApiUrl as bS, resolveProductSelection as bT, resolveVariantForSelection as bU, stringifyProductSelection as bV, ShippingApi as ba, type ShippingApiOptions as bb, type StockCheckResult as bc, type SuspenseInfiniteQueryOptions as bd, type SuspenseQueryOptions as be, TimeoutError as bf, type UnbanCustomerParams as bg, type UpdateFulfillmentParams as bh, type UpdateOrderParams as bi, type UpdateProfileData as bj, type UpdateReturnParams as bk, type UpdateTransactionParams as bl, UsageLimitError as bm, ValidationError as bn, buildProductListingGroupsByOption as bo, buildProductListingProjection as bp, buildProductOptionMatrix as bq, buildProductOptionMatrixFromDetail as br, createAuthError as bs, createConflictError as bt, createNotFoundError as bu, createPermissionError as bv, createProductSelectionCodec as bw, createRateLimitError as bx, createServerClient as by, getAvailableOptionValues as bz, type ProductDetailParams as c, type ProductDetail as d, type ApplyDiscountParams as e, type RemoveDiscountParams as f, type ClearCartParams as g, type CheckoutParams as h, type PayloadFindResponse as i, type ValidateDiscountResult as j, type CalculateShippingParams as k, type CalculateShippingResult as l, type ApiQueryOptions as m, type ProductListingGroupsQueryOptions as n, CommunityClient as o, type ReadOnlyQueryHooks as p, ReadOnlyCollectionClient as q, type ClientState as r, type ClientConfig as s, ApiError as t, AuthError as u, BaseApi as v, type BulkImportFulfillmentsParams as w, type BulkImportFulfillmentsResponse as x, CartApi as y, type CartApiOptions as z };

package/dist/server.cjs

@@ -1374,6 +1374,29 @@ var ProductApi = class extends BaseApi {
       params
     );
   }
+  /**
+   * Fetch full product detail by slug or id.
+   * Returns `null` on 404 regardless of reason (`not_found` / `not_published` /
+   * `tenant_mismatch` / `feature_disabled`). For the reason behind a null,
+   * inspect `client.lastRequestId` against backend logs.
+   */
+  async detail(params) {
+    try {
+      return await this.request("/api/products/detail", params);
+    } catch (err) {
+      if (err instanceof NotFoundError) return null;
+      throw err;
+    }
+  }
+  /**
+   * Atomically create or update a product together with its options,
+   * option-values, and variants in a single transaction. Mirrors Shopify's
+   * `productSet` shape and is the canonical write path for the MCP
+   * `product-upsert` tool.
+   */
+  upsert(params) {
+    return this.request("/api/products/upsert", params);
+  }
 };
 
 // src/core/api/discount-api.ts
@@ -1466,7 +1489,9 @@ var ServerCommerceClient = class {
     const orderApi = new OrderApi(serverOptions);
     this.product = {
       stockCheck: productApi.stockCheck.bind(productApi),
-      listingGroups: productApi.listingGroups.bind(productApi)
+      listingGroups: productApi.listingGroups.bind(productApi),
+      detail: productApi.detail.bind(productApi),
+      upsert: productApi.upsert.bind(productApi)
     };
     this.cart = {
       get: cartApi.getCart.bind(cartApi),
@@ -1553,10 +1578,24 @@ var customerKeys = {
 };
 var productKeys = {
   listingGroups: (options) => ["products", "listing-groups", "list", options],
-  listingGroupsInfinite: (options) => ["products", "listing-groups", "infinite", options]
+  listingGroupsInfinite: (options) => ["products", "listing-groups", "infinite", options],
+  detail: (params) => ["products", "detail", params],
+  detailAll: () => ["products", "detail"]
 };
 
 // src/core/query/collection-hooks.ts
+var PRODUCT_DETAIL_INVALIDATING_COLLECTIONS = /* @__PURE__ */ new Set([
+  "products",
+  "product-variants",
+  "product-options",
+  "product-option-values",
+  "product-categories",
+  "product-tags",
+  "product-collections",
+  "brands",
+  "brand-logos",
+  "images"
+]);
 var DEFAULT_PAGE_SIZE = 20;
 var CollectionHooks = class {
   constructor(queryClient, collectionClient) {
@@ -1714,6 +1753,9 @@ var CollectionHooks = class {
         this.queryClient.invalidateQueries({
           queryKey: collectionKeys(collection).all
         });
+        if (PRODUCT_DETAIL_INVALIDATING_COLLECTIONS.has(collection)) {
+          this.queryClient.invalidateQueries({ queryKey: ["products", "detail"] });
+        }
         options?.onSuccess?.(data);
       },
       onError: options?.onError,
@@ -1734,6 +1776,9 @@ var CollectionHooks = class {
         this.queryClient.invalidateQueries({
           queryKey: collectionKeys(collection).all
         });
+        if (PRODUCT_DETAIL_INVALIDATING_COLLECTIONS.has(collection)) {
+          this.queryClient.invalidateQueries({ queryKey: ["products", "detail"] });
+        }
         options?.onSuccess?.(data);
       },
       onError: options?.onError,
@@ -1750,6 +1795,9 @@ var CollectionHooks = class {
         this.queryClient.invalidateQueries({
           queryKey: collectionKeys(collection).all
         });
+        if (PRODUCT_DETAIL_INVALIDATING_COLLECTIONS.has(collection)) {
+          this.queryClient.invalidateQueries({ queryKey: ["products", "detail"] });
+        }
         options?.onSuccess?.(data);
       },
       onError: options?.onError,
@@ -1902,7 +1950,7 @@ var CustomerHooks = class {
 
 // src/core/query/query-hooks.ts
 var QueryHooks = class extends CollectionHooks {
-  constructor(queryClient, collectionClient, customerAuth) {
+  constructor(queryClient, collectionClient, customerAuth, commerceClient) {
     super(queryClient, collectionClient);
     // --- Customer hooks delegation ---
     this.useCustomerMe = (...args) => this._customer.useCustomerMe(...args);
@@ -1919,6 +1967,7 @@ var QueryHooks = class extends CollectionHooks {
     this.getCustomerData = () => this._customer.getCustomerData();
     this.setCustomerData = (data) => this._customer.setCustomerData(data);
     this._customer = new CustomerHooks(queryClient, customerAuth);
+    this._commerce = commerceClient;
   }
   useProductListingGroupsQuery(params, options) {
     const queryOptions = params.options;
@@ -2012,6 +2061,21 @@ var QueryHooks = class extends CollectionHooks {
       staleTime: options?.staleTime
     });
   }
+  useProductDetail(params, options) {
+    const discriminator = "slug" in params ? params.slug : params.id;
+    const enabled = options?.enabled !== false && Boolean(discriminator);
+    return (0, import_react_query4.useQuery)({
+      queryKey: productKeys.detail(params),
+      queryFn: () => this._commerce.product.detail(params),
+      enabled
+    });
+  }
+  useProductDetailBySlug(slug, options) {
+    return this.useProductDetail({ slug }, options);
+  }
+  useProductDetailById(id, options) {
+    return this.useProductDetail({ id }, options);
+  }
 };
 
 // src/core/client/client.server.ts
@@ -2062,7 +2126,7 @@ var ServerClient = class {
       onRequestId
     );
     this.queryClient = getQueryClient();
-    this.query = new QueryHooks(this.queryClient, this.collections);
+    this.query = new QueryHooks(this.queryClient, this.collections, void 0, this.commerce);
   }
   getState() {
     return { ...this.state };