Skip to content

Commit 1e3d873

Browse files
axe312gerwhitelisab
axe312ger
and
whitelisab
authored
Refactor/restructure and improve docs (#2592)
* docs: categorize navigation for better plain and legacy client destinction * refactor: move createClient in its own file and rename defaultProps to plainClientDefaultProps * docs: add descriptions to our entity status check functions * Update lib/create-client.ts Co-authored-by: Lisa White <[email protected]> * Update lib/plain/checks.ts Co-authored-by: Lisa White <[email protected]> * refactor: simplify or remove @ts-expect-errors * chore: set createAssetApi to private again --------- Co-authored-by: Lisa White <[email protected]>
1 parent 8d57f3a commit 1e3d873

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

77 files changed

+532
-158
lines changed

‎lib/common-utils.ts‎

Lines changed: 9 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,3 @@
1-
/* eslint-disable @typescript-eslint/ban-ts-comment */
2-
31
import { toPlainObject } from 'contentful-sdk-core'
42
import copy from 'fast-copy'
53
import type {
@@ -17,10 +15,11 @@ export const wrapCollection =
1715
<R, T, Rest extends any[]>(fn: (makeRequest: MakeRequest, entity: T, ...rest: Rest) => R) =>
1816
(makeRequest: MakeRequest, data: CollectionProp<T>, ...rest: Rest): Collection<R, T> => {
1917
const collectionData = toPlainObject(copy(data))
20-
// @ts-expect-error
21-
collectionData.items = collectionData.items.map((entity) => fn(makeRequest, entity, ...rest))
22-
// @ts-expect-error
23-
return collectionData
18+
19+
return {
20+
...collectionData,
21+
items: collectionData.items.map((entity) => fn(makeRequest, entity, ...rest)),
22+
}
2423
}
2524

2625
export const wrapCursorPaginatedCollection =
@@ -31,10 +30,10 @@ export const wrapCursorPaginatedCollection =
3130
...rest: Rest
3231
): CursorPaginatedCollection<R, T> => {
3332
const collectionData = toPlainObject(copy(data))
34-
// @ts-expect-error
35-
collectionData.items = collectionData.items.map((entity) => fn(makeRequest, entity, ...rest))
36-
// @ts-expect-error
37-
return collectionData
33+
return {
34+
...collectionData,
35+
items: collectionData.items.map((entity) => fn(makeRequest, entity, ...rest)),
36+
}
3837
}
3938
export function isSuccessful(statusCode: number) {
4039
return statusCode < 300

‎lib/contentful-management.ts‎

Lines changed: 2 additions & 115 deletions
Original file line numberDiff line numberDiff line change
@@ -4,23 +4,12 @@
44
* @packageDocumentation
55
*/
66

7-
import type { AdapterParams } from './create-adapter'
8-
import type { ClientAPI } from './create-contentful-api'
9-
import type { DefaultParams } from './plain/plain-client'
10-
import type { MakeRequest, XOR } from './common-types'
11-
import type { PlainClientAPI } from './plain/plain-client-types'
12-
import type { RestAdapterParams } from './adapters/REST/rest-adapter'
13-
14-
import { createAdapter } from './create-adapter'
15-
import { createPlainClient } from './plain/plain-client'
16-
import { getUserAgentHeader } from 'contentful-sdk-core'
17-
import createContentfulApi from './create-contentful-api'
7+
export type { PlainClientDefaultParams } from './plain/plain-client'
188

199
export type { ClientAPI } from './create-contentful-api'
2010
export type { PlainClientAPI } from './plain/plain-client-types'
2111
export type { RestAdapterParams } from './adapters/REST/rest-adapter'
2212
export type * from './export-types'
23-
export type PlainClientDefaultParams = DefaultParams
2413

2514
export { asIterator } from './plain/as-iterator'
2615
export { fetchAll } from './plain/pagination-helper'
@@ -29,106 +18,4 @@ export { makeRequest } from './adapters/REST/make-request'
2918
export { RestAdapter } from './adapters/REST/rest-adapter'
3019
export * as editorInterfaceDefaults from './constants/editor-interface-defaults/index'
3120

32-
interface UserAgentParams {
33-
/**
34-
* Application name and version e.g myApp/version
35-
*/
36-
application?: string
37-
/**
38-
* Integration name and version e.g react/version
39-
*/
40-
integration?: string
41-
42-
feature?: string
43-
}
44-
45-
export type ClientOptions = UserAgentParams & XOR<RestAdapterParams, AdapterParams>
46-
47-
/**
48-
* Create a plain client instance
49-
*
50-
* @param clientOptions
51-
* @param opts
52-
*
53-
* @example Plain Client
54-
* ```javascript
55-
* const client = contentfulManagement.createClient({
56-
* accessToken: 'myAccessToken',
57-
* opts: {
58-
* type: 'plain'
59-
* }
60-
* })
61-
* ```
62-
* @example Plain Client with defaults
63-
* ```javascript
64-
* const client = contentfulManagement.createClient({
65-
* accessToken: 'myAccessToken',
66-
* opts: {
67-
* type: 'plain',
68-
* defaults: {
69-
* ...
70-
* }
71-
* }
72-
* })
73-
* ```
74-
*/
75-
function createClient(
76-
clientOptions: ClientOptions,
77-
opts: {
78-
type: 'plain'
79-
defaults?: DefaultParams
80-
}
81-
): PlainClientAPI
82-
/**
83-
* Create a legacy, chainable client instance
84-
* @param clientOptions
85-
*
86-
* @example Legacy Chainable Client
87-
* ```javascript
88-
* const client = contentfulManagement.createClient({
89-
* accessToken: 'myAccessToken'
90-
* })
91-
* ```
92-
*/
93-
function createClient(clientOptions: ClientOptions): ClientAPI
94-
/**
95-
* Create a legacy or plain client instance
96-
*
97-
* Please check the responding section below:
98-
*
99-
* * [Plain Client](#createclient)
100-
* * [Legacy Chainable Client](#createclient-1)
101-
*/
102-
function createClient(
103-
clientOptions: ClientOptions,
104-
opts?: {
105-
type?: string
106-
defaults?: DefaultParams
107-
}
108-
): ClientAPI | PlainClientAPI {
109-
const sdkMain =
110-
opts && opts.type === 'plain' ? 'contentful-management-plain.js' : 'contentful-management.js'
111-
const userAgent = getUserAgentHeader(
112-
// @ts-expect-error
113-
`${sdkMain}/${__VERSION__}`,
114-
clientOptions.application,
115-
clientOptions.integration,
116-
clientOptions.feature
117-
)
118-
119-
const adapter = createAdapter({ ...clientOptions, userAgent })
120-
121-
// Parameters<?> and ReturnType<?> only return the types of the last overload
122-
// https://github.com/microsoft/TypeScript/issues/26591
123-
// @ts-expect-error
124-
const makeRequest: MakeRequest = (options: Parameters<MakeRequest>[0]): ReturnType<MakeRequest> =>
125-
adapter.makeRequest({ ...options, userAgent })
126-
127-
if (opts && opts.type === 'plain') {
128-
return createPlainClient(makeRequest, opts.defaults)
129-
} else {
130-
return createContentfulApi(makeRequest) as ClientAPI
131-
}
132-
}
133-
134-
export { createClient }
21+
export * from './create-client'

‎lib/create-client.ts‎

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
/**
2+
* Navigate below to the `createClient` function to get started with using this library.
3+
* @module
4+
* @category Core
5+
*/
6+
import type { AdapterParams } from './create-adapter'
7+
import type { ClientAPI } from './create-contentful-api'
8+
import type { PlainClientDefaultParams } from './plain/plain-client'
9+
import type { MakeRequest, XOR } from './common-types'
10+
import type { PlainClientAPI } from './plain/plain-client-types'
11+
import type { RestAdapterParams } from './adapters/REST/rest-adapter'
12+
13+
import { createAdapter } from './create-adapter'
14+
import { createPlainClient } from './plain/plain-client'
15+
import { getUserAgentHeader } from 'contentful-sdk-core'
16+
import { createClientApi } from './create-contentful-api'
17+
18+
interface UserAgentParams {
19+
/**
20+
* Application name and version e.g myApp/version
21+
*/
22+
application?: string
23+
/**
24+
* Integration name and version e.g react/version
25+
*/
26+
integration?: string
27+
28+
feature?: string
29+
}
30+
31+
export type ClientOptions = UserAgentParams & XOR<RestAdapterParams, AdapterParams>
32+
33+
declare global {
34+
const __VERSION__: string
35+
}
36+
37+
/**
38+
* Create a plain client instance
39+
*
40+
* @param clientOptions
41+
* @param opts
42+
*
43+
* @example Plain Client
44+
* ```javascript
45+
* const client = contentfulManagement.createClient({
46+
* accessToken: 'myAccessToken',
47+
* opts: {
48+
* type: 'plain'
49+
* }
50+
* })
51+
* ```
52+
* @example Plain Client with defaults
53+
* ```javascript
54+
* const client = contentfulManagement.createClient({
55+
* accessToken: 'myAccessToken',
56+
* opts: {
57+
* type: 'plain',
58+
* defaults: {
59+
* ...
60+
* }
61+
* }
62+
* })
63+
* ```
64+
*/
65+
export function createClient(
66+
clientOptions: ClientOptions,
67+
opts: {
68+
type: 'plain'
69+
defaults?: PlainClientDefaultParams
70+
}
71+
): PlainClientAPI
72+
/**
73+
* Create a legacy, chainable client instance
74+
* @param clientOptions
75+
*
76+
* @example Legacy Chainable Client
77+
* ```javascript
78+
* const client = contentfulManagement.createClient({
79+
* accessToken: 'myAccessToken'
80+
* })
81+
* ```
82+
*/
83+
export function createClient(clientOptions: ClientOptions): ClientAPI
84+
/**
85+
* Create a legacy or plain client instance
86+
*
87+
* Please check the corresponding section below:
88+
*
89+
* * [Plain Client](#createclient)
90+
* * [Legacy Chainable Client](#createclient-1)
91+
*/
92+
export function createClient(
93+
clientOptions: ClientOptions,
94+
opts?: {
95+
type?: string
96+
defaults?: PlainClientDefaultParams
97+
}
98+
): ClientAPI | PlainClientAPI {
99+
const sdkMain =
100+
opts && opts.type === 'plain' ? 'contentful-management-plain.js' : 'contentful-management.js'
101+
const userAgent = getUserAgentHeader(
102+
`${sdkMain}/${__VERSION__}`,
103+
clientOptions.application,
104+
clientOptions.integration,
105+
clientOptions.feature
106+
)
107+
108+
const adapter = createAdapter({ ...clientOptions, userAgent })
109+
110+
// @ts-expect-error Parameters<?> and ReturnType<?> only return the types of the last overload (https://github.com/microsoft/TypeScript/issues/26591)
111+
const makeRequest: MakeRequest = (options: Parameters<MakeRequest>[0]): ReturnType<MakeRequest> =>
112+
adapter.makeRequest({ ...options, userAgent })
113+
114+
if (opts && opts.type === 'plain') {
115+
return createPlainClient(makeRequest, opts.defaults)
116+
} else {
117+
return createClientApi(makeRequest) as ClientAPI
118+
}
119+
}

‎lib/create-contentful-api.ts‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,7 @@
1+
/**
2+
* @module
3+
* @category Legacy Client
4+
*/
15
import { createRequestConfig } from 'contentful-sdk-core'
26
import type {
37
Collection,
@@ -52,7 +56,7 @@ type CreateSpaceProps = Omit<SpaceProps, 'sys'> & { defaultLocale?: string }
5256
/**
5357
* @private
5458
*/
55-
export default function createClientApi(makeRequest: MakeRequest) {
59+
export function createClientApi(makeRequest: MakeRequest) {
5660
return {
5761
/**
5862
* Gets all environment templates for a given organization with the lasted version

‎lib/entities/access-token.ts‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,7 @@
1+
/**
2+
* @module
3+
* @category Entities
4+
*/
15
import copy from 'fast-copy'
26
import { freezeSys, toPlainObject } from 'contentful-sdk-core'
37
import enhanceWithMethods from '../enhance-with-methods'

‎lib/entities/api-key.ts‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,7 @@
1+
/**
2+
* @module
3+
* @category Entities
4+
*/
15
import { freezeSys, toPlainObject } from 'contentful-sdk-core'
26
import copy from 'fast-copy'
37
import type { DefaultElements, MakeRequest, MetaLinkProps, MetaSysProps } from '../common-types'

‎lib/entities/app-access-token.ts‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,7 @@
1+
/**
2+
* @module
3+
* @category Entities
4+
*/
15
import copy from 'fast-copy'
26
import { freezeSys, toPlainObject } from 'contentful-sdk-core'
37
import type { Except } from 'type-fest'

‎lib/entities/app-action-call.ts‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,7 @@
1+
/**
2+
* @module
3+
* @category Entities
4+
*/
15
import copy from 'fast-copy'
26
import { toPlainObject } from 'contentful-sdk-core'
37
import type { Except } from 'type-fest'

‎lib/entities/app-action.ts‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,7 @@
1+
/**
2+
* @module
3+
* @category Entities
4+
*/
15
import { freezeSys, toPlainObject } from 'contentful-sdk-core'
26
import copy from 'fast-copy'
37
import type { Except } from 'type-fest'

‎lib/entities/app-bundle.ts‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,7 @@
1+
/**
2+
* @module
3+
* @category Entities
4+
*/
15
import { freezeSys, toPlainObject } from 'contentful-sdk-core'
26
import copy from 'fast-copy'
37
import type { Except } from 'type-fest'

0 commit comments

Comments
 (0)