@contentchef/contentchef-types 11.2.0-alpha.3 → 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/dist/api/PublishedContent.d.ts

@@ -1,4 +1,4 @@
-import { ContentId, LocalizationSettings } from "./Content";
+import { ContentId, LocalizationSettings, SortDirection } from "./Content";
 import { AuthorResponse } from "./Author";
 import { ContentRepositoryId } from "./ContentRepository";
 import { ContentTranslationStatus } from "./ContentTranslation";
@@ -452,3 +452,312 @@ export type ListReleaseItemsV2Response = PagedListResponse<ReleaseItemGroup> & {
  * This type represent the response of a get published content API request
  */
 export type GetPublishedContentResponse = PublishedContentResponse | undefined;
+/**
+ * This enum represent how the items of [[PropFilters]] combine
+ */
+export declare enum LogicalOperators {
+    AND = "AND",
+    OR = "OR"
+}
+/**
+ * This enum represent how a [[PropFilterItem]] compares an indexed field with its value. The `_IC`
+ * variants ignore case
+ */
+export declare enum ConditionOperators {
+    CONTAINS = "CONTAINS",
+    CONTAINS_IC = "CONTAINS_IC",
+    EQUALS = "EQUALS",
+    EQUALS_IC = "EQUALS_IC",
+    IN = "IN",
+    IN_IC = "IN_IC",
+    STARTS_WITH = "STARTS_WITH",
+    STARTS_WITH_IC = "STARTS_WITH_IC"
+}
+/**
+ * This type represent one condition over an indexed field of a published content, as the delivery API
+ * takes it
+ */
+export type PropFilterItem = {
+    field: string;
+    operator: ConditionOperators;
+    /**
+     * An array for [[ConditionOperators.IN]] and [[ConditionOperators.IN_IC]]
+     */
+    value: string | string[];
+};
+/**
+ * This type represent the delivery API's property filters, over the indexed fields of a published content
+ */
+export type PropFilters = {
+    condition: LogicalOperators;
+    /**
+     * From 1 to 10
+     */
+    items: PropFilterItem[];
+};
+/**
+ * This type represent which date of a content's online window has to fall within a timeline's range:
+ * `overlap`, online at some point of it, `starts`, its online date, or `ends`, its offline date
+ */
+export type TimelineMatch = "overlap" | "starts" | "ends";
+/**
+ * This type represent the range and filters of the timeline API requests. Every filter given applies,
+ * together, and a list filter matches a content that has one of its values
+ */
+export type TimelineFilters = {
+    /**
+     * The range's start, as an ISO 8601 string. With `from` equal to `to`, what is online at that instant
+     */
+    from: string;
+    /**
+     * The range's end, as an ISO 8601 string, not before `from` and at most 400 days after it
+     */
+    to: string;
+    /**
+     * `overlap` by default
+     */
+    match?: TimelineMatch;
+    /**
+     * Whether the contents with neither date, online all the time, are left out, by default, or included
+     */
+    undated?: "exclude" | "include";
+    /**
+     * From 2 to 100 characters, matched anywhere in the name, the public id or the external identifier,
+     * ignoring case
+     */
+    search?: string;
+    /**
+     * Up to 500
+     */
+    publicIds?: string[];
+    /**
+     * Up to 500
+     */
+    contentIds?: ContentId[];
+    /**
+     * Content definition mnemonic ids, up to 100
+     */
+    definitions?: string[];
+    /**
+     * Content repository mnemonic ids, up to 100
+     */
+    repositories?: string[];
+    /**
+     * Up to 100
+     */
+    channels?: string[];
+    /**
+     * Up to 100
+     */
+    tags?: string[];
+    /**
+     * Up to 100
+     */
+    locales?: string[];
+    propFilters?: PropFilters;
+};
+/**
+ * This type represent a version of a content on the timeline: `live`, the one delivery serves, or
+ * `pending`, the one published to stage and not promoted yet
+ */
+export type TimelineVersionKind = "live" | "pending";
+/**
+ * This type represent what the timeline can be sorted by. With both versions, a content sorts by the
+ * earlier online date, the later offline date and the latest publish of the two
+ */
+export type TimelineSort = "onlineDate" | "offlineDate" | "name" | "publicId" | "definition" | "lastPublished";
+/**
+ * This type represent the data needed to make a list timeline API request
+ */
+export type ListTimelineRequest = TimelineFilters & {
+    /**
+     * Both by default
+     */
+    versions?: TimelineVersionKind[];
+    /**
+     * `onlineDate` by default
+     */
+    sort?: TimelineSort;
+    /**
+     * Ascending by default
+     */
+    order?: SortDirection;
+    /**
+     * true counts the filtered contents per definition, repository, channel, tag and locale
+     */
+    facets?: boolean;
+    /**
+     * 0 by default
+     */
+    skip?: number;
+    /**
+     * 50 by default, at most 200, counted in contents
+     */
+    take?: number;
+};
+/**
+ * This type represent one version of a content on the timeline, as its default locale has it
+ */
+export type TimelineVersion = {
+    version: number;
+    /**
+     * As an ISO 8601 string, null without one
+     */
+    onlineDate: string | null;
+    /**
+     * As an ISO 8601 string, null without one
+     */
+    offlineDate: string | null;
+    /**
+     * When the version was published to stage, as an ISO 8601 string
+     */
+    publishedDate: string;
+    channels: string[];
+    tags: string[];
+    /**
+     * Every locale of the version
+     */
+    locales: string[];
+};
+/**
+ * This type represent a content on the timeline, with each of its versions asked for
+ */
+export type TimelineItem = {
+    contentId: ContentId;
+    /**
+     * The pending version's when there is one, as `name` and `externalIdentifier`
+     */
+    publicId: string;
+    name: string;
+    externalIdentifier: string | null;
+    /**
+     * The content definition mnemonic id
+     */
+    definition: string;
+    /**
+     * The content repository mnemonic id
+     */
+    repository: string;
+    /**
+     * null for a content only in stage
+     */
+    live: TimelineVersion | null;
+    /**
+     * null for a content whose staged version is the live one
+     */
+    pending: TimelineVersion | null;
+};
+/**
+ * This type represent, per value, how many of the filtered contents have it. A content with two versions
+ * counts once per value either has
+ */
+export type TimelineFacets = {
+    definitions: {
+        [mnemonicId: string]: number;
+    };
+    repositories: {
+        [mnemonicId: string]: number;
+    };
+    channels: {
+        [channel: string]: number;
+    };
+    tags: {
+        [tag: string]: number;
+    };
+    locales: {
+        [locale: string]: number;
+    };
+};
+/**
+ * This type represent the response of a list timeline API request
+ */
+export type ListTimelineResponse = {
+    items: TimelineItem[];
+    total: number;
+    /**
+     * The contents with neither date, whether `undated` excludes them or not
+     */
+    undated: number;
+    /**
+     * Only when asked for
+     */
+    facets?: TimelineFacets;
+};
+/**
+ * This type represent the size of a timeline summary's buckets. A week starts on Monday
+ */
+export type TimelineBucket = "day" | "week" | "month";
+/**
+ * This type represent what a timeline summary counts: `live`, what delivery serves, or `afterRelease`,
+ * what it would serve were the staged versions promoted
+ */
+export type TimelineState = "live" | "afterRelease";
+/**
+ * This type represent the data needed to make a get timeline summary API request
+ */
+export type GetTimelineSummaryRequest = TimelineFilters & {
+    bucket: TimelineBucket;
+    /**
+     * An IANA time zone, `UTC` by default: buckets start at its midnights
+     */
+    timeZone?: string;
+    /**
+     * `live` by default
+     */
+    state?: TimelineState;
+};
+/**
+ * This type represent the counts of one bucket of a timeline summary
+ */
+export type TimelineBucketCount = {
+    /**
+     * The bucket's first day in the time zone, as `YYYY-MM-DD`
+     */
+    date: string;
+    /**
+     * The bucket's start, as an ISO 8601 string in UTC
+     */
+    from: string;
+    /**
+     * The bucket's end, as an ISO 8601 string in UTC
+     */
+    to: string;
+    /**
+     * The contents online at some point of the bucket
+     */
+    online: number;
+    /**
+     * The contents whose online date falls within the bucket
+     */
+    comingOnline: number;
+    /**
+     * The contents whose offline date falls within the bucket
+     */
+    goingOffline: number;
+};
+/**
+ * This type represent the response of a get timeline summary API request: one entry per bucket, from the
+ * one holding `from` to the one holding `to`
+ */
+export type GetTimelineSummaryResponse = TimelineBucketCount[];
+/**
+ * Thin enum represent the error types of the timeline API requests. Each is the `type` of a
+ * `RequestError`, whose `details` is a [[TimelineError]]
+ */
+export declare enum TimelineErrorTypes {
+    /**
+     * `to` before `from`, a range over 400 days, or an unknown time zone
+     */
+    invalidTimelineQuery = "InvalidTimelineQuery",
+    /**
+     * The query took over 4 seconds and was stopped: narrow the range or the filters
+     */
+    timelineTooSlow = "TimelineTooSlow"
+}
+/**
+ * This type represent the `details` of a `RequestError` whose `type` is one of [[TimelineErrorTypes]]
+ */
+export type TimelineError = {
+    type: TimelineErrorTypes;
+    message: string;
+};

package/dist/api/PublishedContent.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DateFilterOperator = void 0;
+exports.TimelineErrorTypes = exports.ConditionOperators = exports.LogicalOperators = exports.DateFilterOperator = void 0;
 /**
  * This enum represent the comparison operators available to a release item date filter
  */
@@ -9,3 +9,41 @@ var DateFilterOperator;
     DateFilterOperator["lte"] = "lte";
     DateFilterOperator["gte"] = "gte";
 })(DateFilterOperator || (exports.DateFilterOperator = DateFilterOperator = {}));
