@01.software/sdk 0.28.0 → 0.30.1

package/dist/types-Dlb2mwpX.d.cts

@@ -0,0 +1,1249 @@
+import { P as PublicCollection } from './const-VZuk2tWc.cjs';
+import { C as CollectionType } from './types-BwT0eeaz.cjs';
+import { O as Order, h as Cart, i as CartItem, d as Product, l as OrderItem, m as Transaction, n as Fulfillment, o as Return } from './payload-types-DPjO_IbQ.cjs';
+
+interface CommunityClientOptions {
+    publishableKey?: string;
+    secretKey?: string;
+    apiUrl?: string;
+    customerToken?: string | (() => string | null);
+    onUnauthorized?: () => Promise<string | null>;
+    onRequestId?: (id: string | null) => void;
+}
+interface CommunityPost {
+    id: string;
+    title?: string | null;
+    displayTitle?: string | null;
+    content?: unknown;
+    categories?: string[];
+    thumbnail?: string;
+    viewCount?: number;
+    createdAt?: string;
+    updatedAt?: string;
+    [key: string]: unknown;
+}
+interface Comment {
+    id: string;
+    body: string;
+    post?: string;
+    parent?: string;
+    rootComment?: string;
+    createdAt?: string;
+    updatedAt?: string;
+    [key: string]: unknown;
+}
+interface Reaction {
+    id: string;
+    post?: string;
+    comment?: string;
+    type?: string;
+    createdAt?: string;
+    [key: string]: unknown;
+}
+interface ReactionSummary {
+    counts: Record<string, number>;
+    total: number;
+    userReactions: string[];
+}
+interface Bookmark {
+    id: string;
+    post?: string;
+    createdAt?: string;
+    [key: string]: unknown;
+}
+interface ReactionType {
+    id: string;
+    title: string;
+    slug: string;
+    emoji?: string;
+    [key: string]: unknown;
+}
+interface PaginatedResponse<T> {
+    docs: T[];
+    totalDocs: number;
+    limit: number;
+    totalPages: number;
+    page: number;
+    pagingCounter: number;
+    hasPrevPage: boolean;
+    hasNextPage: boolean;
+    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?;
+    constructor(options: CommunityClientOptions);
+    private buildQuery;
+    private execute;
+    createPost(params: {
+        title?: string | null;
+        content?: unknown;
+        categories?: string[];
+        thumbnail?: string;
+    }): Promise<CommunityPost>;
+    getMyPosts(params?: {
+        page?: number;
+        limit?: number;
+    }): Promise<PaginatedResponse<CommunityPost>>;
+    getTrending(params?: {
+        page?: number;
+        limit?: number;
+        period?: string;
+    }): Promise<PaginatedResponse<CommunityPost>>;
+    incrementView(params: {
+        postId: string;
+    }): Promise<{
+        viewCount: number;
+    }>;
+    reportPost(params: {
+        postId: string;
+        reason?: string;
+        reasonDetail?: string;
+    }): Promise<{
+        success: boolean;
+    }>;
+    createComment(params: {
+        postId: string;
+        body: string;
+        parentId?: string;
+    }): Promise<Comment>;
+    listComments(params: {
+        postId: string;
+        page?: number;
+        limit?: number;
+        rootComment?: string;
+    }): Promise<PaginatedResponse<Comment>>;
+    updateComment(params: {
+        commentId: string;
+        body: string;
+    }): Promise<Comment>;
+    deleteComment(params: {
+        commentId: string;
+    }): Promise<{
+        success: boolean;
+    }>;
+    reportComment(params: {
+        commentId: string;
+        reason?: string;
+        reasonDetail?: string;
+    }): Promise<{
+        success: boolean;
+    }>;
+    addReaction(params: {
+        postId: string;
+        type: string;
+    }): Promise<Reaction>;
+    removeReaction(params: {
+        postId: string;
+        type: string;
+    }): Promise<{
+        success: boolean;
+    }>;
+    addCommentReaction(params: {
+        commentId: string;
+        type: string;
+    }): Promise<Reaction>;
+    removeCommentReaction(params: {
+        commentId: string;
+        type: string;
+    }): Promise<{
+        success: boolean;
+    }>;
+    getReactionSummary(params: {
+        postId: string;
+    }): Promise<ReactionSummary>;
+    getReactionTypes(): Promise<PaginatedResponse<ReactionType>>;
+    addBookmark(params: {
+        postId: string;
+    }): Promise<Bookmark>;
+    removeBookmark(params: {
+        postId: string;
+    }): Promise<{
+        success: boolean;
+    }>;
+    getMyBookmarks(params?: {
+        page?: number;
+        limit?: number;
+    }): Promise<PaginatedResponse<Bookmark>>;
+}
+
+interface ServerApiOptions {
+    publishableKey?: string;
+    secretKey: string;
+    apiUrl?: string;
+    onRequestId?: (id: string | null) => void;
+}
+interface RequestOptions {
+    method?: 'GET' | 'POST' | 'PATCH' | 'DELETE';
+    headers?: Record<string, string>;
+}
+declare abstract class BaseApi {
+    protected readonly publishableKey: string;
+    protected readonly secretKey: string;
+    protected readonly apiUrl?: string;
+    protected readonly onRequestId?: (id: string | null) => void;
+    constructor(apiName: string, options: ServerApiOptions);
+    protected request<T>(endpoint: string, body: unknown, options?: RequestOptions): Promise<T>;
+}
+
+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;
+}
+
+/**
+ * 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<Order>>;
+    /**
+     * 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;
+};
+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 EntityID = string;
+type RelationshipValue = string | number | null | undefined | {
+    id?: string | number | null;
+};
+type MediaValue = ProductDetailMedia | null | undefined;
+interface ProductOptionValueShape {
+    id?: string | number | null;
+    option?: RelationshipValue;
+    value?: string | null;
+    slug?: string | null;
+    swatchColor?: string | null;
+    thumbnail?: MediaValue;
+    images?: MediaValue[] | 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;
+    images?: MediaValue[] | null;
+}
+type ProductOptionMatrixValue = {
+    id: string;
+    optionId: string;
+    optionSlug: string;
+    label: string;
+    slug: string | null;
+    swatchColor?: string | null;
+    thumbnail?: MediaValue;
+    images?: MediaValue[] | null;
+    order: string;
+};
+type ProductOptionMatrixOption = {
+    id: string;
+    title: string;
+    slug: string;
+    order: string;
+    values: ProductOptionMatrixValue[];
+};
+type ProductOptionMatrixVariant<TVariant extends ProductVariantShape = ProductVariantShape> = {
+    id: string;
+    optionValueIds: string[];
+    optionValueByOptionId: Map<string, string>;
+    optionValueByOptionSlug: Map<string, string>;
+    source: TVariant;
+};
+type ProductOptionMatrix<TVariant extends ProductVariantShape = ProductVariantShape> = {
+    options: ProductOptionMatrixOption[];
+    optionIds: string[];
+    optionSlugs: string[];
+    optionById: Map<string, ProductOptionMatrixOption>;
+    optionBySlug: Map<string, ProductOptionMatrixOption>;
+    valueById: Map<string, ProductOptionMatrixValue>;
+    valueToOptionId: Map<string, string>;
+    valueToOptionSlug: Map<string, string>;
+    variants: ProductOptionMatrixVariant<TVariant>[];
+};
+type ProductListingProjection = {
+    selectionHintVariant: EntityID | null;
+    primaryImage: EntityID | null;
+    minPrice: number | null;
+    maxPrice: number | null;
+    minCompareAtPrice: number | null;
+    maxCompareAtPrice: number | null;
+    isPriceRange: boolean;
+    availableForSale: boolean;
+};
+type ProductListingGroup<TVariant extends ProductVariantShape = ProductVariantShape> = {
+    optionId: EntityID;
+    optionTitle: string;
+    optionValueId: EntityID;
+    optionValueLabel: string;
+    optionValueSlug: string | null;
+    optionValueSwatchColor?: string | null;
+    optionValueThumbnail?: MediaValue;
+    optionValueImages?: MediaValue[] | null;
+    variantIds: EntityID[];
+    variantCount: number;
+    variants: TVariant[];
+    listing: ProductListingProjection;
+};
+type ProductSelectionByOptionValue = string | number | null | undefined | {
+    valueId?: string | number | null;
+    valueSlug?: string | null;
+};
+type ProductSelectionInput = {
+    variantId?: string | number | null;
+    byOptionSlug?: Record<string, ProductSelectionByOptionValue>;
+    byOptionId?: Record<string, ProductSelectionByOptionValue>;
+    valueIds?: Iterable<unknown>;
+    search?: string | URLSearchParams | URL | null;
+};
+type NormalizedProductSelection = {
+    byOptionSlug: Record<string, string>;
+    byOptionId: Record<string, string>;
+    valueIds: string[];
+    variantId: string | null;
+};
+type CompatibilityProductSelectionParamEvent = {
+    optionId: string;
+    optionSlug: string;
+    valueSlug: string;
+    searchParam: string;
+};
+type LegacyProductSelectionParamEvent = CompatibilityProductSelectionParamEvent;
+type ProductSelectionCodecOptions = {
+    onCompatibilityOptionIdParam?: (event: CompatibilityProductSelectionParamEvent) => void;
+    onLegacyOptionIdParam?: (event: LegacyProductSelectionParamEvent) => void;
+};
+type ProductSelectionResolutionContext = {
+    detail?: Pick<ProductDetail, 'images' | 'listing'>;
+    images?: ProductDetail['images'];
+    listing?: ProductDetail['listing'];
+};
+type ProductSelectionAvailableValue = {
+    valueId: string;
+    value: string;
+    slug: string;
+    selected: boolean;
+    available: boolean;
+    availableForSale: boolean;
+    isUnlimited: boolean;
+    availableStock: number | null;
+    swatchColor?: string | null;
+    thumbnail?: MediaValue;
+    images?: MediaValue[] | null;
+};
+type ProductSelectionResolution = {
+    normalizedSelection: NormalizedProductSelection;
+    selectedVariant: ProductDetailVariant | null;
+    matchingVariants: ProductDetailVariant[];
+    partialVariants: ProductDetailVariant[];
+    availableValuesByOptionSlug: Record<string, ProductSelectionAvailableValue[]>;
+    availableValuesByOptionId: Record<string, ProductSelectionAvailableValue[]>;
+    allOptionsSelected: boolean;
+    price: {
+        min: number | null;
+        max: number | null;
+        compareAtMin: number | null;
+        compareAtMax: number | null;
+        isRange: boolean;
+    };
+    media: {
+        primaryImage: ProductDetailMedia | null;
+        images: ProductDetailMedia[];
+    };
+    stock: {
+        availableForSale: boolean;
+        isUnlimited: boolean;
+        stock: number | null;
+        reservedStock: number | null;
+        availableStock: number | null;
+    };
+};
+declare class ProductSelectionCodecError extends Error {
+    code: string;
+    constructor(message: string);
+}
+declare function buildProductOptionMatrix<TVariant extends ProductVariantShape = ProductVariantShape>({ options, variants, }: {
+    options: ProductOptionShape[];
+    variants?: TVariant[];
+}): ProductOptionMatrix<TVariant>;
+declare function buildProductOptionMatrixFromDetail(detail: ProductDetail): ProductOptionMatrix<ProductDetailVariant>;
+declare function getSelectedValueByOptionId<TVariant extends ProductVariantShape = ProductVariantShape>(matrix: ProductOptionMatrix<TVariant>, selectedValueIds: Iterable<unknown>): Map<string, string>;
+declare function normalizeSelectedValueIds<TVariant extends ProductVariantShape = ProductVariantShape>(matrix: ProductOptionMatrix<TVariant>, selectedValueIds: Iterable<unknown>): string[];
+declare function getAvailableOptionValues<TVariant extends ProductVariantShape = ProductVariantShape>(matrix: ProductOptionMatrix<TVariant>, optionId: string, selectedValueIds: Iterable<unknown>): ProductOptionMatrixValue[];
+declare function resolveVariantForSelection<TVariant extends ProductVariantShape = ProductVariantShape>(matrix: ProductOptionMatrix<TVariant>, selectedValueIds: Iterable<unknown>): ProductOptionMatrixVariant<TVariant> | undefined;
+declare function normalizeProductSelection(detail: ProductDetail, selection?: ProductSelectionInput, options?: ProductSelectionCodecOptions): NormalizedProductSelection;
+declare function normalizeProductSelectionFromMatrix(matrix: ProductOptionMatrix<ProductDetailVariant>, selection?: ProductSelectionInput, options?: ProductSelectionCodecOptions): NormalizedProductSelection;
+declare function parseProductSelection(detail: ProductDetail, search: string | URLSearchParams | URL | null | undefined, options?: ProductSelectionCodecOptions): NormalizedProductSelection;
+declare function stringifyProductSelection(detail: ProductDetail, selection?: ProductSelectionInput, options?: ProductSelectionCodecOptions): string;
+declare function createProductSelectionCodec(detail: ProductDetail, options?: ProductSelectionCodecOptions): {
+    parse: (search: string | URLSearchParams | URL | null | undefined) => NormalizedProductSelection;
+    stringify: (selection?: ProductSelectionInput) => string;
+};
+declare function resolveProductSelectionFromMatrix(matrix: ProductOptionMatrix<ProductDetailVariant>, selection?: ProductSelectionInput, options?: ProductSelectionCodecOptions, context?: ProductSelectionResolutionContext): ProductSelectionResolution;
+declare function resolveProductSelection(detail: ProductDetail, selection?: ProductSelectionInput, options?: ProductSelectionCodecOptions): ProductSelectionResolution;
+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;
+};
+declare function buildProductHref(product: ProductHrefProduct, group?: ProductHrefGroup | null, options?: ProductHrefOptions): string;
+declare function buildProductListingProjection(product: ProductListingProductShape | null | undefined, variants: ProductVariantShape[]): ProductListingProjection;
+/**
+ * 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 StockCheckResult = {
+    variantId: string;
+    available: boolean;
+    availableStock: number;
+    requestedQuantity: number;
+    error?: string;
+};
+type StockCheckResponse = {
+    results: StockCheckResult[];
+    allAvailable: boolean;
+};
+type ListingGroupsParams = {
+    productIds: string[];
+};
+type ProductListingGroupSummary = Omit<ProductListingGroup, 'variants'>;
+type ProductListingGroupsItem = {
+    product: Product;
+    primaryOptionId: string | null;
+    groups: ProductListingGroupSummary[];
+};
+type ProductListingGroupsResponse = {
+    docs: ProductListingGroupsItem[];
+};
+type ProductDetailParams = {
+    slug: string;
+} | {
+    id: string;
+};
+interface ProductDetailVariantOptionValue {
+    optionId: string | number;
+    optionSlug: string;
+    valueId: string | number;
+    valueSlug: string;
+    value?: string | null;
+}
+type ProductDetailMedia = string | number | {
+    id?: string | number | null;
+    url?: string | null;
+    alt?: string | null;
+    width?: number | null;
+    height?: number | null;
+};
+interface ProductDetailVariant {
+    id: string | number;
+    optionKey: string;
+    title?: string | null;
+    displayName: string;
+    sku?: string | null;
+    price: number;
+    compareAtPrice?: number | null;
+    stock: number;
+    reservedStock: number;
+    isUnlimited: boolean;
+    isActive: boolean;
+    thumbnail?: ProductDetailMedia | null;
+    images?: ProductDetailMedia[];
+    optionValues: ProductDetailVariantOptionValue[];
+}
+interface ProductDetailOptionValue {
+    id: string | number;
+    value: string;
+    slug: string;
+    swatchColor?: string | null;
+    thumbnail?: ProductDetailMedia | null;
+    images?: ProductDetailMedia[] | null;
+}
+interface ProductDetailOption {
+    id: string | number;
+    title: string;
+    slug: string;
+    values: ProductDetailOptionValue[];
+}
+interface ProductDetailBrand {
+    id: string | number;
+    name: string;
+    slug?: string | null;
+    logo?: unknown | null;
+}
+interface ProductDetailCategory {
+    id: string | number;
+    title: string;
+    slug?: string | null;
+}
+interface ProductDetailTag {
+    id: string | number;
+    title: string;
+    slug?: string | null;
+}
+interface ProductDetailImage {
+    id: string | number;
+    url?: string | null;
+    alt?: string | null;
+    width?: number | null;
+    height?: number | null;
+}
+interface ProductDetailVideo {
+    id: string | number;
+    url?: string | null;
+}
+interface ProductDetailListing {
+    minPrice?: number | null;
+    maxPrice?: number | null;
+    minCompareAtPrice?: number | null;
+    maxCompareAtPrice?: number | null;
+    isPriceRange?: boolean | null;
+    primaryImage?: ProductDetailMedia | null;
+    availableForSale?: boolean | null;
+    selectionHintVariant?: string | number | null;
+}
+interface ProductDetail {
+    product: {
+        id: string | number;
+        slug: string;
+        title: string;
+        subtitle?: string | null;
+        description?: string | null;
+        content?: unknown;
+        publishedAt?: string | null;
+        status: string;
+        totalInventory: number;
+        totalVariants: number;
+        hasOnlyDefaultVariant: boolean;
+    };
+    variants: ProductDetailVariant[];
+    options: ProductDetailOption[];
+    brand: ProductDetailBrand | null;
+    categories: ProductDetailCategory[];
+    tags: ProductDetailTag[];
+    images: ProductDetailImage[];
+    videos: ProductDetailVideo[];
+    listing: ProductDetailListing;
+}
+type ProductUpsertOptionValueInput = {
+    id?: string;
+    value: string;
+    slug?: string;
+    swatchColor?: string | null;
+    thumbnail?: string | null;
+    images?: string[];
+    metadata?: unknown;
+};
+type ProductUpsertOptionInput = {
+    id?: string;
+    title: string;
+    slug?: string;
+    values: ProductUpsertOptionValueInput[];
+};
+type ProductUpsertVariantOptionValue = string | {
+    valueSlug?: string;
+    valueId?: string;
+    value?: string;
+};
+type ProductUpsertVariantInput = {
+    id?: string;
+    optionValues?: Record<string, ProductUpsertVariantOptionValue> | string[];
+    sku?: string | null;
+    title?: string | null;
+    price: number;
+    compareAtPrice?: number | null;
+    stock?: number;
+    isUnlimited?: boolean;
+    weight?: number | null;
+    requiresShipping?: boolean;
+    barcode?: string | null;
+    externalId?: string | null;
+    isActive?: boolean;
+    thumbnail?: string | null;
+    images?: string[];
+    metadata?: unknown;
+};
+type ProductUpsertParams = {
+    product: Record<string, unknown> & {
+        id?: string;
+        title?: string;
+    };
+    options?: ProductUpsertOptionInput[];
+    variants?: ProductUpsertVariantInput[];
+};
+type ProductUpsertResponse = {
+    ok: true;
+    product: Product;
+} | {
+    ok: false;
+    failedEntity: 'product' | 'option' | 'option-value' | 'variant';
+    failedIndex?: number;
+    message: string;
+};
+declare class ProductApi extends BaseApi {
+    constructor(options: ProductApiOptions);
+    /**
+     * 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>;
+    listingGroups(params: ListingGroupsParams): Promise<ProductListingGroupsResponse>;
+    /**
+     * Fetch full product detail by slug or id.
+     * Returns `null` on 404 regardless of reason (`not_found` / `not_published` /
+     * `tenant_mismatch` / `feature_disabled`). For the reason behind a null,
+     * inspect `client.lastRequestId` against backend logs.
+     */
+    detail(params: ProductDetailParams): Promise<ProductDetail | null>;
+    /**
+     * Atomically create or update a product together with its options,
+     * option-values, and variants in a single transaction. Mirrors Shopify's
+     * `productSet` shape and is the canonical write path for the MCP
+     * `product-upsert` tool.
+     */
+    upsert(params: ProductUpsertParams): Promise<ProductUpsertResponse>;
+}
+
+type DiscountApiOptions = ServerApiOptions;
+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 CalculateShippingResult = {
+    shippingAmount: number;
+    baseShippingAmount: number;
+    extraShippingAmount: number;
+    freeShipping: boolean;
+    freeShippingMinAmount: number | null;
+    isJeju: boolean;
+    isRemoteIsland: boolean;
+};
+declare class ShippingApi extends BaseApi {
+    constructor(options: ShippingApiOptions);
+    calculate(params: CalculateShippingParams): Promise<CalculateShippingResult>;
+}
+
+type OrderApiOptions = ServerApiOptions;
+type CustomerSnapshot = {
+    name?: string;
+    email: string;
+    phone?: string;
+};
+type ReturnReason = 'change_of_mind' | 'defective' | 'wrong_delivery' | 'damaged' | 'other';
+type ReturnItem = {
+    orderItem: string;
+    quantity: number;
+};
+type CreateOrderParams = {
+    orderNumber: string;
+    customer?: string;
+    customerSnapshot: CustomerSnapshot;
+    shippingAddress: Order['shippingAddress'];
+    orderItems: Pick<OrderItem, 'product' | 'variant' | 'quantity' | 'unitPrice' | 'totalPrice'>[];
+    totalAmount: number;
+    shippingAmount?: number;
+    pgPaymentId?: string;
+    discountCode?: string;
+};
+type UpdateOrderParams = {
+    orderNumber: string;
+    status: Order['status'];
+};
+type TransactionStatus = 'pending' | 'paid' | 'failed' | 'canceled';
+type UpdateTransactionParams = {
+    pgPaymentId: string;
+    status: TransactionStatus;
+    paymentMethod?: string;
+    receiptUrl?: string;
+    paymentKey?: string;
+    amount?: number;
+};
+type ConfirmPaymentParams = {
+    orderNumber?: string;
+    pgPaymentId: string;
+    pgProvider: string;
+    pgOrderId?: string;
+    amount: number;
+    currency?: string;
+    paymentMethod?: string;
+    receiptUrl?: string;
+    approvedAt?: string;
+    providerStatus?: string;
+    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 RestockAction = 'return_to_stock' | 'discard';
+type ReturnWithRefundItem = {
+    orderItem: string | number;
+    quantity: number;
+    restockAction?: RestockAction;
+};
+type ReturnWithRefundParams = {
+    orderNumber: string;
+    reason?: ReturnReason;
+    reasonDetail?: string;
+    returnItems: ReturnWithRefundItem[];
+    refundAmount: number;
+    pgPaymentId: string;
+    paymentKey?: string;
+    refundReceiptUrl?: string;
+};
+type CheckoutParams = {
+    cartId: string;
+    orderNumber: string;
+    customerSnapshot: CustomerSnapshot;
+    pgPaymentId?: string;
+    discountCode?: string;
+};
+type CreateFulfillmentParams = {
+    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;
+};
+type BulkImportFulfillmentsParams = {
+    items: Array<{
+        orderNumber: string;
+        carrier?: string;
+        trackingNumber?: string;
+    }>;
+};
+type BulkImportFulfillmentsResponse = {
+    succeeded: Array<{
+        orderNumber: string;
+        fulfillmentId: string;
+    }>;
+    failed: Array<{
+        orderNumber: string;
+        error: string;
+    }>;
+};
+type CreateReturnParams = {
+    orderNumber: string;
+    reason?: ReturnReason;
+    reasonDetail?: string;
+    returnItems: ReturnItem[];
+    refundAmount: number;
+};
+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>;
+    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>;
+}
+
+interface CommerceClientOptions {
+    publishableKey: string;
+    apiUrl?: string;
+    customerToken: () => string | null;
+    onUnauthorized?: () => Promise<string | null>;
+    onRequestId?: (id: string | null) => void;
+    customerAuth: CustomerAuth;
+}
+declare class CommerceClient {
+    readonly product: {
+        stockCheck: (params: StockCheckParams) => Promise<StockCheckResponse>;
+        listingGroups: (params: ListingGroupsParams) => Promise<ProductListingGroupsResponse>;
+        detail: (params: ProductDetailParams) => Promise<ProductDetail | null>;
+    };
+    readonly cart: {
+        get: (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>;
+        clear: (params: ClearCartParams) => Promise<{
+            success: boolean;
+        }>;
+    };
+    readonly orders: {
+        checkout: (params: CheckoutParams) => Promise<Order>;
+        listMine: (options?: {
+            page?: number;
+            limit?: number;
+            status?: string;
+        }) => Promise<PayloadFindResponse<Order>>;
+    };
+    readonly discounts: {
+        validate: (params: ValidateDiscountParams) => Promise<ValidateDiscountResult>;
+    };
+    readonly shipping: {
+        calculate: (params: CalculateShippingParams) => Promise<CalculateShippingResult>;
+    };
+    constructor(options: CommerceClientOptions);
+}
+
+/**
+ * Customer namespace. Currently exposes .auth; reserved for future customer-
+ * scoped capabilities (addresses, preferences, etc.).
+ */
+declare class CustomerNamespace {
+    readonly auth: CustomerAuth;
+    constructor(publishableKey: string, options?: CustomerAuthOptions, apiUrl?: string);
+}
+
+interface ClientConfig {
+    publishableKey: string;
+    /** API base URL for staging, self-hosted, preview, or proxy deployments. */
+    apiUrl?: string;
+    /**
+     * Customer authentication options.
+     * Used to initialize CustomerAuth on Client.
+     */
+    customer?: {
+        /**
+         * 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;
+    };
+}
+interface ClientServerConfig extends ClientConfig {
+    secretKey: string;
+}
+interface ClientMetadata {
+    userAgent?: string;
+    timestamp: number;
+}
+interface ClientState {
+    metadata: ClientMetadata;
+}
+/**
+ * Payload CMS Find (List) Response
+ * GET /api/{collection}
+ */
+interface PayloadFindResponse<T = unknown> {
+    docs: T[];
+    totalDocs: number;
+    limit: number;
+    totalPages: number;
+    page: number;
+    pagingCounter: number;
+    hasPrevPage: boolean;
+    hasNextPage: boolean;
+    prevPage: number | null;
+    nextPage: number | null;
+}
+/**
+ * Payload CMS Create/Update Response
+ * POST /api/{collection}
+ * PATCH /api/{collection}/{id}
+ */
+interface PayloadMutationResponse<T = unknown> {
+    message: string;
+    doc: T;
+    errors?: unknown[];
+}
+type Sort = string | string[];
+type Where = Record<string, unknown>;
+/**
+ * Do NOT replace with `Pick<FindOptions>` from `payload` or import Payload
+ * types here. Payload's generic query types depend on `PayloadTypes` module
+ * augmentation; external SDK consumers who only use `createClient` should not
+ * install Payload just to type REST query objects. Excluded vs native:
+ * Local-API-only fields, `locale`/`fallbackLocale`.
+ */
+interface ApiQueryOptions {
+    page?: number;
+    limit?: number;
+    sort?: Sort;
+    /**
+     * Filter documents. Id-based relation filters (`where: { product: { equals: id } }`) are the
+     * most reliable pattern. Dotted-path relation filters (`where: { 'product.slug': { equals } }`)
+     * are Payload-native but may silently return empty when access control restricts the related
+     * document or when the relation is polymorphic. String shorthand (`where: { slug: 'x' }`)
+     * silently matches nothing — always use `{ slug: { equals: 'x' } }`.
+     */
+    where?: Where;
+    /**
+     * Controls how deeply relationship fields are populated. This is the primary control for
+     * populating relationships like `category`, `images`, `brand`. The configured Payload default
+     * applies when unset.
+     */
+    depth?: number;
+    select?: Record<string, boolean>;
+    /**
+     * Controls which fields are returned for already-populated relationships, keyed by collection
+     * slug. Does NOT control which relationships to populate — that is `depth`.
+     *
+     * @example
+     * // depth: 2 populates category; populate trims which fields come back
+     * populate: { categories: { title: true, slug: true } }
+     */
+    populate?: Record<string, boolean | Record<string, boolean>>;
+    /**
+     * Controls Payload `type: 'join'` virtual reverse-relation fields only (pagination, sort,
+     * filter, count per join field, or `false` to disable all join-field population).
+     *
+     * Does NOT populate normal relationship fields like `category`, `images`, or `brand`.
+     * For normal relationship population use `depth` (and optionally `populate` for field
+     * selection).
+     *
+     * Pass `joins: false` to disable all join-field population — useful for lightweight list
+     * queries where join fields are not needed.
+     *
+     * @example
+     * // `article-authors` has a `type: 'join'` field `articles` (reverse-relation)
+     * joins: { articles: { limit: 10, sort: '-publishedAt' } }
+     *
+     * // depth: 2 populates product.category — joins has no effect on this
+     * depth: 2
+     *
+     * // Disable all join-field population
+     * joins: false
+     */
+    joins?: Record<string, {
+        limit?: number;
+        page?: number;
+        sort?: string;
+        where?: Where;
+        count?: boolean;
+    } | false> | false;
+    /** Set to `false` to skip the count query — returns docs without totalDocs/totalPages */
+    pagination?: boolean;
+    /** Include draft versions (access control still applies on the server) */
+    draft?: boolean;
+    /** Include soft-deleted documents (requires `trash` enabled on the collection) */
+    trash?: boolean;
+}
+interface DebugConfig {
+    logRequests?: boolean;
+    logResponses?: boolean;
+    logErrors?: boolean;
+}
+interface RetryConfig {
+    maxRetries?: number;
+    retryableStatuses?: number[];
+    retryDelay?: (attempt: number) => number;
+}
+interface RootQueryLookup<T extends string> {
+    find(options?: ApiQueryOptions): Promise<PayloadFindResponse<CollectionType<T>>>;
+    findById(id: string | number, options?: ApiQueryOptions): Promise<CollectionType<T>>;
+    count(options?: ApiQueryOptions): Promise<{
+        totalDocs: number;
+    }>;
+}
+type RootReadOnlyQueryBuilder<T extends PublicCollection> = RootQueryLookup<T>;
+interface RootCollectionClient {
+    from<T extends PublicCollection>(collection: T): RootReadOnlyQueryBuilder<T>;
+}
+interface RootClient {
+    commerce: CommerceClient;
+    community: CommunityClient;
+    customer: CustomerNamespace;
+    collections: RootCollectionClient;
+    lastRequestId: string | null;
+    getState(): ClientState;
+    getConfig(): ClientConfig;
+}
+type DeepPartial<T> = {
+    [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
+};
+type ExtractArrayType<T> = T extends (infer U)[] ? U : never;
+
+export { type OrderApiOptions as $, type ApiQueryOptions as A, BaseApi as B, CommerceClient as C, type DebugConfig as D, type ExtractArrayType as E, type CreateFulfillmentParams as F, type CreateOrderParams as G, type CreateReturnParams as H, CustomerAuth as I, type CustomerAuthOptions as J, type CustomerAuthResponse as K, type CustomerLoginData as L, type CustomerProfile as M, type CustomerRefreshResponse as N, type CustomerRegisterData as O, type PayloadFindResponse as P, type CustomerRegisterResponse as Q, type RetryConfig as R, type Sort as S, type CustomerSnapshot as T, DiscountApi as U, type DiscountApiOptions as V, type Where as W, type LegacyProductSelectionParamEvent as X, type ListingGroupsParams as Y, type NormalizedProductSelection as Z, OrderApi as _, CommunityClient as a, buildProductOptionMatrixFromDetail as a$, ProductApi as a0, type ProductApiOptions as a1, type ProductDetail as a2, type ProductDetailBrand as a3, type ProductDetailCategory as a4, type ProductDetailImage as a5, type ProductDetailImageMedia as a6, type ProductDetailListing as a7, type ProductDetailMedia as a8, type ProductDetailOption as a9, type ProductSelectionResolution as aA, type ProductSelectionResolutionContext as aB, type ProductVariantShape as aC, type RemoveDiscountParams as aD, type RemoveItemParams as aE, type RequestOptions as aF, type ReturnItem as aG, type ReturnReason as aH, type ReturnWithRefundParams as aI, type ServerApiOptions as aJ, ShippingApi as aK, type ShippingApiOptions as aL, type StockCheckParams as aM, type StockCheckResponse as aN, type StockCheckResult as aO, type UpdateFulfillmentParams as aP, type UpdateItemParams as aQ, type UpdateOrderParams as aR, type UpdateProfileData as aS, type UpdateReturnParams as aT, type UpdateTransactionParams as aU, type ValidateDiscountParams as aV, type ValidateDiscountResult as aW, buildProductHref as aX, buildProductListingGroupsByOption as aY, buildProductListingProjection as aZ, buildProductOptionMatrix as a_, type ProductDetailOptionValue as aa, type ProductDetailParams as ab, type ProductDetailTag as ac, type ProductDetailVariant as ad, type ProductDetailVariantOptionValue as ae, type ProductDetailVideo as af, type ProductHrefGroup as ag, type ProductHrefOptions as ah, type ProductHrefProduct as ai, type ProductListingGroup as aj, type ProductListingGroupSummary as ak, type ProductListingGroupsItem as al, type ProductListingGroupsResponse as am, type ProductListingProductShape as an, type ProductListingProjection as ao, type ProductOptionMatrix as ap, type ProductOptionMatrixOption as aq, type ProductOptionMatrixValue as ar, type ProductOptionMatrixVariant as as, type ProductOptionShape as at, type ProductOptionValueShape as au, type ProductSelectionAvailableValue as av, type ProductSelectionByOptionValue as aw, ProductSelectionCodecError as ax, type ProductSelectionCodecOptions as ay, type ProductSelectionInput as az, CustomerNamespace as b, createProductSelectionCodec as b0, getAvailableOptionValues as b1, getProductSelectionImages as b2, getSelectedValueByOptionId as b3, normalizeProductSelection as b4, normalizeProductSelectionFromMatrix as b5, normalizeSelectedValueIds as b6, parseProductSelection as b7, resolveProductSelection as b8, resolveProductSelectionFromMatrix as b9, resolveVariantForSelection as ba, stringifyProductSelection as bb, type ProductUpsertParams as bc, type ProductUpsertResponse as bd, type ClientServerConfig as be, type ClientState as c, type ClientConfig as d, type ClientMetadata as e, type DeepPartial as f, type PayloadMutationResponse as g, type RootClient as h, type RootCollectionClient as i, type RootReadOnlyQueryBuilder as j, type AddItemParams as k, type ApplyDiscountParams as l, type BulkImportFulfillmentsParams as m, type BulkImportFulfillmentsResponse as n, type CalculateShippingParams as o, type CalculateShippingResult as p, CartApi as q, type CartApiOptions as r, type CheckoutParams as s, type ClearCartParams as t, type CommerceClientOptions as u, type CommunityClientOptions as v, type CommunityPost as w, type CompatibilityProductSelectionParamEvent as x, type ConfirmPaymentParams as y, type ConfirmPaymentResponse as z };