Migrate OAuth token endpoints to the 2026-03 API (OME-796)

[mjdobbins12]

HubSpot sunsets the legacy /oauth/v1/ token endpoints on 2027-02-16. Move the three OAuth codegen operations to the 2026-03 replacements:

• TokensApi#create: POST /oauth/v1/token -> POST /oauth/2026-03/token (already form-encoded; response is identical, so no model change).
• AccessTokensApi#get and RefreshTokensApi#get: GET /oauth/v1/{access,refresh}-tokens/{token} -> POST /oauth/2026-03/token/introspect, with token, token_type_hint, client_id and client_secret sent as form-body params (never in the URL). Introspection returns a raw hash rather than a strict model, since the 2026-03 introspect fields differ from v1.
• RefreshTokensApi#archive: DELETE /oauth/v1/refresh-tokens/{token} -> POST /oauth/2026-03/token/revoke, token in the form body.

Method names/signatures are unchanged so callers are unaffected. No /oauth/v1/ path remains in the gem.

[macharmi]

chartmogul/hubspot-api-ruby is a fork of HubSpot/hubspot-api-ruby. Worth knowing why it exists before we merge anything else into it.

The issue that caused the fork was never fixed.

We forked because of the Search API sort bug — sorts was typed Array in the generated models, so sort hashes got stringified and HubSpot silently ignored them. That's upstream issue HubSpot#257, open since September 2023.
The one-line fix was posted in the issue itself by the original reporter. HubSpot committed to fixing it twice — November 2023 ("as soon as we can") and January 2025 ("actively working on resolving it") — and as of today
upstream master still ships the broken type. Our fork's PR #1 carries the patch.

HubSpot also hasn't shipped the OAuth change in any SDK.

The v1 OAuth token endpoints sunset on 2027-02-16, which is what this PR addresses. Current state upstream:

• Upstream master still uses /oauth/v1/... with the old verbs and return types — untouched.
• Issue HubSpot#438, "Migrate from the OAuth v1 API to the latest date-based versioned API", has been open since June 2026 with no reply from HubSpot and no linked PR.
• Searching for 2026-03/token across hubspot-api-ruby, hubspot-api-nodejs, hubspot-api-python and hubspot-api-php returns zero hits. They haven't regenerated any SDK against the new spec.

So there's no upstream implementation to pull in, and based on the HubSpot#257 track record I wouldn't plan around one arriving soon.

Recommendation: hold this PR for now.

Not because the direction is wrong — the endpoint migration is necessary and we have runway until Feb 2027. But merging it as-is has real problems, and we should sequence the work differently:

1. Hold this PR. In its current form it breaks callers in platform (the return type changes from a model to a raw Hash, but Connectors::Hubspot::Tokens::Generate still calls .hub_id on the result), and the required
   client_id/client_secret for introspection are optional in the code and never passed by platform. Detailed review notes are on the PR.
2. Open a separate PR to realign the fork with upstream master first. We're currently 131 commits behind upstream and still on VERSION = 19.0.0 while upstream has shipped v20.0.0. Rebasing gets harder the longer we wait,
   and it's much easier to do before we add a second hand-patch to generated files. This should land first.
3. Track the SDK support question with HubSpot. Watch HubSpot#438, comment on it linking our work, and check whether the OAuth 2026-03 endpoints are represented in their published OpenAPI spec yet — that's what would let them
   (and us) regenerate cleanly rather than hand-editing codegen files. If there's no movement, we escalate through our HubSpot contact and ask directly for a timeline.
4. Document the divergence. We'll soon have two hand-edits to generated files that any regeneration would silently wipe. A short PATCHES.md listing each patch with its upstream issue link (HubSpot#257 for sorts, HubSpot#438 for OAuth)
   means the next person to rebase doesn't lose them.

Once the fork is realigned and we know whether HubSpot intends to ship this themselves, we revisit the OAuth PR with the caller-side changes included.