+/**
+ * This enum represent how the items of [[PropFilters]] combine
+ */
+var LogicalOperators;
+(function (LogicalOperators) {
+    LogicalOperators["AND"] = "AND";
+    LogicalOperators["OR"] = "OR";
+})(LogicalOperators || (exports.LogicalOperators = LogicalOperators = {}));
+/**
+ * This enum represent how a [[PropFilterItem]] compares an indexed field with its value. The `_IC`
+ * variants ignore case
+ */
+var ConditionOperators;
+(function (ConditionOperators) {
+    ConditionOperators["CONTAINS"] = "CONTAINS";
+    ConditionOperators["CONTAINS_IC"] = "CONTAINS_IC";
+    ConditionOperators["EQUALS"] = "EQUALS";
+    ConditionOperators["EQUALS_IC"] = "EQUALS_IC";
+    ConditionOperators["IN"] = "IN";
+    ConditionOperators["IN_IC"] = "IN_IC";
+    ConditionOperators["STARTS_WITH"] = "STARTS_WITH";
+    ConditionOperators["STARTS_WITH_IC"] = "STARTS_WITH_IC";
+})(ConditionOperators || (exports.ConditionOperators = ConditionOperators = {}));
+/**
+ * Thin enum represent the error types of the timeline API requests. Each is the `type` of a
+ * `RequestError`, whose `details` is a [[TimelineError]]
+ */
+var TimelineErrorTypes;
+(function (TimelineErrorTypes) {
+    /**
+     * `to` before `from`, a range over 400 days, or an unknown time zone
+     */
+    TimelineErrorTypes["invalidTimelineQuery"] = "InvalidTimelineQuery";
+    /**
+     * The query took over 4 seconds and was stopped: narrow the range or the filters
+     */
+    TimelineErrorTypes["timelineTooSlow"] = "TimelineTooSlow";
+})(TimelineErrorTypes || (exports.TimelineErrorTypes = TimelineErrorTypes = {}));

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/lib/api/PublishedContent.ts

