vilgain-mcp 0.1.0

package/dist/tools/product-variants.js

@@ -0,0 +1,41 @@
+import { z } from 'zod';
+import { errorResult, textResult } from './helpers.js';
+export function createProductVariantsTool(api) {
+    return {
+        name: 'get_product_variants',
+        definition: {
+            title: 'Get Product Variants',
+            description: 'List all purchasable variants (flavors/sizes) of a Vilgain product with prices, availability and variant IDs. ' +
+                'Use this to pick a variant before add_to_cart. For ingredients and nutrition facts use get_product_detail instead.',
+            inputSchema: {
+                product_url: z
+                    .string()
+                    .min(1)
+                    .describe('Product URL from search_products, e.g. "https://vilgain.cz/vilgain-whey-protein-2"'),
+            },
+            annotations: {
+                readOnlyHint: true,
+                openWorldHint: true,
+            },
+        },
+        handler: async ({ product_url }) => {
+            try {
+                const detail = await api.getProductDetail(product_url);
+                if (detail.variants.length === 0) {
+                    return textResult(`No variants found for ${detail.name} - the product may be unavailable.`);
+                }
+                const variants = detail.variants
+                    .map((v) => {
+                    const stock = v.inStock ? '' : ' | OUT OF STOCK';
+                    return `• ${v.name} – ${v.price} ${v.currency}${stock}\n  Variant ID: ${v.variantId}`;
+                })
+                    .join('\n');
+                return textResult(`# ${detail.name}\n\nVariants (use Variant ID with add_to_cart):\n${variants}`);
+            }
+            catch (error) {
+                return errorResult(error);
+            }
+        },
+    };
+}
+//# sourceMappingURL=product-variants.js.map

