basketeer 0.1.2 → 0.3.0

package/README.md

@@ -93,6 +93,10 @@ if (top) {
   console.log(product.title, product.price.actual);
   // => "Tesco Wholemeal Bread 800G" 0.75
 }
+
+// Fetch up to 15 SKUs in one throttled HTTP request. Duplicates are fetched
+// once and missing products are omitted.
+const products = await client.getProducts(["282822189", "275280804"]);
 ```
 
 ### Authenticated, sign in once, then pure HTTP
@@ -140,7 +144,7 @@ console.log("Finish payment in a browser:", url);
 The full grocery lifecycle, typed end to end:
 
 - **Nutrition** — typed macros and structured micros, normalized from a product's on-pack rows when present; filter and rank a search by nutrition (anonymous)
-- **Catalogue** — `search`, `getProduct`, `browseCategory` (anonymous); `favourites` / "my usuals" (authed)
+- **Catalogue** — `search`, `getProduct`, batched `getProducts`, `browseCategory` (anonymous); `favourites` / "my usuals" (authed)
 - **Product images** — `imageUrl` on every product/result; `resizeImageUrl(url, { width, height })` for thumbnails (anonymous)
 - **Basket** — `add`, `set`, `remove`, `get`
 - **Slots** — delivery and collection: `list` / `book` / `release`
@@ -192,11 +196,16 @@ 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)
 
-A stdio MCP server ships as the `basketeer-mcp` bin, exposing tools (`basketeer_search`, `basketeer_search_by_nutrition`, `basketeer_nutrition`, `basketeer_basket_set`, `basketeer_slots_list`, `basketeer_orders_list`, `basketeer_checkout`, …) so Claude Desktop or any MCP client can shop. Read-only tools carry `readOnlyHint`; mutating ones carry `destructiveHint`, and `basketeer_orders_cancel` / `basketeer_checkout` take a two-step confirm token. `basketeer_checkout` returns the payment URL for the human. There is no "pay" tool.
+A stdio MCP server ships as the `basketeer-mcp` bin, exposing tools (`basketeer_search`, `basketeer_search_by_nutrition`, `basketeer_nutrition`, `basketeer_basket_set`, `basketeer_slots_list`, `basketeer_orders_list`, `basketeer_checkout`, …) so Claude Desktop or any MCP client can shop. Read-only tools carry `readOnlyHint`; mutating ones carry `destructiveHint`, and `basketeer_orders_cancel` / `basketeer_checkout` take a two-step confirm token. `basketeer_checkout` returns the payment URL for the human. There is no "pay" tool. The search tools take an optional `select` — an array of dot-notation paths (e.g. `["sku", "title", "price.actual", "promotions.description"]`) that trims each result to just those fields, keeping token usage down in agent loops.
 
 ```jsonc
 // claude_desktop_config.json — run `basketeer login` once first so it has a session.

package/dist/cli.js

@@ -183,8 +183,15 @@ orders
     const items = last.items
         .filter((it) => it.productId)
         .map((it) => ({ id: it.productId, newValue: it.quantity, newUnitChoice: it.unit ?? "pcs" }));
-    const basketResult = await client.basket.update(items);
-    emit({ ok: true, reorderedFrom: last.orderNo, lines: items.length, basket: basketResult });
+    const { basket, rejected, unavailable } = await client.basket.update(items);
+    emit({
+        ok: !rejected.length && !unavailable.length,
+        reorderedFrom: last.orderNo,
+        lines: items.length,
+        rejected,
+        unavailable,
+        basket,
+    });
 });
 // --- checkout ---------------------------------------------------------------
 program

package/dist/client.d.ts

@@ -1,5 +1,5 @@
 import type { AuthBackend, Credentials } from "./auth/types.js";
