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

package/dist/api/Component.d.ts

@@ -0,0 +1,574 @@
+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 declare const COMPONENT_NAME_PATTERN: RegExp;
+/**
+ * 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 declare 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 declare 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;
+export {};

package/dist/api/Component.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ComponentVersionViolationCodes = exports.ComponentErrorTypes = exports.COMPONENT_NAME_PATTERN = void 0;
+/**
+ * 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
+ */
+exports.COMPONENT_NAME_PATTERN = /^[a-zA-Z0-9_]+$/;
+/**
+ * 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]]
+ */
+var ComponentErrorTypes;
+(function (ComponentErrorTypes) {
+    ComponentErrorTypes["componentNotFound"] = "ComponentNotFound";
+    ComponentErrorTypes["componentVersionNotFound"] = "ComponentVersionNotFound";
+    ComponentErrorTypes["failedComponentValidation"] = "FailedComponentValidation";
+    ComponentErrorTypes["componentVersionRefused"] = "ComponentVersionRefused";
+    ComponentErrorTypes["nothingToPublish"] = "NothingToPublish";
+    ComponentErrorTypes["mnemonicIdNotUnique"] = "MnemonicIdNotUnique";
+    ComponentErrorTypes["managedFragmentEdited"] = "ManagedFragmentEdited";
+    ComponentErrorTypes["componentArchived"] = "ComponentArchived";
+    ComponentErrorTypes["componentAdoptionRequired"] = "ComponentAdoptionRequired";
+    ComponentErrorTypes["componentDowngradeRefused"] = "ComponentDowngradeRefused";
+    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]]
+ */
+var ComponentVersionViolationCodes;
+(function (ComponentVersionViolationCodes) {
+    /**
+     * An added field, or one whose type changed, must be optional
+     */
+    ComponentVersionViolationCodes["requiredField"] = "component.requiredField";
+    /**
+     * An added field, or one whose type changed, can be neither compact nor a facet
+     */
+    ComponentVersionViolationCodes["compactOrFacet"] = "component.compactOrFacet";
+    /**
+     * 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
      */