@contentchef/contentchef-types 11.1.1 → 11.2.0-alpha.0

package/dist/api/Component.d.ts

@@ -247,6 +247,13 @@ export type AdoptComponentRequest = {
     definitionId: ContentDefinitionId;
     mnemonicId: string;
     version: number;
+    /**
+     * Fields of the fragment named otherwise in the version: `from` a field of the fragment the version
+     * does not have, `to` a field of the version the fragment does not have, each name in one rename at
+     * most. Unlike a version's rename, one may change the type: the values that do not fit the field
+     * they move to are set aside
+     */
+    renames?: ComponentRename[];
 };
 /**
  * This type represent the response of an adopt component API request: the definition, as the get
@@ -276,8 +283,73 @@ export type PromoteComponentResponse = {
     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]]
+ * This type represent one side of a compare component fields API request: a definition's fragment, own
+ * or a component's, fields of a definition's root, a component version, the latest by default, or
+ * fields saved nowhere, validated as a component draft
+ */
+export type ComponentCompareSide = {
+    definitionId: ContentDefinitionId;
+    fragment: string;
+} | {
+    definitionId: ContentDefinitionId;
+    fields: string[];
+} | {
+    component: string;
+    version?: number;
+} | {
+    shape: ComponentFragment;
+};
+/**
+ * This type represent the data needed to make a compare component fields API request: how `from`'s
+ * fields compare with `to`'s, as an adoption from one to the other would judge them, reading no content
+ */
+export type CompareComponentFieldsRequest = {
+    from: ComponentCompareSide;
+    to: ComponentCompareSide;
+    /**
+     * Fields of `from` that `to` names otherwise, as in [[AdoptComponentRequest.renames]]
+     */
+    renames?: ComponentRename[];
+};
+/**
+ * This type represent what becomes of one field of `from`
+ */
+export type ComparedField = {
+    field: string;
+    /**
+     * The field of `to` it becomes, null when removed
+     */
+    to: string | null;
+    outcome: 'kept' | 'renamed' | 'changed' | 'removed';
+    /**
+     * For a changed field, what differs, keyed by attribute or `constraints.<key>`: its type, a tighter
+     * limit, a list of values (by code)
+     */
+    changes?: {
+        [attribute: string]: {
+            from: unknown;
+            to: unknown;
+        };
+    };
+};
+/**
+ * This type represent the response of a compare component fields API request
+ */
+export type CompareComponentFieldsResponse = {
+    fields: ComparedField[];
+    /**
+     * The fields of `to` no field of `from` reaches
+     */
+    added: string[];
+    /**
+     * What the adopt component API request would refuse, renames included
+     */
+    violations: ComponentVersionViolation[];
+};
+/**
+ * Thin enum represent the error types of the component API requests, and of the content definition and
+ * content ones the components bring. Each is the `type` of a `RequestError`, whose `details` is a
+ * [[ComponentError]]
  */
 export declare enum ComponentErrorTypes {
     componentNotFound = "ComponentNotFound",
@@ -294,7 +366,10 @@ export declare enum ComponentErrorTypes {
     noFragmentToPromote = "NoFragmentToPromote",
     definitionMigrating = "DefinitionMigrating",
     oneMigrationPerSave = "OneMigrationPerSave",
-    migrationPreviewNotFound = "MigrationPreviewNotFound"
+    migrationPreviewNotFound = "MigrationPreviewNotFound",
+    invalidComparison = "InvalidComparison",
+    fieldNotFound = "FieldNotFound",
+    profileTooLarge = "ProfileTooLarge"
 }
 /**
  * Thin enum represent the codes of a [[ComponentVersionViolation]]
@@ -390,7 +465,19 @@ export type ComponentError = ComponentErrorOf<ComponentErrorTypes.componentNotFo
     mnemonicIds: string[];
 }> | ComponentErrorOf<ComponentErrorTypes.migrationPreviewNotFound, {
     id: MigrationPreviewId;
-}>;
+}>
+/**
+ * A side of a compare component fields API request that is none of the kinds it takes
+ */
+ | ComponentErrorOf<ComponentErrorTypes.invalidComparison>
+/**
+ * A fragment or field the request names that the definition does not have
+ */
+ | ComponentErrorOf<ComponentErrorTypes.fieldNotFound>
+/**
+ * A profile content values API request whose queries outlasted their time: ask for fewer fields
+ */
+ | ComponentErrorOf<ComponentErrorTypes.profileTooLarge>;
 /**
  * This type represent where a definition's contents stand, as the get content definition, update content
  * definition and get migration API requests answer it
@@ -487,6 +574,7 @@ export type MigrationPreviewRequest = {
     adopt: {
         mnemonicId: string;
         version: number;
+        renames?: ComponentRename[];
     };
 };
 /**

package/dist/api/Component.js

@@ -7,8 +7,9 @@ exports.ComponentVersionViolationCodes = exports.ComponentErrorTypes = exports.C
  */
 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]]
