Add Zetkin and Mailchimp bulk tag helpers for branch re-tagging

[conatus]

Part of JOIN-151.

GMTU's existing membership needs re-tagging after a branch reorganisation, across both Zetkin and Mailchimp. Neither service exposes what a bulk job needs: a way to walk the membership, and tag writes that report failure per member rather than throwing, so one bad record does not stop the run.

The re-tag command itself lives in the GMTU add-on (gmtu#11). Nothing here changes existing behaviour.

Zetkin

Method	Returns
listPeople($page, $perPage)	One page of people, empty when exhausted or unconfigured
getPersonTags($personId)	That person's tags
findOrCreateTagByTitle($title)	The tag record, or null if unconfigured
tryAddTagToPerson($personId, $tagId)	TAG_OK / TAG_NOT_CONFIGURED / TAG_ERROR
tryRemoveTagFromPerson($personId, $tagId)	as above, plus TAG_MISSING on a 404

Both services' try* pairs now share one contract: they report a TAG_* constant. Both sets of wire values are pinned by tests, since the GMTU add-on compares against them across a plugin boundary.

One assumption worth checking before the bulk run. TAG_MISSING is a Zetkin 404 on DELETE /people/{id}/tags/{tagId}, and the add-on treats it as success on the reading that the person simply did not carry that tag. A 404 could also mean the person or the tag no longer exists. In a re-tag run that is unlikely, since the walk listed the person seconds earlier, but a member deleted mid-run would be logged as a successful removal rather than a problem. Worth watching in the dry run rather than taking on trust. Mailchimp's TAG_NOT_FOUND is a different fact — the member is not in the audience at all — which is why the two are named differently.

Zetkin was searched for a person by email in four places — findPersonByEmail, updatePerson, addTag and removeTag — each repeating the POST, the error check and the filter down to exact matches. addTag and removeTag were otherwise near-identical forty-five line twins. searchPeopleByEmail now holds the search and setTagByEmail the shared body, so both are one-liners. Net 58 lines removed.

The search returns every exact match rather than the first, because addTag/removeTag tagged all of them while findPersonByEmail took the first. Both behaviours are preserved; nothing stops Zetkin holding duplicate emails.

The PUT and DELETE tag calls were also written inline twice in addPerson; they are now putPersonTag and deletePersonTag, shared with the new helpers. A 404 on delete is still not logged as an error.

As with Mailchimp, the log wording in addTag/removeTag changes: the messages varied by verb and preposition and parameterising them cost more than the duplication did. Nothing asserts on them.

Mailchimp

updateListMemberTags was being built in four places, each repeating the audience lookup, subscriber hash and payload shape. There is now one private updateMemberTags, used by signup(), addTag(), removeTag() and the new pair. A hook for extension plugins has one home rather than four.

Method	Returns
isConfigured()	bool
tryAddTag($email, $tag, $client = null)	TAG_OK / TAG_NOT_FOUND / TAG_NOT_CONFIGURED / TAG_ERROR
tryRemoveTag($email, $tag, $client = null)	same

addTag and removeTag were near-identical seventeen-line twins; they are now two-line wrappers over a shared setTagOrThrow, matching the shape of the new pair. Four public methods, two private error policies, one place the call is built.

tryAddTag/tryRemoveTag name the axis that actually differs, which is error policy. addTagToMember did not: it took an email and added a tag, exactly like addTag.

Their throwing contract is unchanged: the primitive does not catch, so they log and rethrow the original ClientException rather than re-wrapping it. External code catching it is unaffected.

One thing is not behaviour-preserving: their log wording. The old messages were parameterised on method name and preposition ("Added tag 'x' to", "Removed tag 'x' from"); threading those through cost more clarity than the duplication did. They now read Set Mailchimp tag 'x' to active for <email>. Nothing asserts on these strings, but anyone grepping logs for the old wording should know.

not_found comes from the 404 rather than a memberExists() pre-check, halving the API calls per member across a full walk.

Test seams and regression coverage

The email-based tag paths in both services run during joins and Stripe webhooks but had no coverage: getZetkinContext() performs a live OAuth exchange and getClient() builds a real Mailchimp client. Two seams fix that — overrideZetkinContext() stands in for the OAuth exchange, and addTag/removeTag/memberExists take the same optional injected client the try* pair already had. getTags and findOrCreateTag now reuse the caller's client instead of constructing a fresh Guzzle client per call.

Twenty-six regression tests pin what the callers rely on, including: addTag tags every exact email match (Zetkin can hold duplicates) and ignores fuzzy near-misses; a missing person is a warning and a no-op; Zetkin failures are logged and swallowed while Mailchimp rethrows the original exception; removing an absent tag is a non-event; listPeople sends p/pp; findOrCreateTagByTitle reuses existing tags rather than creating duplicates.

The seam earned its keep immediately: the first run caught findOrCreateTagByTitle failing to destructure the client it passes along, which would have been a fatal on first production use.

Review notes

• Zetkin's paging parameters (p, pp) are pinned by test as to what we send, but remain unverified against the live API. The add-on guards against a walk that never advances rather than trusting them.
• listPeople opens its own Zetkin context per call, so a full walk costs one OAuth exchange per page.
• getZetkinContext() returning an array destructured identically at many call sites is ugly; several predate this PR. Worth a follow-up rather than bundling here.
• signup() applies ck_join_flow_add_tags and ck_join_flow_mailchimp_add_tags; the direct tag methods apply no filters. A new hook at the primitives would cover every path, but that existing inconsistency is untouched and may want its own ticket.
• Correction to something I said earlier on this PR: I described addTag and removeTag as byte-for-byte unchanged. Their behaviour is, but their signatures are not — both, and memberExists, gained an optional trailing $client for the test seam. Backwards compatible for every existing caller, but not the "no signature change" I claimed.
• overrideZetkinContext() is mutable static state on a class used during live signups. It is public, documented as a test seam and reset in tearDown. The alternative, threading a client through every public method, was larger than this PR should carry, but it is a fair thing to object to.
• Nothing structural protects the contract between this plugin and the add-on. The pinned wire values catch a constant's value drifting and the method_exists guard catches a method disappearing, but neither would catch a return type changing — which is exactly what the bool to TAG_* change here was. That was caught by a test written on purpose, not by the type system. It is the real residual risk of two separately deployed plugins sharing a string protocol.

Testing

193 passing. MailchimpServiceTagsTest covers both tag states, the md5-of-lowercased-email subscriber hash, 404 versus other client errors versus unexpected throwables, and the unconfigured path making no call. The TAG_* values are pinned by a test because the add-on compares against them across a plugin boundary.

Written test-first and reverse-tested: collapsing not_found into error, sending active on remove, not lowercasing the hash, or making the primitive swallow exceptions each fail the suite.

Merge order

Merge, then push the version tag manually — release-plugin.yml fires on a tag, not on merge. gmtu#11 follows; it refuses to run against an older parent.

🤖 Generated with Claude Code

[linear-code]

JOIN-151

[conatus]

Feels to me we need to think a bit more about this before merging it.

[conatus]

@joaquimds

Can you check this out and see if the robot scratched your particular itch?

[joaquimds]

The Zetkin service has the same issue, actually... I don't really care... up to you @conatus