basketeer 0.1.0

package/dist/cli.js

@@ -0,0 +1,211 @@
+#!/usr/bin/env node
+/**
+ * `basketeer` — a thin CLI over the basketeer SDK.
+ *
+ * Reads work anonymously; writes (basket / slots / orders / checkout) resume a
+ * persisted session via {@link FileTokenStore} and, for `login`, mint one with
+ * {@link BrowserAuthBackend}. Results print as JSON to stdout; coded errors go
+ * to stderr with a non-zero exit. Per the SDK's ethics ceiling, `checkout` only
+ * hands back a payment URL — a human completes payment in a browser.
+ */
+import { fileURLToPath } from "node:url";
+import { Command, InvalidArgumentError } from "commander";
+import { BrowserAuthBackend } from "./auth/browser/playwright.js";
+import { Basketeer, BasketeerError, FileTokenStore } from "./index.js";
+/** Pretty-print any JSON-serialisable value to stdout. */
+function emit(value) {
+    process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+}
+/** commander parser: a non-negative integer, else a usage error. */
+export function nonNegativeInt(value) {
+    const n = Number(value);
+    if (!Number.isInteger(n) || n < 0)
+        throw new InvalidArgumentError("must be a non-negative integer");
+    return n;
+}
+/** commander parser: a non-negative number (decimals allowed), else a usage error. */
+export function nonNegativeNumber(value) {
+    const n = Number(value);
+    if (!Number.isFinite(n) || n < 0)
+        throw new InvalidArgumentError("must be a non-negative number");
+    return n;
+}
+const store = new FileTokenStore();
+/** Resume a persisted session for authenticated commands (refreshing if able). */
+function authedClient() {
+    return Basketeer.resume({ store, authBackend: new BrowserAuthBackend() });
+}
+/** Anonymous client for read-only commands (no session required). */
+function readClient() {
+    return new Basketeer();
+}
+const program = new Command();
+program
+    .name("basketeer")
+    .description("Typed CLI for Tesco grocery automation (basketeer).")
+    .showHelpAfterError();
+// --- auth -------------------------------------------------------------------
+program
+    .command("login")
+    .description("Open a real Chrome to sign in, then persist the harvested session.")
+    .action(async () => {
+    const client = new Basketeer({ store, authBackend: new BrowserAuthBackend() });
+    const session = await client.login();
+    emit({
+        ok: true,
+        customerUuid: session.customerUuid,
+        expiresAt: session.accessTokenExpiry ?? null,
+    });
+});
+// --- reads (anonymous) ------------------------------------------------------
+program
+    .command("search")
+    .description("Search the catalogue.")
+    .argument("<query>", "search terms")
+    .option("--limit <n>", "max results", nonNegativeInt, 10)
+    .option("--min-protein <g>", "only products with at least this protein per 100g/ml", nonNegativeNumber)
+    .option("--max-sugar <g>", "only products with at most this sugar per 100g/ml", nonNegativeNumber)
+    .option("--sort <field>", "sort hydrated results by a macro (e.g. protein)")
+    .option("--hydrate <n>", "max results to fetch nutrition for (default 20)", nonNegativeInt)
+    .action(async (query, opts) => {
+    const usesNutrition = opts.minProtein != null || opts.maxSugar != null || opts.sort != null;
+    if (usesNutrition) {
+        const where = {};
+        if (opts.minProtein != null)
+            where.protein = { min: opts.minProtein };
+        if (opts.maxSugar != null)
+            where.sugars = { max: opts.maxSugar };
+        const sort = opts.sort ? { by: opts.sort, dir: "desc" } : undefined;
+        emit(await readClient().searchByNutrition(query, {
+            where,
+            sort,
+            hydrate: opts.hydrate,
+            limit: opts.limit,
+        }));
+        return;
+    }
+    emit(await readClient().search(query, { limit: opts.limit }));
+});
+program
+    .command("product")
+    .description("Look up a single product by SKU (tpnc).")
+    .argument("<sku>", "product SKU / tpnc")
+    .action(async (sku) => {
+    emit(await readClient().getProduct(sku));
+});
+program
+    .command("nutrition")
+    .argument("<sku>", "product SKU (tpnc)")
+    .description("Print normalized nutrition (macros + micros) for a product.")
+    .action(async (sku) => {
+    emit((await readClient().getProduct(sku)).nutrition);
+});
+program
+    .command("favourites")
+    .description("List the customer's favourites (requires a session).")
+    .option("--limit <n>", "max results", nonNegativeInt, 50)
+    .action(async (opts) => {
+    const client = await authedClient();
+    emit(await client.favourites({ limit: opts.limit }));
+});
+// --- basket -----------------------------------------------------------------
+const basket = program.command("basket").description("Inspect and edit the basket.");
+basket
+    .command("get")
+    .description("Show the current basket.")
+    .action(async () => {
+    const client = await authedClient();
+    emit(await client.basket.get());
+});
+basket
+    .command("add")
+    .description("Add <qty> (default 1) of a product to the basket (increments the line).")
+    .argument("<sku>", "product SKU / tpnc")
+    .argument("[qty]", "quantity to add", nonNegativeInt, 1)
+    .action(async (sku, qty) => {
+    const client = await authedClient();
+    emit(await client.basket.add(sku, qty));
+});
+basket
+    .command("set")
+    .description("Set a basket line to an exact quantity (0 removes it).")
+    .argument("<sku>", "product SKU / tpnc")
+    .argument("<qty>", "exact quantity", nonNegativeInt)
+    .action(async (sku, qty) => {
+    const client = await authedClient();
+    emit(await client.basket.set(sku, qty));
+});
+basket
+    .command("remove")
+    .description("Remove a line from the basket.")
+    .argument("<sku>", "product SKU / tpnc")
+    .action(async (sku) => {
+    const client = await authedClient();
+    emit(await client.basket.remove(sku));
+});
+// --- slots ------------------------------------------------------------------
+program
+    .command("slots")
+    .description("List delivery slots (or collection slots with --collection).")
+    .option("--collection", "list click-and-collect slots instead of delivery")
+    .action(async (opts) => {
+    const client = await authedClient();
+    emit(opts.collection ? await client.slots.listCollection() : await client.slots.list());
+});
+// --- orders -----------------------------------------------------------------
+const orders = program.command("orders").description("Inspect and manage orders.");
+orders
+    .command("list")
+    .description("List upcoming orders.")
+    .action(async () => {
+    const client = await authedClient();
+    emit(await client.orders.list());
+});
+orders
+    .command("cancel")
+    .description("Cancel an order by order number.")
+    .argument("<orderNo>", "order number")
+    .action(async (orderNo) => {
+    const client = await authedClient();
+    await client.orders.cancel(orderNo);
+    emit({ ok: true, cancelled: orderNo });
+});
+orders
+    .command("reorder")
+    .description("Re-add the last delivered order's items to the basket.")
+    .action(async () => {
+    const client = await authedClient();
+    const last = await client.orders.lastFulfilled();
+    if (!last) {
+        emit({ ok: false, reason: "no previous fulfilled order" });
+        return;
+    }
+    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 });
+});
+// --- checkout ---------------------------------------------------------------
+program
+    .command("checkout")
+    .description("Prepare checkout and print the payment URL (a human completes payment).")
+    .action(async () => {
+    const client = await authedClient();
+    const { basket: cart, url } = await client.checkout();
+    emit({
+        basket: cart,
+        paymentUrl: url,
+        note: "Payment is browser-bound (3-D Secure). Open paymentUrl and complete payment yourself — the CLI never pays.",
+    });
+});
+// --- entrypoint -------------------------------------------------------------
+// Only parse argv when run as a binary, so the module is importable (tests).
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+    program.parseAsync().catch((err) => {
+        const name = err instanceof BasketeerError ? err.name : "Error";
+        const message = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`${name}: ${message}\n`);
+        process.exit(1);
+    });
+}

