basketeer 0.1.0

package/dist/operations.js

@@ -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 const PUBLIC_API_KEY = "TvOSZJHlEk0pjniDGQFAc9Q59WGAR4dA";
+export 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 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 const MFE = {
+    product: "mfe-pdp",
+    search: "mfe-plp",
+    basket: "mfe-basket",
+    slots: "mfe-slots",
+    orders: "mfe-orders",
+    favourites: "mfe-favourites",
+};
+/** Default contexts for listing upcoming (pending) orders across order types. */
+export const PENDING_ORDER_CONTEXTS = [
+    { type: "GROCERY", statuses: ["Pending"] },
+    { type: "MARKETPLACE", statuses: ["Pending"] },
+    { type: "FNF", statuses: ["Pending"] },
+];
+/** Fulfilment method types accepted by the slot ops. */
+export const FULFILMENT_TYPE = {
+    delivery: "DELIVERY_VAN",
+    collection: "COLLECTION_STORE",
+};
+/**
+ * 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 function categoryFacet(department) {
+    return `b;${btoa(department)}`;
+}

package/dist/parsers.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Raw GraphQL → typed model parsers. Kept separate from the client so they can
+ * be unit-tested against captured fixtures, and so the orchestration stays lean.
+ *
+ * Tesco's GraphQL shape drifts (the public api key rotates ~monthly), so every
+ * parser is defensive: it reads untrusted `unknown`, narrows with small
+ * accessors, tolerates nulls/missing fields, and never throws on a sparse array.
+ */
+import type { Basket, BookedSlot, Order, Product, Promotion, SearchResult, Slot } from "./models.js";
+/** A decoded-JSON object whose fields are still untrusted. */
+export type Raw = Record<string, unknown>;
+export declare function parsePromotions(v: unknown): Promotion[];
+export declare function parseProduct(v: unknown): Product;
+/**
+ * Map a ProductInterface node (search / category / favourites) to a SearchResult,
+ * or `null` for non-product union members and nodes without a `tpnc` (callers
+ * filter these out rather than fabricating an `"undefined"` SKU).
+ */
+export declare function parseProductNode(v: unknown): SearchResult | null;
+export declare function parseBasket(v: unknown): Basket;
+export declare function parseSlot(v: unknown): Slot;
+export declare function parseBookedSlot(v: unknown): BookedSlot;
+export declare function parseOrder(v: unknown): Order;
+/** YYYY-MM-DD `offsetDays` from today, in LOCAL time (Tesco slot dates are UK-local). */
+export declare function isoDate(offsetDays?: number): string;

package/dist/parsers.js

