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

package/dist/api/Content.d.ts

@@ -4,7 +4,7 @@ import { PagedListResponse } from "./common";
 import { ContentDefinitionId, ContentDefinitionResponse } from "./ContentDefinition";
 import { SchemaTypeIds } from "./ContentDefinitionSchema";
 import { ContentRepositoryId, ContentRepositoryResponse } from "./ContentRepository";
-import { ContentTranslation, ContentTranslationStatus } from "./ContentTranslation";
+import { ContentTranslation, ContentTranslationStatus, FieldTranslation } from "./ContentTranslation";
 import { CoverageReport } from "./Audience";
 import { SetAsideResolution, SetAsideValue } from "./Component";
 /**
@@ -309,6 +309,11 @@ export type UpdateContentRequest = {
      * discarded
      */
     setAside?: SetAsideResolution[];
+    /**
+     * The version the person saw: a save made meanwhile is refused with `VersionMoved` rather than
+     * overwritten unseen
+     */
+    expectedVersion?: number;
 };
 /**
  * This type represent the data that can be used to filter a list of contents
@@ -987,3 +992,179 @@ export type ProfileContentValuesResponse = {
     instances: number;
     fields: FieldValuesProfile[];
 };
+/**
+ * This type represent the kind of a version in a content's history: what a publish published, or the
+ * content as a restore found it, unpublished edits and translations included
+ */
+export type ContentHistoryKind = "published" | "beforeRestore";
+/**
+ * This type represent the data needed to make a list content history API request
+ */
+export type ListContentHistoryRequest = {
+    contentId: ContentId;
+    /**
+     * 0 by default
+     */
+    skip?: number;
+    /**
+     * 20 by default, at most 100
+     */
+    take?: number;
+};
+/**
+ * This type represent a version in a content's history
+ */
+export type ContentHistoryEntry = {
+    kind: ContentHistoryKind;
+    /**
+     * The publishing request's id for a `published` version, the restore's for a `beforeRestore` one
+     */
+    id: number;
+    /**
+     * The content's version at the time
+     */
+    version: number;
+    date: Date;
+    /**
+     * Who published or restored, null when unknown
+     */
+    author: Pick<AuthorResponse, "authorId" | "fullName"> | null;
+};
+/**
+ * This type represent the response of a list content history API request: newest first, without the
+ * publishes that failed or are still running
+ */
+export type ListContentHistoryResponse = {
+    items: ContentHistoryEntry[];
+    total: number;
+};
+/**
+ * This type represent the data needed to make a get content history entry API request
+ */
+export type GetContentHistoryEntryRequest = {
+    contentId: ContentId;
+    kind: ContentHistoryKind;
+    id: number;
+};
+/**
+ * This type represent a violation of one constraint. `code` is one of [[ContentFieldViolationCodes]], or
+ * of the translation ones such as `translation.unknownField`
+ */
+export type ContentConstraintViolation = {
+    path?: string;
+    code: string;
+};
+/**
+ * This type represent the violations of one item of an array field, matched by its `itemKey`
+ */
+export type ContentArrayItemViolation = {
+    itemKey: string;
+    index: number;
+    violations: (ContentConstraintViolation | ContentFieldViolation)[];
+};
+/**
+ * This type represent the violations of one field of a payload, as an update content API request answers
+ * them in its `validation`
+ */
+export type ContentFieldViolation = {
+    field: string;
+    violations: (ContentConstraintViolation | ContentFieldViolation | ContentArrayItemViolation)[];
+};
+/**
+ * This type represent what keeps a version of the history from being restored, all empty when it can be
+ */
+export type RestoreViolations = {
+    payload: ContentFieldViolation[];
+    /**
+     * Per locale, the violations of its translated values
+     */
+    translations: {
+        locale: string;
+        violations: ContentConstraintViolation[];
+    }[];
+    /**
+     * Values a component migration since would set aside: the definition has no place for them any more
+     */
+    setAside: {
+        path: string;
+        reason: "removed" | "changed";
+    }[];
+};
+/**
+ * This type represent the response of a get content history entry API request: the version as a restore
+ * would write it, migrated to the definition as it is now, so it compares key by key with the get content
+ * API request's
+ */
+export type GetContentHistoryEntryResponse = ContentHistoryEntry & {
+    payload: object;
+    translations: {
+        locale: string;
+        translations: FieldTranslation[];
+    }[];
+    restorable: boolean;
+    violations: RestoreViolations;
+};
+/**
+ * This type represent the data needed to make a restore content API request
+ */
+export type RestoreContentRequest = {
+    contentId: ContentId;
+    kind: ContentHistoryKind;
+    id: number;
+    /**
+     * The version the person saw: a save made meanwhile is refused with `VersionMoved` rather than
+     * overwritten unseen
+     */
+    expectedVersion?: number;
+};
+/**
+ * This type represent the response of a restore content API request: the content as an update content
+ * API request answers it
+ */
+export type RestoreContentResponse = UpdateContentResponse;
+/**
+ * Thin enum represent the error types of the content API requests: the update content one, and the content
+ * history ones. Each is the `type` of a `RequestError`, whose `details` is a [[ContentError]]
+ */
+export declare enum ContentErrorTypes {
+    contentNotFound = "ContentNotFound",
+    failedContentPayloadValidation = "FailedContentPayloadValidation",
+    publicIdNotExclusiveToDefinitionId = "PublicIdNotExclusiveToDefinitionId",
+    versionMoved = "VersionMoved",
+    definitionMoved = "DefinitionMoved",
+    historyEntryNotFound = "HistoryEntryNotFound",
+    restoreRefused = "RestoreRefused"
+}
+type ContentErrorOf<T extends ContentErrorTypes, D = {}> = {
+    type: T;
+    message: string;
+} & D;
+/**
+ * This type represent the `details` of a `RequestError` whose `type` is one of [[ContentErrorTypes]]
+ */
+export type ContentError = ContentErrorOf<ContentErrorTypes.contentNotFound>
+/**
+ * The payload does not fit its definition, field by field; nothing was written
+ */
+ | ContentErrorOf<ContentErrorTypes.failedContentPayloadValidation, {
+    validation: ContentFieldViolation[];
+}>
+/**
+ * The public id is in use on a content of another definition
+ */
+ | ContentErrorOf<ContentErrorTypes.publicIdNotExclusiveToDefinitionId>
+/**
+ * The content is no longer at `expectedVersion`: read it again
+ */
+ | ContentErrorOf<ContentErrorTypes.versionMoved>
+/**
+ * The definition changed while the content was saved or restored: try again
+ */
+ | ContentErrorOf<ContentErrorTypes.definitionMoved> | ContentErrorOf<ContentErrorTypes.historyEntryNotFound>
+/**
+ * The version does not fit the definition as it is now; nothing was written
+ */
+ | ContentErrorOf<ContentErrorTypes.restoreRefused, {
+    violations: RestoreViolations;
+}>;
+export {};

