Skip to content

AGENTS.md

Latest commit

 

History

History
64 lines (48 loc) · 4.24 KB

AGENTS.md

File metadata and controls

64 lines (48 loc) · 4.24 KB
Raw

AGENTS.md

Context for coding agents (Claude Code, Codex, Cursor, Copilot and others) working in this repository. Humans: see README.md and CONTRIBUTING.md if present.

Overview

The official SDK for the ShopSavvy Data API in Python (3.8+). It wraps the REST API at https://api.shopsavvy.com/v1: look up products by barcode (UPC/EAN/ISBN), ASIN, URL, model number or MPN, and get current retailer offers, price history, scheduled refreshes and usage.

Layout

  • src/shopsavvy/client.py: the client (one method per endpoint)
  • src/shopsavvy/models.py: response models
  • src/shopsavvy/exceptions.py: error types
  • src/shopsavvy/_version.py: version (also sent in the User-Agent)
  • tests/: pytest suite with recorded fixtures (fixture_*.json)

Commands

# setup
pip install -e ".[dev]"

# test (offline, no API key needed)
pytest

# lint / build checks
black --check src tests
isort --check-only src tests
mypy src

Code conventions

  • Serialized field names (JSON tags, annotations, CodingKeys, model attributes) match the API JSON exactly (shopsavvy, barcode, amazon, model, mpn, offers, retailer, price, availability, timestamp, history, meta.credits_used, meta.credits_remaining, meta.rate_limit_remaining). Add a friendlier alias only alongside the real name, never instead of it.
  • Identifiers go in the ids query parameter, comma-separated, up to 100 per request (id for reviews). The API does not read barcode=, upc= or asin=.
  • availability is "in" or "out" and is absent when unknown. Treat absent as unknown, never as in stock. currency on a history point can be null; never assume USD for it.
  • Map errors from error_detail.code (ERR_AUTH_MISSING, ERR_RATE_LIMIT, ERR_CREDITS_EXHAUSTED, ...), not from the HTTP status: two different codes share 429. Surface Retry-After on ERR_RATE_LIMIT.
  • Authenticate with Authorization: Bearer <key>. Examples and docs read the key from the SHOPSAVVY_API_KEY environment variable.
  • Type hints on every public function; models are pydantic BaseModels whose field names match the API JSON.
  • Keep both the sync client and the context-manager usage documented in the README working.
  • Version lives in src/shopsavvy/_version.py. Bump it in the same change as any public API change.

Testing

  • Unit tests must run offline: mock HTTP and use recorded fixtures. Use obviously fake keys (ss_test_...).
  • Tests mock HTTP and read fixtures from tests/; they never call the live API.
  • When adding an endpoint or field, add a fixture copied from a real response shape in the API docs or OpenAPI spec, and a test that parses it.
  • Run the full test command above before committing.

What NOT to do

  • Never commit an API key, token or password. Not in code, tests, examples, fixtures, .env files or build config. This repo is public. Publishing credentials (registry tokens, signing passwords) stay on the maintainer's machine. If you find one in the tree, remove it and tell a maintainer so it can be rotated.
  • Never hardcode a key in an example; use SHOPSAVVY_API_KEY.
  • Don't invent endpoints, parameters or response fields. If it isn't in the API docs or OpenAPI spec, it doesn't exist yet.
  • Don't put plan prices, plan names, dollar amounts or credit costs in the README; link to https://shopsavvy.com/data and https://shopsavvy.com/data/documentation instead.
  • Don't add claims about scale, uptime or customers (no "99.9% uptime", "trusted by", retailer or product counts). The approved wording is "tens of thousands of retailers" and "30M+ products".
  • Don't publish a release (PyPI) from an agent session. Prepare the version bump and changelog; a maintainer publishes.
  • Don't change public method names or signatures without a deprecation path; other people's code depends on them.