feat(calendar): add --event-types filter to calendar events

[malob]

What

Adds an opt-in --event-types flag to gog calendar events, passed through to the Calendar API events.list eventTypes parameter.

Why

Without a filter, events.list returns every event type, so birthday, workingLocation, and fromGmail entries come back mixed in with regular events — with no way to focus on the common event types a caller is usually interested in, or to filter down to just the subset they want and clear out the rest. The API supports this server-side via the repeatable eventTypes parameter; this exposes it.

Changes

• --event-types on calendar events, repeatable or comma-separated, honored across single-calendar, --cal/--calendars, and --all paths.
• Accepts all six API types plus friendly aliases: default, birthday, focus-time/focusTime, from-gmail/fromGmail, out-of-office/ooo, working-location/wl. Values are canonicalized and de-duplicated.
• Default unchanged: when the flag is omitted, no eventTypes param is sent, so all types are returned exactly as before. A flag that is present but resolves to no values (e.g. --event-types "") is a usage error, matching gmail watch --history-types.
• Event-type aliases now live in a single shared eventTypeAliases map: the create/update path restricts to the user-creatable types, while the filter accepts all six (including the read-only birthday/fromGmail). This consolidated the previous create-path switch.
• Docs: docs/spec.md + regenerated command reference.

Deliberately not in this PR (happy to add on your call)

• No change to default output or the --plain/table columns. --plain is the stable parseable contract, --json already includes eventType, and event get already prints it — so I left the human/TSV surfaces untouched to keep this strictly additive. If surfacing the event type in the list view would be useful, I'm happy to follow up; I'd defer to you on the form (e.g. a new column vs. an opt-in flag).
• No default-view change. Whether events should hide birthday/workingLocation by default is a reasonable question but a breaking one, so this PR just provides the filter and leaves the default as-is.
• No signature refactor. Threading eventTypes adds another positional param to the already-long calendar_list.go list helpers. I kept it consistent with the existing style rather than refactoring here, but I'd be happy to follow up with a small PR bundling those params into query/view structs if that cleanup would be welcome.

Testing

• Unit: both normalizers (filter accepts all six + aliases; create/update rejects the read-only birthday/fromGmail), the flatten/dedupe resolver (incl. the present-but-empty error), and a guard test for the shared-map invariant (every creatable type is aliased).
• Wiring: asserts the eventTypes query param is sent (in order) when set and absent when unset — at the single-calendar call and across the --cal/--all paths.
• make fmt-check lint docs-check clean; calendar tests pass under -race.

Live (real account, event-type tallies)

$ gog calendar events --days 60 --max 200 --json | jq -r '.events[].eventType' | sort | uniq -c
     34 birthday
    103 default
      3 fromGmail            # 140 total — unchanged default (all types)

$ gog calendar events --days 60 --max 200 --json --event-types default | jq -r '.events[].eventType' | sort | uniq -c
    103 default              # birthdays + fromGmail filtered out

$ gog calendar events --days 60 --max 200 --json --event-types birthday,working-location | jq -r '.events[].eventType' | sort | uniq -c
     34 birthday             # only requested types (no workingLocation events in window)

No CHANGELOG.md entry (treated as release-owned) — happy to add one if you'd prefer.

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed June 22, 2026, 8:31 PM ET / 00:31 UTC.

Summary
The PR adds a repeatable/comma-separated --event-types flag to gog calendar events, canonicalizes Calendar event type aliases, passes them to events.list for single and multi-calendar listings, and updates docs/tests.

Reproducibility: not applicable. this is a feature PR rather than a bug report. The PR body includes live command output showing the new filtered behavior against a real Calendar account.

Review metrics: 2 noteworthy metrics.

• PR scope: 10 files changed, +358/-35. The change spans CLI wiring, request construction, docs, and tests but stays within Calendar event listing.
• New user surface: 1 flag added. --event-types is user-facing, so help text, docs, and live Calendar behavior matter before merge.

Merge readiness
Overall: 🦞 diamond lobster
Proof: 🦞 diamond lobster
Patch quality: 🦞 diamond lobster
Result: ready for maintainer review.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Next step before merge

• [P2] No repair lane is needed because the patch has sufficient proof and no concrete automated fix target from this review.

Security
Cleared: The diff adds CLI parsing, API query parameters, docs, and tests without changing secrets, auth, dependencies, workflows, or code-download paths.

