Added publish and unpublish methods in entry variants

Author: sunil-lakshman

lib/entity.js

@@ -13,7 +13,7 @@ import ContentstackCollection from './contentstackCollection'
  * await publishFn.call(entryInstance, { publishDetails: {...}, locale: 'en-us' })
  */
 export const publish = (http, type) => {
-  return async function ({ publishDetails, locale = null, version = null, scheduledAt = null }) {
+  return async function ({ publishDetails, locale = null, version = null, scheduledAt = null, headers: extraHeaders = {}, params = {} }) {
     const url = this.urlPath + '/publish'
     const headers = {
       headers: {
@@ -22,7 +22,10 @@ export const publish = (http, type) => {
     } || {}
     const httpBody = {}
     httpBody[type] = cloneDeep(publishDetails)
-    return publishUnpublish(http, url, httpBody, headers, locale, version, scheduledAt)
+    return publishUnpublish(http, url, httpBody, headers, locale, version, scheduledAt, {
+      headers: extraHeaders,
+      params
+    })
   }
 }
 
@@ -36,7 +39,7 @@ export const publish = (http, type) => {
  * await unpublishFn.call(entryInstance, { publishDetails: {...}, locale: 'en-us' })
  */
 export const unpublish = (http, type) => {
-  return async function ({ publishDetails, locale = null, version = null, scheduledAt = null }) {
+  return async function ({ publishDetails, locale = null, version = null, scheduledAt = null, headers: extraHeaders = {}, params = {} }) {
     const url = this.urlPath + '/unpublish'
     const headers = {
       headers: {
@@ -45,7 +48,10 @@ export const unpublish = (http, type) => {
     } || {}
     const httpBody = {}
     httpBody[type] = cloneDeep(publishDetails)
-    return publishUnpublish(http, url, httpBody, headers, locale, version, scheduledAt)
+    return publishUnpublish(http, url, httpBody, headers, locale, version, scheduledAt, {
+      headers: extraHeaders,
+      params
+    })
   }
 }
 
@@ -58,11 +64,12 @@ export const unpublish = (http, type) => {
  * @param {string|null} locale - Locale code.
  * @param {number|null} version - Version number.
  * @param {string|null} scheduledAt - Scheduled date/time in ISO format.
+ * @param {Object} [configExtras={}] - Optional `{ headers, params }` merged into the axios request (stack headers stay in `headers.headers`).
  * @returns {Promise<Object>} Promise that resolves to response data.
  * @async
  * @private
  */
-export const publishUnpublish = async (http, url, httpBody, headers, locale = null, version = null, scheduledAt = null) => {
+export const publishUnpublish = async (http, url, httpBody, headers, locale = null, version = null, scheduledAt = null, configExtras = {}) => {
   if (locale !== null) {
     httpBody.locale = locale
   }
@@ -72,8 +79,18 @@ export const publishUnpublish = async (http, url, httpBody, headers, locale = nu
   if (scheduledAt !== null) {
     httpBody.scheduled_at = scheduledAt
   }
+  const requestConfig = {
+    headers: {
+      ...cloneDeep(headers?.headers || {}),
+      ...cloneDeep(configExtras?.headers || {})
+    },
+    params: {
+      ...cloneDeep(headers?.params || {}),
+      ...cloneDeep(configExtras?.params || {})
+    }
+  }
   try {
-    const response = await http.post(url, httpBody, headers)
+    const response = await http.post(url, httpBody, requestConfig)
     if (response.data) {
       const data = response.data || {}
       if (http?.httpClientParams?.headers?.api_version) {

lib/stack/contentType/entry/variants/index.js

@@ -2,7 +2,8 @@ import cloneDeep from 'lodash/cloneDeep'
 import {
   deleteEntity,
   fetch,
-  query
+  query,
+  publishUnpublish
 }
   from '../../../../entity'
 import error from '../../../../core/contentstackError'
@@ -26,6 +27,7 @@ export function Variants (http, data) {
   }
   if (variantPathSegment) {
     this.urlPath += `/${variantPathSegment}`
+    const entryBaseUrlPath = `/content_types/${this.content_type_uid}/entries/${this.entry_uid}`
     /**
          * @description The Update a variant call updates an existing variant for the selected content type.
          * @memberof Variants
@@ -131,6 +133,88 @@ export function Variants (http, data) {
         return error(err)
       }
     }
+
+    /**
+         * @description Publishes via the entry publish endpoint (POST .../entries/{entry_uid}/publish). Pass `publishDetails` as the object nested under `entry` (environments, locales, variants, variant_rules, etc.). Optional `headers` and `params` are merged into the HTTP request.
+         * @memberof Variants
+         * @func publish
+         * @param {Object} options
+         * @param {Object} options.publishDetails - Payload for the `entry` property (e.g. environments, locales, variants, variant_rules).
+         * @param {String|null} [options.locale] - Top-level `locale` on the request body.
+         * @param {Number|null} [options.version] - Top-level `version` on the request body.
+         * @param {String|null} [options.scheduledAt] - Top-level `scheduled_at` (ISO) on the request body.
+         * @param {Object} [options.headers={}] - Extra request headers merged with stack headers.
+         * @param {Object} [options.params={}] - Query string parameters for the request.
+         * @returns {Promise<Object>} Response data (e.g. notice, job_id).
+         * @example
+         * import * as contentstack from '@contentstack/management'
+         * const client = contentstack.client()
+         * await client.stack({ api_key: 'api_key' }).contentType('ct').entry('entry_uid').variants('variant_uid').publish({
+         *   publishDetails: {
+         *     environments: ['production'],
+         *     locales: ['en-us'],
+         *     variants: [{ uid: 'variant_uid', version: 1 }],
+         *     variant_rules: { publish_latest_base: false, publish_latest_base_conditionally: true }
+         *   },
+         *   locale: 'en-us'
+         * })
+         */
+    this.publish = async ({
+      publishDetails,
+      locale = null,
+      version = null,
+      scheduledAt = null,
+      headers: extraHeaders = {},
+      params = {}
+    }) => {
+      const url = `${entryBaseUrlPath}/publish`
+      const httpBody = {}
+      httpBody.entry = cloneDeep(publishDetails)
+      const baseHeaders = {
+        headers: {
+          ...cloneDeep(this.stackHeaders)
+        }
+      }
+      return publishUnpublish(http, url, httpBody, baseHeaders, locale, version, scheduledAt, {
+        headers: extraHeaders,
+        params
+      })
+    }
+
+    /**
+         * @description Unpublishes via the entry unpublish endpoint (POST .../entries/{entry_uid}/unpublish). Pass `publishDetails` as the object nested under `entry`. Optional `headers` and `params` are merged into the HTTP request.
+         * @memberof Variants
+         * @func unpublish
+         * @param {Object} options
+         * @param {Object} options.publishDetails - Payload for the `entry` property (e.g. environments, locales, variants).
+         * @param {String|null} [options.locale] - Top-level `locale` on the request body.
+         * @param {Number|null} [options.version] - Top-level `version` on the request body.
+         * @param {String|null} [options.scheduledAt] - Top-level `scheduled_at` (ISO) on the request body.
+         * @param {Object} [options.headers={}] - Extra request headers merged with stack headers.
+         * @param {Object} [options.params={}] - Query string parameters for the request.
+         * @returns {Promise<Object>} Response data (e.g. notice, job_id).
+         */
+    this.unpublish = async ({
+      publishDetails,
+      locale = null,
+      version = null,
+      scheduledAt = null,
+      headers: extraHeaders = {},
+      params = {}
+    }) => {
+      const url = `${entryBaseUrlPath}/unpublish`
+      const httpBody = {}
+      httpBody.entry = cloneDeep(publishDetails)
+      const baseHeaders = {
+        headers: {
+          ...cloneDeep(this.stackHeaders)
+        }
+      }
+      return publishUnpublish(http, url, httpBody, baseHeaders, locale, version, scheduledAt, {
+        headers: extraHeaders,
+        params
+      })
+    }
   } else {
     /**
          * @description The Query on Variants will allow you to fetch details of all or specific Variants.

test/sanity-check/api/entryVariants-test.js

@@ -452,6 +452,46 @@ describe('Entry Variants API Tests', () => {
       }
     })
 
+    it('should publish entry variant via variants(uid).publish()', async function () {
+      this.timeout(15000)
+
+      if (!contentTypeUid || !entryUid || !variantUid) {
+        this.skip()
+      }
+
+      const publishDetails = {
+        environments: [environmentName],
+        locales: ['en-us'],
+        variants: [{
+          uid: variantUid,
+          version: 1
+        }],
+        variant_rules: {
+          publish_latest_base: false,
+          publish_latest_base_conditionally: true
+        }
+      }
+
+      try {
+        const response = await stack
+          .contentType(contentTypeUid)
+          .entry(entryUid)
+          .variants(variantUid)
+          .publish({
+            publishDetails,
+            locale: 'en-us'
+          })
+
+        expect(response.notice).to.not.equal(undefined)
+      } catch (error) {
+        if (error.status === 403 || error.status === 422) {
+          this.skip()
+        } else {
+          console.log('variants().publish warning:', error.message)
+        }
+      }
+    })
+
     it('should publish entry variant with api_version', async function () {
       this.timeout(15000)
 
@@ -521,6 +561,42 @@ describe('Entry Variants API Tests', () => {
         }
       }
     })
+
+    it('should unpublish entry variant via variants(uid).unpublish()', async function () {
+      this.timeout(15000)
+
+      if (!contentTypeUid || !entryUid || !variantUid) {
+        this.skip()
+      }
+
+      const unpublishDetails = {
+        environments: [environmentName],
+        locales: ['en-us'],
+        variants: [{
+          uid: variantUid,
+          version: 1
+        }]
+      }
+
+      try {
+        const response = await stack
+          .contentType(contentTypeUid)
+          .entry(entryUid)
+          .variants(variantUid)
+          .unpublish({
+            publishDetails: unpublishDetails,
+            locale: 'en-us'
+          })
+
+        expect(response.notice).to.not.equal(undefined)
+      } catch (error) {
+        if (error.status === 403 || error.status === 422) {
+          this.skip()
+        } else {
+          console.log('variants().unpublish warning:', error.message)
+        }
+      }
+    })
   })
 
   describe('Entry Variant Deletion', () => {

test/unit/variants-entry-test.js

@@ -239,6 +239,76 @@ describe('Contentstack Variants entry test', () => {
       .catch(done)
   })
 
+  it('Variants entry publish posts to entry publish URL with optional headers and params', (done) => {
+    const mock = new MockAdapter(Axios)
+    mock.onPost('/content_types/content_type_uid/entries/entry_uid/publish').reply((config) => {
+      const body = typeof config.data === 'string' ? JSON.parse(config.data) : config.data
+      expect(body.entry).to.be.an('object')
+      expect(body.entry.variants).to.be.an('array')
+      expect(body.entry.variants[0].uid).to.equal('variant_uid')
+      expect(body.locale).to.equal('en-us')
+      expect(config.headers['x-custom']).to.equal('1')
+      expect(config.params.t).to.equal('1')
+      return [200, { notice: 'Entry sent for publishing.', job_id: 'jid' }]
+    })
+    makeEntryVariants({
+      content_type_uid: 'content_type_uid',
+      entry_uid: 'entry_uid',
+      variants_uid: 'variant_uid',
+      stackHeaders: { api_key: 'k' }
+    })
+      .publish({
+        publishDetails: {
+          environments: ['development'],
+          locales: ['en-us'],
+          variants: [{ uid: 'variant_uid', version: 1 }],
+          variant_rules: { publish_latest_base_conditionally: true }
+        },
+        locale: 'en-us',
+        headers: { 'x-custom': '1' },
+        params: { t: '1' }
+      })
+      .then((res) => {
+        expect(res.notice).to.include('publish')
+        done()
+      })
+      .catch(done)
+  })
+
+  it('Variants entry unpublish posts to entry unpublish URL with optional headers and params', (done) => {
+    const mock = new MockAdapter(Axios)
+    mock.onPost('/content_types/content_type_uid/entries/entry_uid/unpublish').reply((config) => {
+      const body = typeof config.data === 'string' ? JSON.parse(config.data) : config.data
+      expect(body.entry).to.be.an('object')
+      expect(body.entry.variants).to.be.an('array')
+      expect(body.locale).to.equal('en-us')
+      expect(config.headers['x-unpub']).to.equal('y')
+      expect(config.params.q).to.equal('2')
+      return [200, { notice: 'Entry sent for unpublishing.' }]
+    })
+    makeEntryVariants({
+      content_type_uid: 'content_type_uid',
+      entry_uid: 'entry_uid',
+      variants_uid: 'variant_uid',
+      stackHeaders: { api_key: 'k' }
+    })
+      .unpublish({
+        publishDetails: {
+          environments: ['development'],
+          locales: ['en-us'],
+          variants: [{ uid: 'variant_uid', version: 1 }]
+        },
+        locale: 'en-us',
+        headers: { 'x-unpub': 'y' },
+        params: { q: '2' }
+      })
+      .then((res) => {
+        expect(res.notice).to.include('unpublish')
+        done()
+      })
+      .catch(done)
+  })
+
   it('Entry variants fetch sends optional branch header', (done) => {
     const mock = new MockAdapter(Axios)
     mock

types/stack/contentType/variants.d.ts

@@ -2,7 +2,21 @@ import { Response } from "../../contentstackCollection";
 import { AnyProperty, SystemFields } from "../../utility/fields";
 import { Queryable, SystemFunction } from "../../utility/operations";
 
+/** Options for {@link Variant.publish} and {@link Variant.unpublish} (entry publish/unpublish APIs with variant payload). */
+export interface VariantPublishUnpublishOptions {
+    publishDetails: AnyProperty
+    locale?: string | null
+    version?: number | null
+    scheduledAt?: string | null
+    /** Merged with stack headers on the request */
+    headers?: Record<string, string>
+    /** Query string parameters */
+    params?: Record<string, unknown>
+}
+
 export interface Variant extends SystemFields, SystemFunction<Variant> {
+    publish(options: VariantPublishUnpublishOptions): Promise<Response>
+    unpublish(options: VariantPublishUnpublishOptions): Promise<Response>
 }
 export interface Variants extends Queryable<Variants, {Variants: VariantData}> {
 }

types/utility/publish.d.ts

@@ -11,6 +11,10 @@ export interface PublishConfig {
     locale?: string
     version?: number
     scheduledAt?: string
+    /** Extra HTTP headers merged with stack headers (publish / unpublish). */
+    headers?: Record<string, string>
+    /** Query string parameters (publish / unpublish). */
+    params?: Record<string, unknown>
 }
 
 export interface Publishable {