package/dist/api/Content.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.LocalizationSettings = exports.ContentFieldViolationCodes = exports.SortDirection = exports.ContentSortField = exports.ContentsStatus = void 0;
+exports.ContentErrorTypes = exports.LocalizationSettings = exports.ContentFieldViolationCodes = exports.SortDirection = exports.ContentSortField = exports.ContentsStatus = void 0;
 /**
  * This enum represent the possible content status
  */
@@ -100,3 +100,17 @@ var LocalizationSettings;
     LocalizationSettings["DEFAULT"] = "default";
     LocalizationSettings["MAIN"] = "main";
 })(LocalizationSettings || (exports.LocalizationSettings = LocalizationSettings = {}));
+/**
+ * Thin enum represent the error types of the content API requests: the update content one, and the content
+ * history ones. Each is the `type` of a `RequestError`, whose `details` is a [[ContentError]]
+ */
+var ContentErrorTypes;
+(function (ContentErrorTypes) {
+    ContentErrorTypes["contentNotFound"] = "ContentNotFound";
+    ContentErrorTypes["failedContentPayloadValidation"] = "FailedContentPayloadValidation";
+    ContentErrorTypes["publicIdNotExclusiveToDefinitionId"] = "PublicIdNotExclusiveToDefinitionId";
+    ContentErrorTypes["versionMoved"] = "VersionMoved";
+    ContentErrorTypes["definitionMoved"] = "DefinitionMoved";
+    ContentErrorTypes["historyEntryNotFound"] = "HistoryEntryNotFound";
+    ContentErrorTypes["restoreRefused"] = "RestoreRefused";
+})(ContentErrorTypes || (exports.ContentErrorTypes = ContentErrorTypes = {}));

package/dist/api/MediaGallery.d.ts

