fix(gumtree): South Africa ids are refs — widen id types, 0.60.1 (SCR-295)

[0xGhostCasper]

Why

gumtree.co.za replaced its old site with a new Nuxt app on 2026-10-12. The API now serves market="za" from the site's new JSON API (scrape-badger/scrapebadger#2461, deployed). Category, location and listing ids there are refs, not numbers:

• p6dnh is Cars & Bakkies.
• dkp8y is Gauteng.
• ls26bvmcpnsqmz7l9jz is a listing.

0.60.0 typed those ids as int, so every za tree, facet, suggestion and location-suggestion response failed validation.

Change

• These fields go from int to int | str: TreeNode.id, TreeResponse.id, CategoryRef.id, CategoryFacet.id, LocationSuggestion.id, category_id (search response, listing summary, listing detail) and category_ids.
  • uk/au responses still parse to ints, and callers passing ints are unaffected.
• list_categories / list_locations take parent_id: int | str, so za refs can be passed.
• Docstrings and examples use real za values:
  • search(market="za", category="p6dnh", location="dkp8y", filters="make:toyota")
  • filter keys make / model / fuelType / year / mileageKm
  • the 375-match paging window
  • listing refs
• Field descriptions updated: price_type za values ASKING_PRICE / POA; short_id, lifetime_listings and total_views are no longer published; za member_since_year.
• Tests:
  • The za fixtures in tests/fixtures/gumtree_samples.json were re-captured from the live API on 2026-10-13 (search, listing, and a za category tree with string ids). uk/au fixtures are untouched.
  • New tests cover za string ids, uk int ids, and passing a za ref as parent_id.
• Version 0.60.1 (pyproject.toml, __version__, SDK_VERSION, uv.lock) with a CHANGELOG entry.

Checks

ruff check, ruff format --check, mypy src/ (224 files, no issues) and pytest --ignore=tests/e2e: 870 passed, 41 of them gumtree.

Linear: SCR-295

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!