@@ -0,0 +1,167 @@
+import { parseNutrition } from "./nutrition.js";
+const obj = (v) => (v !== null && typeof v === "object" ? v : {});
+const arr = (v) => (Array.isArray(v) ? v : []);
+/** Array of objects, with null/non-object elements dropped. */
+const objs = (v) => arr(v).filter((x) => x !== null && typeof x === "object");
+const str = (v) => (typeof v === "string" ? v : null);
+const num = (v) => (typeof v === "number" && Number.isFinite(v) ? v : null);
+const id = (v) => (v == null ? null : String(v));
+function parsePrice(v) {
+    const p = obj(v);
+    return {
+        actual: num(p.actual),
+        unitPrice: num(p.unitPrice),
+        unitOfMeasure: str(p.unitOfMeasure),
+    };
+}
+export function parsePromotions(v) {
+    return objs(v).map((p) => {
+        const price = obj(p.price);
+        return {
+            description: str(p.description) ?? "",
+            startDate: str(p.startDate),
+            endDate: str(p.endDate),
+            attributes: arr(p.attributes).filter((a) => typeof a === "string"),
+            priceAfterDiscount: num(price.afterDiscount),
+            priceBeforeDiscount: num(price.beforeDiscount),
+        };
+    });
+}
+function parsePackSize(v) {
+    const first = Array.isArray(v) ? v[0] : v;
+    const p = obj(first);
+    const units = str(p.units);
+    const value = Number(p.value); // Tesco sends packSize.value as a numeric string
+    return units && Number.isFinite(value) ? { value, units } : null;
+}
+export function parseProduct(v) {
+    const node = obj(v);
+    const details = obj(node.details);
+    const nutrition = parseNutrition(arr(details.nutrition));
+    return {
+        sku: id(node.tpnc) ?? "",
+        tpnb: id(node.tpnb),
+        title: str(node.title) ?? "",
+        brand: str(node.brandName),
+        price: parsePrice(node.price),
+        packSize: parsePackSize(details.packSize),
+        promotions: parsePromotions(node.promotions),
+        nutrition,
+        macros: nutrition?.macros ?? null,
+        raw: v,
+    };
+}
+/**
+ * Map a ProductInterface node (search / category / favourites) to a SearchResult,
+ * or `null` for non-product union members and nodes without a `tpnc` (callers
+ * filter these out rather than fabricating an `"undefined"` SKU).
+ */
+export function parseProductNode(v) {
+    const node = obj(v);
+    if (node.tpnc == null)
+        return null;
+    const seller = obj(arr(obj(node.sellers).results)[0]);
+    const promotions = parsePromotions(seller.promotions);
+    return {
+        sku: String(node.tpnc),
+        tpnb: id(node.tpnb),
+        title: str(node.title) ?? "",
+        brand: str(node.brandName),
+        price: parsePrice(seller.price),
+        onOffer: promotions.length > 0,
+        promotions,
+    };
+}
+export function parseBasket(v) {
+    const node = obj(v);
+    const items = objs(node.items).map((it) => ({
+        id: id(it.id) ?? "",
+        sku: id(obj(it.product).id),
+        quantity: num(it.quantity) ?? 0,
+        unit: str(it.unit),
+        cost: num(it.cost),
+    }));
+    return {
+        id: id(node.id),
+        guidePrice: num(node.guidePrice),
+        isInAmend: Boolean(node.isInAmend),
+        amendExpiry: str(node.amendExpiry),
+        shoppingMethod: str(node.shoppingMethod),
+        items,
+        raw: v ?? null,
+    };
+}
+export function parseSlot(v) {
+    const node = obj(v);
+    const price = obj(node.price);
+    return {
+        id: id(node.id) ?? "",
+        start: str(node.start) ?? "",
+        end: str(node.end) ?? "",
+        charge: num(node.charge),
+        status: str(node.status) ?? "",
+        group: num(node.group),
+        priceBeforeDiscount: num(price.beforeDiscount),
+        priceAfterDiscount: num(price.afterDiscount),
+        locationUuid: id(node.locationUuid),
+    };
+}
+export function parseBookedSlot(v) {
+    const node = obj(v);
+    return {
+        id: id(node.id) ?? "",
+        status: str(node.status) ?? "",
+        start: str(node.start) ?? "",
+        end: str(node.end) ?? "",
+        reservationExpiry: str(node.reservationExpiry),
+        group: num(node.group),
+        locationUuid: id(node.locationUuid),
+    };
+}
+export function parseOrder(v) {
+    const node = obj(v);
+    const slot = obj(node.slot);
+    const addr = obj(node.address);
+    const items = objs(node.items).map((it) => {
+        const product = obj(it.product);
+        return {
+            id: id(it.id) ?? "",
+            quantity: num(it.quantity) ?? 0,
+            unit: str(it.unit),
+            weight: num(it.weight),
+            productId: id(product.id),
+            title: str(product.title) ?? "",
+        };
+    });
+    return {
+        id: id(node.id) ?? "",
+        orderNo: id(node.orderNo) ?? "",
+        status: str(node.status) ?? "",
+        totalPrice: num(node.totalPrice),
+        totalItems: num(node.totalItems),
+        isInAmend: Boolean(node.isInAmend),
+        amendExpiry: str(node.amendExpiryTime),
+        shoppingMethod: str(node.shoppingMethod),
+        slot: node.slot
+            ? { id: id(slot.id), start: str(slot.start), end: str(slot.end), charge: num(slot.charge) }
+            : null,
+        address: node.address
+            ? {
+                name: str(addr.name),
+                city: str(addr.city),
+                addressLine1: str(addr.addressLine1),
+                postcode: str(addr.postcode),
+            }
+            : null,
+        items,
+        raw: v,
+    };
+}
+/** YYYY-MM-DD `offsetDays` from today, in LOCAL time (Tesco slot dates are UK-local). */
+export function isoDate(offsetDays = 0) {
+    const d = new Date();
+    d.setDate(d.getDate() + offsetDays);
+    const m = String(d.getMonth() + 1).padStart(2, "0");
+    const day = String(d.getDate()).padStart(2, "0");
+    return `${d.getFullYear()}-${m}-${day}`;
+}

package/dist/queries.d.ts