+ * Thin enum represent the error types of the component API requests, and of the content definition and
+ * content ones the components bring. Each is the `type` of a `RequestError`, whose `details` is a
+ * [[ComponentError]]
  */
 var ComponentErrorTypes;
 (function (ComponentErrorTypes) {
@@ -27,6 +28,9 @@ var ComponentErrorTypes;
     ComponentErrorTypes["definitionMigrating"] = "DefinitionMigrating";
     ComponentErrorTypes["oneMigrationPerSave"] = "OneMigrationPerSave";
     ComponentErrorTypes["migrationPreviewNotFound"] = "MigrationPreviewNotFound";
+    ComponentErrorTypes["invalidComparison"] = "InvalidComparison";
+    ComponentErrorTypes["fieldNotFound"] = "FieldNotFound";
+    ComponentErrorTypes["profileTooLarge"] = "ProfileTooLarge";
 })(ComponentErrorTypes || (exports.ComponentErrorTypes = ComponentErrorTypes = {}));
 /**
  * Thin enum represent the codes of a [[ComponentVersionViolation]]

package/dist/api/Content.d.ts

@@ -383,7 +383,42 @@ export type ListContentsFilters = {
      * true lists only the contents holding values a migration set aside
      */
     setAside?: boolean;
+    /**
+     * This filter is used to search the contents of one definition holding a value of a kind in one field
+     */
+    field?: ListContentsFieldFilter;
 };
+/**
+ * This type represent the JSON type of a value in a content payload
+ */
+export type JsonValueType = "string" | "number" | "boolean" | "object" | "array";
+/**
+ * This type represent a filter on the values of one field: the contents of the definition where an
+ * instance of its root, or of the fragment wherever the definition places it, holds an empty value
+ * (missing, null, "", [] or {}), a value, a text longer than `length`, or a value not of `type`. With
+ * `locale`, where that locale's translation of the field does. A field the definition does not have is
+ * refused with `FieldNotFound`
+ */
+export type ListContentsFieldFilter = {
+    definitionId: ContentDefinitionId;
+    /**
+     * The fragment holding the field, the definition's root without it
+     */
+    fragment?: string;
+    /**
+     * The field name
+     */
+    name: string;
+    locale?: string;
+} & ({
+    is: "empty" | "notEmpty";
+} | {
+    is: "longerThan";
+    length: number;
+} | {
+    is: "notType";
+    type: JsonValueType;
+});
 /**
  * This type represent the data needed to make a list content API request
  */
@@ -873,3 +908,82 @@ export type AnalysePersonalizedRulesResponse = {
      */
     fields: PersonalizedFieldCoverage[];
 };
+/**
+ * This type represent the data needed to make a profile content values API request: what the
+ * definition's contents, archived ones included, hold in the fields of its root or of one of its
+ * fragments wherever the definition places it. For investigating, never for a form
+ */
+export type ProfileContentValuesRequest = {
+    definitionId: ContentDefinitionId;
+    /**
+     * The fragment to profile, the definition's root without it
+     */
+    fragment?: string;
+    /**
+     * The fields to profile, from 1 to 100, all of them without it
+     */
+    fields?: string[];
+};
+/**
+ * This type represent what the contents hold in one field
+ */
+export type FieldValuesProfile = {
+    name: string;
+    type: string;
+    /**
+     * The objects of the place, each holding the field or not
+     */
+    instances: number;
+    values: number;
+    /**
+     * The instances holding null, "", [], {} or nothing
+     */
+    empty: number;
+    /**
+     * The contents holding at least one value
+     */
+    contents: number;
+    /**
+     * The values by JSON type
+     */
+    types: {
+        [type in JsonValueType]?: number;
+    };
+    /**
+     * The lengths of the text values, null without any
+     */
+    length: {
+        min: number;
+        max: number;
+        p95: number;
+    } | null;
+    /**
+     * The translations holding text, by locale, null for a field that is not translatable
+     */
+    translations: {
+        [locale: string]: number;
+    } | null;
+};
+/**
+ * This type represent the response of a profile content values API request. A fragment nested in itself
+ * is followed one level deep, and a profile whose queries outlast their time is refused with
+ * `ProfileTooLarge`
+ */
+export type ProfileContentValuesResponse = {
+    definitionId: ContentDefinitionId;
+    fragment: string | null;
+    contents: {
+        total: number;
+        archived: number;
+    };
+    /**
+     * Where the fragment sits, as `blocks[]<seo>` (an array of `oneFragmentOf` holding it) or
+     * `hero.variants[]` (a personalized field's variants), empty for the root
+     */
+    placements: string[];
+    /**
+     * The objects of the place found in the contents
+     */
+    instances: number;
+    fields: FieldValuesProfile[];
+};

