Expose full Water Data STAC API

[thodson-usgs]

Summary

• add raw-document access to every public USGS Water Data STAC resource through the canonical waterdata.stac namespace:
  • get_catalog() and get_conformance()
  • get_collections() and get_collection()
  • get_items() and get_item()
  • get_queryables() and search()
• support every advertised collection, item-list, GET search, and POST search parameter while preserving STAC, GeoJSON, and JSON Schema response documents
• keep the analysis-ready waterdata.get_ratings() helper flat while grouping only the raw catalog operations under waterdata.stac
• provide no compatibility aliases for the earlier flat get_stac_*/search_stac draft names because this API has not been released
• share Water Data base-URL redirection, host-scoped API keys, typed HTTP errors, and bounded retries
• document the (dict, BaseMetadata) contract, namespace decision (ADR 0012), and API usage in the README, NEWS, reference docs, and a pedagogical notebook

Before this change, waterdata.get_ratings() used only the specialized GET /stac/v0/search path and then downloaded rating assets. The rest of the public STAC API had no dataretrieval entry point. Internal /_mgmt/ping and /_mgmt/health operations are intentionally excluded because they are service operations rather than STAC capabilities.

The upstream parameter named token is exposed as page_token and mapped back to token on the wire, avoiding ambiguity with the package's credential-parameter guard.

Validation

• coverage run -m pytest tests/: 1005 passed, 12 live tests deselected; 98% coverage
• focused post-review STAC/public-API/architecture suite: 108 passed
• notebook schema and syntax validated; all 12 migrated notebook code cells executed successfully against the live API
• ruff check . and ruff format --check .
• strict mypy dataretrieval: 62 source files
• all 8 import-linter contracts
• complexipy threshold 10 and xenon gates
• git diff --check
• full Sphinx HTML build rendered the STAC notebook and ADR 0012; only five known pre-existing warnings remain
• independent Standards/Spec review completed; the architecture documentation finding was addressed before commit