@@ -0,0 +1,18 @@
+/**
+ * GraphQL operation strings for `xapi.tesco.com`, ported from observed traffic.
+ * Internal — not part of the public API. Config/constants live in operations.ts.
+ */
+export declare const GET_PRODUCT: string;
+export declare const SEARCH: string;
+export declare const GET_CATEGORY_PRODUCTS: string;
+export declare const GET_FAVOURITES: string;
+export declare const GET_BASKET: string;
+export declare const UPDATE_BASKET: string;
+export declare const GET_UPCOMING_ORDERS: string;
+export declare const AMEND_ORDER: string;
+export declare const CANCEL_ORDER: string;
+export declare const CANCEL_AMEND: string;
+export declare const GET_LAST_FULFILLED_ORDER: string;
+export declare const DELIVERY_SLOTS: string;
+export declare const COLLECTION_SLOTS: string;
+export declare const FULFILMENT: string;

package/dist/queries.js

@@ -0,0 +1,235 @@
+/**
+ * GraphQL operation strings for `xapi.tesco.com`, ported from observed traffic.
+ * Internal — not part of the public API. Config/constants live in operations.ts.
+ */
+export const GET_PRODUCT = `
+query GetProduct($tpnc: String!) {
+  product(tpnc: $tpnc) {
+    tpnb tpnc title brandName
+    price { actual unitPrice unitOfMeasure }
+    promotions {
+      description
+      startDate
+      endDate
+      attributes
+      price { afterDiscount beforeDiscount }
+    }
+    details {
+      packSize { value units }
+      nutrition { name value1 value2 value3 }
+      ingredients
+    }
+  }
+}`.trim();
+export const SEARCH = `
+query Search($query: String!, $page: Int = 1, $count: Int) {
+  search(query: $query, page: $page, count: $count) {
+    results {
+      node {
+        __typename
+        ... on ProductInterface {
+          tpnc tpnb title brandName
+          sellers {
+            results {
+              price { actual unitPrice unitOfMeasure }
+              promotions {
+                description
+                startDate
+                endDate
+                attributes
+                price { afterDiscount beforeDiscount }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}`.trim();
+export const GET_CATEGORY_PRODUCTS = `
+query GetCategoryProducts($facet: ID, $page: Int = 1, $count: Int) {
+  category(facet: $facet, page: $page, count: $count) {
+    results {
+      node {
+        __typename
+        ... on ProductInterface {
+          tpnc tpnb title brandName
+          sellers {
+            results {
+              price { actual unitPrice unitOfMeasure }
+              promotions { description startDate endDate attributes price { afterDiscount beforeDiscount } }
+            }
+          }
+        }
+      }
+    }
+  }
+}`.trim();
+export const GET_FAVOURITES = `
+query GetFavourites($page: Int = 1, $count: Int, $sortBy: String) {
+  favourites(page: $page, count: $count, sortBy: $sortBy) {
+    products {
+      __typename
+      ... on ProductInterface {
+        tpnc tpnb title brandName
+        sellers {
+          results {
+            price { actual unitPrice unitOfMeasure }
+            promotions { description startDate endDate attributes price { afterDiscount beforeDiscount } }
+          }
+        }
+      }
+    }
+  }
+}`.trim();
+export const GET_BASKET = `
+query GetBasket {
+  basket {
+    id
+    guidePrice
+    isInAmend
+    amendExpiry
+    shoppingMethod
+    items {
+      __typename
+      id
+      unit
+      weight
+      cost
+      quantity
+      product { id __typename }
+    }
+  }
+}`.trim();
+// Selects the same fields as GET_BASKET so the Basket returned from a write has
+// full fidelity (guidePrice / isInAmend / amendExpiry / unit / weight), not a
+// partial object.
+export const UPDATE_BASKET = `
+mutation UpdateBasket($items: [BasketLineItemInputType], $orderId: ID) {
+  basket(items: $items, orderId: $orderId) {
+    id
+    guidePrice
+    isInAmend
+    amendExpiry
+    shoppingMethod
+    items {
+      __typename
+      id
+      unit
+      weight
+      cost
+      quantity
+      product { id __typename }
+    }
+    updates {
+      items { id successful __typename }
+    }
+  }
+}`.trim();
+// ---- orders ----------------------------------------------------------------
+export const GET_UPCOMING_ORDERS = `
+query GetUpcomingOrders($orderContexts: [OrderContextType]) {
+  orderSearch(orderContexts: $orderContexts) {
+    orders {
+      id
+      orderNo
+      status
+      totalPrice
+      totalItems
+      isInAmend
+      amendExpiryTime
+      shoppingMethod
+      paymentMode
+      slot { id start end charge }
+      address { name city addressLine1 postcode }
+      items { id quantity unit weight product { id title } }
+    }
+  }
+}`.trim();
+// One unified mutation drives the order lifecycle: action ∈ AMEND | CANCEL | CANCEL_AMEND.
+export const AMEND_ORDER = `
+mutation AmendOrder($orderNo: ID!) {
+  order(orderNo: $orderNo, action: AMEND) { id orderNo }
+}`.trim();
+export const CANCEL_ORDER = `
+mutation CancelOrder($orderNo: ID!) {
+  order(orderNo: $orderNo, action: CANCEL) { id }
+}`.trim();
+export const CANCEL_AMEND = `
+mutation CancelAmend($orderNo: ID!) {
+  order(orderNo: $orderNo, action: CANCEL_AMEND) { id orderNo }
+  basket { id isInAmend amendExpiry }
+}`.trim();
+// Last delivered order — the source for "reorder my usual shop".
+export const GET_LAST_FULFILLED_ORDER = `
+query GetLastFulfilledOrder($status: OrderStatusInputType) {
+  order(status: $status) {
+    orderNo
+    items { id quantity unit weight product { id title } }
+  }
+}`.trim();
+// ---- slots -----------------------------------------------------------------
+export const DELIVERY_SLOTS = `
+query DeliverySlots($start: String, $end: String, $group: Int, $type: FulfilmentTypeType) {
+  delivery(start: $start, end: $end, group: $group) {
+    ...Slot
+    __typename
+  }
+  fulfilment(type: $type, range: {start: $start, end: $end}) {
+    ...Fulfilment
+    __typename
+  }
+}
+
+fragment Slot on SlotInterface {
+  id
+  start
+  end
+  charge
+  status
+  group
+  price {
+    beforeDiscount
+    afterDiscount
+    __typename
+  }
+  locationUuid
+  __typename
+}
+
+fragment Fulfilment on FulfilmentType {
+  fulfilmentLocation {
+    locationUuid
+    __typename
+  }
+  metadata {
+    preBookedOrderDays
+    __typename
+  }
+  __typename
+}`.trim();
+export const COLLECTION_SLOTS = `
+query CollectionSlots($start: String, $end: String, $locationUuid: ID) {
+  collection(start: $start, end: $end, locationUuid: $locationUuid) {
+    id start end charge status group locationUuid
+    price { beforeDiscount afterDiscount }
+  }
+}`.trim();
+// Reserve (action "BOOK") or release (action "UNBOOK") a slot by its id.
+// `action` mirrors the server's `SlotActions` enum.
+export const FULFILMENT = `
+mutation Fulfilment($slotId: ID, $action: SlotActions) {
+  fulfilment(slotId: $slotId, action: $action) {
+    slot {
+      id
+      status
+      start
+      end
+      reservationExpiry
+      group
+      locationUuid
+      __typename
+    }
+    __typename
+  }
+}`.trim();