@@ -1,4 +1,4 @@
-import { ContentId, LocalizationSettings } from "./Content";
+import { ContentId, LocalizationSettings, SortDirection } from "./Content";
 import { AuthorResponse } from "./Author";
 import { ContentRepositoryId } from "./ContentRepository";
 import { ContentTranslationStatus } from "./ContentTranslation";
@@ -477,3 +477,325 @@ export type ListReleaseItemsV2Response = PagedListResponse<ReleaseItemGroup> & {
  * This type represent the response of a get published content API request
  */
 export type GetPublishedContentResponse = PublishedContentResponse | undefined;
+
+/**
+ * This enum represent how the items of [[PropFilters]] combine
+ */
+export enum LogicalOperators {
+  AND = "AND",
+  OR = "OR",
+}
+
+/**
+ * This enum represent how a [[PropFilterItem]] compares an indexed field with its value. The `_IC`
+ * variants ignore case
+ */
+export enum ConditionOperators {
+  CONTAINS = "CONTAINS",
+  CONTAINS_IC = "CONTAINS_IC",
+  EQUALS = "EQUALS",
+  EQUALS_IC = "EQUALS_IC",
+  IN = "IN",
+  IN_IC = "IN_IC",
+  STARTS_WITH = "STARTS_WITH",
+  STARTS_WITH_IC = "STARTS_WITH_IC",
+}
+
+/**
+ * This type represent one condition over an indexed field of a published content, as the delivery API
+ * takes it
+ */
+export type PropFilterItem = {
+  field: string;
+  operator: ConditionOperators;
+  /**
+   * An array for [[ConditionOperators.IN]] and [[ConditionOperators.IN_IC]]
+   */
+  value: string | string[];
+};
+
+/**
+ * This type represent the delivery API's property filters, over the indexed fields of a published content
+ */
+export type PropFilters = {
+  condition: LogicalOperators;
+  /**
+   * From 1 to 10
+   */
+  items: PropFilterItem[];
+};
+
+/**
+ * This type represent which date of a content's online window has to fall within a timeline's range:
+ * `overlap`, online at some point of it, `starts`, its online date, or `ends`, its offline date
+ */
+export type TimelineMatch = "overlap" | "starts" | "ends";
+
+/**
+ * This type represent the range and filters of the timeline API requests. Every filter given applies,
+ * together, and a list filter matches a content that has one of its values
+ */
+export type TimelineFilters = {
+  /**
+   * The range's start, as an ISO 8601 string. With `from` equal to `to`, what is online at that instant
+   */
+  from: string;
+  /**
+   * The range's end, as an ISO 8601 string, not before `from` and at most 400 days after it
+   */
+  to: string;
+  /**
+   * `overlap` by default
+   */
+  match?: TimelineMatch;
+  /**
+   * Whether the contents with neither date, online all the time, are left out, by default, or included
+   */
+  undated?: "exclude" | "include";
+  /**
+   * From 2 to 100 characters, matched anywhere in the name, the public id or the external identifier,
+   * ignoring case
+   */
+  search?: string;
+  /**
+   * Up to 500
+   */
+  publicIds?: string[];
+  /**
+   * Up to 500
+   */
+  contentIds?: ContentId[];
+  /**
+   * Content definition mnemonic ids, up to 100
+   */
+  definitions?: string[];
+  /**
+   * Content repository mnemonic ids, up to 100
+   */
+  repositories?: string[];
+  /**
+   * Up to 100
+   */
+  channels?: string[];
+  /**
+   * Up to 100
+   */
+  tags?: string[];
+  /**
+   * Up to 100
+   */
+  locales?: string[];
+  propFilters?: PropFilters;
+};
+
+/**
+ * This type represent a version of a content on the timeline: `live`, the one delivery serves, or
+ * `pending`, the one published to stage and not promoted yet
+ */
+export type TimelineVersionKind = "live" | "pending";
+
+/**
+ * This type represent what the timeline can be sorted by. With both versions, a content sorts by the
+ * earlier online date, the later offline date and the latest publish of the two
+ */
+export type TimelineSort =
+  | "onlineDate"
+  | "offlineDate"
+  | "name"
+  | "publicId"
+  | "definition"
+  | "lastPublished";
+
+/**
+ * This type represent the data needed to make a list timeline API request
+ */
+export type ListTimelineRequest = TimelineFilters & {
+  /**
+   * Both by default
+   */
+  versions?: TimelineVersionKind[];
+  /**
+   * `onlineDate` by default
+   */
+  sort?: TimelineSort;
+  /**
+   * Ascending by default
+   */
+  order?: SortDirection;
+  /**
+   * true counts the filtered contents per definition, repository, channel, tag and locale
+   */
+  facets?: boolean;
+  /**
+   * 0 by default
+   */
+  skip?: number;
+  /**
+   * 50 by default, at most 200, counted in contents
+   */
+  take?: number;
+};
+
+/**
+ * This type represent one version of a content on the timeline, as its default locale has it
+ */
+export type TimelineVersion = {
+  version: number;
+  /**
+   * As an ISO 8601 string, null without one
+   */
+  onlineDate: string | null;
+  /**
+   * As an ISO 8601 string, null without one
+   */
+  offlineDate: string | null;
+  /**
+   * When the version was published to stage, as an ISO 8601 string
+   */
+  publishedDate: string;
+  channels: string[];
+  tags: string[];
+  /**
+   * Every locale of the version
+   */
+  locales: string[];
+};
+
+/**
+ * This type represent a content on the timeline, with each of its versions asked for
+ */
+export type TimelineItem = {
+  contentId: ContentId;
+  /**
+   * The pending version's when there is one, as `name` and `externalIdentifier`
+   */
+  publicId: string;
+  name: string;
+  externalIdentifier: string | null;
+  /**
+   * The content definition mnemonic id
+   */
+  definition: string;
+  /**
+   * The content repository mnemonic id
+   */
+  repository: string;
+  /**
+   * null for a content only in stage
+   */
+  live: TimelineVersion | null;
+  /**
+   * null for a content whose staged version is the live one
+   */
+  pending: TimelineVersion | null;
+};
+
+/**
+ * This type represent, per value, how many of the filtered contents have it. A content with two versions
+ * counts once per value either has
+ */
+export type TimelineFacets = {
+  definitions: { [mnemonicId: string]: number };
+  repositories: { [mnemonicId: string]: number };
+  channels: { [channel: string]: number };
+  tags: { [tag: string]: number };
+  locales: { [locale: string]: number };
+};
+
+/**
+ * This type represent the response of a list timeline API request
+ */
+export type ListTimelineResponse = {
+  items: TimelineItem[];
+  total: number;
+  /**
+   * The contents with neither date, whether `undated` excludes them or not
+   */
+  undated: number;
+  /**
+   * Only when asked for
+   */
+  facets?: TimelineFacets;
+};
+
+/**
+ * This type represent the size of a timeline summary's buckets. A week starts on Monday
+ */
+export type TimelineBucket = "day" | "week" | "month";
+
+/**
+ * This type represent what a timeline summary counts: `live`, what delivery serves, or `afterRelease`,
+ * what it would serve were the staged versions promoted
+ */
+export type TimelineState = "live" | "afterRelease";
+
+/**
+ * This type represent the data needed to make a get timeline summary API request
+ */
+export type GetTimelineSummaryRequest = TimelineFilters & {
+  bucket: TimelineBucket;
+  /**
+   * An IANA time zone, `UTC` by default: buckets start at its midnights
+   */
+  timeZone?: string;
+  /**
+   * `live` by default
+   */
+  state?: TimelineState;
+};
+
+/**
+ * This type represent the counts of one bucket of a timeline summary
+ */
+export type TimelineBucketCount = {
+  /**
+   * The bucket's first day in the time zone, as `YYYY-MM-DD`
+   */
+  date: string;
+  /**
+   * The bucket's start, as an ISO 8601 string in UTC
+   */
+  from: string;
+  /**
+   * The bucket's end, as an ISO 8601 string in UTC
+   */
+  to: string;
+  /**
+   * The contents online at some point of the bucket
+   */
+  online: number;
+  /**
+   * The contents whose online date falls within the bucket
+   */
+  comingOnline: number;
+  /**
+   * The contents whose offline date falls within the bucket
+   */
+  goingOffline: number;
+};
+
+/**
+ * This type represent the response of a get timeline summary API request: one entry per bucket, from the
+ * one holding `from` to the one holding `to`
+ */
+export type GetTimelineSummaryResponse = TimelineBucketCount[];
+
+/**
+ * Thin enum represent the error types of the timeline API requests. Each is the `type` of a
+ * `RequestError`, whose `details` is a [[TimelineError]]
+ */
+export enum TimelineErrorTypes {
+  /**
+   * `to` before `from`, a range over 400 days, or an unknown time zone
+   */
+  invalidTimelineQuery = "InvalidTimelineQuery",
+  /**
+   * The query took over 4 seconds and was stopped: narrow the range or the filters
+   */
+  timelineTooSlow = "TimelineTooSlow",
+}
+
+/**
+ * This type represent the `details` of a `RequestError` whose `type` is one of [[TimelineErrorTypes]]
+ */
+export type TimelineError = { type: TimelineErrorTypes; message: string };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contentchef/contentchef-types",
-  "version": "11.2.0-alpha.3",
+  "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": "2c7d06e055598e85bcd776844dc388f0633009a3"
+  "gitHead": "ccaa9d0ae10d67701cf34df7ec127c3c40fefae4"
 }