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

package/dist/api/Component.d.ts

@@ -0,0 +1,382 @@
+import { AuthorResponse } from './Author';
+import { PagedListResponse } from './common';
+import { AttributeViolation, ContentDefinitionId, GetContentDefinitionResponse, SchemaFieldViolationsErrors } from './ContentDefinition';
+import { 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 field names, by what happened to them between two versions of a fragment.
+ * A field whose type changed is `changed`
+ */
+export type FieldChanges = {
+    added: string[];
+    removed: string[];
+    changed: string[];
+};
+/**
+ * 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;
+};
+/**
+ * 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",
+    componentUpgradeBlocked = "ComponentUpgradeBlocked",
+    noFragmentToAdopt = "NoFragmentToAdopt",
+    noFragmentToPromote = "NoFragmentToPromote"
+}
+/**
+ * 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"
+}
+/**
+ * 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;
+};
+/**
+ * This type represent a field an upgrade removes or changes while contents hold a value in it
+ */
+export type ComponentUpgradeBlockingField = {
+    field: string;
+    /**
+     * How many contents, archived ones and translations included, hold a value in the field
+     */
+    contents: number;
+    /**
+     * Up to 20 of their content ids
+     */
+    examples: number[];
+};
+type ComponentErrorOf<T extends ComponentErrorTypes, D = {}> = {
+    type: T;
+    message: string;
+} & D;
+/**
+ * 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.componentUpgradeBlocked, {
+    fragment: string;
+    mnemonicId: string;
+    /**
+     * Null when the definition's own fragment is adopted
+     */
+    from: number | null;
+    to: number;
+    fields: ComponentUpgradeBlockingField[];
+}> | ComponentErrorOf<ComponentErrorTypes.noFragmentToAdopt, {
+    fragment: string;
+}> | ComponentErrorOf<ComponentErrorTypes.noFragmentToPromote, {
+    fragment: string;
+}>;
+export {};

package/dist/api/Component.js

@@ -0,0 +1,46 @@
+"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["componentUpgradeBlocked"] = "ComponentUpgradeBlocked";
+    ComponentErrorTypes["noFragmentToAdopt"] = "NoFragmentToAdopt";
+    ComponentErrorTypes["noFragmentToPromote"] = "NoFragmentToPromote";
+})(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";
+})(ComponentVersionViolationCodes || (exports.ComponentVersionViolationCodes = ComponentVersionViolationCodes = {}));

package/dist/api/ContentDefinition.d.ts

@@ -1,6 +1,7 @@
 import { AuthorResponse } from './Author';
 import { PagedListResponse } from './common';
-import { ContentDefinitionSchema, Field, I18NDictionary } from './ContentDefinitionSchema';
+import { FieldChanges } from './Component';
+import { ComponentMarker, ContentDefinitionSchema, ContentDefinitionSchemaInput, Field, I18NDictionary } from './ContentDefinitionSchema';
 import { Extension } from './Extension';
 /**
  * This type represent the unique content definition id type
@@ -100,7 +101,7 @@ export type CreateContentDefinitionRequest = {
     /**
      * The content definition fields schema
      */
-    schema: ContentDefinitionSchema;
+    schema: ContentDefinitionSchemaInput;
     /**
      * will bypass content definition mnemonicId validation for every linked-content field
      */
