Refactor: clean up what many devs left untouched (improves DX)

CHANGELOG.md

@@ -14,7 +14,7 @@
   <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="https://github.com/contentful/contentful-management.js/releases">Changelog</a> · 
   <a href="CONTRIBUTING.md">Contributing</a>
 </p>
 

CONTRIBUTING.md

@@ -14,7 +14,7 @@
   <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="https://github.com/contentful/contentful-management.js/releases">Changelog</a> · 
   <a href="CONTRIBUTING.md">Contributing</a>
 </p>
 

SETUP.md

@@ -14,7 +14,7 @@
   <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="https://github.com/contentful/contentful-management.js/releases">Changelog</a> · 
   <a href="CONTRIBUTING.md">Contributing</a>
 </p>
 

lib/adapters/REST/make-request.ts

@@ -2,7 +2,7 @@ import type { AxiosInstance } from 'contentful-sdk-core'
 import type { MakeRequestOptions, MakeRequestPayload } from '../../common-types'
 import type { OpPatch } from 'json-patch'
 import type { RawAxiosRequestHeaders } from 'axios'
-import endpoints from './endpoints'
+import endpoints from './endpoints/index'
 
 type makeAxiosRequest = MakeRequestOptions & {
   axiosInstance: AxiosInstance

lib/common-utils.ts

@@ -1,5 +1,3 @@
-/* eslint-disable @typescript-eslint/ban-ts-comment */
-
 import { toPlainObject } from 'contentful-sdk-core'
 import copy from 'fast-copy'
 import type {
@@ -17,10 +15,11 @@ export const wrapCollection =
   <R, T, Rest extends any[]>(fn: (makeRequest: MakeRequest, entity: T, ...rest: Rest) => R) =>
   (makeRequest: MakeRequest, data: CollectionProp<T>, ...rest: Rest): Collection<R, T> => {
     const collectionData = toPlainObject(copy(data))
-    // @ts-expect-error
-    collectionData.items = collectionData.items.map((entity) => fn(makeRequest, entity, ...rest))
-    // @ts-expect-error
-    return collectionData
+
+    return {
+      ...collectionData,
+      items: collectionData.items.map((entity) => fn(makeRequest, entity, ...rest)),
+    }
   }
 
 export const wrapCursorPaginatedCollection =
@@ -31,10 +30,10 @@ export const wrapCursorPaginatedCollection =
     ...rest: Rest
   ): CursorPaginatedCollection<R, T> => {
     const collectionData = toPlainObject(copy(data))
-    // @ts-expect-error
-    collectionData.items = collectionData.items.map((entity) => fn(makeRequest, entity, ...rest))
-    // @ts-expect-error
-    return collectionData
+    return {
+      ...collectionData,
+      items: collectionData.items.map((entity) => fn(makeRequest, entity, ...rest)),
+    }
   }
 export function isSuccessful(statusCode: number) {
   return statusCode < 300

lib/contentful-management.ts

@@ -4,109 +4,18 @@
  * @packageDocumentation
  */
 
-import { getUserAgentHeader } from 'contentful-sdk-core'
-import type { RestAdapterParams } from './adapters/REST/rest-adapter'
-import type { MakeRequest, XOR } from './common-types'
-import type { AdapterParams } from './create-adapter'
-import { createAdapter } from './create-adapter'
-import type { ClientAPI } from './create-contentful-api'
-import createContentfulApi from './create-contentful-api'
-import type { PlainClientAPI } from './plain/common-types'
-import type { DefaultParams } from './plain/plain-client'
-import { createPlainClient } from './plain/plain-client'
-import * as editorInterfaceDefaults from './constants/editor-interface-defaults'
+export type { PlainClientDefaultParams } from './plain/plain-client'
 
 export type { ClientAPI } from './create-contentful-api'
+export type { PlainClientAPI } from './plain/plain-client-types'
+export type { RestAdapterParams } from './adapters/REST/rest-adapter'
+export type * from './export-types'
+
 export { asIterator } from './plain/as-iterator'
 export { fetchAll } from './plain/pagination-helper'
 export { isDraft, isPublished, isUpdated } from './plain/checks'
-export type { PlainClientAPI } from './plain/common-types'
-export { createClient }
-export { RestAdapter } from './adapters/REST/rest-adapter'
-export type { RestAdapterParams } from './adapters/REST/rest-adapter'
 export { makeRequest } from './adapters/REST/make-request'
-export { editorInterfaceDefaults }
-export type PlainClientDefaultParams = DefaultParams
-export * from './export-types'
-
-interface UserAgentParams {
-  /**
-   * Application name and version e.g myApp/version
-   */
-  application?: string
-  /**
-   * Integration name and version e.g react/version
-   */
-  integration?: string
-
-  feature?: string
-}
-
-/**
- * @deprecated
- */
-export type ClientParams = RestAdapterParams & UserAgentParams
-
-export type ClientOptions = UserAgentParams & XOR<RestAdapterParams, AdapterParams>
-
-/**
- * Create a client instance
- * @param params - Client initialization parameters
- *
- * ```javascript
- * const client = contentfulManagement.createClient({
- *  accessToken: 'myAccessToken'
- * })
- * ```
- */
-function createClient(params: ClientOptions): ClientAPI
-function createClient(
-  params: ClientOptions,
-  opts: {
-    type: 'plain'
-    defaults?: DefaultParams
-  }
-): PlainClientAPI
-// Usually, overloads with more specific signatures should come first but some IDEs are often not able to handle overloads with separate TSDocs correctly
-/**
- * @deprecated The `alphaFeatures` option is no longer supported. Please use the function without this option.
- */
-function createClient(
-  params: ClientOptions,
-  opts: {
-    type?: 'plain'
-    alphaFeatures: string[]
-    defaults?: DefaultParams
-  }
-): ClientAPI | PlainClientAPI
-function createClient(
-  params: ClientOptions,
-  opts: {
-    type?: 'plain'
-    defaults?: DefaultParams
-  } = {}
-): ClientAPI | PlainClientAPI {
-  const sdkMain =
-    opts.type === 'plain' ? 'contentful-management-plain.js' : 'contentful-management.js'
-  const userAgent = getUserAgentHeader(
-    // @ts-expect-error
-    `${sdkMain}/${__VERSION__}`,
-    params.application,
-    params.integration,
-    params.feature
-  )
-
-  const adapter = createAdapter({ ...params, userAgent })
-
-  // Parameters<?> and ReturnType<?> only return the types of the last overload
-  // https://github.com/microsoft/TypeScript/issues/26591
-  // @ts-expect-error
-  const makeRequest: MakeRequest = (options: Parameters<MakeRequest>[0]): ReturnType<MakeRequest> =>
-    adapter.makeRequest({ ...options, userAgent })
+export { RestAdapter } from './adapters/REST/rest-adapter'
+export * as editorInterfaceDefaults from './constants/editor-interface-defaults/index'
 
-  if (opts.type === 'plain') {
-    return createPlainClient(makeRequest, opts.defaults)
-  } else {
-    return createContentfulApi(makeRequest) as ClientAPI
-  }
-}
+export * from './create-client'

lib/create-app-definition-api.ts

@@ -1,5 +1,6 @@
 import type { MakeRequest, QueryOptions, SpaceQueryOptions } from './common-types'
-import entities from './entities'
+import { wrapAppBundle, wrapAppBundleCollection } from './entities/app-bundle'
+import { wrapResourceProvider } from './entities/resource-provider'
 import type { CreateAppBundleProps } from './entities/app-bundle'
 import type { AppDefinitionProps } from './entities/app-definition'
 import { wrapAppDefinition } from './entities/app-definition'
@@ -14,9 +15,6 @@ export type ContentfulAppDefinitionAPI = ReturnType<typeof createAppDefinitionAp
  * @private
  */
 export default function createAppDefinitionApi(makeRequest: MakeRequest) {
-  const { wrapAppBundle, wrapAppBundleCollection } = entities.appBundle
-  const { wrapResourceProvider } = entities.resourceProvider
-
   const getParams = (data: AppDefinitionProps) => ({
     appDefinitionId: data.sys.id,
     organizationId: data.sys.organization.sys.id,

lib/create-client.ts

@@ -0,0 +1,119 @@
+/**
+ * Navigate below to the `createClient` function to get started with using this library.
+ * @module
+ * @category Core
+ */
+import type { AdapterParams } from './create-adapter'
+import type { ClientAPI } from './create-contentful-api'
+import type { PlainClientDefaultParams } from './plain/plain-client'
+import type { MakeRequest, XOR } from './common-types'
+import type { PlainClientAPI } from './plain/plain-client-types'
+import type { RestAdapterParams } from './adapters/REST/rest-adapter'
+
+import { createAdapter } from './create-adapter'
+import { createPlainClient } from './plain/plain-client'
+import { getUserAgentHeader } from 'contentful-sdk-core'
+import { createClientApi } from './create-contentful-api'
+
+interface UserAgentParams {
+  /**
+   * Application name and version e.g myApp/version
+   */
+  application?: string
+  /**
+   * Integration name and version e.g react/version
+   */
+  integration?: string
+
+  feature?: string
+}
+
+export type ClientOptions = UserAgentParams & XOR<RestAdapterParams, AdapterParams>
+
+declare global {
+  const __VERSION__: string
+}
+
+/**
+ * Create a plain client instance
+ *
+ * @param clientOptions
+ * @param opts
+ *
+ * @example Plain Client
+ * ```javascript
+ * const client = contentfulManagement.createClient({
+ *   accessToken: 'myAccessToken',
+ *   opts: {
+ *     type: 'plain'
+ *   }
+ * })
+ * ```
+ * @example Plain Client with defaults
+ * ```javascript
+ * const client = contentfulManagement.createClient({
+ *   accessToken: 'myAccessToken',
+ *   opts: {
+ *     type: 'plain',
+ *     defaults: {
+ *        ...
+ *     }
+ *   }
+ * })
+ * ```
+ */
+export function createClient(
+  clientOptions: ClientOptions,
+  opts: {
+    type: 'plain'
+    defaults?: PlainClientDefaultParams
+  }
+): PlainClientAPI
+/**
+ * Create a legacy, chainable client instance
+ * @param clientOptions
+ *
+ * @example Legacy Chainable Client
+ * ```javascript
+ * const client = contentfulManagement.createClient({
+ *   accessToken: 'myAccessToken'
+ * })
+ * ```
+ */
+export function createClient(clientOptions: ClientOptions): ClientAPI
+/**
+ * Create a legacy or plain client instance
+ *
+ * Please check the corresponding section below:
+ *
+ * * [Plain Client](#createclient)
+ * * [Legacy Chainable Client](#createclient-1)
+ */
+export function createClient(
+  clientOptions: ClientOptions,
+  opts?: {
+    type?: string
+    defaults?: PlainClientDefaultParams
+  }
+): ClientAPI | PlainClientAPI {
+  const sdkMain =
+    opts && opts.type === 'plain' ? 'contentful-management-plain.js' : 'contentful-management.js'
+  const userAgent = getUserAgentHeader(
+    `${sdkMain}/${__VERSION__}`,
+    clientOptions.application,
+    clientOptions.integration,
+    clientOptions.feature
+  )
+
+  const adapter = createAdapter({ ...clientOptions, userAgent })
+
+  // @ts-expect-error Parameters<?> and ReturnType<?> only return the types of the last overload (https://github.com/microsoft/TypeScript/issues/26591)
+  const makeRequest: MakeRequest = (options: Parameters<MakeRequest>[0]): ReturnType<MakeRequest> =>
+    adapter.makeRequest({ ...options, userAgent })
+
+  if (opts && opts.type === 'plain') {
+    return createPlainClient(makeRequest, opts.defaults)
+  } else {
+    return createClientApi(makeRequest) as ClientAPI
+  }
+}

lib/create-contentful-api.ts

@@ -1,3 +1,7 @@
+/**
+ * @module
+ * @category Legacy Client
+ */
 import { createRequestConfig } from 'contentful-sdk-core'
 import type {
   Collection,
@@ -12,7 +16,27 @@ import type {
   GetOAuthApplicationParams,
   GetUserParams,
 } from './common-types'
-import entities from './entities'
+import { wrapSpace, wrapSpaceCollection } from './entities/space'
+import { wrapUser } from './entities/user'
+import {
+  wrapPersonalAccessToken,
+  wrapPersonalAccessTokenCollection,
+} from './entities/personal-access-token'
+import { wrapAccessToken, wrapAccessTokenCollection } from './entities/access-token'
+import { wrapOrganization, wrapOrganizationCollection } from './entities/organization'
+import { wrapUsageCollection } from './entities/usage'
+import { wrapAppDefinition } from './entities/app-definition'
+import {
+  wrapEnvironmentTemplate,
+  wrapEnvironmentTemplateCollection,
+} from './entities/environment-template'
+import type {
+  CreateOAuthApplicationProps,
+  OAuthApplication,
+  OAuthApplicationProps,
+} from './entities/oauth-application'
+import { wrapOAuthApplication, wrapOAuthApplicationCollection } from './entities/oauth-application'
+
 import type { Organization, OrganizationProps } from './entities/organization'
 import type { CreatePersonalAccessTokenProps } from './entities/personal-access-token'
 import type { Space, SpaceProps } from './entities/space'
@@ -25,31 +49,14 @@ import type {
   EnvironmentTemplateProps,
 } from './entities/environment-template'
 import type { RawAxiosRequestConfig } from 'axios'
-import type {
-  CreateOAuthApplicationProps,
-  OAuthApplication,
-  OAuthApplicationProps,
-} from './export-types'
 
 export type ClientAPI = ReturnType<typeof createClientApi>
 type CreateSpaceProps = Omit<SpaceProps, 'sys'> & { defaultLocale?: string }
 
 /**
  * @private
  */
-export default function createClientApi(makeRequest: MakeRequest) {
-  const { wrapSpace, wrapSpaceCollection } = entities.space
-  const { wrapUser } = entities.user
-  const { wrapPersonalAccessToken, wrapPersonalAccessTokenCollection } =
-    entities.personalAccessToken
-  const { wrapAccessToken, wrapAccessTokenCollection } = entities.accessToken
-  const { wrapOrganization, wrapOrganizationCollection } = entities.organization
-  const { wrapUsageCollection } = entities.usage
-  const { wrapAppDefinition } = entities.appDefinition
-  const { wrapEnvironmentTemplate, wrapEnvironmentTemplateCollection } =
-    entities.environmentTemplate
-  const { wrapOAuthApplication, wrapOAuthApplicationCollection } = entities.oauthApplication
-
+export function createClientApi(makeRequest: MakeRequest) {
   return {
     /**
      * Gets all environment templates for a given organization with the lasted version