-import type { Basket, 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 {
@@ -16,6 +16,10 @@ export interface BasketeerOptions {
     /** Injected for tests; defaults to global fetch. */
     fetchImpl?: typeof fetch;
 }
+/** 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;
@@ -56,6 +60,11 @@ export declare class Basketeer {
     /** The order currently open for amendment via `orders.amend`, if any. */
     get amendingOrderNo(): string | null;
     getProduct(sku: string): Promise<Product>;
+    /**
+     * Fetch up to 15 products in one throttled HTTP request. Duplicate SKUs are
+     * fetched once and missing products are omitted from the returned array.
+     */
+    getProducts(skus: readonly string[]): Promise<Product[]>;
     search(query: string, opts?: {
         limit?: number;
         page?: number;
@@ -105,16 +114,34 @@ export declare class Basketeer {
         set: (sku: string, quantity: number, unit?: string) => Promise<Basket>;
         /** Remove `sku` from the basket. */
         remove: (sku: string) => Promise<Basket>;
-        /** Low-level: send raw basket line inputs (and an optional orderId). */
-        update: (items: BasketItemInput[], orderId?: string) => Promise<Basket>;
+        /**
+         * Low-level: send raw basket line inputs (and an optional orderId).
+         * A batch can partly succeed, so line-level outcomes (`rejected`,
+         * `unavailable`) are reported on the result rather than thrown.
+         */
+        update: (items: BasketItemInput[], orderId?: string) => Promise<BasketUpdateResult>;
     };
     private getBasket;
+    /** Single-line path for `add`/`set`/`remove`: line-level failures throw. */
+    private updateLine;
     private updateBasket;
     readonly orders: {
         /** List upcoming (pending) orders with their items, slot, and amend window. */
         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
@@ -131,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,10 +1,14 @@
-import { BasketeerError, LineRejectedError, NotFoundError } from "./errors.js";
+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, 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)
@@ -85,6 +89,26 @@ export class Basketeer {
             throw new NotFoundError(`No product found for SKU ${sku}`);
         return parseProduct(data.product);
     }
+    /**
+     * Fetch up to 15 products in one throttled HTTP request. Duplicate SKUs are
+     * fetched once and missing products are omitted from the returned array.
+     */
+    async getProducts(skus) {
+        const uniqueSkus = [...new Set(skus.map(String))];
+        if (uniqueSkus.length === 0)
+            return [];
+        if (uniqueSkus.length > MAX_PRODUCT_BATCH_SIZE) {
+            throw new RangeError(`skus must contain at most ${MAX_PRODUCT_BATCH_SIZE} unique values`);
+        }
+        const variables = Object.fromEntries(uniqueSkus.map((sku, i) => [`tpnc${i}`, sku]));
+        const data = await this.transport.execute({
+            operationName: "GetProducts",
+            query: getProductsQuery(uniqueSkus.length),
+            variables,
+            mfeName: MFE.product,
+        });
+        return uniqueSkus.flatMap((_, i) => (data[`p${i}`] ? [parseProduct(data[`p${i}`])] : []));
+    }
     async search(query, opts = {}) {
         reqInt(opts.limit, "limit", 1);
         reqInt(opts.page, "page", 1);
@@ -176,17 +200,21 @@ export class Basketeer {
             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 }]);
+            return this.updateLine({ 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 }]);
+            return this.updateLine({ 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). */
+        remove: (sku) => this.updateLine({ id: sku, newValue: 0 }),
+        /**
+         * Low-level: send raw basket line inputs (and an optional orderId).
+         * A batch can partly succeed, so line-level outcomes (`rejected`,
+         * `unavailable`) are reported on the result rather than thrown.
+         */
         update: (items, orderId) => this.updateBasket(items, orderId),
     };
     async getBasket() {
@@ -198,6 +226,15 @@ export class Basketeer {
         });
         return parseBasket(data.basket);
     }
+    /** Single-line path for `add`/`set`/`remove`: line-level failures throw. */
+    async updateLine(item) {
+        const { basket, rejected, unavailable } = await this.updateBasket([item]);
+        if (rejected.length)
+            throw new LineRejectedError(rejected.join(", "));
+        if (unavailable.length)
+            throw new ItemUnavailableError(unavailable);
+        return basket;
+    }
     async updateBasket(items, orderId) {
         for (const item of items)
             reqQty(item.newValue, "quantity");
@@ -212,14 +249,34 @@ export class Basketeer {
         });
         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);
