contentful-management 11.60.3 → 12.0.0-beta.10

package/dist/types/entities/asset.d.ts

@@ -0,0 +1,277 @@
+import type { Stream } from 'stream';
+import type { DefaultElements, EntityMetaSysProps, MetadataProps, MakeRequest } from '../common-types.js';
+export type AssetProps<S = {}> = {
+    sys: EntityMetaSysProps & S;
+    fields: {
+        /** Title for this asset */
+        title: {
+            [key: string]: string;
+        };
+        /** Description for this asset */
+        description?: {
+            [key: string]: string;
+        };
+        /** File object for this asset */
+        file: {
+            [key: string]: {
+                fileName: string;
+                contentType: string;
+                /** Url where the file is available to be downloaded from, into the Contentful asset system. After the asset is processed this field is gone. */
+                upload?: string;
+                /** Url where the file is available at the Contentful media asset system. This field won't be available until the asset is processed. */
+                url?: string;
+                /** Details for the file, depending on file type (example: image size in bytes, etc) */
+                details?: Record<string, any>;
+                uploadFrom?: Record<string, any>;
+            };
+        };
+    };
+    metadata?: MetadataProps;
+};
+export type CreateAssetProps = Omit<AssetProps, 'sys'>;
+export type CreateAssetFromFilesOptions = {
+    uploadTimeout?: number;
+};
+export interface AssetFileProp {
+    fields: {
+        title: {
+            [key: string]: string;
+        };
+        description: {
+            [key: string]: string;
+        };
+        file: {
+            [key: string]: {
+                file: string | ArrayBuffer | Stream;
+                contentType: string;
+                fileName: string;
+            };
+        };
+    };
+}
+export interface AssetProcessingForLocale {
+    processingCheckWait?: number;
+    processingCheckRetries?: number;
+}
+type AssetApi = {
+    /**
+     * Triggers asset processing after an upload, for the files uploaded to all locales of an asset.
+     * @param options - Additional options for processing
+     * @prop options.processingCheckWait - Time in milliseconds to wait before checking again if the asset has been processed (default: 500ms)
+     * @prop options.processingCheckRetries - Maximum amount of times to check if the asset has been processed (default: 5)
+     * @return Object returned from the server with updated metadata.
+     * @throws {AssetProcessingTimeout} If the asset takes too long to process. If this happens, retrieve the asset again, and if the url property is available, then processing has succeeded. If not, your file might be damaged.
+     * @example ```javascript
+     * const contentful = require('contentful-management')
+     *
+     * const client = contentful.createClient({
+     *   accessToken: '<content_management_api_key>'
+     * })
+     * client.getSpace('<space_id>')
+     * .then((space) => space.getEnvironment('<environment_id>'))
+     * .then((environment) => environment.createAssetWithId('<asset_id>', {
+     *   title: {
+     *     'en-US': 'Playsam Streamliner',
+     *     'de-DE': 'Playsam Streamliner'
+     *   },
+     *   file: {
+     *     'en-US': {
+     *       contentType: 'image/jpeg',
+     *       fileName: 'example.jpeg',
+     *       upload: 'https://example.com/example.jpg'
+     *     },
+     *     'de-DE': {
+     *       contentType: 'image/jpeg',
+     *       fileName: 'example.jpeg',
+     *       upload: 'https://example.com/example-de.jpg'
+     *     }
+     *   }
+     * }))
+     * .then((asset) => asset.processForAllLocales())
+     * .then((asset) => console.log(asset))
+     * .catch(console.error)
+     * ```
+     */
+    processForAllLocales(options?: AssetProcessingForLocale): Promise<Asset>;
+    /**
+     * Triggers asset processing after an upload, for the file uploaded to a specific locale.
+     * @param locale - Locale which processing should be triggered for
+     * @param options - Additional options for processing
+     * @prop options.processingCheckWait - Time in milliseconds to wait before checking again if the asset has been processed (default: 500ms)
+     * @prop options.processingCheckRetries - Maximum amount of times to check if the asset has been processed (default: 5)
+     * @return Object returned from the server with updated metadata.
+     * @throws {AssetProcessingTimeout} If the asset takes too long to process. If this happens, retrieve the asset again, and if the url property is available, then processing has succeeded. If not, your file might be damaged.
+     * @example ```javascript
+     * const contentful = require('contentful-management')
+     *
+     * const client = contentful.createClient({
+     *   accessToken: '<content_management_api_key>'
+     * })
+     * client.getSpace('<space_id>')
+     * .then((space) => space.getEnvironment('<environment_id>'))
+     * .then((environment) => environment.createAssetWithId('<asset_id>', {
+     *   title: {
+     *     'en-US': 'Playsam Streamliner',
+     *   },
+     *   file: {
+     *     'en-US': {
+     *       contentType: 'image/jpeg',
+     *       fileName: 'example.jpeg',
+     *       upload: 'https://example.com/example.jpg'
+     *     }
+     *   }
+     * }))
+     * .then((asset) => asset.processForLocale('en-US'))
+     * .then((asset) => console.log(asset))
+     * .catch(console.error)
+     * ```
+     */
+    processForLocale(locale: string, Options?: AssetProcessingForLocale): Promise<Asset>;
+    /**
+     * Publishes the object
+     * @return Object returned from the server with updated metadata.
+     * @example ```javascript
+     * const contentful = require('contentful-management')
+     *
+     * const client = contentful.createClient({
+     *   accessToken: '<content_management_api_key>'
+     * })
+     *
+     * client.getSpace('<space_id>')
+     * .then((space) => space.getEnvironment('<environment_id>'))
+     * .then((environment) => environment.getAsset('<asset_id>'))
+     * .then((asset) => asset.publish())
+     * .then((asset) => console.log(`Asset ${asset.sys.id} published.`)
+     * .catch(console.error)
+     * ```
+     */
+    publish(): Promise<Asset>;
+    /**
+     * Archives the object
+     * @return Object returned from the server with updated metadata.
+     * @example ```javascript
+     * const contentful = require('contentful-management')
+     *
+     * const client = contentful.createClient({
+     *   accessToken: '<content_management_api_key>'
+     * })
+     *
+     * client.getSpace('<space_id>')
+     * .then((space) => space.getEnvironment('<environment_id>'))
+     * .then((environment) => environment.getAsset('<asset_id>'))
+     * .then((asset) => asset.archive())
+     * .then((asset) => console.log(`Asset ${asset.sys.id} archived.`)
+     * .catch(console.error)
+     * ```
+     */
+    archive(): Promise<Asset>;
+    /**
+     * Deletes this object on the server.
+     * @return Promise for the deletion. It contains no data, but the Promise error case should be handled.
+     * @example ```javascript
+     * const contentful = require('contentful-management')
+     *
+     * const client = contentful.createClient({
+     *   accessToken: '<content_management_api_key>'
+     * })
+     *
+     * client.getSpace('<space_id>')
+     * .then((space) => space.getEnvironment('<environment_id>'))
+     * .then((environment) => environment.getAsset('<asset_id>'))
+     * .then((asset) => asset.delete())
+     * .then((asset) => console.log(`Asset deleted.`)
+     * .catch(console.error)
+     * ```
+     */
+    delete(): Promise<void>;
+    /**
+     * Unarchives the object
+     * @return Object returned from the server with updated metadata.
+     * @example ```javascript
+     * const contentful = require('contentful-management')
+     *
+     * const client = contentful.createClient({
+     *   accessToken: '<content_management_api_key>'
+     * })
+     *
+     * client.getSpace('<space_id>')
+     * .then((space) => space.getEnvironment('<environment_id>'))
+     * .then((environment) => environment.getAsset('<asset_id>'))
+     * .then((asset) => asset.unarchive())
+     * .then((asset) => console.log(`Asset ${asset.sys.id} unarchived.`)
+     * .catch(console.error)
+     * ```
+     */
+    unarchive(): Promise<Asset>;
+    /**
+     * Unpublishes the object
+     * @return Object returned from the server with updated metadata.
+     * @example ```javascript
+     * const contentful = require('contentful-management')
+     *
+     * const client = contentful.createClient({
+     *   accessToken: '<content_management_api_key>'
+     * })
+     *
+     * client.getSpace('<space_id>')
+     * .then((space) => space.getEnvironment('<environment_id>'))
+     * .then((environment) => environment.getAsset('<asset_id>'))
+     * .then((asset) => asset.unpublish())
+     * .then((asset) => console.log(`Asset ${asset.sys.id} unpublished.`)
+     * .catch(console.error)
+     * ```
+     */
+    unpublish(): Promise<Asset>;
+    /**
+     * Sends an update to the server with any changes made to the object's properties
+     * @return Object returned from the server with updated changes.
+     * @example ```javascript
+     * const contentful = require('contentful-management')
+     *
+     * const client = contentful.createClient({
+     *   accessToken: '<content_management_api_key>'
+     * })
+     *
+     * client.getSpace('<space_id>')
+     * .then((space) => space.getEnvironment('<environment_id>'))
+     * .then((environment) => environment.getAsset('<asset_id>'))
+     * .then((asset) => {
+     *   asset.fields.title['en-US'] = 'New asset title'
+     *   return asset.update()
+     * })
+     * .then((asset) => console.log(`Asset ${asset.sys.id} updated.`)
+     * .catch(console.error)
+     * ```
+     */
+    update(): Promise<Asset>;
+    /**
+     * Checks if the asset is published. A published asset might have unpublished changes
+     */
+    isPublished(): boolean;
+    /**
+     * Checks if the asset is updated. This means the asset was previously published but has unpublished changes.
+     */
+    isUpdated(): boolean;
+    /**
+     * Checks if the asset is in draft mode. This means it is not published.
+     */
+    isDraft(): boolean;
+    /**
+     * Checks if asset is archived. This means it's not exposed to the Delivery/Preview APIs.
+     */
+    isArchived(): boolean;
+};
+export interface Asset extends AssetProps, DefaultElements<AssetProps>, AssetApi {
+}
+/**
+ * @private
+ * @param makeRequest - function to make requests via an adapter
+ * @param data - Raw asset data
+ * @return Wrapped asset data
+ */
+export declare function wrapAsset(makeRequest: MakeRequest, data: AssetProps): Asset;
+/**
+ * @private
+ */
+export declare const wrapAssetCollection: (makeRequest: MakeRequest, data: import("../common-types.js").CollectionProp<AssetProps<{}>>) => import("../common-types.js").Collection<Asset, AssetProps<{}>>;
+export {};

