@contentchef/contentchef-types 11.0.0 → 11.1.0-alpha.1

package/lib/api/Component.ts

@@ -0,0 +1,592 @@
+import { AuthorResponse } from './Author';
+import { PagedListResponse } from './common';
+import {
+    AttributeViolation,
+    ContentDefinitionId,
+    GetContentDefinitionResponse,
+    SchemaFieldViolationsErrors
+} from './ContentDefinition';
+import { ContentDefinitionSchemaInput, Field, FragmentDefinition } from './ContentDefinitionSchema';
+
+/**
+ * The component unique id
+ */
+export type ComponentId = number;
+
+/**
+ * A component's mnemonicId must match this pattern. It becomes the fragment's name in every definition
+ * using the component, so it is unique in the space, case insensitively, and never changes
+ */
+export const COMPONENT_NAME_PATTERN = /^[a-zA-Z0-9_]+$/;
+
+/**
+ * This type represent the fragment a component defines: its fields and optionally its labels, nothing
+ * 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 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
+ */
+export type ComponentAuthor = Pick<AuthorResponse, 'authorId' | 'fullName'>;
+
+/**
+ * This type represent a published version of a component, which never changes
+ */
+export type ComponentVersion = ComponentFragment & {
+    /**
+     * The version number, from 1
+     */
+    version: number;
+    /**
+     * The changes from the version before. Version 1 lists every field as added
+     */
+    changes: FieldChanges;
+    /**
+     * The note given when publishing
+     */
+    note?: string;
+    publishedBy: ComponentAuthor;
+    publishedDate: Date;
+};
+
+/**
+ * This type represent a version of a component without its fragment
+ */
+export type ComponentVersionSummary = Omit<ComponentVersion, 'labels' | 'fields'>;
+
+/**
+ * This type represent a definition using a component
+ */
+export type ComponentUsedBy = {
+    definitionId: ContentDefinitionId;
+    definitionMnemonicId: string;
+    definitionName: string;
+    /**
+     * The component version the definition copies
+     */
+    version: number;
+};
+
+/**
+ * This type represent a component as the list components API request answers it
+ *
+ * A component is a fragment a space defines once, for any of its definitions to use. Publishing its
+ * draft makes its next version, and a definition moves to a newer version only when it is upgraded
+ */
+export type ComponentSummary = {
+    id: ComponentId;
+    /**
+     * The component mnemonic id, matching [[COMPONENT_NAME_PATTERN]]
+     */
+    mnemonicId: string;
+    name: string;
+    /**
+     * An archived component keeps working in the definitions using it, and cannot be added to another
+     * definition or component
+     */
+    archived: boolean;
+    /**
+     * The latest version, null until the first publish
+     */
+    latestVersion: number | null;
+    /**
+     * Whether the draft differs from the latest version, true before the first publish
+     */
+    draftChanged: boolean;
+    /**
+     * How many definitions use the component, and how many of those are on an older version
+     */
+    usage: { definitions: number; behind: number };
+};
+
+/**
+ * This type represent the model of a component, as every component API request but list answers it
+ */
+export type ComponentResponse = ComponentSummary & {
+    archivedDate: Date | null;
+    /**
+     * The fragment being edited
+     */
+    draft: ComponentFragment;
+    /**
+     * The version asked for, the latest by default, null before the first publish
+     */
+    version: ComponentVersion | null;
+    /**
+     * Every version, newest first
+     */
+    versions: ComponentVersionSummary[];
+    usedBy: ComponentUsedBy[];
+    createdDate: Date;
+    lastModifiedDate: Date;
+    author: ComponentAuthor;
+    latestContributor: ComponentAuthor;
+};
+
+/**
+ * This type represent all possible filters used to retrieve a list of components
+ */
+export type ListComponentsFilters = {
+    /**
+     * Matches the name or the mnemonic id, case insensitively, anywhere in it. At most 100 characters
+     */
+    name?: string;
+    /**
+     * Left out, the list holds both archived and not archived components
+     */
+    archived?: boolean;
+};
+
+/**
+ * This type represent the data needed to make a list components API request
+ */
+export type ListComponentsRequest = {
+    /**
+     * The number of components to skip, 0 by default
+     */
+    skip?: number;
+    /**
+     * The number of components to take, 10 by default and at most 100
+     */
+    take?: number;
+    filters?: ListComponentsFilters;
+};
+
+/**
+ * This type represent the response of a list components API request
+ */
+export type ListComponentsResponse = PagedListResponse<ComponentSummary>;
+
+/**
+ * This type represent the data needed to make a get component API request, by id or by mnemonic id
+ */
+export type GetComponentRequest = ({ id: ComponentId } | { mnemonicId: string }) & {
+    /**
+     * The version to answer with, the latest by default
+     */
+    version?: number;
+};
+
+/**
+ * This type represent the response of a get component API request
+ */
+export type GetComponentResponse = ComponentResponse;
+
+/**
+ * This type represent the data needed to make a create component API request
+ */
+export type CreateComponentRequest = {
+    /**
+     * The component mnemonic id, matching [[COMPONENT_NAME_PATTERN]]
+     */
+    mnemonicId: string;
+    name: string;
+    draft: ComponentFragment;
+};
+
+/**
+ * This type represent the response of a create component API request, with no version yet
+ */
+export type CreateComponentResponse = ComponentResponse;
+
+/**
+ * This type represent the data needed to make an update component API request. The name and the whole
+ * draft are replaced, and the last save wins
+ */
+export type UpdateComponentRequest = {
+    id: ComponentId;
+    name: string;
+    draft: ComponentFragment;
+};
+
+/**
+ * This type represent the response of an update component API request
+ */
+export type UpdateComponentResponse = ComponentResponse;
+
+/**
+ * This type represent the data needed to make a publish component API request
+ */
+export type PublishComponentRequest = {
+    id: ComponentId;
+    /**
+     * 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
+ * published
+ */
+export type PublishComponentResponse = ComponentResponse;
+
+/**
+ * This type represent the data needed to make a toggle archived component API request
+ */
+export type ToggleArchivedComponentRequest = {
+    id: ComponentId;
+    archived: boolean;
+};
+
+/**
+ * This type represent the response of a toggle archived component API request
+ */
+export type ToggleArchivedComponentResponse = ComponentResponse;
+
+/**
+ * This type represent the data needed to make an adopt component API request: the definition's own
+ * fragment named `mnemonicId` becomes the managed fragment of that component version
+ */
+export type AdoptComponentRequest = {
+    definitionId: ContentDefinitionId;
+    mnemonicId: string;
+    version: number;
+};
+
+/**
+ * This type represent the response of an adopt component API request: the definition, as the get
+ * content definition API request answers it
+ */
+export type AdoptComponentResponse = NonNullable<GetContentDefinitionResponse>;
+
+/**
+ * This type represent the data needed to make a promote component API request: the definition's own
+ * fragment becomes version 1 of a new component, whose mnemonic id is the fragment's name
+ */
+export type PromoteComponentRequest = {
+    definitionId: ContentDefinitionId;
+    fragment: string;
+    /**
+     * The component name, the fragment's name by default
+     */
+    name?: string;
+};
+
+/**
+ * This type represent the response of a promote component API request
+ */
+export type PromoteComponentResponse = {
+    component: ComponentResponse;
+    /**
+     * The definition, as the get content definition API request answers it
+     */
+    definition: NonNullable<GetContentDefinitionResponse>;
+};
+
+/**
+ * Thin enum represent the error types of the component API requests, and of the content definition
+ * ones using components. Each is the `type` of a `RequestError`, whose `details` is a [[ComponentError]]
+ */
+export enum ComponentErrorTypes {
+    componentNotFound = 'ComponentNotFound',
+    componentVersionNotFound = 'ComponentVersionNotFound',
+    failedComponentValidation = 'FailedComponentValidation',
+    componentVersionRefused = 'ComponentVersionRefused',
+    nothingToPublish = 'NothingToPublish',
+    mnemonicIdNotUnique = 'MnemonicIdNotUnique',
+    managedFragmentEdited = 'ManagedFragmentEdited',
+    componentArchived = 'ComponentArchived',
+    componentAdoptionRequired = 'ComponentAdoptionRequired',
+    componentDowngradeRefused = 'ComponentDowngradeRefused',
+    noFragmentToAdopt = 'NoFragmentToAdopt',
+    noFragmentToPromote = 'NoFragmentToPromote',
+    definitionMigrating = 'DefinitionMigrating',
+    oneMigrationPerSave = 'OneMigrationPerSave',
+    migrationPreviewNotFound = 'MigrationPreviewNotFound'
+}
+
+/**
+ * Thin enum represent the codes of a [[ComponentVersionViolation]]
+ */
+export enum ComponentVersionViolationCodes {
+    /**
+     * An added field, or one whose type changed, must be optional
+     */
+    requiredField = 'component.requiredField',
+    /**
+     * An added field, or one whose type changed, can be neither compact nor a facet
+     */
+    compactOrFacet = 'component.compactOrFacet',
+    /**
+     * A kept field may only change its texts, or loosen its constraints
+     */
+    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
+ */
+export type ComponentVersionViolation = {
+    field: string;
+    /**
+     * One of [[ComponentVersionViolationCodes]]
+     */
+    code: string;
+    message: string;
+};
+
+type ComponentErrorOf<T extends ComponentErrorTypes, D = {}> = { type: T; message: string } & D;
+
+/**
+ * This type represent the `details` of a `RequestError` whose `type` is one of [[ComponentErrorTypes]].
+ * Where present, `fragment` names the definition's fragment at fault
+ */
+export type ComponentError =
+    | ComponentErrorOf<ComponentErrorTypes.componentNotFound, { fragment?: string }>
+    | ComponentErrorOf<ComponentErrorTypes.componentVersionNotFound, { fragment?: string }>
+    | ComponentErrorOf<ComponentErrorTypes.failedComponentValidation, {
+        /**
+         * The draft's violations, as a definition fragment's. A component a field references while
+         * unpublished or archived is reported on its `constraints` as `componentNotPublished` or
+         * `componentArchived`, with the components at fault as affected attributes
+         */
+        validation: (SchemaFieldViolationsErrors | AttributeViolation)[];
+    }>
+    | ComponentErrorOf<ComponentErrorTypes.componentVersionRefused, {
+        violations: ComponentVersionViolation[];
+        /**
+         * Set by an adoption, naming the fragment it refuses
+         */
+        fragment?: string;
+    }>
+    | ComponentErrorOf<ComponentErrorTypes.nothingToPublish>
+    | ComponentErrorOf<ComponentErrorTypes.mnemonicIdNotUnique, {
+        mnemonicId: string;
+        /**
+         * Set by a promotion: every component mnemonic id already taken, whatever its case. Adopt
+         * those components instead
+         */
+        mnemonicIds?: string[];
+    }>
+    | ComponentErrorOf<ComponentErrorTypes.managedFragmentEdited, { fragment: string; mnemonicId: string; version: number }>
+    | ComponentErrorOf<ComponentErrorTypes.componentArchived, { fragment: string }>
+    | ComponentErrorOf<ComponentErrorTypes.componentAdoptionRequired, { fragment: string }>
+    | ComponentErrorOf<ComponentErrorTypes.componentDowngradeRefused, { fragment: string; mnemonicId: string; from: number; to: number }>
+    | 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 API request
+ * answers 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 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
    */