One-click tags on HubSpot contacts and companies

There is no tag field you can add to a HubSpot contact or company by hand. The request in HubSpot's ideas forum has 488 votes, and HubSpot marked it Not Currently Planned in May 2020. HubSpot's colour-coded object tags cover deals, tickets and some other objects, but not contacts or companies. They are set by rules, not by hand, and need a paid plan.

The usual workaround is a multiple-checkbox property used as a tag field. Every new tag is a property option, so a user without permission to edit property settings has to ask an admin. Merging two tags means a filter, two bulk edits and deleting an option by hand. On the free CRM, each such property uses one of only 10 custom properties.

• Why it needed a backend. HubSpot's own serverless functions can only be installed by Enterprise accounts, and they aren't available to apps distributed through the Marketplace. A free app for every plan still needs a place for its OAuth tokens. We used a Cloudflare Worker with a D1 database that stores only the encrypted tokens, each tag's colour and two settings.
• OAuth and trust. The Worker exchanges the install code for tokens, encrypts them with AES-GCM bound to the account id, and after install redirects only to HubSpot addresses. Every call from the card or settings page must carry a valid HubSpot signature and exactly one account id and user id, so a request can't point at another account. Every change on the settings page needs a Super Admin, which the Worker checks with HubSpot.
• Two people tagging the same record. Adds use HubSpot's append syntax, so two people adding tags at once don't overwrite each other. Changes to the list of tags take a short lock and re-check the list right before the write.
• Rename and merge across many records. Merge and delete run in steps of up to 500 records, with a lock on the object held across steps so two admins can't run conflicting jobs. Each page re-reads current values with a batch read, because search results can lag, and re-reads the tag list so a tag created meanwhile isn't stripped. At the end, a final pass and one last search confirm that no record still carries the old tag before the option is removed.
• Staying inside the limits. Cloudflare caps the outbound calls one Worker request can make. Each step tracks its HubSpot call budget, caps retries, times out a call after 15 seconds and hands back a cursor before it runs out, and the settings page keeps calling until the job is finished. HubSpot replays a card's request to the backend if it fails with a server error, so the Worker reports HubSpot outages as client errors, to avoid repeated writes.
• HubSpot's own rules. A multiple-checkbox property can't exist without options, so the property is created with the first tag, and the last tag can't be deleted. When an account uninstalls, an hourly job notices the revoked token, deletes it, and purges the colours and settings 30 days later unless the account installs again.