@contentchef/contentchef-types 11.1.0-alpha.0 → 11.1.0-alpha.2

package/dist/api/Component.d.ts

@@ -1,7 +1,7 @@
 import { AuthorResponse } from './Author';
 import { PagedListResponse } from './common';
 import { AttributeViolation, ContentDefinitionId, GetContentDefinitionResponse, SchemaFieldViolationsErrors } from './ContentDefinition';
-import { FragmentDefinition } from './ContentDefinitionSchema';
+import { ContentDefinitionSchemaInput, Field, FragmentDefinition } from './ContentDefinitionSchema';
 /**
  * The component unique id
  */
@@ -16,14 +16,24 @@ export declare const COMPONENT_NAME_PATTERN: RegExp;
  * else. Its labels, hints, placeholders and list value labels need at least one locale, any locale
  */
 export type ComponentFragment = Omit<FragmentDefinition, 'component'>;
+/**
+ * This type represent a field a version renames, declared when it is published so that the values
+ * written under the old name follow
+ */
+export type ComponentRename = {
+    from: string;
+    to: string;
+};
 /**
  * This type represent field names, by what happened to them between two versions of a fragment.
- * A field whose type changed is `changed`
+ * A field whose type changed is `changed`; a renamed field is in `renamed`, and in neither `added` nor
+ * `removed`
  */
 export type FieldChanges = {
     added: string[];
     removed: string[];
     changed: string[];
+    renamed: ComponentRename[];
 };
 /**
  * This type represent the author of a component, or of one of its versions
@@ -206,6 +216,12 @@ export type PublishComponentRequest = {
      * A note on the version, at most 2000 characters
      */
     note?: string;
+    /**
+     * The fields the version renames: `from` a field of the latest version the draft no longer has, `to`
+     * a field of the draft the latest version does not have, of the same type and changed only as a kept
+     * field may. A name is in one rename at most
+     */
+    renames?: ComponentRename[];
 };
 /**
  * This type represent the response of a publish component API request, its `version` the one just
@@ -274,9 +290,11 @@ export declare enum ComponentErrorTypes {
     componentArchived = "ComponentArchived",
     componentAdoptionRequired = "ComponentAdoptionRequired",
     componentDowngradeRefused = "ComponentDowngradeRefused",
-    componentUpgradeBlocked = "ComponentUpgradeBlocked",
     noFragmentToAdopt = "NoFragmentToAdopt",
-    noFragmentToPromote = "NoFragmentToPromote"
+    noFragmentToPromote = "NoFragmentToPromote",
+    definitionMigrating = "DefinitionMigrating",
+    oneMigrationPerSave = "OneMigrationPerSave",
+    migrationPreviewNotFound = "MigrationPreviewNotFound"
 }
 /**
  * Thin enum represent the codes of a [[ComponentVersionViolation]]
@@ -293,7 +311,11 @@ export declare enum ComponentVersionViolationCodes {
     /**
      * A kept field may only change its texts, or loosen its constraints
      */
