Files

Dmytro Stanchiev b657ea594a chore: update agents docs

Signed-off-by: Dmytro Stanchiev <git@dmytros.dev>

2026-04-30 22:29:01 -04:00

packages/core

Scope

This package owns scraper behavior, parsing, result shapes, shared cookie handling, and shared HTTP utilities.
Put marketplace-specific logic in src/scrapers/*.ts.
Put reusable cross-marketplace helpers in src/utils/* only when at least two callers need them.

Cookie loading order is a hard invariant: parameter > env var > file.
Exported names in src/index.ts are the package contract for api-server and mcp-server.
Keep result field semantics stable across refactors; adapter packages should not need to reinterpret core results.

New marketplace behavior belongs here, not in route or protocol layers.
Isolate marketplace-specific hacks/selectors inside the owning scraper file unless they are genuinely shared.
If a new helper is scraper-local, keep it local. Do not promote it into utils early.
If you change shared types or exports, check downstream imports in both adapter packages.
eBay SplashUI challenge handling needs raw fetch for manual redirects and getSetCookie(); use fetchHtml only once the flow only needs final HTML.

Tests live in test/*.test.ts and use bun:test.
Mock network and file edges. Do not depend on live cookies, live HTTP, wall clock timing, or external sessions.
Favor parser/extraction tests with fixture-like inline HTML/JSON over broad end-to-end behavior.