package/dist/client.d.ts

@@ -0,0 +1,167 @@
+import type { AuthBackend, Credentials } from "./auth/types.js";
+import type { Basket, 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 {
+    /** A ready-made session (e.g. harvested elsewhere). */
+    session?: Session | null;
+    /** Persists/loads the session. */
+    store?: TokenStore;
+    /** Mints/renews sessions (browser-driven in v1). */
+    authBackend?: AuthBackend;
+    /** Override the public api key (it rotates ~monthly). */
+    apiKey?: string;
+    /** Min gap between requests, ms. Default 1000 (polite). */
+    throttleMs?: number;
+    /** Injected for tests; defaults to global fetch. */
+    fetchImpl?: typeof fetch;
+}
+/** A raw basket line input for the low-level `basket.update`. */
+export interface BasketItemInput {
+    id: string;
+    newValue: number;
+    newUnitChoice?: string;
+    adjustment?: boolean;
+    substitutionOption?: string;
+}
+/**
+ * A handle to an order opened for amendment (see {@link Basketeer.orders}.amend).
+ * Its basket ops apply to the amended order; finish by checking out again, or
+ * `discard()` to leave the order unchanged.
+ */
+export interface Amendment {
+    readonly orderNo: string;
+    /** The order's working basket while amending. */
+    get(): Promise<Basket>;
+    /** Set a line to an exact quantity (0 removes) on the amended order. */
+    set(sku: string, quantity: number, unit?: string): Promise<Basket>;
+    /** Remove a line from the amended order. */
+    remove(sku: string): Promise<Basket>;
+    /** Abandon the amendment, leaving the order unchanged. */
+    discard(): Promise<void>;
+}
+export declare class Basketeer {
+    private readonly transport;
+    private readonly sessions;
+    private _amendingOrderNo;
+    constructor(opts?: BasketeerOptions);
+    /** Resume a persisted session, refreshing proactively if it has expired. */
+    static resume(opts?: BasketeerOptions): Promise<Basketeer>;
+    /** Mint a new session via the configured AuthBackend. */
+    login(credentials?: Credentials): Promise<Session>;
+    /** The current session, or null if unauthenticated. */
+    get session(): Session | null;
+    /** True when a (non-expired) session is loaded. */
+    get isAuthenticated(): boolean;
+    /** The order currently open for amendment via `orders.amend`, if any. */
+    get amendingOrderNo(): string | null;
+    getProduct(sku: string): Promise<Product>;
+    search(query: string, opts?: {
+        limit?: number;
+        page?: number;
+    }): Promise<SearchPage>;
+    /**
+     * Keyword search, then hydrate the top `hydrate` results' nutrition (each a throttled
+     * product fetch) and filter/rank locally. The cost is bounded by `hydrate` (default 20)
+     * and reported honestly: `hydrated` is how many products were fetched, `failed` how many
+     * detail fetches errored (and were skipped, not fatal), and `hasMore` whether the
+     * catalogue had more keyword matches than were hydrated.
+     */
+    searchByNutrition(query: string, opts?: {
+        where?: NutritionFilter;
+        sort?: NutritionSort;
+        hydrate?: number;
+        limit?: number;
+    }): Promise<{
+        results: Product[];
+        hydrated: number;
+        failed: number;
+        hasMore: boolean;
+    }>;
+    /**
+     * List products in a category. Build `facet` with {@link categoryFacet} (or
+     * lift it from a Tesco category-page URL `?...&facet=…`).
+     */
+    browseCategory(facet: string, opts?: {
+        limit?: number;
+        page?: number;
+    }): Promise<SearchPage>;
+    /** The customer's favourites ("my usuals"). */
+    favourites(opts?: {
+        limit?: number;
+        page?: number;
+    }): Promise<SearchPage>;
+    /** Shared paging: map nodes → SearchResult, drop nulls, derive `hasMore`. */
+    private page;
+    readonly basket: {
+        get: () => Promise<Basket>;
+        /**
+         * Increment the line for `sku` by `quantity` (default 1). Reads the current
+         * quantity first, so it costs an extra request and is not safe under
+         * concurrent edits — use `set` for exact, idempotent quantities.
+         */
+        add: (sku: string, quantity?: number, unit?: string) => Promise<Basket>;
+        /** Set the line for `sku` to an exact `quantity` (0 removes it). */
+        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>;
+    };
+    private getBasket;
+    private updateBasket;
+    readonly orders: {
+        /** List upcoming (pending) orders with their items, slot, and amend window. */
+        list: (opts?: {
+            contexts?: readonly OrderContext[];
+        }) => Promise<Order[]>;
+        /**
+         * Open an order for amendment. Returns an {@link Amendment} handle whose
+         * basket ops apply to THAT order; finish by checking out again, or call
+         * `discard()`. Only works before the order's `amendExpiry`. While amending,
+         * `client.amendingOrderNo` reports the open order.
+         */
+        amend: (orderNo: string) => Promise<Amendment>;
+        /** Cancel an order outright (before its amend/cancel cutoff). */
+        cancel: (orderNo: string) => Promise<void>;
+        /** The last delivered order (its items), for "reorder my usual shop". */
+        lastFulfilled: () => Promise<Order | null>;
+    };
+    private amendOrder;
+    private cancelOrder;
+    private lastFulfilledOrder;
+    private listOrders;
+    private orderAction;
+    /**
+     * Prepare for payment. Returns the current basket and the URL where payment
+     * is completed **in a browser**. basketeer deliberately stops here:
+     * Tesco's payment step is a separate CSRF-protected checkout app + 3-D Secure
+     * card authentication — browser-bound by design and PCI/fraud-sensitive. Fill
+     * the basket and book a slot via this SDK, then complete payment at `url`.
+     */
+    checkout(): Promise<{
+        basket: Basket;
+        url: string;
+    }>;
+    readonly slots: {
+        /** List delivery slots over a date window (default today..+6 days). */
+        list: (opts?: {
+            start?: string;
+            end?: string;
+            type?: FulfilmentType;
+        }) => Promise<Slot[]>;
+        /** List click-and-collect slots for a store (`locationUuid`); default today..+6 days. */
+        listCollection: (opts?: {
+            start?: string;
+            end?: string;
+            locationUuid?: string;
+        }) => Promise<Slot[]>;
+        /** Reserve a slot by id. Held until `reservationExpiry`; check out before then. */
+        book: (slotId: string) => Promise<BookedSlot>;
+        /** Release a previously-reserved slot. */
+        release: (slotId: string) => Promise<BookedSlot>;
+    };
+    private listSlots;
+    private listCollectionSlots;
+    private fulfilment;
+}