Review details

Best possible solution:

Review and land the focused opt-in filter after normal checks and maintainer approval, preserving the unchanged default event listing behavior.

Do we have a high-confidence way to reproduce the issue?

Not applicable: this is a feature PR rather than a bug report. The PR body includes live command output showing the new filtered behavior against a real Calendar account.

Is this the best way to solve the issue?

Yes: an opt-in server-side eventTypes pass-through is the narrowest maintainable solution and keeps the existing default output unchanged.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against fc13b4147e20.

Label changes

Label changes:

• add P2: This is a normal-priority Calendar CLI feature with useful but limited blast radius and no urgent regression signal.
• add proof: sufficient: Contributor real behavior proof is sufficient. The PR body includes copied live terminal output from a real Calendar account showing default all-type output and filtered event-type results after the change.
• add rating: 🦞 diamond lobster: Overall readiness is 🦞 diamond lobster; proof is 🦞 diamond lobster and patch quality is 🦞 diamond lobster.
• add status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (terminal): The PR body includes copied live terminal output from a real Calendar account showing default all-type output and filtered event-type results after the change.

Label justifications:

• P2: This is a normal-priority Calendar CLI feature with useful but limited blast radius and no urgent regression signal.
• rating: 🦞 diamond lobster: Overall readiness is 🦞 diamond lobster; proof is 🦞 diamond lobster and patch quality is 🦞 diamond lobster.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (terminal): The PR body includes copied live terminal output from a real Calendar account showing default all-type output and filtered event-type results after the change.
• proof: sufficient: Contributor real behavior proof is sufficient. The PR body includes copied live terminal output from a real Calendar account showing default all-type output and filtered event-type results after the change.

Evidence reviewed

What I checked:

• Repository policy read: AGENTS.md was read fully; the review followed the PR-link review mode and checked stdout/scriptability expectations around the new flag. (AGENTS.md:1, fc13b4147e20)
• Current main lacks this filter: Current main has calendarEventsListCall without an eventTypes argument or EventTypes(...) call, and the command docs/spec do not list --event-types. (internal/cmd/calendar_list.go:17, fc13b4147e20)
• PR adds CLI surface: The PR head adds EventTypes []string to CalendarEventsCmd and resolves it before dispatching single, selected-calendar, and all-calendar list paths. (internal/cmd/calendar_events_cmds.go:27, cccc5e1de482)
• PR passes filter to Google API call: The PR head calls call.EventTypes(eventTypes...) only when values are supplied, preserving the unset default behavior. (internal/cmd/calendar_list.go:26, cccc5e1de482)
• PR normalizes supported values: The PR head shares event type aliases while keeping create/update restricted to creatable types and allowing the list filter to accept birthday and fromGmail. (internal/cmd/calendar_event_type.go:23, cccc5e1de482)
• PR adds focused coverage: The PR head includes a multi-calendar command test proving eventTypes reaches both --calendars and --all paths. (internal/cmd/calendar_events_test.go:307, cccc5e1de482)

Likely related people:

• salmonumbrella: Introduced the earlier Calendar event type support and added calendar_event_type.go through the merged Calendar feature work in Add calendar propose-time, tasks repeat, auth alias, and more #75. (role: introduced behavior; confidence: high; commits: 2cdeb8bf73bf; files: internal/cmd/calendar_event_type.go, internal/cmd/calendar_edit.go, internal/cmd/calendar_list.go)
• steipete: Current line blame points the release/current Calendar files at the v0.30.0 release commit, and PR history shows recent direct work/merge involvement around Calendar event-list behavior. (role: recent area contributor; confidence: medium; commits: 48db48b4f61f, d93d17eada2f; files: internal/cmd/calendar_list.go, internal/cmd/calendar_events_cmds.go, internal/cmd/calendar_event_type.go)
• TurboTheTurtle: Recently changed multi-calendar event listing pagination and tests in fix(calendar): hint truncated event pages #831, adjacent to this PR's --all/--calendars event list wiring. (role: recent adjacent contributor; confidence: medium; commits: 968550099bef, d93d17eada2f; files: internal/cmd/calendar_list.go, internal/cmd/calendar_all_events_test.go, internal/cmd/execute_calendar_events_text_test.go)

What the crustacean ranks mean

• 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
• 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
• 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
• 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
• 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
• 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
• 🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.