-    notLooser = "component.notLooser"
+    notLooser = "component.notLooser",
+    /**
+     * A rename must go from a field the draft no longer has to a new one of the same type
+     */
+    invalidRename = "component.invalidRename"
 }
 /**
  * This type represent a field a new version may not change as the draft does
@@ -306,20 +328,6 @@ export type ComponentVersionViolation = {
     code: string;
     message: string;
 };
-/**
- * This type represent a field an upgrade removes or changes while contents hold a value in it
- */
-export type ComponentUpgradeBlockingField = {
-    field: string;
-    /**
-     * How many contents, archived ones and translations included, hold a value in the field
-     */
-    contents: number;
-    /**
-     * Up to 20 of their content ids
-     */
-    examples: number[];
-};
 type ComponentErrorOf<T extends ComponentErrorTypes, D = {}> = {
     type: T;
     message: string;
@@ -365,18 +373,215 @@ export type ComponentError = ComponentErrorOf<ComponentErrorTypes.componentNotFo
     mnemonicId: string;
     from: number;
     to: number;
-}> | ComponentErrorOf<ComponentErrorTypes.componentUpgradeBlocked, {
+}> | ComponentErrorOf<ComponentErrorTypes.noFragmentToAdopt, {
+    fragment: string;
+}> | ComponentErrorOf<ComponentErrorTypes.noFragmentToPromote, {
     fragment: string;
+}>
+/**
+ * A save changing the schema while the definition's contents are still being migrated
+ */
+ | ComponentErrorOf<ComponentErrorTypes.definitionMigrating, DefinitionMigrationState>
+/**
+ * A save that would migrate the values of more than one component: save one, then the next once it
+ * has finished
+ */
+ | ComponentErrorOf<ComponentErrorTypes.oneMigrationPerSave, {
+    mnemonicIds: string[];
+}> | ComponentErrorOf<ComponentErrorTypes.migrationPreviewNotFound, {
+    id: MigrationPreviewId;
+}>;
+/**
+ * This type represent where a definition's contents stand, as the get content definition, update content
+ * definition and get migration API requests answer it
+ *
+ * An upgrade or adoption that renames, removes or retypes fields bumps the definition's revision and
+ * migrates its contents in the background, one migration at a time per definition
+ */
+export type DefinitionMigrationState = {
+    /**
+     * Bumped by each save that migrates values
+     */
+    revision: number;
+    /**
+     * The contents, archived ones included, still waiting for the migration to `revision`, 0 when none
+     * runs. While above 0, a save changing the schema is refused with `DefinitionMigrating`
+     */
+    behind: number;
+};
+/**
+ * This type represent a translation of a value set aside
+ */
+export type SetAsideTranslation = {
+    /**
+     * Relative to the value's `path`, empty for the value itself
+     */
+    key: string;
+    value: string | null;
+    checksum: string | null;
+};
+/**
+ * This type represent a value a migration could not carry, waiting beside its content for a person to
+ * move into a field or discard
+ */
+export type SetAsideValue = {
+    /**
+     * The definition revision whose migration set it aside
+     */
+    revision: number;
+    /**
+     * The component it was a value of
+     */
+    mnemonicId: string;
+    /**
+     * Where it was, in the key format translation entries use, with the names the payload has now:
+     * `pic.credit`, `gallery.$k1.width`
+     */
+    path: string;
+    /**
+     * The field as the version it came from defined it, for the form to show the value
+     */
+    field: Field;
+    reason: 'removed' | 'changed';
+    /**
+     * Null when the value followed its field and only its translations, which have no place there, wait
+     */
+    value: unknown;
+    /**
+     * Its translations by locale
+     */
+    translations: {
+        [locale: string]: SetAsideTranslation[];
+    };
+    /**
+     * Absent while the content still waits for its migration: the value is set aside by the read
+     */
+    setAsideDate?: Date;
+};
+/**
+ * This type represent a value set aside that a content save resolves. The value itself moves in the
+ * payload, where the person put it, and is then deleted; values not named stay
+ */
+export type SetAsideResolution = {
+    revision: number;
+    path: string;
+    /**
+     * The path of the field the value moved to, for its translations to follow there, where that field
+     * is translatable. Left out, the value is discarded
+     */
+    into?: string;
+};
+/**
+ * The migration preview unique id
+ */
+export type MigrationPreviewId = number;
+/**
+ * This type represent the data needed to make a migration preview API request: the definition, and the
+ * schema about to be saved with the update content definition API request or the adoption about to be made
+ */
+export type MigrationPreviewRequest = {
+    id: ContentDefinitionId;
+    schema: ContentDefinitionSchemaInput;
+} | {
+    id: ContentDefinitionId;
+    adopt: {
+        mnemonicId: string;
+        version: number;
+    };
+};
+/**
+ * This type represent the response of a migration preview API request: the preview's id, or null when
+ * the save would migrate nothing
+ */
+export type MigrationPreviewResponse = {
+    id: MigrationPreviewId | null;
+};
+/**
+ * This type represent the data needed to make a get migration preview API request
+ */
+export type GetMigrationPreviewRequest = {
+    id: MigrationPreviewId;
+};
+/**
+ * This type represent what a migration does to one field of the version the definition is on, whose
+ * values move or are checked
+ */
+export type MigrationPreviewField = {
+    field: string;
+    outcome: 'renamed' | 'changed' | 'removed';
+    /**
+     * The field it becomes, null when removed
+     */
+    to: string | null;
+    /**
+     * The contents holding a value of it
+     */
+    contents: number;
+    renamed: number;
+    converted: number;
+    setAside: number;
+    /**
+     * The translations moved
+     */
+    translations: number;
+    /**
+     * Up to 20 of the contents' ids
+     */
+    examples: number[];
+};
+/**
+ * This type represent the response of a get migration preview API request, to poll until `status` is
+ * `done`. Previews are kept a day
+ */
+export type GetMigrationPreviewResponse = {
+    id: MigrationPreviewId;
+    definitionId: ContentDefinitionId;
     mnemonicId: string;
     /**
-     * Null when the definition's own fragment is adopted
+     * Null for an adoption
      */
     from: number | null;
     to: number;
-    fields: ComponentUpgradeBlockingField[];
-}> | ComponentErrorOf<ComponentErrorTypes.noFragmentToAdopt, {
-    fragment: string;
-}> | ComponentErrorOf<ComponentErrorTypes.noFragmentToPromote, {
-    fragment: string;
-}>;
+    status: 'running' | 'done';
+    /**
+     * The contents walked so far, out of `total`
+     */
+    scanned: number;
+    total: number;
+    fields: MigrationPreviewField[];
+    /**
+     * The contents whose payload or translations would change
+     */
+    changing: number;
+    /**
+     * The contents that would hold values set aside
+     */
+    settingAside: number;
+};
+/**
+ * This type represent the data needed to make a get migration API request
+ */
+export type GetMigrationRequest = {
+    /**
+     * The content definition unique id
+     */
+    id: ContentDefinitionId;
+};
+/**
+ * This type represent the response of a get migration API request, to poll while a migration runs
+ */
+export type GetMigrationResponse = DefinitionMigrationState;
+/**
+ * This type represent the data needed to make a resume migration API request
+ */
+export type ResumeMigrationRequest = {
+    /**
+     * The content definition unique id
+     */
+    id: ContentDefinitionId;
+};
+/**
+ * This type represent the response of a resume migration API request
+ */
+export type ResumeMigrationResponse = DefinitionMigrationState;
 export {};