package/dist/types/entities/asset.js

@@ -0,0 +1,129 @@
+import copy from 'fast-copy';
+import { toPlainObject, freezeSys } from 'contentful-sdk-core';
+import enhanceWithMethods from '../enhance-with-methods.js';
+import { wrapCollection } from '../common-utils.js';
+import { isPublished, isUpdated, isDraft, isArchived } from '../plain/checks.js';
+
+/**
+ * @private
+ */
+function createAssetApi(makeRequest) {
+    const getParams = (raw) => {
+        return {
+            spaceId: raw.sys.space.sys.id,
+            environmentId: raw.sys.environment.sys.id,
+            assetId: raw.sys.id,
+        };
+    };
+    return {
+        processForLocale: function processForLocale(locale, options) {
+            const raw = this.toPlainObject();
+            return makeRequest({
+                entityType: 'Asset',
+                action: 'processForLocale',
+                params: {
+                    ...getParams(raw),
+                    locale,
+                    options,
+                    asset: raw,
+                },
+            }).then((data) => wrapAsset(makeRequest, data));
+        },
+        processForAllLocales: function processForAllLocales(options) {
+            const raw = this.toPlainObject();
+            return makeRequest({
+                entityType: 'Asset',
+                action: 'processForAllLocales',
+                params: {
+                    ...getParams(raw),
+                    asset: raw,
+                    options,
+                },
+            }).then((data) => wrapAsset(makeRequest, data));
+        },
+        update: function update() {
+            const raw = this.toPlainObject();
+            return makeRequest({
+                entityType: 'Asset',
+                action: 'update',
+                params: getParams(raw),
+                payload: raw,
+                headers: {},
+            }).then((data) => wrapAsset(makeRequest, data));
+        },
+        delete: function del() {
+            const raw = this.toPlainObject();
+            return makeRequest({
+                entityType: 'Asset',
+                action: 'delete',
+                params: getParams(raw),
+            });
+        },
+        publish: function publish() {
+            const raw = this.toPlainObject();
+            return makeRequest({
+                entityType: 'Asset',
+                action: 'publish',
+                params: getParams(raw),
+                payload: raw,
+            }).then((data) => wrapAsset(makeRequest, data));
+        },
+        unpublish: function unpublish() {
+            const raw = this.toPlainObject();
+            return makeRequest({
+                entityType: 'Asset',
+                action: 'unpublish',
+                params: getParams(raw),
+            }).then((data) => wrapAsset(makeRequest, data));
+        },
+        archive: function archive() {
+            const raw = this.toPlainObject();
+            return makeRequest({
+                entityType: 'Asset',
+                action: 'archive',
+                params: getParams(raw),
+            }).then((data) => wrapAsset(makeRequest, data));
+        },
+        unarchive: function unarchive() {
+            const raw = this.toPlainObject();
+            return makeRequest({
+                entityType: 'Asset',
+                action: 'unarchive',
+                params: getParams(raw),
+            }).then((data) => wrapAsset(makeRequest, data));
+        },
+        isPublished: function isPublished$1() {
+            const raw = this.toPlainObject();
+            return isPublished(raw);
+        },
+        isUpdated: function isUpdated$1() {
+            const raw = this.toPlainObject();
+            return isUpdated(raw);
+        },
+        isDraft: function isDraft$1() {
+            const raw = this.toPlainObject();
+            return isDraft(raw);
+        },
+        isArchived: function isArchived$1() {
+            const raw = this.toPlainObject();
+            return isArchived(raw);
+        },
+    };
+}
+/**
+ * @private
+ * @param makeRequest - function to make requests via an adapter
+ * @param data - Raw asset data
+ * @return Wrapped asset data
+ */
+function wrapAsset(makeRequest, data) {
+    const asset = toPlainObject(copy(data));
+    const assetWithMethods = enhanceWithMethods(asset, createAssetApi(makeRequest));
+    return freezeSys(assetWithMethods);
+}
+/**
+ * @private
+ */
+const wrapAssetCollection = wrapCollection(wrapAsset);
+
+export { wrapAsset, wrapAssetCollection };

