basketeer 0.1.0

package/dist/client.js

@@ -0,0 +1,341 @@
+import { BasketeerError, LineRejectedError, NotFoundError } from "./errors.js";
+import { GraphQLTransport } from "./graphql.js";
+import { filterByNutrition } from "./nutrition.js";
+import { CHECKOUT_URL, FULFILMENT_TYPE, MFE, PENDING_ORDER_CONTEXTS, } from "./operations.js";
+import { isoDate, parseBasket, parseBookedSlot, parseOrder, parseProduct, parseProductNode, parseSlot, } from "./parsers.js";
+import { AMEND_ORDER, CANCEL_AMEND, CANCEL_ORDER, COLLECTION_SLOTS, DELIVERY_SLOTS, FULFILMENT, GET_BASKET, GET_CATEGORY_PRODUCTS, GET_FAVOURITES, GET_LAST_FULFILLED_ORDER, GET_PRODUCT, GET_UPCOMING_ORDERS, SEARCH, UPDATE_BASKET, } from "./queries.js";
+import { SessionManager } from "./session-manager.js";
+/** Guard for numeric SDK inputs. Throws `RangeError` for non-integer or out-of-range values. */
+function reqInt(v, name, min) {
+    if (v === undefined)
+        return;
+    if (!Number.isInteger(v) || v < min)
+        throw new RangeError(`${name} must be an integer >= ${min}`);
+}
+/**
+ * Guard for a basket-line quantity (the low-level `basket.update` escape hatch).
+ * Rejects negative, NaN, and Infinity; allows fractional values for weight-priced
+ * lines. `JSON.stringify(NaN)` → `null`, which Tesco would silently misread.
+ */
+function reqQty(v, name) {
+    if (!Number.isFinite(v) || v < 0)
+        throw new RangeError(`${name} must be a finite number >= 0`);
+}
+function normaliseItem(item) {
+    return {
+        adjustment: item.adjustment ?? false,
+        id: String(item.id),
+        newValue: item.newValue,
+        newUnitChoice: item.newUnitChoice ?? "pcs",
+        substitutionOption: item.substitutionOption ?? "FindSuitableAlternative",
+    };
+}
+export class Basketeer {
+    transport;
+    sessions;
+    _amendingOrderNo = null;
+    constructor(opts = {}) {
+        this.sessions = new SessionManager({
+            session: opts.session,
+            backend: opts.authBackend,
+            store: opts.store,
+        });
+        this.transport = new GraphQLTransport({
+            apiKey: opts.apiKey,
+            throttleMs: opts.throttleMs,
+            fetchImpl: opts.fetchImpl,
+            getAuth: () => this.sessions.authHeaders(),
+            onUnauthorized: () => this.sessions.refresh(),
+        });
+    }
+    /** Resume a persisted session, refreshing proactively if it has expired. */
+    static async resume(opts = {}) {
+        const client = new Basketeer(opts);
+        await client.sessions.load();
+        if (client.sessions.isExpired() && opts.authBackend) {
+            await client.sessions.refresh();
+        }
+        return client;
+    }
+    /** Mint a new session via the configured AuthBackend. */
+    async login(credentials) {
+        return this.sessions.login(credentials);
+    }
+    /** The current session, or null if unauthenticated. */
+    get session() {
+        return this.sessions.current;
+    }
+    /** True when a (non-expired) session is loaded. */
+    get isAuthenticated() {
+        return this.sessions.current !== null && !this.sessions.isExpired();
+    }
+    /** The order currently open for amendment via `orders.amend`, if any. */
+    get amendingOrderNo() {
+        return this._amendingOrderNo;
+    }
+    // --- reads (anonymous) ----------------------------------------------------
+    async getProduct(sku) {
+        const data = await this.transport.execute({
+            operationName: "GetProduct",
+            query: GET_PRODUCT,
+            variables: { tpnc: String(sku) },
+            mfeName: MFE.product,
+        });
+        if (!data.product)
+            throw new NotFoundError(`No product found for SKU ${sku}`);
+        return parseProduct(data.product);
+    }
+    async search(query, opts = {}) {
+        reqInt(opts.limit, "limit", 1);
+        reqInt(opts.page, "page", 1);
+        const data = await this.transport.execute({
+            operationName: "Search",
+            query: SEARCH,
+            variables: { query, count: opts.limit ?? 10, page: opts.page ?? 1 },
+            mfeName: MFE.search,
+        });
+        return this.page(data.search?.results, (e) => e.node, opts);
+    }
+    /**
+     * Keyword search, then hydrate the top `hydrate` results' nutrition (each a throttled
+     * product fetch) and filter/rank locally. The cost is bounded by `hydrate` (default 20)
+     * and reported honestly: `hydrated` is how many products were fetched, `failed` how many
+     * detail fetches errored (and were skipped, not fatal), and `hasMore` whether the
+     * catalogue had more keyword matches than were hydrated.
+     */
+    async searchByNutrition(query, opts = {}) {
+        reqInt(opts.hydrate, "hydrate", 1);
+        reqInt(opts.limit, "limit", 1);
+        const cap = opts.hydrate ?? 20;
+        const page = await this.search(query, { limit: Math.max(cap, opts.limit ?? 0) });
+        const head = page.results.slice(0, cap);
+        const hydrated = [];
+        let failed = 0;
+        for (const r of head) {
+            try {
+                hydrated.push(await this.getProduct(r.sku)); // serial — relies on the 1 req/s transport throttle
+            }
+            catch (err) {
+                if (err instanceof NotFoundError) {
+                    failed++;
+                    continue;
+                } // discontinued/regional SKU 404s — soft-skip
+                throw err; // rate-limit, bad key, auth, transport, schema — these are real; don't hide them
+            }
+        }
+        let results = filterByNutrition(hydrated, { where: opts.where, sort: opts.sort });
+        if (opts.limit != null)
+            results = results.slice(0, opts.limit);
+        return { results, hydrated: hydrated.length, failed, hasMore: page.hasMore };
+    }
+    /**
+     * List products in a category. Build `facet` with {@link categoryFacet} (or
+     * lift it from a Tesco category-page URL `?...&facet=…`).
+     */
+    async browseCategory(facet, opts = {}) {
+        reqInt(opts.limit, "limit", 1);
+        reqInt(opts.page, "page", 1);
+        const data = await this.transport.execute({
+            operationName: "GetCategoryProducts",
+            query: GET_CATEGORY_PRODUCTS,
+            variables: { facet, count: opts.limit ?? 24, page: opts.page ?? 1 },
+            mfeName: MFE.search,
+        });
+        return this.page(data.category?.results, (e) => e.node, { limit: 24, ...opts });
+    }
+    /** The customer's favourites ("my usuals"). */
+    async favourites(opts = {}) {
+        reqInt(opts.limit, "limit", 1);
+        reqInt(opts.page, "page", 1);
+        const data = await this.transport.execute({
+            operationName: "GetFavourites",
+            query: GET_FAVOURITES,
+            variables: { count: opts.limit ?? 50, page: opts.page ?? 1, sortBy: "TAXONOMY" },
+            mfeName: MFE.favourites,
+        });
+        return this.page(data.favourites?.products, (p) => p, { limit: 50, ...opts });
+    }
+    /** Shared paging: map nodes → SearchResult, drop nulls, derive `hasMore`. */
+    page(raw, node, opts) {
+        const pageSize = opts.limit ?? 10;
+        const rows = raw ?? [];
+        const results = rows
+            .map((r) => parseProductNode(node(r)))
+            .filter((r) => r !== null);
+        return { results, page: opts.page ?? 1, pageSize, hasMore: rows.length >= pageSize };
+    }
+    // --- basket (requires auth) -----------------------------------------------
+    basket = {
+        get: () => this.getBasket(),
+        /**
+         * Increment the line for `sku` by `quantity` (default 1). Reads the current
+         * quantity first, so it costs an extra request and is not safe under
+         * concurrent edits — use `set` for exact, idempotent quantities.
+         */
+        add: async (sku, quantity = 1, unit = "pcs") => {
+            if (!Number.isInteger(quantity) || quantity < 1)
+                throw new RangeError("quantity must be an integer >= 1");
+            const current = (await this.getBasket()).items.find((i) => i.sku === sku)?.quantity ?? 0;
+            return this.updateBasket([{ id: sku, newValue: current + quantity, newUnitChoice: unit }]);
+        },
+        /** Set the line for `sku` to an exact `quantity` (0 removes it). */
+        set: (sku, quantity, unit = "pcs") => {
+            if (!Number.isInteger(quantity) || quantity < 0)
+                throw new RangeError("quantity must be an integer >= 0");
+            return this.updateBasket([{ id: sku, newValue: quantity, newUnitChoice: unit }]);
+        },
+        /** Remove `sku` from the basket. */
+        remove: (sku) => this.updateBasket([{ id: sku, newValue: 0 }]),
+        /** Low-level: send raw basket line inputs (and an optional orderId). */
+        update: (items, orderId) => this.updateBasket(items, orderId),
+    };
+    async getBasket() {
+        const data = await this.transport.execute({
+            operationName: "GetBasket",
+            query: GET_BASKET,
+            variables: {},
+            mfeName: MFE.basket,
+        });
+        return parseBasket(data.basket);
+    }
+    async updateBasket(items, orderId) {
+        for (const item of items)
+            reqQty(item.newValue, "quantity");
+        const variables = { items: items.map(normaliseItem) };
+        if (orderId !== undefined)
+            variables.orderId = orderId;
+        const data = await this.transport.execute({
+            operationName: "UpdateBasket",
+            query: UPDATE_BASKET,
+            variables,
+            mfeName: MFE.basket,
+        });
+        const updates = data.basket?.updates?.items ?? [];
+        const rejected = updates.filter((u) => u.successful === false).map((u) => String(u.id));
+        if (rejected.length)
+            throw new LineRejectedError(rejected.join(", "));
+        return parseBasket(data.basket);
+    }
+    // --- orders (requires auth) -----------------------------------------------
+    orders = {
+        /** List upcoming (pending) orders with their items, slot, and amend window. */
+        list: (opts = {}) => this.listOrders(opts),
+        /**
+         * Open an order for amendment. Returns an {@link Amendment} handle whose
+         * basket ops apply to THAT order; finish by checking out again, or call
+         * `discard()`. Only works before the order's `amendExpiry`. While amending,
+         * `client.amendingOrderNo` reports the open order.
+         */
+        amend: (orderNo) => this.amendOrder(orderNo),
+        /** Cancel an order outright (before its amend/cancel cutoff). */
+        cancel: (orderNo) => this.cancelOrder(orderNo),
+        /** The last delivered order (its items), for "reorder my usual shop". */
+        lastFulfilled: () => this.lastFulfilledOrder(),
+    };
+    async amendOrder(orderNo) {
+        await this.orderAction(AMEND_ORDER, "AmendOrder", orderNo);
+        this._amendingOrderNo = orderNo;
+        return {
+            orderNo,
+            get: () => this.getBasket(),
+            set: (sku, quantity, unit) => this.basket.set(sku, quantity, unit),
+            remove: (sku) => this.basket.remove(sku),
+            discard: async () => {
+                await this.orderAction(CANCEL_AMEND, "CancelAmend", orderNo);
+                if (this._amendingOrderNo === orderNo)
+                    this._amendingOrderNo = null;
+            },
+        };
+    }
+    async cancelOrder(orderNo) {
+        await this.orderAction(CANCEL_ORDER, "CancelOrder", orderNo);
+        if (this._amendingOrderNo === orderNo)
+            this._amendingOrderNo = null;
+    }
+    async lastFulfilledOrder() {
+        const data = await this.transport.execute({
+            operationName: "GetLastFulfilledOrder",
+            query: GET_LAST_FULFILLED_ORDER,
+            variables: { status: "LastFulfilled" },
+            mfeName: MFE.orders,
+        });
+        return data.order ? parseOrder(data.order) : null;
+    }
+    async listOrders(opts) {
+        const data = await this.transport.execute({
+            operationName: "GetUpcomingOrders",
+            query: GET_UPCOMING_ORDERS,
+            variables: { orderContexts: opts.contexts ?? PENDING_ORDER_CONTEXTS },
+            mfeName: MFE.orders,
+        });
+        return (data.orderSearch?.orders ?? []).map(parseOrder);
+    }
+    async orderAction(query, operationName, orderNo) {
+        await this.transport.execute({
+            operationName,
+            query,
+            variables: { orderNo },
+            mfeName: MFE.orders,
+        });
+    }
+    // --- checkout (boundary: pure HTTP up to payment) -------------------------
+    /**
+     * Prepare for payment. Returns the current basket and the URL where payment
+     * is completed **in a browser**. basketeer deliberately stops here:
+     * Tesco's payment step is a separate CSRF-protected checkout app + 3-D Secure
+     * card authentication — browser-bound by design and PCI/fraud-sensitive. Fill
+     * the basket and book a slot via this SDK, then complete payment at `url`.
+     */
+    async checkout() {
+        return { basket: await this.getBasket(), url: CHECKOUT_URL };
+    }
+    // --- slots (requires auth) ------------------------------------------------
+    slots = {
+        /** List delivery slots over a date window (default today..+6 days). */
+        list: (opts = {}) => this.listSlots(opts),
+        /** List click-and-collect slots for a store (`locationUuid`); default today..+6 days. */
+        listCollection: (opts = {}) => this.listCollectionSlots(opts),
+        /** Reserve a slot by id. Held until `reservationExpiry`; check out before then. */
+        book: (slotId) => this.fulfilment(slotId, "BOOK"),
+        /** Release a previously-reserved slot. */
+        release: (slotId) => this.fulfilment(slotId, "UNBOOK"),
+    };
+    async listSlots(opts) {
+        const data = await this.transport.execute({
+            operationName: "DeliverySlots",
+            query: DELIVERY_SLOTS,
+            variables: {
+                start: opts.start ?? isoDate(0),
+                end: opts.end ?? isoDate(6),
+                type: opts.type ?? FULFILMENT_TYPE.delivery,
+            },
+            mfeName: MFE.slots,
+        });
+        return (data.delivery ?? []).map(parseSlot);
+    }
+    async listCollectionSlots(opts) {
+        const data = await this.transport.execute({
+            operationName: "CollectionSlots",
+            query: COLLECTION_SLOTS,
+            variables: {
+                start: opts.start ?? isoDate(0),
+                end: opts.end ?? isoDate(6),
+                locationUuid: opts.locationUuid ?? null,
+            },
+            mfeName: MFE.slots,
+        });
+        return (data.collection ?? []).map(parseSlot);
+    }
+    async fulfilment(slotId, action) {
+        const data = await this.transport.execute({
+            operationName: "Fulfilment",
+            query: FULFILMENT,
+            variables: { slotId, action },
+            mfeName: MFE.slots,
+        });
+        const slot = data.fulfilment?.slot;
+        if (!slot)
+            throw new BasketeerError(`Slot ${action} returned no slot`);
+        return parseBookedSlot(slot);
+    }
+}

