Improve Maintainability of cal-api-version

[TonyValenti]

Is your proposal related to a problem?

I have a library I am building that interacts with the CAL API. Certain APIs require that I provide the
cal-api-version header in order to access the latest version of the API. The cal-api-version header appears to always be in a date format.

Currently, the API checks for an exact match on the string. If the date exactly matches, then the current version of the API is invoked. If it is NEWER (ie, today's date), then the API actually falls back to using the older version of the API.

When maintaining my library, I'd like to be able to simply provide a single, consistent date to the API and have it just work with the latest version of the API as of that date.

(Write your answer here.)

Describe the solution you'd like

Providing cal-api-version calls the newest API that is <= the date provided.
For example, calling:
https://cal.com/docs/api-reference/v2/event-types/get-all-event-types#parameter-cal-api-version
with cal-api-version: 2026-07-01 should call the current version of that API (v2024-06-14).