package/dist/types/entities/bulk-action.d.ts

@@ -0,0 +1,94 @@
+import type { DefaultElements, ISO8601Timestamp, Link, MakeRequest, MakeRequestPayload, VersionedLink } from '../common-types.js';
+import type { AsyncActionProcessingOptions } from '../methods/action.js';
+/** Entity types supported by the BulkAction API */
+type Entity = 'Entry' | 'Asset';
+type Collection<T> = Array<T>;
+type EntityError = {
+    entity: VersionedLink<Entity> | Link<Entity>;
+    error: any;
+};
+export type BulkActionType = 'publish' | 'unpublish' | 'validate';
+/** Represents the state of the BulkAction */
+export declare enum BulkActionStatus {
+    /** BulkAction is pending execution */
+    created = "created",
+    /** BulkAction has been started and pending completion */
+    inProgress = "inProgress",
+    /** BulkAction was completed successfully (terminal state) */
+    succeeded = "succeeded",
+    /** BulkAction failed to complete (terminal state) */
+    failed = "failed"
+}
+declare const STATUSES: BulkActionStatus[];
+type BulkActionStatuses = (typeof STATUSES)[number];
+interface BulkActionFailedError {
+    sys: {
+        type: 'Error';
+        id: 'BulkActionFailed';
+    };
+    message?: string;
+    details?: {
+        errors: Collection<EntityError>;
+    };
+}
+export type BulkActionPayload = BulkActionPublishPayload | BulkActionUnpublishPayload | BulkActionValidatePayload;
+export interface BulkActionValidatePayload extends MakeRequestPayload {
+    action?: 'publish';
+    entities: {
+        sys?: {
+            type: 'Array';
+        };
+        items: Collection<Link<Entity>>;
+    };
+}
+export interface BulkActionUnpublishPayload extends MakeRequestPayload {
+    entities: {
+        sys?: {
+            type: 'Array';
+        };
+        items: Collection<Link<Entity>>;
+    };
+}
+export interface BulkActionPublishPayload extends MakeRequestPayload {
+    entities: {
+        sys?: {
+            type: 'Array';
+        };
+        items: Collection<VersionedLink<Entity>>;
+    };
+}
+export type BulkActionSysProps = {
+    id: string;
+    type: 'BulkAction';
+    status: BulkActionStatuses;
+    space: Link<'Space'>;
+    environment: Link<'Environment'>;
+    createdBy: Link<'User'>;
+    createdAt: ISO8601Timestamp;
+    updatedAt: ISO8601Timestamp;
+};
+/** The object returned by the BulkActions API */
+export interface BulkActionProps<TPayload extends BulkActionPayload = any> {
+    sys: BulkActionSysProps;
+    action: BulkActionType;
+    /** original payload when BulkAction was created */
+    payload: TPayload;
+    /** error information, if present */
+    error?: BulkActionFailedError;
+}
+export interface BulkActionApiMethods {
+    /** Performs a new GET request and returns the wrapper BulkAction */
+    get(): BulkAction;
+    /** Waits until the BulkAction is in one of the final states (`succeeded` or `failed`) and returns it. */
+    waitProcessing(options?: AsyncActionProcessingOptions): Promise<BulkAction>;
+}
+export interface BulkAction<T extends BulkActionPayload = any> extends BulkActionProps<T>, BulkActionApiMethods, DefaultElements<BulkActionProps<T>> {
+}
+/**
+ * @private
+ * @param makeRequest - function to make requests via an adapter
+ * @param data - Raw BulkAction data
+ * @return Wrapped BulkAction data
+ */
+export declare function wrapBulkAction<TPayload extends BulkActionPayload = any>(makeRequest: MakeRequest, data: BulkActionProps<BulkActionPayload>): BulkAction<TPayload>;
+export {};