package/dist/errors.d.ts

@@ -0,0 +1,40 @@
+/** Base class for every error this library throws. */
+export declare class BasketeerError extends Error {
+    constructor(message: string);
+}
+/**
+ * The session could not be renewed (refresh failed or no session present).
+ * Callers must re-authenticate — interactively for OSS users, or via the
+ * consumer's own re-login flow.
+ */
+export declare class AuthExpiredError extends BasketeerError {
+}
+/**
+ * Tesco returned 429/403 (rate limited or bot-blocked). The client never
+ * retry-storms: it surfaces this so callers back off. Honour polite usage.
+ */
+export declare class RateLimitedError extends BasketeerError {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+/**
+ * The gateway rejected the `x-apikey` (HTTP 403, body `Forbidden: Invalid
+ * Client`). The public key rotates ~monthly — set `TESCO_API_KEY` or update
+ * `PUBLIC_API_KEY`. This is a configuration error, never retryable.
+ */
+export declare class ApiKeyError extends BasketeerError {
+}
+/** Thrown when a requested resource does not exist (e.g. an unknown SKU). */
+export declare class NotFoundError extends BasketeerError {
+}
+/** The GraphQL response carried an `errors` array (non-auth). */
+export declare class GraphQLRequestError extends BasketeerError {
+    /** The raw GraphQL errors, for programmatic inspection. */
+    readonly errors: unknown[];
+    constructor(errors: unknown[]);
+}
+/** A basket line update was rejected by Tesco (updates.items[].successful === false). */
+export declare class LineRejectedError extends BasketeerError {
+    readonly lineId: string;
+    constructor(lineId: string);
+}

package/dist/errors.js

@@ -0,0 +1,64 @@
+/** Base class for every error this library throws. */
+export class BasketeerError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = new.target.name;
+    }
+}
+/**
+ * The session could not be renewed (refresh failed or no session present).
+ * Callers must re-authenticate — interactively for OSS users, or via the
+ * consumer's own re-login flow.
+ */
+export class AuthExpiredError extends BasketeerError {
+}
+/**
+ * Tesco returned 429/403 (rate limited or bot-blocked). The client never
+ * retry-storms: it surfaces this so callers back off. Honour polite usage.
+ */
+export class RateLimitedError extends BasketeerError {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+    }
+}
+/**
+ * The gateway rejected the `x-apikey` (HTTP 403, body `Forbidden: Invalid
+ * Client`). The public key rotates ~monthly — set `TESCO_API_KEY` or update
+ * `PUBLIC_API_KEY`. This is a configuration error, never retryable.
+ */
+export class ApiKeyError extends BasketeerError {
+}
+/** Thrown when a requested resource does not exist (e.g. an unknown SKU). */
+export class NotFoundError extends BasketeerError {
+}
+/** The GraphQL response carried an `errors` array (non-auth). */
+export class GraphQLRequestError extends BasketeerError {
+    /** The raw GraphQL errors, for programmatic inspection. */
+    errors;
+    constructor(errors) {
+        // Keep the message short and scrubbed — the raw array may echo request
+        // context. Full detail stays on `.errors` for programmatic access; callers
+        // should avoid logging the whole object.
+        const first = errors[0]?.message;
+        const summary = typeof first === "string" ? first : "request failed";
+        const more = errors.length > 1 ? ` (+${errors.length - 1} more)` : "";
+        super(`Tesco GraphQL error: ${scrubSecrets(summary)}${more}`);
+        this.errors = errors;
+    }
+}
+/** Redact anything that looks like a bearer/JWT/cookie from a message. */
+function scrubSecrets(s) {
+    return s
+        .replace(/eyJ[A-Za-z0-9_-]{10,}/g, "«jwt»")
+        .replace(/(OAuth\.[A-Za-z]+|_abck|bm_[a-z]+)=[^;\s]+/gi, "$1=«redacted»");
+}
+/** A basket line update was rejected by Tesco (updates.items[].successful === false). */
+export class LineRejectedError extends BasketeerError {
+    lineId;
+    constructor(lineId) {
+        super(`Tesco rejected basket line ${lineId}`);
+        this.lineId = lineId;
+    }
+}