package/dist/api/Component.js

@@ -22,9 +22,11 @@ var ComponentErrorTypes;
     ComponentErrorTypes["componentArchived"] = "ComponentArchived";
     ComponentErrorTypes["componentAdoptionRequired"] = "ComponentAdoptionRequired";
     ComponentErrorTypes["componentDowngradeRefused"] = "ComponentDowngradeRefused";
-    ComponentErrorTypes["componentUpgradeBlocked"] = "ComponentUpgradeBlocked";
     ComponentErrorTypes["noFragmentToAdopt"] = "NoFragmentToAdopt";
     ComponentErrorTypes["noFragmentToPromote"] = "NoFragmentToPromote";
+    ComponentErrorTypes["definitionMigrating"] = "DefinitionMigrating";
+    ComponentErrorTypes["oneMigrationPerSave"] = "OneMigrationPerSave";
+    ComponentErrorTypes["migrationPreviewNotFound"] = "MigrationPreviewNotFound";
 })(ComponentErrorTypes || (exports.ComponentErrorTypes = ComponentErrorTypes = {}));
 /**
  * Thin enum represent the codes of a [[ComponentVersionViolation]]
@@ -43,4 +45,8 @@ var ComponentVersionViolationCodes;
      * A kept field may only change its texts, or loosen its constraints
      */
     ComponentVersionViolationCodes["notLooser"] = "component.notLooser";