@@ -396,18 +396,25 @@ export type ListMediaRequest = {
  */
 export type ListMediaResponse = PagedMediaResponse<Media>;
 /**
- * This type represent the data needed to make a get media API request
+ * This type represent the data needed to make a get media API request: the media by its id, or by its full
+ * public id, looked up in the space
  */
 export type GetMediaRequest = {
     /**
-     * The media gallery unique id
+     * The media gallery unique id, only needed for a `mediaPublicId` relative to the gallery root
      */
-    mediaGalleryId: MediaGalleryId;
+    mediaGalleryId?: MediaGalleryId;
+} & ({
     /**
      * The media entity unique id
      */
     mediaId: MediaId;
-};
+} | {
+    /**
+     * The media full public id, as [[Media.mediaPublicId]] holds it
+     */
+    mediaPublicId: MediaPublicId;
+});
 /**
  * This type represent the response of a get media API request
  */

package/lib/api/Content.ts

@@ -13,6 +13,7 @@ import {
 import {
   ContentTranslation,
   ContentTranslationStatus,
+  FieldTranslation,
 } from "./ContentTranslation";
 import { CoverageReport } from "./Audience";
 import { SetAsideResolution, SetAsideValue } from "./Component";
@@ -342,6 +343,12 @@ export type UpdateContentRequest = {
    * discarded
    */
   setAside?: SetAsideResolution[];
+
+  /**
+   * The version the person saw: a save made meanwhile is refused with `VersionMoved` rather than
+   * overwritten unseen
+   */
+  expectedVersion?: number;
 };
 
 /**
@@ -1057,3 +1064,192 @@ export type ProfileContentValuesResponse = {
   instances: number;
   fields: FieldValuesProfile[];
 };
+
+/**
+ * This type represent the kind of a version in a content's history: what a publish published, or the
+ * content as a restore found it, unpublished edits and translations included
+ */
+export type ContentHistoryKind = "published" | "beforeRestore";
+
+/**
+ * This type represent the data needed to make a list content history API request
+ */
+export type ListContentHistoryRequest = {
+  contentId: ContentId;
+  /**
+   * 0 by default
+   */
+  skip?: number;
+  /**
+   * 20 by default, at most 100
+   */
+  take?: number;
+};
+
+/**
+ * This type represent a version in a content's history
+ */
+export type ContentHistoryEntry = {
+  kind: ContentHistoryKind;
+  /**
+   * The publishing request's id for a `published` version, the restore's for a `beforeRestore` one
+   */
+  id: number;
+  /**
+   * The content's version at the time
+   */
+  version: number;
+  date: Date;
+  /**
+   * Who published or restored, null when unknown
+   */
+  author: Pick<AuthorResponse, "authorId" | "fullName"> | null;
+};
+
+/**
+ * This type represent the response of a list content history API request: newest first, without the
+ * publishes that failed or are still running
+ */
+export type ListContentHistoryResponse = {
+  items: ContentHistoryEntry[];
+  total: number;
+};
+
+/**
+ * This type represent the data needed to make a get content history entry API request
+ */
+export type GetContentHistoryEntryRequest = {
+  contentId: ContentId;
+  kind: ContentHistoryKind;
+  id: number;
+};
+
+/**
+ * This type represent a violation of one constraint. `code` is one of [[ContentFieldViolationCodes]], or
+ * of the translation ones such as `translation.unknownField`
+ */
+export type ContentConstraintViolation = {
+  path?: string;
+  code: string;
+};
+
+/**
+ * This type represent the violations of one item of an array field, matched by its `itemKey`
+ */
+export type ContentArrayItemViolation = {
+  itemKey: string;
+  index: number;
+  violations: (ContentConstraintViolation | ContentFieldViolation)[];
+};
+
+/**
+ * This type represent the violations of one field of a payload, as an update content API request answers
+ * them in its `validation`
+ */
+export type ContentFieldViolation = {
+  field: string;
+  violations: (
+    | ContentConstraintViolation
+    | ContentFieldViolation
+    | ContentArrayItemViolation
+  )[];
+};
+
+/**
+ * This type represent what keeps a version of the history from being restored, all empty when it can be
+ */
+export type RestoreViolations = {
+  payload: ContentFieldViolation[];
+  /**
+   * Per locale, the violations of its translated values
+   */
+  translations: { locale: string; violations: ContentConstraintViolation[] }[];
+  /**
+   * Values a component migration since would set aside: the definition has no place for them any more
+   */
+  setAside: { path: string; reason: "removed" | "changed" }[];
+};
+
+/**
+ * This type represent the response of a get content history entry API request: the version as a restore
+ * would write it, migrated to the definition as it is now, so it compares key by key with the get content
+ * API request's
+ */
+export type GetContentHistoryEntryResponse = ContentHistoryEntry & {
+  payload: object;
+  translations: { locale: string; translations: FieldTranslation[] }[];
+  restorable: boolean;
+  violations: RestoreViolations;
+};
+
+/**
+ * This type represent the data needed to make a restore content API request
+ */
+export type RestoreContentRequest = {
+  contentId: ContentId;
+  kind: ContentHistoryKind;
+  id: number;
+  /**
+   * The version the person saw: a save made meanwhile is refused with `VersionMoved` rather than
+   * overwritten unseen
+   */
+  expectedVersion?: number;
+};
+
+/**
+ * This type represent the response of a restore content API request: the content as an update content
+ * API request answers it
+ */
+export type RestoreContentResponse = UpdateContentResponse;
+
+/**
+ * Thin enum represent the error types of the content API requests: the update content one, and the content
+ * history ones. Each is the `type` of a `RequestError`, whose `details` is a [[ContentError]]
+ */
+export enum ContentErrorTypes {
+  contentNotFound = "ContentNotFound",
+  failedContentPayloadValidation = "FailedContentPayloadValidation",
+  publicIdNotExclusiveToDefinitionId = "PublicIdNotExclusiveToDefinitionId",
+  versionMoved = "VersionMoved",
+  definitionMoved = "DefinitionMoved",
+  historyEntryNotFound = "HistoryEntryNotFound",
+  restoreRefused = "RestoreRefused",
+}
+
+type ContentErrorOf<T extends ContentErrorTypes, D = {}> = {
+  type: T;
+  message: string;
+} & D;
+
+/**
+ * This type represent the `details` of a `RequestError` whose `type` is one of [[ContentErrorTypes]]
+ */
+export type ContentError =
+  | ContentErrorOf<ContentErrorTypes.contentNotFound>
+  /**
+   * The payload does not fit its definition, field by field; nothing was written
+   */
+  | ContentErrorOf<
+      ContentErrorTypes.failedContentPayloadValidation,
+      { validation: ContentFieldViolation[] }
+    >
+  /**
+   * The public id is in use on a content of another definition
+   */
+  | ContentErrorOf<ContentErrorTypes.publicIdNotExclusiveToDefinitionId>
+  /**
+   * The content is no longer at `expectedVersion`: read it again
+   */
+  | ContentErrorOf<ContentErrorTypes.versionMoved>
+  /**
+   * The definition changed while the content was saved or restored: try again
+   */
+  | ContentErrorOf<ContentErrorTypes.definitionMoved>
+  | ContentErrorOf<ContentErrorTypes.historyEntryNotFound>
+  /**
+   * The version does not fit the definition as it is now; nothing was written
+   */
+  | ContentErrorOf<
+      ContentErrorTypes.restoreRefused,
+      { violations: RestoreViolations }
+    >;

package/lib/api/MediaGallery.ts

@@ -421,18 +421,28 @@ export type ListMediaRequest = {
 export type ListMediaResponse = PagedMediaResponse<Media>;
 
 /**
- * This type represent the data needed to make a get media API request
+ * This type represent the data needed to make a get media API request: the media by its id, or by its full
+ * public id, looked up in the space
  */
 export type GetMediaRequest = {
     /**
-     * The media gallery unique id
-     */
-    mediaGalleryId: MediaGalleryId;
-    /**
-     * The media entity unique id
-     */
-    mediaId: MediaId;
-};
+     * The media gallery unique id, only needed for a `mediaPublicId` relative to the gallery root
+     */
+    mediaGalleryId?: MediaGalleryId;
+} & (
+    | {
+          /**
+           * The media entity unique id
+           */
+          mediaId: MediaId;
+      }
+    | {
+          /**
+           * The media full public id, as [[Media.mediaPublicId]] holds it
+           */
+          mediaPublicId: MediaPublicId;
+      }
+);
 
 /**
  * This type represent the response of a get media API request

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contentchef/contentchef-types",
-  "version": "11.2.0-alpha.0",
+  "version": "11.2.0-alpha.2",
   "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": "30ca15f956b396cce7e0db037e836b79406278cf"
+  "gitHead": "d5eafaf4b1b7a4d7add4d6c1153e3391e713c712"
 }