feat: add support for locale based publishing [TOL-2810] (#1465)

* chore: bump contentful-management []

* feat: support locale based publishing [TOL-2810]

* chore: adjust linting rule as it breaks without context

* chore: handle floating promise []

* chore: add missing property to validator []

Author: chrishelgert

README.md

@@ -288,9 +288,10 @@ The transform function is expected to return an object with the desired target f
 - **`transformEntryForLocale : function (fields, locale, {id}): object`** _(required)_ – Transformation function to be applied.
   - `fields` is an object containing each of the `from` fields. Each field will contain their current localized values (i.e. `fields == {myField: {'en-US': 'my field value'}}`)
   - `locale` one of the locales in the space being transformed
-  - `id` id of the current entry in scope  
+  - `id` id of the current entry in scope
     The return value must be an object with the same keys as specified in `to`. Their values will be written to the respective entry fields for the current locale (i.e. `{nameField: 'myNewValue'}`). If it returns `undefined`, this the values for this locale on the entry will be left untouched.
 - **`shouldPublish : bool | 'preserve'`** _(optional)_ – Flag that specifies publishing of target entries, `preserve` will keep current states of the source entries (default `'preserve'`)
+- **`useLocaleBasedPublishing: bool`** _(optional)_ - Flag to use locale based publishing for the target entries. (default: `false`)
 
 ##### `transformEntries` Example
 

examples/16-typescript-migration.ts

@@ -1,12 +1,10 @@
 import Migration from 'contentful-migration'
 
-export = function (migration: Migration) {
+export default function typeScriptMigration(migration: Migration) {
   const dog = migration.createContentType('dog', {
     name: 'Dog'
   })
 
   const name = dog.createField('name')
-  name.name('Name')
-    .type('Symbol')
-    .required(true)
-}
+  name.name('Name').type('Symbol').required(true)
+}

examples/55-transform-content-with-locale-based-publishing.js

@@ -0,0 +1,18 @@
+// In this example, we fill the "byLine" field with the combined values of 2 other fields.
+// It will skip the "de-DE" locale and then automatically publish the entry with locale based publishing.
+module.exports = function (migration) {
+  migration.transformEntries({
+    contentType: 'newsArticle',
+    from: ['author', 'authorCity'],
+    to: ['byline'],
+    shouldPublish: 'preserve',
+    useLocaleBasedPublishing: true,
+    transformEntryForLocale: function (fromFields, currentLocale) {
+      if (currentLocale === 'de-DE') {
+        return
+      }
+      const newByline = `${fromFields.author[currentLocale]} ${fromFields.authorCity[currentLocale]}`
+      return { byline: newByline }
+    }
+  })
+}

index.d.ts

@@ -492,6 +492,8 @@ export interface ITransformEntriesConfig {
   ) => any
   /** (optional) – If true, the transformed entries will be published. If false, they will remain in draft state. When the value is set to "preserve" items will be published only if the original entry was published as well (default true) */
   shouldPublish?: boolean | 'preserve'
+  /** (optional) – If true, the transformed entries will be published with locale based publishing. If false, they will remain in draft state. When the value is set to "preserve" items will be published only if the original entry was published in this locale as well (default false) */
+  useLocaleBasedPublishing?: boolean
 }
 
 export interface ITransformEntriesToTypeConfig {

package-lock.json

@@ -56,7 +56,7 @@
     "callsites": "^3.1.0",
     "cardinal": "^2.1.1",
     "chalk": "^4.0.0",
-    "contentful-management": "^11.40.3",
+    "contentful-management": "^11.47.1",
     "didyoumean2": "^5.0.0",
     "https-proxy-agent": "^5.0.0",
     "inquirer": "^8.1.2",

package.json

@@ -20,6 +20,7 @@ class EntryDeriveAction extends APIAction {
   ) => Promise<any>
   private identityKey: (fromFields: any) => Promise<string>
   private shouldPublish: boolean | 'preserve'
+  private useLocaleBasedPublishing: boolean
 
   constructor(contentTypeId: string, entryDerivation: EntryDerive) {
     super()
@@ -32,6 +33,17 @@ class EntryDeriveAction extends APIAction {
     this.shouldPublish = isDefined(entryDerivation.shouldPublish)
       ? entryDerivation.shouldPublish
       : true
+    this.useLocaleBasedPublishing = isDefined(entryDerivation.useLocaleBasedPublishing)
+      ? entryDerivation.useLocaleBasedPublishing
+      : false
+  }
+
+  private async publishEntry(api: OfflineAPI, entry: Entry, locales: string[]) {
+    if (this.useLocaleBasedPublishing) {
+      await api.localeBasedPublishEntry(entry.id, locales)
+    } else {
+      await api.publishEntry(entry.id)
+    }
   }
 
   async applyTo(api: OfflineAPI) {
@@ -101,8 +113,8 @@ class EntryDeriveAction extends APIAction {
           }
         }
         await api.saveEntry(targetEntry.id)
-        if (shouldPublishLocalChanges(this.shouldPublish, entry)) {
-          await api.publishEntry(targetEntry.id)
+        if (shouldPublishLocalChanges(this.shouldPublish, entry, this.useLocaleBasedPublishing)) {
+          await this.publishEntry(api, targetEntry, locales)
         }
       }
       const field = sourceContentType.fields.getField(this.referenceField)
@@ -118,8 +130,8 @@ class EntryDeriveAction extends APIAction {
       }
 
       await api.saveEntry(entry.id)
-      if (shouldPublishLocalChanges(this.shouldPublish, entry)) {
-        await api.publishEntry(entry.id)
+      if (shouldPublishLocalChanges(this.shouldPublish, entry, this.useLocaleBasedPublishing)) {
+        await this.publishEntry(api, entry, locales)
       }
     }
   }

src/lib/action/entry-derive.ts

@@ -9,19 +9,21 @@ class EntryTransformAction extends APIAction {
   private fromFields: string[]
   private transformEntryForLocale: Function
   private shouldPublish: boolean | 'preserve'
-
+  private useLocaleBasedPublishing: boolean
   constructor(
     contentTypeId: string,
     fromFields: string[],
     transformation: Function,
-    shouldPublish: boolean | 'preserve' = 'preserve'
+    shouldPublish: boolean | 'preserve' = 'preserve',
+    useLocaleBasedPublishing: boolean = false
   ) {
     super()
     this.contentTypeId = contentTypeId
     this.fromFields = fromFields
     // this.toFields = toFields
     this.transformEntryForLocale = transformation
     this.shouldPublish = shouldPublish
+    this.useLocaleBasedPublishing = useLocaleBasedPublishing
   }
 
   async applyTo(api: OfflineAPI) {
@@ -57,8 +59,18 @@ class EntryTransformAction extends APIAction {
       }
       if (changesForThisEntry) {
         await api.saveEntry(entry.id)
-        if (shouldPublishLocalChanges(this.shouldPublish, entry)) {
-          await api.publishEntry(entry.id)
+        if (shouldPublishLocalChanges(this.shouldPublish, entry, this.useLocaleBasedPublishing)) {
+          if (this.useLocaleBasedPublishing) {
+            const localesToPublish =
+              this.shouldPublish === 'preserve'
+                ? Object.entries(entry.fieldStatus['*'])
+                    .filter(([, status]) => status === 'published')
+                    .map(([locale]) => locale)
+                : locales
+            await api.localeBasedPublishEntry(entry.id, localesToPublish)
+          } else {
+            await api.publishEntry(entry.id)
+          }
         }
       }
     }

src/lib/action/entry-transform.ts

@@ -2,6 +2,7 @@ import { cloneDeep } from 'lodash'
 import APIEntry from '../interfaces/api-entry'
 import APITagLink from '../interfaces/api-tag-link'
 import isDefined from '../utils/is-defined'
+import type { EntityMetaSysProps } from 'contentful-management'
 
 class Entry {
   private _id: string
@@ -10,6 +11,7 @@ class Entry {
   private _fields: object
   private _publishedVersion?: number
   private _tags?: APITagLink[]
+  private _fieldStatus?: EntityMetaSysProps['fieldStatus']
 
   constructor(entry: APIEntry) {
     this._id = entry.sys.id
@@ -18,6 +20,7 @@ class Entry {
     this._contentTypeId = entry.sys.contentType.sys.id
     this._publishedVersion = entry.sys.publishedVersion
     this._tags = entry.metadata?.tags
+    this._fieldStatus = entry.sys.fieldStatus
   }
 
   get id() {
@@ -86,6 +89,14 @@ class Entry {
     this._tags = tags
   }
 
+  get fieldStatus() {
+    return this._fieldStatus
+  }
+
+  set fieldStatus(fieldStatus: EntityMetaSysProps['fieldStatus']) {
+    this._fieldStatus = fieldStatus
+  }
+
   toApiEntry(): APIEntry {
     const sys = {
       id: this.id,
@@ -97,7 +108,8 @@ class Entry {
           linkType: 'ContentType',
           id: this.contentTypeId
         }
-      }
+      },
+      fieldStatus: cloneDeep(this.fieldStatus)
     }
 
     let payload: APIEntry

src/lib/entities/entry.ts

@@ -23,7 +23,8 @@ class ContentTransformIntentValidator extends SchemaValidator {
       from: Joi.array().items(Joi.string()).required(),
       to: Joi.array().items(Joi.string()).required(),
       transformEntryForLocale: Joi.func().required(),
-      shouldPublish: Joi.alternatives().try(Joi.boolean(), Joi.string().valid('preserve'))
+      shouldPublish: Joi.alternatives().try(Joi.boolean(), Joi.string().valid('preserve')),
+      useLocaleBasedPublishing: Joi.boolean().optional()
     }
   }
 }