@@ -125,7 +126,7 @@ export type UpdateContentDefinitionRequest = {
     /**
      * The content definition fields schema
      */
-    schema: ContentDefinitionSchema;
+    schema: ContentDefinitionSchemaInput;
     /**
      * will bypass content definition mnemonicId validation for every linked-content field
      */
@@ -175,6 +176,29 @@ export type ContentDefinitionResponse = {
      * Valued with paths to each array or null if definition is legacy
      */
     trackableArrayFields?: ArrayField[] | null;
+    /**
+     * The components the definition's managed fragments copy, one per component
+     */
+    components: ComponentMarker[];
+};
+/**
+ * This type represent one component a definition uses, as the get content definition API request
+ * describes it
+ */
+export type DefinitionComponent = ComponentMarker & {
+    /**
+     * The component latest version
+     */
+    latestVersion: number;
+    /**
+     * The archived status of the component
+     */
+    archived: boolean;
+    /**
+     * What upgrading from `version` to `latestVersion` would add, remove and change, all empty when up
+     * to date. Whether the upgrade would be blocked by the contents is only known by trying it
+     */
+    changes: FieldChanges;
 };
 /**
  * This type represent the response of a create content definition API request
@@ -187,7 +211,12 @@ export type UpdateContentDefinitionResponse = ContentDefinitionResponse;
 /**
  * This type represent the response of a get content definition API request
  */
-export type GetContentDefinitionResponse = ContentDefinitionResponse | undefined;
+export type GetContentDefinitionResponse = (Omit<ContentDefinitionResponse, 'components'> & {
+    /**
+     * The components the definition uses, each with its latest version and what upgrading to it changes
+     */
+    components: DefinitionComponent[];
+}) | undefined;
 /**
  * This type represent the data needed to make a validate definition field API request
  */
@@ -389,5 +418,8 @@ export declare enum SchemaFieldViolationCodes {
     translatableNotAllowed = "translatableNotAllowed",
     invalidEnumValue = "invalidEnumValue",
     compactCannotBeNested = "compactCannotBeNested",
-    variantTypeNotAllowed = "variantTypeNotAllowed"
+    variantTypeNotAllowed = "variantTypeNotAllowed",
+    componentArchived = "componentArchived",
+    componentNotPublished = "componentNotPublished",
+    invalidComponentMarker = "invalidComponentMarker"
 }

package/dist/api/ContentDefinition.js

@@ -46,4 +46,7 @@ var SchemaFieldViolationCodes;
     SchemaFieldViolationCodes["invalidEnumValue"] = "invalidEnumValue";
     SchemaFieldViolationCodes["compactCannotBeNested"] = "compactCannotBeNested";
     SchemaFieldViolationCodes["variantTypeNotAllowed"] = "variantTypeNotAllowed";
+    SchemaFieldViolationCodes["componentArchived"] = "componentArchived";
+    SchemaFieldViolationCodes["componentNotPublished"] = "componentNotPublished";
+    SchemaFieldViolationCodes["invalidComponentMarker"] = "invalidComponentMarker";
 })(SchemaFieldViolationCodes || (exports.SchemaFieldViolationCodes = SchemaFieldViolationCodes = {}));

package/dist/api/ContentDefinitionSchema.d.ts