+    /**
+     * A rename must go from a field the draft no longer has to a new one of the same type
+     */
+    ComponentVersionViolationCodes["invalidRename"] = "component.invalidRename";
 })(ComponentVersionViolationCodes || (exports.ComponentVersionViolationCodes = ComponentVersionViolationCodes = {}));

package/dist/api/Content.d.ts

@@ -6,6 +6,7 @@ import { SchemaTypeIds } from "./ContentDefinitionSchema";
 import { ContentRepositoryId, ContentRepositoryResponse } from "./ContentRepository";
 import { ContentTranslation, ContentTranslationStatus } from "./ContentTranslation";
 import { CoverageReport } from "./Audience";
+import { SetAsideResolution, SetAsideValue } from "./Component";
 /**
  * This type represent the content unique id type
  */
@@ -303,6 +304,11 @@ export type UpdateContentRequest = {
      * set an identifier coming from a third party application
      */
     externalIdentifier?: string;
+    /**
+     * The values a migration set aside that this save resolves, moved into the payload by the person or
+     * discarded
+     */
+    setAside?: SetAsideResolution[];
 };
 /**
  * This type represent the data that can be used to filter a list of contents
@@ -373,6 +379,10 @@ export type ListContentsFilters = {
      * audience mnemonic ids inserted. Several of them narrow the result like `tags` do
      */
     audiences?: string[];
+    /**
+     * true lists only the contents holding values a migration set aside
+     */
+    setAside?: boolean;
 };
 /**
  * This type represent the data needed to make a list content API request
@@ -655,9 +665,12 @@ export type LinkingContents = ContentResponse;
  */
 export type GetContentResponse = {
     /**
-     * The requested content
+     * The requested content, migrated when it still waits for its definition's migration, with the values
+     * set aside beside it
      */
-    content: ContentResponse | undefined;
+    content: (ContentResponse & {
+        setAside: SetAsideValue[];
+    }) | undefined;
     /**
      * The contents that use the requested content
      */
@@ -670,7 +683,12 @@ export type CreateContentResponse = ContentResponse;
 /**
  * This type represent the response of an update content API request
  */
-export type UpdateContentResponse = ContentResponse;
+export type UpdateContentResponse = ContentResponse & {
+    /**
+     * The values set aside left to resolve after the save, so a form need not read the content again
+     */
+    setAside: SetAsideValue[];
+};
 /**
  * This type represent the data needed to make a list public id API request
  */

package/dist/api/ContentDefinition.d.ts

@@ -1,6 +1,6 @@
 import { AuthorResponse } from './Author';
 import { PagedListResponse } from './common';
-import { FieldChanges } from './Component';
+import { DefinitionMigrationState, FieldChanges } from './Component';
 import { ComponentMarker, ContentDefinitionSchema, ContentDefinitionSchemaInput, Field, I18NDictionary } from './ContentDefinitionSchema';
 import { Extension } from './Extension';
 /**
@@ -195,8 +195,8 @@ export type DefinitionComponent = ComponentMarker & {
      */
     archived: boolean;
     /**
-     * What upgrading from `version` to `latestVersion` would add, remove and change, all empty when up
-     * to date. Whether the upgrade would be blocked by the contents is only known by trying it
+     * What upgrading from `version` to `latestVersion` would add, remove, change and rename, all empty
+     * when up to date. What it would do to the contents is only known by previewing it
      */
     changes: FieldChanges;
 };
@@ -207,7 +207,12 @@ export type CreateContentDefinitionResponse = ContentDefinitionResponse;
 /**
  * This type represent the response of an update content definition API request
  */
