feat: add integration for locale based publishing in CDA [TOL-3653]

README.md

@@ -340,12 +340,13 @@ When initialising a client, you will receive an instance of the [`ContentfulClie
 
 #### Entries
 
-| Chain                      | Modifier                                                                                                                                                                                         |
-| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| _none (default)_           | Returns entries in a single locale. Resolvable linked entries will be inlined while unresolvable links will be kept as link objects. [Read more on link resolution](ADVANCED.md#link-resolution) |
-| `withAllLocales`           | Returns entries in all locales.                                                                                                                                                                  |
-| `withoutLinkResolution`    | All linked entries will be rendered as link objects. [Read more on link resolution](ADVANCED.md#link-resolution)                                                                                 |
-| `withoutUnresolvableLinks` | If linked entries are not resolvable, the corresponding link objects are removed from the response.                                                                                              |
+| Chain                       | Modifier                                                                                                                                                                                         |
+| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| _none (default)_            | Returns entries in a single locale. Resolvable linked entries will be inlined while unresolvable links will be kept as link objects. [Read more on link resolution](ADVANCED.md#link-resolution) |
+| `withAllLocales`            | Returns entries in all locales.                                                                                                                                                                  |
+| `withoutLinkResolution`     | All linked entries will be rendered as link objects. [Read more on link resolution](ADVANCED.md#link-resolution)                                                                                 |
+| `withoutUnresolvableLinks`  | If linked entries are not resolvable, the corresponding link objects are removed from the response.                                                                                              |
+| `withLocaleBasedPublishing` | Fetched entries & assets will be returned with only content from published locales.                                                                                                              |
 
 ##### Example
 

lib/create-contentful-api.ts

@@ -50,6 +50,7 @@
 import { getTimelinePreviewParams } from './utils/timeline-preview-helpers.js'
 import { normalizeCursorPaginationParameters } from './utils/normalize-cursor-pagination-parameters.js'
 import { normalizeCursorPaginationResponse } from './utils/normalize-cursor-pagination-response.js'
+import type { AxiosRequestConfig } from 'axios'
 
 const ASSET_KEY_MAX_LIFETIME = 48 * 60 * 60
 
@@ -60,7 +61,7 @@
 
 class NotFoundError extends Error {
   public readonly sys: { id: string; type: string }
   public readonly details: { environment: string; id: string; type: string; space: any }
 
   constructor(id: string, environment: string, space: string) {
     super('The resource could not be found.')
@@ -90,11 +91,11 @@
   interface GetConfig {
     context: Context
     path: string
     config?: any
   }
 
   interface PostConfig extends GetConfig {
     data?: any
   }
 
   const getBaseUrl = (context: Context) => {
@@ -112,7 +113,7 @@
     return baseUrl
   }
 
   function maybeEnableSourceMaps(query: Record<string, any> = {}): Record<string, any> {
     const params = http.httpClientParams as CreateClientParams
     const includeContentSourceMaps =
       params?.includeContentSourceMaps ?? params?.alphaFeatures?.includeContentSourceMaps
@@ -142,7 +143,7 @@
     return enabled ? `timeline/${path}` : path
   }
 
   function maybeAddTimelinePreviewConfigToQuery(query: Record<string, any>) {
     const { enabled, timelinePreview } = getTimelinePreviewParams(
       http.httpClientParams as CreateClientParams,
     )
@@ -158,7 +159,7 @@
     return query
   }
 
   function maybeEncodeCPAResponse(data: any, config: Record<string, any>): any {
     const includeContentSourceMaps = config?.params?.includeContentSourceMaps as boolean
 
     if (includeContentSourceMaps) {
@@ -230,6 +231,7 @@
       withAllLocales: false,
       withoutLinkResolution: false,
       withoutUnresolvableLinks: false,
+      withLocaleBasedPublishing: false,
     },
   ) {
     const { withAllLocales } = options
@@ -280,6 +282,7 @@
       withAllLocales: false,
       withoutLinkResolution: false,
       withoutUnresolvableLinks: false,
+      withLocaleBasedPublishing: false,
     },
   ) {
     const { withAllLocales } = options
@@ -318,14 +321,22 @@
   ): Promise<
     CollectionForQuery<Entry<EntrySkeleton, ModifiersFromOptions<Options>, Locales>, Query>
   > {
-    const { withoutLinkResolution, withoutUnresolvableLinks } = options
+    const { withoutLinkResolution, withoutUnresolvableLinks, withLocaleBasedPublishing } = options
     try {
+      const baseConfig = createRequestConfig({
+        query: prepareQuery(query),
+      })
+      const config: AxiosRequestConfig = baseConfig
+      if (withLocaleBasedPublishing) {
+        config.headers = {
+          ...config.headers,
+          'X-Contentful-Locale-Based-Publishing': true,
+        }
+      }
       const entries = await get({
         context: 'environment',
         path: maybeEnableTimelinePreview('entries'),
-        config: createRequestConfig({
-          query: prepareQuery(query),
-        }),
+        config,
       })
 
       return resolveCircular(entries, {
@@ -358,6 +369,7 @@
       withAllLocales: false,
       withoutLinkResolution: false,
       withoutUnresolvableLinks: false,
+      withLocaleBasedPublishing: false,
     },
   ) {
     const { withAllLocales } = options
@@ -367,18 +379,33 @@
 
     const localeSpecificQuery = withAllLocales ? { ...query, locale: '*' } : query
 
-    return internalGetAssets<any, Extract<ChainOptions, typeof options>, Query>(localeSpecificQuery)
+    return internalGetAssets<any, Extract<ChainOptions, typeof options>, Query>(
+      localeSpecificQuery,
+      options,
+    )
   }
 
   async function internalGetAsset<Locales extends LocaleCode, Options extends ChainOptions>(
     id: string,
     query: Record<string, any>,
+    options: Options,
   ): Promise<Asset<ModifiersFromOptions<Options>, Locales>> {
+    const { withLocaleBasedPublishing } = options
     try {
+      const baseConfig = createRequestConfig({
+        query: prepareQuery(query),
+      })
+      const config: AxiosRequestConfig = baseConfig
+      if (withLocaleBasedPublishing) {
+        config.headers = {
+          ...config.headers,
+          'X-Contentful-Locale-Based-Publishing': true,
+        }
+      }
       return get({
         context: 'environment',
         path: maybeEnableTimelinePreview(`assets/${id}`),
-        config: createRequestConfig({ query: prepareQuery(query) }),
+        config,
       })
     } catch (error) {
       errorHandler(error)
@@ -392,6 +419,7 @@
       withAllLocales: false,
       withoutLinkResolution: false,
       withoutUnresolvableLinks: false,
+      withLocaleBasedPublishing: false,
     },
   ) {
     const { withAllLocales } = options
@@ -401,7 +429,11 @@
 
     const localeSpecificQuery = withAllLocales ? { ...query, locale: '*' } : query
 
-    return internalGetAsset<any, Extract<ChainOptions, typeof options>>(id, localeSpecificQuery)
+    return internalGetAsset<any, Extract<ChainOptions, typeof options>>(
+      id,
+      localeSpecificQuery,
+      options,
+    )
   }
 
   async function internalGetAssets<
@@ -410,14 +442,24 @@
     Query extends Record<string, any>,
   >(
     query: Query,
+    options: Options,
   ): Promise<CollectionForQuery<Asset<ModifiersFromOptions<Options>, Locales>, Query>> {
+    const { withLocaleBasedPublishing } = options
     try {
+      const baseConfig = createRequestConfig({
+        query: prepareQuery(query),
+      })
+      const config: AxiosRequestConfig = baseConfig
+      if (withLocaleBasedPublishing) {
+        config.headers = {
+          ...config.headers,
+          'X-Contentful-Locale-Based-Publishing': true,
+        }
+      }
       return get({
         context: 'environment',
         path: maybeEnableTimelinePreview('assets'),
-        config: createRequestConfig({
-          query: prepareQuery(query),
-        }),
+        config,
       })
     } catch (error) {
       errorHandler(error)
@@ -481,6 +523,7 @@
       withAllLocales: false,
       withoutLinkResolution: false,
       withoutUnresolvableLinks: false,
+      withLocaleBasedPublishing: false,
     },
   ) {
     validateResolveLinksParam(query)
@@ -508,6 +551,7 @@
       withAllLocales: false,
       withoutLinkResolution: false,
       withoutUnresolvableLinks: false,
+      withLocaleBasedPublishing: false,
     },
   ) {
     return internalParseEntries<EntrySkeleton, any, Extract<ChainOptions, typeof options>>(

lib/make-client.ts

@@ -31,6 +31,9 @@ function create<OptionsType extends ChainOptions>(
   Object.defineProperty(response, 'withoutUnresolvableLinks', {
     get: () => makeInnerClient({ ...options, withoutUnresolvableLinks: true }),
   })
+  Object.defineProperty(response, 'withLocaleBasedPublishing', {
+    get: () => makeInnerClient({ ...options, withLocaleBasedPublishing: true }),
+  })
   return Object.create(response) as ContentfulClientApi<ModifiersFromOptions<OptionsType>>
 }
 
@@ -50,6 +53,7 @@ export const makeClient = ({
       withoutLinkResolution: false,
       withAllLocales: false,
       withoutUnresolvableLinks: false,
+      withLocaleBasedPublishing: false,
     },
   )
 
@@ -60,20 +64,31 @@ export const makeClient = ({
         withAllLocales: true,
         withoutLinkResolution: false,
         withoutUnresolvableLinks: false,
+        withLocaleBasedPublishing: false,
       })
     },
     get withoutLinkResolution() {
       return makeInnerClient<ChainOption<'WITHOUT_LINK_RESOLUTION'>>({
         withAllLocales: false,
         withoutLinkResolution: true,
         withoutUnresolvableLinks: false,
+        withLocaleBasedPublishing: false,
       })
     },
     get withoutUnresolvableLinks() {
       return makeInnerClient<ChainOption<'WITHOUT_UNRESOLVABLE_LINKS'>>({
         withAllLocales: false,
         withoutLinkResolution: false,
         withoutUnresolvableLinks: true,
+        withLocaleBasedPublishing: false,
+      })
+    },
+    get withLocaleBasedPublishing() {
+      return makeInnerClient<ChainOption<'WITH_LOCALE_BASED_PUBLISHING'>>({
+        withAllLocales: false,
+        withoutLinkResolution: false,
+        withoutUnresolvableLinks: false,
+        withLocaleBasedPublishing: true,
       })
     },
   }

lib/types/client.ts

@@ -36,6 +36,7 @@ export type ChainModifiers =
   | 'WITH_ALL_LOCALES'
   | 'WITHOUT_LINK_RESOLUTION'
   | 'WITHOUT_UNRESOLVABLE_LINKS'
+  | 'WITH_LOCALE_BASED_PUBLISHING'
   | undefined
 
 /**
@@ -581,6 +582,10 @@ export interface ContentfulClientApi<Modifiers extends ChainModifiers> {
       ? never
       : ContentfulClientApi<AddChainModifier<Modifiers, 'WITHOUT_UNRESOLVABLE_LINKS'>>
 
+  withLocaleBasedPublishing: 'WITH_LOCALE_BASED_PUBLISHING' extends Modifiers
+    ? never
+    : ContentfulClientApi<AddChainModifier<Modifiers, 'WITH_LOCALE_BASED_PUBLISHING'>>
+
   /**
    * The current Contentful.js version
    */

lib/utils/client-helpers.ts

@@ -16,6 +16,11 @@ export type ChainOption<Modifiers extends ChainModifiers = ChainModifiers> = {
     : 'WITHOUT_UNRESOLVABLE_LINKS' extends Modifiers
       ? true
       : false
+  withLocaleBasedPublishing: ChainModifiers extends Modifiers
+    ? boolean
+    : 'WITH_LOCALE_BASED_PUBLISHING' extends Modifiers
+      ? true
+      : false
 }
 
 export type DefaultChainOption = ChainOption<undefined>

test/types/chain-options.test-d.ts

@@ -8,40 +8,47 @@ expectAssignable<ChainOptions>({
   withoutLinkResolution: true as boolean,
   withAllLocales: true as boolean,
   withoutUnresolvableLinks: true as boolean,
+  withLocaleBasedPublishing: true as boolean,
 })
 
 expectType<ChainOption<undefined>>({
   withoutLinkResolution: false,
   withAllLocales: false,
   withoutUnresolvableLinks: false,
+  withLocaleBasedPublishing: false,
 })
 
 expectType<ChainOption<'WITHOUT_UNRESOLVABLE_LINKS'>>({
   withoutLinkResolution: false,
   withAllLocales: false,
+  withLocaleBasedPublishing: false,
   withoutUnresolvableLinks: true,
 })
 
 expectType<ChainOption<'WITHOUT_LINK_RESOLUTION'>>({
   withoutLinkResolution: true,
   withAllLocales: false,
+  withLocaleBasedPublishing: false,
   withoutUnresolvableLinks: false,
 })
 
 expectType<ChainOption<'WITH_ALL_LOCALES'>>({
   withoutLinkResolution: false,
   withAllLocales: true,
+  withLocaleBasedPublishing: false,
   withoutUnresolvableLinks: false,
 })
 
 expectType<ChainOption<'WITH_ALL_LOCALES' | 'WITHOUT_UNRESOLVABLE_LINKS'>>({
   withoutLinkResolution: false,
+  withLocaleBasedPublishing: false,
   withAllLocales: true,
   withoutUnresolvableLinks: true,
 })
 
 expectNotType<ChainOption<'WITH_ALL_LOCALES' | 'WITHOUT_UNRESOLVABLE_LINKS'>>({
   withoutLinkResolution: false,
+  withLocaleBasedPublishing: false,
   withAllLocales: true,
   withoutUnresolvableLinks: false,
 })
@@ -50,4 +57,33 @@ expectType<ChainOption<'WITH_ALL_LOCALES' | 'WITHOUT_LINK_RESOLUTION'>>({
   withoutLinkResolution: true,
   withAllLocales: true,
   withoutUnresolvableLinks: false,
+  withLocaleBasedPublishing: false,
+})
+
+expectType<ChainOption<'WITH_LOCALE_BASED_PUBLISHING'>>({
+  withoutLinkResolution: false,
+  withAllLocales: false,
+  withoutUnresolvableLinks: false,
+  withLocaleBasedPublishing: true,
+})
+
+expectType<ChainOption<'WITH_LOCALE_BASED_PUBLISHING' | 'WITH_ALL_LOCALES'>>({
+  withoutLinkResolution: false,
+  withAllLocales: true,
+  withoutUnresolvableLinks: false,
+  withLocaleBasedPublishing: true,
+})
+
+expectType<ChainOption<'WITH_LOCALE_BASED_PUBLISHING' | 'WITHOUT_LINK_RESOLUTION'>>({
+  withoutLinkResolution: true,
+  withAllLocales: false,
+  withoutUnresolvableLinks: false,
+  withLocaleBasedPublishing: true,
+})
+
+expectType<ChainOption<'WITH_LOCALE_BASED_PUBLISHING' | 'WITHOUT_UNRESOLVABLE_LINKS'>>({
+  withoutLinkResolution: false,
+  withAllLocales: false,
+  withoutUnresolvableLinks: true,
+  withLocaleBasedPublishing: true,
 })

test/types/client/createClient.test-d.ts

@@ -55,3 +55,29 @@ expectType<ContentfulClientApi<'WITH_ALL_LOCALES' | 'WITHOUT_LINK_RESOLUTION'>>(
 expectType<ContentfulClientApi<'WITH_ALL_LOCALES' | 'WITHOUT_UNRESOLVABLE_LINKS'>>(
   createClient(CLIENT_OPTIONS).withAllLocales.withoutUnresolvableLinks,
 )
+expectType<ContentfulClientApi<'WITH_LOCALE_BASED_PUBLISHING'>>(
+  createClient(CLIENT_OPTIONS).withLocaleBasedPublishing,
+)
+expectType<never>(createClient(CLIENT_OPTIONS).withLocaleBasedPublishing.withLocaleBasedPublishing)
+
+expectType<ContentfulClientApi<'WITH_LOCALE_BASED_PUBLISHING' | 'WITH_ALL_LOCALES'>>(
+  createClient(CLIENT_OPTIONS).withLocaleBasedPublishing.withAllLocales,
+)
+
+expectType<ContentfulClientApi<'WITH_LOCALE_BASED_PUBLISHING' | 'WITHOUT_LINK_RESOLUTION'>>(
+  createClient(CLIENT_OPTIONS).withLocaleBasedPublishing.withoutLinkResolution,
+)
+
+expectType<ContentfulClientApi<'WITH_LOCALE_BASED_PUBLISHING' | 'WITHOUT_UNRESOLVABLE_LINKS'>>(
+  createClient(CLIENT_OPTIONS).withLocaleBasedPublishing.withoutUnresolvableLinks,
+)
+
+expectType<
+  ContentfulClientApi<
+    'WITH_LOCALE_BASED_PUBLISHING' | 'WITH_ALL_LOCALES' | 'WITHOUT_LINK_RESOLUTION'
+  >
+>(createClient(CLIENT_OPTIONS).withLocaleBasedPublishing.withAllLocales.withoutLinkResolution)
+
+expectType<ContentfulClientApi<'WITH_ALL_LOCALES' | 'WITH_LOCALE_BASED_PUBLISHING'>>(
+  createClient(CLIENT_OPTIONS).withAllLocales.withLocaleBasedPublishing,
+)