@enonic-types/lib-content 7.16.2-RC2 → 8.0.0-A2

package/content.d.ts

@@ -10,19 +10,46 @@ declare global {
     interface XpLibraries {
         '/lib/xp/content': typeof import('./content');
     }
-    interface XpXData {
-    }
 }
-import type { Aggregations, AggregationsResult, AggregationsToAggregationResults, ByteSource, Content, ContentInheritValue, Filter, FormItem, Highlight, HighlightResult, PublishInfo, QueryDsl, SortDsl, Workflow } from '@enonic-types/core';
-export type { Aggregation, Aggregations, AggregationsResult, Attachment, BooleanDslExpression, BooleanFilter, Bucket, BucketsAggregationResult, BucketsAggregationsUnion, ByteSource, Component, Content, DateBucket, DateHistogramAggregation, DateRange, DateRangeAggregation, DistanceUnit, DslOperator, DslQueryType, ExistsDslExpression, ExistsFilter, FieldSortDsl, Filter, FormItem, FormItemInlineMixin, FormItemInput, FormItemLayout, FormItemOptionSet, FormItemSet, FulltextDslExpression, GeoDistanceAggregation, GeoDistanceSortDsl, GroupKey, HasValueFilter, Highlight, HighlightResult, HistogramAggregation, IdsFilter, InDslExpression, InputType, LikeDslExpression, MatchAllDslExpression, MaxAggregation, MinAggregation, NgramDslExpression, NotExistsFilter, NumericBucket, NumericRange, NumericRangeAggregation, PathMatchDslExpression, PublishInfo, QueryDsl, RangeDslExpression, Region, RoleKey, ScriptValue, SingleValueMetricAggregationResult, SingleValueMetricAggregationsUnion, SortDirection, SortDsl, StatsAggregation, StatsAggregationResult, StemmedDslExpression, TermDslExpression, TermsAggregation, UserKey, ValueCountAggregation, ValueType, } from '@enonic-types/core';
-declare type Attachments = Content['attachments'];
-export declare type PageComponentWhenAutomaticTemplate = Record<string, never>;
+import { Aggregations, AggregationsResult, AggregationsToAggregationResults, Attachment, ByteSource, Content, ContentComponent, ContentComponentConstraint, ContentInheritValue, Filter, FormItem, Highlight, HighlightResult, Layout, LayoutComponent, Page, PageComponent, Part, PartComponent, PublishInfo, QueryDsl, SortDsl, UserKey, ValidationError, Workflow, WorkflowState } from '@enonic-types/core';
+export type { Aggregation, Aggregations, AggregationsResult, Attachment, BooleanDslExpression, BooleanFilter, Bucket, BucketsAggregationResult, BucketsAggregationsUnion, ByteSource, Component, Content, ContentComponent, ContentComponentConstraint, DateBucket, DateHistogramAggregation, DateRange, DateRangeAggregation, DistanceUnit, DslOperator, DslQueryType, ExistsDslExpression, ExistsFilter, FieldSortDsl, Filter, FormItem, FormItemFormFragment, FormItemInput, FormItemLayout, FormItemOptionSet, FormItemSet, FulltextDslExpression, GeoDistanceAggregation, GeoDistanceSortDsl, GroupKey, HasValueFilter, Highlight, HighlightResult, HistogramAggregation, IdsFilter, InDslExpression, InputType, LikeDslExpression, MatchAllDslExpression, MaxAggregation, MinAggregation, NgramDslExpression, NotExistsFilter, NumericBucket, NumericRange, NumericRangeAggregation, PathMatchDslExpression, PublishInfo, QueryDsl, RangeDslExpression, Region, RoleKey, ScriptValue, SingleValueMetricAggregationResult, SingleValueMetricAggregationsUnion, SortDirection, SortDsl, StatsAggregation, StatsAggregationResult, StemmedDslExpression, TermDslExpression, TermsAggregation, UserKey, ValueCountAggregation, ValueType, } from '@enonic-types/core';
+type Attachments = Content['attachments'];
+export type PageComponentWhenAutomaticTemplate = Record<string, never>;
 export interface PageComponentWhenSpecificTemplate {
     path: '/';
     template: string;
     type: 'page';
 }