-export type UpdateContentDefinitionResponse = ContentDefinitionResponse;
+export type UpdateContentDefinitionResponse = ContentDefinitionResponse & {
+    /**
+     * Where the definition's contents stand: a save that started a migration has them all behind
+     */
+    migration: DefinitionMigrationState;
+};
 /**
  * This type represent the response of a get content definition API request
  */
@@ -216,6 +221,10 @@ export type GetContentDefinitionResponse = (Omit<ContentDefinitionResponse, 'com
      * The components the definition uses, each with its latest version and what upgrading to it changes
      */
     components: DefinitionComponent[];
+    /**
+     * Where the definition's contents stand in its migrations
+     */
+    migration: DefinitionMigrationState;
 }) | undefined;
 /**
  * This type represent the data needed to make a validate definition field API request

package/lib/api/Component.ts

@@ -6,7 +6,7 @@ import {
     GetContentDefinitionResponse,
     SchemaFieldViolationsErrors
 } from './ContentDefinition';
-import { FragmentDefinition } from './ContentDefinitionSchema';
+import { ContentDefinitionSchemaInput, Field, FragmentDefinition } from './ContentDefinitionSchema';
 
 /**
  * The component unique id
@@ -25,14 +25,25 @@ export const COMPONENT_NAME_PATTERN = /^[a-zA-Z0-9_]+$/;
  */
 export type ComponentFragment = Omit<FragmentDefinition, 'component'>;
 
+/**
+ * This type represent a field a version renames, declared when it is published so that the values
+ * written under the old name follow
+ */
+export type ComponentRename = {
+    from: string;
+    to: string;
+};
+
 /**
  * This type represent field names, by what happened to them between two versions of a fragment.
- * A field whose type changed is `changed`
+ * A field whose type changed is `changed`; a renamed field is in `renamed`, and in neither `added` nor
+ * `removed`
  */
 export type FieldChanges = {
     added: string[];
     removed: string[];
     changed: string[];
+    renamed: ComponentRename[];
 };
 
 /**
@@ -224,6 +235,12 @@ export type PublishComponentRequest = {
      * A note on the version, at most 2000 characters
      */
     note?: string;
+    /**
+     * The fields the version renames: `from` a field of the latest version the draft no longer has, `to`
+     * a field of the draft the latest version does not have, of the same type and changed only as a kept
+     * field may. A name is in one rename at most
+     */
+    renames?: ComponentRename[];
 };
 
 /**
@@ -300,9 +317,11 @@ export enum ComponentErrorTypes {
     componentArchived = 'ComponentArchived',
     componentAdoptionRequired = 'ComponentAdoptionRequired',
     componentDowngradeRefused = 'ComponentDowngradeRefused',
-    componentUpgradeBlocked = 'ComponentUpgradeBlocked',
     noFragmentToAdopt = 'NoFragmentToAdopt',
-    noFragmentToPromote = 'NoFragmentToPromote'
+    noFragmentToPromote = 'NoFragmentToPromote',
+    definitionMigrating = 'DefinitionMigrating',
+    oneMigrationPerSave = 'OneMigrationPerSave',
+    migrationPreviewNotFound = 'MigrationPreviewNotFound'
 }
 
 /**
@@ -320,7 +339,11 @@ export enum ComponentVersionViolationCodes {
     /**
      * A kept field may only change its texts, or loosen its constraints
      */
