basketeer 0.1.2 → 0.2.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`
@@ -196,7 +200,7 @@ for (const it of last?.items ?? []) await client.basket.set(it.productId!, it.qu
 
 ## 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, 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,8 @@ 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;
 /** A raw basket line input for the low-level `basket.update`. */
 export interface BasketItemInput {
     id: string;
@@ -56,6 +58,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,10 +112,16 @@ 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. */

package/dist/client.js

@@ -1,10 +1,12 @@
-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 { 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_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;
 /** 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 +87,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 +198,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 +224,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,9 +247,21 @@ 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 = {

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,11 +1,11 @@
 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_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, 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";

package/dist/index.js

@@ -1,9 +1,9 @@
 // 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_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";

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;

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,6 +3,8 @@
  * 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;

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 }

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.2.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",