continentept-mcp 0.0.0-stage → 0.2.0

package/.env.example

@@ -0,0 +1,14 @@
+# continentept-mcp settings.
+# Save as ~/.continentept-mcp/credentials.env, or anywhere you point CONTINENTE_CREDENTIALS_FILE at.
+# Keep it private (chmod 600). Values set in the MCP client environment take precedence.
+
+# Account credentials for automatic sign-in. Not needed for search or product details.
+CONTINENTE_EMAIL=you@example.com
+CONTINENTE_PASSWORD=replace-with-your-password
+
+# Close the browser after this many idle seconds; 0 keeps it open. Default: 300
+# CONTINENTE_BROWSER_IDLE_SECONDS=300
+
+# These two only work as environment variables in the MCP client configuration:
+# CONTINENTE_CREDENTIALS_FILE=/private/path/credentials.env
+# CONTINENTE_DATA_DIR=/private/path/continentept-mcp

package/CHANGELOG.md

@@ -0,0 +1,33 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses
+[Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.2.0] - 2026-10-15
+
+### Added
+
+- Server instructions: assistants receive the cart rules (exact totals, one change at a time, check the cart after an uncertain change) as soon as they connect.
+- A `basket-planner` prompt with the full shopping workflow, with an optional request to plan for. No skill install is needed.
+- Documentation for supplying credentials from 1Password with `op run`.
+
+### Changed
+
+- The `basket-planner` skill links to the online tool reference, so it also works when uploaded on its own.
+
+## [0.1.0] - 2026-10-15
+
+### Added
+
+- Catalogue search and product details with exact prices, availability and sale rules.
+- Cart tools that confirm every change by reading the cart back and report uncertain changes instead of retrying them.
+- Favorites, order history and a ranking of frequently bought products.
+- Automatic sign-in from environment variables or a private credentials file, and a `login` command.
+- The `basket-planner` skill for planning a shopping list and updating the basket.
+
+[Unreleased]: https://github.com/andredelgado/continente-mcp/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/andredelgado/continente-mcp/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/andredelgado/continente-mcp/releases/tag/v0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 André Delgado
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,157 @@
-# Temporary Holding Version
+# Continente MCP
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![CI](https://github.com/andredelgado/continente-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/andredelgado/continente-mcp/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/continentept-mcp)](https://www.npmjs.com/package/continentept-mcp)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+An [MCP](https://modelcontextprotocol.io) server that lets AI assistants shop at
+[Continente.pt](https://www.continente.pt): search products, check prices and sale rules,
+read your favorites and past orders, and fill your cart. Checkout and payment always stay
+on the website.
+
+> **Unofficial.** This project is not affiliated with, endorsed by or supported by
+> Continente or MC Sonae. It automates the public website with a headless browser, may break
+> when the site changes, and should be used in line with the website's terms. You are
+> responsible for anything placed in your cart.
+
+## Features
+
+- **Catalogue search and product details**, with exact prices, unit prices, availability and
+  sale rules for weighted and bulk products.
+- **Safe cart changes.** Every change is confirmed by reading the cart back. If a change
+  cannot be confirmed, the result says so and tells the assistant to check the cart instead
+  of retrying.
+- **Your account**: favorites, order history and a ranking of the products you buy most.
+- **Runs locally** over stdio. Credentials and cookies stay on your machine.
+- **Built-in guidance.** The server tells the assistant the cart rules as soon as it
+  connects, and offers a `basket-planner` prompt with the full shopping workflow. Nothing
+  extra to install; the same guide also ships as a [skill](skills/basket-planner/SKILL.md).
+
+## Requirements
+
+- Node.js 22 or newer
+- A Continente.pt account for account features (search and product details work without one)
+
+## Quick start
+
+**1. Install the browser** the server uses to talk to the website (one-time download):
+
+```sh
+npx -y continentept-mcp install-browser
+```
+
+On Linux, append `--with-deps` to also install the required system libraries.
+
+**2. Save your credentials** in `~/.continentept-mcp/credentials.env` (see
+[configuration](docs/configuration.md) for other options):
+
+```sh
+mkdir -p ~/.continentept-mcp && chmod 700 ~/.continentept-mcp
+printf 'CONTINENTE_EMAIL=you@example.com\nCONTINENTE_PASSWORD=your-password\n' > ~/.continentept-mcp/credentials.env
+chmod 600 ~/.continentept-mcp/credentials.env
+```
+
+Using 1Password? Skip the file and pass secret references through `op run` instead; see
+[Using 1Password](docs/configuration.md#using-1password).
+
+Optionally check that login works:
+
+```sh
+npx -y continentept-mcp login
+```
+
+**3. Add the server to your MCP client.**
+
+Claude Code:
+
+```sh
+claude mcp add continente -- npx -y continentept-mcp
+```
+
+Claude Desktop, Cursor and other clients (`claude_desktop_config.json`, `mcp.json`, ...):
+
+```json
+{
+  "mcpServers": {
+    "continente": {
+      "command": "npx",
+      "args": ["-y", "continentept-mcp"]
+    }
+  }
+}
+```
+
+To keep the credentials file elsewhere, add
+`"env": { "CONTINENTE_CREDENTIALS_FILE": "/absolute/path/to/credentials.env" }`.
+
+Then ask your assistant something like *"Add semi-skimmed milk and a dozen eggs to my
+Continente cart"* or *"What do I usually buy? Build me a list for this week."*
+
+## Tools
+
+| Tool | What it does |
+| --- | --- |
+| `search_products` | Search the catalogue; favorites rank first |
+| `get_product` | Price, availability and sale rules for one product |
+| `list_favorites` | Your saved favorites (`refresh: true` fetches the latest) |
+| `get_cart` | Cart lines, quantities and total |
+| `add_cart_item` | Add an amount on top of what is in the cart |
+| `set_cart_item_quantity` | Make the cart hold exactly a quantity; zero removes |
+| `remove_cart_item` | Remove a line from the cart |
+| `list_orders` | Recent orders with their product lines |
+| `get_order` | One order's product lines |
+| `list_frequently_bought_products` | Products ranked by how often you order them |
+| `get_session_status` | Local login, cookie and cache state (no network) |
+
+See the [tool reference](docs/tools.md) for inputs, outputs, error codes and limits.
+
+### About uncertain cart changes
+
+A cart change can fail after the request has reached the website, for example on a timeout.
+In that case the result has `mutation.outcome: "unknown"` and asks the client to call
+`get_cart` before doing anything else. The server never retries such a change on its own,
+and clients should not either: repeating an `add_cart_item` could add the item twice.
+
+### Guidance for the assistant
+
+When a client connects, the server sends short instructions with these cart rules, so the
+assistant follows them without any setup. For planning a shopping list, pick the
+**basket-planner** prompt from your client's prompt or attachment menu, optionally with a
+request such as "weekly basket for two".
+
+The same guide is available as a skill in
+[`skills/basket-planner`](skills/basket-planner/SKILL.md). Clients that support skills, such
+as Claude Desktop (Settings → Capabilities → Skills) or Claude Code (`~/.claude/skills/`),
+then apply it automatically whenever you ask about groceries.
+
+## Command line
+
+```text
+continentept-mcp                    Start the MCP server on stdio
+continentept-mcp login              Sign in and save the session (--show-browser to watch)
+continentept-mcp install-browser    Download Chromium (extra arguments go to Playwright)
+continentept-mcp --version
+```
+
+## Limitations
+
+- One account per server process.
+- Searches read at most five result pages and order listings at most ten pages, so very
+  broad queries or long histories are reported as incomplete rather than read in full.
+- Login handles the standard email and password flow. If the website asks for extra
+  verification, run `continentept-mcp login --show-browser` and complete it in the browser
+  window.
+- There are no checkout, payment, delivery-slot or favorites-editing tools.
+
+## Documentation
+
+- [Tool reference](docs/tools.md)
+- [Configuration](docs/configuration.md)
+- [Troubleshooting](docs/troubleshooting.md)
+- [Contributing](CONTRIBUTING.md)
+- [Security policy](SECURITY.md)
+- [Changelog](CHANGELOG.md)
+
+## License
+
+[MIT](LICENSE)

package/dist/application.d.ts

@@ -0,0 +1,12 @@
+import { ContinenteMcpServer } from './mcp/server.js';
+import type { PromptHandler, ToolHandler } from './mcp/server.js';
+export interface ApplicationOptions {
+    readonly version: string;
+    readonly tools?: readonly ToolHandler[];
+    readonly prompts?: readonly PromptHandler[];
+    readonly instructions?: string;
+    readonly closeResources?: () => Promise<void>;
+    readonly requestTimeoutMs?: number;
+}
+/** Create an MCP server from tool handlers. Importing the library performs no configuration or I/O. */
+export declare function createApplication(options: ApplicationOptions): ContinenteMcpServer;

package/dist/application.js

@@ -0,0 +1,5 @@
+import { ContinenteMcpServer } from './mcp/server.js';
+/** Create an MCP server from tool handlers. Importing the library performs no configuration or I/O. */
+export function createApplication(options) {
+    return new ContinenteMcpServer({ ...options, tools: options.tools ?? [] });
+}

package/dist/auto-login.d.ts

@@ -0,0 +1,3 @@
+import type { LoginOptions } from './clients/authentication.js';
+/** Sign in with the configured credentials and save the session for the server to reuse. */
+export declare function runAutoLogin(options?: LoginOptions): Promise<boolean>;

package/dist/auto-login.js

@@ -0,0 +1,10 @@
+import { loadSettings } from './config.js';
+import { FileCookieStore } from './stores/files.js';
+import { AuthenticationClient } from './clients/authentication.js';
+import { launchBrowser } from './runtime.js';
+/** Sign in with the configured credentials and save the session for the server to reuse. */
+export async function runAutoLogin(options = {}) {
+    const settings = loadSettings();
+    const logger = (message) => console.error(message);
+    return new AuthenticationClient(launchBrowser, new FileCookieStore(settings.cookieFile), settings, logger, options).loginWithCredentials();
+}

package/dist/cli.d.ts

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+import type { ContinenteMcpServer } from './mcp/server.js';
+export declare function startStdioServer(): Promise<ContinenteMcpServer>;
+/** The SDK stdio transport does not treat input EOF as closure, so the CLI owns that lifecycle. */
+export declare function connectStdioApplication(application: ContinenteMcpServer): Promise<void>;
+export declare function main(args: string[]): Promise<number>;

package/dist/cli.js

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createShoppingApplication } from './runtime.js';
+import { runAutoLogin } from './auto-login.js';
+import { isMainModule } from './main-module.js';
+const USAGE = `Usage: continentept-mcp [command]
+
+Commands:
+  (none)            Start the MCP server on stdio
+  login             Sign in with CONTINENTE_EMAIL and CONTINENTE_PASSWORD and save the session
+                    (--show-browser displays the browser window)
+  install-browser   Download the Chromium build used by the server (extra arguments go to Playwright)
+
+Options:
+  -h, --help        Show this help
+  -v, --version     Show the version
+`;
+function packageVersion() {
+    const metadata = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+    if (typeof metadata !== 'object' || metadata === null || !('version' in metadata) ||
+        typeof metadata.version !== 'string')
+        throw new Error('Missing package version');
+    return metadata.version;
+}
+export async function startStdioServer() {
+    const version = packageVersion();
+    const application = createShoppingApplication({ version });
+    await connectStdioApplication(application);
+    console.error(`continentept-mcp ${version} ready on stdio`);
+    return application;
+}
+/** The SDK stdio transport does not treat input EOF as closure, so the CLI owns that lifecycle. */
+export async function connectStdioApplication(application) {
+    const detach = () => {
+        process.off('SIGINT', shutdown);
+        process.off('SIGTERM', shutdown);
+        process.stdin.off('end', shutdown);
+        process.stdin.off('close', shutdown);
+    };
+    const shutdown = () => {
+        detach();
+        void application.close().catch(() => { console.error('Could not close Continente MCP resources.'); process.exitCode = 1; });
+    };
+    process.once('SIGINT', shutdown);
+    process.once('SIGTERM', shutdown);
+    process.stdin.once('end', shutdown);
+    process.stdin.once('close', shutdown);
+    try {
+        await application.connect(new StdioServerTransport());
+    }
+    catch (error) {
+        detach();
+        throw error;
+    }
+}
+function installBrowser(extra) {
+    const playwright = dirname(createRequire(import.meta.url).resolve('playwright/package.json'));
+    const result = spawnSync(process.execPath, [join(playwright, 'cli.js'), 'install', 'chromium', ...extra], { stdio: 'inherit' });
+    return result.status ?? 1;
+}
+export async function main(args) {
+    const [command, ...rest] = args;
+    switch (command) {
+        case undefined:
+        case 'serve':
+            await startStdioServer();
+            return 0;
+        case 'login':
+            try {
+                return (await runAutoLogin({ showBrowser: rest.includes('--show-browser') })) ? 0 : 1;
+            }
+            catch (error) {
+                console.error(`Login failed: ${error instanceof Error ? error.message : 'unknown error'}`);
+                return 1;
+            }
+        case 'install-browser':
+            return installBrowser(rest);
+        case '-v':
+        case '--version':
+            console.log(packageVersion());
+            return 0;
+        case '-h':
+        case '--help':
+            console.log(USAGE);
+            return 0;
+        default:
+            console.error(`Unknown command: ${command}\n\n${USAGE}`);
+            return 2;
+    }
+}
+if (isMainModule(import.meta.url)) {
+    main(process.argv.slice(2)).then(code => { if (code)
+        process.exitCode = code; }, (error) => {
+        console.error(error instanceof Error ? error.message : 'Could not start Continente MCP');
+        process.exitCode = 1;
+    });
+}

package/dist/clients/authentication.d.ts

@@ -0,0 +1,26 @@
+import type { BrowserContext, Frame, Page } from 'playwright';
+import type { Logger } from '../ports.js';
+import type { CookieStore } from '../stores/files.js';
+import type { BrowserLauncher } from '../session/browser.js';
+export interface Credentials {
+    readonly email: string;
+    readonly password: string;
+}
+export interface LoginOptions {
+    readonly showBrowser?: boolean;
+}
+/** Signs in through the website's login form and saves the resulting session cookies. */
+export declare class AuthenticationClient {
+    private readonly launch;
+    private readonly cookies;
+    private readonly credentials;
+    private readonly logger;
+    private readonly options;
+    constructor(launch: BrowserLauncher, cookies: CookieStore, credentials: Credentials, logger: Logger, options?: LoginOptions);
+    /** Ask the storefront whether this browser context belongs to a signed-in customer. */
+    isSignedIn(context: BrowserContext): Promise<boolean>;
+    /** The login form is served in a frame from the login origin; wait for it to load. */
+    loginFrame(page: Page): Promise<Frame>;
+    private submit;
+    loginWithCredentials(): Promise<boolean>;
+}

package/dist/clients/authentication.js

@@ -0,0 +1,92 @@
+import { SessionCookiesSchema } from '../stores/files.js';
+import { browserUserAgent } from '../session/browser.js';
+import { field } from '../parsers/records.js';
+import { STOREFRONT_ORIGIN } from '../parsers/catalog.js';
+import { isLoginUrl, responseStatus } from './policy.js';
+import { CART_SUMMARY_URL } from './storefront.js';
+import { requestIO, acquireResource, checkRequest } from '../session/request.js';
+const LOGIN_ORIGIN = 'https://login.continente.pt';
+const EMAIL_INPUT = '#userNameCC';
+const PASSWORD_INPUT = '#password_input';
+const CONSENT_BUTTON = /^permitir todos$/i;
+/** Signs in through the website's login form and saves the resulting session cookies. */
+export class AuthenticationClient {
+    launch;
+    cookies;
+    credentials;
+    logger;
+    options;
+    constructor(launch, cookies, credentials, logger, options = {}) {
+        this.launch = launch;
+        this.cookies = cookies;
+        this.credentials = credentials;
+        this.logger = logger;
+        this.options = options;
+    }
+    /** Ask the storefront whether this browser context belongs to a signed-in customer. */
+    async isSignedIn(context) {
+        const response = await context.request.get(CART_SUMMARY_URL, { headers: { 'X-Requested-With': 'XMLHttpRequest' }, timeout: 10000 });
+        if (!responseStatus(response, response.url?.() ?? CART_SUMMARY_URL).ok)
+            return false;
+        const body = await response.json().catch(() => null);
+        return field(body, 'resources', 'customerAuthenticated') === true;
+    }
+    /** The login form is served in a frame from the login origin; wait for it to load. */
+    async loginFrame(page) {
+        const fromLoginOrigin = (frame) => {
+            try {
+                return new URL(frame.url()).origin === LOGIN_ORIGIN;
+            }
+            catch {
+                return false;
+            }
+        };
+        return page.frames().find(fromLoginOrigin) ?? page.waitForEvent('framenavigated', { predicate: fromLoginOrigin, timeout: 15000 });
+    }
+    async submit(frame, input, value) {
+        checkRequest();
+        const field = frame.locator(input);
+        await field.fill(value, { timeout: 15000 });
+        const button = frame.locator('button[type="submit"]:visible').first();
+        if (await button.count())
+            await button.click();
+        else
+            await field.press('Enter');
+    }
+    async loginWithCredentials() {
+        const { email, password } = this.credentials;
+        if (!email || !password) {
+            this.logger('Login skipped: CONTINENTE_EMAIL and CONTINENTE_PASSWORD are required.');
+            return false;
+        }
+        const browser = await acquireResource(() => this.launch({ headless: !this.options.showBrowser }), browser => browser.close());
+        let closing;
+        const close = () => closing ??= browser.close();
+        try {
+            return await requestIO(async () => {
+                const context = await acquireResource(() => browser.newContext({ userAgent: browserUserAgent(browser.version()), locale: 'pt-PT' }), context => context.close());
+                const page = await acquireResource(() => context.newPage(), page => page.close());
+                this.logger('Signing in.');
+                await page.goto(`${STOREFRONT_ORIGIN}/login/`, { waitUntil: 'domcontentloaded', timeout: 30000 });
+                await page.getByRole('button', { name: CONSENT_BUTTON }).click({ timeout: 5000 }).catch(() => { });
+                const frame = await this.loginFrame(page);
+                await this.submit(frame, EMAIL_INPUT, email);
+                const leftLogin = page.waitForURL(url => url.origin === STOREFRONT_ORIGIN && !isLoginUrl(url.href), { timeout: 20000 }).catch(() => { });
+                await this.submit(frame, PASSWORD_INPUT, password);
+                await leftLogin;
+                checkRequest();
+                if (!(await this.isSignedIn(context)))
+                    throw new Error('The website did not accept the login');
+                const cookies = SessionCookiesSchema.safeParse(await context.cookies());
+                if (!cookies.success)
+                    throw new Error('The website returned an unexpected session');
+                await this.cookies.save(cookies.data);
+                this.logger('Signed in; session saved.');
+                return true;
+            }, close);
+        }
+        finally {
+            await close();
+        }
+    }
+}

package/dist/clients/policy.d.ts

@@ -0,0 +1,26 @@
+export declare function isLoginUrl(value: string): boolean;
+export interface HttpResponse {
+    ok(): boolean;
+    status(): number;
+    url?(): string;
+    headers?(): Record<string, string>;
+}
+/** Only known authentication evidence triggers recovery; arbitrary upstream failures do not. */
+export declare function responseStatus(response: HttpResponse | null, finalUrl: string): import("../domain/result.js").Result<undefined, {
+    code: "cache_unavailable" | "cancelled" | "cart_change_rejected" | "cart_change_unconfirmed" | "deadline_exceeded" | "invalid_data" | "invalid_input" | "not_authenticated" | "not_found" | "order_details_unavailable" | "quantity_below_minimum" | "queue_full" | "sale_rules_unknown" | "server_closed" | "upstream_unavailable";
+    message: string;
+    retryable: boolean;
+    issues?: {
+        path: string;
+        code: string;
+    }[] | undefined;
+}>;
+export declare function authenticatedPayload(input: unknown): import("../domain/result.js").Result<unknown, {
+    code: "cache_unavailable" | "cancelled" | "cart_change_rejected" | "cart_change_unconfirmed" | "deadline_exceeded" | "invalid_data" | "invalid_input" | "not_authenticated" | "not_found" | "order_details_unavailable" | "quantity_below_minimum" | "queue_full" | "sale_rules_unknown" | "server_closed" | "upstream_unavailable";
+    message: string;
+    retryable: boolean;
+    issues?: {
+        path: string;
+        code: string;
+    }[] | undefined;
+}>;

package/dist/clients/policy.js

@@ -0,0 +1,37 @@
+import { STOREFRONT_ORIGIN, storefrontUrl } from '../parsers/catalog.js';
+import { field } from '../parsers/records.js';
+import { failure, success } from '../domain/index.js';
+export function isLoginUrl(value) {
+    try {
+        const url = new URL(value);
+        return url.protocol === 'https:' && (url.origin === 'https://login.continente.pt' ||
+            (url.origin === STOREFRONT_ORIGIN && /^\/login(?:\/|$)/i.test(url.pathname)));
+    }
+    catch {
+        return false;
+    }
+}
+/** Only known authentication evidence triggers recovery; arbitrary upstream failures do not. */
+export function responseStatus(response, finalUrl) {
+    const status = response?.status();
+    const location = response?.headers?.().location;
+    let redirect = '';
+    try {
+        if (location)
+            redirect = new URL(location, STOREFRONT_ORIGIN).href;
+    }
+    catch {
+        return failure('invalid_data', 'Invalid response redirect');
+    }
+    if (status === 401 || status === 403 || isLoginUrl(finalUrl) || (status && status >= 300 && status < 400 && isLoginUrl(redirect))) {
+        return failure('not_authenticated');
+    }
+    if (!storefrontUrl(finalUrl))
+        return failure('invalid_data', 'Unexpected response origin');
+    if (status === 404)
+        return failure('not_found');
+    return response?.ok() ? success(undefined) : failure('upstream_unavailable', `The website returned HTTP ${status ?? 'with no status'}`);
+}
+export function authenticatedPayload(input) {
+    return field(input, 'resources', 'customerAuthenticated') === false ? failure('not_authenticated') : success(input);
+}

package/dist/clients/storefront.d.ts

@@ -0,0 +1,40 @@
+import type { CatalogGateway, FavoritesGateway, CartGateway, OrdersGateway, PreparedCartMutation, RetrievedPages } from '../ports.js';
+import type { Result, ToolError } from '../domain/index.js';
+import type { BrowserLease, StorefrontSession } from '../session/browser.js';
+export declare const CART_SUMMARY_URL = "https://www.continente.pt/on/demandware.store/Sites-continente-Site/default/Cart-MiniCartShow";
+export declare class StorefrontClient {
+    readonly session: StorefrontSession;
+    constructor(session: StorefrontSession);
+    io<T>(lease: BrowserLease, operation: () => Promise<T>): Promise<T>;
+    navigateToStorefrontPage(path: string): Promise<Result<BrowserLease, ToolError>>;
+    html(path: string, marker?: string): Promise<Result<string, ToolError>>;
+}
+export declare class CatalogClient implements CatalogGateway {
+    private readonly site;
+    constructor(site: StorefrontClient);
+    fetchProductDetails(reference: string): Promise<Result<{
+        html: string;
+        url: string;
+    }, ToolError>>;
+    searchProducts(query: string, limit: number): Promise<Result<RetrievedPages, ToolError>>;
+}
+export declare class FavoritesClient implements FavoritesGateway {
+    private readonly site;
+    constructor(site: StorefrontClient);
+    fetchFavorites(): Promise<Result<RetrievedPages, ToolError>>;
+}
+export declare class CartClient implements CartGateway {
+    private readonly site;
+    constructor(site: StorefrontClient);
+    fetchCart(): Promise<Result<unknown, ToolError>>;
+    fetchProductForm(reference: string): Promise<Result<unknown, ToolError>>;
+    fetchCartControls(): Promise<Result<string, ToolError>>;
+    submitCartMutation(action: string, parameters: URLSearchParams, method: 'GET' | 'POST'): Promise<Result<unknown, ToolError>>;
+    prepareCartMutation(action: string, parameters: URLSearchParams, method: 'GET' | 'POST'): Promise<Result<PreparedCartMutation, ToolError>>;
+}
+export declare class OrdersClient implements OrdersGateway {
+    private readonly site;
+    constructor(site: StorefrontClient);
+    fetchOrderHistory(cursor?: string): Promise<Result<string, ToolError>>;
+    fetchOrderLines(url: string): Promise<Result<string, ToolError>>;
+}