feat: better docs

README.md

@@ -13,7 +13,6 @@
 <p align="center">
   <a href="README.md">Readme</a> · 
   <a href="SETUP.md">Setup</a> · 
-  <a href="MIGRATION.md">Migration</a> · 
   <a href="CHANGELOG.md">Changelog</a> · 
   <a href="CONTRIBUTING.md">Contributing</a>
 </p>
@@ -43,29 +42,44 @@
 
 <!-- TOC -->
 
-- [Features](#features)
-- [Supported Environments](#supported-environments)
-- [Getting Started](#getting-started)
+- [Getting started](#getting-started)
   - [Installation](#installation)
-    - [Node](#node-)
-    - [Browser](#browser-)
-    - [Typings](#typings)
+    - [Node:](#node)
+    - [Browser:](#browser)
+  - [Typings](#typings)
   - [Authentication](#authentication)
   - [Using ES6 import](#using-es6-import)
-  - [Your first Request](#your-first-request)
-  - [Alternative plain API](#alternative-plain-api)
-- [App Framework](#app-framework)
-- [Troubleshooting](#troubleshooting)
-- [Documentation/References](#documentationreferences)
+  - [Your first request](#your-first-request)
+  - [Legacy Client Interface](#legacy-client-interface)
+  - [App Framework](#app-framework)
+  - [Troubleshooting](#troubleshooting)
+  - [Documentation/References](#documentationreferences)
   - [Configuration](#configuration)
-  - [Reference Documentation](#reference-documentation)
-  - [Contentful Javascript resources](#contentful-javascript-resources)
-  - [REST API reference](#rest-api-reference)
-- [Versioning](#versioning)
-- [Reach out to us](#reach-out-to-us)
-- [Get involved](#get-involved)
-- [License](#license)
-- [Code of Conduct](#code-of-conduct)
+    - [accessToken (required, when `apiAdapter` is not set)](#accesstoken-required-when-apiadapter-is-not-set)
+    - [host (default: `'api.contentful.com'`)](#host-default-apicontentfulcom)
+    - [hostUpload (default: `'upload.contentful.com'`)](#hostupload-default-uploadcontentfulcom)
+    - [basePath (default: \`\`)](#basepath-default-)
+    - [httpAgent (default: `undefined`)](#httpagent-default-undefined)
+    - [httpsAgent (default: `undefined`)](#httpsagent-default-undefined)
+    - [headers (default: `{}`)](#headers-default-)
+    - [proxy (default: `undefined`)](#proxy-default-undefined)
+    - [retryOnError (default: `true`)](#retryonerror-default-true)
+    - [logHandler (default: `function (level, data) {}`)](#loghandler-default-function-level-data-)
+    - [requestLogger (default: `function (config) {}`)](#requestlogger-default-function-config-)
+    - [responseLogger (default: `function (response) {}`)](#responselogger-default-function-response-)
+    - [apiAdapter (default: `new RestAdapter(configuration)`)](#apiadapter-default-new-restadapterconfiguration)
+    - [throttle (default: `0`)](#throttle-default-0)
+    - [Reference documentation](#reference-documentation)
+    - [Contentful JavaScript resources](#contentful-javascript-resources)
+    - [REST API reference](#rest-api-reference)
+  - [Versioning](#versioning)
+  - [Reach out to us](#reach-out-to-us)
+    - [You have questions about how to use this library?](#you-have-questions-about-how-to-use-this-library)
+    - [You found a bug or want to propose a feature?](#you-found-a-bug-or-want-to-propose-a-feature)
+    - [You need to share confidential information or have other questions?](#you-need-to-share-confidential-information-or-have-other-questions)
+  - [Get involved](#get-involved)
+  - [License](#license)
+  - [Code of Conduct](#code-of-conduct)
 
 <!-- /TOC -->
 </details>

lib/adapters/REST/endpoints/access-token.ts

@@ -15,7 +15,8 @@ import * as raw from './raw'
  * @param {Object} params - Parameters for the request.
  * @param {string} params.tokenId - The unique token ID of the access token to retrieve.
  * @returns {Promise<AccessTokenProps>} A Promise that resolves with the retrieved access token information.
- * @example ```javascript
+ * @example
+ * ```javascript
  * const contentful = require('contentful-management')
  *
  * const plainClient = contentful.createClient(
@@ -42,7 +43,8 @@ export const get: RestEndpoint<'AccessToken', 'get'> = (
  * @param {AxiosInstance} http - An Axios HTTP client instance.
  * @param {QueryParams} params - Query parameters to filter and customize the request.
  * @returns {Promise<CollectionProp<AccessTokenProps>>} A Promise that resolves with a collection of access token properties.
- * @example ```javascript
+ * @example
+ * ```javascript
  * const contentful = require('contentful-management')
  *
  * const plainClient = contentful.createClient(
@@ -73,7 +75,8 @@ export const getMany: RestEndpoint<'AccessToken', 'getMany'> = (
  * @param {CreatePersonalAccessTokenProps} rawData - Data for creating the personal access token.
  * @param {RawAxiosRequestHeaders} [headers] - Optional HTTP headers for the request.
  * @returns {Promise<AccessTokenProps>} A Promise that resolves with the created personal access token.
- * @example ```javascript
+ * @example
+ * ```javascript
  * const contentful = require('contentful-management')
  *
  * const plainClient = contentful.createClient(
@@ -105,7 +108,8 @@ export const createPersonalAccessToken: RestEndpoint<'AccessToken', 'createPerso
  * @param {Object} params - The parameters for revoking the access token.
  * @param {string} params.tokenId - The unique identifier of the access token to revoke.
  * @returns {Promise<AccessTokenProps>} A Promise that resolves with the updated access token information after revocation.
- * @example ```javascript
+ * @example
+ * ```javascript
  * const contentful = require('contentful-management')
  *
  * const plainClient = contentful.createClient(
@@ -133,7 +137,8 @@ export const revoke: RestEndpoint<'AccessToken', 'revoke'> = (
  * @param {GetOrganizationParams & QueryParams} params - Parameters for the request, including organization ID and query parameters.
  * @param {string} params.organizationId - The unique identifier of the organization.
  * @returns {Promise<CollectionProp<AccessTokenProps>>} A promise that resolves to a collection of access tokens.
- * @example ```javascript
+ * @example
+ * ```javascript
  * const contentful = require('contentful-management')
  *
  * const plainClient = contentful.createClient(

lib/adapters/REST/endpoints/oauth-application.ts

@@ -22,7 +22,8 @@ import type {
  * @param {string} params.userId - The unique user ID of the user.
  * @param {string} params.oauthApplicationId - The unique application ID of the OAuth application.
  * @returns {Promise<OAuthApplicationProps>} A Promise that resolves with the retrieved OAuth Application.
- * @example ```javascript
+ * @example
+ * ```javascript
  * const contentful = require('contentful-management')
  *
  * const plainClient = contentful.createClient(
@@ -54,7 +55,8 @@ export const get: RestEndpoint<'OAuthApplication', 'get'> = (
  * @param {string} params.userId - The unique user ID of the user.
  * @param {QueryParams} params - Query parameters to filter and customize the request.
  * @returns {Promise<CursorPaginatedCollectionProp<OAuthApplicationProps>>} A Promise that resolves with a collection of oauth application properties.
- * @example ```javascript
+ * @example
+ * ```javascript
  * const contentful = require('contentful-management')
  *
  * const plainClient = contentful.createClient(
@@ -89,7 +91,8 @@ export const getManyForUser: RestEndpoint<'OAuthApplication', 'getManyForUser'>
  * @param {string} params.userId - The unique user ID of the user.
  * @param {RawAxiosRequestHeaders} [headers] - Optional HTTP headers for the request.
  * @returns {Promise<OAuthApplicationProps>} A Promise that resolves with the created oauth application.
- * @example ```javascript
+ * @example
+ * ```javascript
  * const contentful = require('contentful-management')
  *
  * const plainClient = contentful.createClient(
@@ -130,7 +133,8 @@ export const create: RestEndpoint<'OAuthApplication', 'create'> = (
  * @param {string} params.userId - The unique user ID of the user.
  * @param {string} params.oauthApplicationId - The unique application ID of the OAuth application.
  * @returns {Promise<OAuthApplicationProps>} A Promise that resolves with the updated oauth application.
- * @example ```javascript
+ * @example
+ * ```javascript
  * const contentful = require('contentful-management')
  *
  * const plainClient = contentful.createClient(
@@ -171,7 +175,8 @@ export const update: RestEndpoint<'OAuthApplication', 'update'> = (
  * @param {string} params.userId - The unique user ID of the user.
  * @param {string} params.oauthApplicationId - The unique application ID of the OAuth application.
  * @returns {Promise<void>}
- * @example ```javascript
+ * @example
+ * ```javascript
  * const contentful = require('contentful-management')
  *
  * const plainClient = contentful.createClient(

lib/create-app-definition-api.ts

@@ -25,8 +25,9 @@ export default function createAppDefinitionApi(makeRequest: MakeRequest) {
   return {
     /**
      * Sends an update to the server with any changes made to the object's properties
-     * @return Object returned from the server with updated changes.
-     * @example ```javascript
+     * @returns Object returned from the server with updated changes.
+     * @example
+     * ```javascript
      * const contentful = require('contentful-management')
      *
      * const client = contentful.createClient({
@@ -56,8 +57,9 @@ export default function createAppDefinitionApi(makeRequest: MakeRequest) {
 
     /**
      * Deletes this object on the server.
-     * @return Promise for the deletion. It contains no data, but the Promise error case should be handled.
-     * @example ```javascript
+     * @returns Promise for the deletion. It contains no data, but the Promise error case should be handled.
+     * @example
+     * ```javascript
      * const contentful = require('contentful-management')
      *
      * const client = contentful.createClient({
@@ -83,8 +85,9 @@ export default function createAppDefinitionApi(makeRequest: MakeRequest) {
     /**
      * Gets an app bundle
      * @param id - AppBundle ID
-     * @return Promise for an AppBundle
-     * @example ```javascript
+     * @returns Promise for an AppBundle
+     * @example
+     * ```javascript
      * const contentful = require('contentful-management')
      * const client = contentful.createClient({
      *   accessToken: '<content_management_api_key>'
@@ -112,8 +115,9 @@ export default function createAppDefinitionApi(makeRequest: MakeRequest) {
 
     /**
      * Gets a collection of AppBundles
-     * @return Promise for a collection of AppBundles
-     * @example ```javascript
+     * @returns Promise for a collection of AppBundles
+     * @example
+     * ```javascript
      * const contentful = require('contentful-management')
      * const client = contentful.createClient({
      *   accessToken: '<content_management_api_key>'
@@ -138,8 +142,9 @@ export default function createAppDefinitionApi(makeRequest: MakeRequest) {
     /**
      * Creates an app bundle
      * @param Object representation of the App Bundle to be created
-     * @return Promise for the newly created AppBundle
-     * @example ```javascript
+     * @returns Promise for the newly created AppBundle
+     * @example
+     * ```javascript
      * const contentful = require('contentful-management')
      * const client = contentful.createClient({
      *   accessToken: '<content_management_api_key>'
@@ -167,8 +172,9 @@ export default function createAppDefinitionApi(makeRequest: MakeRequest) {
     /**
      * Gets a list of App Installations across an org for given organization and App Definition
      * If a spaceId is provided in the query object, it will return the App Installations for that specific space.
-     * @return Promise for the newly created AppBundle
-     * @example ```javascript
+     * @returns Promise for the newly created AppBundle
+     * @example
+     * ```javascript
      * const contentful = require('contentful-management')
      * const client = contentful.createClient({
      *   accessToken: '<content_management_api_key>'
@@ -196,8 +202,9 @@ export default function createAppDefinitionApi(makeRequest: MakeRequest) {
     /**
      * Creates or updates a resource provider
      * @param data representation of the ResourceProvider
-     * @return Promise for the newly created or updated ResourceProvider
-     * @example ```javascript
+     * @returns Promise for the newly created or updated ResourceProvider
+     * @example
+     * ```javascript
      * const contentful = require('contentful-management')
      * const client = contentful.createClient({
      *   accessToken: '<content_management_api_key>'
@@ -237,8 +244,9 @@ export default function createAppDefinitionApi(makeRequest: MakeRequest) {
     },
     /**
      * Gets a Resource Provider
-     * @return Promise for a Resource Provider
-     * @example ```javascript
+     * @returns Promise for a Resource Provider
+     * @example
+     * ```javascript
      * const contentful = require('contentful-management')
      * const client = contentful.createClient({
      *   accessToken: '<content_management_api_key>'