Explain the Go consumer API contracts

[korya]

Problem

Go consumers lack enough documentation to handle structured outcomes, customize request policy, or understand response-body ownership safely.

The existing README names these concepts but does not show how their contracts fit together. Callers must infer when a top-level error can carry a partial result, how failures differ from evaluation errors, which values are safe to switch on, and whether the response body remains readable.

Solution

Document the complete consumer contract with copyable, executable examples for outcomes, HTTP policy, body access, and version compatibility.

flowchart TD
    Do["ha.Client.Do"] -->|"top-level error"| Incomplete["no complete outcome set; Result may be partial"]
    Do -->|"nil error"| Result["one Outcome per assertion"]
    Result --> Pass["Passed: assertion held"]
    Result --> Failure["Failure: response disproved assertion"]
    Result --> Evaluation["Err: assertion could not reach a verdict"]

Loading

The result example uses exported kind and error-code constants, handles *ha.EvaluationError with errors.As, and preserves a fallback for errors returned by custom assertions. The HTTP-policy example demonstrates caller context and client timeouts without moving retry or presentation policy into the library.

The ownership section states that Client.Do consumes and closes the original body, while decoded bytes and HTTP metadata remain on the structured response. A compatibility section sets the expected pre-v1 upgrade contract.

No visual change: this updates README and Go package documentation.

Other Changes

• Add executable Go examples for failure/evaluation classification, request cancellation, custom client timeout, and decoded body access.
• Expand the package overview so pkg.go.dev surfaces outcome and body-ownership semantics.
• Keep every library import explicitly aliased as ha.

Related:

• Extract reusable HTTP assertion library #105
• Add typed assertion-kind constants #107
• Honor request cancellation during jq evaluation #108
• Generalize Must for any value #109

🤖 Generated with Claude Code