package/dist/tools/product-variants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"product-variants.js","sourceRoot":"","sources":["../../src/tools/product-variants.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAEvD,MAAM,UAAU,yBAAyB,CAAC,GAAe;IACvD,OAAO;QACL,IAAI,EAAE,sBAAsB;QAC5B,UAAU,EAAE;YACV,KAAK,EAAE,sBAAsB;YAC7B,WAAW,EACT,gHAAgH;gBAChH,oHAAoH;YACtH,WAAW,EAAE;gBACX,WAAW,EAAE,CAAC;qBACX,MAAM,EAAE;qBACR,GAAG,CAAC,CAAC,CAAC;qBACN,QAAQ,CAAC,oFAAoF,CAAC;aAClG;YACD,WAAW,EAAE;gBACX,YAAY,EAAE,IAAI;gBAClB,aAAa,EAAE,IAAI;aACpB;SACF;QACD,OAAO,EAAE,KAAK,EAAE,EAAE,WAAW,EAA2B,EAAE,EAAE;YAC1D,IAAI,CAAC;gBACH,MAAM,MAAM,GAAG,MAAM,GAAG,CAAC,gBAAgB,CAAC,WAAW,CAAC,CAAC;gBACvD,IAAI,MAAM,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;oBACjC,OAAO,UAAU,CAAC,yBAAyB,MAAM,CAAC,IAAI,oCAAoC,CAAC,CAAC;gBAC9F,CAAC;gBACD,MAAM,QAAQ,GAAG,MAAM,CAAC,QAAQ;qBAC7B,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;oBACT,MAAM,KAAK,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,iBAAiB,CAAC;oBACjD,OAAO,KAAK,CAAC,CAAC,IAAI,MAAM,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,QAAQ,GAAG,KAAK,mBAAmB,CAAC,CAAC,SAAS,EAAE,CAAC;gBACxF,CAAC,CAAC;qBACD,IAAI,CAAC,IAAI,CAAC,CAAC;gBACd,OAAO,UAAU,CAAC,KAAK,MAAM,CAAC,IAAI,oDAAoD,QAAQ,EAAE,CAAC,CAAC;YACpG,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,OAAO,WAAW,CAAC,KAAK,CAAC,CAAC;YAC5B,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/tools/search-products.d.ts

@@ -0,0 +1,27 @@
+import { z } from 'zod';
+import { VilgainAPI } from '../vilgain-api.js';
+export declare function createSearchProductsTool(api: VilgainAPI): {
+    name: string;
+    definition: {
+        title: string;
+        description: string;
+        inputSchema: {
+            query: z.ZodString;
+            limit: z.ZodDefault<z.ZodNumber>;
+        };
+        annotations: {
+            readOnlyHint: boolean;
+            openWorldHint: boolean;
+        };
+    };
+    handler: ({ query, limit }: {
+        query: string;
+        limit?: number;
+    }) => Promise<{
+        content: Array<{
+            type: "text";
+            text: string;
+        }>;
+        isError?: boolean;
+    }>;
+};

package/dist/tools/search-products.js

@@ -0,0 +1,43 @@
+import { z } from 'zod';
+import { errorResult, textResult } from './helpers.js';
+export function createSearchProductsTool(api) {
+    return {
+        name: 'search_products',
+        definition: {
+            title: 'Search Products',
+            description: 'Search for products on Vilgain by name or keyword. Returns product names, prices, ratings, product URLs and ' +
+                'the Variant ID of the displayed variant, which can be passed directly to add_to_cart. ' +
+                'To pick a different flavor/size, call get_product_variants with the product URL first.',
+            inputSchema: {
+                query: z.string().min(1).describe('Search term, e.g. "whey protein" or "arašídové máslo"'),
+                limit: z.number().int().min(1).max(30).default(10).describe('Maximum number of results (default 10)'),
+            },
+            annotations: {
+                readOnlyHint: true,
+                openWorldHint: true,
+            },
+        },
+        handler: async ({ query, limit }) => {
+            try {
+                const products = await api.searchProducts(query, limit ?? 10);
+                if (products.length === 0) {
+                    return textResult(`No products found for "${query}".`);
+                }
+                const output = products
+                    .map((p) => {
+                    const price = p.price !== undefined ? `${p.price} ${p.currency}` : 'price unavailable';
+                    const rating = p.rating ? ` | Rating: ${p.rating} (${p.reviewCount} reviews)` : '';
+                    const variant = p.defaultVariant ? ` | Shown variant: ${p.defaultVariant}` : '';
+                    const variantId = p.variantId !== undefined ? `\n  Variant ID (shown variant): ${p.variantId}` : '';
+                    return `• ${p.name}${p.subtitle ? ` – ${p.subtitle}` : ''}\n  Price: ${price}${variant}${rating}${variantId}\n  URL: ${p.url}`;
+                })
+                    .join('\n\n');
+                return textResult(`Found ${products.length} products for "${query}":\n\n${output}`);
+            }
+            catch (error) {
+                return errorResult(error);
+            }
+        },
+    };
+}
+//# sourceMappingURL=search-products.js.map

package/dist/tools/search-products.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-products.js","sourceRoot":"","sources":["../../src/tools/search-products.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAEvD,MAAM,UAAU,wBAAwB,CAAC,GAAe;IACtD,OAAO;QACL,IAAI,EAAE,iBAAiB;QACvB,UAAU,EAAE;YACV,KAAK,EAAE,iBAAiB;YACxB,WAAW,EACT,8GAA8G;gBAC9G,wFAAwF;gBACxF,wFAAwF;YAC1F,WAAW,EAAE;gBACX,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,uDAAuD,CAAC;gBAC1F,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,wCAAwC,CAAC;aACtG;YACD,WAAW,EAAE;gBACX,YAAY,EAAE,IAAI;gBAClB,aAAa,EAAE,IAAI;aACpB;SACF;QACD,OAAO,EAAE,KAAK,EAAE,EAAE,KAAK,EAAE,KAAK,EAAqC,EAAE,EAAE;YACrE,IAAI,CAAC;gBACH,MAAM,QAAQ,GAAG,MAAM,GAAG,CAAC,cAAc,CAAC,KAAK,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC;gBAC9D,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;oBAC1B,OAAO,UAAU,CAAC,0BAA0B,KAAK,IAAI,CAAC,CAAC;gBACzD,CAAC;gBACD,MAAM,MAAM,GAAG,QAAQ;qBACpB,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;oBACT,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,mBAAmB,CAAC;oBACvF,MAAM,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,WAAW,WAAW,CAAC,CAAC,CAAC,EAAE,CAAC;oBACnF,MAAM,OAAO,GAAG,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,qBAAqB,CAAC,CAAC,cAAc,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;oBAChF,MAAM,SAAS,GAAG,CAAC,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,mCAAmC,CAAC,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;oBACpG,OAAO,KAAK,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,cAAc,KAAK,GAAG,OAAO,GAAG,MAAM,GAAG,SAAS,YAAY,CAAC,CAAC,GAAG,EAAE,CAAC;gBACjI,CAAC,CAAC;qBACD,IAAI,CAAC,MAAM,CAAC,CAAC;gBAChB,OAAO,UAAU,CAAC,SAAS,QAAQ,CAAC,MAAM,kBAAkB,KAAK,SAAS,MAAM,EAAE,CAAC,CAAC;YACtF,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,OAAO,WAAW,CAAC,KAAK,CAAC,CAAC;YAC5B,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,124 @@
+export interface VilgainCredentials {
+    email: string;
+    password: string;
+}
+/** Product as listed in search results. One product groups multiple variants (flavors, sizes). */
+export interface SearchProduct {
+    /** Product group id (identifies the product family, not a purchasable variant) */
+    productId: number;
+    name: string;
+    /** Short marketing description shown under the product name */
+    subtitle?: string;
+    /** Name of the variant the listed price refers to, e.g. "Čokoláda 1 000 g" */
+    defaultVariant?: string;
+    /** Variant id of the displayed variant, usable directly with add_to_cart (best-effort) */
+    variantId?: number;
+    /** Absolute URL of the product detail page */
+    url: string;
+    /** Current price of the default variant (VAT included) */
+    price?: number;
+    currency?: string;
+    /** Rating like "4.6/5" */
+    rating?: string;
+    reviewCount?: number;
+}
+/** A purchasable product variant (specific flavor + size). */
+export interface ProductVariant {
+    /** Variant id used by cart operations */
+    variantId: number;
+    /** Variant name, e.g. "Čokoláda 1 000 g" */
+    name: string;
+    url: string;
+    price: number;
+    currency: string;
+    inStock: boolean;
+    gtin?: string;
+}
+export interface NutritionRow {
+    /** e.g. "Energetická hodnota", "Bílkoviny" */
+    label: string;
+    /** Values in the same order as NutritionTable.columns */
+    values: string[];
+}
+export interface NutritionTable {
+    /** Column headers, e.g. ["100 g", "30 g"] */
+    columns: string[];
+    rows: NutritionRow[];
+}
+export interface ProductDetail {
+    name: string;
+    url: string;
+    /** Marketing description from page metadata */
+    shortDescription?: string;
+    /** Full description text from the "Popis" tab */
+    description?: string;
+    /** Ingredients text including allergen notes (for the variant selected by the URL) */
+    ingredients?: string;
+    /** Dosage / usage instructions */
+    dosage?: string;
+    /** Nutrition facts tables (values per 100 g and per serving) */
+    nutrition: NutritionTable[];
+    rating?: string;
+    reviewCount?: number;
+    variants: ProductVariant[];
+    /** Id of the variant the page content (ingredients, nutrition) refers to */
+    selectedVariantId?: number;
+}
+export interface CartItem {
+    variantId: number;
+    productName: string;
+    /** Variant name, e.g. "1 000 g" or "jahoda 1 000 g" */
+    variant?: string;
+    quantity: number;
+    /** Unit price with VAT */
+    price: number;
+    currency: string;
+}
+export interface CartContent {
+    items: CartItem[];
+    /** Cart total with VAT */
+    totalWithVat?: number;
+    currency?: string;
+}
+export interface OrderSummary {
+    /** Order id/number as displayed by the shop */
+    id: string;
+    url?: string;
+    /** ISO date (YYYY-MM-DD) */
+    date?: string;
+    /** e.g. "Vyřízeno", "Stornováno" */
+    state?: string;
+    total?: number;
+    currency?: string;
+    /** Product names in the order (from the list page thumbnails) */
+    productNames: string[];
+}
+export interface OrderItem {
+    name: string;
+    /** e.g. "Příchuť: křupavé mandle" */
+    variant?: string;
+    /** Variant id usable with add_to_cart (to reorder the item) */
+    variantId?: number;
+    quantity?: number;
+    /** Line price with VAT */
+    price?: number;
+    currency?: string;
+    /** Product page URL */
+    url?: string;
+}
+export interface OrderTimelineEvent {
+    /** e.g. "Zásilka byla doručena" */
+    event: string;
+    /** e.g. "11. 08. 2026 16:14" */
+    date?: string;
+}
+export interface OrderDetail {
+    orderNumber: string;
+    items: OrderItem[];
+    totalWithVat?: number;
+    currency?: string;
+    /** Shipment status history, most recent first */
+    timeline: OrderTimelineEvent[];
+    /** Delivery destination (pickup point or address) */
+    deliveryAddress?: string;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/dist/validate-api.d.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+/**
+ * Live smoke test against the real Vilgain website.
+ * Run with `npm run validate-api` (requires credentials in .env).
+ *
+ * Exercises every API method end to end and cleans up after itself
+ * (anything it adds to the cart is removed again).
+ */
+export {};

package/dist/validate-api.js

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+/**
+ * Live smoke test against the real Vilgain website.
+ * Run with `npm run validate-api` (requires credentials in .env).
+ *
+ * Exercises every API method end to end and cleans up after itself
+ * (anything it adds to the cart is removed again).
+ */
+import { VilgainAPI } from './vilgain-api.js';
+const email = process.env.VILGAIN_EMAIL;
+const password = process.env.VILGAIN_PASSWORD;
+if (!email || !password) {
+    console.error('VILGAIN_EMAIL and VILGAIN_PASSWORD are required (put them in .env)');
+    process.exit(1);
+}
+const api = new VilgainAPI({ email, password }, process.env.VILGAIN_BASE_URL || 'https://vilgain.cz');
+let failures = 0;
+async function step(name, fn) {
+    try {
+        const result = await fn();
+        console.log(`✓ ${name}`);
+        return result;
+    }
+    catch (error) {
+        failures++;
+        console.error(`✗ ${name}: ${error instanceof Error ? error.message : String(error)}`);
+        return undefined;
+    }
+}
+function assert(condition, message) {
+    if (!condition)
+        throw new Error(message);
+}
+await step('login', () => api.login());
+const products = await step('searchProducts("protein")', async () => {
+    const results = await api.searchProducts('protein', 5);
+    assert(results.length > 0, 'no search results');
+    assert(results[0].url.startsWith('http'), 'missing product url');
+    assert(results[0].price !== undefined, 'missing price');
+    assert(results[0].variantId !== undefined, 'missing displayed variant id');
+    return results;
+});
+const detail = products
+    ? await step(`getProductDetail(${products[0].name})`, async () => {
+        const d = await api.getProductDetail(products[0].url);
+        assert(d.variants.length > 0, 'no variants parsed');
+        assert(d.ingredients, 'no ingredients parsed');
+        assert(d.nutrition.length > 0, 'no nutrition table parsed');
+        return d;
+    })
+    : undefined;
+if (detail && products) {
+    const otherVariant = detail.variants.find((v) => v.inStock && v.variantId !== detail.selectedVariantId);
+    if (otherVariant) {
+        await step(`getProductDetail(variant ${otherVariant.variantId})`, async () => {
+            const variantDetail = await api.getProductDetail(products[0].url, otherVariant.variantId);
+            assert(variantDetail.selectedVariantId === otherVariant.variantId, 'wrong variant selected');
+            assert(variantDetail.ingredients, 'no ingredients for variant');
+        });
+    }
+}
+const variant = detail?.variants.find((v) => v.inStock);
+if (variant) {
+    await step(`addToCart(${variant.variantId} = ${variant.name}, quantity 2)`, async () => {
+        const cart = await api.addToCart(variant.variantId, 2);
+        const item = cart.items.find((i) => i.variantId === variant.variantId);
+        assert(item, 'item not in cart after add');
+    });
+    await step(`setCartItemQuantity(${variant.variantId}, 1)`, async () => {
+        const cart = await api.setCartItemQuantity(variant.variantId, 1);
+        const item = cart.items.find((i) => i.variantId === variant.variantId);
+        assert(item?.quantity === 1, `expected quantity 1, got ${item?.quantity}`);
+    });
+    await step(`removeFromCart(${variant.variantId})`, async () => {
+        const cart = await api.removeFromCart(variant.variantId);
+        assert(!cart.items.some((i) => i.variantId === variant.variantId), 'item still in cart after remove');
+    });
+}
+await step('getCart', async () => {
+    await api.getCart();
+});
+const history = await step('getOrderHistory', async () => api.getOrderHistory());
+if (history && history.orders.length > 0) {
+    await step(`getOrderDetail(${history.orders[0].id})`, async () => {
+        const detail = await api.getOrderDetail(history.orders[0].id);
+        assert(detail.orderNumber === history.orders[0].id, 'order number mismatch');
+        assert(detail.items.length > 0, 'no items parsed');
+        assert(detail.totalWithVat !== undefined, 'no total parsed');
+        assert(detail.timeline.length > 0, 'no timeline parsed');
+    });
+}
+else {
+    console.log('- getOrderDetail skipped (account has no orders)');
+}
+console.log(failures === 0 ? '\nAll checks passed.' : `\n${failures} check(s) failed.`);
+process.exit(failures === 0 ? 0 : 1);
+//# sourceMappingURL=validate-api.js.map

package/dist/validate-api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-api.js","sourceRoot":"","sources":["../src/validate-api.ts"],"names":[],"mappings":"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"}

package/dist/vilgain-api.d.ts

@@ -0,0 +1,60 @@
+import { CartContent, OrderDetail, OrderSummary, ProductDetail, SearchProduct, VilgainCredentials } from './types.js';
+export declare class VilgainAPIError extends Error {
+    status?: number | undefined;
+    constructor(message: string, status?: number | undefined);
+}
+/**
+ * Client for the reverse engineered Vilgain.cz web endpoints.
+ *
+ * Vilgain has no public JSON API; the website is a server-rendered Nette
+ * application. This client talks to the same endpoints the website's own
+ * frontend uses (Nette "signals" via the `_do` form field) and parses data
+ * out of the returned HTML/JSON. See docs/api.md for the endpoint map.
+ */
+export declare class VilgainAPI {
+    private credentials;
+    readonly baseUrl: string;
+    private cookies;
+    private loggedIn;
+    private lastRequestTime;
+    private readonly minRequestInterval;
+    constructor(credentials: VilgainCredentials, baseUrl?: string);
+    private rateLimit;
+    private storeCookies;
+    private request;
+    /** Log in and store the session cookie. Called automatically when needed. */
+    login(): Promise<void>;
+    private ensureLoggedIn;
+    /**
+     * Fetch a page that requires authentication. If the session has expired
+     * (the server redirects to the login page), re-login and retry once.
+     */
+    private getAuthenticatedPage;
+    /** Full-text product search. */
+    searchProducts(query: string, limit?: number): Promise<SearchProduct[]>;
+    /**
+     * Fetch and parse a product detail page. Accepts absolute or relative product URLs.
+     * With `variantId`, the page of that specific variant is fetched instead of the
+     * default one (the router resolves `/<product-slug>/<anything>-<variantId>`).
+     */
+    getProductDetail(productUrl: string, variantId?: number): Promise<ProductDetail>;
+    /** Get current cart content. */
+    getCart(): Promise<CartContent>;
+    /**
+     * Add a product variant to the cart. Each call adds `quantity` more pieces
+     * (the shop's add-to-cart adds one; larger quantities are set explicitly
+     * afterwards). Returns the updated cart.
+     */
+    addToCart(variantId: number, quantity?: number): Promise<CartContent>;
+    /** Set the absolute quantity of a cart item. Returns the updated cart. */
+    setCartItemQuantity(variantId: number, quantity: number): Promise<CartContent>;
+    /** Remove an item from the cart. Returns the updated cart. */
+    removeFromCart(variantId: number): Promise<CartContent>;
+    /** List past orders (most recent first, as displayed by the shop). */
+    getOrderHistory(): Promise<{
+        orders: OrderSummary[];
+        empty: boolean;
+    }>;
+    /** Get one order's items, total, delivery destination and shipment timeline. */
+    getOrderDetail(orderId: string): Promise<OrderDetail>;
+}

package/dist/vilgain-api.js

@@ -0,0 +1,238 @@
+import { parseCart } from './parsers/cart.js';
+import { isOrderHistoryEmpty, parseOrderDetail, parseOrderHistory } from './parsers/orders.js';
+import { parseProductDetail } from './parsers/product.js';
+import { parseSearchResults } from './parsers/search.js';
+export class VilgainAPIError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+        this.name = 'VilgainAPIError';
+    }
+}
+const USER_AGENT = 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36';
+/**
+ * Client for the reverse engineered Vilgain.cz web endpoints.
+ *
+ * Vilgain has no public JSON API; the website is a server-rendered Nette
+ * application. This client talks to the same endpoints the website's own
+ * frontend uses (Nette "signals" via the `_do` form field) and parses data
+ * out of the returned HTML/JSON. See docs/api.md for the endpoint map.
+ */
+export class VilgainAPI {
+    credentials;
+    baseUrl;
+    cookies = new Map();
+    loggedIn = false;
+    lastRequestTime = 0;
+    minRequestInterval = 100;
+    constructor(credentials, baseUrl = 'https://vilgain.cz') {
+        this.credentials = credentials;
+        this.baseUrl = baseUrl;
+    }
+    async rateLimit() {
+        const elapsed = Date.now() - this.lastRequestTime;
+        if (elapsed < this.minRequestInterval) {
+            await new Promise((resolve) => setTimeout(resolve, this.minRequestInterval - elapsed));
+        }
+        this.lastRequestTime = Date.now();
+    }
+    storeCookies(response) {
+        for (const cookie of response.headers.getSetCookie()) {
+            const [pair] = cookie.split(';');
+            const eq = pair.indexOf('=');
+            if (eq > 0) {
+                this.cookies.set(pair.slice(0, eq).trim(), pair.slice(eq + 1).trim());
+            }
+        }
+    }
+    async request(path, options = {}) {
+        await this.rateLimit();
+        const url = new URL(path, this.baseUrl).href;
+        const headers = {
+            'User-Agent': USER_AGENT,
+            'Accept-Language': 'cs,en;q=0.8',
+            // The site's own AJAX layer sends this header; without it some
+            // requests can be challenged by the WAF.
+            'x-vilgain-waf-bypass': 'naja-shop',
+        };
+        if (options.ajax) {
+            headers['X-Requested-With'] = 'XMLHttpRequest';
+            headers['Accept'] = '*/*';
+        }
+        if (this.cookies.size > 0) {
+            headers['Cookie'] = [...this.cookies.entries()].map(([k, v]) => `${k}=${v}`).join('; ');
+        }
+        let body;
+        if (options.form) {
+            body = new FormData();
+            for (const [key, value] of Object.entries(options.form)) {
+                body.append(key, value);
+            }
+        }
+        let response;
+        try {
+            response = await fetch(url, {
+                method: options.method ?? (options.form ? 'POST' : 'GET'),
+                headers,
+                body,
+            });
+        }
+        catch (error) {
+            throw new VilgainAPIError(`Request to ${url} failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        this.storeCookies(response);
+        if (response.status === 202) {
+            throw new VilgainAPIError('Request was challenged by the site\'s bot protection (HTTP 202). Try again later.', 202);
+        }
+        if (!response.ok) {
+            throw new VilgainAPIError(`Request to ${url} failed with HTTP ${response.status}`, response.status);
+        }
+        return response;
+    }
+    /** Log in and store the session cookie. Called automatically when needed. */
+    async login() {
+        // Initial GET establishes the session cookies the login form expects.
+        await this.request('/prihlaseni');
+        const response = await this.request('/prihlaseni', {
+            ajax: true,
+            form: {
+                email: this.credentials.email,
+                password: this.credentials.password,
+                _do: 'modalStack-loginModal-form-submit',
+                ok: 'Přihlásit',
+            },
+        });
+        const result = (await response.json());
+        // On success the server redirects away from the login page;
+        // on bad credentials it redirects back to it.
+        if (!result.redirect || result.redirect.includes('/prihlaseni')) {
+            throw new VilgainAPIError('Login failed - check VILGAIN_EMAIL and VILGAIN_PASSWORD');
+        }
+        this.loggedIn = true;
+    }
+    async ensureLoggedIn() {
+        if (!this.loggedIn) {
+            await this.login();
+        }
+    }
+    /**
+     * Fetch a page that requires authentication. If the session has expired
+     * (the server redirects to the login page), re-login and retry once.
+     */
+    async getAuthenticatedPage(path) {
+        await this.ensureLoggedIn();
+        let response = await this.request(path);
+        if (new URL(response.url).pathname === '/prihlaseni') {
+            this.loggedIn = false;
+            await this.ensureLoggedIn();
+            response = await this.request(path);
+        }
+        return response.text();
+    }
+    /** Full-text product search. */
+    async searchProducts(query, limit = 10) {
+        const response = await this.request(`/vyhledavani?s=${encodeURIComponent(query)}`);
+        const html = await response.text();
+        return parseSearchResults(html, this.baseUrl).slice(0, limit);
+    }
+    /**
+     * Fetch and parse a product detail page. Accepts absolute or relative product URLs.
+     * With `variantId`, the page of that specific variant is fetched instead of the
+     * default one (the router resolves `/<product-slug>/<anything>-<variantId>`).
+     */
+    async getProductDetail(productUrl, variantId) {
+        let url = new URL(productUrl, this.baseUrl);
+        if (url.host !== new URL(this.baseUrl).host) {
+            throw new VilgainAPIError(`Product URL must be on ${this.baseUrl}`);
+        }
+        if (variantId !== undefined) {
+            const productSlug = url.pathname.split('/').filter(Boolean)[0];
+            if (!productSlug) {
+                throw new VilgainAPIError('Product URL is missing the product slug');
+            }
+            url = new URL(`/${productSlug}/v-${variantId}`, this.baseUrl);
+        }
+        const response = await this.request(url.href);
+        const html = await response.text();
+        const detail = parseProductDetail(html, response.url);
+        if (variantId !== undefined && detail.selectedVariantId !== variantId) {
+            throw new VilgainAPIError(`Variant ${variantId} not found on ${productUrl}`);
+        }
+        return detail;
+    }
+    /** Get current cart content. */
+    async getCart() {
+        const html = await this.getAuthenticatedPage('/objednavka');
+        return parseCart(html);
+    }
+    /**
+     * Add a product variant to the cart. Each call adds `quantity` more pieces
+     * (the shop's add-to-cart adds one; larger quantities are set explicitly
+     * afterwards). Returns the updated cart.
+     */
+    async addToCart(variantId, quantity = 1) {
+        await this.ensureLoggedIn();
+        await this.request('/', {
+            ajax: true,
+            form: {
+                _do: `buyVariant-${variantId}-addForm-submit`,
+                add: 'add_to_cart_button',
+            },
+        });
+        let cart = await this.getCart();
+        const item = cart.items.find((i) => i.variantId === variantId);
+        if (!item) {
+            throw new VilgainAPIError(`Adding variant ${variantId} to the cart had no effect - the variant id is probably invalid or out of stock`);
+        }
+        if (quantity > 1) {
+            cart = await this.setCartItemQuantity(variantId, item.quantity + quantity - 1);
+        }
+        return cart;
+    }
+    /** Set the absolute quantity of a cart item. Returns the updated cart. */
+    async setCartItemQuantity(variantId, quantity) {
+        await this.ensureLoggedIn();
+        await this.request('/objednavka', {
+            ajax: true,
+            form: {
+                _do: `mainBox-productVariant_${variantId}-quantityForm-submit`,
+                quantity: String(quantity),
+            },
+        });
+        return this.getCart();
+    }
+    /** Remove an item from the cart. Returns the updated cart. */
+    async removeFromCart(variantId) {
+        await this.ensureLoggedIn();
+        await this.request('/objednavka', {
+            ajax: true,
+            form: {
+                _do: `mainBox-productVariant_${variantId}-removeForm-submit`,
+                remove: '',
+            },
+        });
+        return this.getCart();
+    }
+    /** List past orders (most recent first, as displayed by the shop). */
+    async getOrderHistory() {
+        const html = await this.getAuthenticatedPage('/muj-ucet/objednavky');
+        return {
+            orders: parseOrderHistory(html, this.baseUrl),
+            empty: isOrderHistoryEmpty(html),
+        };
+    }
+    /** Get one order's items, total, delivery destination and shipment timeline. */
+    async getOrderDetail(orderId) {
+        if (!/^\d+$/.test(orderId)) {
+            throw new VilgainAPIError(`Invalid order id "${orderId}" - expected a number from get_order_history`);
+        }
+        const html = await this.getAuthenticatedPage(`/muj-ucet/objednavka/${orderId}`);
+        const detail = parseOrderDetail(html, this.baseUrl);
+        if (!detail.orderNumber) {
+            throw new VilgainAPIError(`Order ${orderId} not found on this account`);
+        }
+        return detail;
+    }
+}
+//# sourceMappingURL=vilgain-api.js.map