+        const basket = parseBasket(data.basket);
+        // Tesco accepts unavailable lines silently (updates.successful stays true)
+        // then drops them at checkout. Mirror its UI: among the SKUs we just added
+        // (newValue > 0), roll back any the basket reports as unavailable and
+        // report them on the result.
+        const added = new Set(items.filter((i) => i.newValue > 0).map((i) => String(i.id)));
+        const unavailable = basket.items
+            .filter((l) => l.sku != null && added.has(l.sku) && l.available === false)
+            .map((l) => l.sku);
+        if (unavailable.length) {
+            // The rollback lines are all newValue 0, so this cannot recurse further.
+            const rollback = await this.updateBasket(unavailable.map((id) => ({ id, newValue: 0 })), orderId);
+            return { basket: rollback.basket, rejected, unavailable };
+        }
+        return { basket, rejected, unavailable };
     }
     // --- orders (requires auth) -----------------------------------------------
     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
@@ -270,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/errors.d.ts

@@ -38,3 +38,15 @@ export declare class LineRejectedError extends BasketeerError {
     readonly lineId: string;
     constructor(lineId: string);
 }
+/**
+ * The SKU passed to `basket.add`/`set` is unavailable for the basket's
+ * slot/store (Tesco's `isForSale` is false). Tesco silently accepts these on
+ * write then drops them at checkout, so the client rolls the line back and
+ * throws this instead. The batch `basket.update` does not throw this — it
+ * reports unavailable SKUs on its result. Availability is slot-specific —
+ * see {@link Product.available}.
+ */
+export declare class ItemUnavailableError extends BasketeerError {
+    readonly skus: string[];
+    constructor(skus: string[]);
+}

package/dist/errors.js

@@ -62,3 +62,18 @@ export class LineRejectedError extends BasketeerError {
         this.lineId = lineId;
     }
 }
+/**
+ * The SKU passed to `basket.add`/`set` is unavailable for the basket's
+ * slot/store (Tesco's `isForSale` is false). Tesco silently accepts these on
+ * write then drops them at checkout, so the client rolls the line back and
+ * throws this instead. The batch `basket.update` does not throw this — it
+ * reports unavailable SKUs on its result. Availability is slot-specific —
+ * see {@link Product.available}.
+ */
+export class ItemUnavailableError extends BasketeerError {
+    skus;
+    constructor(skus) {
+        super(`Unavailable for your slot, not added: ${skus.join(", ")}`);
+        this.skus = skus;
+    }
+}

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 } from "./client.js";
-export { ApiKeyError, AuthExpiredError, BasketeerError, GraphQLRequestError, LineRejectedError, NotFoundError, RateLimitedError, } from "./errors.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, 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 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 } from "./client.js";
+export { Basketeer, MAX_HISTORY_PAGE_SIZE, MAX_PRODUCT_BATCH_SIZE } from "./client.js";
 // Errors
-export { ApiKeyError, AuthExpiredError, BasketeerError, GraphQLRequestError, LineRejectedError, NotFoundError, RateLimitedError, } from "./errors.js";
+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/mcp-server.js

@@ -28,9 +28,15 @@ import { z } from "zod";
 import { BrowserAuthBackend } from "./auth/browser/playwright.js";
 import { Basketeer, BasketeerError, FileTokenStore } from "./index.js";
 import { isMainModule } from "./is-main.js";
-/** Wrap a value as MCP JSON text content. */
+import { PRODUCT_FIELDS, projectResults, SEARCH_RESULT_FIELDS } from "./select.js";
+/**
+ * Wrap a value as MCP JSON text content. `raw` GraphQL escape hatches are
+ * omitted at any depth — they duplicate the parsed fields and waste agent
+ * context (issue #9).
+ */
 function json(value) {
-    return { content: [{ type: "text", text: JSON.stringify(value, null, 2) }] };
+    const text = JSON.stringify(value, (key, v) => (key === "raw" ? undefined : v), 2);
+    return { content: [{ type: "text", text }] };
 }
 /** Run a tool body, mapping SDK errors to a clean MCP error result. */
 async function run(fn) {
@@ -46,6 +52,30 @@ async function run(fn) {
         };
     }
 }
