@01.software/sdk 0.36.0 → 0.38.0

package/dist/{types-DK9EnLwJ.d.ts → types-D2xYdz4P.d.ts}

@@ -1,7 +1,36 @@
-import { P as PublicCollection, S as ServerCollection } from './const-BDUKFP9w.js';
-import { C as CollectionType, P as PublicProduct } from './types-3qV6sY7T.js';
-import { O as Order, i as Cart, j as CartItem, m as Transaction, n as Fulfillment, o as Return } from './payload-types-BCui2Oml.js';
+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;
+    secretKey?: string;
+    apiUrl?: string;
+    customerToken?: string | (() => string | null);
+    onUnauthorized?: () => Promise<string | null>;
+    onRequestId?: (id: string | null) => void;
+    requiresCredential?: boolean;
+}
+interface CustomerScopedRequestOptions {
+    method: 'GET' | 'POST' | 'PATCH' | 'DELETE';
+    body?: unknown;
+    headers?: Record<string, string>;
+}
+declare class CustomerScopedApi {
+    private readonly publishableKey;
+    private readonly secretKey?;
+    private readonly apiUrl?;
+    private readonly customerToken?;
+    private readonly onUnauthorized?;
+    private readonly onRequestId?;
+    constructor(apiName: string, options: CustomerScopedApiOptions);
+    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;
@@ -10,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`. */
@@ -24,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 {
@@ -37,8 +139,9 @@ interface ReactionSummary {
 }
 interface Bookmark {
     id: string;
-    post?: string;
+    post?: string | CommunityPost | null;
     createdAt?: string;
+    updatedAt?: string;
     [key: string]: unknown;
 }
 interface ReactionType {
@@ -60,24 +163,23 @@ interface PaginatedResponse<T> {
     prevPage: number | null;
     nextPage: number | null;
 }
-declare class CommunityClient {
-    private readonly publishableKey;
-    private readonly secretKey?;
-    private readonly apiUrl?;
-    private readonly customerToken?;
-    private readonly onUnauthorized?;
-    private readonly onRequestId?;
+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;
     private buildPostsListQuery;
     private buildCommentsListQuery;
     private execute;
+    private executeDoc;
     createPost(params: {
         title?: string | null;
         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).
@@ -123,7 +225,7 @@ declare class CommunityClient {
         postId: string;
         body: string;
         parentId?: string;
-    }): Promise<CommunityComment>;
+    }): Promise<CommunityCommentMutationResponse>;
     /**
      * List comments for a post.
      *
@@ -149,12 +251,10 @@ declare class CommunityClient {
     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;
@@ -167,7 +267,7 @@ declare class CommunityClient {
         typeSlug?: string;
         /** @deprecated Use `typeSlug`. */
         type?: string;
-    }): Promise<Reaction>;
+    }): Promise<CommunityReactionMutationResponse>;
     removeReaction(params: {
         postId: string;
         type: string;
@@ -179,7 +279,7 @@ declare class CommunityClient {
         typeSlug?: string;
         /** @deprecated Use `typeSlug`. */
         type?: string;
-    }): Promise<Reaction>;
+    }): Promise<CommunityReactionMutationResponse>;
     removeCommentReaction(params: {
         commentId: string;
         type: string;
@@ -195,7 +295,7 @@ declare class CommunityClient {
     getReactionTypes(): Promise<PaginatedResponse<ReactionType>>;
     addBookmark(params: {
         postId: string;
-    }): Promise<Bookmark>;
+    }): Promise<CommunityBookmarkMutationResponse>;
     removeBookmark(params: {
         postId: string;
     }): Promise<{
@@ -270,799 +370,1057 @@ 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;
+    orderItems?: never;
 };
-type UpdateItemParams = {
-    cartItemId: string;
-    quantity: number;
-};
-type RemoveItemParams = {
-    cartItemId: string;
-};
-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 {
-    private readonly publishableKey;
-    private readonly secretKey?;
-    private readonly apiUrl?;
-    private readonly customerToken?;
-    private readonly onUnauthorized?;
-    private readonly onRequestId?;
-    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 ResolveCancelRefundFailedResponse = {
+    orderId: string;
+    transactionId: string;
+    refundTransactionId: string;
+    refundedAmount: 0;
+    refundStatus: 'failed';
+    transactionStatus: 'paid';
 };
-type ProductListingSwatch = {
-    optionId: EntityID;
-    optionValueId: EntityID;
-    label: string;
-    swatch: ProductOptionValueSwatch<ProductDetailMedia>;
-    href: string;
-    availableForSale: boolean;
+type ResolveCancelRefundResponse = ResolveCancelRefundSucceededResponse | ResolveCancelRefundFailedResponse;
+type RestockAction = 'return_to_stock' | 'discard';
+type ReturnWithRefundItem = {
+    orderItem: string | number;
+    quantity: number;
+    restockAction?: RestockAction;
+    restockingFee?: number;
 };
-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 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 ProductSelectionByOptionValue = string | number | null | undefined | {
-    valueId?: string | number | null;
-    valueSlug?: string | null;
+type PrepareFulfillmentOrderResponse = {
+    orderId: string;
+    fulfillmentOrders: Array<{
+        id: string;
+        status: string;
+    }>;
 };
-type ProductSelectionInput = {
-    variantId?: string | number | null;
-    byOptionSlug?: Record<string, ProductSelectionByOptionValue>;
-    byOptionId?: Record<string, ProductSelectionByOptionValue>;
-    valueIds?: Iterable<unknown>;
-    search?: string | URLSearchParams | URL | null;
+type UpdateFulfillmentParams = {
+    fulfillmentId: string;
+    status?: 'shipped' | 'delivered' | 'failed';
+    carrier?: string;
+    trackingNumber?: string;
 };
-type NormalizedProductSelection = {
-    byOptionSlug: Record<string, string>;
-    byOptionId: Record<string, string>;
-    valueIds: string[];
-    variantId: string | null;
+type BulkImportFulfillmentsParams = {
+    items: Array<{
+        orderNumber: string;
+        carrier: string;
+        trackingNumber: string;
+    }>;
 };
-type CompatibilityProductSelectionParamEvent = {
-    optionId: string;
-    optionSlug: string;
-    valueSlug: string;
-    searchParam: string;
+type BulkImportFulfillmentsResponse = {
+    succeeded: Array<{
+        orderNumber: string;
+        fulfillmentId: string;
+    }>;
+    failed: Array<{
+        orderNumber: string;
+        error: string;
+    }>;
 };
-type LegacyProductSelectionParamEvent = CompatibilityProductSelectionParamEvent;
-type ProductSelectionUrlEmit = 'slug-compat' | 'canonical-id';
-type ProductSelectionCodecOptions = {
-    emit?: ProductSelectionUrlEmit;
+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 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 {
     /**
-     * When true, `resolveProductSelection()` fills unselected options to reach a
-     * concrete variant. Does not change codec parse/stringify behavior.
+     * 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.
      */
-    fillDefaults?: boolean;
-    onCompatibilityOptionIdParam?: (event: CompatibilityProductSelectionParamEvent) => void;
-    onLegacyOptionIdParam?: (event: LegacyProductSelectionParamEvent) => void;
+    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;
+}
+
+/**
+ * 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>;
+    /**
+     * 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;
+}
+
+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;
+};
+type ApplyDiscountParams = {
+    cartId: string;
+    discountCode: string;
+};
+type RemoveDiscountParams = {
+    cartId: string;
+};
+type ClearCartParams = {
+    cartId: string;
+};
+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;
+};
+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[];
+};
+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;
+};
+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 ProductSelectionOptionValue = {
+    id?: string | number | null;
+    swatch?: NormalizedOptionSwatch<unknown> | null;
+};
+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 ProductSelectionResolutionContext = {
-    detail?: Pick<ProductDetail, 'images' | 'listing' | 'primaryMediaItemId'>;
-    images?: ProductDetail['images'];
-    listing?: ProductDetail['listing'];
-    primaryMediaItemId?: ProductDetail['primaryMediaItemId'];
+type ResolveProductSelectionMediaResult<TMedia> = {
+    primaryImage: TMedia | null;
+    images: TMedia[];
+    source: ProductSelectionMediaSource;
 };
-type ProductSelectionAvailableSwatch = {
-    color?: string | null;
-    image?: MediaValue | null;
+type ResolveProductDisplayMediaInput<TMedia> = {
+    productMediaPool?: TMedia[] | null;
+    productPrimaryMediaItemId?: ProductSelectionMediaPointer;
+    listingPrimaryImage?: ProductSelectionMediaPointer;
 };
-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 ResolveProductDisplayMediaResult<TMedia> = {
+    primaryImage: TMedia | null;
+    images: TMedia[];
+    source: ProductDisplayMediaSource;
 };
-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 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;
 };
-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;
+declare function resolveListingPrimaryImagePointer<TMedia>(input: ListingPrimaryImageFallbackInput<TMedia>): string | null;
+
+type EntityID = string;
+type RelationshipValue = string | number | null | undefined | {
+    id?: string | number | null;
 };
-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, {
+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;
-    url?: string | null;
-}>;
-declare function getProductSelectionImages(resolution: Pick<ProductSelectionResolution, 'media'>): ProductDetailImageMedia[];
-type ProductHrefProduct = ProductDetail | {
+    option?: RelationshipValue;
+    value?: string | null;
     slug?: string | null;
-    product?: {
-        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;
-};
-type ProductHrefGroup = {
-    optionId?: string | number | null;
-    optionSlug?: string | null;
-    optionValueId?: string | number | null;
-    optionValueSlug?: string | null;
-    variantId?: string | number | 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?: {
-        selectionHintVariant?: string | number | null;
+        primaryImage?: MediaValue;
     } | null;
+}
+type ProductOptionMatrixValue = {
+    id: string;
+    optionId: string;
+    optionSlug: string;
+    label: string;
+    slug: string | null;
+    swatch: ProductOptionValueSwatch;
+    order: string;
 };
-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 ProductOptionMatrixOption = {
+    id: string;
+    title: string;
+    slug: string;
+    order: string;
+    values: ProductOptionMatrixValue[];
 };
-/**
- * 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 ProductApiOptions = ServerApiOptions;
-type StockCheckParams = {
-    items: Array<{
-        variantId: string;
-        quantity: number;
-    }>;
+type ProductOptionMatrixVariant<TVariant extends ProductVariantShape = ProductVariantShape> = {
+    id: string;
+    optionValueIds: string[];
+    optionValueByOptionId: Map<string, string>;
+    optionValueByOptionSlug: Map<string, string>;
+    source: TVariant;
 };
-type StockCheckResult = {
-    variantId: string;
-    status: 'available' | 'not_published' | 'archived' | 'not_found';
-    available: boolean;
-    availableStock: number;
-    isUnlimited: boolean;
-    requestedQuantity: number;
-    error?: 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 StockCheckResponse = {
-    results: StockCheckResult[];
-    allAvailable: boolean;
+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 ListingGroupsParams = {
-    productIds: 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 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 | {
-    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 ProductListingCardPriceRange = {
+    minPrice: number | null;
+    maxPrice: number | null;
+    minCompareAtPrice: number | null;
+    maxCompareAtPrice: number | null;
+    isPriceRange: boolean;
 };
-type ProductListingGroupsItem = {
-    product: ProductListingGroupsProduct;
-    groups: ProductListingGroupSummary[];
+type ProductListingSwatch = {
+    optionId: EntityID;
+    optionValueId: EntityID;
+    label: string;
+    swatch: ProductOptionValueSwatch<ProductDetailMedia>;
+    href: string;
+    availableForSale: boolean;
 };
-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 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 ProductDetailParams = {
-    slug: string;
-} | {
-    id: string;
+type ProductSelectionByOptionValue = string | number | null | undefined | {
+    valueId?: string | number | null;
+    valueSlug?: string | null;
 };
-type ProductDetailPreviewParams = {
-    id: string;
+type ProductSelectionInput = {
+    variantId?: string | number | null;
+    byOptionSlug?: Record<string, ProductSelectionByOptionValue>;
+    byOptionId?: Record<string, ProductSelectionByOptionValue>;
+    valueIds?: Iterable<unknown>;
+    search?: string | URLSearchParams | URL | null;
 };
-type ProductDetailPreviewOptions = {
-    previewToken: string;
+type NormalizedProductSelection = {
+    byOptionSlug: Record<string, string>;
+    byOptionId: Record<string, string>;
+    valueIds: string[];
+    variantId: string | null;
 };
-interface ProductDetailVariantOptionValue {
-    optionId: string | number;
+type CompatibilityProductSelectionParamEvent = {
+    optionId: string;
     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;
+    searchParam: string;
 };
-type ProductOptionValueColorSwatch = {
-    type: 'color';
-    color: string;
-    mediaItemId?: null;
+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 ProductOptionValueMediaSwatch<TMedia = ProductDetailMedia> = {
-    type: 'media';
-    mediaItemId: TMedia;
-    color?: null;
+type ProductSelectionResolutionContext = {
+    detail?: Pick<ProductDetail, 'images' | 'listing' | 'primaryMediaItemId'>;
+    images?: ProductDetail['images'];
+    listing?: ProductDetail['listing'];
+    primaryMediaItemId?: ProductDetail['primaryMediaItemId'];
 };
-type ProductOptionValueSwatch<TMedia = ProductDetailMedia> = ProductOptionValueColorSwatch | ProductOptionValueMediaSwatch<TMedia> | null;
-type ProductUpsertSwatchInput = ProductOptionValueColorSwatch | ProductOptionValueMediaSwatch<string>;
-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;
+type ProductSelectionAvailableSwatch = {
+    color?: string | null;
+    image?: MediaValue | null;
+};
+type ProductSelectionAvailableValue = {
+    valueId: string;
     value: string;
+    label: 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;
+    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;
+    constructor(message: string);
 }
-interface StockSnapshotResponse {
-    snapshots: StockSnapshotItem[];
-}
-type StockSnapshotParams = {
-    variantIds: 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;
 };
-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;
+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 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;
     };
-    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 ProductDetailCatalogResult = {
-    found: true;
-    product: ProductDetailCatalog;
-} | {
-    found: false;
-    reason: ProductDetailUnavailableReason;
+/**
+ * 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.
+ *
+ * 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 ProductUpsertColorSwatchInput = {
+    type: 'color';
+    color: string;
+    mediaItemId?: null;
+};
+type ProductUpsertMediaSwatchInput = {
+    type: 'media';
+    mediaItemId: string;
+    color?: null;
 };
+type ProductUpsertSwatchInput = ProductUpsertColorSwatchInput | ProductUpsertMediaSwatchInput;
 type ProductUpsertOptionValueInput = {
     id?: string;
     value: string;
@@ -1070,20 +1428,20 @@ type ProductUpsertOptionValueInput = {
     swatch?: ProductUpsertSwatchInput | null;
     metadata?: unknown;
 };
-type ProductUpsertOptionInput = {
+type OptionValueInput = ProductUpsertOptionValueInput;
+type OptionInput = {
     id?: string;
     title: string;
     slug?: string;
-    values: ProductUpsertOptionValueInput[];
-};
-type ProductUpsertVariantOptionValue = string | {
-    valueSlug?: string;
-    valueId?: string;
-    value?: string;
+    values: OptionValueInput[];
 };
-type ProductUpsertVariantInput = {
+type VariantInput = {
     id?: string;
-    optionValues?: Record<string, ProductUpsertVariantOptionValue> | string[];
+    optionValues?: Record<string, string | {
+        valueSlug?: string;
+        valueId?: string;
+        value?: string;
+    }> | string[];
     sku?: string | null;
     title?: string | null;
     price: number;
@@ -1098,373 +1456,385 @@ type ProductUpsertVariantInput = {
     images?: string[];
     metadata?: unknown;
 };
-type ProductUpsertParams = {
-    product: Record<string, unknown> & {
-        id?: string;
-        title?: string;
-    };
-    options?: ProductUpsertOptionInput[];
-    variants?: ProductUpsertVariantInput[];
-};
-/** 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;
-};
-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;
-};
-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>;
-    /**
-     * 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 ValidateDiscountResult = {
-    valid: boolean;
-    code: string;
-    type?: 'percentage' | 'fixed_amount' | 'free_shipping' | 'tiered';
-    discountAmount: number;
-    freeShipping?: boolean;
-    reason?: string;
-};
-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 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 CalculateShippingResult = {
-    shippingAmount: number;
-    baseShippingAmount: number;
-    extraShippingAmount: number;
-    freeShipping: boolean;
-    freeShippingMinAmount: number | null;
-    isJeju: boolean;
-    isRemoteIsland: boolean;
+type ProductUpsertGraphFields = {
+    /** Required when updating an existing product graph if the server graph is non-empty. */
+    graphRevision?: string;
+    options?: OptionInput[];
+    variants?: VariantInput[];
 };
-declare class ShippingApi extends BaseApi {
-    constructor(options: ShippingApiOptions);
-    calculate(params: CalculateShippingParams): Promise<CalculateShippingResult>;
-}
-
-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;
+/** Create a product document and initial graph. */
+type ProductUpsertCreateInput = ProductUpsertGraphFields & {
+    productId?: never;
+    product: ProductFieldsInput & {
+        title: string;
+    };
 };
-type CustomerSnapshot = {
-    name?: string;
-    email: string;
-    phone?: string;
+/** Graph-only update for an existing product (document fields via Payload save). */
+type ProductUpsertEditInput = ProductUpsertGraphFields & {
+    productId: string;
+    product?: never;
 };
-type ReturnReason = 'change_of_mind' | 'defective' | 'wrong_delivery' | 'damaged' | 'other';
-type ReturnItem = {
-    orderItem: string;
-    quantity: number;
+type ProductUpsertInput = ProductUpsertCreateInput | ProductUpsertEditInput;
+
+type ProductApiOptions = ServerApiOptions;
+type StockCheckParams = {
+    items: Array<{
+        variantId: string;
+        quantity: number;
+    }>;
 };
-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 StockCheckResult = {
+    variantId: string;
+    status: 'available' | 'not_published' | 'archived' | 'not_found';
+    available: boolean;
+    availableStock: number;
+    isUnlimited: boolean;
+    requestedQuantity: number;
+    error?: string;
 };
-type CreateOrderParams = WithIdempotencyKey<{
-    orderNumber: string;
-    customer?: string;
-    customerSnapshot: CustomerSnapshot;
-    shippingAddress: Order['shippingAddress'];
-    orderItems: CreateOrderItem[];
-    totalAmount: number;
-    shippingAmount?: number;
-    pgPaymentId?: string;
-    discountCode?: string;
-}>;
-type UpdateOrderParams = {
-    orderNumber: string;
-    status: Order['status'];
+type StockCheckResponse = {
+    results: StockCheckResult[];
+    allAvailable: boolean;
 };
-type TransactionStatus = 'pending' | 'paid' | 'failed' | 'canceled';
-type UpdateTransactionParams = {
-    pgPaymentId: string;
-    status: TransactionStatus;
-    paymentMethod?: string;
-    receiptUrl?: string;
-    paymentKey?: string;
-    amount?: number;
+type ListingGroupsParams = {
+    productIds: 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;
+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, 'variants'> & {
+    id: string;
+    slug: string;
+    title: string;
+    primaryMediaItemId?: ProductListingGroupsProductPrimaryMediaItemId;
+    variants?: (Omit<ProductListingGroupsProductVariants, 'docs'> & {
+        docs: ProductListingGroupVariant[];
+    }) | null;
 };
-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 ProductListingGroupsCatalogProduct = Omit<ProductListingGroupsProduct, 'variants'> & {
+    variants?: (Omit<NonNullable<ProductListingGroupsProduct['variants']>, 'docs'> & {
+        docs: ProductListingGroupCatalogVariant[];
+    }) | null;
 };
-type CancelOrderUnpaidCommittedResponseFields = {
-    refundedAmount: 0;
-    providerRefunded: false;
+type ProductListingGroupsItem = {
+    product: ProductListingGroupsProduct;
+    groups: ProductListingGroupSummary[];
 };
-type CancelOrderPaidCommittedResponseFields = {
-    transactionId: string;
-    refundedAmount: 0;
-    providerRefunded: false;
-    refundPending: true;
+type ProductListingGroupsCatalogItem = {
+    product: ProductListingGroupsCatalogProduct;
+    groups: ProductListingGroupCatalogSummary[];
 };
-type CancelOrderLegacyProviderRefundResponseFields = {
-    transactionId: string;
-    refundedAmount: number;
-    refundSeq: number;
-    providerRefunded: 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 CancelOrderAlreadyCanceledResponseFields = {
-    refundedAmount: number;
-    providerRefunded: false;
+type ProductListingGroupsCatalogResponse = Omit<ProductListingGroupsResponse, 'docs'> & {
+    docs: ProductListingGroupsCatalogItem[];
 };
-type CancelOrderAlreadyCanceledRefundPendingResponseFields = {
-    transactionId: string;
-    refundedAmount: number;
-    providerRefunded: false;
-    refundPending: true;
+type ProductDetailParams = {
+    slug: string;
+} | {
+    id: string;
 };
-type CancelOrderPaidCommittedResponse = CancelOrderResponseBase & CancelOrderPaidCommittedResponseFields & {
-    status: 'canceled';
-    cancelCommitted: true;
+type ProductDetailPreviewParams = {
+    id: string;
 };
-type CancelOrderUnpaidCommittedResponse = CancelOrderResponseBase & CancelOrderUnpaidCommittedResponseFields & {
-    status: 'canceled';
-    cancelCommitted: true;
+type ProductDetailPreviewOptions = {
+    previewToken: string;
 };
-type CancelOrderCommittedResponse = CancelOrderPaidCommittedResponse | CancelOrderUnpaidCommittedResponse;
-type CancelOrderAlreadyCanceledResponse = CancelOrderResponseBase & CancelOrderAlreadyCanceledResponseFields & {
-    status: 'canceled';
-    cancelCommitted: false;
-    alreadyCanceled: true;
+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 CancelOrderAlreadyCanceledRefundPendingResponse = CancelOrderResponseBase & CancelOrderAlreadyCanceledRefundPendingResponseFields & {
-    status: 'canceled';
-    cancelCommitted: false;
-    alreadyCanceled: true;
+type ProductOptionValueColorSwatch = {
+    type: 'color';
+    color: string;
+    mediaItemId?: null;
 };
-/** @deprecated Inline PG cancel reconciliation; retained for legacy API consumers. */
-type CancelOrderReconciliationResponse = CancelOrderResponseBase & CancelOrderLegacyProviderRefundResponseFields & {
-    status: CancelOrderReconciliationStatus;
-    cancelCommitted: false;
-    reconciliationRequired: true;
+type ProductOptionValueMediaSwatch<TMedia = ProductDetailMedia> = {
+    type: 'media';
+    mediaItemId: TMedia;
+    color?: null;
 };
-type CancelOrderResponse = CancelOrderCommittedResponse | CancelOrderAlreadyCanceledResponse | CancelOrderAlreadyCanceledRefundPendingResponse | CancelOrderReconciliationResponse;
-type CancelOrderParams = {
-    orderNumber: string;
-    reasonCode?: CancelReasonCode;
-    reasonDetail?: string;
-    idempotencyKey?: string;
+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;
 };
-type ResolveCancelRefundOutcome = 'succeeded' | 'failed';
-type ResolveCancelRefundSucceededParams = {
-    orderNumber: string;
-    idempotencyKey: string;
-    outcome: 'succeeded';
-    refundedAmount: number;
-    pgProvider: string;
-    pgRefundId: string;
+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 ResolveCancelRefundFailedParams = {
-    orderNumber: string;
-    idempotencyKey: string;
-    outcome: 'failed';
-    refundedAmount: 0;
-    pgProvider: string;
-    pgRefundId?: 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 ResolveCancelRefundParams = ResolveCancelRefundSucceededParams | ResolveCancelRefundFailedParams;
-type ResolveCancelRefundSucceededResponse = {
-    orderId: string;
-    transactionId: string;
-    refundTransactionId: string;
-    refundedAmount: number;
-    refundStatus: 'succeeded';
-    transactionStatus: 'refunded';
+type ProductDetailCatalogResult = {
+    found: true;
+    product: ProductDetailCatalog;
+} | {
+    found: false;
+    reason: ProductDetailUnavailableReason;
 };
-type ResolveCancelRefundFailedResponse = {
-    orderId: string;
-    transactionId: string;
-    refundTransactionId: string;
-    refundedAmount: 0;
-    refundStatus: 'failed';
-    transactionStatus: 'paid';
+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 ResolveCancelRefundResponse = ResolveCancelRefundSucceededResponse | ResolveCancelRefundFailedResponse;
-type RestockAction = 'return_to_stock' | 'discard';
-type ReturnWithRefundItem = {
-    orderItem: string | number;
-    quantity: number;
-    restockAction?: RestockAction;
-    restockingFee?: number;
+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 ReturnWithRefundParams = WithIdempotencyKey<{
-    orderNumber: string;
-    reason?: ReturnReason;
-    reasonDetail?: string;
-    returnItems: ReturnWithRefundItem[];
-    refundAmount: number;
-    returnShippingFee?: number;
-    pgPaymentId: string;
-    paymentKey?: string;
-    refundReceiptUrl?: string;
-}>;
-type CheckoutParams = WithIdempotencyKey<{
-    cartId: string;
-    orderNumber: string;
-    customerSnapshot: CustomerSnapshot;
-    pgPaymentId?: string;
-    discountCode?: string;
-}>;
-type CreateFulfillmentParams = WithIdempotencyKey<{
-    orderNumber: string;
-    carrier?: string;
-    trackingNumber?: string;
-    items: Array<{
-        orderItem: string;
-        quantity: number;
-    }>;
-}>;
-type UpdateFulfillmentParams = {
-    fulfillmentId: string;
-    status: 'packed' | 'shipped' | 'delivered' | 'failed';
-    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>;
+    /**
+     * 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 BulkImportFulfillmentsParams = {
-    items: Array<{
-        orderNumber: string;
-        carrier?: string;
-        trackingNumber?: string;
-    }>;
+type ValidateDiscountResult = {
+    valid: boolean;
+    code: string;
+    type?: 'percentage' | 'fixed_amount' | 'free_shipping' | 'tiered';
+    discountAmount: number;
+    freeShipping?: boolean;
+    reason?: string;
 };
-type BulkImportFulfillmentsResponse = {
-    succeeded: Array<{
-        orderNumber: string;
-        fulfillmentId: string;
-    }>;
-    failed: Array<{
-        orderNumber: string;
-        error: string;
-    }>;
+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 CreateReturnParams = WithIdempotencyKey<{
-    orderNumber: string;
-    reason?: ReturnReason;
-    reasonDetail?: string;
-    returnItems: ReturnItem[];
-    refundAmount: number;
-}>;
-type UpdateReturnParams = {
-    returnId: string;
-    status: 'processing' | 'approved' | 'rejected' | 'completed';
+type CalculateShippingResult = {
+    shippingAmount: number;
+    baseShippingAmount: number;
+    extraShippingAmount: number;
+    freeShipping: boolean;
+    freeShippingMinAmount: number | null;
+    isJeju: boolean;
+    isRemoteIsland: boolean;
 };
-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>;
-    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>;
+declare class ShippingApi extends BaseApi {
+    constructor(options: ShippingApiOptions);
+    calculate(params: CalculateShippingParams): Promise<CalculateShippingResult>;
 }
 
 interface CommerceClientOptions {
@@ -1480,30 +1850,30 @@ declare class CommerceClient {
         stockCheck: (params: StockCheckParams) => Promise<StockCheckResponse>;
         stockSnapshot: (params: StockSnapshotParams) => Promise<StockSnapshotResponse>;
         listingGroups: (params: ListingGroupsParams) => Promise<ProductListingGroupsResponse>;
-        listingGroupsCatalog: (params: ListingGroupsParams) => Promise<ProductListingGroupsResponse>;
+        listingGroupsCatalog: (params: ListingGroupsParams) => Promise<ProductListingGroupsCatalogResponse>;
         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>;
@@ -1529,20 +1899,20 @@ declare class ServerCommerceClient {
         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>;
@@ -1550,6 +1920,7 @@ declare class ServerCommerceClient {
         cancelOrder: (params: CancelOrderParams) => Promise<CancelOrderResponse>;
         resolveCancelRefund: (params: ResolveCancelRefundParams) => Promise<ResolveCancelRefundResponse>;
         createFulfillment: (params: CreateFulfillmentParams) => Promise<Fulfillment>;
+        prepareFulfillmentOrder: (params: PrepareFulfillmentOrderParams) => Promise<PrepareFulfillmentOrderResponse>;
         updateFulfillment: (params: UpdateFulfillmentParams) => Promise<Fulfillment>;
         bulkImportFulfillments: (params: BulkImportFulfillmentsParams) => Promise<BulkImportFulfillmentsResponse>;
         createReturn: (params: CreateReturnParams) => Promise<Return>;
@@ -2038,4 +2409,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 ProductVariantShape 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_UPSERT_READONLY_FIELD_REASON as b6, PRODUCT_UPSERT_UNKNOWN_FIELD_REASON as b7, ProductApi as b8, type ProductApiOptions as b9, type ProductListingGroupsProduct as bA, type ProductListingGroupsResponse as bB, type ProductListingProductShape as bC, type ProductListingProjection as bD, type ProductListingSwatch as bE, type ProductMediaResolutionSource as bF, type ProductOptionMatrix as bG, type ProductOptionMatrixOption as bH, type ProductOptionMatrixValue as bI, type ProductOptionMatrixVariant as bJ, type ProductOptionShape as bK, type ProductOptionValueShape as bL, type ProductOptionValueSwatch as bM, type ProductOptionValueSwatchInput as bN, type ProductSelectionAvailableSwatch as bO, type ProductSelectionAvailableValue as bP, type ProductSelectionByOptionValue as bQ, ProductSelectionCodecError as bR, type ProductSelectionCodecOptions as bS, type ProductSelectionInput as bT, type ProductSelectionOptionValue as bU, type ProductSelectionResolution as bV, type ProductSelectionResolutionContext as bW, type ProductSelectionUrlEmit as bX, type ProductSelectionVariant as bY, type ProductUpsertFieldValidationErrorBody as bZ, type ProductUpsertFieldValidationErrorReason as b_, type ProductDetailBrand as ba, type ProductDetailCatalogListing as bb, type ProductDetailCatalogResult as bc, type ProductDetailCatalogVariant as bd, type ProductDetailCategory as be, type ProductDetailImage as bf, type ProductDetailImageMedia as bg, type ProductDetailListing as bh, type ProductDetailMedia as bi, type ProductDetailOption as bj, type ProductDetailOptionValue as bk, type ProductDetailTag as bl, type ProductDetailUnavailableReason as bm, type ProductDetailVariant as bn, type ProductDetailVariantOptionValue as bo, type ProductDetailVideo as bp, type ProductHrefGroup as bq, type ProductHrefOptions as br, type ProductHrefProduct as bs, type ProductListingCard as bt, type ProductListingCardOptions as bu, type ProductListingCardPriceRange as bv, type ProductListingCardRepresentativeVariant as bw, type ProductListingGroup as bx, type ProductListingGroupSummary as by, type ProductListingGroupVariant as bz, type ClientState as c, type RemoveDiscountParams as c0, type RemoveItemParams as c1, type RequestOptions as c2, type ResolveCancelRefundFailedResponse as c3, type ResolveCancelRefundOutcome as c4, type ResolveCancelRefundParams as c5, type ResolveCancelRefundResponse as c6, type ResolveCancelRefundSucceededResponse as c7, type ResolveProductDisplayMediaInput as c8, type ResolveProductDisplayMediaResult as c9, getAvailableOptionValues as cA, getProductSelectionImages as cB, getSelectedValueByOptionId as cC, isProductUpsertFieldValidationErrorBody as cD, normalizeProductSelection as cE, normalizeProductSelectionFromMatrix as cF, normalizeSelectedValueIds as cG, parseProductSelection as cH, resolveListingPrimaryImagePointer as cI, resolveProductDisplayMedia as cJ, resolveProductSelection as cK, resolveProductSelectionFromMatrix as cL, resolveProductSelectionMedia as cM, resolveVariantForSelection as cN, selectNext as cO, selectedSwatchMediaItemId as cP, stringifyProductSelection as cQ, toShopifyPriceRangeV2 as cR, type ReturnItem as ca, type ReturnReason as cb, type ReturnWithRefundItem as cc, type ReturnWithRefundParams as cd, ShippingApi as ce, type ShippingApiOptions as cf, type StockCheckParams as cg, type StockCheckResponse as ch, type StockCheckResult as ci, type StockSnapshotItem as cj, type StockSnapshotParams as ck, type UpdateFulfillmentParams as cl, type UpdateItemParams as cm, type UpdateOrderParams as cn, type UpdateReturnParams as co, type UpdateTransactionParams as cp, type ValidateDiscountParams as cq, type ValidateDiscountResult as cr, type WithIdempotencyKey as cs, buildProductHref as ct, buildProductListingCard as cu, buildProductListingGroupsByOption as cv, buildProductListingProjection as cw, buildProductOptionMatrix as cx, buildProductOptionMatrixFromDetail as cy, createProductSelectionCodec 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 EventsCalendarItem as $, type AddItemParams as A, BaseApi as B, CommerceClient as C, type DebugConfig as D, EventsClient as E, ServerCommerceClient as F, type BanCustomerParams as G, type CommunityBan as H, type UnbanCustomerParams as I, type ClientServerConfig as J, type RootServerClientWithEvents as K, type CollectionFieldSchema as L, type CollectionSchemaResponse as M, type EventGuestCancelParams as N, type EventGuestRegistration as O, type PayloadFindResponse as P, type EventGuestRegistrationResponse as Q, type RemoveDiscountParams as R, type Sort as S, type TenantIntrospectionClient as T, type UpdateItemParams as U, type EventRegistrationAnswerInput as V, type Where as W, type EventRegistrationAttendeeInput as X, type EventRegistrationPublic as Y, type EventRegistrationRegisterParams as Z, type EventRegistrationRegisterResponse as _, CommunityClient as a, type CommunityPublicAuthorSnapshot as a$, type EventsClientOptions as a0, type EventsDateParam as a1, type EventsExternalSource as a2, type EventsLocation as a3, type EventsOccurrenceLocation as a4, type EventsRangeEvent as a5, type EventsRangeOccurrence as a6, type EventsRangeParams as a7, type EventsRangeResponse as a8, type EventsTaxonomyItem as a9, type ProductDetailCatalog as aA, type StockSnapshotResponse as aB, type ProductSelectionMediaSource as aC, type ProductDisplayMediaSource as aD, type ResolveProductSelectionMediaInput as aE, type ResolveProductSelectionMediaResult as aF, type ProductSelectionMediaPointer as aG, type RootClientWithEvents as aH, type BulkImportFulfillmentsParams as aI, type BulkImportFulfillmentsResponse as aJ, type CalculateShippingParams as aK, type CalculateShippingResult as aL, type CancelOrderParams as aM, type CancelOrderReconciliationStatus as aN, type CancelOrderResponse as aO, type CancelReasonCode as aP, CartApi as aQ, type CartApiOptions as aR, type Comment as aS, type CommerceClientOptions as aT, type CommunityClientOptions as aU, type CommunityComment as aV, type CommunityCommentListSort as aW, type CommunityPost as aX, type CommunityPostCategory as aY, type CommunityPostListSort as aZ, type CommunityPostTag as a_, ModerationApi as aa, type RootServerClient as ab, type TenantFeatureProgressEvidenceValue as ac, type TenantFeatureProgressFeature as ad, type TenantFeatureProgressGroup as ae, type TenantFeatureProgressInput as af, type TenantFeatureProgressItem as ag, type TenantFeatureProgressItemState as ah, type TenantFeatureProgressResponse as ai, type TenantFeatureProgressSeverity as aj, type TenantFeatureProgressStatus as ak, TenantIntrospectionApi as al, type TenantIntrospectionApiOptions as am, CustomerAuth as an, type CustomerProfile as ao, type CustomerAuthResponse as ap, type CustomerLoginData as aq, type CustomerRegisterResponse as ar, type CustomerRegisterData as as, type CustomerRefreshResponse as at, type UpdateProfileData as au, type ProductDetailParams as av, type ProductDetailResult as aw, type ProductListingGroupsItem as ax, type ProductListingGroupsCatalogItem as ay, type ProductDetail as az, CustomerNamespace as b, type ProductMediaResolutionSource as b$, type CommunityPublicMediaAsset as b0, type CommunityPublicReference as b1, type CompatibilityProductSelectionParamEvent as b2, type ConfirmPaymentParams as b3, type ConfirmPaymentResponse as b4, type CreateFulfillmentParams as b5, type CreateOrderItem as b6, type CreateOrderParams as b7, type CreateReturnParams as b8, type CustomerAuthOptions as b9, type ProductDetailMedia as bA, type ProductDetailOption as bB, type ProductDetailOptionValue as bC, type ProductDetailTag as bD, type ProductDetailUnavailableReason as bE, type ProductDetailVariant as bF, type ProductDetailVariantOptionValue as bG, type ProductDetailVideo as bH, type ProductHrefGroup as bI, type ProductHrefOptions as bJ, type ProductHrefProduct as bK, type ProductListingCard as bL, type ProductListingCardOptions as bM, type ProductListingCardPriceRange as bN, type ProductListingCardRepresentativeVariant as bO, type ProductListingGroup as bP, type ProductListingGroupCatalogSummary as bQ, type ProductListingGroupCatalogVariant as bR, type ProductListingGroupSummary as bS, type ProductListingGroupVariant as bT, type ProductListingGroupsCatalogProduct as bU, type ProductListingGroupsCatalogResponse as bV, type ProductListingGroupsProduct as bW, type ProductListingGroupsResponse as bX, type ProductListingProductShape as bY, type ProductListingProjection as bZ, type ProductListingSwatch as b_, type CustomerSnapshot as ba, DiscountApi as bb, type DiscountApiOptions as bc, type LegacyProductSelectionParamEvent as bd, type ListingGroupsParams as be, type ListingPrimaryImageFallbackInput as bf, type MediaValue as bg, type NormalizedOptionSwatch as bh, type NormalizedProductSelection as bi, OrderApi as bj, type OrderApiOptions as bk, PRODUCT_PLP_FIND_OPTIONS as bl, PRODUCT_UPSERT_READONLY_FIELD_REASON as bm, PRODUCT_UPSERT_UNKNOWN_FIELD_REASON as bn, type PrepareFulfillmentOrderParams as bo, type PrepareFulfillmentOrderResponse as bp, ProductApi as bq, type ProductApiOptions as br, type ProductDetailBrand as bs, type ProductDetailCatalogListing as bt, type ProductDetailCatalogResult as bu, type ProductDetailCatalogVariant as bv, type ProductDetailCategory as bw, type ProductDetailImage as bx, type ProductDetailImageMedia as by, type ProductDetailListing as bz, type ClientState as c, resolveListingPrimaryImagePointer as c$, type ProductOptionMatrix as c0, type ProductOptionMatrixOption as c1, type ProductOptionMatrixValue as c2, type ProductOptionMatrixVariant as c3, type ProductOptionShape as c4, type ProductOptionValueShape as c5, type ProductOptionValueSwatch as c6, type ProductOptionValueSwatchInput as c7, type ProductSelectionAvailableSwatch as c8, type ProductSelectionAvailableValue as c9, type StockCheckParams as cA, type StockCheckResponse as cB, type StockCheckResult as cC, type StockSnapshotItem as cD, type StockSnapshotParams as cE, type UpdateFulfillmentParams as cF, type UpdateOrderParams as cG, type UpdateReturnParams as cH, type UpdateTransactionParams as cI, type ValidateDiscountParams as cJ, type ValidateDiscountResult as cK, type WithIdempotencyKey as cL, buildProductHref as cM, buildProductListingCard as cN, buildProductListingGroupsByOption as cO, buildProductListingProjection as cP, buildProductOptionMatrix as cQ, buildProductOptionMatrixFromDetail as cR, createProductSelectionCodec as cS, getAvailableOptionValues as cT, getProductSelectionImages as cU, getSelectedValueByOptionId as cV, isProductUpsertFieldValidationErrorBody as cW, normalizeProductSelection as cX, normalizeProductSelectionFromMatrix as cY, normalizeSelectedValueIds as cZ, parseProductSelection as c_, type ProductSelectionByOptionValue as ca, ProductSelectionCodecError as cb, type ProductSelectionCodecOptions as cc, type ProductSelectionInput as cd, type ProductSelectionOptionValue as ce, type ProductSelectionResolution as cf, type ProductSelectionResolutionContext as cg, type ProductSelectionUrlEmit as ch, type ProductSelectionVariant as ci, type ProductUpsertFieldValidationErrorBody as cj, type ProductUpsertFieldValidationErrorReason as ck, type ProductVariantShape as cl, type RequestOptions as cm, type ResolveCancelRefundFailedResponse as cn, type ResolveCancelRefundOutcome as co, type ResolveCancelRefundParams as cp, type ResolveCancelRefundResponse as cq, type ResolveCancelRefundSucceededResponse as cr, type ResolveProductDisplayMediaInput as cs, type ResolveProductDisplayMediaResult as ct, type ReturnItem as cu, type ReturnReason as cv, type ReturnWithRefundItem as cw, type ReturnWithRefundParams as cx, ShippingApi as cy, type ShippingApiOptions as cz, type ClientConfig as d, resolveProductDisplayMedia as d0, resolveProductSelection as d1, resolveProductSelectionFromMatrix as d2, resolveProductSelectionMedia as d3, resolveVariantForSelection as d4, selectNext as d5, selectedSwatchMediaItemId as d6, stringifyProductSelection as d7, toShopifyPriceRangeV2 as d8, type ApiQueryOptions as e, type ApplyDiscountParams as f, type CheckoutParams as g, type ClearCartParams as h, type ClientMetadata as i, type DeepPartial as j, type ExtractArrayType as k, type PayloadMutationResponse as l, type PublicCart as m, type PublicCartItem as n, type PublicCartReference as o, type PublicMediaAsset as p, type PublicMediaSize as q, type PublicOrder as r, type PublicOrderItem as s, type PublicOrderReference as t, type RemoveItemParams as u, type RetryConfig as v, type RootClient as w, type RootCollectionClient as x, type RootReadOnlyQueryBuilder as y, type ServerApiOptions as z };