basketeer 0.1.0

package/dist/jwt.js

@@ -0,0 +1,13 @@
+/** Decode a JWT's `exp` (seconds) into epoch ms, or undefined if not a JWT. */
+export function jwtExpiryMs(token) {
+    const parts = token.split(".");
+    if (parts.length !== 3)
+        return undefined;
+    try {
+        const payload = JSON.parse(Buffer.from(parts[1], "base64url").toString("utf8"));
+        return typeof payload.exp === "number" ? payload.exp * 1000 : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/mcp-server.d.ts

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+/**
+ * basketeer MCP server (stdio).
+ *
+ * Exposes the SDK as Model Context Protocol tools so an MCP agent (Claude
+ * Desktop, etc.) can browse the catalogue, fill a basket, and prepare checkout.
+ *
+ * The client is built with a `FileTokenStore` + `BrowserAuthBackend`:
+ *   - Reads (search/product/favourites/slots/orders) work anonymously.
+ *   - Authed ops reuse whatever session was saved to
+ *     `~/.basketeer/session.json` (mint one with the SDK's login flow).
+ *
+ * Import safety: building the client (which reads the session file from disk)
+ * and connecting the transport happen ONLY when this file is run as the entry
+ * point — importing the module has no filesystem/auth side effects.
+ *
+ * ETHICS CEILING: this server NEVER places or pays for an order. `basketeer_checkout`
+ * hands back the payment URL and a note that a human must complete payment in a
+ * browser (Tesco's 3-D Secure / CSRF-protected checkout is browser-bound by
+ * design). Listing/cancelling orders is fine; paying is not automated.
+ *
+ * Run: `basketeer-mcp` (stdio). Configure it as an MCP server in your agent.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { Basketeer } from "./index.js";
+/** Short deterministic token an agent must echo back to confirm a destructive action. */
+export declare function confirmToken(parts: string): string;
+/**
+ * Register every tool against the passed-in client and return the server.
+ * Pure: no filesystem/auth/transport side effects — safe to call from a test.
+ */
+export declare function buildServer(client: Basketeer): McpServer;

package/dist/mcp-server.js

@@ -0,0 +1,165 @@
+#!/usr/bin/env node
+/**
+ * basketeer MCP server (stdio).
+ *
+ * Exposes the SDK as Model Context Protocol tools so an MCP agent (Claude
+ * Desktop, etc.) can browse the catalogue, fill a basket, and prepare checkout.
+ *
+ * The client is built with a `FileTokenStore` + `BrowserAuthBackend`:
+ *   - Reads (search/product/favourites/slots/orders) work anonymously.
+ *   - Authed ops reuse whatever session was saved to
+ *     `~/.basketeer/session.json` (mint one with the SDK's login flow).
+ *
+ * Import safety: building the client (which reads the session file from disk)
+ * and connecting the transport happen ONLY when this file is run as the entry
+ * point — importing the module has no filesystem/auth side effects.
+ *
+ * ETHICS CEILING: this server NEVER places or pays for an order. `basketeer_checkout`
+ * hands back the payment URL and a note that a human must complete payment in a
+ * browser (Tesco's 3-D Secure / CSRF-protected checkout is browser-bound by
+ * design). Listing/cancelling orders is fine; paying is not automated.
+ *
+ * Run: `basketeer-mcp` (stdio). Configure it as an MCP server in your agent.
+ */
+import { createHash } from "node:crypto";
+import { fileURLToPath } from "node:url";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { BrowserAuthBackend } from "./auth/browser/playwright.js";
+import { Basketeer, BasketeerError, FileTokenStore } from "./index.js";
+/** Wrap a value as MCP JSON text content. */
+function json(value) {
+    return { content: [{ type: "text", text: JSON.stringify(value, null, 2) }] };
+}
+/** Run a tool body, mapping SDK errors to a clean MCP error result. */
+async function run(fn) {
+    try {
+        return json(await fn());
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        const kind = err instanceof BasketeerError ? err.name : "Error";
+        return {
+            isError: true,
+            content: [{ type: "text", text: JSON.stringify({ error: kind, message }, null, 2) }],
+        };
+    }
+}
+/** Short deterministic token an agent must echo back to confirm a destructive action. */
+export function confirmToken(parts) {
+    return createHash("sha256").update(parts).digest("hex").slice(0, 8);
+}
+/**
+ * Register every tool against the passed-in client and return the server.
+ * Pure: no filesystem/auth/transport side effects — safe to call from a test.
+ */
+export function buildServer(client) {
+    const server = new McpServer({ name: "basketeer", version: "0.1.0" });
+    // --- reads (anonymous OK) -------------------------------------------------
+    server.tool("basketeer_search", "Search the Tesco grocery catalogue. Returns matching products with SKU, title, price, and any offers.", {
+        query: z.string().describe("Search terms, e.g. 'semi skimmed milk'."),
+        limit: z.number().int().positive().optional(),
+    }, { readOnlyHint: true }, ({ query, limit }) => run(() => client.search(query, { limit })));
+    server.tool("basketeer_product", "Fetch one product by SKU (tpnc), including price, pack size, promotions, and nutrition.", { sku: z.string().describe("The product SKU (tpnc), e.g. from a search result.") }, { readOnlyHint: true }, ({ sku }) => run(() => client.getProduct(sku)));
+    server.tool("basketeer_favourites", "List the signed-in customer's favourites ('my usuals'). Requires a saved session.", { limit: z.number().int().positive().optional() }, { readOnlyHint: true }, ({ limit }) => run(() => client.favourites({ limit })));
+    server.tool("basketeer_nutrition", "Normalized nutrition (typed macros + micros) for a product by SKU.", { sku: z.string().describe("The product SKU (tpnc).") }, { readOnlyHint: true }, ({ sku }) => run(() => client.getProduct(sku).then((p) => p.nutrition)));
+    server.tool("basketeer_search_by_nutrition", "Search products by keyword, then filter/rank by nutrition (per 100g/ml). " +
+        "Hydrates each candidate with a throttled product fetch; bounded by `hydrate`.", {
+        query: z.string().describe("Search terms, e.g. 'greek yogurt'."),
+        minProtein: z.number().optional().describe("Minimum protein (g per 100g/ml)."),
+        maxSugar: z.number().optional().describe("Maximum sugars (g per 100g/ml)."),
+        sortBy: z.string().optional().describe("Macro to sort by descending, e.g. 'protein'."),
+        hydrate: z
+            .number()
+            .int()
+            .positive()
+            .optional()
+            .describe("Max candidates to fetch nutrition for (default 20)."),
+        limit: z
+            .number()
+            .int()
+            .positive()
+            .optional()
+            .describe("Max results to return after filtering."),
+    }, { readOnlyHint: true }, ({ query, minProtein, maxSugar, sortBy, hydrate, limit }) => run(() => {
+        const where = {};
+        if (minProtein != null)
+            where.protein = { min: minProtein };
+        if (maxSugar != null)
+            where.sugars = { max: maxSugar };
+        const sort = sortBy ? { by: sortBy, dir: "desc" } : undefined;
+        return client.searchByNutrition(query, { where, sort, hydrate, limit });
+    }));
+    // --- basket (requires a saved session) ------------------------------------
+    server.tool("basketeer_basket_get", "Get the current basket: line items, quantities, and guide price.", {}, { readOnlyHint: true }, () => run(() => client.basket.get()));
+    server.tool("basketeer_basket_set", "Set a SKU's basket line to an exact quantity (set-not-increment). quantity 0 removes the line.", {
+        sku: z.string().describe("The product SKU (tpnc) to set."),
+        quantity: z.number().int().nonnegative().describe("Exact quantity to set; 0 removes."),
+    }, { readOnlyHint: false, destructiveHint: true }, ({ sku, quantity }) => run(() => client.basket.set(sku, quantity)));
+    server.tool("basketeer_basket_remove", "Remove a SKU from the basket entirely.", { sku: z.string().describe("The product SKU (tpnc) to remove.") }, { readOnlyHint: false, destructiveHint: true }, ({ sku }) => run(() => client.basket.remove(sku)));
+    // --- slots (requires a saved session) -------------------------------------
+    server.tool("basketeer_slots_list", "List delivery slots over a date window (defaults to today..+6 days). Dates are YYYY-MM-DD.", {
+        start: z.string().optional().describe("Window start, YYYY-MM-DD."),
+        end: z.string().optional().describe("Window end, YYYY-MM-DD."),
+    }, { readOnlyHint: true }, ({ start, end }) => run(() => client.slots.list({ start, end })));
+    // --- orders (requires a saved session) ------------------------------------
+    server.tool("basketeer_orders_list", "List upcoming (pending) orders with their items, slot, and amend window.", {}, { readOnlyHint: true }, () => run(() => client.orders.list()));
+    server.tool("basketeer_orders_cancel", "Cancel an upcoming order outright (only before its amend/cancel cutoff). " +
+        "Two-step: call once with just orderNo to get a confirmToken and a preview; " +
+        "call again with confirm set to that token to actually cancel. Cancelling is irreversible.", { orderNo: z.string().describe("The order number to cancel."), confirm: z.string().optional() }, { readOnlyHint: false, destructiveHint: true }, ({ orderNo, confirm }) => run(async () => {
+        const token = confirmToken(`cancel:${orderNo}`);
+        if (confirm !== token) {
+            return {
+                requiresConfirmation: true,
+                action: "cancel_order",
+                orderNo,
+                confirmToken: token,
+                hint: "Cancelling is irreversible. Call again with confirm set to this confirmToken to proceed.",
+            };
+        }
+        await client.orders.cancel(orderNo);
+        return { ok: true, cancelled: orderNo };
+    }));
+    server.tool("basketeer_last_order", "Return the last delivered (fulfilled) order and its items, e.g. for 'reorder my usual shop'. " +
+        "Returns null if there is none. This is a read — to reorder, add its items via basketeer_basket_set.", {}, { readOnlyHint: true }, () => run(() => client.orders.lastFulfilled()));
+    // --- checkout (boundary: stops at the payment URL) ------------------------
+    server.tool("basketeer_checkout", "Prepare checkout: returns the current basket and the URL where a HUMAN completes payment in a browser. " +
+        "This server never places or pays for an order — Tesco's 3-D Secure payment step is browser-bound by design. " +
+        "Two-step: call once with no args to preview the basket and get a confirmToken; " +
+        "call again with confirm set to that token to get the payment URL for the human to complete.", { confirm: z.string().optional() }, { readOnlyHint: false, destructiveHint: true }, ({ confirm }) => run(async () => {
+        const basket = await client.basket.get();
+        const signature = `${basket.items.length}:${basket.guidePrice ?? ""}`;
+        const token = confirmToken(`checkout:${signature}`);
+        if (confirm !== token) {
+            return {
+                requiresConfirmation: true,
+                action: "checkout",
+                basket,
+                confirmToken: token,
+                hint: "Checkout returns the current basket and a payment URL for a human to complete in a browser. Call again with confirm set to this confirmToken to proceed.",
+            };
+        }
+        const { basket: cart, url } = await client.checkout();
+        return {
+            basket: cart,
+            paymentUrl: url,
+            note: "Payment is NOT automated. Open paymentUrl in a browser and complete payment (card + 3-D Secure) yourself.",
+        };
+    }));
+    return server;
+}
+// --- start ------------------------------------------------------------------
+// Only build the client (which reads ~/.basketeer/session.json) and attach the
+// stdio transport when run as a binary, so the module can be imported (e.g. by a
+// smoke test) without any filesystem/auth side effects or starting the server.
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+    const store = new FileTokenStore();
+    const client = new Basketeer({
+        session: await store.load(),
+        store,
+        authBackend: new BrowserAuthBackend(),
+    });
+    const server = buildServer(client);
+    await server.connect(new StdioServerTransport());
+}

package/dist/models.d.ts

@@ -0,0 +1,181 @@
+/** Typed domain models. Raw GraphQL nodes are kept on `.raw` for escape hatches. */
+export interface Price {
+    actual: number | null;
+    unitPrice: number | null;
+    unitOfMeasure: string | null;
+}
+export interface Promotion {
+    description: string;
+    startDate: string | null;
+    endDate: string | null;
+    attributes: string[];
+    priceAfterDiscount: number | null;
+    priceBeforeDiscount: number | null;
+}
+export interface PackSize {
+    value: number;
+    units: string;
+}
+export interface Product {
+    /** tpnc — the SKU used for product lookup and basket ops. */
+    sku: string;
+    tpnb: string | null;
+    title: string;
+    brand: string | null;
+    price: Price;
+    packSize: PackSize | null;
+    promotions: Promotion[];
+    /** Normalized nutrition, or null if Tesco returned none / it was unparseable. */
+    nutrition: Nutrition | null;
+    /** Convenience mirror of `nutrition?.macros`. */
+    macros: Macros | null;
+    raw: unknown;
+}
+export interface SearchResult {
+    sku: string;
+    tpnb: string | null;
+    title: string;
+    brand: string | null;
+    price: Price;
+    onOffer: boolean;
+    promotions: Promotion[];
+}
+/** A page of product results, with the signal needed to page reliably. */
+export interface SearchPage {
+    results: SearchResult[];
+    page: number;
+    pageSize: number;
+    /** True if the server returned a full page (more may exist). */
+    hasMore: boolean;
+}
+export interface BasketLine {
+    id: string;
+    sku: string | null;
+    quantity: number;
+    unit: string | null;
+    cost: number | null;
+}
+export interface Basket {
+    id: string | null;
+    guidePrice: number | null;
+    isInAmend: boolean;
+    /** ISO time the amend window closes (when `isInAmend`), else null. */
+    amendExpiry: string | null;
+    shoppingMethod: string | null;
+    items: BasketLine[];
+    raw: unknown;
+}
+export interface Slot {
+    /** Opaque slot id — pass to slots.book(). */
+    id: string;
+    start: string;
+    end: string;
+    /** Delivery charge for this slot, or null. */
+    charge: number | null;
+    /** e.g. "Available" / "UnAvailable" / "Booked". */
+    status: string;
+    group: number | null;
+    priceBeforeDiscount: number | null;
+    priceAfterDiscount: number | null;
+    locationUuid: string | null;
+}
+export interface BookedSlot {
+    id: string;
+    status: string;
+    start: string;
+    end: string;
+    /** When the reservation lapses if you don't check out. */
+    reservationExpiry: string | null;
+    group: number | null;
+    locationUuid: string | null;
+}
+export interface OrderItem {
+    id: string;
+    quantity: number;
+    unit: string | null;
+    weight: number | null;
+    productId: string | null;
+    title: string;
+}
+export interface OrderSlot {
+    id: string | null;
+    start: string | null;
+    end: string | null;
+    charge: number | null;
+}
+export interface OrderAddress {
+    name: string | null;
+    city: string | null;
+    addressLine1: string | null;
+    postcode: string | null;
+}
+export interface Order {
+    id: string;
+    orderNo: string;
+    status: string;
+    totalPrice: number | null;
+    totalItems: number | null;
+    /** True while the order is open for amendment. */
+    isInAmend: boolean;
+    /** ISO time after which the order can no longer be amended/cancelled. */
+    amendExpiry: string | null;
+    shoppingMethod: string | null;
+    slot: OrderSlot | null;
+    address: OrderAddress | null;
+    items: OrderItem[];
+    raw: unknown;
+}
+/**
+ * An authenticated session. For the browser-minted hybrid (v1), `accessToken`
+ * is the harvested `OAuth.AccessToken` bearer and `customerUuid` is the `UUID`
+ * cookie. `cookies` carries the tesco.com cookies replayed on writes (auth +
+ * Akamai bot-mitigation cookies). Renewal is performed by the AuthBackend.
+ */
+export interface Session {
+    accessToken: string;
+    customerUuid: string;
+    cookies: Record<string, string>;
+    /** epoch ms; parsed from the JWT `exp` when available, else undefined. */
+    accessTokenExpiry?: number;
+}
+export type NutritionBasis = "per_100g" | "per_100ml" | "per_serving" | "unknown";
+export interface Macros {
+    energyKcal: number | null;
+    energyKj: number | null;
+    protein: number | null;
+    fat: number | null;
+    saturates: number | null;
+    carbs: number | null;
+    sugars: number | null;
+    fibre: number | null;
+    salt: number | null;
+}
+export interface Micronutrient {
+    name: string;
+    amount: number | null;
+    unit: string | null;
+    nrvPercent: number | null;
+}
+export interface Nutrition {
+    basis: NutritionBasis;
+    macros: Macros;
+    micros: Micronutrient[];
+    raw: unknown[];
+}
+export interface Range {
+    min?: number;
+    max?: number;
+}
+/** Macro fields that can be filtered/sorted on. Excludes energyKj (use energyKcal). */
+export type MacroFilterKey = "energyKcal" | "protein" | "fat" | "saturates" | "carbs" | "sugars" | "fibre" | "salt";
+export type NutritionFilter = Partial<Record<MacroFilterKey, Range>> & {
+    micro?: {
+        name: string;
+        min?: number;
+        max?: number;
+    }[];
+};
+export interface NutritionSort {
+    by: MacroFilterKey | (string & {});
+    dir?: "asc" | "desc";
+}

package/dist/models.js

@@ -0,0 +1,2 @@
+/** Typed domain models. Raw GraphQL nodes are kept on `.raw` for escape hatches. */
+export {};

package/dist/nutrition.d.ts

@@ -0,0 +1,7 @@
+import type { Nutrition, NutritionBasis, NutritionFilter, NutritionSort, Product } from "./models.js";
+export declare function parseNutrition(rows: unknown[]): Nutrition | null;
+export declare function filterByNutrition(products: Product[], opts?: {
+    where?: NutritionFilter;
+    sort?: NutritionSort;
+    basis?: NutritionBasis;
+}): Product[];

package/dist/nutrition.js

@@ -0,0 +1,194 @@
+const emptyMacros = () => ({
+    energyKcal: null,
+    energyKj: null,
+    protein: null,
+    fat: null,
+    saturates: null,
+    carbs: null,
+    sugars: null,
+    fibre: null,
+    salt: null,
+});
+/** Normalize a decimal comma between digits ("1,5" -> "1.5") so European values parse. */
+const deComma = (s) => s.replace(/(\d),(\d)/g, "$1.$2");
+/** First number in a string: "3.0 g" -> 3.0, "21.5g" -> 21.5, "3.4 g*" -> 3.4, "1,5 g" -> 1.5. */
+function num(s) {
+    if (!s)
+        return null;
+    const m = deComma(s).match(/-?\d+(?:\.\d+)?/);
+    return m ? parseFloat(m[0]) : null;
+}
+/** Unit right after the number: "1.1 µg (22%)" -> "µg", "3.0 g" -> "g". */
+function unitOf(s) {
+    const m = s.match(/-?\d+(?:\.\d+)?\s*([A-Za-zµμ]+)/);
+    return m ? (m[1] ?? null) : null;
+}
+/** NRV percent in parens: "(22%**)" -> 22. */
+function nrvOf(s) {
+    const m = deComma(s).match(/\((\d+(?:\.\d+)?)\s*%/);
+    return m ? parseFloat(m[1] ?? "0") : null;
+}
+function basisFromHeader(v) {
+    const t = v.toLowerCase();
+    if (t.includes("100 ml") || t.includes("100ml"))
+        return "per_100ml";
+    if (t.includes("100 g") || t.includes("100g"))
+        return "per_100g";
+    if (t.includes("serving"))
+        return "per_serving";
+    return "unknown";
+}
+const MACRO_LABELS = {
+    fat: "fat",
+    saturates: "saturates",
+    "of which saturates": "saturates",
+    carbohydrate: "carbs",
+    "available carbohydrate": "carbs",
+    "total carbohydrate": "carbs",
+    sugars: "sugars",
+    "of which sugars": "sugars",
+    fibre: "fibre",
+    protein: "protein",
+    salt: "salt",
+    "salt equivalent": "salt",
+};
+function isFootnote(name, value) {
+    const n = name.trim();
+    if (n.startsWith("*"))
+        return true;
+    if (/^of which$/i.test(n))
+        return true;
+    if (/^as sold$/i.test(n))
+        return true;
+    if (/reference intake|nutrient reference value/i.test(n))
+        return true;
+    const known = !!MACRO_LABELS[n.toLowerCase()] || /^energy/i.test(n);
+    if (!known && (value === "-" || value === null || value === ""))
+        return true;
+    return false;
+}
+export function parseNutrition(rows) {
+    if (!Array.isArray(rows) || rows.length === 0)
+        return null;
+    const macros = emptyMacros();
+    const micros = [];
+    let basis = "unknown";
+    let expectKcalNext = false;
+    for (const r of rows) {
+        const row = (r ?? {});
+        const name = typeof row.name === "string" ? row.name.trim() : "";
+        // Normalize a decimal comma so the energy kJ/kcal regexes (and num/nrvOf) see "1.5", not "1".
+        const value1 = typeof row.value1 === "string" ? deComma(row.value1.trim()) : null;
+        if (!name)
+            continue;
+        // Energy split across two rows: "257 kJ/" then a row whose value holds the kcal.
+        if (expectKcalNext) {
+            expectKcalNext = false;
+            if (value1 && /kcal/i.test(value1)) {
+                macros.energyKcal = num(value1.match(/(\d+(?:\.\d+)?)\s*kcal/i)?.[0] ?? null);
+                continue;
+            }
+            // not a kcal continuation — fall through and process normally
+        }
+        // Header row → basis
+        if (/typical values/i.test(name) || (value1 && /per\s*100|per\s*serving/i.test(value1))) {
+            if (value1)
+                basis = basisFromHeader(value1);
+            continue;
+        }
+        // Energy (inline "486kJ / 115kcal" or split "257 kJ/")
+        if (/^energy/i.test(name)) {
+            if (value1) {
+                const kj = value1.match(/(\d+(?:\.\d+)?)\s*kj/i);
+                const kcal = value1.match(/(\d+(?:\.\d+)?)\s*kcal/i);
+                if (kj)
+                    macros.energyKj = parseFloat(kj[1] ?? "0");
+                if (kcal)
+                    macros.energyKcal = parseFloat(kcal[1] ?? "0");
+                if (kj && !kcal)
+                    expectKcalNext = true;
+            }
+            continue;
+        }
+        if (isFootnote(name, value1))
+            continue;
+        const key = MACRO_LABELS[name.toLowerCase()];
+        if (key) {
+            macros[key] = num(value1);
+            continue;
+        }
+        // Anything else with a value is a micronutrient.
+        if (value1) {
+            micros.push({ name, amount: num(value1), unit: unitOf(value1), nrvPercent: nrvOf(value1) });
+        }
+    }
+    return { basis, macros, micros, raw: rows };
+}
+const MACRO_FILTER_KEYS = [
+    "energyKcal",
+    "protein",
+    "fat",
+    "saturates",
+    "carbs",
+    "sugars",
+    "fibre",
+    "salt",
+];
+function inRange(v, r) {
+    if (!r)
+        return true;
+    if (v == null)
+        return false;
+    if (r.min != null && v < r.min)
+        return false;
+    if (r.max != null && v > r.max)
+        return false;
+    return true;
+}
+function sortValue(p, by) {
+    const n = p.nutrition;
+    if (MACRO_FILTER_KEYS.includes(by))
+        return n?.macros?.[by] ?? null;
+    const micro = n?.micros.find((x) => x.name.toLowerCase() === by.toLowerCase());
+    return micro?.amount ?? null;
+}
+export function filterByNutrition(products, opts = {}) {
+    const { where, sort, basis } = opts;
+    const usesNutrition = !!where || !!sort;
+    let out = usesNutrition ? products.filter((p) => p.nutrition) : [...products];
+    if (usesNutrition) {
+        const target = basis ?? out.find((p) => p.nutrition)?.nutrition?.basis;
+        if (target)
+            out = out.filter((p) => p.nutrition?.basis === target);
+    }
+    if (where) {
+        out = out.filter((p) => {
+            const m = p.nutrition.macros;
+            for (const k of MACRO_FILTER_KEYS) {
+                if (where[k] && !inRange(m[k], where[k]))
+                    return false;
+            }
+            for (const mc of where.micro ?? []) {
+                const found = p.nutrition.micros.find((x) => x.name.toLowerCase() === mc.name.toLowerCase());
+                if (!inRange(found?.amount ?? null, { min: mc.min, max: mc.max }))
+                    return false;
+            }
+            return true;
+        });
+    }
+    if (sort) {
+        const dir = sort.dir === "asc" ? 1 : -1;
+        out = [...out].sort((a, b) => {
+            const av = sortValue(a, String(sort.by));
+            const bv = sortValue(b, String(sort.by));
+            if (av == null && bv == null)
+                return 0;
+            if (av == null)
+                return 1;
+            if (bv == null)
+                return -1;
+            return (av - bv) * dir;
+        });
+    }
+    return out;
+}

package/dist/operations.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Config, constants, and small public helpers. GraphQL query strings are
+ * internal and live in queries.ts.
+ *
+ * The api key is public (baked into Tesco's web JS) and rotates roughly monthly
+ * — override via the `TESCO_API_KEY` env var or the client `apiKey` option.
+ */
+export declare const PUBLIC_API_KEY = "TvOSZJHlEk0pjniDGQFAc9Q59WGAR4dA";
+export declare const ENDPOINT = "https://xapi.tesco.com/";
+/**
+ * The Tesco order-summary / payment page. Payment is completed HERE in a browser
+ * — a separate CSRF-protected checkout app + 3-D Secure card authentication
+ * (browser-bound by design, PCI/fraud-sensitive), deliberately NOT part of the
+ * pure-HTTP API. Fill the basket + book a slot via this SDK, then finish here.
+ */
+export declare const CHECKOUT_URL = "https://www.tesco.com/checkout/en-GB/groceries/order-summary?basketType=GROCERY";
+/** Micro-frontend tags Tesco's own client sends per operation. Internal. */
+export declare const MFE: {
+    readonly product: "mfe-pdp";
+    readonly search: "mfe-plp";
+    readonly basket: "mfe-basket";
+    readonly slots: "mfe-slots";
+    readonly orders: "mfe-orders";
+    readonly favourites: "mfe-favourites";
+};
+/** One context for `orders.list` — an order type plus the statuses to include. */
+export interface OrderContext {
+    type: string;
+    statuses: readonly string[];
+}
+/** Default contexts for listing upcoming (pending) orders across order types. */
+export declare const PENDING_ORDER_CONTEXTS: readonly OrderContext[];
+/** Fulfilment method types accepted by the slot ops. */
+export declare const FULFILMENT_TYPE: {
+    readonly delivery: "DELIVERY_VAN";
+    readonly collection: "COLLECTION_STORE";
+};
+export type FulfilmentType = (typeof FULFILMENT_TYPE)[keyof typeof FULFILMENT_TYPE];
+/**
+ * Build a category `facet` for {@link Basketeer.browseCategory} from a
+ * department name. Tesco encodes it as `"b;" + base64(name)` — e.g.
+ * `categoryFacet("Fresh Food")`. Uses the cross-runtime `btoa` (works in Node,
+ * Bun, Deno, browsers, workers). You can also lift a `facet` straight from a
+ * Tesco category-page URL (`?...&facet=…`).
+ */
+export declare function categoryFacet(department: string): string;