Skip to content

AGENTS.md

Latest commit

 

History

History
62 lines (46 loc) · 4.27 KB

AGENTS.md

File metadata and controls

62 lines (46 loc) · 4.27 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 Java (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/main/java/com/shopsavvy/sdk/ShopSavvyClient.java: the client and VERSION
  • src/main/java/com/shopsavvy/sdk/models/: response models (Jackson)
  • src/main/java/com/shopsavvy/sdk/exceptions/: error types
  • src/test/java/com/shopsavvy/sdk/: JUnit 5 tests with OkHttp MockWebServer
  • pom.xml (release build) and build.gradle (kept in step)

Commands

# setup
mvn -q -DskipTests install

# test (offline, no API key needed)
mvn test

# lint / build checks
mvn -q verify

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.
  • Models are immutable with Jackson annotations matching the API field names.
  • Keep pom.xml and build.gradle dependency versions identical.
  • Version lives in pom.xml, build.gradle and VERSION in ShopSavvyClient.java (keep all three equal). 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 use OkHttp MockWebServer; no network.
  • 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 (Maven Central) 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.