-    notLooser = 'component.notLooser'
+    notLooser = 'component.notLooser',
+    /**
+     * A rename must go from a field the draft no longer has to a new one of the same type
+     */
+    invalidRename = 'component.invalidRename'
 }
 
 /**
@@ -335,21 +358,6 @@ export type ComponentVersionViolation = {
     message: string;
 };
 
-/**
- * This type represent a field an upgrade removes or changes while contents hold a value in it
- */
-export type ComponentUpgradeBlockingField = {
-    field: string;
-    /**
-     * How many contents, archived ones and translations included, hold a value in the field
-     */
-    contents: number;
-    /**
-     * Up to 20 of their content ids
-     */
-    examples: number[];
-};
-
 type ComponentErrorOf<T extends ComponentErrorTypes, D = {}> = { type: T; message: string } & D;
 
 /**
@@ -387,15 +395,213 @@ export type ComponentError =
     | ComponentErrorOf<ComponentErrorTypes.componentArchived, { fragment: string }>
     | ComponentErrorOf<ComponentErrorTypes.componentAdoptionRequired, { fragment: string }>
     | ComponentErrorOf<ComponentErrorTypes.componentDowngradeRefused, { fragment: string; mnemonicId: string; from: number; to: number }>
-    | ComponentErrorOf<ComponentErrorTypes.componentUpgradeBlocked, {
-        fragment: string;
-        mnemonicId: string;
-        /**
-         * Null when the definition's own fragment is adopted
-         */
-        from: number | null;
-        to: number;
-        fields: ComponentUpgradeBlockingField[];
-    }>
     | ComponentErrorOf<ComponentErrorTypes.noFragmentToAdopt, { fragment: string }>