package/dist/session-manager.d.ts

@@ -0,0 +1,31 @@
+import type { AuthBackend } from "./auth/types.js";
+import type { AuthHeaders } from "./graphql.js";
+import type { Session } from "./models.js";
+import type { TokenStore } from "./store/types.js";
+export interface SessionManagerOptions {
+    session?: Session | null;
+    backend?: AuthBackend;
+    store?: TokenStore;
+}
+/**
+ * Owns the auth lifecycle: holds the current {@link Session}, serialises it
+ * into request headers, and renews it on demand (proactively or lazily on a
+ * 401) via the {@link AuthBackend}, persisting through the {@link TokenStore}.
+ */
+export declare class SessionManager {
+    private session;
+    private readonly backend?;
+    private readonly store?;
+    constructor(opts?: SessionManagerOptions);
+    /** Load any persisted session from the store into the manager. */
+    load(): Promise<Session | null>;
+    get current(): Session | null;
+    setSession(session: Session): Promise<void>;
+    /** True when there is no session or the access token is within `skewMs` of expiry. */
+    isExpired(skewMs?: number): boolean;
+    /** Build the auth headers for a write, or undefined when anonymous. */
+    authHeaders(): AuthHeaders | undefined;
+    /** Renew via the backend. Returns false if renewal is impossible. */
+    refresh(): Promise<boolean>;
+    login(...args: Parameters<AuthBackend["login"]>): Promise<Session>;
+}

package/dist/session-manager.js

