feat: better (type) docs

[Benedikt Rötsch (axe312ger)]

We plan to finally get the docs of this repository into a good shape. Addressing plenty of complaints:

• Methods missing in the documentation #1304
• Documentation for JavaScript Plain API #1574
• How to filter entry.getMany? #1690
• Docs are unusable. How to create/manage releases? #1821
• Docs suck #1969

Goals

• clean up config and update typedocs
• (ongoing) improving current jsdocs comments
• ensure all types and interfaces are available, so people finally can fully dig around
• ensure already included examples are actually rendered
• clear introduction of both client types
• soft deprecation of legacy chainable client
• clear separation in navigation between plain and chainable client
• reintroduce structure for legacy client like in v4 and v5
• introduce a version selector
• potentially deprecate/discontinue outdated theme https://github.com/contentful/contentful-sdk-jsdoc/ and migrating https://github.com/contentful/contentful-sdk-jsdoc/blob/master/bin/publish-docs.sh directly into this repo, either as circleci action or github workflow

Old typedocs

Improved typedocs (WIP!)

In general, to fix this, constrain the untrusted value (select.value) to a trusted set of allowed versions or otherwise validate/sanitize it before constructing a URL. This avoids arbitrary or malformed values being used to build navigation targets, and also satisfies the static analyzer by breaking the taint flow.

The minimal, behavior-preserving fix here is to ensure that the version chosen from the <select> is one of the known versions from versions.json (plus possibly the preselected currentVersion), and to fall back to currentVersion if it is not. The simplest way is to compute an array allowedVersions once per initialization, containing all values we consider valid (the union of versions and currentVersion, deduplicated), and then, in the change handler, replace var newVersion = select.value with a guarded lookup: if select.value is in allowedVersions, use it; otherwise, revert to currentVersion. Since all other uses of versions and currentVersion remain unchanged, the visible functionality (navigating between known documentation versions) stays the same.

Concretely:

• After the if (!versions || !versions.length) return check and before creating DOM elements, define var allowedVersions = versions.slice() and, if currentVersion is not already in it, push it, then deduplicate if desired.
• In the select.addEventListener('change', ...) handler, compute var selectedValue = select.value; and then var newVersion = allowedVersions.indexOf(selectedValue) !== -1 ? selectedValue : currentVersion;.
• Leave the construction of newUrl unchanged.

No new imports or external libraries are needed; this can be implemented with vanilla JavaScript in the existing file.