-    | ComponentErrorOf<ComponentErrorTypes.noFragmentToPromote, { fragment: string }>;
+    | ComponentErrorOf<ComponentErrorTypes.noFragmentToPromote, { fragment: string }>
+    /**
+     * A save changing the schema while the definition's contents are still being migrated
+     */
+    | ComponentErrorOf<ComponentErrorTypes.definitionMigrating, DefinitionMigrationState>
+    /**
+     * A save that would migrate the values of more than one component: save one, then the next once it
+     * has finished
+     */
+    | ComponentErrorOf<ComponentErrorTypes.oneMigrationPerSave, { mnemonicIds: string[] }>
+    | ComponentErrorOf<ComponentErrorTypes.migrationPreviewNotFound, { id: MigrationPreviewId }>;
+
+/**
+ * This type represent where a definition's contents stand, as the get content definition, update content
+ * definition and get migration API requests answer it
+ *
+ * An upgrade or adoption that renames, removes or retypes fields bumps the definition's revision and
+ * migrates its contents in the background, one migration at a time per definition
+ */
+export type DefinitionMigrationState = {
+    /**
+     * Bumped by each save that migrates values
+     */
+    revision: number;
+    /**
+     * The contents, archived ones included, still waiting for the migration to `revision`, 0 when none
+     * runs. While above 0, a save changing the schema is refused with `DefinitionMigrating`
+     */
+    behind: number;
+};
+
+/**
+ * This type represent a translation of a value set aside
+ */
+export type SetAsideTranslation = {
+    /**
+     * Relative to the value's `path`, empty for the value itself
+     */
+    key: string;
+    value: string | null;
+    checksum: string | null;
+};
+
+/**
+ * This type represent a value a migration could not carry, waiting beside its content for a person to
+ * move into a field or discard
+ */
+export type SetAsideValue = {
+    /**
+     * The definition revision whose migration set it aside
+     */
+    revision: number;
+    /**
+     * The component it was a value of
+     */
+    mnemonicId: string;
+    /**
+     * Where it was, in the key format translation entries use, with the names the payload has now:
+     * `pic.credit`, `gallery.$k1.width`
+     */
+    path: string;
+    /**
+     * The field as the version it came from defined it, for the form to show the value
+     */
+    field: Field;
+    reason: 'removed' | 'changed';
+    /**
+     * Null when the value followed its field and only its translations, which have no place there, wait
+     */
+    value: unknown;
+    /**
+     * Its translations by locale
+     */
+    translations: { [locale: string]: SetAsideTranslation[] };
+    /**
+     * Absent while the content still waits for its migration: the value is set aside by the read
+     */
+    setAsideDate?: Date;
+};
+
+/**
+ * This type represent a value set aside that a content save resolves. The value itself moves in the
+ * payload, where the person put it, and is then deleted; values not named stay
+ */
+export type SetAsideResolution = {
+    revision: number;
+    path: string;
+    /**
+     * The path of the field the value moved to, for its translations to follow there, where that field
+     * is translatable. Left out, the value is discarded
+     */
+    into?: string;
+};
+
+/**
+ * The migration preview unique id
+ */
+export type MigrationPreviewId = number;
+
+/**
+ * This type represent the data needed to make a migration preview API request: the definition, and the
+ * schema about to be saved with the update content definition API request or the adoption about to be made
+ */
+export type MigrationPreviewRequest =
+    | { id: ContentDefinitionId; schema: ContentDefinitionSchemaInput }
+    | { id: ContentDefinitionId; adopt: { mnemonicId: string; version: number } };
+
+/**
+ * This type represent the response of a migration preview API request: the preview's id, or null when
+ * the save would migrate nothing
+ */
+export type MigrationPreviewResponse = {
+    id: MigrationPreviewId | null;
+};
+
+/**
+ * This type represent the data needed to make a get migration preview API request
+ */
+export type GetMigrationPreviewRequest = {
+    id: MigrationPreviewId;
+};
+
+/**
+ * This type represent what a migration does to one field of the version the definition is on, whose
+ * values move or are checked
+ */
+export type MigrationPreviewField = {
+    field: string;
+    outcome: 'renamed' | 'changed' | 'removed';
+    /**
+     * The field it becomes, null when removed
+     */
+    to: string | null;
+    /**
+     * The contents holding a value of it
+     */
+    contents: number;
+    renamed: number;
+    converted: number;
+    setAside: number;
+    /**
+     * The translations moved
+     */
+    translations: number;
+    /**
+     * Up to 20 of the contents' ids
+     */
+    examples: number[];
+};
+
+/**
+ * This type represent the response of a get migration preview API request, to poll until `status` is
+ * `done`. Previews are kept a day
+ */
+export type GetMigrationPreviewResponse = {
+    id: MigrationPreviewId;
+    definitionId: ContentDefinitionId;
+    mnemonicId: string;
+    /**
+     * Null for an adoption
+     */
+    from: number | null;
+    to: number;
+    status: 'running' | 'done';
+    /**
+     * The contents walked so far, out of `total`
+     */
+    scanned: number;
+    total: number;
+    fields: MigrationPreviewField[];
+    /**
+     * The contents whose payload or translations would change
+     */
+    changing: number;
+    /**
+     * The contents that would hold values set aside
+     */
+    settingAside: number;
+};
+
+/**
+ * This type represent the data needed to make a get migration API request
+ */
+export type GetMigrationRequest = {
+    /**
+     * The content definition unique id
+     */
+    id: ContentDefinitionId;
+};
+
+/**
+ * This type represent the response of a get migration API request, to poll while a migration runs
+ */
+export type GetMigrationResponse = DefinitionMigrationState;
+
+/**
+ * This type represent the data needed to make a resume migration API request
+ */
+export type ResumeMigrationRequest = {
+    /**
+     * The content definition unique id
+     */
+    id: ContentDefinitionId;
+};
+
+/**
+ * This type represent the response of a resume migration API request
+ */
+export type ResumeMigrationResponse = DefinitionMigrationState;

package/lib/api/Content.ts

@@ -15,6 +15,7 @@ import {
   ContentTranslationStatus,
 } from "./ContentTranslation";
 import { CoverageReport } from "./Audience";
+import { SetAsideResolution, SetAsideValue } from "./Component";
 
 /**
  * This type represent the content unique id type
@@ -335,6 +336,12 @@ export type UpdateContentRequest = {
    * set an identifier coming from a third party application
    */
   externalIdentifier?: string;
