feat: add taxonomy validations to content type

Author: Deeds67

CONTRIBUTING.md

@@ -16,12 +16,13 @@ Don't worry if this is your first time with Typescript. The language reads like
 
 In order to run integration tests, you need:
 
-* a source space the tests are run against (`CONTENTFUL_SPACE_ID`) and is called `contentful-migration`
-* a management token for the defined space (`CONTENTFUL_INTEGRATION_TEST_CMA_TOKEN`)
+- a source space the tests are run against (`CONTENTFUL_SPACE_ID`) and is called `contentful-migration`
+- a source organization the tests are run against (`CONTENTFUL_ORGANIZATION_ID`)
+- a management token for the defined space (`CONTENTFUL_INTEGRATION_TEST_CMA_TOKEN`)
 
 ```sh
 CONTENTFUL_SPACE_ID=<spaceId> \
 CONTENTFUL_INTEGRATION_TEST_CMA_TOKEN=CFPAT-xxx \
+CONTENTFUL_ORGANIZATION_ID=<organizationId> \
 npm test
 ```
-

README.md

@@ -764,6 +764,39 @@ Configure the annotations assigned to this content type. See [annotations docume
 
 Remove all assigned annotations from this content type
 
+#### `addTaxonomyValidation(id, linkType[, opts])`
+
+Adds a taxonomy validation to this content type. This method is additive - you can call it multiple times to add validations one by one.
+
+**`id : string`** – The ID of the taxonomy concept or concept scheme.
+
+**`linkType : string`** – The type of taxonomy link. Must be either `TaxonomyConcept` or `TaxonomyConceptScheme`.
+
+**`opts : Object`** – Validation options, with the following properties:
+
+- **`required : boolean`** – Whether this taxonomy validation is required. Defaults to `false`.
+
+#### `clearTaxonomyValidations()`
+
+Remove all taxonomy validations from this content type.
+
+#### `setTaxonomyValidations(validations)`
+
+Replace all existing taxonomy validations with a new set of validations.
+
+**`validations : Array`** – Array of taxonomy validation objects. Each validation object should have the following structure:
+
+```javascript
+{
+  sys: {
+    type: 'Link',
+    id: 'taxonomy-id',
+    linkType: 'TaxonomyConcept' // or 'TaxonomyConceptScheme'
+  },
+  required: true // or false
+}
+```
+
 ### Field
 
 The field object has the same methods as the properties listed in the [`ContentType.createField`](#createfieldid--string-opts--object--field) method.
@@ -881,7 +914,7 @@ You can use Typescript to write your migration files using `ts-node`! First `npm
 then run your migration with ts-node:
 
 ```bash
-node_modules/.bin/ts-node node_modules/.bin/contentful-migration -s $CONTENTFUL_SPACE_ID -a $CONTENTFUL_MANAGEMENT_TOKEN my_migration.ts
+node_modules/.bin/ts-node node_modules/.bin/contentful-migration -s $CONTENTFUL_SPACE_ID -a $CONTENTFUL_MANAGEMENT_TOKEN -o $CONTENTFUL_ORGANIZATION_ID my_migration.ts
 ```
 
 An example Typescript migration:

examples/56-set-taxonomy-validations.js

@@ -0,0 +1,35 @@
+// Note: Taxonomy concepts and concept schemes cannot yet be created via migrations.
+// You must first create them via the Contentful web app or CMA API.
+// This example shows how to add existing taxonomy concepts/schemes as validations to a content type.
+
+module.exports = function (migration) {
+  const contentType = migration.createContentType('taxonomy-example').name('Taxonomy Example')
+
+  // Add taxonomy validations one by one
+  contentType
+    .addTaxonomyValidation('existing-concept', 'TaxonomyConcept', { required: true })
+    .addTaxonomyValidation('existing-concept-scheme', 'TaxonomyConceptScheme')
+
+  // Clear all taxonomy validations
+  contentType.clearTaxonomyValidations()
+
+  // Replace all taxonomy validations with a new set
+  contentType.setTaxonomyValidations([
+    {
+      sys: {
+        type: 'Link',
+        id: 'existing-concept',
+        linkType: 'TaxonomyConcept'
+      },
+      required: true
+    },
+    {
+      sys: {
+        type: 'Link',
+        id: 'existing-concept-scheme',
+        linkType: 'TaxonomyConceptScheme'
+      },
+      required: false
+    }
+  ])
+}

index.d.ts

@@ -4,6 +4,7 @@ export type RunMigrationConfig = {
   accessToken?: string
   spaceId?: string
   environmentId?: string
+  organizationId?: string
   proxy?: string
   rawProxy?: boolean
   yes?: boolean
@@ -239,6 +240,24 @@ export interface IEntryEditor {
   settings?: IEditorInterfaceOptions
 }
 
+export interface ITaxonomyConceptValidationLink {
+  sys: {
+    type: 'Link'
+    linkType: 'TaxonomyConcept'
+    id: string
+  }
+  required?: boolean
+}
+
+export interface ITaxonomyConceptSchemeValidationLink {
+  sys: {
+    type: 'Link'
+    linkType: 'TaxonomyConceptScheme'
+    id: string
+  }
+  required?: boolean
+}
+
 export interface ContentType {
   id: string
   instanceId: string
@@ -256,6 +275,23 @@ export interface ContentType {
   /** Removes all annotaions associated with the field */
   clearAnnotations(): ContentType
 
+  /** Set taxonomy validations associated with the content type */
+  setTaxonomyValidations(
+    taxonomyValidations: Array<
+      ITaxonomyConceptValidationLink | ITaxonomyConceptSchemeValidationLink
+    >
+  ): ContentType
+
+  /** Add a single taxonomy validation to the content type */
+  addTaxonomyValidation(
+    id: string,
+    linkType: 'TaxonomyConcept' | 'TaxonomyConceptScheme',
+    options?: { required?: boolean }
+  ): ContentType
+
+  /** Clear all taxonomy validations from the content type */
+  clearTaxonomyValidations(): ContentType
+
   /** Creates a field with provided id. */
   createField(id: string, init?: IFieldOptions): Field
 
@@ -702,6 +738,7 @@ export interface ClientConfig {
   accessToken?: string
   spaceId?: string
   environmentId?: string
+  organizationId?: string
   proxy?: string
   rawProxy?: boolean
   requestBatchSize?: number

package-lock.json

@@ -166,4 +166,4 @@
       "prettier --write"
     ]
   }
-}
+}

package.json

@@ -54,17 +54,27 @@ const makeTerminatingFunction =
     }
   }
 
+export enum UrlBaseType {
+  Space = 'space',
+  Org = 'org'
+}
+
 export const createMakeRequest = (
   client: PlainClientAPI,
-  { spaceId, environmentId, limit = 10, host = 'api.contentful.com' }
+  { spaceId, environmentId, organizationId, limit = 10, host = 'api.contentful.com' }
 ) => {
   const throttle = pThrottle({
     limit,
     interval: 1000,
     strict: false
   })
 
-  const makeBaseUrl = (url: string) => {
+  const makeOrgBaseUrl = (url: string) => {
+    const parts = [`https://${host}`, 'organizations', organizationId, trim(url, '/')]
+    return parts.filter((x) => x !== '').join('/')
+  }
+
+  const makeSpaceBaseUrl = (url: string) => {
     const parts = [
       `https://${host}`,
       'spaces',
@@ -73,13 +83,12 @@ export const createMakeRequest = (
       environmentId,
       trim(url, '/')
     ]
-
     return parts.filter((x) => x !== '').join('/')
   }
 
-  return function makeRequest(requestConfig: RawAxiosRequestConfig) {
-    const { url, ...config } = requestConfig
-    const fullUrl = makeBaseUrl(url)
+  return function makeRequest(requestConfig: RawAxiosRequestConfig & { baseType?: UrlBaseType }) {
+    const { url, baseType, ...config } = requestConfig
+    const fullUrl = baseType === UrlBaseType.Org ? makeOrgBaseUrl(url) : makeSpaceBaseUrl(url)
 
     return throttle(() => client.raw.http(fullUrl, config))()
   }
@@ -121,6 +130,7 @@ const createRun = ({ shouldThrow }) =>
     const makeRequest = createMakeRequest(client, {
       spaceId: clientConfig.spaceId,
       environmentId: clientConfig.environmentId,
+      organizationId: clientConfig.organizationId,
       limit: argv.requestLimit,
       host: clientConfig.host
     })

src/bin/cli.ts

@@ -36,6 +36,7 @@ function getEnvConfig(): ClientConfig {
 function getArgvConfig({
   spaceId,
   environmentId = 'master',
+  organizationId,
   accessToken,
   proxy,
   rawProxy,
@@ -47,6 +48,7 @@ function getArgvConfig({
   const config = {
     spaceId,
     environmentId,
+    organizationId,
     accessToken,
     proxy,
     rawProxy,

src/bin/lib/config.ts

@@ -27,6 +27,10 @@ export default yargs
     describe: 'ID of the environment within the space to run the migration script on',
     default: 'master'
   })
+  .option('organization-id', {
+    alias: 'o',
+    describe: 'ID of the organization (required for organization-scoped operations)'
+  })
   .option('access-token', {
     alias: 'a',
     describe:

src/bin/usage-params.ts

@@ -0,0 +1,87 @@
+import { EntityAction, EntityType } from './action'
+import {
+  ContentType,
+  TaxonomyConceptValidationLink,
+  TaxonomyConceptSchemeValidationLink
+} from '../entities/content-type'
+
+export class ContentTypeSetTaxonomyValidationsAction extends EntityAction {
+  private contentTypeId: string
+  private taxonomyValidations: Array<
+    TaxonomyConceptValidationLink | TaxonomyConceptSchemeValidationLink
+  >
+
+  constructor(
+    contentTypeId: string,
+    taxonomyValidations?: Array<TaxonomyConceptValidationLink | TaxonomyConceptSchemeValidationLink>
+  ) {
+    super()
+    this.contentTypeId = contentTypeId
+    this.taxonomyValidations = taxonomyValidations
+  }
+
+  getEntityId(): string {
+    return this.contentTypeId
+  }
+
+  getEntityType(): EntityType {
+    return EntityType.ContentType
+  }
+
+  async applyTo(ct: ContentType): Promise<void> {
+    ct.setTaxonomyValidations(this.taxonomyValidations)
+  }
+}
+
+export class ContentTypeAddTaxonomyValidationAction extends EntityAction {
+  private contentTypeId: string
+  private taxonomyId: string
+  private linkType: 'TaxonomyConcept' | 'TaxonomyConceptScheme'
+  private options: { required?: boolean }
+
+  constructor(
+    contentTypeId: string,
+    taxonomyId: string,
+    linkType: 'TaxonomyConcept' | 'TaxonomyConceptScheme',
+    options: { required?: boolean } = {}
+  ) {
+    super()
+    this.contentTypeId = contentTypeId
+    this.taxonomyId = taxonomyId
+    this.linkType = linkType
+    this.options = options
+  }
+
+  getEntityId(): string {
+    return this.contentTypeId
+  }
+
+  getEntityType(): EntityType {
+    return EntityType.ContentType
+  }
+
+  async applyTo(ct: ContentType): Promise<void> {
+    ct.addTaxonomyValidation(this.taxonomyId, this.linkType, this.options)
+  }
+}
+
+export class ContentTypeClearTaxonomyValidationsAction extends EntityAction {
+  private contentTypeId: string
+
+  constructor(contentTypeId: string) {
+    super()
+    this.contentTypeId = contentTypeId
+  }
+
+  getEntityId(): string {
+    return this.contentTypeId
+  }
+
+  getEntityType(): EntityType {
+    return EntityType.ContentType
+  }
+
+  async applyTo(ct: ContentType): Promise<void> {
+    ct.clearTaxonomyValidations()
+  }
+}