# 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.

## Keep Stable

- 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.

## Editing Rules

- 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.

## Tests

- 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.

## Verify

- `bun test packages/core/test`
- `bun run ci`