+
+  /**
+   * The values a migration set aside that this save resolves, moved into the payload by the person or
+   * discarded
+   */
+  setAside?: SetAsideResolution[];
 };
 
 /**
@@ -408,6 +415,11 @@ export type ListContentsFilters = {
    * audience mnemonic ids inserted. Several of them narrow the result like `tags` do
    */
   audiences?: string[];
+
+  /**
+   * true lists only the contents holding values a migration set aside
+   */
+  setAside?: boolean;
 };
 
 /**
@@ -716,9 +728,10 @@ export type LinkingContents = ContentResponse;
  */
 export type GetContentResponse = {
   /**
-   * The requested content
+   * The requested content, migrated when it still waits for its definition's migration, with the values
+   * set aside beside it
    */
-  content: ContentResponse | undefined;
+  content: (ContentResponse & { setAside: SetAsideValue[] }) | undefined;
   /**
    * The contents that use the requested content
    */
@@ -732,7 +745,12 @@ export type CreateContentResponse = ContentResponse;
 /**
  * This type represent the response of an update content API request
  */
-export type UpdateContentResponse = ContentResponse;
+export type UpdateContentResponse = ContentResponse & {
+  /**
+   * The values set aside left to resolve after the save, so a form need not read the content again
+   */
+  setAside: SetAsideValue[];
+};
 
 /**
  * This type represent the data needed to make a list public id API request

package/lib/api/ContentDefinition.ts

@@ -1,6 +1,6 @@
 import { AuthorResponse } from './Author';
 import { PagedListResponse } from './common';
-import { FieldChanges } from './Component';
+import { DefinitionMigrationState, FieldChanges } from './Component';
 import { ComponentMarker, ContentDefinitionSchema, ContentDefinitionSchemaInput, Field, I18NDictionary } from './ContentDefinitionSchema';
 import { Extension } from './Extension';
 
@@ -211,8 +211,8 @@ export type DefinitionComponent = ComponentMarker & {
      */
     archived: boolean;
     /**
-     * What upgrading from `version` to `latestVersion` would add, remove and change, all empty when up
-     * to date. Whether the upgrade would be blocked by the contents is only known by trying it
+     * What upgrading from `version` to `latestVersion` would add, remove, change and rename, all empty
+     * when up to date. What it would do to the contents is only known by previewing it
      */
     changes: FieldChanges;
 };
@@ -224,7 +224,12 @@ export type CreateContentDefinitionResponse = ContentDefinitionResponse;
 /**
  * This type represent the response of an update content definition API request
  */
-export type UpdateContentDefinitionResponse = ContentDefinitionResponse;
+export type UpdateContentDefinitionResponse = ContentDefinitionResponse & {
+    /**
+     * Where the definition's contents stand: a save that started a migration has them all behind
+     */
+    migration: DefinitionMigrationState;
+};
 /**
  * This type represent the response of a get content definition API request
  */
@@ -233,6 +238,10 @@ export type GetContentDefinitionResponse = (Omit<ContentDefinitionResponse, 'com
      * The components the definition uses, each with its latest version and what upgrading to it changes
      */
     components: DefinitionComponent[];
+    /**
+     * Where the definition's contents stand in its migrations
+     */
+    migration: DefinitionMigrationState;
 }) | undefined;
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contentchef/contentchef-types",
-  "version": "11.1.0-alpha.0",
+  "version": "11.1.0-alpha.2",
   "description": "ContentChef types",
   "author": "PierpaoloIannone <piannone@byte-code.com>",
   "homepage": "https://github.com/ContentChef/contentchef-management-js-client#readme",
@@ -34,5 +34,5 @@
   "devDependencies": {
     "typescript": "^5.9.3"
   },
-  "gitHead": "06b0724c9e74c0e2975a4af2917924010858759d"
+  "gitHead": "6aef68846f09d3cec95ade3d59906d1edc48db85"
 }