@asteby/storefront 0.0.0-stage → 0.2.0

package/dist/index.d.cts

@@ -0,0 +1,261 @@
+import { V as ProductSort, a1 as Shop, T as ProductConnection, Q as Product, q as Connection, p as Collection, a5 as StockLevel, i as CartLineInput, C as Cart, k as CartLineUpdateInput, d as CartBuyerInput, a as AddressInput, w as DeliveryOptions, L as PaymentMethods, D as DeliveryInput, m as CheckoutInput, o as CheckoutResult, s as CustomerIdentifier, u as CustomerSessionInput, t as CustomerSession, r as Customer, O as Order, Y as ReturnRequestInput, X as ReturnRequest, y as InvoiceRequest, z as InvoiceResult, A as Address, a8 as Theme, P as Page, M as Menu, b as Article, a7 as StorefrontErrorCode, E as Money } from './types-CTXB8Dnl.cjs';
+export { c as CartBuyer, e as CartCost, f as CartDelivery, g as CartDiscountCode, h as CartLine, j as CartLineMerchandise, l as CheckoutInfo, n as CheckoutPayment, v as DeliveryMethod, F as Facet, x as FacetValue, I as Image, B as MenuItem, G as MoneyRange, H as OrderLine, J as PageInfo, K as PaymentMethod, N as PickupOption, R as ProductAttributeValue, S as ProductCategory, U as ProductOption, W as ProductVariant, Z as SEO, _ as Section, $ as SelectedOption, a0 as ShippingRate, a2 as ShopBranch, a3 as ShopContact, a4 as ShopPolicies, a6 as StorefrontErrorBody, a9 as UnavailableRateProvider } from './types-CTXB8Dnl.cjs';
+
+type QueryValue = string | number | boolean | null | undefined;
+type QueryParams = Record<string, QueryValue | QueryValue[]>;
+type PaginationParams = {
+    /** Page size (1–100; articles accept at most 50). */
+    first?: number;
+    /** Cursor from `page_info.end_cursor`. */
+    after?: string | null;
+};
+type ProductListParams = PaginationParams & {
+    /** Free-text search. */
+    q?: string;
+    /** Collection handle. */
+    collection?: string;
+    sort?: ProductSort;
+    /** Only products available for sale. */
+    available?: boolean;
+    price_min?: number | string;
+    price_max?: number | string;
+    /**
+     * Attribute filters, serialized as repeated `filter.<key>=<value>` params.
+     * Values of one key are OR-ed; different keys are AND-ed.
+     * e.g. `{ vendor: ['A', 'B'], rim: 16 }`.
+     */
+    filters?: Record<string, QueryValue | QueryValue[]>;
+    /** Restrict to these handles (max 100). Serialized comma-separated. */
+    handles?: string[];
+};
+type CollectionListParams = PaginationParams;
+type ArticleListParams = Omit<PaginationParams, 'first'> & {
+    /** Page size (1–50). The API answers 400 `validation` above 50. */
+    first?: number;
+    tag?: string;
+    q?: string;
+};
+/** Appends params to a URLSearchParams, repeating keys for arrays and skipping nullish values. */
+declare function appendParams(search: URLSearchParams, params: QueryParams | undefined): URLSearchParams;
+/** Serializes product list params per the contract (`filter.<attr>` repeated, `handles` comma-separated). */
+declare function productListQuery(params?: ProductListParams): URLSearchParams;
+/** Reads `filter.<key>` params back into a filters record (useful in route loaders). */
+declare function parseProductFilters(search: URLSearchParams): Record<string, string[]>;
+
+type FetchLike = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+/** Context passed to `onRequest` / `onResponse` hooks. */
+type StorefrontRequestContext = {
+    method: string;
+    /** Absolute URL, including the query string. */
+    url: string;
+    /** Route path relative to `baseUrl`, e.g. `/storefront/products/abc`. */
+    path: string;
+    /** Final `RequestInit` (headers already merged). Hooks may mutate it. */
+    init: RequestInit & {
+        headers: Headers;
+    };
+    /** Per-call options as given by the caller. */
+    options: RequestOptions;
+};
+type StorefrontResponseContext = StorefrontRequestContext & {
+    response: Response;
+    /** Milliseconds spent waiting for the response. */
+    durationMs: number;
+};
+type StorefrontClientOptions = {
+    /** Base URL of the gateway, e.g. `https://ops.example.com/api/gw`. Routes are appended as `/storefront/...`. */
+    baseUrl: string;
+    /** `pk_...` (browser) or `sk_...` (server only). Sent as `Authorization: Bearer <token>`. */
+    token: string;
+    /** Buyer session (`X-Customer-Token`) for `/storefront/customer/*` routes. */
+    customerToken?: string | null;
+    /** Custom fetch (defaults to `globalThis.fetch`). */
+    fetch?: FetchLike;
+    /** Sent as `Accept-Language`. */
+    locale?: string;
+    /** Extra headers on every request. */
+    headers?: Record<string, string>;
+    /** Abort requests that take longer than this (default: no timeout). */
+    timeoutMs?: number;
+    /**
+     * Runs before every request. Return a `Response` to short-circuit the
+     * network (e.g. an SSR cache hit); return nothing to continue.
+     */
+    onRequest?: (ctx: StorefrontRequestContext) => void | Response | Promise<void | Response>;
+    /** Runs after every response (including short-circuited ones), before parsing. */
+    onResponse?: (ctx: StorefrontResponseContext) => void | Promise<void>;
+};
+/** Per-call options. Unknown keys (e.g. Next.js `next`) are forwarded to `fetch` as-is. */
+type RequestOptions = {
+    cache?: RequestCache;
+    signal?: AbortSignal;
+    /** Framework fetch extensions, forwarded verbatim (e.g. `{ revalidate: 60, tags: ['products'] }`). */
+    next?: Record<string, unknown>;
+    headers?: Record<string, string>;
+    /** Overrides the client-level timeout for this call. */
+    timeoutMs?: number;
+    /** Overrides the client-level customer token for this call. */
+    customerToken?: string | null;
+    [key: string]: unknown;
+};
+type WriteOptions = RequestOptions & {
+    /** `Idempotency-Key` header. Auto-generated for checkout when omitted. */
+    idempotencyKey?: string;
+};
+type PreviewOptions = RequestOptions & {
+    /** Signed preview token: returns the draft (`private, no-store`). */
+    preview?: string;
+};
+type HttpMethod = 'GET' | 'POST' | 'PATCH' | 'PUT' | 'DELETE';
+type RequestSpec = {
+    method: HttpMethod;
+    path: string;
+    query?: URLSearchParams | QueryParams;
+    body?: unknown;
+    options?: WriteOptions;
+    /** Resolve `null` instead of throwing on 404. */
+    nullOn404?: boolean;
+};
+/** Generates an idempotency key (crypto.randomUUID when available). */
+declare function generateIdempotencyKey(): string;
+declare function createStorefrontClient(config: StorefrontClientOptions): {
+    /** Resolved configuration (read-only). */
+    config: Readonly<StorefrontClientOptions>;
+    /** Low-level escape hatch: any route under `baseUrl`. */
+    request: {
+        <T>(spec: RequestSpec & {
+            nullOn404: true;
+        }): Promise<T | null>;
+        <T>(spec: RequestSpec): Promise<T>;
+    };
+    /** Returns a new client that sends the given buyer session token. */
+    withCustomerToken(customerToken: string | null): /*elided*/ any;
+    shop: {
+        get: (options?: RequestOptions) => Promise<Shop>;
+    };
+    products: {
+        list: (params?: ProductListParams, options?: RequestOptions) => Promise<ProductConnection>;
+        /** `null` when the product does not exist or is unpublished. */
+        get: (handle: string, options?: RequestOptions) => Promise<Product | null>;
+        recommendations: (handle: string, options?: RequestOptions) => Promise<{
+            nodes: Product[];
+        }>;
+    };
+    collections: {
+        list: (params?: CollectionListParams, options?: RequestOptions) => Promise<Connection<Collection>>;
+        /** `null` when the collection does not exist. */
+        get: (handle: string, options?: RequestOptions) => Promise<Collection | null>;
+    };
+    stock: {
+        /** Stock for up to 250 SKUs. */
+        get: (skus: string[], options?: RequestOptions) => Promise<{
+            nodes: StockLevel[];
+        }>;
+    };
+    carts: {
+        create: (input?: {
+            lines?: CartLineInput[];
+        }, options?: WriteOptions) => Promise<Cart>;
+        /** `null` when the cart does not exist (e.g. expired cookie). */
+        get: (id: string, options?: RequestOptions) => Promise<Cart | null>;
+        addLines: (id: string, lines: CartLineInput[], options?: WriteOptions) => Promise<Cart>;
+        /** Quantity `0` removes the line. */
+        updateLines: (id: string, lines: CartLineUpdateInput[], options?: WriteOptions) => Promise<Cart>;
+        removeLines: (id: string, lineIds: string[], options?: WriteOptions) => Promise<Cart>;
+        setDiscountCodes: (id: string, codes: string[], options?: WriteOptions) => Promise<Cart>;
+        setBuyer: (id: string, buyer: CartBuyerInput, options?: WriteOptions) => Promise<Cart>;
+        setShippingAddress: (id: string, address: AddressInput, options?: WriteOptions) => Promise<Cart>;
+        deliveryOptions: (id: string, options?: RequestOptions) => Promise<DeliveryOptions>;
+        /** Payment providers active for the cart's market; send the chosen `key` as `payment_method`. */
+        paymentMethods: (id: string, options?: RequestOptions) => Promise<PaymentMethods>;
+        setDelivery: (id: string, delivery: DeliveryInput, options?: WriteOptions) => Promise<Cart>;
+        /** Reserves stock and creates the order. Sends `Idempotency-Key` (auto-generated if omitted). */
+        checkout: (id: string, input: CheckoutInput, options?: WriteOptions) => Promise<CheckoutResult>;
+    };
+    customer: {
+        /** Sends a one-time code by email or SMS/WhatsApp. */
+        requestOtp: (identifier: CustomerIdentifier, options?: WriteOptions) => Promise<void>;
+        /** Exchanges the code for a buyer session (`token` goes in `customerToken`). */
+        createSession: (input: CustomerSessionInput, options?: WriteOptions) => Promise<CustomerSession>;
+        get: (options?: RequestOptions) => Promise<Customer>;
+        orders: (params?: PaginationParams, options?: RequestOptions) => Promise<Connection<Order>>;
+        /** `null` when the order does not exist or belongs to someone else. */
+        order: (id: string, options?: RequestOptions) => Promise<Order | null>;
+        requestReturn: (orderId: string, input: ReturnRequestInput, options?: WriteOptions) => Promise<ReturnRequest>;
+        requestInvoice: (orderId: string, input: InvoiceRequest, options?: WriteOptions) => Promise<InvoiceResult>;
+        addresses: {
+            list: (options?: RequestOptions) => Promise<{
+                nodes: Address[];
+            }>;
+            create: (address: AddressInput, options?: WriteOptions) => Promise<Address>;
+            update: (id: string, address: Partial<AddressInput>, options?: WriteOptions) => Promise<Address>;
+            delete: (id: string, options?: WriteOptions) => Promise<void>;
+        };
+    };
+    content: {
+        theme: (options?: RequestOptions) => Promise<Theme>;
+        /** `null` when the page does not exist. */
+        page: (handle: string, options?: PreviewOptions) => Promise<Page | null>;
+        /** `null` when the menu does not exist. */
+        menu: (handle: string, options?: RequestOptions) => Promise<Menu | null>;
+        articles: (params?: ArticleListParams, options?: RequestOptions) => Promise<Connection<Article>>;
+        /** `null` when the article does not exist. */
+        article: (handle: string, options?: PreviewOptions) => Promise<Article | null>;
+    };
+};
+type StorefrontClient = ReturnType<typeof createStorefrontClient>;
+
+type StorefrontErrorInit = {
+    status: number;
+    code: StorefrontErrorCode;
+    message: string;
+    field?: string;
+    /** Request URL that failed (without credentials). */
+    url?: string;
+    cause?: unknown;
+};
+/**
+ * Error thrown by the client for any non-2xx response, network failure,
+ * timeout or abort. `status` is `0` when no HTTP response was received.
+ */
+declare class StorefrontError extends Error {
+    readonly name = "StorefrontError";
+    readonly status: number;
+    readonly code: StorefrontErrorCode;
+    readonly field: string | undefined;
+    readonly url: string | undefined;
+    constructor(init: StorefrontErrorInit);
+    toJSON(): {
+        name: string;
+        status: number;
+        code: StorefrontErrorCode;
+        message: string;
+        field: string | undefined;
+    };
+}
+declare function isStorefrontError(err: unknown): err is StorefrontError;
+
+type FormatMoneyOptions = {
+    /** Drop `.00` when the amount is a whole number. */
+    withoutTrailingZeros?: boolean;
+    /** Format as a plain number, without the currency symbol. */
+    withoutCurrency?: boolean;
+    /** `symbol` (default), `narrowSymbol`, `code` or `name`. */
+    currencyDisplay?: 'symbol' | 'narrowSymbol' | 'code' | 'name';
+};
+/** Parses a contract `Money` amount into a JS number (`"1899.00"` → `1899`). */
+declare function parseMoney(money: Money | string | null | undefined): number;
+/**
+ * Formats `Money` with `Intl.NumberFormat`. Works in every runtime (no DOM).
+ * Falls back to `"<amount> <code>"` when the runtime lacks the currency.
+ */
+declare function formatMoney(money: Money, locale?: string, options?: FormatMoneyOptions): string;
+/** Builds a `Money` from a number, rounding to cents. */
+declare function toMoney(value: number, currencyCode: string): Money;
+/**
+ * True for public (`pk_`) tokens, the only ones that may reach a browser.
+ * Private (`sk_`) tokens must stay on the server.
+ */
+declare function isTokenPublishable(token: string | null | undefined): boolean;
+
+export { Address, AddressInput, Article, type ArticleListParams, Cart, CartBuyerInput, CartLineInput, CartLineUpdateInput, CheckoutInput, CheckoutResult, Collection, type CollectionListParams, Connection, Customer, CustomerIdentifier, CustomerSession, CustomerSessionInput, DeliveryInput, DeliveryOptions, type FetchLike, type FormatMoneyOptions, InvoiceRequest, InvoiceResult, Menu, Money, Order, Page, type PaginationParams, PaymentMethods, type PreviewOptions, Product, ProductConnection, type ProductListParams, ProductSort, type QueryParams, type QueryValue, type RequestOptions, ReturnRequest, ReturnRequestInput, Shop, StockLevel, type StorefrontClient, type StorefrontClientOptions, StorefrontError, StorefrontErrorCode, type StorefrontErrorInit, type StorefrontRequestContext, type StorefrontResponseContext, Theme, type WriteOptions, appendParams, createStorefrontClient, formatMoney, generateIdempotencyKey, isStorefrontError, isTokenPublishable, parseMoney, parseProductFilters, productListQuery, toMoney };