package/dist/types/entities/bulk-action.js

@@ -0,0 +1,58 @@
+import { toPlainObject, freezeSys } from 'contentful-sdk-core';
+import copy from 'fast-copy';
+import enhanceWithMethods from '../enhance-with-methods.js';
+import { pollAsyncActionStatus } from '../methods/action.js';
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+/** Represents the state of the BulkAction */
+var BulkActionStatus;
+(function (BulkActionStatus) {
+    /** BulkAction is pending execution */
+    BulkActionStatus["created"] = "created";
+    /** BulkAction has been started and pending completion */
+    BulkActionStatus["inProgress"] = "inProgress";
+    /** BulkAction was completed successfully (terminal state) */
+    BulkActionStatus["succeeded"] = "succeeded";
+    /** BulkAction failed to complete (terminal state) */
+    BulkActionStatus["failed"] = "failed";
+})(BulkActionStatus || (BulkActionStatus = {}));
+Object.values(BulkActionStatus);
+/**
+ * @private
+ */
+function createBulkActionApi(makeRequest) {
+    const getParams = (self) => {
+        const bulkAction = self.toPlainObject();
+        return {
+            spaceId: bulkAction.sys.space.sys.id,
+            environmentId: bulkAction.sys.environment.sys.id,
+            bulkActionId: bulkAction.sys.id,
+        };
+    };
+    return {
+        async get() {
+            const params = getParams(this);
+            return makeRequest({
+                entityType: 'BulkAction',
+                action: 'get',
+                params,
+            }).then((bulkAction) => wrapBulkAction(makeRequest, bulkAction));
+        },
+        async waitProcessing(options) {
+            return pollAsyncActionStatus(async () => this.get(), options);
+        },
+    };
+}
+/**
+ * @private
+ * @param makeRequest - function to make requests via an adapter
+ * @param data - Raw BulkAction data
+ * @return Wrapped BulkAction data
+ */
+function wrapBulkAction(makeRequest, data) {
+    const bulkAction = toPlainObject(copy(data));
+    const bulkActionWithApiMethods = enhanceWithMethods(bulkAction, createBulkActionApi(makeRequest));
+    return freezeSys(bulkActionWithApiMethods);
+}
+
+export { BulkActionStatus, wrapBulkAction };