@@ -71,6 +71,43 @@ export type FragmentDefinition = {
      * The friendly labels of the fragment
      */
     labels?: I18NDictionary;
+    /**
+     * Set on a managed fragment: a copy of a component version, keyed by the component's mnemonic id,
+     * that the backend writes and nobody edits by hand. Saving a definition with the marker alone has
+     * the backend fill in labels and fields, and saving it with a later `version` upgrades the fragment
+     */
+    component?: ComponentMarker;
+};
+/**
+ * This type represent a content definition schema as the create and update content definition API
+ * requests take it, whose managed fragments may leave out their labels and fields
+ */
+export type ContentDefinitionSchemaInput = Omit<ContentDefinitionSchema, 'fragments'> & {
+    fragments: {
+        [name: string]: FragmentDefinition | ManagedFragmentInput;
+    };
+};
+/**
+ * This type represent a managed fragment as a definition save may send it: labels and fields left out
+ * are filled in from the component version, and labels and fields sent must be the version's
+ */
+export type ManagedFragmentInput = {
+    component: ComponentMarker;
+    labels?: I18NDictionary;
+    fields?: Field[];
+};
+/**
+ * This type represent the marker of a managed fragment, naming the component and the version it copies
+ */
+export type ComponentMarker = {
+    /**
+     * The component mnemonic id, which is also the fragment's key in the schema
+     */
+    mnemonicId: string;
+    /**
+     * The component version the fragment copies
+     */
+    version: number;
 };
 /**
  * This type represent the base model of a schema field

package/dist/api/index.d.ts

@@ -3,6 +3,7 @@ export * from './AuditLog';
 export * from './Author';
 export * from './Channel';
 export * from './Content';
+export * from './Component';
 export * from './ContentDefinition';
 export * from './ContentDefinitionSchema';
 export * from './ContentExportImport';

package/dist/api/index.js

@@ -19,6 +19,7 @@ __exportStar(require("./AuditLog"), exports);
 __exportStar(require("./Author"), exports);
 __exportStar(require("./Channel"), exports);
 __exportStar(require("./Content"), exports);
+__exportStar(require("./Component"), exports);
 __exportStar(require("./ContentDefinition"), exports);
 __exportStar(require("./ContentDefinitionSchema"), exports);
 __exportStar(require("./ContentExportImport"), exports);

package/lib/api/Component.ts

@@ -0,0 +1,401 @@
+import { AuthorResponse } from './Author';
+import { PagedListResponse } from './common';
+import {
+    AttributeViolation,
+    ContentDefinitionId,
+    GetContentDefinitionResponse,
+    SchemaFieldViolationsErrors
+} from './ContentDefinition';
+import { 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 field names, by what happened to them between two versions of a fragment.
+ * A field whose type changed is `changed`
+ */
+export type FieldChanges = {
+    added: string[];
+    removed: string[];
+    changed: string[];
+};
+
+/**
+ * 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;
+};
+
+/**
+ * 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',
+    componentUpgradeBlocked = 'ComponentUpgradeBlocked',
+    noFragmentToAdopt = 'NoFragmentToAdopt',
+    noFragmentToPromote = 'NoFragmentToPromote'
+}
+
+/**
+ * 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'
+}
+
+/**
+ * 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;
+};
+
+/**
+ * This type represent a field an upgrade removes or changes while contents hold a value in it
+ */
+export type ComponentUpgradeBlockingField = {
+    field: string;
+    /**
+     * How many contents, archived ones and translations included, hold a value in the field
+     */
+    contents: number;
+    /**
+     * Up to 20 of their content ids
+     */
+    examples: number[];
+};
+
+type ComponentErrorOf<T extends ComponentErrorTypes, D = {}> = { type: T; message: string } & D;
+
+/**
+ * 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.componentUpgradeBlocked, {
+        fragment: string;
+        mnemonicId: string;
+        /**
+         * Null when the definition's own fragment is adopted
+         */
+        from: number | null;
+        to: number;
+        fields: ComponentUpgradeBlockingField[];
+    }>
+    | ComponentErrorOf<ComponentErrorTypes.noFragmentToAdopt, { fragment: string }>
+    | ComponentErrorOf<ComponentErrorTypes.noFragmentToPromote, { fragment: string }>;

package/lib/api/ContentDefinition.ts

@@ -1,6 +1,7 @@
 import { AuthorResponse } from './Author';
 import { PagedListResponse } from './common';
-import { ContentDefinitionSchema, Field, I18NDictionary } from './ContentDefinitionSchema';
+import { FieldChanges } from './Component';
+import { ComponentMarker, ContentDefinitionSchema, ContentDefinitionSchemaInput, Field, I18NDictionary } from './ContentDefinitionSchema';
 import { Extension } from './Extension';
 
 /**
@@ -108,7 +109,7 @@ export type CreateContentDefinitionRequest = {
     /**
      * The content definition fields schema
      */
-    schema: ContentDefinitionSchema;
+    schema: ContentDefinitionSchemaInput;
 
     /**
      * will bypass content definition mnemonicId validation for every linked-content field
@@ -135,7 +136,7 @@ export type UpdateContentDefinitionRequest = {
     /**
      * The content definition fields schema
      */
-    schema: ContentDefinitionSchema;
+    schema: ContentDefinitionSchemaInput;
 
     /**
      * will bypass content definition mnemonicId validation for every linked-content field
@@ -189,6 +190,31 @@ export type ContentDefinitionResponse = {
      * Valued with paths to each array or null if definition is legacy
      */
     trackableArrayFields?: ArrayField[] | null;
