@magicstoreai/hydrogen 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,790 @@
+import * as _magicstoreai_storefront_client from '@magicstoreai/storefront-client';
+import { StorefrontClient, operations, Schema, MagicStoreError, StorefrontClientOptions } from '@magicstoreai/storefront-client';
+export { MagicStoreError } from '@magicstoreai/storefront-client';
+import * as react from 'react';
+import { ReactNode, ComponentPropsWithoutRef, ElementType } from 'react';
+
+/** Where the SDK keeps what outlives a page: the customer session, the cart id, the guest wishlist. */
+interface KeyValueStorage {
+    get(key: string): string | null;
+    set(key: string, value: string): void;
+    remove(key: string): void;
+}
+/** In memory — for tests, the server, and when the browser refuses storage. */
+declare function memoryStorage(initial?: Record<string, string>): KeyValueStorage;
+/**
+ * `localStorage` when the browser allows it; memory otherwise (server render, private mode,
+ * blocked site data). Every access is guarded: storage can throw at any time.
+ */
+declare function browserStorage(): KeyValueStorage;
+/**
+ * A tiny observable value — what the React hooks subscribe to. `serverValue` is what a server render
+ * and hydration see: storage is browser-only, so both must render the same "not known yet" state
+ * and let the stored one arrive after hydration (otherwise React reports a hydration mismatch).
+ */
+declare class Observable<T> {
+    private value;
+    private listeners;
+    private readonly serverValue;
+    constructor(value: T, serverValue?: T);
+    get(): T;
+    protected set(value: T): void;
+    subscribe: (listener: () => void) => (() => void);
+    getSnapshot: () => T;
+    getServerSnapshot: () => T;
+}
+
+type EventsBody = NonNullable<operations['analyticsEventsStore']['requestBody']>['content']['application/json'];
+type AnalyticsEvent = EventsBody['events'][number];
+type AnalyticsEventType = Schema<'StorefrontEventType'>;
+type AnalyticsPayload = AnalyticsEvent['payload'];
+/**
+ * The visitor's id for the shop's analytics and funnel: a UUID minted once per visitor and kept.
+ * The same value goes out as `X-Session-Id`, which ties carts and orders to the visit.
+ */
+declare function visitorSessionId(storage: KeyValueStorage, key?: string): string;
+/**
+ * What the visitor looks at, sent in batches (`POST /analytics/events`). Cart and checkout steps
+ * are recorded by the server — never report them. Failures are dropped: analytics must never get
+ * in the way of shopping.
+ */
+declare class AnalyticsController {
+    private readonly client;
+    private readonly sessionId;
+    private readonly options;
+    private queue;
+    private timer;
+    constructor(client: StorefrontClient, sessionId: string, options?: {
+        flushAfterMs?: number;
+        context?: AnalyticsPayload;
+    });
+    /** A page view — starts the session with its first-touch attribution (UTM, click ids, referrer). */
+    pageView(path: string, extra?: AnalyticsPayload): void;
+    productView(productId: string, variantId?: string | null): void;
+    collectionView(collectionId: string): void;
+    search(query: string, resultsCount?: number): void;
+    custom(name: string, properties?: Record<string, unknown>): void;
+    track(type: AnalyticsEventType, payload: AnalyticsPayload): void;
+    /** Sends what is queued now — call it when the page is hidden. */
+    flush(): Promise<void>;
+}
+/** The first-touch attribution a landing URL carries, for the first `pageView`. */
+declare function attributionFrom(url: URL, referrer?: string): AnalyticsPayload;
+
+type Cart = Schema<'Cart'>;
+type CartLine = Schema<'CartLine'>;
+type CartAttribute = {
+    key: string;
+    value: string | null;
+};
+/** A line to add: the product, its variant (null for a product without variants) and how many. */
+interface CartLineInput {
+    productId: string;
+    variantId?: string | null;
+    quantity?: number;
+    attributes?: CartAttribute[];
+}
+interface CartState {
+    cart: Cart | null;
+    /** `loading` while the stored cart is fetched; `updating` while a change is on its way. */
+    status: 'idle' | 'loading' | 'updating';
+    /** The last change that failed — the cart is back to what the server holds. */
+    error: MagicStoreError | null;
+}
+/**
+ * The visitor's cart. Its id is a capability and lives only in storage; the cart itself always
+ * comes from the server, so prices, discounts and availability are the server's. Quantity changes
+ * show at once and roll back if the server refuses them. Changes run one after another.
+ */
+declare class CartController extends Observable<CartState> {
+    private readonly client;
+    private readonly storage;
+    private readonly key;
+    private queue;
+    constructor(client: StorefrontClient, storage: KeyValueStorage, key?: string);
+    get cart(): Cart | null;
+    get cartId(): string | null;
+    /** Fetches the stored cart, if any. A cart that is gone is forgotten. */
+    load(): Promise<Cart | null>;
+    /** Adds lines; the first add creates the cart. */
+    addLines(lines: CartLineInput[]): Promise<Cart | null>;
+    /** The line's quantity outright; 0 removes it. Shown at once, rolled back if refused. */
+    updateLine(lineId: string, quantity: number): Promise<Cart | null>;
+    removeLine(lineId: string): Promise<Cart | null>;
+    /** The cart's codes as a whole — `[]` takes the code off. A code that does not apply is kept, flagged. */
+    setDiscountCodes(discountCodes: string[]): Promise<Cart | null>;
+    setNote(note: string | null): Promise<Cart | null>;
+    setAttributes(attributes: CartAttribute[]): Promise<Cart | null>;
+    /** The gift promotion chosen from `cart.giftOptions`; null takes it off. */
+    setGift(promotionId: string | null): Promise<Cart | null>;
+    /** Points to spend on this cart (signed-in customers). */
+    setPoints(points: number): Promise<Cart | null>;
+    /**
+     * After sign-in: the cart becomes the customer's. When they already had an open cart, this one
+     * merges into it and the answer is THAT cart — its id replaces the stored one.
+     */
+    attachCustomer(): Promise<Cart | null>;
+    /** After sign-out: the cart is the customer's, not this visitor's any more. */
+    forget(): void;
+    /** Shows `optimistic` at once (when given), sends the change, and adopts the server's cart or rolls back. */
+    private mutate;
+    private adopt;
+    private fail;
+    private patch;
+    private enqueue;
+}
+
+type Money$1 = Schema<'Money'>;
+type MoneyFormat = Schema<'Shop'>['moneyFormat'];
+/** The currency's symbol or word in a locale: `сум`, `so‘m`, `$`. */
+declare function currencySymbol(currencyCode: string, locale: string): string;
+/**
+ * `12500.00` → `12 500`: groups of three separated by a space, the fraction kept only when it is
+ * not zero. The amount is never rounded here — the API already applied the shop's rounding, and
+ * the string is exactly what will be charged.
+ */
+declare function groupAmount(amount: string): string;
+/**
+ * Money as the shop shows it: `shop.moneyFormat.format` places the symbol or the code, and a shop
+ * with no format uses the currency's own convention (`12 500 сум`, `$129.99`).
+ */
+declare function formatMoney(money: Money$1, options: {
+    locale: string;
+    format?: MoneyFormat | null;
+}): string;
+/** The amount as a number, for arithmetic you must do on the client (sorting, a progress bar). */
+declare function moneyAmount(money: Money$1): number;
+
+type CustomerSession = Schema<'CustomerSession'>;
+type Customer = Schema<'Customer'>;
+interface SessionState {
+    session: CustomerSession | null;
+}
+/**
+ * The signed-in customer and their tokens. The access token lives an hour and is refreshed on
+ * demand; the refresh token works once, so concurrent callers share one refresh.
+ */
+declare class CustomerSessionController extends Observable<SessionState> {
+    private readonly storage;
+    private readonly key;
+    private readonly now;
+    private refreshing;
+    private client;
+    constructor(storage: KeyValueStorage, key?: string, now?: () => number);
+    /** The client the session signs in and refreshes through (created with this controller's token). */
+    attach(client: StorefrontClient): void;
+    get session(): CustomerSession | null;
+    get customer(): Customer | null;
+    /** The bearer for the next call: refreshed when it is about to expire; null when signed out. */
+    accessToken: () => Promise<string | null>;
+    /** One refresh at a time: every caller waiting meanwhile gets its result. */
+    refresh(): Promise<string | null>;
+    private doRefresh;
+    /** Texts a sign-in code. */
+    requestOtp(phone: string): Promise<Schema<'OtpChallenge'>>;
+    verifyOtp(phone: string, code: string, referralCode?: string): Promise<CustomerSession>;
+    signInWithTelegram(initData: string, referralCode?: string): Promise<CustomerSession>;
+    signInWithOq(oqToken: string): Promise<CustomerSession>;
+    signInWithClick(webSession: string): Promise<CustomerSession>;
+    /** Ends this sign-in on the server too; signed out locally whatever the server says. */
+    signOut(): Promise<void>;
+    /** The customer as the server has them now (after a profile change). */
+    reloadCustomer(): Promise<Customer | null>;
+    private signedIn;
+    private store;
+    private requireClient;
+}
+
+type ProductVariant = Schema<'ProductVariant'>;
+type ProductOption = Schema<'ProductOption'>;
+/** What variant selection needs of a product — `Product` and `ProductDetail` both fit. */
+interface SelectableProduct {
+    options: ProductOption[];
+    variants: ProductVariant[];
+}
+type SelectedOptions = Record<string, string>;
+declare function optionsOf(variant: ProductVariant): SelectedOptions;
+/** The variant whose options are exactly these, or null while the selection is incomplete. */
+declare function variantFor(product: SelectableProduct, selected: SelectedOptions): ProductVariant | null;
+/**
+ * Where selection starts: the given variant, else the first one for sale, else the first one.
+ * A product with a single variant and no options is always "selected".
+ */
+declare function initialSelection(product: SelectableProduct, variantId?: string | null): SelectedOptions;
+/**
+ * Whether picking `value` for `name` — keeping the other choices — lands on a variant for sale.
+ * What a storefront uses to grey out a size that is sold out in the chosen colour.
+ */
+declare function isOptionValueAvailable(product: SelectableProduct, selected: SelectedOptions, name: string, value: string): boolean;
+/**
+ * Choosing a value keeps the other choices when that combination exists; otherwise it moves to the
+ * closest variant that has the new value (for sale first), so the selection never dead-ends.
+ */
+declare function selectOption(product: SelectableProduct, selected: SelectedOptions, name: string, value: string): SelectedOptions;
+
+interface WishlistState {
+    /** Product ids, most recent first. */
+    productIds: string[];
+    /** Whose list it is: a guest's lives in this browser, a customer's on the server. */
+    owner: 'guest' | 'customer';
+    status: 'idle' | 'loading';
+}
+/** The server keeps up to this many; a guest list is capped the same. */
+declare const WISHLIST_LIMIT = 500;
+/**
+ * Saved products. A guest's list is kept in this browser; on sign-in it moves into the customer's
+ * list on the server and the local copy is cleared. Changes show at once and roll back if refused.
+ */
+declare class WishlistController extends Observable<WishlistState> {
+    private readonly client;
+    private readonly storage;
+    private readonly key;
+    constructor(client: StorefrontClient, storage: KeyValueStorage, key?: string);
+    has(productId: string): boolean;
+    add(productId: string): Promise<void>;
+    remove(productId: string): Promise<void>;
+    toggle(productId: string): Promise<void>;
+    /** After sign-in: the guest's products join the customer's list, then the list is the server's. */
+    signedIn(): Promise<void>;
+    /** After sign-out: back to an empty guest list — the customer's list stays on the server. */
+    signedOut(): void;
+    /** The customer's list as the server has it. */
+    reload(): Promise<void>;
+    private setIds;
+}
+
+type MoneyProps<As extends ElementType> = {
+    data: Money$1 | null | undefined;
+    as?: As;
+    /** What to render for a missing price (the API sends null for "unknown", never 0). */
+    fallback?: ReactNode;
+} & Omit<ComponentPropsWithoutRef<As>, 'children'>;
+/**
+ * A price as the shop shows it (`shop.moneyFormat`, the storefront's locale).
+ *
+ * @example
+ * <Money data={product.price} fallback={<span>—</span>} />
+ */
+declare function Money<As extends ElementType = 'span'>({ data, as, fallback, ...rest }: MoneyProps<As>): react.JSX.Element;
+type ImageProps = {
+    data: Schema<'Image'> | null | undefined;
+    /** Used when the image has no alt text of its own. */
+    alt?: string;
+    fallback?: ReactNode;
+} & Omit<ComponentPropsWithoutRef<'img'>, 'src' | 'alt'>;
+/**
+ * An API image with lazy loading by default. Its intrinsic size is set (no layout shift) unless
+ * you pass `width` / `height` to draw it at another size, e.g. a 64×64 cart thumbnail.
+ *
+ * @example
+ * <Image data={product.featuredImage} alt={product.title} fallback={<div className="noimg" />} />
+ */
+declare function Image({ data, alt, fallback, loading, decoding, width, height, ...rest }: ImageProps): react.JSX.Element;
+interface PaginationState {
+    page: number;
+    totalPages: number;
+    hasPreviousPage: boolean;
+    hasNextPage: boolean;
+    previousPage: number | null;
+    nextPage: number | null;
+    /** Page numbers around the current one, with `null` for a gap: `[1, null, 4, 5, 6, null, 12]`. */
+    pages: Array<number | null>;
+}
+declare function paginationState(meta: Pagination, around?: number): PaginationState;
+type Pagination = Schema<'Pagination'>;
+/**
+ * Headless pagination over `meta.pagination`: you render the links, it does the arithmetic.
+ *
+ * @example
+ * <Pagination meta={products.meta.pagination}>
+ *   {({ pages }) =>
+ *     pages.map((page, i) =>
+ *       page === null ? <span key={i}>…</span> : <a key={i} href={`?page=${page}`}>{page}</a>,
+ *     )
+ *   }
+ * </Pagination>
+ */
+declare function Pagination({ meta, around, children, }: {
+    meta: Pagination;
+    around?: number;
+    children: (state: PaginationState) => ReactNode;
+}): react.JSX.Element;
+
+type Shop = Schema<'Shop'>;
+interface MagicStore {
+    client: StorefrontClient;
+    /** Null until `/shop` has loaded, unless the page passed `shop` in. */
+    shop: Shop | null;
+    locale: string;
+    session: CustomerSessionController;
+    cart: CartController;
+    wishlist: WishlistController;
+    analytics: AnalyticsController;
+    sessionId: string;
+}
+interface MagicStoreProviderProps extends Pick<StorefrontClientOptions, 'shopDomain' | 'baseUrl' | 'storefrontToken' | 'fetch' | 'retry'> {
+    /** The language the storefront renders in; the shop's default when omitted. */
+    locale?: string;
+    /** The shop, when the page already has it (server-rendered) — saves a `/shop` call. */
+    shop?: Shop;
+    /** Where the session, cart id and guest wishlist are kept; `localStorage` by default. */
+    storage?: KeyValueStorage;
+    children: ReactNode;
+}
+/**
+ * The root of a storefront: one client, and the customer, cart, wishlist and analytics built on it.
+ * On sign-in the cart becomes the customer's and the guest wishlist moves into their list; on
+ * sign-out both are left behind with the customer.
+ *
+ * @example
+ * // app/providers.tsx ('use client'); `shop` comes from a server-side `api.shop()`.
+ * <MagicStoreProvider shopDomain="shop.example.uz" shop={shop} locale="ru">
+ *   {children}
+ * </MagicStoreProvider>
+ */
+declare function MagicStoreProvider(props: MagicStoreProviderProps): react.JSX.Element;
+/**
+ * Everything the provider holds: client, shop, locale and the controllers. Throws outside
+ * `<MagicStoreProvider>`.
+ *
+ * @example
+ * const { locale, sessionId } = useMagicStore();
+ */
+declare function useMagicStore(): MagicStore;
+/**
+ * The typed API client, for anything the hooks do not cover.
+ *
+ * @example
+ * const client = useStorefrontClient();
+ * const { data } = await client.searchSuggestions({ query: { q } });
+ */
+declare function useStorefrontClient(): StorefrontClient;
+/**
+ * The shop (`GET /shop`): name, currency, money format, locales, features, branding…
+ *
+ * @example
+ * const shop = useShop();
+ * return <span>{shop?.name}</span>;
+ */
+declare function useShop(): Shop | null;
+
+/**
+ * The signed-in customer and every way to sign in and out.
+ *
+ * @wraps CustomerSessionController
+ * @example
+ * const { customer, isSignedIn, requestOtp, verifyOtp, signOut } = useCustomer();
+ * await requestOtp('+998901234567');
+ * await verifyOtp('+998901234567', code);
+ */
+declare function useCustomer(): {
+    customer: {
+        createdAt: string | null;
+        deletionRequestedAt: string | null;
+        gender: "MALE" | "FEMALE" | null;
+        id: string;
+        locale: string | null;
+        name: string | null;
+        phone: string | null;
+        referralCode: string | null;
+    } | null;
+    isSignedIn: boolean;
+    requestOtp: (phone: string) => Promise<{
+        codeLength: number;
+        expiresAt: string;
+    }>;
+    verifyOtp: (phone: string, code: string, referralCode?: string) => Promise<{
+        accessToken: string;
+        customer: _magicstoreai_storefront_client.components["schemas"]["Customer"];
+        expiresAt: string;
+        refreshToken: string;
+        refreshTokenExpiresAt: string;
+    }>;
+    signInWithTelegram: (initData: string, referralCode?: string) => Promise<{
+        accessToken: string;
+        customer: _magicstoreai_storefront_client.components["schemas"]["Customer"];
+        expiresAt: string;
+        refreshToken: string;
+        refreshTokenExpiresAt: string;
+    }>;
+    signInWithOq: (oqToken: string) => Promise<{
+        accessToken: string;
+        customer: _magicstoreai_storefront_client.components["schemas"]["Customer"];
+        expiresAt: string;
+        refreshToken: string;
+        refreshTokenExpiresAt: string;
+    }>;
+    signInWithClick: (webSession: string) => Promise<{
+        accessToken: string;
+        customer: _magicstoreai_storefront_client.components["schemas"]["Customer"];
+        expiresAt: string;
+        refreshToken: string;
+        refreshTokenExpiresAt: string;
+    }>;
+    signOut: () => Promise<void>;
+    reload: () => Promise<{
+        createdAt: string | null;
+        deletionRequestedAt: string | null;
+        gender: "MALE" | "FEMALE" | null;
+        id: string;
+        locale: string | null;
+        name: string | null;
+        phone: string | null;
+        referralCode: string | null;
+    } | null>;
+};
+/**
+ * The visitor's cart and every change to it. The first `addLines` creates the cart.
+ *
+ * @wraps CartController
+ * @example
+ * const { cart, totalQuantity, status, error, addLine } = useCart();
+ * await addLine({ productId: product.id, variantId: selectedVariant?.id ?? null, quantity: 1 });
+ */
+declare function useCart(): {
+    totalQuantity: number;
+    addLines: (lines: CartLineInput[]) => Promise<{
+        attributes: {
+            key: string;
+            value: string;
+        }[];
+        buyerIdentity: {
+            customerId: string;
+        } | null;
+        cost: {
+            discountTotal: _magicstoreai_storefront_client.components["schemas"]["Money"] | null;
+            pointsDiscount: _magicstoreai_storefront_client.components["schemas"]["Money"] | null;
+            subtotal: _magicstoreai_storefront_client.components["schemas"]["Money"] | null;
+            total: _magicstoreai_storefront_client.components["schemas"]["Money"] | null;
+            welcomeDiscount: _magicstoreai_storefront_client.components["schemas"]["Money"] | null;
+        };
+        createdAt: string | null;
+        discountCodes: _magicstoreai_storefront_client.components["schemas"]["CartDiscountCode"][];
+        expiresAt: string | null;
+        giftOptions: _magicstoreai_storefront_client.components["schemas"]["CartGiftOption"][];
+        id: string;
+        lines: _magicstoreai_storefront_client.components["schemas"]["CartLine"][];
+        note: string | null;
+        points: _magicstoreai_storefront_client.components["schemas"]["CartPoints"] | null;
+        selectedGift: _magicstoreai_storefront_client.components["schemas"]["CartGiftOption"] | null;
+        status: "ACTIVE" | "COMPLETED" | "MERGED";
+        totalQuantity: number;
+        updatedAt: string | null;
+    } | null>;
+    addLine: (line: CartLineInput) => Promise<{
+        attributes: {
+            key: string;
+            value: string;
+        }[];
+        buyerIdentity: {
+            customerId: string;
+        } | null;
+        cost: {
+            discountTotal: _magicstoreai_storefront_client.components["schemas"]["Money"] | null;
+            pointsDiscount: _magicstoreai_storefront_client.components["schemas"]["Money"] | null;
+            subtotal: _magicstoreai_storefront_client.components["schemas"]["Money"] | null;
+            total: _magicstoreai_storefront_client.components["schemas"]["Money"] | null;
+            welcomeDiscount: _magicstoreai_storefront_client.components["schemas"]["Money"] | null;
+        };
+        createdAt: string | null;
+        discountCodes: _magicstoreai_storefront_client.components["schemas"]["CartDiscountCode"][];
+        expiresAt: string | null;
+        giftOptions: _magicstoreai_storefront_client.components["schemas"]["CartGiftOption"][];
+        id: string;
+        lines: _magicstoreai_storefront_client.components["schemas"]["CartLine"][];
+        note: string | null;
+        points: _magicstoreai_storefront_client.components["schemas"]["CartPoints"] | null;
+        selectedGift: _magicstoreai_storefront_client.components["schemas"]["CartGiftOption"] | null;
+        status: "ACTIVE" | "COMPLETED" | "MERGED";
+        totalQuantity: number;
+        updatedAt: string | null;
+    } | null>;
+    updateLine: (lineId: string, quantity: number) => Promise<{
+        attributes: {
+            key: string;
+            value: string;
+        }[];
+        buyerIdentity: {
+            customerId: string;
+        } | null;
+        cost: {
+            discountTotal: _magicstoreai_storefront_client.components["schemas"]["Money"] | null;
+            pointsDiscount: _magicstoreai_storefront_client.components["schemas"]["Money"] | null;
+            subtotal: _magicstoreai_storefront_client.components["schemas"]["Money"] | null;
+            total: _magicstoreai_storefront_client.components["schemas"]["Money"] | null;
+            welcomeDiscount: _magicstoreai_storefront_client.components["schemas"]["Money"] | null;
+        };
+        createdAt: string | null;
+        discountCodes: _magicstoreai_storefront_client.components["schemas"]["CartDiscountCode"][];
+        expiresAt: string | null;
+        giftOptions: _magicstoreai_storefront_client.components["schemas"]["CartGiftOption"][];
+        id: string;
+        lines: _magicstoreai_storefront_client.components["schemas"]["CartLine"][];
+        note: string | null;
+        points: _magicstoreai_storefront_client.components["schemas"]["CartPoints"] | null;
+        selectedGift: _magicstoreai_storefront_client.components["schemas"]["CartGiftOption"] | null;
+        status: "ACTIVE" | "COMPLETED" | "MERGED";
+        totalQuantity: number;
+        updatedAt: string | null;
+    } | null>;
+    removeLine: (lineId: string) => Promise<{
+        attributes: {
+            key: string;
+            value: string;
+        }[];
+        buyerIdentity: {
+            customerId: string;
+        } | null;
+        cost: {
+            discountTotal: _magicstoreai_storefront_client.components["schemas"]["Money"] | null;
+            pointsDiscount: _magicstoreai_storefront_client.components["schemas"]["Money"] | null;
+            subtotal: _magicstoreai_storefront_client.components["schemas"]["Money"] | null;
+            total: _magicstoreai_storefront_client.components["schemas"]["Money"] | null;
+            welcomeDiscount: _magicstoreai_storefront_client.components["schemas"]["Money"] | null;
+        };
+        createdAt: string | null;
+        discountCodes: _magicstoreai_storefront_client.components["schemas"]["CartDiscountCode"][];
+        expiresAt: string | null;
+        giftOptions: _magicstoreai_storefront_client.components["schemas"]["CartGiftOption"][];
+        id: string;
+        lines: _magicstoreai_storefront_client.components["schemas"]["CartLine"][];
+        note: string | null;
+        points: _magicstoreai_storefront_client.components["schemas"]["CartPoints"] | null;
+        selectedGift: _magicstoreai_storefront_client.components["schemas"]["CartGiftOption"] | null;
+        status: "ACTIVE" | "COMPLETED" | "MERGED";
+        totalQuantity: number;
+        updatedAt: string | null;
+    } | null>;
+    setDiscountCodes: (codes: string[]) => Promise<{
+        attributes: {
+            key: string;
+            value: string;
+        }[];
+        buyerIdentity: {
+            customerId: string;
+        } | null;
+        cost: {
+            discountTotal: _magicstoreai_storefront_client.components["schemas"]["Money"] | null;
+            pointsDiscount: _magicstoreai_storefront_client.components["schemas"]["Money"] | null;
+            subtotal: _magicstoreai_storefront_client.components["schemas"]["Money"] | null;
+            total: _magicstoreai_storefront_client.components["schemas"]["Money"] | null;
+            welcomeDiscount: _magicstoreai_storefront_client.components["schemas"]["Money"] | null;
+        };
+        createdAt: string | null;
+        discountCodes: _magicstoreai_storefront_client.components["schemas"]["CartDiscountCode"][];
+        expiresAt: string | null;
+        giftOptions: _magicstoreai_storefront_client.components["schemas"]["CartGiftOption"][];
+        id: string;
+        lines: _magicstoreai_storefront_client.components["schemas"]["CartLine"][];
+        note: string | null;
+        points: _magicstoreai_storefront_client.components["schemas"]["CartPoints"] | null;
+        selectedGift: _magicstoreai_storefront_client.components["schemas"]["CartGiftOption"] | null;
+        status: "ACTIVE" | "COMPLETED" | "MERGED";
+        totalQuantity: number;
+        updatedAt: string | null;
+    } | null>;
+    setNote: (note: string | null) => Promise<{
+        attributes: {
+            key: string;
+            value: string;
+        }[];
+        buyerIdentity: {
+            customerId: string;
+        } | null;
+        cost: {
+            discountTotal: _magicstoreai_storefront_client.components["schemas"]["Money"] | null;
+            pointsDiscount: _magicstoreai_storefront_client.components["schemas"]["Money"] | null;
+            subtotal: _magicstoreai_storefront_client.components["schemas"]["Money"] | null;
+            total: _magicstoreai_storefront_client.components["schemas"]["Money"] | null;
+            welcomeDiscount: _magicstoreai_storefront_client.components["schemas"]["Money"] | null;
+        };
+        createdAt: string | null;
+        discountCodes: _magicstoreai_storefront_client.components["schemas"]["CartDiscountCode"][];
+        expiresAt: string | null;
+        giftOptions: _magicstoreai_storefront_client.components["schemas"]["CartGiftOption"][];
+        id: string;
+        lines: _magicstoreai_storefront_client.components["schemas"]["CartLine"][];
+        note: string | null;
+        points: _magicstoreai_storefront_client.components["schemas"]["CartPoints"] | null;
+        selectedGift: _magicstoreai_storefront_client.components["schemas"]["CartGiftOption"] | null;
+        status: "ACTIVE" | "COMPLETED" | "MERGED";
+        totalQuantity: number;
+        updatedAt: string | null;
+    } | null>;
+    setAttributes: (attributes: CartAttribute[]) => Promise<{
+        attributes: {
+            key: string;
+            value: string;
+        }[];
+        buyerIdentity: {
+            customerId: string;
+        } | null;
+        cost: {
+            discountTotal: _magicstoreai_storefront_client.components["schemas"]["Money"] | null;
+            pointsDiscount: _magicstoreai_storefront_client.components["schemas"]["Money"] | null;
+            subtotal: _magicstoreai_storefront_client.components["schemas"]["Money"] | null;
+            total: _magicstoreai_storefront_client.components["schemas"]["Money"] | null;
+            welcomeDiscount: _magicstoreai_storefront_client.components["schemas"]["Money"] | null;
+        };
+        createdAt: string | null;
+        discountCodes: _magicstoreai_storefront_client.components["schemas"]["CartDiscountCode"][];
+        expiresAt: string | null;
+        giftOptions: _magicstoreai_storefront_client.components["schemas"]["CartGiftOption"][];
+        id: string;
+        lines: _magicstoreai_storefront_client.components["schemas"]["CartLine"][];
+        note: string | null;
+        points: _magicstoreai_storefront_client.components["schemas"]["CartPoints"] | null;
+        selectedGift: _magicstoreai_storefront_client.components["schemas"]["CartGiftOption"] | null;
+        status: "ACTIVE" | "COMPLETED" | "MERGED";
+        totalQuantity: number;
+        updatedAt: string | null;
+    } | null>;
+    setGift: (promotionId: string | null) => Promise<{
+        attributes: {
+            key: string;
+            value: string;
+        }[];
+        buyerIdentity: {
+            customerId: string;
+        } | null;
+        cost: {
+            discountTotal: _magicstoreai_storefront_client.components["schemas"]["Money"] | null;
+            pointsDiscount: _magicstoreai_storefront_client.components["schemas"]["Money"] | null;
+            subtotal: _magicstoreai_storefront_client.components["schemas"]["Money"] | null;
+            total: _magicstoreai_storefront_client.components["schemas"]["Money"] | null;
+            welcomeDiscount: _magicstoreai_storefront_client.components["schemas"]["Money"] | null;
+        };
+        createdAt: string | null;
+        discountCodes: _magicstoreai_storefront_client.components["schemas"]["CartDiscountCode"][];
+        expiresAt: string | null;
+        giftOptions: _magicstoreai_storefront_client.components["schemas"]["CartGiftOption"][];
+        id: string;
+        lines: _magicstoreai_storefront_client.components["schemas"]["CartLine"][];
+        note: string | null;
+        points: _magicstoreai_storefront_client.components["schemas"]["CartPoints"] | null;
+        selectedGift: _magicstoreai_storefront_client.components["schemas"]["CartGiftOption"] | null;
+        status: "ACTIVE" | "COMPLETED" | "MERGED";
+        totalQuantity: number;
+        updatedAt: string | null;
+    } | null>;
+    setPoints: (points: number) => Promise<{
+        attributes: {
+            key: string;
+            value: string;
+        }[];
+        buyerIdentity: {
+            customerId: string;
+        } | null;
+        cost: {
+            discountTotal: _magicstoreai_storefront_client.components["schemas"]["Money"] | null;
+            pointsDiscount: _magicstoreai_storefront_client.components["schemas"]["Money"] | null;
+            subtotal: _magicstoreai_storefront_client.components["schemas"]["Money"] | null;
+            total: _magicstoreai_storefront_client.components["schemas"]["Money"] | null;
+            welcomeDiscount: _magicstoreai_storefront_client.components["schemas"]["Money"] | null;
+        };
+        createdAt: string | null;
+        discountCodes: _magicstoreai_storefront_client.components["schemas"]["CartDiscountCode"][];
+        expiresAt: string | null;
+        giftOptions: _magicstoreai_storefront_client.components["schemas"]["CartGiftOption"][];
+        id: string;
+        lines: _magicstoreai_storefront_client.components["schemas"]["CartLine"][];
+        note: string | null;
+        points: _magicstoreai_storefront_client.components["schemas"]["CartPoints"] | null;
+        selectedGift: _magicstoreai_storefront_client.components["schemas"]["CartGiftOption"] | null;
+        status: "ACTIVE" | "COMPLETED" | "MERGED";
+        totalQuantity: number;
+        updatedAt: string | null;
+    } | null>;
+    cart: Cart | null;
+    status: "idle" | "loading" | "updating";
+    error: _magicstoreai_storefront_client.MagicStoreError | null;
+};
+/**
+ * Saved products: a guest's in this browser, a customer's on the server (merged at sign-in).
+ *
+ * @wraps WishlistController
+ * @example
+ * const wishlist = useWishlist();
+ * <button aria-pressed={wishlist.has(product.id)} onClick={() => wishlist.toggle(product.id)}>♥</button>
+ */
+declare function useWishlist(): {
+    has: (productId: string) => boolean;
+    add: (productId: string) => Promise<void>;
+    remove: (productId: string) => Promise<void>;
+    toggle: (productId: string) => Promise<void>;
+    productIds: string[];
+    owner: "guest" | "customer";
+    status: "idle" | "loading";
+};
+/**
+ * Reports what the visitor looks at. Stable across renders.
+ *
+ * @wraps AnalyticsController
+ * @example
+ * const analytics = useAnalytics();
+ * useEffect(() => analytics.productView(product.id), [analytics, product.id]);
+ */
+declare function useAnalytics(): AnalyticsController;
+/**
+ * Options → variant. `selectedVariant` is null only while a choice is missing; `isAvailable` says
+ * whether a value leads to a variant for sale given the other choices.
+ *
+ * @example
+ * const { selectedOptions, selectedVariant, setOption, isAvailable } = useVariantSelection(product);
+ * <button disabled={!isAvailable('Size', 'M')} onClick={() => setOption('Size', 'M')}>M</button>
+ */
+declare function useVariantSelection(product: SelectableProduct, initialVariantId?: string | null): {
+    selectedOptions: SelectedOptions;
+    selectedVariant: {
+        availableForSale: boolean;
+        barcode: string | null;
+        compareAtPrice: _magicstoreai_storefront_client.components["schemas"]["Money"] | null;
+        gtin: string | null;
+        id: string;
+        image: _magicstoreai_storefront_client.components["schemas"]["Image"] | null;
+        mpn: string | null;
+        price: _magicstoreai_storefront_client.components["schemas"]["Money"] | null;
+        quantityAvailable: number | null;
+        requiresShipping: boolean;
+        selectedOptions: {
+            name: string;
+            value: string;
+        }[];
+        sku: string | null;
+        title: string;
+        weight: {
+            unit: string;
+            value: number;
+        } | null;
+    } | null;
+    setOption: (name: string, value: string) => void;
+    isAvailable: (name: string, value: string) => boolean;
+};
+
+type ProductContextValue = ReturnType<typeof useVariantSelection> & {
+    product: SelectableProduct;
+};
+/**
+ * Shares one product's variant selection with everything under it (options, price, add-to-cart).
+ *
+ * @example
+ * <ProductProvider product={product}>
+ *   <VariantPicker />
+ *   <AddToCart />
+ * </ProductProvider>
+ */
+declare function ProductProvider<P extends SelectableProduct>({ product, initialVariantId, children, }: {
+    product: P;
+    initialVariantId?: string | null;
+    children: ReactNode;
+}): react.JSX.Element;
+/**
+ * The product and variant selection of the nearest `<ProductProvider>`; throws outside one.
+ *
+ * @example
+ * const { product, selectedVariant } = useProduct();
+ * return <Money data={selectedVariant?.price ?? product.price} />;
+ */
+declare function useProduct(): ProductContextValue;
+
+export { AnalyticsController, type AnalyticsEvent, type AnalyticsEventType, type AnalyticsPayload, type Cart, type CartAttribute, CartController, type CartLine, type CartLineInput, type CartState, type Customer, type CustomerSession, CustomerSessionController, Image, type KeyValueStorage, type MagicStore, MagicStoreProvider, type MagicStoreProviderProps, Money, type MoneyFormat, Pagination, type PaginationState, type ProductOption, ProductProvider, type ProductVariant, type SelectableProduct, type SelectedOptions, type SessionState, type Shop, WISHLIST_LIMIT, WishlistController, type WishlistState, attributionFrom, browserStorage, currencySymbol, formatMoney, groupAmount, initialSelection, isOptionValueAvailable, memoryStorage, moneyAmount, optionsOf, paginationState, selectOption, useAnalytics, useCart, useCustomer, useMagicStore, useProduct, useShop, useStorefrontClient, useVariantSelection, useWishlist, variantFor, visitorSessionId };