@contentchef/contentchef-types 11.2.0-alpha.4 → 11.2.0-alpha.5

package/dist/api/Component.d.ts

@@ -24,6 +24,17 @@ export type ComponentRename = {
     from: string;
     to: string;
 };
+/**
+ * This type represent a field of a definition's root, or of one of its own fragments, that a save gives
+ * another name, so that its values and translations follow. Unlike a version's rename, the type may
+ * change: the values are then checked against the field they move to
+ */
+export type DefinitionRename = ComponentRename & {
+    /**
+     * The definition's own fragment holding the field, left out or null at the root
+     */
+    fragment?: string | null;
+};
 /**
  * This type represent field names, by what happened to them between two versions of a fragment.
  * A field whose type changed is `changed`; a renamed field is in `renamed`, and in neither `added` nor
@@ -366,6 +377,7 @@ export declare enum ComponentErrorTypes {
     noFragmentToPromote = "NoFragmentToPromote",
     definitionMigrating = "DefinitionMigrating",
     oneMigrationPerSave = "OneMigrationPerSave",
+    definitionRenamesRefused = "DefinitionRenamesRefused",
     migrationPreviewNotFound = "MigrationPreviewNotFound",
     invalidComparison = "InvalidComparison",
     fieldNotFound = "FieldNotFound",
@@ -403,6 +415,23 @@ export type ComponentVersionViolation = {
     code: string;
     message: string;
 };
+/**
+ * This type represent a rename a definition save may not declare: from a field the definition does not
+ * have or the save still has, onto one the save does not have or the definition has already, a field in
+ * two renames, or a `fragment` that is not one of the definition's own on both sides
+ */
+export type DefinitionRenameViolation = {
+    /**
+     * The rename's fragment, null at the root
+     */
+    fragment: string | null;
+    /**
+     * The rename's `to`
+     */
+    field: string;
+    code: 'definition.invalidRename';
+    message: string;
+};
 type ComponentErrorOf<T extends ComponentErrorTypes, D = {}> = {
     type: T;
     message: string;
@@ -458,11 +487,14 @@ export type ComponentError = ComponentErrorOf<ComponentErrorTypes.componentNotFo
  */
  | 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
+ * A save that would migrate the values of more than one component, or of a component and of the
+ * definition's own fields (`ownFields`): save one, then the other once its migration has finished
  */
  | ComponentErrorOf<ComponentErrorTypes.oneMigrationPerSave, {
     mnemonicIds: string[];
+    ownFields: boolean;
+}> | ComponentErrorOf<ComponentErrorTypes.definitionRenamesRefused, {
+    violations: DefinitionRenameViolation[];
 }> | ComponentErrorOf<ComponentErrorTypes.migrationPreviewNotFound, {
     id: MigrationPreviewId;
 }>
@@ -482,8 +514,9 @@ export type ComponentError = ComponentErrorOf<ComponentErrorTypes.componentNotFo
  * 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
+ * An upgrade, an adoption, or a save of the definition's own fields 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 = {
     /**
@@ -517,9 +550,13 @@ export type SetAsideValue = {
      */
     revision: number;
     /**
-     * The component it was a value of
+     * The component it was a value of, null for a value of the definition's own fields
      */
-    mnemonicId: string;
+    mnemonicId: string | null;
+    /**
+     * The definition's own fragment it was in, null at the root and for a component's value
+     */
+    fragment: string | null;
     /**
      * Where it was, in the key format translation entries use, with the names the payload has now:
      * `pic.credit`, `gallery.$k1.width`
@@ -564,11 +601,13 @@ export type SetAsideResolution = {
 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
+ * schema about to be saved with the update content definition API request with the renames it will
+ * declare, or the adoption about to be made
  */
 export type MigrationPreviewRequest = {
     id: ContentDefinitionId;
     schema: ContentDefinitionSchemaInput;
+    renames?: DefinitionRename[];
 } | {
     id: ContentDefinitionId;
     adopt: {
@@ -595,6 +634,10 @@ export type GetMigrationPreviewRequest = {
  * values move or are checked
  */
 export type MigrationPreviewField = {
+    /**
+     * The definition's own fragment holding the field, null at the root and for a component's field
+     */
+    fragment: string | null;
     field: string;
     outcome: 'renamed' | 'changed' | 'removed';
     /**
@@ -624,12 +667,15 @@ export type MigrationPreviewField = {
 export type GetMigrationPreviewResponse = {
     id: MigrationPreviewId;
     definitionId: ContentDefinitionId;
-    mnemonicId: string;
     /**
-     * Null for an adoption
+     * The component, null for a save changing the definition's own fields, as `from` and `to`
+     */
+    mnemonicId: string | null;
+    /**
+     * Null for an adoption, and for the definition's own fields
      */
     from: number | null;
-    to: number;
+    to: number | null;
     status: 'running' | 'done';
     /**
      * The contents walked so far, out of `total`
@@ -672,4 +718,67 @@ export type ResumeMigrationRequest = {
  * This type represent the response of a resume migration API request
  */
 export type ResumeMigrationResponse = DefinitionMigrationState;
+/**
+ * This type represent the data needed to make a get set aside API request
+ */
+export type GetSetAsideRequest = {
+    /**
+     * The content definition unique id
+     */
+    id: ContentDefinitionId;
+};
+/**
+ * This type represent what a definition's contents hold set aside for one field by one revision
+ */
+export type SetAsideGroup = {
+    revision: number;
+    /**
+     * The component, null for the definition's own fields
+     */
+    mnemonicId: string | null;
+    /**
+     * The definition's own fragment, null at the root and for a component's field
+     */
+    fragment: string | null;
+    /**
+     * The field's name as the version it came from had it
+     */
+    field: string;
+    reason: 'removed' | 'changed';
+    /**
+     * The contents holding such values
+     */
+    contents: number;
+    values: number;
+};
+/**
+ * This type represent the response of a get set aside API request, by revision, then fragment, then field,
+ * components' values included
+ */
+export type GetSetAsideResponse = SetAsideGroup[];
+/**
+ * This type represent the data needed to make a discard set aside API request: one group as the get set
+ * aside API request answers it
+ */
+export type DiscardSetAsideRequest = {
+    /**
+     * The content definition unique id
+     */
+    id: ContentDefinitionId;
+    revision: number;
+    fragment?: string | null;
+    field: string;
+    /**
+     * Where the previous call stopped, its `next`
+     */
+    after?: number;
+};
+/**
+ * This type represent the response of a discard set aside API request. A call works for about five
+ * seconds: call again with `after: next` until `next` is null
+ */
+export type DiscardSetAsideResponse = {
+    discarded: number;
+    next: number | null;
+};
 export {};

package/dist/api/Component.js

@@ -27,6 +27,7 @@ var ComponentErrorTypes;
     ComponentErrorTypes["noFragmentToPromote"] = "NoFragmentToPromote";
     ComponentErrorTypes["definitionMigrating"] = "DefinitionMigrating";
     ComponentErrorTypes["oneMigrationPerSave"] = "OneMigrationPerSave";
+    ComponentErrorTypes["definitionRenamesRefused"] = "DefinitionRenamesRefused";
     ComponentErrorTypes["migrationPreviewNotFound"] = "MigrationPreviewNotFound";
     ComponentErrorTypes["invalidComparison"] = "InvalidComparison";
     ComponentErrorTypes["fieldNotFound"] = "FieldNotFound";

package/dist/api/Content.d.ts

@@ -1083,7 +1083,8 @@ export type RestoreViolations = {
         violations: ContentConstraintViolation[];
     }[];
     /**
-     * Values a component migration since would set aside: the definition has no place for them any more
+     * @deprecated Always empty: what the migrations since set aside no longer keeps a version from being
+     * restored, see [[GetContentHistoryEntryResponse.setAside]]
      */
     setAside: {
         path: string;
@@ -1104,13 +1105,19 @@ export type GetContentHistoryEntryResponse = ContentHistoryEntry & {
     restorable: boolean;
     violations: RestoreViolations;
     /**
-     * Values of fields removed from the definition by hand since, `path` in the key format of translation
-     * entries. They are left out of `payload` and `translations`, as a save leaves them out, so they do not
-     * keep the version from being restored
+     * Values of fields removed from the definition by hand, before saves migrated contents, `path` in the key
+     * format of translation entries. They are left out of `payload` and `translations`, as a save leaves them
+     * out, so they do not keep the version from being restored
      */
     dropped: {
         path: string;
     }[];
+    /**
+     * Values the migrations since set aside, removed or retyped fields of a component or of the definition.
+     * They are left out of `payload` and `translations`, and a restore writes them beside the content, once,
+     * for a person to move or discard
+     */
+    setAside: SetAsideValue[];
 };
 /**
  * This type represent the data needed to make a restore content API request

package/dist/api/ContentDefinition.d.ts

@@ -1,6 +1,6 @@
 import { AuthorResponse } from './Author';
 import { PagedListResponse } from './common';
-import { DefinitionMigrationState, FieldChanges } from './Component';
+import { DefinitionMigrationState, DefinitionRename, FieldChanges } from './Component';
 import { ComponentMarker, ContentDefinitionSchema, ContentDefinitionSchemaInput, Field, I18NDictionary } from './ContentDefinitionSchema';
 import { Extension } from './Extension';
 /**
@@ -131,6 +131,11 @@ export type UpdateContentDefinitionRequest = {
      * will bypass content definition mnemonicId validation for every linked-content field
      */
     bypassLinkedContentValidation?: boolean;
+    /**
+     * The fields the save gives another name, at the root or in one of the definition's own fragments, for
+     * their values to follow. Undeclared, a rename is a removal and an addition, and the values are set aside
+     */
+    renames?: DefinitionRename[];
 };
 /**
  * This type represent the model of a content definition

package/lib/api/Component.ts

@@ -34,6 +34,18 @@ export type ComponentRename = {
     to: string;
 };
 
+/**
+ * This type represent a field of a definition's root, or of one of its own fragments, that a save gives
+ * another name, so that its values and translations follow. Unlike a version's rename, the type may
+ * change: the values are then checked against the field they move to
+ */
+export type DefinitionRename = ComponentRename & {
+    /**
+     * The definition's own fragment holding the field, left out or null at the root
+     */
+    fragment?: string | null;
+};
+
 /**
  * This type represent field names, by what happened to them between two versions of a fragment.
  * A field whose type changed is `changed`; a renamed field is in `renamed`, and in neither `added` nor
@@ -385,6 +397,7 @@ export enum ComponentErrorTypes {
     noFragmentToPromote = 'NoFragmentToPromote',
     definitionMigrating = 'DefinitionMigrating',
     oneMigrationPerSave = 'OneMigrationPerSave',
+    definitionRenamesRefused = 'DefinitionRenamesRefused',
     migrationPreviewNotFound = 'MigrationPreviewNotFound',
     invalidComparison = 'InvalidComparison',
     fieldNotFound = 'FieldNotFound',
@@ -425,6 +438,24 @@ export type ComponentVersionViolation = {
     message: string;
 };
 
+/**
+ * This type represent a rename a definition save may not declare: from a field the definition does not
+ * have or the save still has, onto one the save does not have or the definition has already, a field in
+ * two renames, or a `fragment` that is not one of the definition's own on both sides
+ */
+export type DefinitionRenameViolation = {
+    /**
+     * The rename's fragment, null at the root
+     */
+    fragment: string | null;
+    /**
+     * The rename's `to`
+     */
+    field: string;
+    code: 'definition.invalidRename';
+    message: string;
+};
+
 type ComponentErrorOf<T extends ComponentErrorTypes, D = {}> = { type: T; message: string } & D;
 
 /**
@@ -469,10 +500,11 @@ export type ComponentError =
      */
     | 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
+     * A save that would migrate the values of more than one component, or of a component and of the
+     * definition's own fields (`ownFields`): save one, then the other once its migration has finished
      */
-    | ComponentErrorOf<ComponentErrorTypes.oneMigrationPerSave, { mnemonicIds: string[] }>
+    | ComponentErrorOf<ComponentErrorTypes.oneMigrationPerSave, { mnemonicIds: string[]; ownFields: boolean }>
+    | ComponentErrorOf<ComponentErrorTypes.definitionRenamesRefused, { violations: DefinitionRenameViolation[] }>
     | ComponentErrorOf<ComponentErrorTypes.migrationPreviewNotFound, { id: MigrationPreviewId }>
     /**
      * A side of a compare component fields API request that is none of the kinds it takes
@@ -491,8 +523,9 @@ export type ComponentError =
  * 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
+ * An upgrade, an adoption, or a save of the definition's own fields 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 = {
     /**
@@ -528,9 +561,13 @@ export type SetAsideValue = {
      */
     revision: number;
     /**
-     * The component it was a value of
+     * The component it was a value of, null for a value of the definition's own fields
      */
-    mnemonicId: string;
+    mnemonicId: string | null;
+    /**
+     * The definition's own fragment it was in, null at the root and for a component's value
+     */
+    fragment: string | null;
     /**
      * Where it was, in the key format translation entries use, with the names the payload has now:
      * `pic.credit`, `gallery.$k1.width`
@@ -576,10 +613,11 @@ 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
+ * schema about to be saved with the update content definition API request with the renames it will
+ * declare, or the adoption about to be made
  */
 export type MigrationPreviewRequest =
-    | { id: ContentDefinitionId; schema: ContentDefinitionSchemaInput }
+    | { id: ContentDefinitionId; schema: ContentDefinitionSchemaInput; renames?: DefinitionRename[] }
     | { id: ContentDefinitionId; adopt: { mnemonicId: string; version: number; renames?: ComponentRename[] } };
 
 /**
@@ -602,6 +640,10 @@ export type GetMigrationPreviewRequest = {
  * values move or are checked
  */
 export type MigrationPreviewField = {
+    /**
+     * The definition's own fragment holding the field, null at the root and for a component's field
+     */
+    fragment: string | null;
     field: string;
     outcome: 'renamed' | 'changed' | 'removed';
     /**
@@ -632,12 +674,15 @@ export type MigrationPreviewField = {
 export type GetMigrationPreviewResponse = {
     id: MigrationPreviewId;
     definitionId: ContentDefinitionId;
-    mnemonicId: string;
     /**
-     * Null for an adoption
+     * The component, null for a save changing the definition's own fields, as `from` and `to`
+     */
+    mnemonicId: string | null;
+    /**
+     * Null for an adoption, and for the definition's own fields
      */
     from: number | null;
-    to: number;
+    to: number | null;
     status: 'running' | 'done';
     /**
      * The contents walked so far, out of `total`
@@ -684,3 +729,71 @@ export type ResumeMigrationRequest = {
  * This type represent the response of a resume migration API request
  */
 export type ResumeMigrationResponse = DefinitionMigrationState;
+
+/**
+ * This type represent the data needed to make a get set aside API request
+ */
+export type GetSetAsideRequest = {
+    /**
+     * The content definition unique id
+     */
+    id: ContentDefinitionId;
+};
+
+/**
+ * This type represent what a definition's contents hold set aside for one field by one revision
+ */
+export type SetAsideGroup = {
+    revision: number;
+    /**
+     * The component, null for the definition's own fields
+     */
+    mnemonicId: string | null;
+    /**
+     * The definition's own fragment, null at the root and for a component's field
+     */
+    fragment: string | null;
+    /**
+     * The field's name as the version it came from had it
+     */
+    field: string;
+    reason: 'removed' | 'changed';
+    /**
+     * The contents holding such values
+     */
+    contents: number;
+    values: number;
+};
+
+/**
+ * This type represent the response of a get set aside API request, by revision, then fragment, then field,
+ * components' values included
+ */
+export type GetSetAsideResponse = SetAsideGroup[];
+
+/**
+ * This type represent the data needed to make a discard set aside API request: one group as the get set
+ * aside API request answers it
+ */
+export type DiscardSetAsideRequest = {
+    /**
+     * The content definition unique id
+     */
+    id: ContentDefinitionId;
+    revision: number;
+    fragment?: string | null;
+    field: string;
+    /**
+     * Where the previous call stopped, its `next`
+     */
+    after?: number;
+};
+
+/**
+ * This type represent the response of a discard set aside API request. A call works for about five
+ * seconds: call again with `after: next` until `next` is null
+ */
+export type DiscardSetAsideResponse = {
+    discarded: number;
+    next: number | null;
+};

package/lib/api/Content.ts

@@ -1165,7 +1165,8 @@ export type RestoreViolations = {
    */
   translations: { locale: string; violations: ContentConstraintViolation[] }[];
   /**
-   * Values a component migration since would set aside: the definition has no place for them any more
+   * @deprecated Always empty: what the migrations since set aside no longer keeps a version from being
+   * restored, see [[GetContentHistoryEntryResponse.setAside]]
    */
   setAside: { path: string; reason: "removed" | "changed" }[];
 };
@@ -1181,11 +1182,17 @@ export type GetContentHistoryEntryResponse = ContentHistoryEntry & {
   restorable: boolean;
   violations: RestoreViolations;
   /**
-   * Values of fields removed from the definition by hand since, `path` in the key format of translation
-   * entries. They are left out of `payload` and `translations`, as a save leaves them out, so they do not
-   * keep the version from being restored
+   * Values of fields removed from the definition by hand, before saves migrated contents, `path` in the key
+   * format of translation entries. They are left out of `payload` and `translations`, as a save leaves them
+   * out, so they do not keep the version from being restored
    */
   dropped: { path: string }[];
+  /**
+   * Values the migrations since set aside, removed or retyped fields of a component or of the definition.
+   * They are left out of `payload` and `translations`, and a restore writes them beside the content, once,
+   * for a person to move or discard
+   */
+  setAside: SetAsideValue[];
 };
 
 /**

package/lib/api/ContentDefinition.ts

@@ -1,6 +1,6 @@
 import { AuthorResponse } from './Author';
 import { PagedListResponse } from './common';
-import { DefinitionMigrationState, FieldChanges } from './Component';
+import { DefinitionMigrationState, DefinitionRename, FieldChanges } from './Component';
 import { ComponentMarker, ContentDefinitionSchema, ContentDefinitionSchemaInput, Field, I18NDictionary } from './ContentDefinitionSchema';
 import { Extension } from './Extension';
 
@@ -142,6 +142,11 @@ export type UpdateContentDefinitionRequest = {
      * will bypass content definition mnemonicId validation for every linked-content field
      */
     bypassLinkedContentValidation?: boolean;
+    /**
+     * The fields the save gives another name, at the root or in one of the definition's own fragments, for
+     * their values to follow. Undeclared, a rename is a removal and an addition, and the values are set aside
+     */
+    renames?: DefinitionRename[];
 };
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contentchef/contentchef-types",
-  "version": "11.2.0-alpha.4",
+  "version": "11.2.0-alpha.5",
   "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": "4768ad3fee441d17e997f7461a28ec12dbe19b5e"
+  "gitHead": "ccaa9d0ae10d67701cf34df7ec127c3c40fefae4"
 }