package/lib/api/Component.ts

@@ -270,6 +270,13 @@ export type AdoptComponentRequest = {
     definitionId: ContentDefinitionId;
     mnemonicId: string;
     version: number;
+    /**
+     * Fields of the fragment named otherwise in the version: `from` a field of the fragment the version
+     * does not have, `to` a field of the version the fragment does not have, each name in one rename at
+     * most. Unlike a version's rename, one may change the type: the values that do not fit the field
+     * they move to are set aside
+     */
+    renames?: ComponentRename[];
 };
 
 /**
@@ -303,8 +310,65 @@ export type PromoteComponentResponse = {
 };
 
 /**
- * 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]]
+ * This type represent one side of a compare component fields API request: a definition's fragment, own
+ * or a component's, fields of a definition's root, a component version, the latest by default, or
+ * fields saved nowhere, validated as a component draft
+ */
+export type ComponentCompareSide =
+    | { definitionId: ContentDefinitionId; fragment: string }
+    | { definitionId: ContentDefinitionId; fields: string[] }
+    | { component: string; version?: number }
+    | { shape: ComponentFragment };
+
+/**
+ * This type represent the data needed to make a compare component fields API request: how `from`'s
+ * fields compare with `to`'s, as an adoption from one to the other would judge them, reading no content
+ */
+export type CompareComponentFieldsRequest = {
+    from: ComponentCompareSide;
+    to: ComponentCompareSide;
+    /**
+     * Fields of `from` that `to` names otherwise, as in [[AdoptComponentRequest.renames]]
+     */
+    renames?: ComponentRename[];
+};
+
+/**
+ * This type represent what becomes of one field of `from`
+ */
+export type ComparedField = {
+    field: string;
+    /**
+     * The field of `to` it becomes, null when removed
+     */
+    to: string | null;
+    outcome: 'kept' | 'renamed' | 'changed' | 'removed';
+    /**
+     * For a changed field, what differs, keyed by attribute or `constraints.<key>`: its type, a tighter
+     * limit, a list of values (by code)
+     */
+    changes?: { [attribute: string]: { from: unknown; to: unknown } };
+};
+
+/**
+ * This type represent the response of a compare component fields API request
+ */
+export type CompareComponentFieldsResponse = {
+    fields: ComparedField[];
+    /**
+     * The fields of `to` no field of `from` reaches
+     */
+    added: string[];
+    /**
+     * What the adopt component API request would refuse, renames included
+     */
+    violations: ComponentVersionViolation[];
+};
+
+/**
+ * Thin enum represent the error types of the component API requests, and of the content definition and
+ * content ones the components bring. Each is the `type` of a `RequestError`, whose `details` is a
+ * [[ComponentError]]
  */
 export enum ComponentErrorTypes {
     componentNotFound = 'ComponentNotFound',
@@ -321,7 +385,10 @@ export enum ComponentErrorTypes {
     noFragmentToPromote = 'NoFragmentToPromote',
     definitionMigrating = 'DefinitionMigrating',
     oneMigrationPerSave = 'OneMigrationPerSave',
-    migrationPreviewNotFound = 'MigrationPreviewNotFound'
+    migrationPreviewNotFound = 'MigrationPreviewNotFound',
+    invalidComparison = 'InvalidComparison',
+    fieldNotFound = 'FieldNotFound',
+    profileTooLarge = 'ProfileTooLarge'
 }
 
 /**
@@ -406,7 +473,19 @@ export type ComponentError =
      * has finished
      */
     | ComponentErrorOf<ComponentErrorTypes.oneMigrationPerSave, { mnemonicIds: string[] }>
-    | ComponentErrorOf<ComponentErrorTypes.migrationPreviewNotFound, { id: MigrationPreviewId }>;
+    | ComponentErrorOf<ComponentErrorTypes.migrationPreviewNotFound, { id: MigrationPreviewId }>
+    /**
+     * A side of a compare component fields API request that is none of the kinds it takes
+     */
+    | ComponentErrorOf<ComponentErrorTypes.invalidComparison>
+    /**
+     * A fragment or field the request names that the definition does not have
+     */
+    | ComponentErrorOf<ComponentErrorTypes.fieldNotFound>
+    /**
+     * A profile content values API request whose queries outlasted their time: ask for fewer fields
+     */
+    | ComponentErrorOf<ComponentErrorTypes.profileTooLarge>;
 
 /**
  * This type represent where a definition's contents stand, as the get content definition, update content
@@ -501,7 +580,7 @@ export type MigrationPreviewId = number;
  */
 export type MigrationPreviewRequest =
     | { id: ContentDefinitionId; schema: ContentDefinitionSchemaInput }
-    | { id: ContentDefinitionId; adopt: { mnemonicId: string; version: number } };
+    | { id: ContentDefinitionId; adopt: { mnemonicId: string; version: number; renames?: ComponentRename[] } };
 
 /**
  * This type represent the response of a migration preview API request: the preview's id, or null when

package/lib/api/Content.ts

@@ -420,8 +420,42 @@ export type ListContentsFilters = {
    * true lists only the contents holding values a migration set aside
    */
   setAside?: boolean;
+
+  /**
+   * This filter is used to search the contents of one definition holding a value of a kind in one field
+   */
+  field?: ListContentsFieldFilter;
 };
 
