feat(BUZZ-231): add audience breakdown command

[lloydrhodes87]

Summary

Adds prolific audience breakdown, a wrapper over POST /api/v1/eligibility-count/filter-breakdown/ that counts eligible participants matching a set of base filters, broken down by the values (or bucketed ranges, for numeric filters) of one distributable filter (BUZZ-231).

$ prolific audience breakdown -t docs/examples/filter-breakdown.json -w <workspace-id>
VALUE   COUNT
0       4
1       3
N/A     5

The response includes an "N/A" bucket — participants who match the base filters but don't fall into any of the breakdown filter's selected values/range (e.g. an unanswered screener question). This isn't documented anywhere public (the endpoint isn't in the published OpenAPI spec yet), so the command's own --help explains it explicitly, traced back to filter_breakdown_service.py's base_count - unsplit_count in the prolific-api repo.

Implementation

• New client payload/response types (FilterBreakdownPayload/FilterBreakdownResponse) + GetFilterBreakdown method
• New cmd/audience package: an audience parent command (pure router) with breakdown as its first subcommand, following the documented Two-Level Command Structure — leaves room for a future audience count; eligibility-count itself is untouched in this PR
• docs/examples/filter-breakdown.json example template
• contract_test.go: added a skip entry for messages_CreateConversation, an unrelated operation that appeared in the live spec and was blocking the pre-commit hook — no CLI command exists for it

Testing

cmd/audience/breakdown_test.go covers rendering, empty-filters-not-nil, input validation (missing template/workspace/breakdown filter), config read/unmarshal failures, and API error handling. make lint, make test (incl. contract test against the live spec), make build all pass.

🤖 Generated with Claude Code

[prolific-snyk]

✅ Snyk checks have passed. No issues have been found so far.

Status	Scan Engine	Critical	High	Medium	Low	Total (0)
✅	Open Source Security	0	0	0	0	0 issues
✅	Licenses	0	0	0	0	0 issues
✅	Code Security	0	0	0	0	0 issues

💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse.

[Copilot]

Copilot review overview

🟡 Changes recommended

README coverage must be updated for CI, and the new endpoint needs direct request/response client testing.

Get a fresh assessment by requesting another Copilot review.

Review effort: Lite
Findings: 1 · 1

Open (2)

• Update README API coverage for messages_CreateConversation · New
• Add HTTP-backed test for GetFilterBreakdown request and response · New

What changed in this PR

Adds prolific audience breakdown with API support, validation, rendering, and tests.

Changes:

• Adds filter-breakdown client payloads, responses, and endpoint method.
• Adds the audience breakdown command and example template.
• Updates mocks and contract-test coverage.

File	Description
mock_client/​mock_client.go	Updates generated API mocks.
docs/​examples/​filter-breakdown.json	Adds an example filter template.
contract_test/​contract_test.go	Adds an operation skip entry.
cmd/​root.go	Registers the audience command.
cmd/​audience/​breakdown.go	Implements command behavior and rendering.
cmd/​audience/​breakdown_test.go	Tests command behavior and output.
cmd/​audience/​audience.go	Adds the audience parent command.
client/​responses.go	Adds the response type.
client/​payloads.go	Adds the request payload type.
client/​client.go	Adds filter-breakdown API support.

Files not reviewed (1)

• mock_client/mock_client.go: Generated file

---

💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Copilot review overview

🔵 Needs a closer look

Add parent-command help and malformed-template regression coverage before approval.

Review effort: Lite
Findings: None

Resolved since last review (2)

• Update README API coverage for messages_CreateConversation
• Add HTTP-backed test for GetFilterBreakdown request and response

Files not reviewed (1)

• mock_client/mock_client.go: Generated file

Previously missed (1)

In code that hasn't changed since last review

Add Long description and Example to audience command

cmd/​audience/​audience.go:15

The new top-level audience command has no Long or Example, so prolific audience --help lacks the description and invocation guidance provided by the other parent commands (for example, cmd/bonus/bonus.go:14-30). Add both fields so users can discover that breakdown requires a template and workspace.

[SeanAlexanderHarris]

nit: 'distributable' is a bit opaque for a user here (perhaps agent too if not elaborated on a bit as a domain specific language

[lloydrhodes87]

agreed and change pushed if you wouldnt mind reapproving @SeanAlexanderHarris

[SeanAlexanderHarris]

one nit comment and one non blocking question 🙏