@01.software/sdk 0.37.0 → 0.39.0

package/dist/{types-BWMUr3Zw.d.cts → types-CVf8sCZ-.d.ts}

@@ -1,6 +1,6 @@
-import { P as PublicCollection, S as ServerCollection } from './const-CK_FPaIn.cjs';
-import { C as CollectionType, P as PublicProduct } from './types-BkZNhuBh.cjs';
-import { O as Order, i as Cart, j as CartItem, m as Transaction, n as Fulfillment, o as Return } from './payload-types-CREOjFNT.cjs';
+import { P as PublicCollection, S as ServerCollection } from './const-6XHz_jej.js';
+import { C as CollectionType, P as PublicProduct } from './types-Cmrd1ezc.js';
+import { O as Order, l as Transaction, m as Fulfillment, R as Return } from './payload-types-m3jjhxk9.js';
 
 interface CustomerScopedApiOptions {
     publishableKey?: string;
@@ -27,6 +27,10 @@ declare class CustomerScopedApi {
     protected request<T>(endpoint: string, options: CustomerScopedRequestOptions): Promise<T>;
 }
 
+type RawCommunityPost = CollectionType<'posts'>;
+type RawCommunityComment = CollectionType<'comments'>;
+type RawCommunityReaction = CollectionType<'reactions'>;
+type RawCommunityBookmark = CollectionType<'bookmarks'>;
 interface CommunityClientOptions {
     publishableKey?: string;
     secretKey?: string;
@@ -35,10 +39,82 @@ interface CommunityClientOptions {
     onUnauthorized?: () => Promise<string | null>;
     onRequestId?: (id: string | null) => void;
 }
-/** Public read shape for `posts` (tenant-scoped author profiles). */
-type CommunityPost = CollectionType<'posts'>;
-/** Public read shape for `comments`. */
-type CommunityComment = CollectionType<'comments'>;
+type CommunityPublicMediaAsset = string | {
+    id?: string | number | null;
+    alt?: string | null;
+    width?: number | null;
+    height?: number | null;
+    mimeType?: string | null;
+    filename?: string | null;
+    url?: string | null;
+    sizes?: Record<string, {
+        width?: number | null;
+        height?: number | null;
+        mimeType?: string | null;
+        filename?: string | null;
+        url?: string | null;
+    }> | null;
+};
+type CommunityPublicReference = string | {
+    id?: string | number | null;
+    title?: string | null;
+    name?: string | null;
+    slug?: string | null;
+    displayName?: string | null;
+    handle?: string | null;
+    color?: string | null;
+    image?: CommunityPublicMediaAsset | null;
+    thumbnail?: CommunityPublicMediaAsset | null;
+    avatar?: CommunityPublicMediaAsset | null;
+};
+interface CommunityPublicAuthorSnapshot {
+    displayName?: string | null;
+    handle?: string | null;
+    avatarUrl?: string | null;
+    avatar?: CommunityPublicMediaAsset | null;
+}
+/** Public read shape for projected community post endpoints. */
+interface CommunityPost {
+    id: RawCommunityPost['id'];
+    title?: RawCommunityPost['title'];
+    slug?: RawCommunityPost['slug'];
+    content?: RawCommunityPost['content'];
+    status?: RawCommunityPost['status'];
+    thumbnail?: CommunityPublicMediaAsset | null;
+    categories?: CommunityPublicReference[] | null;
+    tags?: CommunityPublicReference[] | null;
+    authorProfile?: CommunityPublicReference | null;
+    authorSnapshot?: CommunityPublicAuthorSnapshot | null;
+    viewCount?: RawCommunityPost['viewCount'];
+    commentCount?: RawCommunityPost['commentCount'];
+    reactionCount?: RawCommunityPost['reactionCount'];
+    isPinned?: RawCommunityPost['isPinned'];
+    allowsComments?: RawCommunityPost['allowsComments'];
+    isEdited?: RawCommunityPost['isEdited'];
+    editedAt?: RawCommunityPost['editedAt'];
+    lastActivityAt?: RawCommunityPost['lastActivityAt'];
+    publishedAt?: RawCommunityPost['publishedAt'];
+    createdAt: RawCommunityPost['createdAt'];
+    updatedAt: RawCommunityPost['updatedAt'];
+}
+/** Public read shape for projected community comment endpoints. */
+interface CommunityComment {
+    id: RawCommunityComment['id'];
+    body?: RawCommunityComment['body'];
+    post?: CommunityPublicReference | null;
+    parent?: CommunityPublicReference | null;
+    rootComment?: CommunityPublicReference | null;
+    authorProfile?: CommunityPublicReference | null;
+    authorSnapshot?: CommunityPublicAuthorSnapshot | null;
+    depth?: RawCommunityComment['depth'];
+    status?: RawCommunityComment['status'];
+    reactionCount?: RawCommunityComment['reactionCount'];
+    replyCount?: RawCommunityComment['replyCount'];
+    isEdited?: RawCommunityComment['isEdited'];
+    editedAt?: RawCommunityComment['editedAt'];
+    createdAt: RawCommunityComment['createdAt'];
+    updatedAt: RawCommunityComment['updatedAt'];
+}
 /** @deprecated Use {@link CommunityComment}. */
 type Comment = CommunityComment;
 /** Public read shape for `post-categories`. */
@@ -49,10 +125,11 @@ type CommunityPostListSort = 'createdAt' | '-createdAt' | 'lastActivityAt' | '-l
 type CommunityCommentListSort = 'createdAt' | '-createdAt';
 interface Reaction {
     id: string;
-    post?: string;
-    comment?: string;
-    type?: string;
+    post?: CommunityPublicReference | null;
+    comment?: CommunityPublicReference | null;
+    type?: CommunityPublicReference | null;
     createdAt?: string;
+    updatedAt?: string;
     [key: string]: unknown;
 }
 interface ReactionSummary {
@@ -62,8 +139,9 @@ interface ReactionSummary {
 }
 interface Bookmark {
     id: string;
-    post?: string;
+    post?: string | CommunityPost | null;
     createdAt?: string;
+    updatedAt?: string;
     [key: string]: unknown;
 }
 interface ReactionType {
@@ -85,6 +163,10 @@ interface PaginatedResponse<T> {
     prevPage: number | null;
     nextPage: number | null;
 }
+type CommunityPostMutationResponse = CommunityPost | RawCommunityPost;
+type CommunityCommentMutationResponse = CommunityComment | RawCommunityComment;
+type CommunityReactionMutationResponse = Reaction | RawCommunityReaction;
+type CommunityBookmarkMutationResponse = Bookmark | RawCommunityBookmark;
 declare class CommunityClient extends CustomerScopedApi {
     constructor(options: CommunityClientOptions);
     private buildQuery;
@@ -97,7 +179,7 @@ declare class CommunityClient extends CustomerScopedApi {
         content?: unknown;
         categories?: string[];
         thumbnail?: string;
-    }): Promise<CommunityPost>;
+    }): Promise<CommunityPostMutationResponse>;
     /**
      * Public post feed. Server applies the same visibility contract as
      * `communityPostRead` (published + visible + moderation-safe).
@@ -143,7 +225,7 @@ declare class CommunityClient extends CustomerScopedApi {
         postId: string;
         body: string;
         parentId?: string;
-    }): Promise<CommunityComment>;
+    }): Promise<CommunityCommentMutationResponse>;
     /**
      * List comments for a post.
      *
@@ -169,12 +251,10 @@ declare class CommunityClient extends CustomerScopedApi {
     updateComment(params: {
         commentId: string;
         body: string;
-    }): Promise<CommunityComment>;
+    }): Promise<CommunityCommentMutationResponse>;
     deleteComment(params: {
         commentId: string;
-    }): Promise<{
-        success: boolean;
-    }>;
+    }): Promise<CommunityCommentMutationResponse>;
     reportComment(params: {
         commentId: string;
         reason?: string;
@@ -187,7 +267,7 @@ declare class CommunityClient extends CustomerScopedApi {
         typeSlug?: string;
         /** @deprecated Use `typeSlug`. */
         type?: string;
-    }): Promise<Reaction>;
+    }): Promise<CommunityReactionMutationResponse>;
     removeReaction(params: {
         postId: string;
         type: string;
@@ -199,7 +279,7 @@ declare class CommunityClient extends CustomerScopedApi {
         typeSlug?: string;
         /** @deprecated Use `typeSlug`. */
         type?: string;
-    }): Promise<Reaction>;
+    }): Promise<CommunityReactionMutationResponse>;
     removeCommentReaction(params: {
         commentId: string;
         type: string;
@@ -215,7 +295,7 @@ declare class CommunityClient extends CustomerScopedApi {
     getReactionTypes(): Promise<PaginatedResponse<ReactionType>>;
     addBookmark(params: {
         postId: string;
-    }): Promise<Bookmark>;
+    }): Promise<CommunityBookmarkMutationResponse>;
     removeBookmark(params: {
         postId: string;
     }): Promise<{
@@ -290,1304 +370,1515 @@ declare class ModerationApi extends BaseApi {
     }>;
 }
 
-interface CustomerAuthResponse {
-    token: string;
-    customer: CustomerProfile;
-}
-interface MarketingConsentChannel {
-    isConsented?: boolean;
-}
-interface MarketingConsent {
-    email?: MarketingConsentChannel;
-    sms?: MarketingConsentChannel;
-    push?: MarketingConsentChannel;
-    consentSource?: string;
-}
-interface CustomerProfile {
-    id: string;
-    name: string;
-    email?: string | null;
-    phone?: string | null;
-    authProvider?: 'local' | 'google' | 'apple' | 'kakao' | 'naver' | null;
-    isGuest?: boolean | null;
-    marketingConsent?: MarketingConsent | null;
-    metadata?: Record<string, unknown> | null;
-    groups?: string[];
-}
-interface CustomerRegisterData {
-    name: string;
-    email: string;
-    password: string;
-    phone?: string;
-}
-interface CustomerRegisterResponse {
-    customer: CustomerProfile;
-}
-interface CustomerLoginData {
-    email: string;
-    password: string;
-}
-interface CustomerRefreshResponse {
-    token: string;
-}
-interface UpdateProfileData {
-    name?: string;
-    phone?: string;
-    marketingConsent?: MarketingConsent;
-}
-interface CustomerAuthOptions {
-    /**
-     * Persist token in localStorage. Defaults to `true`.
-     * - `true` (default): uses key `'customer-token'`
-     * - `string`: uses the given string as localStorage key
-     * - `false`: disables persistence (token/onTokenChange used instead)
-     *
-     * Handles SSR safely (no-op on server).
-     * When enabled, `token` and `onTokenChange` are ignored.
-     */
-    persist?: boolean | string;
-    /** Initial token (e.g. from SSR cookie) */
-    token?: string;
-    /** Called when token changes (login/logout) — use to persist in localStorage/cookie */
-    onTokenChange?: (token: string | null) => void;
-}
+type PublicMediaSize = {
+    width?: number | null;
+    height?: number | null;
+    mimeType?: string | null;
+    filename?: string | null;
+    url?: string | null;
+};
+type PublicMediaAsset = string | {
+    id?: string | number | null;
+    alt?: string | null;
+    width?: number | null;
+    height?: number | null;
+    mimeType?: string | null;
+    filename?: string | null;
+    url?: string | null;
+    sizes?: Record<string, PublicMediaSize>;
+};
 
-/**
- * Customer authentication client.
- *
- * Manages customer registration, login, logout, and token lifecycle.
- * All requests include X-Publishable-Key for tenant resolution.
- */
-declare class CustomerAuth {
-    private publishableKey;
-    private baseUrl;
-    private token;
-    private onTokenChange?;
-    private refreshPromise;
-    constructor(publishableKey: string, options?: CustomerAuthOptions, apiUrl?: string);
-    /**
-     * Register a new customer account
-     */
-    register(data: CustomerRegisterData): Promise<CustomerRegisterResponse>;
-    /**
-     * Login with email and password. Stores the token internally.
-     */
-    login(data: CustomerLoginData): Promise<CustomerAuthResponse>;
-    /**
-     * Refresh the current token. Requires a valid (non-expired) token.
-     */
-    refreshToken(): Promise<CustomerRefreshResponse>;
-    private _doRefreshToken;
-    /**
-     * Clear the stored token
-     */
-    logout(): void;
-    /**
-     * Get the current authenticated customer's profile
-     */
-    me(): Promise<CustomerProfile | null>;
-    /**
-     * Request a password reset email
-     */
-    forgotPassword(email: string): Promise<void>;
-    /**
-     * Reset password using a token from the reset email
-     */
-    resetPassword(token: string, password: string): Promise<void>;
+type OrderApiOptions = ServerApiOptions;
+/** Header-only; never sent in the JSON body. */
+type WithIdempotencyKey<T> = T & {
     /**
-     * Update the authenticated customer's profile (name, phone, marketingConsent)
+     * Client-generated key for safe retries. Sent as `X-Idempotency-Key` when the
+     * server endpoint supports HTTP idempotency.
      */
-    updateProfile(data: UpdateProfileData): Promise<CustomerProfile>;
+    idempotencyKey?: string;
+};
+type CustomerSnapshot = {
+    name?: string;
+    email: string;
+    phone?: string;
+};
+type PublicOrderReference = string | {
+    id?: string | number | null;
+    title?: string | null;
+    name?: string | null;
+    slug?: string | null;
+    displayName?: string | null;
+    handle?: string | null;
+    color?: string | null;
+    image?: PublicMediaAsset | null;
+    thumbnail?: PublicMediaAsset | null;
+    avatar?: PublicMediaAsset | null;
+};
+type PublicOrderItem = {
+    id?: string | number;
+    product?: PublicOrderReference;
+    variant?: PublicOrderReference;
+    productTitle?: string | null;
+    variantTitle?: string | null;
+    sku?: string | null;
+    quantity?: number | null;
+    unitPrice?: number | null;
+    discountedUnitPrice?: number | null;
+    totalPrice?: number | null;
+    options?: unknown;
+    createdAt?: string | null;
+    updatedAt?: string | null;
+    image?: PublicMediaAsset | null;
+};
+type PublicOrder = {
+    id?: string | number;
+    orderNumber?: string | null;
+    status?: string | null;
+    displayStatus?: string | null;
+    primaryDisplayStatus?: string | null;
+    displayFinancialStatus?: string | null;
+    displayFulfillmentStatus?: string | null;
+    returnDisplayStatus?: string | null;
+    totalAmount?: number | null;
+    subtotalAmount?: number | null;
+    shippingAmount?: number | null;
+    discountAmount?: number | null;
+    taxAmount?: number | null;
+    refundedAmount?: number | null;
+    currency?: string | null;
+    customerNote?: string | null;
+    createdAt?: string | null;
+    updatedAt?: string | null;
+    customerSnapshot?: {
+        name?: string | null;
+        email?: string | null;
+        phone?: string | null;
+    };
+    shippingAddress?: {
+        recipientName?: string | null;
+        phone?: string | null;
+        postalCode?: string | null;
+        address1?: string | null;
+        address2?: string | null;
+        jibunAddress?: string | null;
+        administrativeArea?: string | null;
+        city?: string | null;
+        province?: string | null;
+        country?: string | null;
+        deliveryMemo?: string | null;
+        address?: string | null;
+        detailAddress?: string | null;
+        deliveryMessage?: string | null;
+    };
+    items?: PublicOrderItem[];
+};
+type ReturnReason = 'change_of_mind' | 'defective' | 'wrong_delivery' | 'damaged' | 'other';
+type ReturnItem = {
+    orderItem: string | number;
+    quantity: number;
+    restockAction?: RestockAction;
+    restockingFee?: number;
+};
+type OrderCreateEntityID = string | number;
+type CreateOrderItem = {
     /**
-     * Change the password of the currently authenticated customer
+     * Compatibility input: the create-order endpoint derives the line's product
+     * from the variant's parent server-side; storefront items may omit this.
      */
-    changePassword(currentPassword: string, newPassword: string): Promise<void>;
+    product?: OrderCreateEntityID;
+    variant: OrderCreateEntityID;
     /**
-     * Get the authenticated customer's orders with pagination and optional status filter
+     * Compatibility input: accepted but unused by the create-order endpoint;
+     * option selection is snapshotted server-side from the variant.
      */
-    getMyOrders(options?: {
-        page?: number;
-        limit?: number;
-        status?: string;
-    }): Promise<PayloadFindResponse<Order>>;
+    option?: OrderCreateEntityID;
+    quantity: number;
     /**
-     * Get the current token (or null if not authenticated)
+     * Compatibility input: the create-order endpoint accepts this, but the server
+     * derives authoritative line pricing from the product variant.
      */
-    getToken(): string | null;
+    unitPrice?: number;
     /**
-     * Set the token manually (e.g. from SSR)
+     * Compatibility input: the create-order endpoint accepts this, but the server
+     * derives authoritative line totals from the product variant.
      */
-    setToken(token: string | null): void;
+    totalPrice?: number;
+};
+type CreateOrderLineItemsInput = {
+    orderItems: CreateOrderItem[];
+    items?: never;
+} | {
     /**
-     * Check if the customer is currently authenticated
+     * Storefront-facing alias for orderItems. The SDK serializes this to
+     * orderItems for the existing create-order endpoint.
      */
-    isAuthenticated(): boolean;
+    items: CreateOrderItem[];
     /**
-     * Internal: make a request with timeout and error handling.
-     * Auth endpoints don't retry — failures are final.
+     * @deprecated Use items for storefront-facing create-order inputs.
      */
-    private requestJson;
-}
-
-interface CartApiOptions {
-    publishableKey?: string;
-    secretKey?: string;
-    apiUrl?: string;
-    customerToken?: string | (() => string | null);
-    onUnauthorized?: () => Promise<string | null>;
-    onRequestId?: (id: string | null) => void;
-}
-type AddItemParams = {
-    cartId: string;
-    product: string;
-    variant: string;
-    option: string;
-    quantity: number;
-};
-type UpdateItemParams = {
-    cartItemId: string;
-    quantity: number;
-};
-type RemoveItemParams = {
-    cartItemId: string;
+    orderItems?: never;
 };
-type ApplyDiscountParams = {
-    cartId: string;
-    discountCode: string;
+type CreateOrderBodyBase = {
+    orderNumber: string;
+    customer?: string;
+    customerSnapshot: CustomerSnapshot;
+    shippingAddress: Order['shippingAddress'];
+    totalAmount: number;
+    shippingAmount?: number;
+    pgPaymentId?: string;
+    discountCode?: string;
 };
-type RemoveDiscountParams = {
-    cartId: string;
+type CreateOrderParams = WithIdempotencyKey<CreateOrderBodyBase & CreateOrderLineItemsInput>;
+type UpdateOrderParams = {
+    orderNumber: string;
+    status: 'confirmed';
 };
-type ClearCartParams = {
-    cartId: string;
+type TransactionStatus = 'pending' | 'paid' | 'failed' | 'canceled';
+type UpdateTransactionParams = {
+    pgPaymentId: string;
+    status: TransactionStatus;
+    paymentMethod?: string;
+    receiptUrl?: string;
+    paymentKey?: string;
+    amount?: number;
 };
-declare class CartApi extends CustomerScopedApi {
-    constructor(options: CartApiOptions);
-    private execute;
-    getCart(cartId: string): Promise<Cart>;
-    addItem(params: AddItemParams): Promise<CartItem>;
-    updateItem(params: UpdateItemParams): Promise<CartItem>;
-    removeItem(params: RemoveItemParams): Promise<{
-        success: boolean;
-    }>;
-    applyDiscount(params: ApplyDiscountParams): Promise<Cart>;
-    removeDiscount(params: RemoveDiscountParams): Promise<Cart>;
-    clearCart(params: ClearCartParams): Promise<{
-        success: boolean;
-    }>;
-}
-
-type NormalizedOptionSwatch<TMedia = unknown> = {
-    type: 'color' | 'media' | null;
-    color?: string | null;
-    mediaItemId?: string | number | null;
-    /** Inlined swatch media when the API populated mediaItemId before pool indexing. */
-    inlineMedia?: TMedia | null;
+type ConfirmPaymentParams = WithIdempotencyKey<{
+    orderNumber?: string;
+    pgPaymentId: string;
+    pgProvider: string;
+    pgOrderId?: string;
+    amount: number;
+    currency?: string;
+    paymentMethod?: string;
+    receiptUrl?: string;
+    approvedAt?: string;
+    providerStatus?: string;
+    /** Provider event id; also used as idempotency key when `idempotencyKey` is omitted. */
+    providerEventId?: string;
+    paymentKey?: string;
+    confirmationSource?: 'provider_webhook' | 'provider_lookup' | 'provider_api_confirm' | 'manual_server';
+    metadata?: Record<string, unknown>;
+}>;
+type ConfirmPaymentResponse = {
+    orderId: string;
+    transactionId: string;
+    status: 'paid';
+    alreadyConfirmed?: boolean;
 };
-declare function selectedSwatchMediaItemId(swatch: NormalizedOptionSwatch | null | undefined): string | null;
-type ProductSelectionMediaSource = 'variant_media_selected' | 'variant_media_matching' | 'option_swatch' | 'none';
-type ProductDisplayMediaSource = 'listing_primary' | 'product_primary' | 'product_pool' | 'none';
-/** @deprecated Use {@link ProductSelectionMediaSource} or {@link ProductDisplayMediaSource}. */
-type ProductMediaResolutionSource = ProductSelectionMediaSource | ProductDisplayMediaSource;
-type ProductSelectionVariant<TMedia> = {
-    id?: string | number | null;
-    images?: Array<TMedia | string | number | null | undefined> | null;
+type CancelReasonCode = 'customer' | 'inventory' | 'fraud' | 'declined' | 'staff' | 'other';
+type CancelOrderStatus = 'pending' | 'paid' | 'canceled' | 'refunded' | 'preparing' | 'shipped' | 'delivered' | 'confirmed' | 'return_requested' | 'return_processing' | 'returned';
+type CancelOrderReconciliationStatus = Exclude<CancelOrderStatus, 'pending' | 'canceled'>;
+type CancelOrderResponseBase = {
+    orderId: string;
 };
-type ProductSelectionOptionValue = {
-    id?: string | number | null;
-    swatch?: NormalizedOptionSwatch<unknown> | null;
+type CancelOrderUnpaidCommittedResponseFields = {
+    refundedAmount: 0;
+    providerRefunded: false;
 };
-type ProductSelectionMediaPointer = string | number | {
-    id?: string | number | null;
-} | null;
-type ResolveProductSelectionMediaInput<TMedia> = {
-    productMediaPool?: TMedia[] | null;
-    productPrimaryMediaItemId?: ProductSelectionMediaPointer;
-    selectedVariant?: ProductSelectionVariant<TMedia> | null;
-    matchingVariants?: Array<ProductSelectionVariant<TMedia> | null | undefined> | null;
-    selectedOptionValues?: Array<ProductSelectionOptionValue | null | undefined> | null;
+type CancelOrderPaidCommittedResponseFields = {
+    transactionId: string;
+    refundedAmount: 0;
+    providerRefunded: false;
+    refundPending: true;
 };
-type ResolveProductSelectionMediaResult<TMedia> = {
-    primaryImage: TMedia | null;
-    images: TMedia[];
-    source: ProductSelectionMediaSource;
+type CancelOrderLegacyProviderRefundResponseFields = {
+    transactionId: string;
+    refundedAmount: number;
+    refundSeq: number;
+    providerRefunded: true;
 };
-type ResolveProductDisplayMediaInput<TMedia> = {
-    productMediaPool?: TMedia[] | null;
-    productPrimaryMediaItemId?: ProductSelectionMediaPointer;
-    listingPrimaryImage?: ProductSelectionMediaPointer;
+type CancelOrderAlreadyCanceledResponseFields = {
+    refundedAmount: number;
+    providerRefunded: false;
 };
-type ResolveProductDisplayMediaResult<TMedia> = {
-    primaryImage: TMedia | null;
-    images: TMedia[];
-    source: ProductDisplayMediaSource;
+type CancelOrderAlreadyCanceledRefundPendingResponseFields = {
+    transactionId: string;
+    refundedAmount: number;
+    providerRefunded: false;
+    refundPending: true;
 };
-declare function resolveProductSelectionMedia<TMedia>(input: ResolveProductSelectionMediaInput<TMedia>): ResolveProductSelectionMediaResult<TMedia>;
-declare function resolveProductDisplayMedia<TMedia>(input: ResolveProductDisplayMediaInput<TMedia>): ResolveProductDisplayMediaResult<TMedia>;
-type ListingPrimaryImageFallbackInput<TMedia> = {
-    productMediaPool?: TMedia[] | null;
-    productPrimaryMediaItemId?: ProductSelectionMediaPointer;
-    productThumbnail?: TMedia | string | number | null;
-    listingPrimaryImage?: TMedia | string | number | null;
-    resolvedPrimary?: TMedia | null;
-    resolvedSource?: ProductMediaResolutionSource;
+type CancelOrderPaidCommittedResponse = CancelOrderResponseBase & CancelOrderPaidCommittedResponseFields & {
+    status: 'canceled';
+    cancelCommitted: true;
 };
-declare function resolveListingPrimaryImagePointer<TMedia>(input: ListingPrimaryImageFallbackInput<TMedia>): string | null;
-
-type EntityID = string;
-type RelationshipValue = string | number | null | undefined | {
-    id?: string | number | null;
+type CancelOrderUnpaidCommittedResponse = CancelOrderResponseBase & CancelOrderUnpaidCommittedResponseFields & {
+    status: 'canceled';
+    cancelCommitted: true;
 };
-type MediaValue = ProductDetailMedia | null | undefined;
-
-/** Raw Payload / REST swatch before strict public normalization. */
-type ProductOptionValueSwatchInput = {
-    type?: 'color' | 'media' | null;
-    color?: string | null;
-    mediaItemId?: RelationshipValue;
+type CancelOrderCommittedResponse = CancelOrderPaidCommittedResponse | CancelOrderUnpaidCommittedResponse;
+type CancelOrderAlreadyCanceledResponse = CancelOrderResponseBase & CancelOrderAlreadyCanceledResponseFields & {
+    status: 'canceled';
+    cancelCommitted: false;
+    alreadyCanceled: true;
 };
-interface ProductOptionValueShape {
-    id?: string | number | null;
-    option?: RelationshipValue;
-    value?: string | null;
-    slug?: string | null;
-    swatch?: ProductOptionValueSwatch | ProductOptionValueSwatchInput | null;
-    _order?: string | null;
-    '_product-option-values_values_order'?: string | null;
-}
-interface ProductOptionShape {
-    id?: string | number | null;
-    title?: string | null;
-    slug?: string | null;
-    _order?: string | null;
-    '_product-options_options_order'?: string | null;
-    values?: {
-        docs?: unknown[];
-    } | null;
-}
-interface ProductVariantShape {
-    id?: string | number | null;
-    optionValues?: unknown[] | null;
-    price?: number | null;
-    compareAtPrice?: number | null;
-    stock?: number | null;
-    reservedStock?: number | null;
-    isUnlimited?: boolean | null;
-    isActive?: boolean | null;
-    thumbnail?: MediaValue;
-    images?: MediaValue[] | null;
-    _order?: string | null;
-}
-interface ProductListingProductShape {
-    id?: EntityID;
-    thumbnail?: MediaValue;
-    primaryMediaItemId?: MediaValue;
-    images?: MediaValue[] | null;
-    listing?: {
-        primaryImage?: MediaValue;
-    } | null;
-}
-type ProductOptionMatrixValue = {
-    id: string;
-    optionId: string;
-    optionSlug: string;
-    label: string;
-    slug: string | null;
-    swatch: ProductOptionValueSwatch;
-    order: string;
+type CancelOrderAlreadyCanceledRefundPendingResponse = CancelOrderResponseBase & CancelOrderAlreadyCanceledRefundPendingResponseFields & {
+    status: 'canceled';
+    cancelCommitted: false;
+    alreadyCanceled: true;
 };
-type ProductOptionMatrixOption = {
-    id: string;
-    title: string;
-    slug: string;
-    order: string;
-    values: ProductOptionMatrixValue[];
+/** @deprecated Inline PG cancel reconciliation; retained for legacy API consumers. */
+type CancelOrderReconciliationResponse = CancelOrderResponseBase & CancelOrderLegacyProviderRefundResponseFields & {
+    status: CancelOrderReconciliationStatus;
+    cancelCommitted: false;
+    reconciliationRequired: true;
 };
-type ProductOptionMatrixVariant<TVariant extends ProductVariantShape = ProductVariantShape> = {
-    id: string;
-    optionValueIds: string[];
-    optionValueByOptionId: Map<string, string>;
-    optionValueByOptionSlug: Map<string, string>;
-    source: TVariant;
+type CancelOrderResponse = CancelOrderCommittedResponse | CancelOrderAlreadyCanceledResponse | CancelOrderAlreadyCanceledRefundPendingResponse | CancelOrderReconciliationResponse;
+type CancelOrderParams = {
+    orderNumber: string;
+    reasonCode?: CancelReasonCode;
+    reasonDetail?: string;
+    idempotencyKey?: string;
 };
-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 ResolveCancelRefundOutcome = 'succeeded' | 'failed';
+type ResolveCancelRefundSucceededParams = {
+    orderNumber: string;
+    idempotencyKey: string;
+    outcome: 'succeeded';
+    refundedAmount: number;
+    pgProvider: string;
+    pgRefundId: string;
 };
-type ProductListingProjection = {
-    selectionHintVariant: EntityID | null;
-    primaryImage: EntityID | null;
-    minPrice: number | null;
-    maxPrice: number | null;
-    minCompareAtPrice: number | null;
-    maxCompareAtPrice: number | null;
-    isPriceRange: boolean;
-    availableForSale: boolean;
+type ResolveCancelRefundFailedParams = {
+    orderNumber: string;
+    idempotencyKey: string;
+    outcome: 'failed';
+    refundedAmount: 0;
+    pgProvider: string;
+    pgRefundId?: string;
 };
-type ProductListingGroup<TVariant extends ProductVariantShape = ProductVariantShape> = {
-    optionId: EntityID;
-    optionTitle: string;
-    optionSlug: string;
-    optionValueId: EntityID;
-    optionValueLabel: string;
-    optionValueSlug: string | null;
-    optionValueSwatch: ProductOptionValueSwatch;
-    variantIds: EntityID[];
-    variantCount: number;
-    variants: TVariant[];
-    listing: ProductListingProjection;
+type ResolveCancelRefundParams = ResolveCancelRefundSucceededParams | ResolveCancelRefundFailedParams;
+type ResolveCancelRefundSucceededResponse = {
+    orderId: string;
+    transactionId: string;
+    refundTransactionId: string;
+    refundedAmount: number;
+    refundStatus: 'succeeded';
+    transactionStatus: 'refunded';
 };
-type ProductListingCardPriceRange = {
-    minPrice: number | null;
-    maxPrice: number | null;
-    minCompareAtPrice: number | null;
-    maxCompareAtPrice: number | null;
-    isPriceRange: boolean;
-};
-type ProductListingSwatch = {
-    optionId: EntityID;
-    optionValueId: EntityID;
-    label: string;
-    swatch: ProductOptionValueSwatch<ProductDetailMedia>;
-    href: string;
-    availableForSale: boolean;
-};
-type ProductListingCardRepresentativeVariant = ProductListingGroupsItem['groups'][number]['variants'][number];
-type ProductListingCard = {
-    id: EntityID;
-    href: string;
-    title: string;
-    representativeVariant?: ProductListingCardRepresentativeVariant | null;
-    primaryImage: ProductDetailMedia | null;
-    priceRange: ProductListingCardPriceRange;
-    availableForSale: boolean;
-    swatches: ProductListingSwatch[];
-};
-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 CompatibilityProductSelectionParamEvent = {
-    optionId: string;
-    optionSlug: string;
-    valueSlug: string;
-    searchParam: string;
+type ResolveCancelRefundFailedResponse = {
+    orderId: string;
+    transactionId: string;
+    refundTransactionId: string;
+    refundedAmount: 0;
+    refundStatus: 'failed';
+    transactionStatus: 'paid';
 };
-type LegacyProductSelectionParamEvent = CompatibilityProductSelectionParamEvent;
-type ProductSelectionUrlEmit = 'slug-compat' | 'canonical-id';
-type ProductSelectionCodecOptions = {
-    emit?: ProductSelectionUrlEmit;
-    /**
-     * When true, `resolveProductSelection()` fills unselected options to reach a
-     * concrete variant. Does not change codec parse/stringify behavior.
-     */
-    fillDefaults?: boolean;
-    onCompatibilityOptionIdParam?: (event: CompatibilityProductSelectionParamEvent) => void;
-    onLegacyOptionIdParam?: (event: LegacyProductSelectionParamEvent) => void;
+type ResolveCancelRefundResponse = ResolveCancelRefundSucceededResponse | ResolveCancelRefundFailedResponse;
+type RestockAction = 'return_to_stock' | 'discard';
+type ReturnWithRefundItem = {
+    orderItem: string | number;
+    quantity: number;
+    restockAction?: RestockAction;
+    restockingFee?: number;
 };
-type ProductSelectionResolutionContext = {
-    detail?: Pick<ProductDetail, 'images' | 'listing' | 'primaryMediaItemId'>;
-    images?: ProductDetail['images'];
-    listing?: ProductDetail['listing'];
-    primaryMediaItemId?: ProductDetail['primaryMediaItemId'];
+type ReturnWithRefundParams = WithIdempotencyKey<{
+    orderNumber: string;
+    reason?: ReturnReason;
+    reasonDetail?: string;
+    returnItems: ReturnWithRefundItem[];
+    refundAmount: number;
+    returnShippingFee?: number;
+    initialShippingRefundAmount?: number;
+    initialShippingRefundOverrideNote?: string;
+    pgPaymentId: string;
+    paymentKey?: string;
+    refundReceiptUrl?: string;
+}>;
+type CheckoutParams = WithIdempotencyKey<{
+    cartId: string;
+    orderNumber: string;
+    customerSnapshot: CustomerSnapshot;
+    pgPaymentId?: string;
+    discountCode?: string;
+}>;
+type CreateFulfillmentParams = WithIdempotencyKey<{
+    orderNumber: string;
+    fulfillmentOrderId?: string | number;
+    carrier?: string;
+    trackingNumber?: string;
+    items?: Array<{
+        orderItem: string;
+        quantity: number;
+    }>;
+}>;
+type PrepareFulfillmentOrderParams = {
+    orderNumber: string;
 };
-type ProductSelectionAvailableSwatch = {
-    color?: string | null;
-    image?: MediaValue | null;
+type PrepareFulfillmentOrderResponse = {
+    orderId: string;
+    fulfillmentOrders: Array<{
+        id: string;
+        status: string;
+    }>;
 };
-type ProductSelectionAvailableValue = {
-    valueId: string;
-    value: string;
-    label: string;
-    slug: string;
-    selected: boolean;
-    available: boolean;
-    exists: boolean;
-    availableForSale: boolean;
-    isUnlimited: boolean;
-    availableStock: number | null;
-    swatch: ProductOptionValueSwatch;
+type UpdateFulfillmentParams = {
+    fulfillmentId: string;
+    status?: 'shipped' | 'delivered' | 'failed';
+    carrier?: string;
+    trackingNumber?: string;
 };
-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[];
-        source?: ProductMediaResolutionSource;
-    };
-    stock: {
-        availableForSale: boolean;
-        isUnlimited: boolean;
-        stock: number | null;
-        reservedStock: number | null;
-        availableStock: number | null;
-    };
+type BulkImportFulfillmentsParams = {
+    items: Array<{
+        orderNumber: string;
+        carrier: string;
+        trackingNumber: string;
+    }>;
 };
-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 normalizeProductSelectionFromMatrix(matrix: ProductOptionMatrix<ProductDetailVariant>, 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;
+type BulkImportFulfillmentsResponse = {
+    succeeded: Array<{
+        orderNumber: string;
+        fulfillmentId: string;
+    }>;
+    failed: Array<{
+        orderNumber: string;
+        error: string;
+    }>;
 };
-declare function resolveProductSelectionFromMatrix(matrix: ProductOptionMatrix<ProductDetailVariant>, selection?: ProductSelectionInput, options?: ProductSelectionCodecOptions, context?: ProductSelectionResolutionContext): ProductSelectionResolution;
-declare function resolveProductSelection(detail: ProductDetail, selection?: ProductSelectionInput, options?: ProductSelectionCodecOptions): ProductSelectionResolution;
-declare function selectNext(detail: ProductDetail, current: ProductSelectionInput | undefined, optionSlug: string, valueSlug: string, options?: ProductSelectionCodecOptions): NormalizedProductSelection;
-type ProductDetailImageMedia = Extract<ProductDetailMedia, {
-    id?: string | number | null;
-    url?: string | null;
+type CreateReturnParams = WithIdempotencyKey<{
+    orderNumber: string;
+    reason?: ReturnReason;
+    reasonDetail?: string;
+    returnItems: ReturnItem[];
+    refundAmount: number;
+    returnShippingFee?: number;
+    initialShippingRefundAmount?: number;
+    initialShippingRefundOverrideNote?: string;
 }>;
-declare function getProductSelectionImages(resolution: Pick<ProductSelectionResolution, 'media'>): ProductDetailImageMedia[];
-type ProductHrefProduct = ProductDetail | {
-    slug?: string | null;
-    product?: {
-        slug?: string | null;
-    } | null;
-};
-type ProductHrefGroup = {
-    optionId?: string | number | null;
-    optionSlug?: string | null;
-    optionValueId?: string | number | null;
-    optionValueSlug?: string | null;
-    variantId?: string | number | null;
-    listing?: {
-        selectionHintVariant?: string | number | null;
-    } | null;
-};
-type ProductHrefOptions = {
-    basePath?: string;
-    detail?: ProductDetail;
-    matrix?: ProductOptionMatrix<ProductDetailVariant>;
-    selection?: ProductSelectionInput;
-    trailingSlash?: boolean;
-    emit?: ProductSelectionUrlEmit;
-    preferCompleteVariantFromHint?: boolean;
-};
-type ProductListingCardOptions = {
-    basePath?: string;
-    trailingSlash?: boolean;
-    emit?: ProductSelectionUrlEmit;
-    preferCompleteVariantFromHint?: boolean;
-};
-declare function buildProductHref(product: ProductHrefProduct, group?: ProductHrefGroup | null, options?: ProductHrefOptions): string;
-declare function buildProductListingProjection(product: ProductListingProductShape | null | undefined, variants: ProductVariantShape[]): ProductListingProjection;
-declare function buildProductListingCard(item: ProductListingGroupsItem, options?: ProductListingCardOptions): ProductListingCard;
-/** Shopify `priceRangeV2` naming for persisted listing projection fields. */
-declare function toShopifyPriceRangeV2(listing: {
-    minPrice?: number | null;
-    maxPrice?: number | null;
-}): {
-    minVariantPrice: {
-        amount: number | null;
-    };
-    maxVariantPrice: {
-        amount: number | null;
-    };
+type UpdateReturnParams = {
+    returnId: string;
+    status: 'processing' | 'approved' | 'rejected' | 'completed';
 };
+declare class OrderApi extends BaseApi {
+    constructor(options: OrderApiOptions);
+    createOrder(params: CreateOrderParams): Promise<Order>;
+    updateOrder(params: UpdateOrderParams): Promise<Order>;
+    updateTransaction(params: UpdateTransactionParams): Promise<Transaction>;
+    confirmPayment(params: ConfirmPaymentParams): Promise<ConfirmPaymentResponse>;
+    cancelOrder(params: CancelOrderParams): Promise<CancelOrderResponse>;
+    resolveCancelRefund(params: ResolveCancelRefundParams): Promise<ResolveCancelRefundResponse>;
+    checkout(params: CheckoutParams): Promise<PublicOrder>;
+    createFulfillment(params: CreateFulfillmentParams): Promise<Fulfillment>;
+    prepareFulfillmentOrder(params: PrepareFulfillmentOrderParams): Promise<PrepareFulfillmentOrderResponse>;
+    updateFulfillment(params: UpdateFulfillmentParams): Promise<Fulfillment>;
+    bulkImportFulfillments(params: BulkImportFulfillmentsParams): Promise<BulkImportFulfillmentsResponse>;
+    returnWithRefund(params: ReturnWithRefundParams): Promise<{
+        return: Return;
+        transaction: Transaction | null;
+    }>;
+    createReturn(params: CreateReturnParams): Promise<Return>;
+    updateReturn(params: UpdateReturnParams): Promise<Return>;
+}
+
+interface CustomerAuthResponse {
+    token: string;
+    customer: CustomerProfile;
+}
+interface MarketingConsentChannel {
+    isConsented?: boolean;
+}
+interface MarketingConsent {
+    email?: MarketingConsentChannel;
+    sms?: MarketingConsentChannel;
+    push?: MarketingConsentChannel;
+    consentSource?: string;
+}
+interface CustomerProfile {
+    id: string;
+    name: string;
+    email?: string | null;
+    phone?: string | null;
+    authProvider?: 'local' | 'google' | 'apple' | 'kakao' | 'naver' | null;
+    isGuest?: boolean | null;
+    marketingConsent?: MarketingConsent | null;
+    metadata?: Record<string, unknown> | null;
+    groups?: string[];
+}
+interface CustomerRegisterData {
+    name: string;
+    email: string;
+    password: string;
+    phone?: string;
+}
+interface CustomerRegisterResponse {
+    customer: CustomerProfile;
+}
+interface CustomerLoginData {
+    email: string;
+    password: string;
+}
+interface CustomerRefreshResponse {
+    token: string;
+}
+interface UpdateProfileData {
+    name?: string;
+    phone?: string;
+    marketingConsent?: MarketingConsent;
+}
+interface CustomerAuthOptions {
+    /**
+     * Persist token in localStorage. Defaults to `true`.
+     * - `true` (default): uses key `'customer-token'`
+     * - `string`: uses the given string as localStorage key
+     * - `false`: disables persistence (token/onTokenChange used instead)
+     *
+     * Handles SSR safely (no-op on server).
+     * When enabled, `token` and `onTokenChange` are ignored.
+     */
+    persist?: boolean | string;
+    /** Initial token (e.g. from SSR cookie) */
+    token?: string;
+    /** Called when token changes (login/logout) — use to persist in localStorage/cookie */
+    onTokenChange?: (token: string | null) => void;
+}
+
 /**
- * PLP-safe query preset for the `products` collection.
- *
- * Payload's top-level `type: 'join'` fields on `products` (`variants`,
- * `options`) return at most 10 docs by default when queried via the REST API.
- * Storefront PLPs calling `client.collections.from('products').find()` without
- * explicit join limits silently receive truncated variant/option join data.
- * `buildProductListingGroupsByOption()` then drops primary-option values with
- * no matching variant in the response — a common cause of missing color swatches
- * even when the product has more variants than the default join cap.
- *
- * Spread this constant into your `find()` call to raise both top-level limits:
- *
- * ```typescript
- * const { docs } = await client.collections.from('products').find({
- *   ...PRODUCT_PLP_FIND_OPTIONS,
- *   where: { status: { equals: 'published' } },
- *   limit: 24,
- * })
- * ```
- *
- * **Limitation:** This preset cures top-level `products.options` and
- * `products.variants` join truncation. It cannot cure the nested
- * `options[].values.docs` join — the Payload REST `joins` param is flat and
- * nested join limits require the listing-groups endpoint. Prefer
- * `commerce.product.listingGroupsCatalog()` + `buildProductListingCard()` as
- * the primary PLP path; they apply unlimited join fetches server-side and
- * return pre-grouped data ready for rendering.
- */
-declare const PRODUCT_PLP_FIND_OPTIONS: ApiQueryOptions;
-/**
- * Builds product-first listing groups for one primary option.
+ * Customer authentication client.
  *
- * The returned groups are intended for product cards with nested swatches or
- * option-value sections. They do not make a product-paginated API response into
- * an expanded-card paginator; one product can still emit several groups.
+ * Manages customer registration, login, logout, and token lifecycle.
+ * All requests include X-Publishable-Key for tenant resolution.
  */
-declare function buildProductListingGroupsByOption<TVariant extends ProductVariantShape = ProductVariantShape>(args: {
-    product: ProductListingProductShape | null | undefined;
-    options: ProductOptionShape[];
-    variants: TVariant[];
-    primaryOptionId?: string | null;
-}): ProductListingGroup<TVariant>[];
+declare class CustomerAuth {
+    private publishableKey;
+    private baseUrl;
+    private token;
+    private onTokenChange?;
+    private refreshPromise;
+    constructor(publishableKey: string, options?: CustomerAuthOptions, apiUrl?: string);
+    /**
+     * Register a new customer account
+     */
+    register(data: CustomerRegisterData): Promise<CustomerRegisterResponse>;
+    /**
+     * Login with email and password. Stores the token internally.
+     */
+    login(data: CustomerLoginData): Promise<CustomerAuthResponse>;
+    /**
+     * Refresh the current token. Requires a valid (non-expired) token.
+     */
+    refreshToken(): Promise<CustomerRefreshResponse>;
+    private _doRefreshToken;
+    /**
+     * Clear the stored token
+     */
+    logout(): void;
+    /**
+     * Get the current authenticated customer's profile
+     */
+    me(): Promise<CustomerProfile | null>;
+    /**
+     * Request a password reset email
+     */
+    forgotPassword(email: string): Promise<void>;
+    /**
+     * Reset password using a token from the reset email
+     */
+    resetPassword(token: string, password: string): Promise<void>;
+    /**
+     * Update the authenticated customer's profile (name, phone, marketingConsent)
+     */
+    updateProfile(data: UpdateProfileData): Promise<CustomerProfile>;
+    /**
+     * Change the password of the currently authenticated customer
+     */
+    changePassword(currentPassword: string, newPassword: string): Promise<void>;
+    /**
+     * Get the authenticated customer's orders with pagination and optional status filter
+     */
+    getMyOrders(options?: {
+        page?: number;
+        limit?: number;
+        status?: string;
+    }): Promise<PayloadFindResponse<PublicOrder>>;
+    /**
+     * Get the current token (or null if not authenticated)
+     */
+    getToken(): string | null;
+    /**
+     * Set the token manually (e.g. from SSR)
+     */
+    setToken(token: string | null): void;
+    /**
+     * Check if the customer is currently authenticated
+     */
+    isAuthenticated(): boolean;
+    /**
+     * Internal: make a request with timeout and error handling.
+     * Auth endpoints don't retry — failures are final.
+     */
+    private requestJson;
+}
 
-type ProductUpsertColorSwatchInput = {
-    type: 'color';
-    color: string;
-    mediaItemId?: null;
+interface CartApiOptions {
+    publishableKey?: string;
+    secretKey?: string;
+    apiUrl?: string;
+    customerToken?: string | (() => string | null);
+    onUnauthorized?: () => Promise<string | null>;
+    onRequestId?: (id: string | null) => void;
+}
+type AddItemParams = {
+    cartId: string;
+    product: string;
+    variant: string;
+    option: string;
+    quantity: number;
 };
-type ProductUpsertMediaSwatchInput = {
-    type: 'media';
-    mediaItemId: string;
-    color?: null;
+type UpdateItemParams = {
+    cartItemId: string;
+    quantity: number;
 };
-type ProductUpsertSwatchInput = ProductUpsertColorSwatchInput | ProductUpsertMediaSwatchInput;
-type ProductUpsertOptionValueInput = {
-    id?: string;
-    value: string;
-    slug?: string;
-    swatch?: ProductUpsertSwatchInput | null;
-    metadata?: unknown;
+type RemoveItemParams = {
+    cartItemId: string;
 };
-type OptionValueInput = ProductUpsertOptionValueInput;
-type OptionInput = {
-    id?: string;
-    title: string;
-    slug?: string;
-    values: OptionValueInput[];
+type ApplyDiscountParams = {
+    cartId: string;
+    discountCode: string;
 };
-type VariantInput = {
-    id?: string;
-    optionValues?: Record<string, string | {
-        valueSlug?: string;
-        valueId?: string;
-        value?: 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;
-    images?: string[];
-    metadata?: unknown;
+type RemoveDiscountParams = {
+    cartId: string;
 };
-type ProductFieldsInput = {
-    id?: string;
-    title?: string;
-    subtitle?: string | null;
-    description?: string | null;
-    status?: string;
-    slug?: string;
-    primaryMediaItemId?: string | null;
-    thumbnail?: string | null;
-    images?: string[];
-    vendor?: string | null;
-    productType?: string | null;
-    brand?: string | null;
-    shippingPolicy?: string | null;
-    weight?: number | null;
-    minOrderQuantity?: number | null;
-    maxOrderQuantity?: number | null;
-    isFeatured?: boolean;
-    publishedAt?: string | null;
-    categories?: string[];
-    tags?: string[];
-    metadata?: unknown;
+type ClearCartParams = {
+    cartId: string;
 };
-type ProductUpsertGraphFields = {
-    /** Required when updating an existing product graph if the server graph is non-empty. */
-    graphRevision?: string;
-    options?: OptionInput[];
-    variants?: VariantInput[];
+type PublicCartReference = string | {
+    id?: string | number | null;
+    title?: string | null;
+    name?: string | null;
+    slug?: string | null;
+    displayName?: string | null;
+    handle?: string | null;
+    color?: string | null;
+    image?: PublicMediaAsset | null;
+    thumbnail?: PublicMediaAsset | null;
+    avatar?: PublicMediaAsset | null;
 };
-/** Create a product document and initial graph. */
-type ProductUpsertCreateInput = ProductUpsertGraphFields & {
-    productId?: never;
-    product: ProductFieldsInput & {
-        title: string;
+type PublicCartItem = {
+    id?: string | number;
+    product?: PublicCartReference;
+    variant?: PublicCartReference;
+    quantity?: number | null;
+    unitPrice?: number | null;
+    discountAllocation?: number | null;
+    discountedUnitPrice?: number | null;
+    discountedTotalPrice?: number | null;
+    createdAt?: string | null;
+    updatedAt?: string | null;
+};
+type PublicCart = {
+    id?: string | number;
+    status?: string | null;
+    currency?: string | null;
+    subtotalAmount?: number | null;
+    shippingAmount?: number | null;
+    discountAmount?: number | null;
+    totalAmount?: number | null;
+    discountCode?: string | null;
+    customerNote?: string | null;
+    lastActivityAt?: string | null;
+    expiresAt?: string | null;
+    createdAt?: string | null;
+    updatedAt?: string | null;
+    shippingAddress?: {
+        recipientName?: string | null;
+        phone?: string | null;
+        postalCode?: string | null;
+        address?: string | null;
+        detailAddress?: string | null;
+        deliveryMessage?: string | null;
+        address1?: string | null;
+        address2?: string | null;
+        jibunAddress?: string | null;
+        administrativeArea?: string | null;
+        city?: string | null;
+        province?: string | null;
+        country?: string | null;
+        deliveryMemo?: string | null;
     };
+    items?: PublicCartItem[];
 };
-/** Graph-only update for an existing product (document fields via Payload save). */
-type ProductUpsertEditInput = ProductUpsertGraphFields & {
-    productId: string;
-    product?: never;
-};
-type ProductUpsertInput = ProductUpsertCreateInput | ProductUpsertEditInput;
-
-type ProductApiOptions = ServerApiOptions;
-type StockCheckParams = {
-    items: Array<{
-        variantId: string;
-        quantity: number;
+declare class CartApi extends CustomerScopedApi {
+    constructor(options: CartApiOptions);
+    private execute;
+    getCart(cartId: string): Promise<PublicCart>;
+    addItem(params: AddItemParams): Promise<PublicCartItem>;
+    updateItem(params: UpdateItemParams): Promise<PublicCartItem>;
+    removeItem(params: RemoveItemParams): Promise<{
+        success: boolean;
     }>;
+    applyDiscount(params: ApplyDiscountParams): Promise<PublicCart>;
+    removeDiscount(params: RemoveDiscountParams): Promise<PublicCart>;
+    clearCart(params: ClearCartParams): Promise<{
+        success: boolean;
+    }>;
+}
+
+type NormalizedOptionSwatch<TMedia = unknown> = {
+    type: 'color' | 'media' | null;
+    color?: string | null;
+    mediaItemId?: string | number | null;
+    /** Inlined swatch media when the API populated mediaItemId before pool indexing. */
+    inlineMedia?: TMedia | null;
 };
-type StockCheckResult = {
-    variantId: string;
-    status: 'available' | 'not_published' | 'archived' | 'not_found';
-    available: boolean;
-    availableStock: number;
-    isUnlimited: boolean;
-    requestedQuantity: number;
-    error?: string;
-};
-type StockCheckResponse = {
-    results: StockCheckResult[];
-    allAvailable: boolean;
-};
-type ListingGroupsParams = {
-    productIds: string[];
+declare function selectedSwatchMediaItemId(swatch: NormalizedOptionSwatch | null | undefined): string | null;
+type ProductSelectionMediaSource = 'variant_media_selected' | 'variant_media_matching' | 'option_swatch' | 'none';
+type ProductDisplayMediaSource = 'listing_primary' | 'product_primary' | 'product_pool' | 'none';
+/** @deprecated Use {@link ProductSelectionMediaSource} or {@link ProductDisplayMediaSource}. */
+type ProductMediaResolutionSource = ProductSelectionMediaSource | ProductDisplayMediaSource;
+type ProductSelectionVariant<TMedia> = {
+    id?: string | number | null;
+    images?: Array<TMedia | string | number | null | undefined> | null;
 };
-type ProductListingGroupVariant = Pick<ProductVariantShape, 'id' | 'optionValues' | 'price' | 'compareAtPrice' | 'stock' | 'isUnlimited' | 'isActive' | 'thumbnail' | 'images' | '_order'>;
-type ProductListingGroupSummary = ProductListingGroup<ProductListingGroupVariant>;
-type ProductListingGroupsProductVariants = NonNullable<PublicProduct['variants']>;
-type ProductListingGroupsProductPrimaryMediaItemId = string | number | {
+type ProductSelectionOptionValue = {
+    id?: string | number | null;
+    swatch?: NormalizedOptionSwatch<unknown> | null;
+};
+type ProductSelectionMediaPointer = string | number | {
     id?: string | number | null;
 } | null;
-type ProductListingGroupsProduct = Omit<PublicProduct, 'variants'> & {
-    id: string;
-    slug: string;
-    title: string;
-    primaryMediaItemId?: ProductListingGroupsProductPrimaryMediaItemId;
-    variants?: (Omit<ProductListingGroupsProductVariants, 'docs'> & {
-        docs: ProductListingGroupVariant[];
-    }) | null;
+type ResolveProductSelectionMediaInput<TMedia> = {
+    productMediaPool?: TMedia[] | null;
+    productPrimaryMediaItemId?: ProductSelectionMediaPointer;
+    selectedVariant?: ProductSelectionVariant<TMedia> | null;
+    matchingVariants?: Array<ProductSelectionVariant<TMedia> | null | undefined> | null;
+    selectedOptionValues?: Array<ProductSelectionOptionValue | null | undefined> | null;
 };
-type ProductListingGroupsItem = {
-    product: ProductListingGroupsProduct;
-    groups: ProductListingGroupSummary[];
+type ResolveProductSelectionMediaResult<TMedia> = {
+    primaryImage: TMedia | null;
+    images: TMedia[];
+    source: ProductSelectionMediaSource;
 };
-type ProductListingGroupsResponse = {
-    /**
-     * Matching products in the same order as the requested productIds, excluding
-     * ids that were not found, not published, or not accessible for the current
-     * tenant/key.
-     */
-    docs: ProductListingGroupsItem[];
-    /** Requested productIds that could not be returned. */
-    missing: string[];
+type ResolveProductDisplayMediaInput<TMedia> = {
+    productMediaPool?: TMedia[] | null;
+    productPrimaryMediaItemId?: ProductSelectionMediaPointer;
+    listingPrimaryImage?: ProductSelectionMediaPointer;
 };
-type ProductDetailParams = {
-    slug: string;
-} | {
-    id: string;
+type ResolveProductDisplayMediaResult<TMedia> = {
+    primaryImage: TMedia | null;
+    images: TMedia[];
+    source: ProductDisplayMediaSource;
 };
-type ProductDetailPreviewParams = {
-    id: string;
+declare function resolveProductSelectionMedia<TMedia>(input: ResolveProductSelectionMediaInput<TMedia>): ResolveProductSelectionMediaResult<TMedia>;
+declare function resolveProductDisplayMedia<TMedia>(input: ResolveProductDisplayMediaInput<TMedia>): ResolveProductDisplayMediaResult<TMedia>;
+type ListingPrimaryImageFallbackInput<TMedia> = {
+    productMediaPool?: TMedia[] | null;
+    productPrimaryMediaItemId?: ProductSelectionMediaPointer;
+    productThumbnail?: TMedia | string | number | null;
+    listingPrimaryImage?: TMedia | string | number | null;
+    resolvedPrimary?: TMedia | null;
+    resolvedSource?: ProductMediaResolutionSource;
 };
-type ProductDetailPreviewOptions = {
-    previewToken: string;
+declare function resolveListingPrimaryImagePointer<TMedia>(input: ListingPrimaryImageFallbackInput<TMedia>): string | null;
+
+type EntityID = string;
+type RelationshipValue = string | number | null | undefined | {
+    id?: string | number | null;
 };
-interface ProductDetailVariantOptionValue {
-    optionId: string | number;
-    optionSlug: string;
-    valueId: string | number;
-    valueSlug: string;
+type MediaValue = ProductDetailMedia | null | undefined;
+
+/** Raw Payload / REST swatch before strict public normalization. */
+type ProductOptionValueSwatchInput = {
+    type?: 'color' | 'media' | null;
+    color?: string | null;
+    mediaItemId?: RelationshipValue;
+};
+interface ProductOptionValueShape {
+    id?: string | number | null;
+    option?: RelationshipValue;
     value?: string | null;
+    slug?: string | null;
+    swatch?: ProductOptionValueSwatch | ProductOptionValueSwatchInput | null;
+    _order?: string | null;
+    '_product-option-values_values_order'?: string | null;
 }
-type ProductDetailMedia = string | number | {
+interface ProductOptionShape {
     id?: string | number | null;
-    url?: string | null;
-    alt?: string | null;
-    width?: number | null;
-    height?: number | null;
-};
-type ProductOptionValueColorSwatch = {
-    type: 'color';
-    color: string;
-    mediaItemId?: null;
-};
-type ProductOptionValueMediaSwatch<TMedia = ProductDetailMedia> = {
-    type: 'media';
-    mediaItemId: TMedia;
-    color?: null;
-};
-type ProductOptionValueSwatch<TMedia = ProductDetailMedia> = ProductOptionValueColorSwatch | ProductOptionValueMediaSwatch<TMedia> | null;
-type ProductDetailMediaValue = string | number | ProductDetailMedia | null;
-type ProductDetailSelectionMediaSource = 'variant_media_selected' | 'variant_media_matching' | 'option_swatch' | 'none';
-interface ProductDetailVariant {
-    id: string | number;
-    optionKey: string;
     title?: string | null;
-    displayName: string;
-    sku?: string | null;
-    price: number;
+    slug?: string | null;
+    _order?: string | null;
+    '_product-options_options_order'?: string | null;
+    values?: {
+        docs?: unknown[];
+    } | null;
+}
+interface ProductVariantShape {
+    id?: string | number | null;
+    optionValues?: unknown[] | null;
+    price?: number | null;
     compareAtPrice?: number | null;
-    stock: number;
-    reservedStock: number;
-    isUnlimited: boolean;
-    isActive: boolean;
-    thumbnail?: ProductDetailMedia | null;
-    images?: ProductDetailMedia[];
-    media?: {
-        primaryImage: ProductDetailMedia | null;
-        images: ProductDetailMedia[];
-        source: ProductDetailSelectionMediaSource;
-    };
-    optionValues: ProductDetailVariantOptionValue[];
+    stock?: number | null;
+    reservedStock?: number | null;
+    isUnlimited?: boolean | null;
+    isActive?: boolean | null;
+    thumbnail?: MediaValue;
+    images?: MediaValue[] | null;
+    _order?: string | null;
 }
-interface ProductDetailOptionValue {
-    id: string | number;
-    value: string;
-    slug: string;
-    swatch?: ProductOptionValueSwatch<ProductDetailMedia>;
+interface ProductListingProductShape {
+    id?: EntityID;
+    thumbnail?: MediaValue;
+    primaryMediaItemId?: MediaValue;
+    images?: MediaValue[] | null;
+    listing?: {
+        primaryImage?: MediaValue;
+    } | null;
 }
-interface ProductDetailOption {
-    id: string | number;
+type ProductOptionMatrixValue = {
+    id: string;
+    optionId: string;
+    optionSlug: string;
+    label: string;
+    slug: string | null;
+    swatch: ProductOptionValueSwatch;
+    order: string;
+};
+type ProductOptionMatrixOption = {
+    id: string;
     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;
-}
-type ProductDetailCatalogVariant = Omit<ProductDetailVariant, 'stock' | 'reservedStock'>;
-type ProductDetailCatalogListing = Omit<ProductDetailListing, 'availableForSale'> & {
-    liveStockRequired: true;
+    order: string;
+    values: ProductOptionMatrixValue[];
+};
+type ProductOptionMatrixVariant<TVariant extends ProductVariantShape = ProductVariantShape> = {
+    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 = {
+    selectionHintVariant: EntityID | null;
+    primaryImage: EntityID | null;
+    minPrice: number | null;
+    maxPrice: number | null;
+    minCompareAtPrice: number | null;
+    maxCompareAtPrice: number | null;
+    isPriceRange: boolean;
+    availableForSale: boolean;
+};
+type ProductListingGroup<TVariant extends ProductVariantShape = ProductVariantShape> = {
+    optionId: EntityID;
+    optionTitle: string;
+    optionSlug: string;
+    optionValueId: EntityID;
+    optionValueLabel: string;
+    optionValueSlug: string | null;
+    optionValueSwatch: ProductOptionValueSwatch;
+    variantIds: EntityID[];
+    variantCount: number;
+    variants: TVariant[];
+    listing: ProductListingProjection;
+};
+type ProductListingCardPriceRange = {
+    minPrice: number | null;
+    maxPrice: number | null;
+    minCompareAtPrice: number | null;
+    maxCompareAtPrice: number | null;
+    isPriceRange: boolean;
 };
-interface ProductDetailCatalog {
-    product: Omit<ProductDetail['product'], 'totalInventory'>;
-    variants: ProductDetailCatalogVariant[];
-    options: ProductDetail['options'];
-    brand: ProductDetail['brand'];
-    categories: ProductDetail['categories'];
-    tags: ProductDetail['tags'];
-    images: ProductDetail['images'];
-    videos: ProductDetail['videos'];
-    primaryMediaItemId?: ProductDetail['primaryMediaItemId'];
-    listing: ProductDetailCatalogListing;
-}
-type StockSnapshotItemStatus = 'available' | 'not_published' | 'archived' | 'not_found';
-interface StockSnapshotItem {
-    variantId: string;
-    status: StockSnapshotItemStatus;
-    availableStock: number;
+type ProductListingSwatch = {
+    optionId: EntityID;
+    optionValueId: EntityID;
+    label: string;
+    swatch: ProductOptionValueSwatch<ProductDetailMedia>;
+    href: string;
     availableForSale: boolean;
-    isUnlimited: boolean;
-}
-interface StockSnapshotResponse {
-    snapshots: StockSnapshotItem[];
-}
-type StockSnapshotParams = {
-    variantIds: string[];
 };
-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 | null;
-        totalVariants: number;
-        hasUnlimitedVariant: boolean;
-        hasOnlyDefaultVariant: boolean;
-    };
-    variants: ProductDetailVariant[];
-    options: ProductDetailOption[];
-    brand: ProductDetailBrand | null;
-    categories: ProductDetailCategory[];
-    tags: ProductDetailTag[];
-    images: ProductDetailImage[];
-    videos: ProductDetailVideo[];
-    /** Canonical product primary pointer (pool member). */
-    primaryMediaItemId?: ProductDetailMediaValue;
-    listing: ProductDetailListing;
-}
-type ProductDetailUnavailableReason = 'not_found' | 'not_published' | 'feature_disabled';
-type ProductDetailResult = {
-    found: true;
-    product: ProductDetail;
-} | {
-    found: false;
-    reason: ProductDetailUnavailableReason;
+type ProductListingCardSourceItem = ProductListingGroupsCatalogItem | ProductListingGroupsItem;
+type ProductListingCardRepresentativeVariant = ProductListingCardSourceItem['groups'][number]['variants'][number];
+type ProductListingCard = {
+    id: EntityID;
+    href: string;
+    title: string;
+    representativeVariant?: ProductListingCardRepresentativeVariant | null;
+    primaryImage: ProductDetailMedia | null;
+    priceRange: ProductListingCardPriceRange;
+    availableForSale: boolean;
+    swatches: ProductListingSwatch[];
 };
-type ProductDetailCatalogResult = {
-    found: true;
-    product: ProductDetailCatalog;
-} | {
-    found: false;
-    reason: ProductDetailUnavailableReason;
+type ProductSelectionByOptionValue = string | number | null | undefined | {
+    valueId?: string | number | null;
+    valueSlug?: string | null;
 };
-type ProductUpsertParams = ProductUpsertInput;
-/** Console `POST /api/products/upsert` field allowlist error reasons. */
-declare const PRODUCT_UPSERT_UNKNOWN_FIELD_REASON: "unknown_field";
-declare const PRODUCT_UPSERT_READONLY_FIELD_REASON: "product_field_readonly";
-type ProductUpsertFieldValidationErrorReason = typeof PRODUCT_UPSERT_UNKNOWN_FIELD_REASON | typeof PRODUCT_UPSERT_READONLY_FIELD_REASON;
-/** 400 response body when upsert rejects unknown or server-managed product fields. */
-type ProductUpsertFieldValidationErrorBody = {
-    error: string;
-    reason: ProductUpsertFieldValidationErrorReason;
-    field: string;
-    requestId?: string;
+type ProductSelectionInput = {
+    variantId?: string | number | null;
+    byOptionSlug?: Record<string, ProductSelectionByOptionValue>;
+    byOptionId?: Record<string, ProductSelectionByOptionValue>;
+    valueIds?: Iterable<unknown>;
+    search?: string | URLSearchParams | URL | null;
 };
-declare function isProductUpsertFieldValidationErrorBody(value: unknown): value is ProductUpsertFieldValidationErrorBody;
-type ProductUpsertResponse = {
-    ok: true;
-    product: PublicProduct;
-    listingProjectionStale: boolean;
-} | {
-    ok: false;
-    failedEntity: 'product' | 'option' | 'option-value' | 'variant';
-    failedIndex?: number;
-    message: string;
+type NormalizedProductSelection = {
+    byOptionSlug: Record<string, string>;
+    byOptionId: Record<string, string>;
+    valueIds: string[];
+    variantId: string | null;
 };
-declare class ProductApi extends BaseApi {
-    constructor(options: ProductApiOptions);
-    /**
-     * Check point-in-time stock availability for one or more product variants.
-     * Results reflect available stock at the moment of the call and are not guaranteed
-     * to remain available by the time an order is placed.
-     */
-    stockCheck(params: StockCheckParams): Promise<StockCheckResponse>;
-    stockSnapshot(params: StockSnapshotParams): Promise<StockSnapshotResponse>;
-    listingGroups(params: ListingGroupsParams): Promise<ProductListingGroupsResponse>;
-    listingGroupsCatalog(params: ListingGroupsParams): Promise<ProductListingGroupsResponse>;
-    /**
-     * Fetch full product detail by slug or id.
-     * Returns a discriminated result so storefronts can distinguish missing,
-     * unpublished, and feature-disabled products.
-     *
-     * Only product-detail 404 responses carrying one of those allowlisted reasons
-     * are mapped to `{ found: false, reason }`. Unknown or uncoded 404s, plus
-     * permission/auth errors such as tenant mismatch, continue to throw typed SDK
-     * errors instead of being collapsed into a storefront absence result.
-     */
-    detail(params: ProductDetailParams): Promise<ProductDetailResult>;
-    detailCatalog(params: ProductDetailParams): Promise<ProductDetailCatalogResult>;
+type CompatibilityProductSelectionParamEvent = {
+    optionId: string;
+    optionSlug: string;
+    valueSlug: string;
+    searchParam: string;
+};
+type LegacyProductSelectionParamEvent = CompatibilityProductSelectionParamEvent;
+type ProductSelectionUrlEmit = 'slug-compat' | 'canonical-id';
+type ProductSelectionCodecOptions = {
+    emit?: ProductSelectionUrlEmit;
     /**
-     * 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.
+     * When true, `resolveProductSelection()` fills unselected options to reach a
+     * concrete variant. Does not change codec parse/stringify behavior.
      */
-    upsert(params: ProductUpsertParams): Promise<ProductUpsertResponse>;
-}
-
-type DiscountApiOptions = ServerApiOptions;
-type ValidateDiscountParams = {
+    fillDefaults?: boolean;
+    onCompatibilityOptionIdParam?: (event: CompatibilityProductSelectionParamEvent) => void;
+    onLegacyOptionIdParam?: (event: LegacyProductSelectionParamEvent) => void;
+};
+type ProductSelectionResolutionContext = {
+    detail?: Pick<ProductDetail, 'images' | 'listing' | 'primaryMediaItemId'>;
+    images?: ProductDetail['images'];
+    listing?: ProductDetail['listing'];
+    primaryMediaItemId?: ProductDetail['primaryMediaItemId'];
+};
+type ProductSelectionAvailableSwatch = {
+    color?: string | null;
+    image?: MediaValue | null;
+};
+type ProductSelectionAvailableValue = {
+    valueId: string;
+    value: string;
+    label: string;
+    slug: string;
+    selected: boolean;
+    available: boolean;
+    exists: boolean;
+    availableForSale: boolean;
+    isUnlimited: boolean;
+    availableStock: number | null;
+    swatch: ProductOptionValueSwatch;
+};
+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[];
+        source?: ProductMediaResolutionSource;
+    };
+    stock: {
+        availableForSale: boolean;
+        isUnlimited: boolean;
+        stock: number | null;
+        reservedStock: number | null;
+        availableStock: number | null;
+    };
+};
+declare class ProductSelectionCodecError extends Error {
     code: string;
-    orderAmount: number;
+    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 normalizeProductSelectionFromMatrix(matrix: ProductOptionMatrix<ProductDetailVariant>, 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 resolveProductSelectionFromMatrix(matrix: ProductOptionMatrix<ProductDetailVariant>, selection?: ProductSelectionInput, options?: ProductSelectionCodecOptions, context?: ProductSelectionResolutionContext): ProductSelectionResolution;
+declare function resolveProductSelection(detail: ProductDetail, selection?: ProductSelectionInput, options?: ProductSelectionCodecOptions): ProductSelectionResolution;
+declare function selectNext(detail: ProductDetail, current: ProductSelectionInput | undefined, optionSlug: string, valueSlug: string, options?: ProductSelectionCodecOptions): NormalizedProductSelection;
+type ProductDetailImageMedia = Extract<ProductDetailMedia, {
+    id?: string | number | null;
+    url?: string | null;
+}>;
+declare function getProductSelectionImages(resolution: Pick<ProductSelectionResolution, 'media'>): ProductDetailImageMedia[];
+type ProductHrefProduct = ProductDetail | {
+    slug?: string | null;
+    product?: {
+        slug?: string | null;
+    } | null;
+};
+type ProductHrefGroup = {
+    optionId?: string | number | null;
+    optionSlug?: string | null;
+    optionValueId?: string | number | null;
+    optionValueSlug?: string | null;
+    variantId?: string | number | null;
+    listing?: {
+        selectionHintVariant?: string | number | null;
+    } | null;
 };
-type ValidateDiscountResult = {
-    valid: boolean;
-    code: string;
-    type?: 'percentage' | 'fixed_amount' | 'free_shipping' | 'tiered';
-    discountAmount: number;
-    freeShipping?: boolean;
-    reason?: string;
+type ProductHrefOptions = {
+    basePath?: string;
+    detail?: ProductDetail;
+    matrix?: ProductOptionMatrix<ProductDetailVariant>;
+    selection?: ProductSelectionInput;
+    trailingSlash?: boolean;
+    emit?: ProductSelectionUrlEmit;
+    preferCompleteVariantFromHint?: boolean;
 };
-declare class DiscountApi extends BaseApi {
-    constructor(options: DiscountApiOptions);
-    validate(params: ValidateDiscountParams): Promise<ValidateDiscountResult>;
-}
-
-type ShippingApiOptions = ServerApiOptions;
-type CalculateShippingParams = {
-    shippingPolicyId?: string;
-    orderAmount: number;
-    postalCode?: string;
+type ProductListingCardOptions = {
+    basePath?: string;
+    trailingSlash?: boolean;
+    emit?: ProductSelectionUrlEmit;
+    preferCompleteVariantFromHint?: boolean;
 };
-type CalculateShippingResult = {
-    shippingAmount: number;
-    baseShippingAmount: number;
-    extraShippingAmount: number;
-    freeShipping: boolean;
-    freeShippingMinAmount: number | null;
-    isJeju: boolean;
-    isRemoteIsland: boolean;
+declare function buildProductHref(product: ProductHrefProduct, group?: ProductHrefGroup | null, options?: ProductHrefOptions): string;
+declare function buildProductListingProjection(product: ProductListingProductShape | null | undefined, variants: ProductVariantShape[]): ProductListingProjection;
+declare function buildProductListingCard(item: ProductListingCardSourceItem, options?: ProductListingCardOptions): ProductListingCard;
+/** Shopify `priceRangeV2` naming for persisted listing projection fields. */
+declare function toShopifyPriceRangeV2(listing: {
+    minPrice?: number | null;
+    maxPrice?: number | null;
+}): {
+    minVariantPrice: {
+        amount: number | null;
+    };
+    maxVariantPrice: {
+        amount: number | null;
+    };
 };
-declare class ShippingApi extends BaseApi {
-    constructor(options: ShippingApiOptions);
-    calculate(params: CalculateShippingParams): Promise<CalculateShippingResult>;
-}
+/**
+ * Server-side PLP query preset for raw `products` collection reads.
+ *
+ * Greenfield storefronts should prefer
+ * `client.commerce.product.listingPage()` because it calls the shaped catalog
+ * endpoint, preserves pagination metadata, returns card-ready `cards`, and
+ * avoids exposing inventory quantities.
+ *
+ * This preset remains only for server-auth raw product query code
+ * that deliberately understands Payload join behavior. It raises top-level
+ * `products.options` and `products.variants` join limits, but it cannot fix
+ * nested `options[].values.docs` joins because the Payload REST `joins` param
+ * is flat.
+ *
+ * It is not accepted by publishable
+ * `createClient().collections.from('products').find()` because browser-public
+ * raw reads are constrained to `depth: 0`, `joins: false`, and no `populate`.
+ */
+declare const PRODUCT_PLP_FIND_OPTIONS: ApiQueryOptions;
+/**
+ * Builds product-first listing groups for one primary option.
+ *
+ * The returned groups are intended for product cards with nested swatches or
+ * option-value sections. They do not make a product-paginated API response into
+ * an expanded-card paginator; one product can still emit several groups.
+ */
+declare function buildProductListingGroupsByOption<TVariant extends ProductVariantShape = ProductVariantShape>(args: {
+    product: ProductListingProductShape | null | undefined;
+    options: ProductOptionShape[];
+    variants: TVariant[];
+    primaryOptionId?: string | null;
+}): ProductListingGroup<TVariant>[];
 
-type OrderApiOptions = ServerApiOptions;
-/** Header-only; never sent in the JSON body. */
-type WithIdempotencyKey<T> = T & {
-    /**
-     * Client-generated key for safe retries. Sent as `X-Idempotency-Key` when the
-     * server endpoint supports HTTP idempotency.
-     */
-    idempotencyKey?: string;
+type ProductUpsertColorSwatchInput = {
+    type: 'color';
+    color: string;
+    mediaItemId?: null;
 };
-type CustomerSnapshot = {
-    name?: string;
-    email: string;
-    phone?: string;
+type ProductUpsertMediaSwatchInput = {
+    type: 'media';
+    mediaItemId: string;
+    color?: null;
 };
-type ReturnReason = 'change_of_mind' | 'defective' | 'wrong_delivery' | 'damaged' | 'other';
-type ReturnItem = {
-    orderItem: string | number;
-    quantity: number;
-    restockAction?: RestockAction;
-    restockingFee?: number;
+type ProductUpsertSwatchInput = ProductUpsertColorSwatchInput | ProductUpsertMediaSwatchInput;
+type ProductUpsertOptionValueInput = {
+    id?: string;
+    value: string;
+    slug?: string;
+    swatch?: ProductUpsertSwatchInput | null;
+    metadata?: unknown;
 };
-type OrderCreateEntityID = string | number;
-type CreateOrderItem = {
-    product: OrderCreateEntityID;
-    variant: OrderCreateEntityID;
-    option: OrderCreateEntityID;
-    quantity: number;
-    /**
-     * Compatibility input: the create-order endpoint accepts this, but the server
-     * derives authoritative line pricing from the product variant.
-     */
-    unitPrice?: number;
-    /**
-     * Compatibility input: the create-order endpoint accepts this, but the server
-     * derives authoritative line totals from the product variant.
-     */
-    totalPrice?: number;
+type OptionValueInput = ProductUpsertOptionValueInput;
+type OptionInput = {
+    id?: string;
+    title: string;
+    slug?: string;
+    values: OptionValueInput[];
 };
-type CreateOrderLineItemsInput = {
-    orderItems: CreateOrderItem[];
-    items?: never;
-} | {
-    /**
-     * Storefront-facing alias for orderItems. The SDK serializes this to
-     * orderItems for the existing create-order endpoint.
-     */
-    items: CreateOrderItem[];
-    /**
-     * @deprecated Use items for storefront-facing create-order inputs.
-     */
-    orderItems?: never;
+type VariantInput = {
+    id?: string;
+    optionValues?: Record<string, string | {
+        valueSlug?: string;
+        valueId?: string;
+        value?: 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;
+    images?: string[];
+    metadata?: unknown;
 };
-type CreateOrderBodyBase = {
-    orderNumber: string;
-    customer?: string;
-    customerSnapshot: CustomerSnapshot;
-    shippingAddress: Order['shippingAddress'];
-    totalAmount: number;
-    shippingAmount?: number;
-    pgPaymentId?: string;
-    discountCode?: string;
+type ProductFieldsInput = {
+    id?: string;
+    title?: string;
+    subtitle?: string | null;
+    description?: string | null;
+    status?: string;
+    slug?: string;
+    primaryMediaItemId?: string | null;
+    thumbnail?: string | null;
+    images?: string[];
+    vendor?: string | null;
+    productType?: string | null;
+    brand?: string | null;
+    shippingPolicy?: string | null;
+    weight?: number | null;
+    minOrderQuantity?: number | null;
+    maxOrderQuantity?: number | null;
+    isFeatured?: boolean;
+    publishedAt?: string | null;
+    categories?: string[];
+    tags?: string[];
+    metadata?: unknown;
 };
-type CreateOrderParams = WithIdempotencyKey<CreateOrderBodyBase & CreateOrderLineItemsInput>;
-type UpdateOrderParams = {
-    orderNumber: string;
-    status: 'confirmed';
+type ProductUpsertGraphFields = {
+    /** Required when updating an existing product graph if the server graph is non-empty. */
+    graphRevision?: string;
+    options?: OptionInput[];
+    variants?: VariantInput[];
 };
-type TransactionStatus = 'pending' | 'paid' | 'failed' | 'canceled';
-type UpdateTransactionParams = {
-    pgPaymentId: string;
-    status: TransactionStatus;
-    paymentMethod?: string;
-    receiptUrl?: string;
-    paymentKey?: string;
-    amount?: number;
+/** Create a product document and initial graph. */
+type ProductUpsertCreateInput = ProductUpsertGraphFields & {
+    productId?: never;
+    product: ProductFieldsInput & {
+        title: string;
+    };
 };
-type ConfirmPaymentParams = WithIdempotencyKey<{
-    orderNumber?: string;
-    pgPaymentId: string;
-    pgProvider: string;
-    pgOrderId?: string;
-    amount: number;
-    currency?: string;
-    paymentMethod?: string;
-    receiptUrl?: string;
-    approvedAt?: string;
-    providerStatus?: string;
-    /** Provider event id; also used as idempotency key when `idempotencyKey` is omitted. */
-    providerEventId?: string;
-    confirmationSource?: 'provider_webhook' | 'provider_lookup' | 'provider_api_confirm' | 'manual_server';
-    metadata?: Record<string, unknown>;
-}>;
-type ConfirmPaymentResponse = {
-    orderId: string;
-    transactionId: string;
-    status: 'paid';
-    alreadyConfirmed?: boolean;
+/** Graph-only update for an existing product (document fields via Payload save). */
+type ProductUpsertEditInput = ProductUpsertGraphFields & {
+    productId: string;
+    product?: never;
+};
+type ProductUpsertInput = ProductUpsertCreateInput | ProductUpsertEditInput;
+
+type ProductApiOptions = ServerApiOptions;
+type StockCheckParams = {
+    items: Array<{
+        variantId: string;
+        quantity: number;
+    }>;
+};
+type StockCheckResult = {
+    variantId: string;
+    status: 'available' | 'not_published' | 'archived' | 'not_found';
+    available: boolean;
+    availableStock: number;
+    isUnlimited: boolean;
+    requestedQuantity: number;
+    error?: string;
 };
-type CancelReasonCode = 'customer' | 'inventory' | 'fraud' | 'declined' | 'staff' | 'other';
-type CancelOrderStatus = 'pending' | 'paid' | 'failed' | 'canceled' | 'refunded' | 'preparing' | 'shipped' | 'delivered' | 'confirmed' | 'return_requested' | 'return_processing' | 'returned';
-type CancelOrderReconciliationStatus = Exclude<CancelOrderStatus, 'pending' | 'failed' | 'canceled'>;
-type CancelOrderResponseBase = {
-    orderId: string;
+type StockCheckResponse = {
+    results: StockCheckResult[];
+    allAvailable: boolean;
 };
-type CancelOrderUnpaidCommittedResponseFields = {
-    refundedAmount: 0;
-    providerRefunded: false;
+type ListingGroupsParams = {
+    productIds: string[];
 };
-type CancelOrderPaidCommittedResponseFields = {
-    transactionId: string;
-    refundedAmount: 0;
-    providerRefunded: false;
-    refundPending: true;
+type ProductListingGroupVariant = Pick<ProductVariantShape, 'id' | 'optionValues' | 'price' | 'compareAtPrice' | 'stock' | 'isUnlimited' | 'isActive' | 'thumbnail' | 'images' | '_order'>;
+type ProductListingGroupSummary = ProductListingGroup<ProductListingGroupVariant>;
+type ProductListingGroupCatalogVariant = Omit<ProductListingGroupVariant, 'stock'>;
+type ProductListingGroupCatalogSummary = ProductListingGroup<ProductListingGroupCatalogVariant>;
+type ProductListingGroupsProductVariants = NonNullable<PublicProduct['variants']>;
+type ProductListingGroupsProductPrimaryMediaItemId = string | number | {
+    id?: string | number | null;
+} | null;
+type ProductListingGroupsProduct = Omit<PublicProduct, 'createdAt' | 'primaryMediaItemId' | 'updatedAt' | 'variants'> & {
+    id: string;
+    slug: string;
+    title: string;
+    createdAt?: PublicProduct['createdAt'];
+    updatedAt?: PublicProduct['updatedAt'];
+    primaryMediaItemId?: ProductListingGroupsProductPrimaryMediaItemId;
+    variants?: (Omit<ProductListingGroupsProductVariants, 'docs'> & {
+        docs: ProductListingGroupVariant[];
+    }) | null;
 };
-type CancelOrderLegacyProviderRefundResponseFields = {
-    transactionId: string;
-    refundedAmount: number;
-    refundSeq: number;
-    providerRefunded: true;
+type ProductListingGroupsCatalogListing = {
+    minPrice?: NonNullable<ProductListingGroupsProduct['listing']>['minPrice'];
+    maxPrice?: NonNullable<ProductListingGroupsProduct['listing']>['maxPrice'];
+    minCompareAtPrice?: NonNullable<ProductListingGroupsProduct['listing']>['minCompareAtPrice'];
+    maxCompareAtPrice?: NonNullable<ProductListingGroupsProduct['listing']>['maxCompareAtPrice'];
+    isPriceRange?: NonNullable<ProductListingGroupsProduct['listing']>['isPriceRange'];
+    primaryImage?: NonNullable<ProductListingGroupsProduct['listing']>['primaryImage'];
+    availableForSale?: NonNullable<ProductListingGroupsProduct['listing']>['availableForSale'];
+    selectionHintVariant?: NonNullable<ProductListingGroupsProduct['listing']>['selectionHintVariant'];
+};
+type ProductListingGroupsCatalogProduct = {
+    id: string;
+    slug: string;
+    handle?: string | null;
+    title: string;
+    subtitle?: ProductListingGroupsProduct['subtitle'];
+    primaryMediaItemId?: ProductListingGroupsProductPrimaryMediaItemId;
+    thumbnail?: ProductListingGroupsProduct['thumbnail'];
+    images?: ProductListingGroupsProduct['images'];
+    listing?: ProductListingGroupsCatalogListing | null;
+    variants?: (Omit<NonNullable<ProductListingGroupsProduct['variants']>, 'docs'> & {
+        docs: ProductListingGroupCatalogVariant[];
+    }) | null;
 };
-type CancelOrderAlreadyCanceledResponseFields = {
-    refundedAmount: number;
-    providerRefunded: false;
+type ProductListingGroupsItem = {
+    product: ProductListingGroupsProduct;
+    groups: ProductListingGroupSummary[];
 };
-type CancelOrderAlreadyCanceledRefundPendingResponseFields = {
-    transactionId: string;
-    refundedAmount: number;
-    providerRefunded: false;
-    refundPending: true;
+type ProductListingGroupsCatalogItem = {
+    product: ProductListingGroupsCatalogProduct;
+    groups: ProductListingGroupCatalogSummary[];
 };
-type CancelOrderPaidCommittedResponse = CancelOrderResponseBase & CancelOrderPaidCommittedResponseFields & {
-    status: 'canceled';
-    cancelCommitted: true;
+type ProductListingGroupsResponse = {
+    /**
+     * Matching products in the same order as the requested productIds, excluding
+     * ids that were not found, not published, or not accessible for the current
+     * tenant/key.
+     */
+    docs: ProductListingGroupsItem[];
+    /** Requested productIds that could not be returned. */
+    missing: string[];
 };
-type CancelOrderUnpaidCommittedResponse = CancelOrderResponseBase & CancelOrderUnpaidCommittedResponseFields & {
-    status: 'canceled';
-    cancelCommitted: true;
+type ProductListingGroupsCatalogResponse = Omit<ProductListingGroupsResponse, 'docs'> & {
+    docs: ProductListingGroupsCatalogItem[];
+};
+type ProductListingPageSort = 'id' | '-id' | 'slug' | '-slug' | 'handle' | '-handle' | 'createdAt' | '-createdAt' | 'updatedAt' | '-updatedAt' | 'title' | '-title' | 'listing.minPrice' | '-listing.minPrice' | 'listing.maxPrice' | '-listing.maxPrice' | 'listing.availableForSale' | '-listing.availableForSale';
+type ProductListingPageFilters = {
+    ids?: string[];
+    slugs?: string[];
+    handles?: string[];
+    categoryIds?: string[];
+    tagIds?: string[];
+    price?: {
+        min?: number;
+        max?: number;
+    };
+    availableForSale?: boolean;
 };
-type CancelOrderCommittedResponse = CancelOrderPaidCommittedResponse | CancelOrderUnpaidCommittedResponse;
-type CancelOrderAlreadyCanceledResponse = CancelOrderResponseBase & CancelOrderAlreadyCanceledResponseFields & {
-    status: 'canceled';
-    cancelCommitted: false;
-    alreadyCanceled: true;
+type ProductListingPageBaseParams = {
+    page?: number;
+    limit?: number;
+    search?: string;
+    sort?: ProductListingPageSort | ProductListingPageSort[];
+    filters?: ProductListingPageFilters;
+} & ProductListingCardOptions;
+type ProductListingPageCatalogParams = ProductListingPageBaseParams & {
+    mode?: 'catalog';
 };
-type CancelOrderAlreadyCanceledRefundPendingResponse = CancelOrderResponseBase & CancelOrderAlreadyCanceledRefundPendingResponseFields & {
-    status: 'canceled';
-    cancelCommitted: false;
-    alreadyCanceled: true;
+type ProductListingPageFullParams = ProductListingPageBaseParams & {
+    mode: 'full';
 };
-/** @deprecated Inline PG cancel reconciliation; retained for legacy API consumers. */
-type CancelOrderReconciliationResponse = CancelOrderResponseBase & CancelOrderLegacyProviderRefundResponseFields & {
-    status: CancelOrderReconciliationStatus;
-    cancelCommitted: false;
-    reconciliationRequired: true;
+type ProductListingPageParams = ProductListingPageCatalogParams | ProductListingPageFullParams;
+type ProductListingPageResult<TItem> = PayloadFindResponse<TItem> & {
+    cards: ProductListingCard[];
 };
-type CancelOrderResponse = CancelOrderCommittedResponse | CancelOrderAlreadyCanceledResponse | CancelOrderAlreadyCanceledRefundPendingResponse | CancelOrderReconciliationResponse;
-type CancelOrderParams = {
-    orderNumber: string;
-    reasonCode?: CancelReasonCode;
-    reasonDetail?: string;
-    idempotencyKey?: string;
+type ProductDetailParams = {
+    slug: string;
+} | {
+    id: string;
 };
-type ResolveCancelRefundOutcome = 'succeeded' | 'failed';
-type ResolveCancelRefundSucceededParams = {
-    orderNumber: string;
-    idempotencyKey: string;
-    outcome: 'succeeded';
-    refundedAmount: number;
-    pgProvider: string;
-    pgRefundId: string;
+type ProductDetailPreviewParams = {
+    id: string;
 };
-type ResolveCancelRefundFailedParams = {
-    orderNumber: string;
-    idempotencyKey: string;
-    outcome: 'failed';
-    refundedAmount: 0;
-    pgProvider: string;
-    pgRefundId?: string;
+type ProductDetailPreviewOptions = {
+    previewToken: string;
 };
-type ResolveCancelRefundParams = ResolveCancelRefundSucceededParams | ResolveCancelRefundFailedParams;
-type ResolveCancelRefundSucceededResponse = {
-    orderId: string;
-    transactionId: string;
-    refundTransactionId: string;
-    refundedAmount: number;
-    refundStatus: 'succeeded';
-    transactionStatus: 'refunded';
+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;
 };
-type ResolveCancelRefundFailedResponse = {
-    orderId: string;
-    transactionId: string;
-    refundTransactionId: string;
-    refundedAmount: 0;
-    refundStatus: 'failed';
-    transactionStatus: 'paid';
+type ProductOptionValueColorSwatch = {
+    type: 'color';
+    color: string;
+    mediaItemId?: null;
+};
+type ProductOptionValueMediaSwatch<TMedia = ProductDetailMedia> = {
+    type: 'media';
+    mediaItemId: TMedia;
+    color?: null;
+};
+type ProductOptionValueSwatch<TMedia = ProductDetailMedia> = ProductOptionValueColorSwatch | ProductOptionValueMediaSwatch<TMedia> | null;
+type ProductDetailMediaValue = string | number | ProductDetailMedia | null;
+type ProductDetailSelectionMediaSource = 'variant_media_selected' | 'variant_media_matching' | 'option_swatch' | 'none';
+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[];
+    media?: {
+        primaryImage: ProductDetailMedia | null;
+        images: ProductDetailMedia[];
+        source: ProductDetailSelectionMediaSource;
+    };
+    optionValues: ProductDetailVariantOptionValue[];
+}
+interface ProductDetailOptionValue {
+    id: string | number;
+    value: string;
+    slug: string;
+    swatch?: ProductOptionValueSwatch<ProductDetailMedia>;
+}
+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;
+}
+type ProductDetailCatalogVariant = Omit<ProductDetailVariant, 'stock' | 'reservedStock'>;
+type ProductDetailCatalogListing = Omit<ProductDetailListing, 'availableForSale'> & {
+    liveStockRequired: true;
+};
+interface ProductDetailCatalog {
+    product: Omit<ProductDetail['product'], 'totalInventory'>;
+    variants: ProductDetailCatalogVariant[];
+    options: ProductDetail['options'];
+    brand: ProductDetail['brand'];
+    categories: ProductDetail['categories'];
+    tags: ProductDetail['tags'];
+    images: ProductDetail['images'];
+    videos: ProductDetail['videos'];
+    primaryMediaItemId?: ProductDetail['primaryMediaItemId'];
+    listing: ProductDetailCatalogListing;
+}
+type StockSnapshotItemStatus = 'available' | 'not_published' | 'archived' | 'not_found';
+interface StockSnapshotItem {
+    variantId: string;
+    status: StockSnapshotItemStatus;
+    availableStock: number;
+    availableForSale: boolean;
+    isUnlimited: boolean;
+}
+interface StockSnapshotResponse {
+    snapshots: StockSnapshotItem[];
+}
+type StockSnapshotParams = {
+    variantIds: string[];
 };
-type ResolveCancelRefundResponse = ResolveCancelRefundSucceededResponse | ResolveCancelRefundFailedResponse;
-type RestockAction = 'return_to_stock' | 'discard';
-type ReturnWithRefundItem = {
-    orderItem: string | number;
-    quantity: number;
-    restockAction?: RestockAction;
-    restockingFee?: number;
+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 | null;
+        totalVariants: number;
+        hasUnlimitedVariant: boolean;
+        hasOnlyDefaultVariant: boolean;
+    };
+    variants: ProductDetailVariant[];
+    options: ProductDetailOption[];
+    brand: ProductDetailBrand | null;
+    categories: ProductDetailCategory[];
+    tags: ProductDetailTag[];
+    images: ProductDetailImage[];
+    videos: ProductDetailVideo[];
+    /** Canonical product primary pointer (pool member). */
+    primaryMediaItemId?: ProductDetailMediaValue;
+    listing: ProductDetailListing;
+}
+type ProductDetailUnavailableReason = 'not_found' | 'not_published' | 'feature_disabled';
+type ProductDetailResult = {
+    found: true;
+    product: ProductDetail;
+} | {
+    found: false;
+    reason: ProductDetailUnavailableReason;
 };
-type ReturnWithRefundParams = WithIdempotencyKey<{
-    orderNumber: string;
-    reason?: ReturnReason;
-    reasonDetail?: string;
-    returnItems: ReturnWithRefundItem[];
-    refundAmount: number;
-    returnShippingFee?: number;
-    initialShippingRefundAmount?: number;
-    initialShippingRefundOverrideNote?: string;
-    pgPaymentId: string;
-    paymentKey?: string;
-    refundReceiptUrl?: string;
-}>;
-type CheckoutParams = WithIdempotencyKey<{
-    cartId: string;
-    orderNumber: string;
-    customerSnapshot: CustomerSnapshot;
-    pgPaymentId?: string;
-    discountCode?: string;
-}>;
-type CreateFulfillmentParams = WithIdempotencyKey<{
-    orderNumber: string;
-    fulfillmentOrderId?: string | number;
-    carrier?: string;
-    trackingNumber?: string;
-    items?: Array<{
-        orderItem: string;
-        quantity: number;
-    }>;
-}>;
-type PrepareFulfillmentOrderParams = {
-    orderNumber: string;
+type ProductDetailCatalogResult = {
+    found: true;
+    product: ProductDetailCatalog;
+} | {
+    found: false;
+    reason: ProductDetailUnavailableReason;
 };
-type PrepareFulfillmentOrderResponse = {
-    orderId: string;
-    fulfillmentOrders: Array<{
-        id: string;
-        status: string;
-    }>;
+type ProductUpsertParams = ProductUpsertInput;
+/** Console `POST /api/products/upsert` field allowlist error reasons. */
+declare const PRODUCT_UPSERT_UNKNOWN_FIELD_REASON: "unknown_field";
+declare const PRODUCT_UPSERT_READONLY_FIELD_REASON: "product_field_readonly";
+type ProductUpsertFieldValidationErrorReason = typeof PRODUCT_UPSERT_UNKNOWN_FIELD_REASON | typeof PRODUCT_UPSERT_READONLY_FIELD_REASON;
+/** 400 response body when upsert rejects unknown or server-managed product fields. */
+type ProductUpsertFieldValidationErrorBody = {
+    error: string;
+    reason: ProductUpsertFieldValidationErrorReason;
+    field: string;
+    requestId?: string;
 };
-type UpdateFulfillmentParams = {
-    fulfillmentId: string;
-    status?: 'shipped' | 'delivered' | 'failed';
-    carrier?: string;
-    trackingNumber?: string;
+declare function isProductUpsertFieldValidationErrorBody(value: unknown): value is ProductUpsertFieldValidationErrorBody;
+type ProductUpsertResponse = {
+    ok: true;
+    product: PublicProduct;
+    listingProjectionStale: boolean;
+} | {
+    ok: false;
+    failedEntity: 'product' | 'option' | 'option-value' | 'variant';
+    failedIndex?: number;
+    message: string;
 };
-type BulkImportFulfillmentsParams = {
-    items: Array<{
-        orderNumber: string;
-        carrier: string;
-        trackingNumber: string;
-    }>;
+declare class ProductApi extends BaseApi {
+    constructor(options: ProductApiOptions);
+    /**
+     * Check point-in-time stock availability for one or more product variants.
+     * Results reflect available stock at the moment of the call and are not guaranteed
+     * to remain available by the time an order is placed.
+     */
+    stockCheck(params: StockCheckParams): Promise<StockCheckResponse>;
+    stockSnapshot(params: StockSnapshotParams): Promise<StockSnapshotResponse>;
+    listingGroups(params: ListingGroupsParams): Promise<ProductListingGroupsResponse>;
+    listingGroupsCatalog(params: ListingGroupsParams): Promise<ProductListingGroupsCatalogResponse>;
+    listingPage(params?: ProductListingPageCatalogParams): Promise<ProductListingPageResult<ProductListingGroupsCatalogItem>>;
+    listingPage(params: ProductListingPageFullParams): Promise<ProductListingPageResult<ProductListingGroupsItem>>;
+    listingPage(params: ProductListingPageParams): Promise<ProductListingPageResult<ProductListingGroupsCatalogItem> | ProductListingPageResult<ProductListingGroupsItem>>;
+    /**
+     * Fetch full product detail by slug or id.
+     * Returns a discriminated result so storefronts can distinguish missing,
+     * unpublished, and feature-disabled products.
+     *
+     * Only product-detail 404 responses carrying one of those allowlisted reasons
+     * are mapped to `{ found: false, reason }`. Unknown or uncoded 404s, plus
+     * permission/auth errors such as tenant mismatch, continue to throw typed SDK
+     * errors instead of being collapsed into a storefront absence result.
+     */
+    detail(params: ProductDetailParams): Promise<ProductDetailResult>;
+    detailCatalog(params: ProductDetailParams): Promise<ProductDetailCatalogResult>;
+    /**
+     * 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;
+type ValidateDiscountParams = {
+    code: string;
+    orderAmount: number;
 };
-type BulkImportFulfillmentsResponse = {
-    succeeded: Array<{
-        orderNumber: string;
-        fulfillmentId: string;
-    }>;
-    failed: Array<{
-        orderNumber: string;
-        error: string;
-    }>;
+type ValidateDiscountResult = {
+    valid: boolean;
+    code: string;
+    type?: 'percentage' | 'fixed_amount' | 'free_shipping' | 'tiered';
+    discountAmount: number;
+    freeShipping?: boolean;
+    reason?: string;
 };
-type CreateReturnParams = WithIdempotencyKey<{
-    orderNumber: string;
-    reason?: ReturnReason;
-    reasonDetail?: string;
-    returnItems: ReturnItem[];
-    refundAmount: number;
-    returnShippingFee?: number;
-    initialShippingRefundAmount?: number;
-    initialShippingRefundOverrideNote?: string;
-}>;
-type UpdateReturnParams = {
-    returnId: string;
-    status: 'processing' | 'approved' | 'rejected' | 'completed';
+declare class DiscountApi extends BaseApi {
+    constructor(options: DiscountApiOptions);
+    validate(params: ValidateDiscountParams): Promise<ValidateDiscountResult>;
+}
+
+type ShippingApiOptions = ServerApiOptions;
+type CalculateShippingParams = {
+    shippingPolicyId?: string;
+    orderAmount: number;
+    postalCode?: string;
 };
-declare class OrderApi extends BaseApi {
-    constructor(options: OrderApiOptions);
-    createOrder(params: CreateOrderParams): Promise<Order>;
-    updateOrder(params: UpdateOrderParams): Promise<Order>;
-    updateTransaction(params: UpdateTransactionParams): Promise<Transaction>;
-    confirmPayment(params: ConfirmPaymentParams): Promise<ConfirmPaymentResponse>;
-    cancelOrder(params: CancelOrderParams): Promise<CancelOrderResponse>;
-    resolveCancelRefund(params: ResolveCancelRefundParams): Promise<ResolveCancelRefundResponse>;
-    checkout(params: CheckoutParams): Promise<Order>;
-    createFulfillment(params: CreateFulfillmentParams): Promise<Fulfillment>;
-    prepareFulfillmentOrder(params: PrepareFulfillmentOrderParams): Promise<PrepareFulfillmentOrderResponse>;
-    updateFulfillment(params: UpdateFulfillmentParams): Promise<Fulfillment>;
-    bulkImportFulfillments(params: BulkImportFulfillmentsParams): Promise<BulkImportFulfillmentsResponse>;
-    returnWithRefund(params: ReturnWithRefundParams): Promise<{
-        return: Return;
-        transaction: Transaction | null;
-    }>;
-    createReturn(params: CreateReturnParams): Promise<Return>;
-    updateReturn(params: UpdateReturnParams): Promise<Return>;
+type CalculateShippingResult = {
+    shippingAmount: number;
+    baseShippingAmount: number;
+    extraShippingAmount: number;
+    freeShipping: boolean;
+    freeShippingMinAmount: number | null;
+    isJeju: boolean;
+    isRemoteIsland: boolean;
+};
+declare class ShippingApi extends BaseApi {
+    constructor(options: ShippingApiOptions);
+    calculate(params: CalculateShippingParams): Promise<CalculateShippingResult>;
 }
 
 interface CommerceClientOptions {
@@ -1602,31 +1893,34 @@ declare class CommerceClient {
     readonly product: {
         stockCheck: (params: StockCheckParams) => Promise<StockCheckResponse>;
         stockSnapshot: (params: StockSnapshotParams) => Promise<StockSnapshotResponse>;
-        listingGroups: (params: ListingGroupsParams) => Promise<ProductListingGroupsResponse>;
-        listingGroupsCatalog: (params: ListingGroupsParams) => Promise<ProductListingGroupsResponse>;
+        listingGroups: (params: ListingGroupsParams) => Promise<ProductListingGroupsCatalogResponse>;
+        listingGroupsCatalog: (params: ListingGroupsParams) => Promise<ProductListingGroupsCatalogResponse>;
+        listingPage: {
+            (params?: ProductListingPageCatalogParams): Promise<ProductListingPageResult<ProductListingGroupsCatalogItem>>;
+        };
         detail: (params: ProductDetailParams) => Promise<ProductDetailResult>;
         detailCatalog: (params: ProductDetailParams) => Promise<ProductDetailCatalogResult>;
     };
     readonly cart: {
-        get: (cartId: string) => Promise<Cart>;
-        addItem: (params: AddItemParams) => Promise<CartItem>;
-        updateItem: (params: UpdateItemParams) => Promise<CartItem>;
+        get: (cartId: string) => Promise<PublicCart>;
+        addItem: (params: AddItemParams) => Promise<PublicCartItem>;
+        updateItem: (params: UpdateItemParams) => Promise<PublicCartItem>;
         removeItem: (params: RemoveItemParams) => Promise<{
             success: boolean;
         }>;
-        applyDiscount: (params: ApplyDiscountParams) => Promise<Cart>;
-        removeDiscount: (params: RemoveDiscountParams) => Promise<Cart>;
+        applyDiscount: (params: ApplyDiscountParams) => Promise<PublicCart>;
+        removeDiscount: (params: RemoveDiscountParams) => Promise<PublicCart>;
         clear: (params: ClearCartParams) => Promise<{
             success: boolean;
         }>;
     };
     readonly orders: {
-        checkout: (params: CheckoutParams) => Promise<Order>;
+        checkout: (params: CheckoutParams) => Promise<PublicOrder>;
         listMine: (options?: {
             page?: number;
             limit?: number;
             status?: string;
-        }) => Promise<PayloadFindResponse<Order>>;
+        }) => Promise<PayloadFindResponse<PublicOrder>>;
     };
     readonly discounts: {
         validate: (params: ValidateDiscountParams) => Promise<ValidateDiscountResult>;
@@ -1637,6 +1931,85 @@ declare class CommerceClient {
     constructor(options: CommerceClientOptions);
 }
 
+type StorefrontContentReference = {
+    id?: string | number | null;
+    title?: string | null;
+    name?: string | null;
+    slug?: string | null;
+    displayName?: string | null;
+    handle?: string | null;
+    color?: string | null;
+    image?: PublicMediaAsset | null;
+    thumbnail?: PublicMediaAsset | null;
+    avatar?: PublicMediaAsset | null;
+};
+type StorefrontLink = {
+    id?: string | number | null;
+    title?: string | null;
+    subtitle?: string | null;
+    url?: string | null;
+    description?: string | null;
+    slug?: string | null;
+    type?: 'external' | 'social' | 'internal' | string | null;
+    platform?: string | null;
+    opensInNewTab?: boolean | null;
+    noFollow?: boolean | null;
+    expiresAt?: string | null;
+    isFeatured?: boolean | null;
+    publishedAt?: string | null;
+    createdAt?: string | null;
+    updatedAt?: string | null;
+    categories?: StorefrontContentReference[] | StorefrontContentReference | null;
+    tags?: StorefrontContentReference[] | StorefrontContentReference | null;
+    thumbnail?: PublicMediaAsset | null;
+    icon?: PublicMediaAsset | null;
+};
+type StorefrontGalleryItem = {
+    id?: string | number | null;
+    title?: string | null;
+    description?: string | null;
+    content?: unknown;
+    createdAt?: string | null;
+    updatedAt?: string | null;
+    gallery?: StorefrontContentReference | string | null;
+    image?: PublicMediaAsset | null;
+};
+type StorefrontLinksSort = 'createdAt' | '-createdAt' | 'updatedAt' | '-updatedAt' | 'publishedAt' | '-publishedAt' | 'title' | '-title' | 'isFeatured' | '-isFeatured';
+type StorefrontGalleryItemsSort = 'manual' | 'createdAt' | '-createdAt' | 'updatedAt' | '-updatedAt' | 'title' | '-title';
+type StorefrontContentListOptions<TSort extends string = string> = {
+    page?: number;
+    limit?: number;
+    sort?: TSort;
+};
+type StorefrontLinksListOptions = StorefrontContentListOptions<StorefrontLinksSort> & {
+    categoryId?: string;
+    categorySlug?: string;
+    tagId?: string;
+    tagSlug?: string;
+    featured?: boolean;
+};
+type StorefrontGalleryItemsListOptions = StorefrontContentListOptions<StorefrontGalleryItemsSort> & ({
+    galleryId: string;
+    gallerySlug?: string;
+} | {
+    galleryId?: string;
+    gallerySlug: string;
+});
+type ContentClientOptions = {
+    publishableKey: string;
+    apiUrl?: string;
+    onRequestId?: (id: string | null) => void;
+};
+declare class ContentClient {
+    readonly links: {
+        list: (options?: StorefrontLinksListOptions) => Promise<PayloadFindResponse<StorefrontLink>>;
+    };
+    readonly galleryItems: {
+        list: (options: StorefrontGalleryItemsListOptions) => Promise<PayloadFindResponse<StorefrontGalleryItem>>;
+    };
+    constructor(options: ContentClientOptions);
+}
+
 interface ServerCommerceClientOptions {
     publishableKey?: string;
     secretKey: string;
@@ -1647,25 +2020,30 @@ declare class ServerCommerceClient {
     readonly product: {
         stockCheck: (params: StockCheckParams) => Promise<StockCheckResponse>;
         listingGroups: (params: ListingGroupsParams) => Promise<ProductListingGroupsResponse>;
+        listingPage: {
+            (params?: ProductListingPageCatalogParams): Promise<ProductListingPageResult<ProductListingGroupsCatalogItem>>;
+            (params: ProductListingPageFullParams): Promise<ProductListingPageResult<ProductListingGroupsItem>>;
+            (params: ProductListingPageParams): Promise<ProductListingPageResult<ProductListingGroupsCatalogItem> | ProductListingPageResult<ProductListingGroupsItem>>;
+        };
         detail: (params: ProductDetailParams) => Promise<ProductDetailResult>;
         previewDetail: (params: ProductDetailPreviewParams, options: ProductDetailPreviewOptions) => Promise<ProductDetail | null>;
         upsert: (params: ProductUpsertParams) => Promise<ProductUpsertResponse>;
     };
     readonly cart: {
-        get: (cartId: string) => Promise<Cart>;
-        addItem: (params: AddItemParams) => Promise<CartItem>;
-        updateItem: (params: UpdateItemParams) => Promise<CartItem>;
+        get: (cartId: string) => Promise<PublicCart>;
+        addItem: (params: AddItemParams) => Promise<PublicCartItem>;
+        updateItem: (params: UpdateItemParams) => Promise<PublicCartItem>;
         removeItem: (params: RemoveItemParams) => Promise<{
             success: boolean;
         }>;
-        applyDiscount: (params: ApplyDiscountParams) => Promise<Cart>;
-        removeDiscount: (params: RemoveDiscountParams) => Promise<Cart>;
+        applyDiscount: (params: ApplyDiscountParams) => Promise<PublicCart>;
+        removeDiscount: (params: RemoveDiscountParams) => Promise<PublicCart>;
         clear: (params: ClearCartParams) => Promise<{
             success: boolean;
         }>;
     };
     readonly orders: {
-        checkout: (params: CheckoutParams) => Promise<Order>;
+        checkout: (params: CheckoutParams) => Promise<PublicOrder>;
         create: (params: CreateOrderParams) => Promise<Order>;
         update: (params: UpdateOrderParams) => Promise<Order>;
         updateTransaction: (params: UpdateTransactionParams) => Promise<Transaction>;
@@ -2085,6 +2463,20 @@ interface ApiQueryOptions {
     /** Include soft-deleted documents (requires `trash` enabled on the collection) */
     trash?: boolean;
 }
+type PublicReadQueryOptions = Omit<ApiQueryOptions, 'depth' | 'joins' | 'populate'> & {
+    /**
+     * Publishable collection reads stay unpopulated. Use shaped commerce/community
+     * endpoints or a server client when populated relations are required.
+     */
+    depth?: 0;
+    /**
+     * Publishable collection reads disable Payload join fields to avoid accidental
+     * exposure and expensive generic list responses.
+     */
+    joins?: false;
+    /** Publishable collection reads do not support relationship populate maps. */
+    populate?: never;
+};
 interface DebugConfig {
     logRequests?: boolean;
     logResponses?: boolean;
@@ -2095,14 +2487,14 @@ interface RetryConfig {
     retryableStatuses?: number[];
     retryDelay?: (attempt: number) => number;
 }
-interface RootQueryLookup<T extends string> {
-    find(options?: ApiQueryOptions): Promise<PayloadFindResponse<CollectionType<T>>>;
-    findById(id: string | number, options?: ApiQueryOptions): Promise<CollectionType<T>>;
-    count(options?: ApiQueryOptions): Promise<{
+interface RootQueryLookup<T extends string, Options extends ApiQueryOptions = ApiQueryOptions> {
+    find(options?: Options): Promise<PayloadFindResponse<CollectionType<T>>>;
+    findById(id: string | number, options?: Options): Promise<CollectionType<T>>;
+    count(options?: Options): Promise<{
         totalDocs: number;
     }>;
 }
-type RootReadOnlyQueryBuilder<T extends PublicCollection> = RootQueryLookup<T>;
+type RootReadOnlyQueryBuilder<T extends PublicCollection> = RootQueryLookup<T, PublicReadQueryOptions>;
 interface RootServerQueryBuilder<T extends ServerCollection> extends RootQueryLookup<T> {
     create(data: Partial<CollectionType<T>>, options?: {
         file?: File | Blob;
@@ -2125,6 +2517,7 @@ interface RootServerCollectionClient {
 interface RootClient {
     commerce: CommerceClient;
     community: CommunityClient;
+    content: ContentClient;
     /** Set on {@link createClient} return values; optional for structural mocks. */
     events?: EventsClient;
     customer: CustomerNamespace;
@@ -2162,4 +2555,4 @@ type DeepPartial<T> = {
 };
 type ExtractArrayType<T> = T extends (infer U)[] ? U : never;
 
-export { type TenantFeatureProgressGroup as $, type ApiQueryOptions as A, BaseApi as B, CommerceClient as C, type DebugConfig as D, EventsClient as E, type EventRegistrationRegisterResponse as F, type EventsCalendarItem as G, type EventsClientOptions as H, type EventsDateParam as I, type EventsExternalSource as J, type EventsLocation as K, type EventsOccurrenceLocation as L, type EventsRangeEvent as M, type EventsRangeOccurrence as N, type EventsRangeParams as O, type PayloadFindResponse as P, type EventsRangeResponse as Q, type RetryConfig as R, type Sort as S, type TenantIntrospectionClient as T, type UnbanCustomerParams as U, type EventsTaxonomyItem as V, type Where as W, ModerationApi as X, type RootServerClient as Y, type TenantFeatureProgressEvidenceValue as Z, type TenantFeatureProgressFeature as _, CommunityClient as a, type ListingGroupsParams as a$, type TenantFeatureProgressInput as a0, type TenantFeatureProgressItem as a1, type TenantFeatureProgressItemState as a2, type TenantFeatureProgressResponse as a3, type TenantFeatureProgressSeverity as a4, type TenantFeatureProgressStatus as a5, TenantIntrospectionApi as a6, type TenantIntrospectionApiOptions as a7, CustomerAuth as a8, type CustomerProfile as a9, type CancelOrderResponse as aA, type CancelReasonCode as aB, CartApi as aC, type CartApiOptions as aD, type CheckoutParams as aE, type ClearCartParams as aF, type Comment as aG, type CommerceClientOptions as aH, type CommunityClientOptions as aI, type CommunityComment as aJ, type CommunityCommentListSort as aK, type CommunityPost as aL, type CommunityPostCategory as aM, type CommunityPostListSort as aN, type CommunityPostTag as aO, type CompatibilityProductSelectionParamEvent as aP, type ConfirmPaymentParams as aQ, type ConfirmPaymentResponse as aR, type CreateFulfillmentParams as aS, type CreateOrderItem as aT, type CreateOrderParams as aU, type CreateReturnParams as aV, type CustomerAuthOptions as aW, type CustomerSnapshot as aX, DiscountApi as aY, type DiscountApiOptions as aZ, type LegacyProductSelectionParamEvent as a_, type CustomerAuthResponse as aa, type CustomerLoginData as ab, type CustomerRegisterResponse as ac, type CustomerRegisterData as ad, type CustomerRefreshResponse as ae, type UpdateProfileData as af, type ProductDetailParams as ag, type ProductDetailResult as ah, type ProductListingGroupsItem as ai, type ProductDetail as aj, type ProductDetailCatalog as ak, type StockSnapshotResponse as al, type ProductSelectionMediaSource as am, type ProductDisplayMediaSource as an, type ResolveProductSelectionMediaInput as ao, type ResolveProductSelectionMediaResult as ap, type ProductSelectionMediaPointer as aq, type RootClientWithEvents as ar, type AddItemParams as as, type ApplyDiscountParams as at, type BulkImportFulfillmentsParams as au, type BulkImportFulfillmentsResponse as av, type CalculateShippingParams as aw, type CalculateShippingResult as ax, type CancelOrderParams as ay, type CancelOrderReconciliationStatus as az, CustomerNamespace as b, type ProductSelectionVariant as b$, type ListingPrimaryImageFallbackInput as b0, type MediaValue as b1, type NormalizedOptionSwatch as b2, type NormalizedProductSelection as b3, OrderApi as b4, type OrderApiOptions as b5, PRODUCT_PLP_FIND_OPTIONS as b6, PRODUCT_UPSERT_READONLY_FIELD_REASON as b7, PRODUCT_UPSERT_UNKNOWN_FIELD_REASON as b8, type PrepareFulfillmentOrderParams as b9, type ProductListingGroup as bA, type ProductListingGroupSummary as bB, type ProductListingGroupVariant as bC, type ProductListingGroupsProduct as bD, type ProductListingGroupsResponse as bE, type ProductListingProductShape as bF, type ProductListingProjection as bG, type ProductListingSwatch as bH, type ProductMediaResolutionSource as bI, type ProductOptionMatrix as bJ, type ProductOptionMatrixOption as bK, type ProductOptionMatrixValue as bL, type ProductOptionMatrixVariant as bM, type ProductOptionShape as bN, type ProductOptionValueShape as bO, type ProductOptionValueSwatch as bP, type ProductOptionValueSwatchInput as bQ, type ProductSelectionAvailableSwatch as bR, type ProductSelectionAvailableValue as bS, type ProductSelectionByOptionValue as bT, ProductSelectionCodecError as bU, type ProductSelectionCodecOptions as bV, type ProductSelectionInput as bW, type ProductSelectionOptionValue as bX, type ProductSelectionResolution as bY, type ProductSelectionResolutionContext as bZ, type ProductSelectionUrlEmit as b_, type PrepareFulfillmentOrderResponse as ba, ProductApi as bb, type ProductApiOptions as bc, type ProductDetailBrand as bd, type ProductDetailCatalogListing as be, type ProductDetailCatalogResult as bf, type ProductDetailCatalogVariant as bg, type ProductDetailCategory as bh, type ProductDetailImage as bi, type ProductDetailImageMedia as bj, type ProductDetailListing as bk, type ProductDetailMedia as bl, type ProductDetailOption as bm, type ProductDetailOptionValue as bn, type ProductDetailTag as bo, type ProductDetailUnavailableReason as bp, type ProductDetailVariant as bq, type ProductDetailVariantOptionValue as br, type ProductDetailVideo as bs, type ProductHrefGroup as bt, type ProductHrefOptions as bu, type ProductHrefProduct as bv, type ProductListingCard as bw, type ProductListingCardOptions as bx, type ProductListingCardPriceRange as by, type ProductListingCardRepresentativeVariant as bz, type ClientState as c, type ProductUpsertFieldValidationErrorBody as c0, type ProductUpsertFieldValidationErrorReason as c1, type ProductVariantShape as c2, type RemoveDiscountParams as c3, type RemoveItemParams as c4, type RequestOptions as c5, type ResolveCancelRefundFailedResponse as c6, type ResolveCancelRefundOutcome as c7, type ResolveCancelRefundParams as c8, type ResolveCancelRefundResponse as c9, buildProductOptionMatrix as cA, buildProductOptionMatrixFromDetail as cB, createProductSelectionCodec as cC, getAvailableOptionValues as cD, getProductSelectionImages as cE, getSelectedValueByOptionId as cF, isProductUpsertFieldValidationErrorBody as cG, normalizeProductSelection as cH, normalizeProductSelectionFromMatrix as cI, normalizeSelectedValueIds as cJ, parseProductSelection as cK, resolveListingPrimaryImagePointer as cL, resolveProductDisplayMedia as cM, resolveProductSelection as cN, resolveProductSelectionFromMatrix as cO, resolveProductSelectionMedia as cP, resolveVariantForSelection as cQ, selectNext as cR, selectedSwatchMediaItemId as cS, stringifyProductSelection as cT, toShopifyPriceRangeV2 as cU, type ResolveCancelRefundSucceededResponse as ca, type ResolveProductDisplayMediaInput as cb, type ResolveProductDisplayMediaResult as cc, type ReturnItem as cd, type ReturnReason as ce, type ReturnWithRefundItem as cf, type ReturnWithRefundParams as cg, ShippingApi as ch, type ShippingApiOptions as ci, type StockCheckParams as cj, type StockCheckResponse as ck, type StockCheckResult as cl, type StockSnapshotItem as cm, type StockSnapshotParams as cn, type UpdateFulfillmentParams as co, type UpdateItemParams as cp, type UpdateOrderParams as cq, type UpdateReturnParams as cr, type UpdateTransactionParams as cs, type ValidateDiscountParams as ct, type ValidateDiscountResult as cu, type WithIdempotencyKey as cv, buildProductHref as cw, buildProductListingCard as cx, buildProductListingGroupsByOption as cy, buildProductListingProjection as cz, type ClientConfig as d, type ClientMetadata as e, type DeepPartial as f, type ExtractArrayType as g, type PayloadMutationResponse as h, type RootClient as i, type RootCollectionClient as j, type RootReadOnlyQueryBuilder as k, type ServerApiOptions as l, ServerCommerceClient as m, type BanCustomerParams as n, type CommunityBan as o, type ClientServerConfig as p, type RootServerClientWithEvents as q, type CollectionFieldSchema as r, type CollectionSchemaResponse as s, type EventGuestCancelParams as t, type EventGuestRegistration as u, type EventGuestRegistrationResponse as v, type EventRegistrationAnswerInput as w, type EventRegistrationAttendeeInput as x, type EventRegistrationPublic as y, type EventRegistrationRegisterParams as z };
+export { type CollectionFieldSchema as $, type AddItemParams as A, type RootReadOnlyQueryBuilder as B, CommerceClient as C, type DebugConfig as D, EventsClient as E, type StorefrontContentListOptions as F, type StorefrontContentReference as G, type StorefrontGalleryItem as H, type StorefrontGalleryItemsListOptions as I, type StorefrontGalleryItemsSort as J, type StorefrontLink as K, type StorefrontLinksListOptions as L, type StorefrontLinksSort as M, BaseApi as N, type ServerApiOptions as O, type PayloadFindResponse as P, ServerCommerceClient as Q, type RemoveDiscountParams as R, type Sort as S, type TenantIntrospectionClient as T, type UpdateItemParams as U, type BanCustomerParams as V, type Where as W, type CommunityBan as X, type UnbanCustomerParams as Y, type ClientServerConfig as Z, type RootServerClientWithEvents as _, CommunityClient as a, type CalculateShippingResult as a$, type CollectionSchemaResponse as a0, type EventGuestCancelParams as a1, type EventGuestRegistration as a2, type EventGuestRegistrationResponse as a3, type EventRegistrationAnswerInput as a4, type EventRegistrationAttendeeInput as a5, type EventRegistrationPublic as a6, type EventRegistrationRegisterParams as a7, type EventRegistrationRegisterResponse as a8, type EventsCalendarItem as a9, type CustomerAuthResponse as aA, type CustomerLoginData as aB, type CustomerRegisterResponse as aC, type CustomerRegisterData as aD, type CustomerRefreshResponse as aE, type UpdateProfileData as aF, type ProductListingPageBaseParams as aG, type ProductListingPageParams as aH, type ProductDetailParams as aI, type ProductDetailResult as aJ, type ProductListingPageCatalogParams as aK, type ProductListingPageResult as aL, type ProductListingGroupsCatalogItem as aM, type ProductListingPageFullParams as aN, type ProductListingGroupsItem as aO, type ProductDetail as aP, type ProductDetailCatalog as aQ, type StockSnapshotResponse as aR, type ProductSelectionMediaSource as aS, type ProductDisplayMediaSource as aT, type ResolveProductSelectionMediaInput as aU, type ResolveProductSelectionMediaResult as aV, type ProductSelectionMediaPointer as aW, type RootClientWithEvents as aX, type BulkImportFulfillmentsParams as aY, type BulkImportFulfillmentsResponse as aZ, type CalculateShippingParams as a_, type EventsClientOptions as aa, type EventsDateParam as ab, type EventsExternalSource as ac, type EventsLocation as ad, type EventsOccurrenceLocation as ae, type EventsRangeEvent as af, type EventsRangeOccurrence as ag, type EventsRangeParams as ah, type EventsRangeResponse as ai, type EventsTaxonomyItem as aj, ModerationApi as ak, type RootServerClient as al, type TenantFeatureProgressEvidenceValue as am, type TenantFeatureProgressFeature as an, type TenantFeatureProgressGroup as ao, type TenantFeatureProgressInput as ap, type TenantFeatureProgressItem as aq, type TenantFeatureProgressItemState as ar, type TenantFeatureProgressResponse as as, type TenantFeatureProgressSeverity as at, type TenantFeatureProgressStatus as au, TenantIntrospectionApi as av, type TenantIntrospectionApiOptions as aw, type PublicReadQueryOptions as ax, CustomerAuth as ay, type CustomerProfile as az, ContentClient as b, type ProductListingCard as b$, type CancelOrderParams as b0, type CancelOrderReconciliationStatus as b1, type CancelOrderResponse as b2, type CancelReasonCode as b3, CartApi as b4, type CartApiOptions as b5, type Comment as b6, type CommerceClientOptions as b7, type CommunityClientOptions as b8, type CommunityComment as b9, type OrderApiOptions as bA, PRODUCT_PLP_FIND_OPTIONS as bB, PRODUCT_UPSERT_READONLY_FIELD_REASON as bC, PRODUCT_UPSERT_UNKNOWN_FIELD_REASON as bD, type PrepareFulfillmentOrderParams as bE, type PrepareFulfillmentOrderResponse as bF, ProductApi as bG, type ProductApiOptions as bH, type ProductDetailBrand as bI, type ProductDetailCatalogListing as bJ, type ProductDetailCatalogResult as bK, type ProductDetailCatalogVariant as bL, type ProductDetailCategory as bM, type ProductDetailImage as bN, type ProductDetailImageMedia as bO, type ProductDetailListing as bP, type ProductDetailMedia as bQ, type ProductDetailOption as bR, type ProductDetailOptionValue as bS, type ProductDetailTag as bT, type ProductDetailUnavailableReason as bU, type ProductDetailVariant as bV, type ProductDetailVariantOptionValue as bW, type ProductDetailVideo as bX, type ProductHrefGroup as bY, type ProductHrefOptions as bZ, type ProductHrefProduct as b_, type CommunityCommentListSort as ba, type CommunityPost as bb, type CommunityPostCategory as bc, type CommunityPostListSort as bd, type CommunityPostTag as be, type CommunityPublicAuthorSnapshot as bf, type CommunityPublicMediaAsset as bg, type CommunityPublicReference as bh, type CompatibilityProductSelectionParamEvent as bi, type ConfirmPaymentParams as bj, type ConfirmPaymentResponse as bk, type CreateFulfillmentParams as bl, type CreateOrderItem as bm, type CreateOrderParams as bn, type CreateReturnParams as bo, type CustomerAuthOptions as bp, type CustomerSnapshot as bq, DiscountApi as br, type DiscountApiOptions as bs, type LegacyProductSelectionParamEvent as bt, type ListingGroupsParams as bu, type ListingPrimaryImageFallbackInput as bv, type MediaValue as bw, type NormalizedOptionSwatch as bx, type NormalizedProductSelection as by, OrderApi as bz, CustomerNamespace as c, type UpdateTransactionParams as c$, type ProductListingCardOptions as c0, type ProductListingCardPriceRange as c1, type ProductListingCardRepresentativeVariant as c2, type ProductListingGroup as c3, type ProductListingGroupCatalogSummary as c4, type ProductListingGroupCatalogVariant as c5, type ProductListingGroupSummary as c6, type ProductListingGroupVariant as c7, type ProductListingGroupsCatalogListing as c8, type ProductListingGroupsCatalogProduct as c9, type ProductSelectionUrlEmit as cA, type ProductSelectionVariant as cB, type ProductUpsertFieldValidationErrorBody as cC, type ProductUpsertFieldValidationErrorReason as cD, type ProductVariantShape as cE, type RequestOptions as cF, type ResolveCancelRefundFailedResponse as cG, type ResolveCancelRefundOutcome as cH, type ResolveCancelRefundParams as cI, type ResolveCancelRefundResponse as cJ, type ResolveCancelRefundSucceededResponse as cK, type ResolveProductDisplayMediaInput as cL, type ResolveProductDisplayMediaResult as cM, type ReturnItem as cN, type ReturnReason as cO, type ReturnWithRefundItem as cP, type ReturnWithRefundParams as cQ, ShippingApi as cR, type ShippingApiOptions as cS, type StockCheckParams as cT, type StockCheckResponse as cU, type StockCheckResult as cV, type StockSnapshotItem as cW, type StockSnapshotParams as cX, type UpdateFulfillmentParams as cY, type UpdateOrderParams as cZ, type UpdateReturnParams as c_, type ProductListingGroupsCatalogResponse as ca, type ProductListingGroupsProduct as cb, type ProductListingGroupsResponse as cc, type ProductListingPageFilters as cd, type ProductListingPageSort as ce, type ProductListingProductShape as cf, type ProductListingProjection as cg, type ProductListingSwatch as ch, type ProductMediaResolutionSource as ci, type ProductOptionMatrix as cj, type ProductOptionMatrixOption as ck, type ProductOptionMatrixValue as cl, type ProductOptionMatrixVariant as cm, type ProductOptionShape as cn, type ProductOptionValueShape as co, type ProductOptionValueSwatch as cp, type ProductOptionValueSwatchInput as cq, type ProductSelectionAvailableSwatch as cr, type ProductSelectionAvailableValue as cs, type ProductSelectionByOptionValue as ct, ProductSelectionCodecError as cu, type ProductSelectionCodecOptions as cv, type ProductSelectionInput as cw, type ProductSelectionOptionValue as cx, type ProductSelectionResolution as cy, type ProductSelectionResolutionContext as cz, type ClientState as d, type ValidateDiscountParams as d0, type ValidateDiscountResult as d1, type WithIdempotencyKey as d2, buildProductHref as d3, buildProductListingCard as d4, buildProductListingGroupsByOption as d5, buildProductListingProjection as d6, buildProductOptionMatrix as d7, buildProductOptionMatrixFromDetail as d8, createProductSelectionCodec as d9, getAvailableOptionValues as da, getProductSelectionImages as db, getSelectedValueByOptionId as dc, isProductUpsertFieldValidationErrorBody as dd, normalizeProductSelection as de, normalizeProductSelectionFromMatrix as df, normalizeSelectedValueIds as dg, parseProductSelection as dh, resolveListingPrimaryImagePointer as di, resolveProductDisplayMedia as dj, resolveProductSelection as dk, resolveProductSelectionFromMatrix as dl, resolveProductSelectionMedia as dm, resolveVariantForSelection as dn, selectNext as dp, selectedSwatchMediaItemId as dq, stringifyProductSelection as dr, toShopifyPriceRangeV2 as ds, type ClientConfig as e, type ApiQueryOptions as f, type ApplyDiscountParams as g, type CheckoutParams as h, type ClearCartParams as i, type ClientMetadata as j, type ContentClientOptions as k, type DeepPartial as l, type ExtractArrayType as m, type PayloadMutationResponse as n, type PublicCart as o, type PublicCartItem as p, type PublicCartReference as q, type PublicMediaAsset as r, type PublicMediaSize as s, type PublicOrder as t, type PublicOrderItem as u, type PublicOrderReference as v, type RemoveItemParams as w, type RetryConfig as x, type RootClient as y, type RootCollectionClient as z };