+/**
+ * This type represent the JSON type of a value in a content payload
+ */
+export type JsonValueType = "string" | "number" | "boolean" | "object" | "array";
+
+/**
+ * This type represent a filter on the values of one field: the contents of the definition where an
+ * instance of its root, or of the fragment wherever the definition places it, holds an empty value
+ * (missing, null, "", [] or {}), a value, a text longer than `length`, or a value not of `type`. With
+ * `locale`, where that locale's translation of the field does. A field the definition does not have is
+ * refused with `FieldNotFound`
+ */
+export type ListContentsFieldFilter = {
+  definitionId: ContentDefinitionId;
+  /**
+   * The fragment holding the field, the definition's root without it
+   */
+  fragment?: string;
+  /**
+   * The field name
+   */
+  name: string;
+  locale?: string;
+} & (
+  | { is: "empty" | "notEmpty" }
+  | { is: "longerThan"; length: number }
+  | { is: "notType"; type: JsonValueType }
+);
+
 /**
  * This type represent the data needed to make a list content API request
  */
@@ -952,3 +986,74 @@ export type AnalysePersonalizedRulesResponse = {
    */
   fields: PersonalizedFieldCoverage[];
 };
+
+/**
+ * This type represent the data needed to make a profile content values API request: what the
+ * definition's contents, archived ones included, hold in the fields of its root or of one of its
+ * fragments wherever the definition places it. For investigating, never for a form
+ */
+export type ProfileContentValuesRequest = {
+  definitionId: ContentDefinitionId;
+  /**
+   * The fragment to profile, the definition's root without it
+   */
+  fragment?: string;
+  /**
+   * The fields to profile, from 1 to 100, all of them without it
+   */
+  fields?: string[];
+};
+
+/**
+ * This type represent what the contents hold in one field
+ */
+export type FieldValuesProfile = {
+  name: string;
+  type: string;
+  /**
+   * The objects of the place, each holding the field or not
+   */
+  instances: number;
+  values: number;
+  /**
+   * The instances holding null, "", [], {} or nothing
+   */
+  empty: number;
+  /**
+   * The contents holding at least one value
+   */
+  contents: number;
+  /**
+   * The values by JSON type
+   */
+  types: { [type in JsonValueType]?: number };
+  /**
+   * The lengths of the text values, null without any
+   */
+  length: { min: number; max: number; p95: number } | null;
+  /**
+   * The translations holding text, by locale, null for a field that is not translatable
+   */
+  translations: { [locale: string]: number } | null;
+};
+
+/**
+ * This type represent the response of a profile content values API request. A fragment nested in itself
+ * is followed one level deep, and a profile whose queries outlast their time is refused with
+ * `ProfileTooLarge`
+ */
+export type ProfileContentValuesResponse = {
+  definitionId: ContentDefinitionId;
+  fragment: string | null;
+  contents: { total: number; archived: number };
+  /**
+   * Where the fragment sits, as `blocks[]<seo>` (an array of `oneFragmentOf` holding it) or
+   * `hero.variants[]` (a personalized field's variants), empty for the root
+   */
+  placements: string[];
+  /**
+   * The objects of the place found in the contents
+   */
+  instances: number;
+  fields: FieldValuesProfile[];
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contentchef/contentchef-types",
-  "version": "11.1.1",
+  "version": "11.2.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": "8ea4c3670efedc53c388f679bd4b3c859f7a066a"
+  "gitHead": "30ca15f956b396cce7e0db037e836b79406278cf"
 }