+
+    /**
+     * The components the definition's managed fragments copy, one per component
+     */
+    components: ComponentMarker[];
+};
+
+/**
+ * This type represent one component a definition uses, as the get content definition API request
+ * describes it
+ */
+export type DefinitionComponent = ComponentMarker & {
+    /**
+     * The component latest version
+     */
+    latestVersion: number;
+    /**
+     * The archived status of the component
+     */
+    archived: boolean;
+    /**
+     * What upgrading from `version` to `latestVersion` would add, remove and change, all empty when up
+     * to date. Whether the upgrade would be blocked by the contents is only known by trying it
+     */
+    changes: FieldChanges;
 };
 
 /**
@@ -202,7 +228,12 @@ export type UpdateContentDefinitionResponse = ContentDefinitionResponse;
 /**
  * This type represent the response of a get content definition API request
  */
-export type GetContentDefinitionResponse = ContentDefinitionResponse | undefined;
+export type GetContentDefinitionResponse = (Omit<ContentDefinitionResponse, 'components'> & {
+    /**
+     * The components the definition uses, each with its latest version and what upgrading to it changes
+     */
+    components: DefinitionComponent[];
+}) | undefined;
 
 /**
  * This type represent the data needed to make a validate definition field API request
@@ -416,5 +447,8 @@ export enum SchemaFieldViolationCodes {
     translatableNotAllowed = 'translatableNotAllowed',
     invalidEnumValue = 'invalidEnumValue',
     compactCannotBeNested = 'compactCannotBeNested',
-    variantTypeNotAllowed = 'variantTypeNotAllowed'
+    variantTypeNotAllowed = 'variantTypeNotAllowed',
+    componentArchived = 'componentArchived',
+    componentNotPublished = 'componentNotPublished',
+    invalidComponentMarker = 'invalidComponentMarker'
 }

package/lib/api/ContentDefinitionSchema.ts

@@ -76,6 +76,46 @@ export type FragmentDefinition = {
      * The friendly labels of the fragment
      */
     labels?: I18NDictionary;
+    /**
+     * Set on a managed fragment: a copy of a component version, keyed by the component's mnemonic id,
+     * that the backend writes and nobody edits by hand. Saving a definition with the marker alone has
+     * the backend fill in labels and fields, and saving it with a later `version` upgrades the fragment
+     */
+    component?: ComponentMarker;
+};
+
+/**
+ * This type represent a content definition schema as the create and update content definition API
+ * requests take it, whose managed fragments may leave out their labels and fields
+ */
+export type ContentDefinitionSchemaInput = Omit<ContentDefinitionSchema, 'fragments'> & {
+    fragments: {
+        [name: string]: FragmentDefinition | ManagedFragmentInput;
+    };
+};
+
+/**
+ * This type represent a managed fragment as a definition save may send it: labels and fields left out
+ * are filled in from the component version, and labels and fields sent must be the version's
+ */
+export type ManagedFragmentInput = {
+    component: ComponentMarker;
+    labels?: I18NDictionary;
+    fields?: Field[];
+};
+
+/**
+ * This type represent the marker of a managed fragment, naming the component and the version it copies
+ */
+export type ComponentMarker = {
+    /**
+     * The component mnemonic id, which is also the fragment's key in the schema
+     */
+    mnemonicId: string;
+    /**
+     * The component version the fragment copies
+     */
+    version: number;
 };
 
 /**

package/lib/api/index.ts

@@ -3,6 +3,7 @@ export * from './AuditLog';
 export * from './Author';
 export * from './Channel';
 export * from './Content';
+export * from './Component';
 export * from './ContentDefinition';
 export * from './ContentDefinitionSchema';
 export * from './ContentExportImport';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contentchef/contentchef-types",
-  "version": "11.0.0",
+  "version": "11.1.0-alpha.0",
   "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": "4590d085381430e5b56e98a2dabdf03911d05e3e"
+  "gitHead": "06b0724c9e74c0e2975a4af2917924010858759d"
 }