Add the postcardCollect flow and deprecate the legacy sighting API

[parrot-tailor]

Second part of splitting #41 into something more reviewable.

Summary

• Add the postcard collect flow — identify_postcard() returns a PostcardAnalysis (species, media, feeder) without collecting; collect_postcard() collects into a CollectedPostcard. Adds POSTCARD_COLLECT and the two models.
• Extend POSTCARD_REANALYZE — select the recognized species, media, and feeder.
• Validate every query against the schema — adds graphql-core as a new dev dependency; together with the bug reports, this is what flagged the dead sighting_create queries.
• Enable the Ruff RUF rules — tooling maintenance; flags noqa directives that suppress an inactive rule. Removed one that previously slipped in by mistake.
• Harden identify_postcard / collect_postcard — raise UnexpectedResponseError on a malformed response.
• Deprecate the legacy sighting/report flow — reanalyze_postcard, sighting_from_postcard, finish_postcard, sighting_choose_species, sighting_choose_mystery (use identify_postcard / collect_postcard); sighting_create / sighting_create_check_progress now raise NotImplementedError since the API removed the mutations.

Issue references

• Fixes BB API update / increased number of internal errors from server #29 — postcard internal server errors; collect_postcard reanalyzes before collecting.
• Related (ha-birdbuddy): the extended reanalyze omits the report/match tokens that were the cause of the payload bloat (Bird Buddy Postcard Event Exceeds 32768 ha-birdbuddy#78).
• Related (ha-birdbuddy): the collect flow resolves the autocollect errors (HA with Blueprint is no longer autocollecting Postcards ha-birdbuddy#98) once the integration adopts this API.

Notes

• Verified use of the new code live against my own BB account: identify_postcard on a fresh postcard returned the recognized species and media and flipped inferenceExecutionMode to MANUAL_COMPLETED (confirmed in the app, needed a pull-to-refresh but it worked!); a re-identify returned ALREADY_REANALYZED, so the internal reanalyze is idempotent.
• The graphql-core validation is its own commit and flips the build red on the dead sighting_create queries; the next commit removes them (wanted proper TDD). Happy to merge the two together if you'd rather not have a red commit in the history, thought it would be easier to review individual commits this way though.
• reanalyze_postcard is deprecated; its raw payload now carries the extra fields from the extended query (additive, so callers are unaffected).

Follow-ups

• After review/merge, I'll close (the draft) Migrate the postcard flow to postcardCollect; remove the legacy sighting API #41 and that'll be that :)
• Ideally I'd like to land Modernize the integration's tooling, CI, and docs ha-birdbuddy#108 first, then when a pybirdbuddy release is cut, I'll rework Migrate to pybirdbuddy v0.1.0 and its server-side postcard flow ha-birdbuddy#109 to adopt it, and I think that'll close out the API changes needed for pybirdbuddy and the HA integration

[jhansche]

LGTM - letting copilot take a pass, but I don't expect there to be anything major

[Copilot]

Pull request overview

This PR migrates the client’s postcard workflow to the newer postcardCollect flow, adds first-class models for postcard analysis/collection, and deprecates the legacy sighting/report API paths that no longer exist upstream. It also adds automated GraphQL query validation against the committed schema and updates developer tooling/docs to reflect the new flow.

Changes:

• Add identify_postcard() (returns PostcardAnalysis) and collect_postcard() (returns CollectedPostcard) and extend the reanalyze selection to include species/media/feeder details.
• Deprecate/remove legacy sighting create/progress paths (now raise NotImplementedError) and add supporting tests + a sanitized collect-flow fixture.
• Validate all library GraphQL documents against tests/fixtures/schema.json via graphql-core, and enable Ruff RUF rules.

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
tests/test_query_validation.py	New test validating all query constants against the committed GraphQL schema.
tests/test_postcards.py	New unit tests for the PostcardAnalysis model parsing behavior.
tests/test_client.py	Updates tests for deprecated sighting APIs; adds tests for identify/collect postcard and malformed responses.
tests/fixtures/collect_flow.json	Adds sanitized real-world capture fixture for the collect flow.
tests/conftest.py	Adds a fixture loader for the new collect-flow capture.
scripts/dump_payloads.py	Updates the capture script to dump the postcard collect flow using the library’s own queries.
README.md	Documents the new identify/collect postcard usage and updated deprecation notes.
pyproject.toml	Adds graphql-core to dev deps, updates Ruff pin, and enables RUF rules.
birdbuddy/queries/birds.py	Extends POSTCARD_REANALYZE selections and adds the POSTCARD_COLLECT mutation + fragment.
birdbuddy/postcards.py	Introduces PostcardAnalysis and CollectedPostcard models.
birdbuddy/client.py	Adds identify_postcard() / collect_postcard(), centralizes postcard id resolution, and deprecates/adjusts legacy sighting methods.

Suppressed comments (4)

birdbuddy/client.py:962

• sighting_choose_species() makes sighting_data optional in the signature, but the implementation requires a report token (schema shows reportToken is NON_NULL in SightingChooseSpeciesInput) and will raise TypeError when sighting_data is omitted/None. Make sighting_data required in the signature to match the actual contract and avoid misleading callers/static typing.

This issue also appears on line 983 of the same file.

    async def sighting_choose_species(
        self,
        sighting_id: str,
        species_id: str,
        sighting_data: SightingReport | str | None = None,

birdbuddy/client.py:1016

• sighting_choose_mystery() makes sighting_data optional in the signature, but the mutation input requires reportToken (NON_NULL in the schema) and the method raises TypeError when sighting_data is omitted/None. Make sighting_data required to match the API contract and improve type safety.

This issue also appears on line 1034 of the same file.

    async def sighting_choose_mystery(
        self,
        sighting_id: str,
        sighting_data: SightingReport | str | None = None,
    ) -> SightingReport:

birdbuddy/client.py:987

• _choose_species() treats sighting_data as required (it raises TypeError unless it’s a SightingReport or str token), but the signature suggests it’s optional by accepting None and providing a default. Tightening the type and removing the default better reflects the actual behavior and simplifies static analysis.

    async def _choose_species(
        self,
        sighting_id: str,
        species_id: str,
        sighting_data: SightingReport | str | None = None,

birdbuddy/client.py:1038

• _choose_mystery() raises TypeError unless sighting_data is a SightingReport or str token, so allowing None in the type/default is misleading. Make sighting_data required in the helper signature to match the implementation and improve readability/type checking.

    async def _choose_mystery(
        self,
        sighting_id: str,
        sighting_data: SightingReport | str | None = None,
    ) -> SightingReport:

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[jhansche]

Thank you!

[jhansche]

I'll have the next release out shortly (with breaking changes noted)