+/** Zod param for `select` — the dot-notation projection on search results (issue #10). */
+function selectParam(fields) {
+    return z
+        .array(z.string())
+        .nonempty()
+        .optional()
+        .describe("Optional list of dot-notation paths to keep in each result (token saver), " +
+        'e.g. ["sku", "title", "price.actual", "promotions.description"]. ' +
+        `Top-level fields: ${fields.join(", ")}. Omit for full results.`);
+}
+/**
+ * Compact mutation receipt (issue #9): basket writes confirm rather than
+ * re-enumerate, so per-call output stays flat as the basket grows. Full state
+ * stays one `basketeer_basket_get` call away.
+ */
+function receipt(basket, sku) {
+    return {
+        sku,
+        quantity: basket.items.find((i) => i.sku === sku)?.quantity ?? 0,
+        itemCount: basket.items.length,
+        guidePrice: basket.guidePrice,
+        isInAmend: basket.isInAmend,
+    };
+}
 /** 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);
@@ -57,12 +87,18 @@ export function confirmToken(parts) {
 export function buildServer(client) {
     const server = new McpServer({ name: "basketeer", version: "0.1.1" });
     // --- reads (anonymous OK) -------------------------------------------------
-    server.tool("basketeer_search", "Search the Tesco grocery catalogue. Returns matching products with SKU, title, price, and any offers.", {
+    server.tool("basketeer_search", "Search the Tesco grocery catalogue. Returns matching products with SKU, title, price, offers, and quantityRules (weight/bulk buy limits).", {
         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 })));
+        select: selectParam(SEARCH_RESULT_FIELDS),
+    }, { readOnlyHint: true }, ({ query, limit, select }) => run(async () => {
+        const page = await client.search(query, { limit });
+        return select
+            ? { ...page, results: projectResults(page.results, select, SEARCH_RESULT_FIELDS) }
+            : page;
+    }));
+    server.tool("basketeer_product", "Fetch one product by SKU (tpnc), including price, pack size, promotions, quantityRules (weight/bulk buy/catch weight options), 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') including price, offers, and quantityRules. 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`.", {
@@ -82,22 +118,28 @@ export function buildServer(client) {
             .positive()
             .optional()
             .describe("Max results to return after filtering."),
-    }, { readOnlyHint: true }, ({ query, minProtein, maxSugar, sortBy, hydrate, limit }) => run(() => {
+        select: selectParam(PRODUCT_FIELDS),
+    }, { readOnlyHint: true }, ({ query, minProtein, maxSugar, sortBy, hydrate, limit, select }) => run(async () => {
         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 });
+        const page = await client.searchByNutrition(query, { where, sort, hydrate, limit });
+        return select
+            ? { ...page, results: projectResults(page.results, select, PRODUCT_FIELDS) }
+            : page;
     }));
     // --- 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.", {
+    server.tool("basketeer_basket_set", "Set a SKU's basket line to an exact quantity (set-not-increment). quantity 0 removes the line. " +
+        "Returns a compact receipt; call basketeer_basket_get for full basket contents.", {
         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)));
+    }, { readOnlyHint: false, destructiveHint: true }, ({ sku, quantity }) => run(async () => receipt(await client.basket.set(sku, quantity), sku)));
+    server.tool("basketeer_basket_remove", "Remove a SKU from the basket entirely. " +
+        "Returns a compact receipt; call basketeer_basket_get for full basket contents.", { sku: z.string().describe("The product SKU (tpnc) to remove.") }, { readOnlyHint: false, destructiveHint: true }, ({ sku }) => run(async () => receipt(await client.basket.remove(sku), 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."),

package/dist/models.d.ts

@@ -16,6 +16,20 @@ export interface PackSize {
     value: number;
     units: string;
 }
+export interface CatchWeightOption {
+    price: number;
+    weight: number;
+    default: boolean;
+}
+export interface ProductQuantityRules {
+    productType: string | null;
+    averageWeight: number | null;
+    minWeight: number | null;
+    maxWeight: number | null;
+    increment: number | null;
+    bulkBuyLimit: number | null;
+    catchWeightOptions: CatchWeightOption[];
+}
 export interface Product {
     /** tpnc — the SKU used for product lookup and basket ops. */
     sku: string;