package/dist/graphql.d.ts

@@ -0,0 +1,53 @@
+/** Auth material injected on writes. Undefined for anonymous reads. */
+export interface AuthHeaders {
+    authorization: string;
+    customerUuid: string;
+    /** Pre-serialised `Cookie` header value (auth + Akamai cookies). */
+    cookie?: string;
+}
+export interface GraphQLOp {
+    operationName: string;
+    query: string;
+    variables: Record<string, unknown>;
+    mfeName: string;
+}
+export interface TransportOptions {
+    endpoint?: string;
+    apiKey?: string;
+    userAgent?: string;
+    /** Minimum gap between requests in ms (polite usage). Default 1000. */
+    throttleMs?: number;
+    /** Injected for tests; defaults to global fetch. */
+    fetchImpl?: typeof fetch;
+    /** Returns current auth headers, or undefined for anonymous. */
+    getAuth?: () => AuthHeaders | undefined;
+    /** Called once on a 401; return true if a refresh succeeded (then we retry). */
+    onUnauthorized?: () => Promise<boolean>;
+}
+/**
+ * Pure-HTTP transport for `xapi.tesco.com`. Builds the JSON-array request body,
+ * assembles the header set Tesco expects, throttles to a polite rate, retries
+ * once on a 401 (after refresh), and refuses to retry-storm a 429/403.
+ */
+export declare class GraphQLTransport {
+    private readonly endpoint;
+    private readonly apiKey;
+    private readonly userAgent;
+    private readonly throttleMs;
+    private readonly fetchImpl;
+    private readonly getAuth;
+    private readonly onUnauthorized?;
+    /** Serial gate: each request awaits the previous one's scheduled slot. */
+    private gate;
+    private nextAllowedAt;
+    constructor(opts?: TransportOptions);
+    /** Run one operation; returns its `data` object. Retries once on a 401. */
+    execute<T = Record<string, unknown>>(op: GraphQLOp): Promise<T>;
+    private post;
+    /**
+     * Hand out request slots serially. Each call chains onto the previous one's
+     * scheduled slot, so N concurrent callers (e.g. `Promise.all`) are spaced
+     * `throttleMs` apart rather than all firing at once.
+     */
+    private throttle;
+}

