basketeer 0.2.0 → 0.3.0

package/README.md

@@ -196,6 +196,11 @@ await client.orders.cancel(orders[0]!.orderNo);
 // "Reorder my usual shop":
 const last = await client.orders.lastFulfilled();
 for (const it of last?.items ?? []) await client.basket.set(it.productId!, it.quantity, it.unit ?? "pcs");
+
+// Completed orders, newest first, offset-paged (Tesco has no cursor or total).
+// The result set is LIVE — dedupe by order.id and never persist nextOffset.
+let page = await client.orders.history();               // { orders, nextOffset }
+while (page.nextOffset !== null) page = await client.orders.history({ offset: page.nextOffset });
 ```
 
 ## MCP server (for AI agents)

package/dist/client.d.ts

@@ -1,5 +1,5 @@
 import type { AuthBackend, Credentials } from "./auth/types.js";
-import type { Basket, BasketUpdateResult, BookedSlot, NutritionFilter, NutritionSort, Order, Product, SearchPage, Session, Slot } from "./models.js";
+import type { Basket, BasketUpdateResult, BookedSlot, NutritionFilter, NutritionSort, Order, OrderHistoryPage, Product, SearchPage, Session, Slot } from "./models.js";
 import { type FulfilmentType, type OrderContext } from "./operations.js";
 import type { TokenStore } from "./store/types.js";
 export interface BasketeerOptions {
@@ -18,6 +18,8 @@ export interface BasketeerOptions {
 }
 /** Tesco's observed maximum number of aliased product fields in one operation. */
 export declare const MAX_PRODUCT_BATCH_SIZE = 15;
+/** Basketeer's policy cap on `orders.history` page size — not a discovered Tesco limit. */
+export declare const MAX_HISTORY_PAGE_SIZE = 100;
 /** A raw basket line input for the low-level `basket.update`. */
 export interface BasketItemInput {
     id: string;
@@ -128,6 +130,18 @@ export declare class Basketeer {
         list: (opts?: {
             contexts?: readonly OrderContext[];
         }) => Promise<Order[]>;
+        /**
+         * One page of completed (previous) orders, newest first. `limit` defaults
+         * to 25 (max {@link MAX_HISTORY_PAGE_SIZE}). Offset pagination runs over a
+         * LIVE result set: follow `nextOffset` within a single traversal, dedupe
+         * by `Order.id`, and never persist an offset across runs — a new completed
+         * order shifts every later offset.
+         */
+        history: (opts?: {
+            offset?: number;
+            limit?: number;
+            contexts?: readonly OrderContext[];
+        }) => Promise<OrderHistoryPage>;
         /**
          * Open an order for amendment. Returns an {@link Amendment} handle whose
          * basket ops apply to THAT order; finish by checking out again, or call
@@ -144,6 +158,7 @@ export declare class Basketeer {
     private cancelOrder;
     private lastFulfilledOrder;
     private listOrders;
+    private orderHistory;
     private orderAction;
     /**
      * Prepare for payment. Returns the current basket and the URL where payment

package/dist/client.js

@@ -1,12 +1,14 @@
 import { BasketeerError, ItemUnavailableError, 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 { CHECKOUT_URL, FULFILMENT_TYPE, MFE, PENDING_ORDER_CONTEXTS, PREVIOUS_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, getProductsQuery, SEARCH, UPDATE_BASKET, } from "./queries.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_ORDER_HISTORY, GET_PRODUCT, GET_UPCOMING_ORDERS, getProductsQuery, SEARCH, UPDATE_BASKET, } from "./queries.js";
 import { SessionManager } from "./session-manager.js";
 /** Tesco's observed maximum number of aliased product fields in one operation. */
 export const MAX_PRODUCT_BATCH_SIZE = 15;
+/** Basketeer's policy cap on `orders.history` page size — not a discovered Tesco limit. */
+export const MAX_HISTORY_PAGE_SIZE = 100;
 /** Guard for numeric SDK inputs. Throws `RangeError` for non-integer or out-of-range values. */
 function reqInt(v, name, min) {
     if (v === undefined)
@@ -267,6 +269,14 @@ export class Basketeer {
     orders = {
         /** List upcoming (pending) orders with their items, slot, and amend window. */
         list: (opts = {}) => this.listOrders(opts),
+        /**
+         * One page of completed (previous) orders, newest first. `limit` defaults
+         * to 25 (max {@link MAX_HISTORY_PAGE_SIZE}). Offset pagination runs over a
+         * LIVE result set: follow `nextOffset` within a single traversal, dedupe
+         * by `Order.id`, and never persist an offset across runs — a new completed
+         * order shifts every later offset.
+         */
+        history: (opts = {}) => this.orderHistory(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
@@ -317,6 +327,29 @@ export class Basketeer {
         });
         return (data.orderSearch?.orders ?? []).map(parseOrder);
     }
+    async orderHistory(opts) {
+        // Never forward surprising values: Tesco treats count: 0 as UNBOUNDED and
+        // returns an empty (terminal-looking) page for a negative offset.
+        reqInt(opts.offset, "offset", 0);
+        reqInt(opts.limit, "limit", 1);
+        if (opts.limit !== undefined && opts.limit > MAX_HISTORY_PAGE_SIZE)
+            throw new RangeError(`limit must be an integer <= ${MAX_HISTORY_PAGE_SIZE}`);
+        const offset = opts.offset ?? 0;
+        const limit = opts.limit ?? 25;
+        const data = await this.transport.execute({
+            operationName: "GetOrderHistory",
+            query: GET_ORDER_HISTORY,
+            variables: { orderContexts: opts.contexts ?? PREVIOUS_ORDER_CONTEXTS, count: limit, offset },
+            mfeName: MFE.orders,
+        });
+        // Strict, unlike list(): a short page is this API's only terminal signal,
+        // so a malformed response must not masquerade as one.
+        const raw = data.orderSearch?.orders;
+        if (!Array.isArray(raw))
+            throw new BasketeerError("GetOrderHistory returned no orderSearch.orders array");
+        const orders = raw.map(parseOrder);
+        return { orders, nextOffset: orders.length < limit ? null : offset + orders.length };
+    }
     async orderAction(query, operationName, orderNo) {
         await this.transport.execute({
             operationName,

package/dist/index.d.ts

@@ -1,14 +1,14 @@
 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, MAX_PRODUCT_BATCH_SIZE } from "./client.js";
+export { Basketeer, MAX_HISTORY_PAGE_SIZE, MAX_PRODUCT_BATCH_SIZE } from "./client.js";
 export { ApiKeyError, AuthExpiredError, BasketeerError, GraphQLRequestError, ItemUnavailableError, LineRejectedError, NotFoundError, RateLimitedError, } from "./errors.js";
 export type { ImageSize } from "./images.js";
 export { resizeImageUrl } from "./images.js";
-export type { Basket, BasketLine, BasketUpdateResult, BookedSlot, CatchWeightOption, MacroFilterKey, Macros, Micronutrient, Nutrition, NutritionBasis, NutritionFilter, NutritionSort, Order, OrderAddress, OrderItem, OrderSlot, PackSize, Price, Product, ProductQuantityRules, Promotion, Range, SearchPage, SearchResult, Session, Slot, } from "./models.js";
+export type { Basket, BasketLine, BasketUpdateResult, BookedSlot, CatchWeightOption, MacroFilterKey, Macros, Micronutrient, Nutrition, NutritionBasis, NutritionFilter, NutritionSort, Order, OrderAddress, OrderHistoryPage, OrderItem, OrderSlot, PackSize, Price, Product, ProductQuantityRules, 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 { CHECKOUT_URL, categoryFacet, ENDPOINT, FULFILMENT_TYPE, PENDING_ORDER_CONTEXTS, PREVIOUS_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

@@ -1,14 +1,14 @@
 // 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, MAX_PRODUCT_BATCH_SIZE } from "./client.js";
+export { Basketeer, MAX_HISTORY_PAGE_SIZE, MAX_PRODUCT_BATCH_SIZE } from "./client.js";
 // Errors
 export { ApiKeyError, AuthExpiredError, BasketeerError, GraphQLRequestError, ItemUnavailableError, LineRejectedError, NotFoundError, RateLimitedError, } from "./errors.js";
 export { resizeImageUrl } from "./images.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";
+export { CHECKOUT_URL, categoryFacet, ENDPOINT, FULFILMENT_TYPE, PENDING_ORDER_CONTEXTS, PREVIOUS_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/models.d.ts

@@ -176,6 +176,22 @@ export interface Order {
     items: OrderItem[];
     raw: unknown;
 }
+/**
+ * One page of completed-order history. Pagination is offset-based over a
+ * LIVE, newest-first result set — a new completed order shifts every later
+ * offset — so keep `nextOffset` only for the duration of one traversal and
+ * deduplicate by `Order.id`.
+ */
+export interface OrderHistoryPage {
+    orders: Order[];
+    /**
+     * Offset for the next page, or null when this page was short (terminal).
+     * Non-null only means "another request is needed to know" — Tesco supplies
+     * no authoritative has-next-page signal, so when the total is an exact
+     * multiple of `limit` the final page is empty.
+     */
+    nextOffset: number | null;
+}
 /**
  * An authenticated session. For the browser-minted hybrid (v1), `accessToken`
  * is the harvested `OAuth.AccessToken` bearer and `customerUuid` is the `UUID`

package/dist/nutrition.js

@@ -40,18 +40,43 @@ function basisFromHeader(v) {
 }
 const MACRO_LABELS = {
     fat: "fat",
+    "total fat": "fat",
     saturates: "saturates",
     "of which saturates": "saturates",
+    "saturated fat": "saturates",
+    "of which saturated fat": "saturates",
     carbohydrate: "carbs",
+    carbohydrates: "carbs",
     "available carbohydrate": "carbs",
     "total carbohydrate": "carbs",
     sugars: "sugars",
     "of which sugars": "sugars",
+    "total sugars": "sugars",
     fibre: "fibre",
     protein: "protein",
     salt: "salt",
     "salt equivalent": "salt",
 };
+/** Trailing unit in a row name: "Fat (g)", "Energy (kcal)", "Calcium (mg)". */
+const UNIT_IN_NAME = /\s*\(\s*(kj|kcal|g|mg|µg|μg)\s*\)\s*$/i;
+/** Drop a leading dash or unbalanced paren: "- Saturates" / "(of which saturates". */
+function cleanName(name) {
+    return name
+        .trim()
+        .replace(/^-\s*(?=[a-z])/i, "")
+        .replace(/^\((?![^(]*\))\s*/, "");
+}
+/** Lookup key for a row label: "(of which: sugars*)" / "Protein g" -> "of which sugars" / "protein". */
+function labelKey(name) {
+    return name
+        .toLowerCase()
+        .replace(/[*†:,]+/g, " ")
+        .trim()
+        .replace(/(\s+|\s*\()(g|mg|µg|μg)\)?$/, "")
+        .replace(/^\((.*)\)$/, "$1")
+        .replace(/\s+/g, " ")
+        .trim();
+}
 function isFootnote(name, value) {
     const n = name.trim();
     if (n.startsWith("*"))
@@ -62,7 +87,7 @@ function isFootnote(name, value) {
         return true;
     if (/reference intake|nutrient reference value/i.test(n))
         return true;
-    const known = !!MACRO_LABELS[n.toLowerCase()] || /^energy/i.test(n);
+    const known = !!MACRO_LABELS[labelKey(n)] || /^energy/i.test(n);
     if (!known && (value === "-" || value === null || value === ""))
         return true;
     return false;
@@ -76,7 +101,7 @@ export function parseNutrition(rows) {
     let expectKcalNext = false;
     for (const r of rows) {
         const row = (r ?? {});
-        const name = typeof row.name === "string" ? row.name.trim() : "";
+        const name = typeof row.name === "string" ? cleanName(row.name) : "";
         // 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)
@@ -96,9 +121,18 @@ export function parseNutrition(rows) {
                 basis = basisFromHeader(value1);
             continue;
         }
-        // Energy (inline "486kJ / 115kcal" or split "257 kJ/")
-        if (/^energy/i.test(name)) {
-            if (value1) {
+        // Unit in the row name with a bare-number value: "Fat (g)" -> "3.0", "Energy (kcal)" -> "60".
+        const unitInName = name.match(UNIT_IN_NAME)?.[1]?.toLowerCase() ?? null;
+        const baseName = unitInName ? name.replace(UNIT_IN_NAME, "").trim() : name;
+        // Energy: unit in the name, inline "486kJ / 115kcal", or split "257 kJ/"
+        if (/^energy/i.test(baseName)) {
+            if (value1 && unitInName && !/kj|kcal/i.test(value1)) {
+                if (unitInName === "kcal")
+                    macros.energyKcal = num(value1);
+                if (unitInName === "kj")
+                    macros.energyKj = num(value1);
+            }
+            else if (value1) {
                 const kj = value1.match(/(\d+(?:\.\d+)?)\s*kj/i);
                 const kcal = value1.match(/(\d+(?:\.\d+)?)\s*kcal/i);
                 if (kj)
@@ -110,16 +144,28 @@ export function parseNutrition(rows) {
             }
             continue;
         }
-        if (isFootnote(name, value1))
+        // NRV on its own row named "-": "Calcium" => "124mg", then "-" => "(15.5% RI*)".
+        if (name === "-") {
+            const prev = micros[micros.length - 1];
+            if (prev && prev.nrvPercent == null && value1)
+                prev.nrvPercent = nrvOf(value1);
+            continue;
+        }
+        if (isFootnote(baseName, value1))
             continue;
-        const key = MACRO_LABELS[name.toLowerCase()];
+        const key = MACRO_LABELS[labelKey(baseName)];
         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) });
+            micros.push({
+                name: baseName,
+                amount: num(value1),
+                unit: unitOf(value1) ?? unitInName,
+                nrvPercent: nrvOf(value1),
+            });
         }
     }
     return { basis, macros, micros, raw: rows };

package/dist/operations.d.ts

@@ -23,13 +23,15 @@ export declare const MFE: {
     readonly orders: "mfe-orders";
     readonly favourites: "mfe-favourites";
 };
-/** One context for `orders.list` — an order type plus the statuses to include. */
+/** One context for the order queries — 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[];
+/** Default contexts for `orders.history` — completed (previous) grocery orders. */
+export declare const PREVIOUS_ORDER_CONTEXTS: readonly OrderContext[];
 /** Fulfilment method types accepted by the slot ops. */
 export declare const FULFILMENT_TYPE: {
     readonly delivery: "DELIVERY_VAN";

package/dist/operations.js

@@ -29,6 +29,10 @@ export const PENDING_ORDER_CONTEXTS = [
     { type: "MARKETPLACE", statuses: ["Pending"] },
     { type: "FNF", statuses: ["Pending"] },
 ];
+/** Default contexts for `orders.history` — completed (previous) grocery orders. */
+export const PREVIOUS_ORDER_CONTEXTS = [
+    { type: "GROCERY", statuses: ["Previous"] },
+];
 /** Fulfilment method types accepted by the slot ops. */
 export const FULFILMENT_TYPE = {
     delivery: "DELIVERY_VAN",

package/dist/queries.d.ts

@@ -11,6 +11,7 @@ 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 GET_ORDER_HISTORY: string;
 export declare const AMEND_ORDER: string;
 export declare const CANCEL_ORDER: string;
 export declare const CANCEL_AMEND: string;

package/dist/queries.js

@@ -144,10 +144,7 @@ mutation UpdateBasket($items: [BasketLineItemInputType], $orderId: ID) {
   }
 }`.trim();
 // ---- orders ----------------------------------------------------------------