@@ -0,0 +1,70 @@
+import { jwtExpiryMs } from "./jwt.js";
+/**
+ * Owns the auth lifecycle: holds the current {@link Session}, serialises it
+ * into request headers, and renews it on demand (proactively or lazily on a
+ * 401) via the {@link AuthBackend}, persisting through the {@link TokenStore}.
+ */
+export class SessionManager {
+    session;
+    backend;
+    store;
+    constructor(opts = {}) {
+        this.session = opts.session ?? null;
+        this.backend = opts.backend;
+        this.store = opts.store;
+    }
+    /** Load any persisted session from the store into the manager. */
+    async load() {
+        if (this.store)
+            this.session = await this.store.load();
+        return this.session;
+    }
+    get current() {
+        return this.session;
+    }
+    async setSession(session) {
+        // Clone so we never mutate the caller's object (it may be shared/frozen).
+        const stored = {
+            ...session,
+            accessTokenExpiry: session.accessTokenExpiry ?? jwtExpiryMs(session.accessToken),
+        };
+        this.session = stored;
+        if (this.store)
+            await this.store.save(stored);
+    }
+    /** True when there is no session or the access token is within `skewMs` of expiry. */
+    isExpired(skewMs = 60_000) {
+        if (!this.session)
+            return true;
+        const exp = this.session.accessTokenExpiry;
+        return exp !== undefined && Date.now() >= exp - skewMs;
+    }
+    /** Build the auth headers for a write, or undefined when anonymous. */
+    authHeaders() {
+        if (!this.session)
+            return undefined;
+        const cookie = Object.entries(this.session.cookies)
+            .map(([k, v]) => `${k}=${v}`)
+            .join("; ");
+        return {
+            authorization: `Bearer ${this.session.accessToken}`,
+            customerUuid: this.session.customerUuid,
+            cookie: cookie || undefined,
+        };
+    }
+    /** Renew via the backend. Returns false if renewal is impossible. */
+    async refresh() {
+        if (!this.backend || !this.session)
+            return false;
+        const renewed = await this.backend.refresh(this.session);
+        await this.setSession(renewed);
+        return true;
+    }
+    async login(...args) {
+        if (!this.backend)
+            throw new Error("No AuthBackend configured — cannot login.");
+        const session = await this.backend.login(...args);
+        await this.setSession(session);
+        return session;
+    }
+}

package/dist/store/file-store.d.ts

@@ -0,0 +1,11 @@
+import type { Session } from "../models.js";
+import type { TokenStore } from "./types.js";
+/** Persists the session to `~/.basketeer/session.json` (garth-style). */
+export declare class FileTokenStore implements TokenStore {
+    private readonly path;
+    constructor(path?: string);
+    load(): Promise<Session | null>;
+    save(session: Session): Promise<void>;
+    /** Note: does not securely erase — the file is unlinked, not shredded. */
+    clear(): Promise<void>;
+}

package/dist/store/file-store.js

@@ -0,0 +1,32 @@
+import { chmod, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+const DEFAULT_PATH = join(homedir(), ".basketeer", "session.json");
+/** Persists the session to `~/.basketeer/session.json` (garth-style). */
+export class FileTokenStore {
+    path;
+    constructor(path = DEFAULT_PATH) {
+        this.path = path;
+    }
+    async load() {
+        try {
+            const raw = await readFile(this.path, "utf8");
+            return JSON.parse(raw);
+        }
+        catch (err) {
+            if (err.code === "ENOENT")
+                return null;
+            throw err;
+        }
+    }
+    async save(session) {
+        await mkdir(dirname(this.path), { recursive: true, mode: 0o700 });
+        await writeFile(this.path, JSON.stringify(session, null, 2), { mode: 0o600 });
+        // writeFile's mode is a no-op if the file already existed with looser perms.
+        await chmod(this.path, 0o600);
+    }
+    /** Note: does not securely erase — the file is unlinked, not shredded. */
+    async clear() {
+        await rm(this.path, { force: true });
+    }
+}

package/dist/store/memory-store.d.ts

@@ -0,0 +1,10 @@
+import type { Session } from "../models.js";
+import type { TokenStore } from "./types.js";
+/** In-memory store for tests and serverless single-invocation use. */
+export declare class MemoryTokenStore implements TokenStore {
+    private session;
+    constructor(initial?: Session | null);
+    load(): Promise<Session | null>;
+    save(session: Session): Promise<void>;
+    clear(): Promise<void>;
+}

package/dist/store/memory-store.js

@@ -0,0 +1,16 @@
+/** In-memory store for tests and serverless single-invocation use. */
+export class MemoryTokenStore {
+    session;
+    constructor(initial = null) {
+        this.session = initial;
+    }
+    async load() {
+        return this.session;
+    }
+    async save(session) {
+        this.session = session;
+    }
+    async clear() {
+        this.session = null;
+    }
+}

package/dist/store/types.d.ts

@@ -0,0 +1,7 @@
+import type { Session } from "../models.js";
+/** Persists the authenticated session between processes. */
+export interface TokenStore {
+    load(): Promise<Session | null>;
+    save(session: Session): Promise<void>;
+    clear(): Promise<void>;
+}

package/dist/store/types.js

@@ -0,0 +1 @@
+export {};