-export declare type Schedule = Omit<PublishInfo, 'first'>;
+export type Schedule = Omit<PublishInfo, 'first'>;
+export interface PatchableContent<Data extends Record<string, unknown> = Record<string, unknown>, Type extends string = string, _Component extends ContentComponentConstraint<Type> = ContentComponent<Type>> {
+    displayName: string;
+    data: Type extends 'portal:fragment' ? Record<string, never> : Data;
+    x: XpMixin;
+    page: Type extends 'portal:fragment' ? never : _Component;
+    valid: boolean;
+    owner: UserKey;
+    language: string;
+    creator: UserKey;
+    createdTime: string;
+    modifier: UserKey;
+    modifiedTime: string;
+    publishInfo: PublishInfo;
+    processedReferences: string[];
+    workflowInfo: Workflow;
+    manualOrderValue: number;
+    inherit: ContentInheritValue[];
+    variantOf: string;
+    modifyAttachments: Attachment;
+    removeAttachments: string[];
+    createAttachments: AddAttachmentParam[];
+    validationErrors: ValidationError[];
+    type: Type;
+    childOrder: string;
+    originProject: string;
+    originalParentPath: string;
+    archivedTime: string;
+    archivedBy: UserKey;
+}
 export declare const ARCHIVE_ROOT_PATH: string;
 export declare const CONTENT_ROOT_PATH: string;
 export interface GetContentParams {
@@ -105,12 +132,12 @@ export interface SiteConfig<Config> {
     applicationKey: string;
     config: Config;
 }
-export declare type Site<Config> = Content<{
+export type Site<Config> = Content<{
     description?: string;
     siteConfig: SiteConfig<Config> | SiteConfig<Config>[];
 }, 'portal:site'>;
 export interface GetSiteParams {
-    key?: string | null;
+    key: string;
 }
 /**
  * This function returns the parent site of a content.
@@ -152,8 +179,8 @@ export interface DeleteContentParams {
  *
  * @returns {boolean} True if deleted, false otherwise.
  */
-declare function _delete(params: DeleteContentParams): boolean;
-export { _delete as delete, };
+export declare function deleteContent(params: DeleteContentParams): boolean;
+export { deleteContent as delete, };
 export interface ContentsResult<Hit extends Content<unknown>, AggregationOutput extends Record<string, AggregationsResult> | undefined = undefined> {
     total: number;
     count: number;
@@ -181,8 +208,8 @@ export interface GetChildContentParams {
  * @returns {Object} Result (of content) fetched from the repository.
  */
 export declare function getChildren<Hit extends Content<unknown> = Content, AggregationOutput extends Record<string, AggregationsResult> = never>(params: GetChildContentParams): ContentsResult<Hit, AggregationOutput>;
-export declare type IdGeneratorSupplier = (value: string) => string;
-export interface CreateContentParams<Data, Type extends string> {
+export type IdGeneratorSupplier = (value: string) => string;
+export interface CreateContentParams<Data, Type extends string, _Component extends (Type extends 'portal:fragment' ? LayoutComponent | PartComponent : PageComponent) = (Type extends 'portal:fragment' ? Layout | Part : Page)> {
     name?: string;
     parentPath: string;
     displayName?: string;
@@ -192,7 +219,8 @@ export interface CreateContentParams<Data, Type extends string> {
     language?: string;
     childOrder?: string;
     data: Data;
-    x?: XpXData;
+    page?: Type extends 'portal:fragment' ? never : _Component;
+    x?: XpMixin;
     idGenerator?: IdGeneratorSupplier;
     workflow?: Workflow;
 }
@@ -251,15 +279,38 @@ export interface QueryContentParams<AggregationInput extends Aggregations = neve
  * @returns {object} Result of query.
  */
 export declare function query<Hit extends Content<unknown> = Content, AggregationInput extends Aggregations = never>(params: QueryContentParams<AggregationInput>): ContentsResult<Hit, AggregationsToAggregationResults<AggregationInput>>;
+/**
+ * @deprecated Use {@link UpdateContentParams} instead.
+ */
 export interface ModifyContentParams<Data, Type extends string> {
     key: string;
     editor: (v: Content<Data, Type>) => Content<Data, Type>;
     requireValid?: boolean;
 }
+export interface UpdateContentParams<Data, Type extends string> {
+    key: string;
+    editor: (v: Content<Data, Type>) => Content<Data, Type>;
+    requireValid?: boolean;
+}
+export interface PatchContentParams {
+    key: string;
+    patcher: (v: PatchableContent) => PatchableContent;
+    attachments?: AddAttachmentParam[];
+    branches?: string[];
+    skipSync?: boolean;
+}
+export interface PatchContentResult<Data extends Record<string, unknown> = Record<string, unknown>, Type extends string = string> {
+    contentId: string;
+    results: BranchPatchResult<Data, Type>[];
+}
+export interface BranchPatchResult<Data extends Record<string, unknown> = Record<string, unknown>, Type extends string = string> {
+    branch: string;
+    content: Content<Data, Type> | null;
+}
 /**
  * This function modifies a content.
  *
- * @example-ref examples/content/modify.js
+ * @deprecated Use {@link update} instead.
  *
  * @param {object} params JSON with the parameters.
  * @param {string} params.key Path or id to the content.
@@ -269,17 +320,95 @@ export interface ModifyContentParams<Data, Type extends string> {
  * @returns {object} Modified content as JSON.
  */
 export declare function modify<Data = Record<string, unknown>, Type extends string = string>(params: ModifyContentParams<Data, Type>): Content<Data, Type> | null;
+/**
+ * This function updates a content.
+ *
+ * @example-ref examples/content/update.js
+ *
+ * @param {object} params JSON with the parameters.
+ * @param {string} params.key Path or id to the content.
+ * @param {function} params.editor Editor callback function.
+ * @param {boolean} [params.requireValid=true] The content has to be valid, according to the content type, to be updated. If requireValid=true and the content is not strictly valid, an error will be thrown.
+ *
+ * @returns {object} Modified content as JSON.
+ */
+export declare function update<Data extends Record<string, unknown> = Record<string, unknown>, Type extends string = string>(params: UpdateContentParams<Data, Type>): Content<Data, Type> | null;
+/**
+ * This function patches a content.
+ *
+ * @example-ref examples/content/patch.js
+ *
+ * @param {object} params JSON with the parameters.
+ * @param {string} params.key Path or id to the content.
+ * @param {function} params.patcher Patcher callback function.
+ * @param {boolean} [params.skipSync=false] If true, the content will not be immediately synced to the child projects.
+ * @param {string[]} [params.branches=[]] List of branches to patch the content in. If not specified, the context's branch is used.
+ *
+ * @returns {object} Patched content as JSON.
+ */
+export declare function patch(params: PatchContentParams): PatchContentResult;
+export interface EditableContentMetadata {
+    source: Content;
+    language?: string;
+    owner?: string;
+    variantOf?: string;
+}
+export interface UpdateMetadataParams {
+    key: string;
+    editor: (v: EditableContentMetadata) => EditableContentMetadata;
+}
+export interface UpdateMetadataResult<Data extends Record<string, unknown> = Record<string, unknown>, Type extends string = string> {
+    content: Content<Data, Type>;
+}
+/**
+ * This function updates metadata (language, owner, and variantOf) for a content.
+ * The update is applied to both master and draft branches.
+ *
+ * @example-ref examples/content/updateMetadata.js
+ *
+ * @param {object} params JSON with the parameters.
+ * @param {string} params.key Path or id to the content.
+ * @param {function} params.editor Editor callback function to modify metadata.
+ *
+ * @returns {object} Updated content metadata result as JSON.
+ */
+export declare function updateMetadata(params: UpdateMetadataParams): UpdateMetadataResult;
+export interface EditableWorkflow {
+    source: Content;
+    state: WorkflowState;
+}
+export interface UpdateWorkflowParams {
+    key: string;
+    editor: (v: EditableWorkflow) => EditableWorkflow;
+}
+export interface UpdateWorkflowResult<Data extends Record<string, unknown> = Record<string, unknown>, Type extends string = string> {
+    content: Content<Data, Type>;
+}
+/**
+ * This function updates workflow information (state and checks) for a content.
+ * The update is applied to the draft branch only.
+ *
+ * @param {object} params JSON with the parameters.
+ * @param {string} params.key Path or id to the content.
+ * @param {function} params.editor Editor callback function to modify workflow.
+ *
+ * @returns {object} Updated workflow result as JSON.
+ */
+export declare function updateWorkflow(params: UpdateWorkflowParams): UpdateWorkflowResult;
 export interface PublishContentParams {
     keys: string[];
     schedule?: Schedule;
     includeChildren?: boolean;
+    /**
+     * @deprecated Use excludeDescendantsOf instead.
+     */
     excludeChildrenIds?: string[];
+    excludeDescendantsOf?: string[];
     includeDependencies?: boolean;
     message?: string;
 }
 export interface PublishContentResult {
     pushedContents: string[];
-    deletedContents: string[];
     failedContents: string[];
 }
 /**
@@ -293,7 +422,8 @@ export interface PublishContentResult {
  * @param {object} [params.schedule] Schedule the publish.
  * @param {string} [params.schedule.from] Time from which the content is considered published. Defaults to the time of the publish
  * @param {string} [params.schedule.to] Time until which the content is considered published.
- * @param {string[]} [params.excludeChildrenIds] List of all content keys which children should be excluded from publishing content.
+ * @param {string[]} [params.excludeChildrenIds] Deprecated. Use excludeDescendantsOf instead.
+ * @param {string[]} [params.excludeDescendantsOf] List of all content keys which children should be excluded from publishing content.
  * @param {boolean} [params.includeDependencies=true] Whether all related content should be included when publishing content.
  * @param {string} [params.message] Publish message.
  *
@@ -398,38 +528,45 @@ export interface RestoreContentParams {
  * @returns {string[]} List with ids of the contents that were restored.
  */
 export declare function restore(params: RestoreContentParams): string[];
-export declare type Permission = 'READ' | 'CREATE' | 'MODIFY' | 'DELETE' | 'PUBLISH' | 'READ_PERMISSIONS' | 'WRITE_PERMISSIONS';
+export type Permission = 'READ' | 'CREATE' | 'MODIFY' | 'DELETE' | 'PUBLISH' | 'READ_PERMISSIONS' | 'WRITE_PERMISSIONS';
 export interface AccessControlEntry {
     principal: string;
     allow?: Permission[];
     deny?: Permission[];
 }
-export interface SetPermissionsParams {
+export interface ApplyPermissionsParams {
     key: string;
-    inheritPermissions?: boolean;
-    overwriteChildPermissions?: boolean;
+    scope?: 'SINGLE' | 'TREE' | 'SUBTREE';
     permissions?: AccessControlEntry[];
+    addPermissions?: AccessControlEntry[];
+    removePermissions?: AccessControlEntry[];
+}
+export type ApplyPermissionsResult = Record<string, BranchResult[]>;
+export interface BranchResult {
+    branch: string;
+    permissions: AccessControlEntry[];
 }
 export interface Permissions {
-    inheritsPermissions: boolean;
     permissions?: AccessControlEntry[];
 }
 /**
- * Sets permissions on a content.
+ * Applies permissions to a content.
  *
- * @example-ref examples/content/setPermissions.js
+ * @example-ref examples/content/applyPermissions.js
  *
  * @param {object} params JSON parameters.
  * @param {string} params.key Path or id of the content.
- * @param {boolean} [params.inheritPermissions] Set to true if the content must inherit permissions. Default to false.
- * @param {boolean} [params.overwriteChildPermissions] Set to true to overwrite child permissions. Default to false.
- * @param {array} [params.permissions] Array of permissions.
+ * @param {string} [params.scope] Scope of operation. Possible values are 'SINGE', 'TREE' or 'SUBTREE'. Default is 'SINGLE'.
+ * @param {array} [params.permissions] Array of permissions. Cannot be used together with addPermissions and removePermissions.
  * @param {string} params.permissions.principal Principal key.
  * @param {array} params.permissions.allow Allowed permissions.
  * @param {array} params.permissions.deny Denied permissions.
- * @returns {boolean} True if successful, false otherwise.
+ * @param {array} [params.addPermissions] Array of permissions to add. Cannot be used together with permissions.
+ * @param {array} [params.removePermissions] Array of permissions to remove. Cannot be used together with permissions.
+ *
+ * @returns {object} Result of the apply permissions operation.
  */
-export declare function setPermissions(params: SetPermissionsParams): boolean;
+export declare function applyPermissions(params: ApplyPermissionsParams): ApplyPermissionsResult;
 export interface GetPermissionsParams {
     key: string;
 }
@@ -525,6 +662,9 @@ export interface ResetInheritanceHandler {
  * @param {string[]} params.inherit flags to be reset.
  */
 export declare function resetInheritance(params: ResetInheritanceParams): void;
+/**
+ * @deprecated Use {@link UpdateMediaParams} instead.
+ */
 export interface ModifyMediaParams {
     key: string;
     name: string;
@@ -538,9 +678,22 @@ export interface ModifyMediaParams {
     tags?: string | string[];
     workflow?: Workflow;
 }
+export interface UpdateMediaParams {
+    key: string;
+    name: string;
+    data: ByteSource;
+    artist?: string | string[];
+    caption?: string;
+    copyright?: string;
+    focalX?: number;
+    focalY?: number;
+    mimeType?: string;
+    tags?: string | string[];
+    workflow?: Workflow;
+}
 /** This function modifies a media content.
  *
- * @example-ref examples/content/modifyMedia.js
+ * deprecated Use {@link updateMedia} instead.
  *
  * @param {object} params JSON with the parameters.
  * @param {string} params.key Path or id to the content.
@@ -558,6 +711,26 @@ export interface ModifyMediaParams {
  * @returns {object} Modified content as JSON.
  */
 export declare function modifyMedia<Data = Record<string, unknown>, Type extends string = string>(params: ModifyMediaParams): Content<Data, Type> | null;
+/** This function updates a media content.
+ *
+ * @example-ref examples/content/updateMedia.js
+ *
+ * @param {object} params JSON with the parameters.
+ * @param {string} params.key Path or id to the content.
+ * @param {string} params.name Name to the content.
+ * @param {function} params.data Data (as stream) to use.
+ * @param {string} [params.mimeType] Mime-type of the data.
+ * @param {string|string[]} [params.artist] Artist to the content.
+ * @param {string} [params.caption] Caption to the content.
+ * @param {string} [params.copyright] Copyright to the content.
+ * @param {string|string[]} [params.tags] Tags to the content.
+ * @param {object} [params.workflow] Workflow information to use. Default has state READY and empty check list.
+ * @param {number} [params.focalX=0.5] Focal point for X axis (if it's an image).
+ * @param {number} [params.focalY=0.5] Focal point for Y axis (if it's an image).
+ *
+ * @returns {object} Modified content as JSON.
+ */
+export declare function updateMedia<Data = Record<string, unknown>, Type extends string = string>(params: UpdateMediaParams): Content<Data, Type> | null;
 export interface DuplicateContentParams {
     contentId: string;
     workflow?: Workflow;
@@ -586,3 +759,57 @@ export interface DuplicateContentsResult {
  * @returns {object} summary about duplicated content.
  */
 export declare function duplicate(params: DuplicateContentParams): DuplicateContentsResult;
+export interface GetVersionsParams {
+    key: string;
+    count?: number;
+    cursor?: string;
+}
+export interface ContentVersion {
+    versionId: string;
+    contentId: string;
+    path: string;
+    timestamp: string;
+    comment?: string;
+    actions?: ContentVersionAction[];
+}
+export interface ContentVersionAction {
+    operation: string;
+    user: string;
+    opTime: string;
+}
+export interface ContentVersionsResult {
+    total: number;
+    count: number;
+    cursor: string | null;
+    hits: ContentVersion[];
+}
+/**
+ * This function returns content versions.
+ *
+ * @example-ref examples/content/getVersions.js
+ *
+ * @param {object} params JSON with the parameters.
+ * @param {string} params.key Path or ID of the content.
+ * @param {number} [params.count=10] Number of content versions to fetch.
+ * @param {string} [params.cursor] Cursor for pagination.
+ *
+ * @returns {object} Content versions result.
+ */
+export declare function getVersions(params: GetVersionsParams): ContentVersionsResult;
+export interface GetActiveVersionsParams {
+    key: string;
+    branches: string[];
+}
+export type ActiveContentVersions = Record<string, ContentVersion>;
+/**
+ * This function returns the active content version for each specified branch.
+ *
+ * @example-ref examples/content/getActiveVersions.js
+ *
+ * @param {object} params JSON with the parameters.
+ * @param {string} params.key Path or ID of the content.
+ * @param {string[]} params.branches Array of branch names to get active versions for.
+ *
+ * @returns {object} Object with branch names as keys and content versions as values.
+ */
+export declare function getActiveVersions(params: GetActiveVersionsParams): ActiveContentVersions;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@enonic-types/lib-content",
-    "version": "7.16.2-RC2",
+    "version": "8.0.0-A2",
     "description": "Type definitions for lib-content.",
     "types": "content.d.ts",
     "files": [
@@ -27,7 +27,7 @@
     },
     "homepage": "https://github.com/enonic/xp/tree/master#readme",
     "dependencies": {
-        "@enonic-types/core": "7.16.2-RC2"
+        "@enonic-types/core": "8.0.0-A2"
     },
     "publishConfig": {
         "access": "public"