-export const GET_UPCOMING_ORDERS = `
-query GetUpcomingOrders($orderContexts: [OrderContextType]) {
-  orderSearch(orderContexts: $orderContexts) {
-    orders {
+const ORDER_FIELDS = `
       id
       orderNo
       status
@@ -159,7 +156,22 @@ query GetUpcomingOrders($orderContexts: [OrderContextType]) {
       paymentMode
       slot { id start end charge }
       address { name city addressLine1 postcode }
-      items { id quantity unit weight product { id title } }
+      items { id quantity unit weight product { id title } }`;
+export const GET_UPCOMING_ORDERS = `
+query GetUpcomingOrders($orderContexts: [OrderContextType]) {
+  orderSearch(orderContexts: $orderContexts) {
+    orders {${ORDER_FIELDS}
+    }
+  }
+}`.trim();
+// Offset pagination over a LIVE, newest-first result set. Tesco's orderSearch
+// exposes only count/offset — no cursor, total, or page metadata — so terminal
+// state is inferred from a short page. The schema accepts `page` but ignores
+// it; never send it.
+export const GET_ORDER_HISTORY = `
+query GetOrderHistory($orderContexts: [OrderContextType], $count: Int, $offset: Int) {
+  orderSearch(orderContexts: $orderContexts, count: $count, offset: $offset) {
+    orders {${ORDER_FIELDS}
     }
   }
 }`.trim();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "basketeer",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Typed, pure-HTTP TypeScript SDK for your own Tesco grocery account — search, basket, delivery slots, and orders over plain fetch. Browser only for login + payment.",
   "type": "module",
   "license": "MIT",