@@ -24,7 +38,15 @@ export interface Product {
     brand: string | null;
     imageUrl: string | null;
     price: Price;
+    /**
+     * Tesco's `isForSale` for the read's context, or null if absent. Anonymous
+     * reads report the optimistic NATIONAL answer; reads on a session bound to a
+     * booked slot report the real per-store answer (the same SKU can flip to
+     * `false`). `null` when Tesco omitted the field.
+     */
+    available: boolean | null;
     packSize: PackSize | null;
+    quantityRules: ProductQuantityRules;
     promotions: Promotion[];
     /** Normalized nutrition, or null if Tesco returned none / it was unparseable. */
     nutrition: Nutrition | null;
@@ -39,6 +61,9 @@ export interface SearchResult {
     brand: string | null;
     imageUrl: string | null;
     price: Price;
+    quantityRules: ProductQuantityRules;
+    /** See {@link Product.available} — context-dependent (anonymous = national). */
+    available: boolean | null;
     onOffer: boolean;
     promotions: Promotion[];
 }
@@ -56,6 +81,12 @@ export interface BasketLine {
     quantity: number;
     unit: string | null;
     cost: number | null;
+    /**
+     * Tesco's `isForSale` for this line in the basket's slot/store context, or
+     * null if absent. `false` means Tesco will drop it at checkout — see
+     * {@link Product.available}.
+     */
+    available: boolean | null;
 }
 export interface Basket {
     id: string | null;
@@ -67,6 +98,24 @@ export interface Basket {
     items: BasketLine[];
     raw: unknown;
 }
+/**
+ * Result of the low-level batch `basket.update`. Line-level outcomes are
+ * reported here rather than thrown, because a batch can partly succeed: the
+ * remote basket reflects the successful lines even when others fail. The
+ * single-SKU conveniences (`add`/`set`/`remove`) throw instead.
+ */
+export interface BasketUpdateResult {
+    /** The basket after the update (and after any rollback of unavailable lines). */
+    basket: Basket;
+    /** SKUs Tesco rejected outright (`updates.items[].successful === false`). */
+    rejected: string[];
+    /**
+     * SKUs unavailable for the basket's slot/store (`isForSale` false). Tesco
+     * accepts these silently then drops them at checkout, so the client has
+     * already rolled these lines back — see {@link Product.available}.
+     */
+    unavailable: string[];
+}
 export interface Slot {
     /** Opaque slot id — pass to slots.book(). */
     id: string;
@@ -127,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/parsers.js

@@ -4,6 +4,7 @@ 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 bool = (v) => (typeof v === "boolean" ? v : null);
 const num = (v) => (typeof v === "number" && Number.isFinite(v) ? v : null);
 const id = (v) => (v == null ? null : String(v));
 function parsePrice(v) {
@@ -34,6 +35,28 @@ function parsePackSize(v) {
     const value = Number(p.value); // Tesco sends packSize.value as a numeric string
     return units && Number.isFinite(value) ? { value, units } : null;
 }
+function parseCatchWeightOptions(v) {
+    return objs(v)
+        .map((entry) => {
+        const price = num(entry.price);
+        const weight = num(entry.weight);
+        if (price === null || weight === null)
+            return null;
+        return { price, weight, default: Boolean(entry.default) };
+    })
+        .filter((entry) => entry !== null);
+}
+function parseQuantityRules(v) {
+    return {
+        productType: str(v.productType),
+        averageWeight: num(v.averageWeight),
+        minWeight: num(v.minWeight),
+        maxWeight: num(v.maxWeight),
+        increment: num(v.increment),
+        bulkBuyLimit: num(v.bulkBuyLimit),
+        catchWeightOptions: parseCatchWeightOptions(v.catchWeightList),
+    };
+}
 export function parseProduct(v) {
     const node = obj(v);
     const details = obj(node.details);
@@ -45,7 +68,9 @@ export function parseProduct(v) {
         brand: str(node.brandName),
         imageUrl: str(node.defaultImageUrl),
         price: parsePrice(node.price),
+        available: bool(node.isForSale),
         packSize: parsePackSize(details.packSize),
+        quantityRules: parseQuantityRules(node),
         promotions: parsePromotions(node.promotions),
         nutrition,
         macros: nutrition?.macros ?? null,
@@ -70,6 +95,8 @@ export function parseProductNode(v) {
         brand: str(node.brandName),
         imageUrl: str(node.defaultImageUrl),
         price: parsePrice(seller.price),
+        quantityRules: parseQuantityRules(node),
+        available: bool(node.isForSale),
         onOffer: promotions.length > 0,
         promotions,
     };
@@ -82,6 +109,7 @@ export function parseBasket(v) {
         quantity: num(it.quantity) ?? 0,
         unit: str(it.unit),
         cost: num(it.cost),
+        available: bool(obj(it.product).isForSale),
     }));
     return {
         id: id(node.id),

package/dist/queries.d.ts

@@ -3,12 +3,15 @@
  * Internal — not part of the public API. Config/constants live in operations.ts.
  */
 export declare const GET_PRODUCT: string;
+/** Build one aliased GraphQL operation so a product set costs one HTTP request. */
+export declare function getProductsQuery(count: number): 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 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

@@ -2,25 +2,36 @@
  * GraphQL operation strings for `xapi.tesco.com`, ported from observed traffic.
  * Internal — not part of the public API. Config/constants live in operations.ts.
  */
+const PRODUCT_FIELDS = `
+  tpnb tpnc title brandName defaultImageUrl isForSale
+  productType averageWeight minWeight maxWeight increment bulkBuyLimit
+  catchWeightList { price weight default }
+  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 GET_PRODUCT = `
 query GetProduct($tpnc: String!) {
   product(tpnc: $tpnc) {
-    tpnb tpnc title brandName defaultImageUrl
-    price { actual unitPrice unitOfMeasure }
-    promotions {
-      description
-      startDate
-      endDate
-      attributes
-      price { afterDiscount beforeDiscount }
-    }
-    details {
-      packSize { value units }
-      nutrition { name value1 value2 value3 }
-      ingredients
-    }
+    ${PRODUCT_FIELDS}
   }
 }`.trim();
+/** Build one aliased GraphQL operation so a product set costs one HTTP request. */
+export function getProductsQuery(count) {
+    const variables = Array.from({ length: count }, (_, i) => `$tpnc${i}: String!`).join(", ");
+    const products = Array.from({ length: count }, (_, i) => `p${i}: product(tpnc: $tpnc${i}) { ${PRODUCT_FIELDS} }`).join("\n  ");
+    return `query GetProducts(${variables}) {\n  ${products}\n}`;
+}
 export const SEARCH = `
 query Search($query: String!, $page: Int = 1, $count: Int) {
   search(query: $query, page: $page, count: $count) {
@@ -28,7 +39,9 @@ query Search($query: String!, $page: Int = 1, $count: Int) {
       node {
         __typename
         ... on ProductInterface {
-          tpnc tpnb title brandName defaultImageUrl
+          tpnc tpnb title brandName defaultImageUrl isForSale
+          productType averageWeight minWeight maxWeight increment bulkBuyLimit
+          catchWeightList { price weight default }
           sellers {
             results {
               price { actual unitPrice unitOfMeasure }
@@ -53,7 +66,9 @@ query GetCategoryProducts($facet: ID, $page: Int = 1, $count: Int) {
       node {
         __typename
         ... on ProductInterface {
-          tpnc tpnb title brandName defaultImageUrl
+          tpnc tpnb title brandName defaultImageUrl isForSale
+          productType averageWeight minWeight maxWeight increment bulkBuyLimit
+          catchWeightList { price weight default }
           sellers {
             results {
               price { actual unitPrice unitOfMeasure }
@@ -71,7 +86,9 @@ query GetFavourites($page: Int = 1, $count: Int, $sortBy: String) {
     products {
       __typename
       ... on ProductInterface {
-        tpnc tpnb title brandName defaultImageUrl
+        tpnc tpnb title brandName defaultImageUrl isForSale
+        productType averageWeight minWeight maxWeight increment bulkBuyLimit
+        catchWeightList { price weight default }
         sellers {
           results {
             price { actual unitPrice unitOfMeasure }
@@ -97,7 +114,7 @@ query GetBasket {
       weight
       cost
       quantity
-      product { id __typename }
+      product { id __typename isForSale }
     }
   }
 }`.trim();
@@ -119,7 +136,7 @@ mutation UpdateBasket($items: [BasketLineItemInputType], $orderId: ID) {
       weight
       cost
       quantity
-      product { id __typename }
+      product { id __typename isForSale }
     }
     updates {
       items { id successful __typename }
@@ -127,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
@@ -142,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/dist/select.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Field projection for MCP search tools (issue #10).
+ *
+ * Agents pass `select`, an array of dot-notation paths, to keep only the
+ * fields they need from each result — full search responses are token-heavy
+ * for LLM loops. A path segment that lands on an array projects each element
+ * (`promotions.description` keeps the description of every promotion).
+ */
+export declare const SEARCH_RESULT_FIELDS: readonly string[];
+export declare const PRODUCT_FIELDS: readonly string[];
+/**
+ * Project each result down to `paths`. Throws `RangeError` on a path whose
+ * first segment is not in `validFields` (so a mistyped field tells the agent
+ * what is valid instead of silently returning empty objects); deeper segments
+ * that don't exist are simply omitted.
+ */
+export declare function projectResults(results: readonly unknown[], paths: readonly string[], validFields: readonly string[]): unknown[];

package/dist/select.js

@@ -0,0 +1,89 @@
+/**
+ * Field projection for MCP search tools (issue #10).
+ *
+ * Agents pass `select`, an array of dot-notation paths, to keep only the
+ * fields they need from each result — full search responses are token-heavy
+ * for LLM loops. A path segment that lands on an array projects each element
+ * (`promotions.description` keeps the description of every promotion).
+ */
+// Record<keyof T, true> so adding a model field without listing it here fails
+// to compile — the valid-field lists can't drift from the interfaces.
+const SEARCH_RESULT_KEYS = {
+    sku: true,
+    tpnb: true,
+    title: true,
+    brand: true,
+    imageUrl: true,
+    price: true,
+    available: true,
+    onOffer: true,
+    promotions: true,
+    quantityRules: true,
+};
+export const SEARCH_RESULT_FIELDS = Object.keys(SEARCH_RESULT_KEYS);
+// `raw` is excluded: MCP outputs strip it at serialisation (issue #9), so
+// offering it as a select field would advertise a field that never appears.
+const PRODUCT_KEYS = {
+    sku: true,
+    tpnb: true,
+    title: true,
+    brand: true,
+    imageUrl: true,
+    price: true,
+    available: true,
+    packSize: true,
+    promotions: true,
+    nutrition: true,
+    macros: true,
+    quantityRules: true,
+};
+export const PRODUCT_FIELDS = Object.keys(PRODUCT_KEYS);
+function buildTree(paths, validFields) {
+    const root = {};
+    for (const path of paths) {
+        const segments = path.split(".");
+        if (segments.some((s) => s === "")) {
+            throw new RangeError(`select path "${path}" has an empty segment`);
+        }
+        const head = segments[0] ?? "";
+        if (!validFields.includes(head)) {
+            throw new RangeError(`unknown select field "${head}" — valid fields: ${validFields.join(", ")}`);
+        }
+        let node = root;
+        for (const [i, seg] of segments.entries()) {
+            if (node[seg] === null)
+                break; // an ancestor path already keeps everything here
+            if (i === segments.length - 1) {
+                node[seg] = null; // keep-all wins over any deeper paths seen earlier
+            }
+            else {
+                node = node[seg] ??= {};
+            }
+        }
+    }
+    return root;
+}
+function apply(value, tree) {
+    if (tree === null)
+        return value;
+    if (Array.isArray(value))
+        return value.map((v) => apply(v, tree));
+    if (typeof value !== "object" || value === null)
+        return value;
+    const out = {};
+    for (const [key, sub] of Object.entries(tree)) {
+        if (key in value)
+            out[key] = apply(value[key], sub);
+    }
+    return out;
+}
+/**
+ * Project each result down to `paths`. Throws `RangeError` on a path whose
+ * first segment is not in `validFields` (so a mistyped field tells the agent
+ * what is valid instead of silently returning empty objects); deeper segments
+ * that don't exist are simply omitted.
+ */
+export function projectResults(results, paths, validFields) {
+    const tree = buildTree(paths, validFields);
+    return results.map((r) => apply(r, tree));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "basketeer",
-  "version": "0.1.2",
+  "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",