@01.software/sdk 0.27.0 → 0.28.0

package/dist/{server-_zvihptw.d.ts → server-C2Q9R-Lu.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-BrSYb-sh.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-BLUb4cYq.js';
+import { P as PublicCollection, d as ServerCollection } from './const-mdQQtIOz.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;
@@ -998,6 +1037,151 @@ type ProductListingGroupsItem = {
 type ProductListingGroupsResponse = {
     docs: ProductListingGroupsItem[];
 };
+type ProductDetailParams = {
+    slug: string;
+} | {
+    id: string;
+};
+interface ProductDetailVariantOptionValue {
+    optionId: string | number;
+    valueId: string | number;
+    value?: string | 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;
+    thumbnail?: unknown | null;
+    images?: unknown[];
+    optionValues: ProductDetailVariantOptionValue[];
+}
+interface ProductDetailOptionValue {
+    id: string | number;
+    value: string;
+    swatchColor?: string | null;
+    thumbnail?: unknown | null;
+}
+interface ProductDetailOption {
+    id: string | number;
+    title: 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?: unknown | null;
+    availableForSale?: boolean | null;
+    selectionHintVariant?: unknown | 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;
+    values: ProductUpsertOptionValueInput[];
+};
+type ProductUpsertVariantInput = {
+    id?: string;
+    optionValues?: Record<string, string> | 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 +1191,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 +1394,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 +1571,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 +1594,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 +1618,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 +1659,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 ServerCommerceClientOptions 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 ProductListingGroup as aA, type ProductListingGroupSummary as aB, type ProductListingGroupsItem as aC, type ProductListingProductShape as aD, type ProductListingProjection as aE, type ProductOptionMatrix as aF, type ProductOptionMatrixOption as aG, type ProductOptionMatrixValue as aH, type ProductOptionMatrixVariant as aI, type ProductOptionShape as aJ, type ProductOptionValueShape as aK, type ProductVariantShape as aL, QueryHooks as aM, type QueryOptions as aN, RateLimitError as aO, type ReadOnlyQueryBuilder as aP, type RequestOptions as aQ, type RetryConfig as aR, type ReturnItem as aS, type ReturnReason as aT, type ReturnWithRefundParams as aU, SDKError as aV, type ServerApiOptions as aW, ServerClient as aX, ServerCollectionClient as aY, ServerCollectionQueryBuilder as aZ, ServerCommerceClient as a_, type DiscountApiOptions as aa, type ExtractArrayType as ab, type GenerateMetadataOptions as ac, GoneError as ad, type InfiniteQueryOptions as ae, ModerationApi as af, type ModerationApiOptions as ag, NetworkError as ah, NotFoundError as ai, OrderApi as aj, type OrderApiOptions as ak, type PaginationMeta as al, type PayloadMutationResponse as am, PermissionError as an, ProductApi as ao, type ProductApiOptions as ap, type ProductDetailBrand as aq, type ProductDetailCategory as ar, type ProductDetailImage as as, type ProductDetailListing as at, type ProductDetailOption as au, type ProductDetailOptionValue as av, type ProductDetailTag as aw, type ProductDetailVariant as ax, type ProductDetailVariantOptionValue as ay, type ProductDetailVideo as az, type StockCheckResponse as b, ServiceUnavailableError as b0, ShippingApi as b1, type ShippingApiOptions as b2, type StockCheckResult as b3, type SuspenseInfiniteQueryOptions as b4, type SuspenseQueryOptions as b5, TimeoutError as b6, type UnbanCustomerParams as b7, type UpdateFulfillmentParams as b8, type UpdateOrderParams as b9, isServiceUnavailableError as bA, isTimeoutError as bB, isUsageLimitError as bC, isValidationError as bD, normalizeSelectedValueIds as bE, resolveApiUrl as bF, resolveVariantForSelection as bG, type UpdateProfileData as ba, type UpdateReturnParams as bb, type UpdateTransactionParams as bc, UsageLimitError as bd, ValidationError as be, buildProductListingGroupsByOption as bf, buildProductListingProjection as bg, buildProductOptionMatrix as bh, createAuthError as bi, createConflictError as bj, createNotFoundError as bk, createPermissionError as bl, createRateLimitError as bm, createServerClient as bn, getAvailableOptionValues as bo, getSelectedValueByOptionId as bp, isApiError as bq, isAuthError as br, isConfigError as bs, isConflictError as bt, isGoneError as bu, isNetworkError as bv, isNotFoundError as bw, isPermissionError as bx, isRateLimitError as by, isSDKError 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-n3xK4Nks.d.cts → server-D369bCVJ.d.cts}

@@ -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.cjs';
+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-BrSYb-sh.cjs';
 import { Sort, Where } from 'payload';
 import { Metadata } from 'next';
-import { C as CollectionType } from './types-DzWNu9pw.cjs';
-import { P as PublicCollection, d as ServerCollection } from './const-C0GlmeJ_.cjs';
+import { C as CollectionType } from './types-CW4PaIL7.cjs';
+import { P as PublicCollection, d as ServerCollection } from './const-Cz9Ki_I7.cjs';
 
 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;
@@ -998,6 +1037,151 @@ type ProductListingGroupsItem = {
 type ProductListingGroupsResponse = {
     docs: ProductListingGroupsItem[];
 };
+type ProductDetailParams = {
+    slug: string;
+} | {
+    id: string;
+};
+interface ProductDetailVariantOptionValue {
+    optionId: string | number;
+    valueId: string | number;
+    value?: string | 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;
+    thumbnail?: unknown | null;
+    images?: unknown[];
+    optionValues: ProductDetailVariantOptionValue[];
+}
+interface ProductDetailOptionValue {
+    id: string | number;
+    value: string;
+    swatchColor?: string | null;
+    thumbnail?: unknown | null;
+}
+interface ProductDetailOption {
+    id: string | number;
+    title: 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?: unknown | null;
+    availableForSale?: boolean | null;
+    selectionHintVariant?: unknown | 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;
+    values: ProductUpsertOptionValueInput[];
+};
+type ProductUpsertVariantInput = {
+    id?: string;
+    optionValues?: Record<string, string> | 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 +1191,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 +1394,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 +1571,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 +1594,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 +1618,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 +1659,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 ServerCommerceClientOptions 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 ProductListingGroup as aA, type ProductListingGroupSummary as aB, type ProductListingGroupsItem as aC, type ProductListingProductShape as aD, type ProductListingProjection as aE, type ProductOptionMatrix as aF, type ProductOptionMatrixOption as aG, type ProductOptionMatrixValue as aH, type ProductOptionMatrixVariant as aI, type ProductOptionShape as aJ, type ProductOptionValueShape as aK, type ProductVariantShape as aL, QueryHooks as aM, type QueryOptions as aN, RateLimitError as aO, type ReadOnlyQueryBuilder as aP, type RequestOptions as aQ, type RetryConfig as aR, type ReturnItem as aS, type ReturnReason as aT, type ReturnWithRefundParams as aU, SDKError as aV, type ServerApiOptions as aW, ServerClient as aX, ServerCollectionClient as aY, ServerCollectionQueryBuilder as aZ, ServerCommerceClient as a_, type DiscountApiOptions as aa, type ExtractArrayType as ab, type GenerateMetadataOptions as ac, GoneError as ad, type InfiniteQueryOptions as ae, ModerationApi as af, type ModerationApiOptions as ag, NetworkError as ah, NotFoundError as ai, OrderApi as aj, type OrderApiOptions as ak, type PaginationMeta as al, type PayloadMutationResponse as am, PermissionError as an, ProductApi as ao, type ProductApiOptions as ap, type ProductDetailBrand as aq, type ProductDetailCategory as ar, type ProductDetailImage as as, type ProductDetailListing as at, type ProductDetailOption as au, type ProductDetailOptionValue as av, type ProductDetailTag as aw, type ProductDetailVariant as ax, type ProductDetailVariantOptionValue as ay, type ProductDetailVideo as az, type StockCheckResponse as b, ServiceUnavailableError as b0, ShippingApi as b1, type ShippingApiOptions as b2, type StockCheckResult as b3, type SuspenseInfiniteQueryOptions as b4, type SuspenseQueryOptions as b5, TimeoutError as b6, type UnbanCustomerParams as b7, type UpdateFulfillmentParams as b8, type UpdateOrderParams as b9, isServiceUnavailableError as bA, isTimeoutError as bB, isUsageLimitError as bC, isValidationError as bD, normalizeSelectedValueIds as bE, resolveApiUrl as bF, resolveVariantForSelection as bG, type UpdateProfileData as ba, type UpdateReturnParams as bb, type UpdateTransactionParams as bc, UsageLimitError as bd, ValidationError as be, buildProductListingGroupsByOption as bf, buildProductListingProjection as bg, buildProductOptionMatrix as bh, createAuthError as bi, createConflictError as bj, createNotFoundError as bk, createPermissionError as bl, createRateLimitError as bm, createServerClient as bn, getAvailableOptionValues as bo, getSelectedValueByOptionId as bp, isApiError as bq, isAuthError as br, isConfigError as bs, isConflictError as bt, isGoneError as bu, isNetworkError as bv, isNotFoundError as bw, isPermissionError as bx, isRateLimitError as by, isSDKError 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 };