package/dist/types/entities/comment.d.ts

@@ -0,0 +1,102 @@
+import type { Node, Text } from '@contentful/rich-text-types';
+import type { BasicMetaSysProps, DefaultElements, GetCommentParams, GetEntryParams, GetSpaceEnvironmentParams, Link, MakeRequest, VersionedLink } from '../common-types.js';
+interface LinkWithReference<T extends string> extends Link<T> {
+    sys: Link<T>['sys'] & {
+        ref: string;
+    };
+}
+export type CommentSysProps = Pick<BasicMetaSysProps, 'id' | 'version' | 'createdAt' | 'createdBy' | 'updatedAt' | 'updatedBy'> & {
+    type: 'Comment';
+    space: Link<'Space'>;
+    environment: Link<'Environment'>;
+    parentEntity: Link<'ContentType'> | LinkWithReference<'ContentType'> | Link<'Entry'> | LinkWithReference<'Entry'> | VersionedLink<'Workflow'>;
+    parent: Link<'Comment'> | null;
+};
+export type PlainTextBodyProperty = 'plain-text';
+export type RichTextBodyProperty = 'rich-text';
+export type RichTextBodyFormat = {
+    bodyFormat: RichTextBodyProperty;
+};
+export type PlainTextBodyFormat = {
+    bodyFormat?: PlainTextBodyProperty;
+};
+export type CommentStatus = 'active' | 'resolved';
+export type CommentProps = {
+    sys: CommentSysProps;
+    body: string;
+    status: CommentStatus;
+};
+export type CreateCommentProps = Omit<CommentProps, 'sys' | 'status'> & {
+    status?: CommentStatus;
+};
+export type UpdateCommentProps = Omit<CommentProps, 'sys'> & {
+    sys: Pick<CommentSysProps, 'version'>;
+};
+export declare enum CommentNode {
+    Document = "document",
+    Paragraph = "paragraph",
+    Mention = "mention"
+}
+export interface Mention {
+    nodeType: CommentNode.Mention;
+    data: {
+        target: Link<'User'> | Link<'Team'>;
+    };
+    content: Text[];
+}
+export interface RootParagraph extends Node {
+    nodeType: CommentNode.Paragraph;
+    content: (Text | Mention)[];
+}
+export interface RichTextCommentDocument extends Node {
+    nodeType: CommentNode.Document;
+    content: RootParagraph[];
+}
+export type RichTextCommentBodyPayload = {
+    body: RichTextCommentDocument;
+};
+export type RichTextCommentProps = Omit<CommentProps, 'body'> & RichTextCommentBodyPayload;
+export type GetCommentParentEntityParams = GetSpaceEnvironmentParams & ({
+    parentEntityType: 'ContentType';
+    parentEntityId: string;
+    parentEntityReference?: string;
+} | {
+    parentEntityType: 'Entry';
+    parentEntityId: string;
+    parentEntityReference?: string;
+} | {
+    parentEntityType: 'Workflow';
+    parentEntityId: string;
+    parentEntityVersion?: number;
+});
+export type GetManyCommentsParams = (GetEntryParams | GetCommentParentEntityParams) & {
+    status?: CommentStatus;
+};
+export type CreateCommentParams = (GetEntryParams | GetCommentParentEntityParams) & {
+    parentCommentId?: string;
+};
+export type UpdateCommentParams = GetCommentParams;
+export type DeleteCommentParams = GetCommentParams & {
+    version: number;
+};
+type CommentApi = {
+    update(): Promise<Comment | RichTextComment>;
+    delete(): Promise<void>;
+};
+export interface Comment extends CommentProps, DefaultElements<CommentProps>, CommentApi {
+}
+export interface RichTextComment extends Omit<CommentProps, 'body'>, RichTextCommentProps, DefaultElements<CommentProps>, CommentApi {
+}
+/**
+ * @private
+ */
+export default function createCommentApi(makeRequest: MakeRequest): CommentApi;
+/**
+ * @private
+ */
+export declare function wrapComment(makeRequest: MakeRequest, data: CommentProps | RichTextCommentProps): Comment | RichTextComment;
+/**
+ * @private
+ */
+export declare const wrapCommentCollection: (makeRequest: MakeRequest, data: import("../common-types.js").CollectionProp<CommentProps | RichTextCommentProps>) => import("../common-types.js").Collection<Comment | RichTextComment, CommentProps | RichTextCommentProps>;
+export {};