@spindlecommerce/storefront-client 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The SpindleCommerce authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,28 @@
-# Temporary Holding Version
+# @spindlecommerce/storefront-client
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A typed client for the [SpindleCommerce](https://spindlecommerce.com) Storefront API. It runs wherever `fetch` does: Node, edge runtimes and browsers.
+
+```ts
+import { createCartSession, createStorefrontClient } from "@spindlecommerce/storefront-client";
+
+const client = createStorefrontClient({ url: "https://api.example.com", channel: "eu", locale: "de-DE", currency: "EUR" });
+
+const route = await client.route("/products/oxford-shirt");
+const { products, endCursor } = await client.categoryProducts(categoryId, { first: 24 });
+
+// The cart's id lives where you keep it: here, browser storage.
+const cart = createCartSession(client, {
+  get: () => localStorage.getItem("cart"),
+  set: (c) => localStorage.setItem("cart", c.id),
+  clear: () => localStorage.removeItem("cart"),
+});
+await cart.add([{ variantId, quantity: 1 }]);
+const result = await cart.checkout.placeOrder({ idempotencyKey, payment: { token } });
+```
+
+- **Reads**: `route`, `routeTemplate`, `routeSections`, `site`, `newestProducts`, `categoryProducts`, `pages`, `productSlugs`, `categoryTree`, `localizedPath`, `previewSession`, `countries` and `guestOrder`. `query(document, variables)` runs your own, and `fragments` holds the client's to spread in them.
+- **Errors**: `StorefrontApiError` (`status` 0 when the API can't be reached), and `PreviewExpiredError` for a preview token the API no longer accepts. Cart and checkout problems come back as values, such as `{ ok: false, reason: "invalid", fieldErrors }`.
+- **Helpers**: `chooseValue` and `inStock` for variant pickers, `verifyWebhookSignature` and `changesFor` for platform webhooks, `editable` for visual editing markup.
+- **Schema**: `@spindlecommerce/storefront-client/schema.graphql` is the Storefront API's schema, for generating types for your own queries.
+
+React: [`@spindlecommerce/storefront-react`](https://www.npmjs.com/package/@spindlecommerce/storefront-react). Next.js: [`@spindlecommerce/storefront-next`](https://www.npmjs.com/package/@spindlecommerce/storefront-next).

package/dist/builder.d.ts

@@ -0,0 +1,6 @@
+import type { ContentNode } from "./types.ts";
+export declare const isContentNode: (value: unknown) => value is ContentNode;
+/** The nodes in a node's blocks fields, in field order. */
+export declare const blockNodes: (node: ContentNode) => ContentNode[];
+/** Whether a component appears among these nodes, nested ones included. */
+export declare const containsComponent: (nodes: readonly ContentNode[], code: string) => boolean;

package/dist/builder.js

@@ -0,0 +1,5 @@
+export const isContentNode = (value) => typeof value === "object" && value !== null && typeof value.id === "string" && typeof value.component === "string" && typeof value.fields === "object";
+/** The nodes in a node's blocks fields, in field order. */
+export const blockNodes = (node) => Object.values(node.fields).flatMap((value) => (Array.isArray(value) ? value.filter(isContentNode) : []));
+/** Whether a component appears among these nodes, nested ones included. */
+export const containsComponent = (nodes, code) => nodes.some((node) => node.component === code || containsComponent(blockNodes(node), code));

package/dist/cart.d.ts

@@ -0,0 +1,105 @@
+import type { StorefrontClient } from "./client.ts";
+import type { Cart, CartRequirement, CartUpdateInput, CheckoutCart, FieldError, Money, PlacedOrderRef } from "./types.ts";
+/** Where the cart's id is kept between requests, such as a cookie or browser storage. */
+export type CartStore = {
+    get: () => string | null | Promise<string | null>;
+    /** After every change, with the cart as it now is. */
+    set: (cart: Cart) => void | Promise<void>;
+    clear: () => void | Promise<void>;
+};
+/** A failed cart change. `available` is set when there is not enough stock. */
+export declare class CartError extends Error {
+    readonly code: string;
+    readonly available: number | null;
+    constructor(message: string, code: string, available?: number | null);
+}
+/** "invalid": fix the input. "expired": the cart is gone. "closed": it became an order. */
+export type CartChange = {
+    ok: true;
+} | {
+    ok: false;
+    reason: "invalid" | "expired" | "closed" | "error";
+    /** The API's result type, such as ValidationError or CouponNotApplicableError. */
+    type: string | null;
+    /** The API's message, in English. */
+    message: string | null;
+    fieldErrors: FieldError[];
+    /** Why a coupon does not apply, in the API's English. */
+    couponReason: string | null;
+};
+export type PaymentSession = {
+    provider: string;
+    methodCode: string;
+    amount: Money | null;
+    clientData: Record<string, unknown>;
+};
+/** "not_ready": the cart still lacks details. "refused": it became an order, or the provider said no. */
+export type PaymentSessionResult = {
+    ok: true;
+    session: PaymentSession;
+} | {
+    ok: false;
+    reason: "expired" | "not_ready" | "refused";
+    message: string | null;
+};
+/**
+ * After "error" the outcome is unknown, so a retry reuses the idempotency key. After the others, it
+ * is a new attempt.
+ */
+export type PlaceOrderFailure = "declined" | "not_ready" | "stock" | "closed" | "expired" | "invalid" | "error";
+export type PlaceOrderResult = {
+    ok: true;
+    order: PlacedOrderRef;
+    cartId: string;
+} | {
+    ok: false;
+    reason: PlaceOrderFailure;
+    type: string | null;
+    message: string | null;
+    missing: CartRequirement[];
+    fieldErrors: FieldError[];
+};
+export type CartSessionOptions = {
+    /** Whether a stored cart can still be used, e.g. not one in another channel's currency. By default, while it is open. */
+    isUsable?: (cart: {
+        isOpen: boolean;
+        currencyCode: string | null;
+    }) => boolean;
+};
+/** The shopper's cart and checkout, with the cart's id kept in `store`. Nothing is read from a cache. */
+export declare const createCartSession: (client: StorefrontClient, store: CartStore, options?: CartSessionOptions) => {
+    id: () => string | Promise<string | null> | null;
+    get: () => Promise<Cart | null>;
+    add: (lines: {
+        variantId: string;
+        quantity: number;
+    }[]) => Promise<Cart>;
+    update: (lineId: string, quantity: number) => Promise<Cart>;
+    move: (to: {
+        locale: string;
+        currency: string;
+    }) => Promise<void>;
+    forget: () => void | Promise<void>;
+    checkout: {
+        /** The cart with everything checkout shows; null when there is none to check out. */
+        get: () => Promise<CheckoutCart | null>;
+        /** Saves any of the shopper's details, complete or not. */
+        update: (input: CartUpdateInput) => Promise<CartChange>;
+        applyCoupon: (code: string) => Promise<CartChange>;
+        removeCoupon: (code: string) => Promise<CartChange>;
+        /** Starts the payment session, or updates it after the total changed. For Stripe, a PaymentIntent's client secret and the publishable key. */
+        createPaymentSession: () => Promise<PaymentSessionResult>;
+        /**
+         * Saves `input` and places the order in one call, then forgets the cart. Retrying with the same
+         * idempotency key returns the same order instead of placing another.
+         */
+        placeOrder: (order: {
+            idempotencyKey: string;
+            payment?: {
+                token?: string;
+            };
+            input?: CartUpdateInput;
+        }) => Promise<PlaceOrderResult>;
+    };
+};
+export type CartSession = ReturnType<typeof createCartSession>;

package/dist/cart.js

@@ -0,0 +1,230 @@
+import { CART_CREATE, CART_LINES_ADD, CART_LINES_REMOVE, CART_LINES_UPDATE, CART_MOVE, CART_QUERY, CART_UPDATE, checkoutCart, CONVERTED_CART, COUPON_APPLY, COUPON_REMOVE, LEGACY_PAYMENT_FIELDS, PAYMENT_FIELDS, PAYMENT_SESSION_CREATE, PLACE_ORDER, } from "./documents.js";
+import { StorefrontApiError } from "./errors.js";
+/** A failed cart change. `available` is set when there is not enough stock. */
+export class CartError extends Error {
+    code;
+    available;
+    constructor(message, code, available = null) {
+        super(message);
+        this.name = "CartError";
+        this.code = code;
+        this.available = available;
+    }
+}
+const FRESH = { init: { cache: "no-store" } };
+/** NotFoundError: the cart is gone. InvalidStateError: it became an order. */
+const isGone = (typename) => typename === "NotFoundError" || typename === "InvalidStateError";
+const unwrap = (result) => {
+    if (result?.cart)
+        return result.cart;
+    throw new CartError(result?.message ?? "The cart could not be updated", result?.code ?? result?.__typename ?? "UNKNOWN", result?.available ?? null);
+};
+const fieldErrorsOf = (errors) => (errors ?? []).flatMap((e) => (e.path?.length && e.message ? [{ path: e.path, message: e.message }] : []));
+const lacksPaymentFields = (error) => error instanceof StorefrontApiError && /Cannot query field "(provider|sessionRequired)"/.test(error.message);
+const toPaymentMethod = (m) => ({
+    code: m.code,
+    name: m.name || m.code,
+    instructions: m.instructions,
+    provider: m.provider ?? null,
+    sessionRequired: m.sessionRequired ?? false,
+});
+const toChange = (result) => {
+    const failure = (reason) => ({
+        ok: false,
+        reason,
+        type: result?.__typename ?? null,
+        message: result?.message ?? null,
+        fieldErrors: fieldErrorsOf(result?.fieldErrors),
+        couponReason: result?.reason ?? null,
+    });
+    switch (result?.__typename) {
+        case "CartPayload":
+            return { ok: true };
+        case "ValidationError":
+        case "CouponNotApplicableError":
+            return failure("invalid");
+        case "NotFoundError":
+            return failure("expired");
+        case "InvalidStateError":
+            return failure("closed");
+        default:
+            return failure("error");
+    }
+};
+/** The shopper's cart and checkout, with the cart's id kept in `store`. Nothing is read from a cache. */
+export const createCartSession = (client, store, options = {}) => {
+    const isUsable = options.isUsable ?? ((cart) => cart.isOpen);
+    const run = (document, variables) => client.query(document, variables, FRESH);
+    const keep = async (cart) => {
+        await store.set(cart);
+        return cart;
+    };
+    const get = async () => {
+        const id = await store.get();
+        if (!id)
+            return null;
+        const { cart } = await run(CART_QUERY, { id });
+        return cart && isUsable(cart) ? cart : null;
+    };
+    /** Creates a cart on the first add, or when the stored one became an order or was removed. */
+    const add = async (lines) => {
+        const id = await store.get();
+        if (id && (await get())) {
+            const { result } = await run(CART_LINES_ADD, { id, lines });
+            if (!isGone(result.__typename))
+                return keep(unwrap(result));
+        }
+        return keep(unwrap((await run(CART_CREATE, { lines })).result));
+    };
+    /** Changes a line's quantity; 0 removes the line. */
+    const update = async (lineId, quantity) => {
+        const id = await store.get();
+        if (!id)
+            throw new CartError("The cart has expired", "NOT_FOUND");
+        const { result } = quantity > 0
+            ? await run(CART_LINES_UPDATE, { id, lines: [{ lineId, quantity }] })
+            : await run(CART_LINES_REMOVE, { id, lineIds: [lineId] });
+        if (isGone(result.__typename)) {
+            await store.clear();
+            throw new CartError("The cart has expired", "NOT_FOUND");
+        }
+        return keep(unwrap(result));
+    };
+    /** Moves the cart to another of the channel's languages and currencies, keeping its items, codes and details. */
+    const move = async (to) => {
+        const id = await store.get();
+        if (!id)
+            return;
+        const { result } = await run(CART_MOVE, { id, input: { locale: to.locale, currencyCode: to.currency } });
+        if (result.cart)
+            await store.set(result.cart);
+        else if (isGone(result.__typename))
+            await store.clear();
+        else
+            throw new CartError(result.message ?? "The cart could not be moved", result.code ?? result.__typename);
+    };
+    /** A change to the stored cart. A cart that is gone is forgotten. */
+    const change = async (document, variables) => {
+        const id = await store.get();
+        if (!id)
+            return toChange({ __typename: "NotFoundError" });
+        const { result } = await run(document, { cartId: id, ...variables });
+        const outcome = toChange(result);
+        if (!outcome.ok && outcome.reason === "expired")
+            await store.clear();
+        return outcome;
+    };
+    /** The order a cart already became, e.g. when a payment webhook placed it first. */
+    const convertedOrder = async (id) => {
+        try {
+            const { cart } = await run(CONVERTED_CART, { id });
+            return cart && !cart.isOpen ? cart.order : null;
+        }
+        catch (error) {
+            console.error("Could not check whether the cart became an order", error);
+            return null;
+        }
+    };
+    const checkout = {
+        /** The cart with everything checkout shows; null when there is none to check out. */
+        get: async () => {
+            const id = await store.get();
+            if (!id)
+                return null;
+            let data;
+            try {
+                data = await run(checkoutCart(PAYMENT_FIELDS), { id });
+            }
+            catch (error) {
+                // An older API without these fields: everything but the payment form works.
+                if (!lacksPaymentFields(error))
+                    throw error;
+                data = await run(checkoutCart(LEGACY_PAYMENT_FIELDS), { id });
+            }
+            const cart = data.cart;
+            if (!cart || !isUsable(cart))
+                return null;
+            const paymentMethods = (cart.availablePaymentMethods ?? []).map(toPaymentMethod);
+            return {
+                id: cart.id,
+                version: cart.version,
+                email: cart.email,
+                requiresShipping: cart.requiresShipping,
+                missing: cart.missing ?? [],
+                shippingAddress: cart.shippingAddress,
+                billingAddress: cart.billingAddress,
+                billingSameAsShipping: cart.billingSameAsShipping,
+                shippingMethods: cart.availableShippingMethods ?? [],
+                selectedShipping: cart.selectedShippingMethod,
+                paymentMethods,
+                selectedPayment: paymentMethods.find((m) => m.code === cart.selectedPaymentMethod?.code) ?? null,
+                coupons: cart.coupons ?? [],
+                discounts: cart.discounts ?? [],
+                cost: cart.cost,
+                lines: cart.lines ?? [],
+            };
+        },
+        /** Saves any of the shopper's details, complete or not. */
+        update: (input) => change(CART_UPDATE, { input }),
+        applyCoupon: (code) => change(COUPON_APPLY, { code }),
+        removeCoupon: (code) => change(COUPON_REMOVE, { code }),
+        /** Starts the payment session, or updates it after the total changed. For Stripe, a PaymentIntent's client secret and the publishable key. */
+        createPaymentSession: async () => {
+            const id = await store.get();
+            if (!id)
+                return { ok: false, reason: "expired", message: null };
+            const { result } = await run(PAYMENT_SESSION_CREATE, { cartId: id });
+            if (result?.__typename === "CartPaymentSessionPayload" && result.session)
+                return { ok: true, session: { ...result.session, clientData: result.session.clientData ?? {} } };
+            if (result?.__typename === "CartNotReadyError")
+                return { ok: false, reason: "not_ready", message: result.message ?? null };
+            // InvalidStateError: the cart became an order, or the provider refused (the message says why).
+            return { ok: false, reason: "refused", message: result?.message ?? null };
+        },
+        /**
+         * Saves `input` and places the order in one call, then forgets the cart. Retrying with the same
+         * idempotency key returns the same order instead of placing another.
+         */
+        placeOrder: async (order) => {
+            const fail = (reason, result) => ({
+                ok: false,
+                reason,
+                type: result?.__typename ?? null,
+                message: result?.message ?? null,
+                missing: result?.missing ?? [],
+                fieldErrors: fieldErrorsOf(result?.fieldErrors),
+            });
+            const id = await store.get();
+            if (!id)
+                return fail("expired");
+            const placed = async (ref) => {
+                await store.clear();
+                return { ok: true, order: ref, cartId: id };
+            };
+            const { result } = await run(PLACE_ORDER, { cartId: id, idempotencyKey: order.idempotencyKey, payment: order.payment ?? {}, input: order.input ?? null });
+            switch (result?.__typename) {
+                case "CheckoutPayload":
+                    if (result.order)
+                        return placed(result.order);
+                    break;
+                case "PaymentDeclinedError":
+                    return fail("declined", result);
+                case "CartNotReadyError":
+                    return fail("not_ready", result);
+                case "InsufficientStockError":
+                    return fail("stock", result);
+                case "InvalidStateError": {
+                    const ref = await convertedOrder(id);
+                    return ref ? placed(ref) : fail("closed", result);
+                }
+                case "NotFoundError":
+                    await store.clear();
+                    return fail("expired", result);
+                case "ValidationError":
+                    return fail("invalid", result);
+            }
+            return fail("error", result);
+        },
+    };
+    return { id: () => store.get(), get, add, update, move, forget: () => store.clear(), checkout };
+};

package/dist/client.d.ts

@@ -0,0 +1,102 @@
+import type { BuilderPage, CategoryTreeNode, Connection, ContentNode, Country, PageEntry, PlacedOrder, PreviewSession, ProductSort, ProductSummary, RouteData, SiteData, TemplatePage } from "./types.ts";
+export type StorefrontScope = {
+    /** The channel's code, sent as x-channel. */
+    channel: string;
+    /** One of the channel's languages; null for its default. */
+    locale?: string | null;
+    /** One of the channel's currencies; null for its default. */
+    currency?: string | null;
+};
+export type StorefrontClientOptions = StorefrontScope & {
+    /** The platform's URL. It serves GraphQL at /graphql. */
+    url: string;
+    /** Sent as x-preview-token, so reads return draft content. */
+    previewToken?: string | null;
+    /** Fetch options for every request, other than method, headers and body. */
+    init?: RequestInit;
+    fetch?: (input: string, init: RequestInit) => Promise<Response>;
+};
+/** Fetch options for one request, such as Next.js's `next: { tags }`. */
+export type RequestOptions = {
+    init?: RequestInit;
+};
+/** Every node of a connection, up to `limit` pages. */
+export declare const allNodes: <N>(load: (after: string | null) => Promise<Connection<N> | null>, limit?: number) => Promise<N[]>;
+type Root = {
+    id: string;
+    component: string;
+};
+export type StorefrontClient = ReturnType<typeof createStorefrontClient>;
+/** The Storefront API for one channel, language and currency. Failed requests throw StorefrontApiError. */
+export declare const createStorefrontClient: (options: StorefrontClientOptions) => {
+    url: string;
+    scope: {
+        channel: string;
+        locale: string | null;
+        currency: string | null;
+    };
+    previewToken: string | null;
+    /** The same client with another scope, preview token or fetch options. */
+    with: (changes: Partial<StorefrontClientOptions>) => /*elided*/ any;
+    query: <T>(document: string, variables?: Record<string, unknown>, request?: RequestOptions) => Promise<T>;
+    /** A path on the API host, such as /media/…, as an absolute URL. */
+    mediaUrl: (src: string) => string;
+    /** A storefront URL path as a page, product, category or redirect; null when nothing is there. */
+    route: (path: string, request?: RequestOptions) => Promise<RouteData | null>;
+    /** The template a product or category page renders with; null for the storefront's own layout. */
+    routeTemplate: (path: string, request?: RequestOptions) => Promise<TemplatePage | null>;
+    /** A product's or category's own sections, which its template places. */
+    routeSections: (path: string, request?: RequestOptions) => Promise<BuilderPage | null>;
+    /** The header and footer (singleton pages of these content types), and the request's language and currency. */
+    site: <Header extends Root = ContentNode, Footer extends Root = ContentNode>(types?: {
+        header?: string;
+        footer?: string;
+    }, request?: RequestOptions) => Promise<SiteData<Header, Footer>>;
+    newestProducts: (first: number, request?: RequestOptions) => Promise<ProductSummary[]>;
+    /** A page of a category's products, its subcategories' included. `endCursor` is null on the last page. */
+    categoryProducts: (id: string, page: {
+        first: number;
+        after?: string | null;
+        sort?: ProductSort | null;
+    }, request?: RequestOptions) => Promise<{
+        products: ProductSummary[];
+        totalCount: number;
+        endCursor: string | null;
+    }>;
+    /** A page of published pages, of one content type or all of them. */
+    pages: (page: {
+        type?: string | null;
+        first: number;
+        after?: string | null;
+    }, request?: RequestOptions) => Promise<Connection<PageEntry> | null>;
+    /** A page of product slugs, 100 at a time. */
+    productSlugs: (after: string | null, request?: RequestOptions) => Promise<Connection<{
+        slug: string;
+    }> | null>;
+    /** Category paths, four levels deep. */
+    categoryTree: (request?: RequestOptions) => Promise<CategoryTreeNode[]>;
+    /** A product's slug or a category's path in the client's language, for hreflang links. */
+    localizedPath: (id: string, request?: RequestOptions) => Promise<string | null>;
+    /** The session of the client's preview token; null when the API refuses the token. */
+    previewSession: (request?: RequestOptions) => Promise<PreviewSession | null>;
+    /** The countries the channel ships to, named in the client's language. */
+    countries: (request?: RequestOptions) => Promise<{
+        locale: string | null;
+        countries: Country[];
+    }>;
+    /** An order looked up as its guest shopper would, with the payment method of the cart it came from. */
+    guestOrder: (lookup: {
+        email: string;
+        number: string;
+        postalCode: string;
+        cartId: string;
+    }, request?: RequestOptions) => Promise<{
+        order: PlacedOrder;
+        paymentMethod: {
+            code: string;
+            name: string | null;
+            instructions: string | null;
+        } | null;
+    } | null>;
+};
+export {};

package/dist/client.js

@@ -0,0 +1,108 @@
+import { CATEGORY_PRODUCTS, CATEGORY_TREE, COUNTRIES, GUEST_ORDER, LOCALIZED_PATH, NEWEST_PRODUCTS, PAGES, PREVIEW_SESSION, PRODUCT_SLUGS, ROUTE, SECTIONS, SITE, TEMPLATE, } from "./documents.js";
+import { isPreviewExpired, PreviewExpiredError, StorefrontApiError } from "./errors.js";
+import { mediaUrl } from "./media.js";
+const nodesOf = (connection) => (connection?.edges ?? []).flatMap((e) => (e.node ? [e.node] : []));
+/** Every node of a connection, up to `limit` pages. */
+export const allNodes = async (load, limit = 50) => {
+    const items = [];
+    let after = null;
+    for (let i = 0; i < limit; i++) {
+        const connection = await load(after);
+        items.push(...nodesOf(connection));
+        if (!connection?.pageInfo.hasNextPage || !connection.pageInfo.endCursor)
+            break;
+        after = connection.pageInfo.endCursor;
+    }
+    return items;
+};
+/** The Storefront API for one channel, language and currency. Failed requests throw StorefrontApiError. */
+export const createStorefrontClient = (options) => {
+    const url = options.url.replace(/\/+$/, "");
+    const scope = { channel: options.channel, locale: options.locale ?? null, currency: options.currency ?? null };
+    const previewToken = options.previewToken ?? null;
+    // Looked up per request: frameworks such as Next.js replace the global fetch.
+    const send = options.fetch ?? ((input, init) => fetch(input, init));
+    const query = async (document, variables = {}, request = {}) => {
+        const headers = { "content-type": "application/json", accept: "application/json", "x-channel": scope.channel };
+        if (scope.locale)
+            headers["x-locale"] = scope.locale;
+        if (scope.currency)
+            headers["x-currency"] = scope.currency;
+        if (previewToken)
+            headers["x-preview-token"] = previewToken;
+        let response;
+        try {
+            response = await send(`${url}/graphql`, { ...options.init, ...request.init, method: "POST", headers, body: JSON.stringify({ query: document, variables }) });
+        }
+        catch (cause) {
+            throw new StorefrontApiError(`The Storefront API at ${url} could not be reached`, 0, [], { cause });
+        }
+        const body = (await response.json().catch(() => null));
+        const codes = (body?.errors ?? []).map((e) => e.extensions?.code ?? "UNKNOWN");
+        // An invalid preview token fails the whole request with 401 UNAUTHENTICATED.
+        if (previewToken && (response.status === 401 || codes.includes("UNAUTHENTICATED")))
+            throw new PreviewExpiredError();
+        if (body?.errors?.length)
+            throw new StorefrontApiError(body.errors.map((e) => e.message).join("; "), response.status, codes);
+        if (!response.ok || !body?.data)
+            throw new StorefrontApiError(`The Storefront API answered HTTP ${response.status}`, response.status, codes);
+        return body.data;
+    };
+    return {
+        url,
+        scope,
+        previewToken,
+        /** The same client with another scope, preview token or fetch options. */
+        with: (changes) => createStorefrontClient({ ...options, ...changes }),
+        query,
+        /** A path on the API host, such as /media/…, as an absolute URL. */
+        mediaUrl: (src) => mediaUrl(url, src),
+        /** A storefront URL path as a page, product, category or redirect; null when nothing is there. */
+        route: async (path, request) => (await query(ROUTE, { path }, request)).route,
+        /** The template a product or category page renders with; null for the storefront's own layout. */
+        routeTemplate: async (path, request) => (await query(TEMPLATE, { path }, request)).route?.template ?? null,
+        /** A product's or category's own sections, which its template places. */
+        routeSections: async (path, request) => (await query(SECTIONS, { path }, request)).route?.sections ?? null,
+        /** The header and footer (singleton pages of these content types), and the request's language and currency. */
+        site: (types = {}, request) => query(SITE, { header: types.header ?? "site_header", footer: types.footer ?? "site_footer" }, request),
+        newestProducts: async (first, request) => nodesOf((await query(NEWEST_PRODUCTS, { first }, request)).products),
+        /** A page of a category's products, its subcategories' included. `endCursor` is null on the last page. */
+        categoryProducts: async (id, page, request) => {
+            const data = await query(CATEGORY_PRODUCTS, { id, first: page.first, after: page.after ?? null, sort: page.sort ?? null }, request);
+            const connection = data.category?.products;
+            return { products: nodesOf(connection), totalCount: connection?.totalCount ?? 0, endCursor: connection?.pageInfo.hasNextPage ? connection.pageInfo.endCursor : null };
+        },
+        /** A page of published pages, of one content type or all of them. */
+        pages: async (page, request) => (await query(PAGES, { type: page.type ?? null, first: page.first, after: page.after ?? null }, request)).pages,
+        /** A page of product slugs, 100 at a time. */
+        productSlugs: async (after, request) => (await query(PRODUCT_SLUGS, { after }, request)).products,
+        /** Category paths, four levels deep. */
+        categoryTree: async (request) => (await query(CATEGORY_TREE, {}, request)).categoryTree ?? [],
+        /** A product's slug or a category's path in the client's language, for hreflang links. */
+        localizedPath: async (id, request) => {
+            const data = await query(LOCALIZED_PATH, { id }, request);
+            return data.node?.slug ?? data.node?.path ?? null;
+        },
+        /** The session of the client's preview token; null when the API refuses the token. */
+        previewSession: async (request) => {
+            try {
+                return (await query(PREVIEW_SESSION, {}, request)).previewSession;
+            }
+            catch (error) {
+                if (isPreviewExpired(error))
+                    return null;
+                throw error;
+            }
+        },
+        /** The countries the channel ships to, named in the client's language. */
+        countries: async (request) => {
+            const data = await query(COUNTRIES, {}, request);
+            return { locale: data.localization?.locale ?? null, countries: (data.localization?.channel?.countries ?? []).filter((c) => c.code) };
+        },
+        /** An order looked up as its guest shopper would, with the payment method of the cart it came from. */
+        guestOrder: async (lookup, request) => {
+            const data = await query(GUEST_ORDER, lookup, request);
+            return data.order ? { order: data.order, paymentMethod: data.cart?.selectedPaymentMethod ?? null } : null;
+        },
+    };
+};