package/dist/index.d.ts

@@ -0,0 +1,261 @@
+import { V as ProductSort, a1 as Shop, T as ProductConnection, Q as Product, q as Connection, p as Collection, a5 as StockLevel, i as CartLineInput, C as Cart, k as CartLineUpdateInput, d as CartBuyerInput, a as AddressInput, w as DeliveryOptions, L as PaymentMethods, D as DeliveryInput, m as CheckoutInput, o as CheckoutResult, s as CustomerIdentifier, u as CustomerSessionInput, t as CustomerSession, r as Customer, O as Order, Y as ReturnRequestInput, X as ReturnRequest, y as InvoiceRequest, z as InvoiceResult, A as Address, a8 as Theme, P as Page, M as Menu, b as Article, a7 as StorefrontErrorCode, E as Money } from './types-CTXB8Dnl.js';
+export { c as CartBuyer, e as CartCost, f as CartDelivery, g as CartDiscountCode, h as CartLine, j as CartLineMerchandise, l as CheckoutInfo, n as CheckoutPayment, v as DeliveryMethod, F as Facet, x as FacetValue, I as Image, B as MenuItem, G as MoneyRange, H as OrderLine, J as PageInfo, K as PaymentMethod, N as PickupOption, R as ProductAttributeValue, S as ProductCategory, U as ProductOption, W as ProductVariant, Z as SEO, _ as Section, $ as SelectedOption, a0 as ShippingRate, a2 as ShopBranch, a3 as ShopContact, a4 as ShopPolicies, a6 as StorefrontErrorBody, a9 as UnavailableRateProvider } from './types-CTXB8Dnl.js';
+
+type QueryValue = string | number | boolean | null | undefined;
+type QueryParams = Record<string, QueryValue | QueryValue[]>;
+type PaginationParams = {
+    /** Page size (1–100; articles accept at most 50). */
+    first?: number;
+    /** Cursor from `page_info.end_cursor`. */
+    after?: string | null;
+};
+type ProductListParams = PaginationParams & {
+    /** Free-text search. */
+    q?: string;
+    /** Collection handle. */
+    collection?: string;
+    sort?: ProductSort;
+    /** Only products available for sale. */
+    available?: boolean;
+    price_min?: number | string;
+    price_max?: number | string;
+    /**
+     * Attribute filters, serialized as repeated `filter.<key>=<value>` params.
+     * Values of one key are OR-ed; different keys are AND-ed.
+     * e.g. `{ vendor: ['A', 'B'], rim: 16 }`.
+     */
+    filters?: Record<string, QueryValue | QueryValue[]>;
+    /** Restrict to these handles (max 100). Serialized comma-separated. */
+    handles?: string[];
+};
+type CollectionListParams = PaginationParams;
+type ArticleListParams = Omit<PaginationParams, 'first'> & {
+    /** Page size (1–50). The API answers 400 `validation` above 50. */
+    first?: number;
+    tag?: string;
+    q?: string;
+};
+/** Appends params to a URLSearchParams, repeating keys for arrays and skipping nullish values. */
+declare function appendParams(search: URLSearchParams, params: QueryParams | undefined): URLSearchParams;
+/** Serializes product list params per the contract (`filter.<attr>` repeated, `handles` comma-separated). */
+declare function productListQuery(params?: ProductListParams): URLSearchParams;
+/** Reads `filter.<key>` params back into a filters record (useful in route loaders). */
+declare function parseProductFilters(search: URLSearchParams): Record<string, string[]>;
+
+type FetchLike = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+/** Context passed to `onRequest` / `onResponse` hooks. */
+type StorefrontRequestContext = {
+    method: string;
+    /** Absolute URL, including the query string. */
+    url: string;
+    /** Route path relative to `baseUrl`, e.g. `/storefront/products/abc`. */
+    path: string;
+    /** Final `RequestInit` (headers already merged). Hooks may mutate it. */
+    init: RequestInit & {
+        headers: Headers;
+    };
+    /** Per-call options as given by the caller. */
+    options: RequestOptions;
+};
+type StorefrontResponseContext = StorefrontRequestContext & {
+    response: Response;
+    /** Milliseconds spent waiting for the response. */
+    durationMs: number;
+};
+type StorefrontClientOptions = {
+    /** Base URL of the gateway, e.g. `https://ops.example.com/api/gw`. Routes are appended as `/storefront/...`. */
+    baseUrl: string;
+    /** `pk_...` (browser) or `sk_...` (server only). Sent as `Authorization: Bearer <token>`. */
+    token: string;
+    /** Buyer session (`X-Customer-Token`) for `/storefront/customer/*` routes. */
+    customerToken?: string | null;
+    /** Custom fetch (defaults to `globalThis.fetch`). */
+    fetch?: FetchLike;
+    /** Sent as `Accept-Language`. */
+    locale?: string;
+    /** Extra headers on every request. */
+    headers?: Record<string, string>;
+    /** Abort requests that take longer than this (default: no timeout). */
+    timeoutMs?: number;
+    /**
+     * Runs before every request. Return a `Response` to short-circuit the
+     * network (e.g. an SSR cache hit); return nothing to continue.
+     */
+    onRequest?: (ctx: StorefrontRequestContext) => void | Response | Promise<void | Response>;
+    /** Runs after every response (including short-circuited ones), before parsing. */
+    onResponse?: (ctx: StorefrontResponseContext) => void | Promise<void>;
+};
+/** Per-call options. Unknown keys (e.g. Next.js `next`) are forwarded to `fetch` as-is. */
+type RequestOptions = {
+    cache?: RequestCache;
+    signal?: AbortSignal;
+    /** Framework fetch extensions, forwarded verbatim (e.g. `{ revalidate: 60, tags: ['products'] }`). */
+    next?: Record<string, unknown>;
+    headers?: Record<string, string>;
+    /** Overrides the client-level timeout for this call. */
+    timeoutMs?: number;
+    /** Overrides the client-level customer token for this call. */
+    customerToken?: string | null;
+    [key: string]: unknown;
+};
+type WriteOptions = RequestOptions & {
+    /** `Idempotency-Key` header. Auto-generated for checkout when omitted. */
+    idempotencyKey?: string;
+};
+type PreviewOptions = RequestOptions & {
+    /** Signed preview token: returns the draft (`private, no-store`). */
+    preview?: string;
+};
+type HttpMethod = 'GET' | 'POST' | 'PATCH' | 'PUT' | 'DELETE';
+type RequestSpec = {
+    method: HttpMethod;
+    path: string;
+    query?: URLSearchParams | QueryParams;
+    body?: unknown;
+    options?: WriteOptions;
+    /** Resolve `null` instead of throwing on 404. */
+    nullOn404?: boolean;
+};
+/** Generates an idempotency key (crypto.randomUUID when available). */
+declare function generateIdempotencyKey(): string;
+declare function createStorefrontClient(config: StorefrontClientOptions): {
+    /** Resolved configuration (read-only). */
+    config: Readonly<StorefrontClientOptions>;
+    /** Low-level escape hatch: any route under `baseUrl`. */
+    request: {
+        <T>(spec: RequestSpec & {
+            nullOn404: true;
+        }): Promise<T | null>;
+        <T>(spec: RequestSpec): Promise<T>;
+    };
+    /** Returns a new client that sends the given buyer session token. */
+    withCustomerToken(customerToken: string | null): /*elided*/ any;
+    shop: {
+        get: (options?: RequestOptions) => Promise<Shop>;
+    };
+    products: {
+        list: (params?: ProductListParams, options?: RequestOptions) => Promise<ProductConnection>;
+        /** `null` when the product does not exist or is unpublished. */
+        get: (handle: string, options?: RequestOptions) => Promise<Product | null>;
+        recommendations: (handle: string, options?: RequestOptions) => Promise<{
+            nodes: Product[];
+        }>;
+    };
+    collections: {
+        list: (params?: CollectionListParams, options?: RequestOptions) => Promise<Connection<Collection>>;
+        /** `null` when the collection does not exist. */
+        get: (handle: string, options?: RequestOptions) => Promise<Collection | null>;
+    };
+    stock: {
+        /** Stock for up to 250 SKUs. */
+        get: (skus: string[], options?: RequestOptions) => Promise<{
+            nodes: StockLevel[];
+        }>;
+    };
+    carts: {
+        create: (input?: {
+            lines?: CartLineInput[];
+        }, options?: WriteOptions) => Promise<Cart>;
+        /** `null` when the cart does not exist (e.g. expired cookie). */
+        get: (id: string, options?: RequestOptions) => Promise<Cart | null>;
+        addLines: (id: string, lines: CartLineInput[], options?: WriteOptions) => Promise<Cart>;
+        /** Quantity `0` removes the line. */
+        updateLines: (id: string, lines: CartLineUpdateInput[], options?: WriteOptions) => Promise<Cart>;
+        removeLines: (id: string, lineIds: string[], options?: WriteOptions) => Promise<Cart>;
+        setDiscountCodes: (id: string, codes: string[], options?: WriteOptions) => Promise<Cart>;
+        setBuyer: (id: string, buyer: CartBuyerInput, options?: WriteOptions) => Promise<Cart>;
+        setShippingAddress: (id: string, address: AddressInput, options?: WriteOptions) => Promise<Cart>;
+        deliveryOptions: (id: string, options?: RequestOptions) => Promise<DeliveryOptions>;
+        /** Payment providers active for the cart's market; send the chosen `key` as `payment_method`. */
+        paymentMethods: (id: string, options?: RequestOptions) => Promise<PaymentMethods>;
+        setDelivery: (id: string, delivery: DeliveryInput, options?: WriteOptions) => Promise<Cart>;
+        /** Reserves stock and creates the order. Sends `Idempotency-Key` (auto-generated if omitted). */
+        checkout: (id: string, input: CheckoutInput, options?: WriteOptions) => Promise<CheckoutResult>;
+    };
+    customer: {
+        /** Sends a one-time code by email or SMS/WhatsApp. */
+        requestOtp: (identifier: CustomerIdentifier, options?: WriteOptions) => Promise<void>;
+        /** Exchanges the code for a buyer session (`token` goes in `customerToken`). */
+        createSession: (input: CustomerSessionInput, options?: WriteOptions) => Promise<CustomerSession>;
+        get: (options?: RequestOptions) => Promise<Customer>;
+        orders: (params?: PaginationParams, options?: RequestOptions) => Promise<Connection<Order>>;
+        /** `null` when the order does not exist or belongs to someone else. */
+        order: (id: string, options?: RequestOptions) => Promise<Order | null>;
+        requestReturn: (orderId: string, input: ReturnRequestInput, options?: WriteOptions) => Promise<ReturnRequest>;
+        requestInvoice: (orderId: string, input: InvoiceRequest, options?: WriteOptions) => Promise<InvoiceResult>;
+        addresses: {
+            list: (options?: RequestOptions) => Promise<{
+                nodes: Address[];
+            }>;
+            create: (address: AddressInput, options?: WriteOptions) => Promise<Address>;
+            update: (id: string, address: Partial<AddressInput>, options?: WriteOptions) => Promise<Address>;
+            delete: (id: string, options?: WriteOptions) => Promise<void>;
+        };
+    };
+    content: {
+        theme: (options?: RequestOptions) => Promise<Theme>;
+        /** `null` when the page does not exist. */
+        page: (handle: string, options?: PreviewOptions) => Promise<Page | null>;
+        /** `null` when the menu does not exist. */
+        menu: (handle: string, options?: RequestOptions) => Promise<Menu | null>;
+        articles: (params?: ArticleListParams, options?: RequestOptions) => Promise<Connection<Article>>;
+        /** `null` when the article does not exist. */
+        article: (handle: string, options?: PreviewOptions) => Promise<Article | null>;
+    };
+};
+type StorefrontClient = ReturnType<typeof createStorefrontClient>;
+
+type StorefrontErrorInit = {
+    status: number;
+    code: StorefrontErrorCode;
+    message: string;
+    field?: string;
+    /** Request URL that failed (without credentials). */
+    url?: string;
+    cause?: unknown;
+};
+/**
+ * Error thrown by the client for any non-2xx response, network failure,
+ * timeout or abort. `status` is `0` when no HTTP response was received.
+ */
+declare class StorefrontError extends Error {
+    readonly name = "StorefrontError";
+    readonly status: number;
+    readonly code: StorefrontErrorCode;
+    readonly field: string | undefined;
+    readonly url: string | undefined;
+    constructor(init: StorefrontErrorInit);
+    toJSON(): {
+        name: string;
+        status: number;
+        code: StorefrontErrorCode;
+        message: string;
+        field: string | undefined;
+    };
+}
+declare function isStorefrontError(err: unknown): err is StorefrontError;
+
+type FormatMoneyOptions = {
+    /** Drop `.00` when the amount is a whole number. */
+    withoutTrailingZeros?: boolean;
+    /** Format as a plain number, without the currency symbol. */
+    withoutCurrency?: boolean;
+    /** `symbol` (default), `narrowSymbol`, `code` or `name`. */
+    currencyDisplay?: 'symbol' | 'narrowSymbol' | 'code' | 'name';
+};
+/** Parses a contract `Money` amount into a JS number (`"1899.00"` → `1899`). */
+declare function parseMoney(money: Money | string | null | undefined): number;
+/**
+ * Formats `Money` with `Intl.NumberFormat`. Works in every runtime (no DOM).
+ * Falls back to `"<amount> <code>"` when the runtime lacks the currency.
+ */
+declare function formatMoney(money: Money, locale?: string, options?: FormatMoneyOptions): string;
+/** Builds a `Money` from a number, rounding to cents. */
+declare function toMoney(value: number, currencyCode: string): Money;
+/**
+ * True for public (`pk_`) tokens, the only ones that may reach a browser.
+ * Private (`sk_`) tokens must stay on the server.
+ */
+declare function isTokenPublishable(token: string | null | undefined): boolean;
+
+export { Address, AddressInput, Article, type ArticleListParams, Cart, CartBuyerInput, CartLineInput, CartLineUpdateInput, CheckoutInput, CheckoutResult, Collection, type CollectionListParams, Connection, Customer, CustomerIdentifier, CustomerSession, CustomerSessionInput, DeliveryInput, DeliveryOptions, type FetchLike, type FormatMoneyOptions, InvoiceRequest, InvoiceResult, Menu, Money, Order, Page, type PaginationParams, PaymentMethods, type PreviewOptions, Product, ProductConnection, type ProductListParams, ProductSort, type QueryParams, type QueryValue, type RequestOptions, ReturnRequest, ReturnRequestInput, Shop, StockLevel, type StorefrontClient, type StorefrontClientOptions, StorefrontError, StorefrontErrorCode, type StorefrontErrorInit, type StorefrontRequestContext, type StorefrontResponseContext, Theme, type WriteOptions, appendParams, createStorefrontClient, formatMoney, generateIdempotencyKey, isStorefrontError, isTokenPublishable, parseMoney, parseProductFilters, productListQuery, toMoney };