package/dist/graphql.js

@@ -0,0 +1,138 @@
+import { randomUUID } from "node:crypto";
+import { ApiKeyError, AuthExpiredError, GraphQLRequestError, RateLimitedError } from "./errors.js";
+import { ENDPOINT, PUBLIC_API_KEY } from "./operations.js";
+const DEFAULT_UA = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 " +
+    "(KHTML, like Gecko) Chrome/147.0.0.0 Safari/537.36";
+function isUnauthorized(errors) {
+    for (const e of errors) {
+        const err = e;
+        // Synthetic 401 envelope injected by post() for raw HTTP 401 responses.
+        if (err.status === 401)
+            return true;
+        if (typeof err.message === "string" && /unauthor|401/i.test(err.message))
+            return true;
+        // GraphQL extension checks (existing).
+        if (err.extensions?.http?.status === 401)
+            return true;
+    }
+    return false;
+}
+function uuid() {
+    return randomUUID();
+}
+/**
+ * Pure-HTTP transport for `xapi.tesco.com`. Builds the JSON-array request body,
+ * assembles the header set Tesco expects, throttles to a polite rate, retries
+ * once on a 401 (after refresh), and refuses to retry-storm a 429/403.
+ */
+export class GraphQLTransport {
+    endpoint;
+    apiKey;
+    userAgent;
+    throttleMs;
+    fetchImpl;
+    getAuth;
+    onUnauthorized;
+    /** Serial gate: each request awaits the previous one's scheduled slot. */
+    gate = Promise.resolve();
+    nextAllowedAt = 0;
+    constructor(opts = {}) {
+        this.endpoint = opts.endpoint ?? ENDPOINT;
+        this.apiKey = opts.apiKey ?? process.env.TESCO_API_KEY ?? PUBLIC_API_KEY;
+        this.userAgent = opts.userAgent ?? DEFAULT_UA;
+        this.throttleMs = opts.throttleMs ?? 1000;
+        this.fetchImpl = opts.fetchImpl ?? fetch;
+        this.getAuth = opts.getAuth ?? (() => undefined);
+        this.onUnauthorized = opts.onUnauthorized;
+    }
+    /** Run one operation; returns its `data` object. Retries once on a 401. */
+    async execute(op) {
+        for (let attempt = 0; attempt < 2; attempt++) {
+            await this.throttle();
+            const result = await this.post(op);
+            const errors = (result.errors ?? []);
+            if (errors.length && isUnauthorized(errors)) {
+                // First 401: refresh and retry once. Persistent 401: the session is dead.
+                if (attempt === 0 && this.onUnauthorized && (await this.onUnauthorized()))
+                    continue;
+                throw new AuthExpiredError("Tesco auth expired and could not be refreshed — re-authenticate.");
+            }
+            if (errors.length)
+                throw new GraphQLRequestError(errors);
+            return (result.data ?? {});
+        }
+        // Only reached if attempt 1 returned no errors above; keep TS happy.
+        throw new AuthExpiredError("Tesco auth expired and could not be refreshed — re-authenticate.");
+    }
+    async post(op) {
+        const auth = this.getAuth();
+        const headers = {
+            "user-agent": this.userAgent,
+            accept: "application/json",
+            "content-type": "application/json",
+            "accept-language": "en-GB",
+            "x-apikey": this.apiKey,
+            region: "UK",
+            language: "en-GB",
+            traceid: `${uuid()}:${uuid()}`,
+            trkid: uuid(),
+        };
+        if (auth) {
+            headers["authorization"] = auth.authorization;
+            headers["customer-uuid"] = auth.customerUuid;
+            if (auth.cookie)
+                headers["cookie"] = auth.cookie;
+        }
+        const body = JSON.stringify([
+            {
+                operationName: op.operationName,
+                variables: op.variables,
+                extensions: { mfeName: op.mfeName },
+                query: op.query,
+            },
+        ]);
+        const res = await this.fetchImpl(this.endpoint, { method: "POST", headers, body });
+        // Read the body once. Non-2xx responses are often plain text, not JSON.
+        const text = await res.text();
+        if (res.status === 401) {
+            // Raw HTTP 401 (often non-JSON). Surface as unauthorized so execute() refreshes + retries.
+            return { errors: [{ message: "HTTP 401 Unauthorized", status: 401 }] };
+        }
+        if (res.status === 403) {
+            if (/invalid client/i.test(text)) {
+                throw new ApiKeyError('Tesco rejected the x-apikey (403 "Invalid Client"). The public key likely ' +
+                    "rotated — set the TESCO_API_KEY env var or update PUBLIC_API_KEY.");
+            }
+            throw new RateLimitedError(403, "Tesco returned 403 (bot-blocked/forbidden) — backing off.");
+        }
+        if (res.status === 429) {
+            throw new RateLimitedError(429, "Tesco returned 429 (rate limited) — backing off.");
+        }
+        let json;
+        try {
+            json = JSON.parse(text);
+        }
+        catch {
+            throw new GraphQLRequestError([
+                { message: `HTTP ${res.status}: non-JSON body`, snippet: text.slice(0, 200) },
+            ]);
+        }
+        const first = Array.isArray(json) ? json[0] : json;
+        return (first ?? {});
+    }
+    /**
+     * Hand out request slots serially. Each call chains onto the previous one's
+     * scheduled slot, so N concurrent callers (e.g. `Promise.all`) are spaced
+     * `throttleMs` apart rather than all firing at once.
+     */
+    throttle() {
+        const slot = this.gate.then(async () => {
+            const delay = this.nextAllowedAt - Date.now();
+            if (delay > 0)
+                await new Promise((r) => setTimeout(r, delay));
+            this.nextAllowedAt = Date.now() + this.throttleMs;
+        });
+        this.gate = slot.catch(() => { }); // one failure must not poison the chain
+        return slot;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+export { keepCookie, sessionFromCookies } from "./auth/harvest.js";
+export type { AuthBackend, Credentials, OtpProvider } from "./auth/types.js";
+export type { Amendment, BasketeerOptions, BasketItemInput } from "./client.js";
+export { Basketeer } from "./client.js";
+export { ApiKeyError, AuthExpiredError, BasketeerError, GraphQLRequestError, LineRejectedError, NotFoundError, RateLimitedError, } from "./errors.js";
+export type { Basket, BasketLine, BookedSlot, MacroFilterKey, Macros, Micronutrient, Nutrition, NutritionBasis, NutritionFilter, NutritionSort, Order, OrderAddress, OrderItem, OrderSlot, PackSize, Price, Product, Promotion, Range, SearchPage, SearchResult, Session, Slot, } from "./models.js";
+export { filterByNutrition, parseNutrition } from "./nutrition.js";
+export type { FulfilmentType, OrderContext } from "./operations.js";
+export { CHECKOUT_URL, categoryFacet, ENDPOINT, FULFILMENT_TYPE, PENDING_ORDER_CONTEXTS, PUBLIC_API_KEY, } from "./operations.js";
+export { FileTokenStore } from "./store/file-store.js";
+export { MemoryTokenStore } from "./store/memory-store.js";
+export type { TokenStore } from "./store/types.js";

package/dist/index.js

@@ -0,0 +1,13 @@
+// Public API surface. Everything exported here is part of the semver contract;
+// internal modules (transport, queries, parsers, session-manager) are not.
+export { keepCookie, sessionFromCookies } from "./auth/harvest.js";
+export { Basketeer } from "./client.js";
+// Errors
+export { ApiKeyError, AuthExpiredError, BasketeerError, GraphQLRequestError, LineRejectedError, NotFoundError, RateLimitedError, } from "./errors.js";
+// Nutrition
+export { filterByNutrition, parseNutrition } from "./nutrition.js";
+// Config & helpers
+export { CHECKOUT_URL, categoryFacet, ENDPOINT, FULFILMENT_TYPE, PENDING_ORDER_CONTEXTS, PUBLIC_API_KEY, } from "./operations.js";
+// Storage seam
+export { FileTokenStore } from "./store/file-store.js";
+export { MemoryTokenStore } from "./store/memory-store.js";

package/dist/jwt.d.ts

@@ -0,0 +1,2 @@
+/** Decode a JWT's `exp` (seconds) into epoch ms, or undefined if not a JWT. */
+export declare function jwtExpiryMs(token: string): number | undefined;