@contentchef/contentchef-types 10.1.0-alpha.1 → 10.1.0-alpha.11

package/lib/api/ContentExportImport.ts

@@ -0,0 +1,564 @@
+import { AuthorResponse } from './Author';
+import { PagedListResponse } from './common';
+import { ContentId, ListContentsFilters } from './Content';
+
+/**
+ * The content export request unique id
+ */
+export type ContentExportRequestId = number;
+
+/**
+ * The content import request unique id
+ */
+export type ContentImportRequestId = number;
+
+/**
+ * The content import request item unique id
+ */
+export type ContentImportRequestItemId = number;
+
+/**
+ * This enum represent the file format of a content export, and the format an import file is read with
+ */
+export enum ContentExportFormat {
+    JSON = 'json',
+    CSV = 'csv'
+}
+
+/**
+ * This enum represent the lifecycle of a content export request. Exports are processed
+ * asynchronously, so a freshly created request is always `queued`
+ */
+export enum ContentExportStatus {
+    QUEUED = 'queued',
+    PROCESSING = 'processing',
+    COMPLETED = 'completed',
+    FAILED = 'failed'
+}
+
+/**
+ * This enum represent the lifecycle of a content import request. A freshly created request is
+ * `awaiting_upload` until the import file is uploaded to
+ * [[CreateContentImportRequestResponse.uploadUrl]], which is what starts the import
+ */
+export enum ContentImportStatus {
+    AWAITING_UPLOAD = 'awaiting_upload',
+    PROCESSING = 'processing',
+    COMPLETED = 'completed',
+    COMPLETED_WITH_ERRORS = 'completed_with_errors',
+    FAILED = 'failed'
+}
+
+/**
+ * This enum represent what an imported row describes: the content itself or one of its translations
+ */
+export enum ContentImportRowType {
+    CONTENT = 'content',
+    TRANSLATION = 'translation'
+}
+
+/**
+ * This enum represent the outcome of a single imported row
+ */
+export enum ContentImportItemStatus {
+    SUCCESS = 'success',
+    FAILED = 'failed'
+}
+
+/**
+ * This enum represent what the import did to the content of a successfully imported row
+ */
+export enum ContentImportItemAction {
+    UPDATED = 'updated'
+}
+
+/**
+ * This type represent the error attached to a failed content export or import request
+ */
+export type ContentExportImportError = {
+    /**
+     * The error type discriminator
+     */
+    type: string;
+    /**
+     * The human readable error message
+     */
+    message: string;
+};
+
+/**
+ * This type represent one of the files produced by a content export, one per exported content
+ * definition. The whole list is written when the export completes, so a `processing` export
+ * exposes no file yet
+ */
+export type ContentExportFile = {
+    /**
+     * The mnemonic id of the content definition the file contains the contents of
+     */
+    definitionMnemonicId: string;
+    /**
+     * The internal storage key of the file. Not fetchable as is, pass
+     * [[definitionMnemonicId]] to [[ContentExportImportFacade.downloadExport]] to get a
+     * downloadable url
+     */
+    s3Key: string;
+    /**
+     * The number of contents written in the file
+     */
+    itemCount: number;
+};
+
+/**
+ * This type represent the model of a content export request
+ */
+export type ContentExportRequestResponse = {
+    /**
+     * The content export request unique id
+     */
+    id: ContentExportRequestId;
+    /**
+     * The space the exported contents belong to
+     */
+    spaceId: string;
+    /**
+     * The current status of the export
+     */
+    status: ContentExportStatus;
+    /**
+     * The filters the exported contents have been selected with
+     */
+    filters: ListContentsFilters;
+    /**
+     * The format the export files are written in
+     */
+    format: ContentExportFormat;
+    /**
+     * The separator used by the exported csv files. Meaningless when [[format]] is `json`
+     */
+    csvSeparator: string;
+    /**
+     * The produced files, one per exported content definition. Empty until [[status]] is
+     * `completed`, the whole list is written in one go when the export finalizes
+     */
+    files: ContentExportFile[] | null;
+    /**
+     * The error describing why the export failed, null unless [[status]] is `failed`
+     */
+    error: ContentExportImportError | null;
+    /**
+     * The author that requested the export
+     */
+    author: AuthorResponse;
+    /**
+     * The last author that modified the export request. Only returned by
+     * [[ContentExportImportFacade.createExport]], the listing does not resolve it
+     */
+    latestContributor?: AuthorResponse;
+    /**
+     * The export request creation date
+     */
+    createdDate: Date;
+    /**
+     * The export request last modified date
+     */
+    lastModifiedDate: Date;
+};
+
+/**
+ * This type represent the data needed to make a create content export request API request
+ */
+export type CreateContentExportRequestRequest = {
+    /**
+     * The filters selecting the contents to export, the same ones accepted by
+     * [[ContentFacade.list]]. When omitted every unarchived content of the space is exported.
+     * [[ListContentsFilters.contentsStatus]] cannot be given: archived contents cannot be
+     * imported back, so an export always covers the unarchived ones only
+     */
+    filters?: Omit<Partial<ListContentsFilters>, 'contentsStatus'>;
+    /**
+     * The format to write the export files in, defaults to `json`
+     */
+    format?: ContentExportFormat;
+    /**
+     * The single character separator to write the exported csv files with, defaults to `,`.
+     * Ignored when [[format]] is `json`
+     */
+    csvSeparator?: string;
+};
+
+/**
+ * This type represent the response of a create content export request API request.
+ * The returned export is always `queued`: it is processed asynchronously
+ */
+export type CreateContentExportRequestResponse = ContentExportRequestResponse;
+
+/**
+ * This type represent the data needed to make a list content export requests API request
+ */
+export type ListContentExportRequestsRequest = {
+    /**
+     * The export requests to skip (used to paginate the result), defaults to 0
+     */
+    skip?: number;
+    /**
+     * The export requests to take (used to paginate the result), defaults to 20.
+     * Cannot exceed [[MAX_CONTENT_EXPORT_IMPORT_PAGE_SIZE]]
+     */
+    take?: number;
+};
+
+/**
+ * This type represent the response of a list content export requests API request,
+ * sorted by [[ContentExportRequestResponse.createdDate]] descending
+ */
+export type ListContentExportRequestsResponse = PagedListResponse<ContentExportRequestResponse>;
+
+/**
+ * This type represent the data needed to make a download content export API request
+ */
+export type DownloadContentExportRequest = {
+    /**
+     * The unique id of the completed export request to download a file of
+     */
+    exportRequestId: ContentExportRequestId;
+    /**
+     * The mnemonic id of the content definition whose exported file is wanted.
+     * It must be one of the [[ContentExportRequestResponse.files]] entries
+     */
+    definitionMnemonicId: string;
+};
+
+/**
+ * This type represent the response of a download content export API request
+ */
+export type DownloadContentExportResponse = {
+    /**
+     * The mnemonic id of the content definition the file contains the contents of
+     */
+    definitionMnemonicId: string;
+    /**
+     * The temporary url to download the exported file from. The client does not download the
+     * file, fetch this url yourself
+     */
+    downloadUrl: string;
+    /**
+     * The number of seconds [[downloadUrl]] stays valid for
+     */
+    expiresInSeconds: number;
+    /**
+     * The number of contents written in the file
+     */
+    itemCount: number;
+};
+
+/**
+ * This type represent the options a content import file is read with
+ */
+export type ContentImportOptions = {
+    /**
+     * The format the import file is read as
+     */
+    format: ContentExportFormat;
+    /**
+     * The separator the imported csv file is read with. Meaningless when [[format]] is `json`
+     */
+    csvSeparator?: string;
+    /**
+     * Whether payloads violating their content definition schema are applied anyway, with the
+     * violations logged instead of failing the row
+     */
+    skipPayloadValidation?: boolean;
+};
+
+/**
+ * This type represent the model of a content import request
+ */
+export type ContentImportRequestResponse = {
+    /**
+     * The content import request unique id
+     */
+    id: ContentImportRequestId;
+    /**
+     * The space the contents are imported in
+     */
+    spaceId: string;
+    /**
+     * The current status of the import
+     */
+    status: ContentImportStatus;
+    /**
+     * The name of the uploaded file, as declared when the import was created. Null when not declared
+     */
+    fileName: string | null;
+    /**
+     * The storage key the import file is expected at
+     */
+    s3Key: string;
+    /**
+     * The options the import file is read with
+     */
+    options: ContentImportOptions;
+    /**
+     * The arn of the workflow execution processing the import.
+     * Null while the import is still `awaiting_upload`
+     */
+    executionArn: string | null;
+    /**
+     * The number of rows found in the import file, null until the file has been read
+     */
+    totalItems: number | null;
+    /**
+     * The number of successfully imported rows, null until the import completes
+     */
+    succeededItems: number | null;
+    /**
+     * The number of rows that failed to import, null until the import completes.
+     * When greater than 0 the [[status]] is `completed_with_errors`
+     */
+    failedItems: number | null;
+    /**
+     * The error describing why the whole import failed, null unless [[status]] is `failed`.
+     * Single row failures are reported by [[ContentImportRequestItemResponse.error]] instead
+     */
+    error: ContentExportImportError | null;
+    /**
+     * The author that requested the import
+     */
+    author: AuthorResponse;
+    /**
+     * The import request creation date
+     */
+    createdDate: Date;
+    /**
+     * The import request last modified date
+     */
+    lastModifiedDate: Date;
+};
+
+/**
+ * This type represent the data needed to make a create content import request API request
+ */
+export type CreateContentImportRequestRequest = {
+    /**
+     * The name of the file about to be uploaded, kept for display purposes only
+     */
+    fileName?: string;
+    /**
+     * The options to read the uploaded file with
+     */
+    options?: {
+        /**
+         * The format the uploaded file is read as, defaults to `json`
+         */
+        format?: ContentExportFormat;
+        /**
+         * The single character separator the uploaded csv file is read with, defaults to `,`.
+         * Ignored when [[format]] is `json`
+         */
+        csvSeparator?: string;
+        /**
+         * Whether to apply payloads that violate their content definition schema, recording the
+         * violations instead of failing the row. Defaults to false.
+         * [[ContentExportImportFacade.retryImport]] can turn it on for an already uploaded file
+         */
+        skipPayloadValidation?: boolean;
+    };
+};
+
+/**
+ * This type represent the response of a create content import request API request
+ */
+export type CreateContentImportRequestResponse = {
+    /**
+     * The created content import request unique id
+     */
+    importRequestId: ContentImportRequestId;
+    /**
+     * The storage key the file is uploaded to
+     */
+    s3Key: string;
+    /**
+     * The temporary url to upload the import file to, with a `PUT` and a `Content-Type` of
+     * `text/csv` or `application/json` matching the requested format. The client does not upload
+     * the file, upload it yourself: the upload is what starts the import
+     */
+    uploadUrl: string;
+    /**
+     * The number of seconds [[uploadUrl]] stays valid for
+     */
+    expiresInSeconds: number;
+};
+
+/**
+ * This type represent the data needed to make a retry content import API request
+ */
+export type RetryContentImportRequest = {
+    /**
+     * The unique id of the import request to re-run the file of. It must have been uploaded:
+     * an import still `awaiting_upload` has nothing to retry
+     */
+    importRequestId: ContentImportRequestId;
+    /**
+     * Whether to apply payloads that violate their content definition schema, recording the
+     * violations instead of failing the row. Use it to push through a run whose validation
+     * failures have been judged acceptable. Defaults to false
+     */
+    skipPayloadValidation?: boolean;
+};
+
+/**
+ * This type represent the response of a retry content import API request.
+ * A retry is a new import request re-running the whole original file, not only its failed rows:
+ * imports are update only and idempotent. Nothing has to be uploaded again, the file is copied
+ * server side, and that copy is what starts the new import
+ */
+export type RetryContentImportResponse = {
+    /**
+     * The unique id of the created import request, the one to follow from now on
+     */
+    importRequestId: ContentImportRequestId;
+    /**
+     * The unique id of the import request being retried
+     */
+    retryOf: ContentImportRequestId;
+    /**
+     * The storage key the original file has been copied to
+     */
+    s3Key: string;
+    /**
+     * Whether the retry applies payloads violating their content definition schema
+     */
+    skipPayloadValidation: boolean;
+};
+
+/**
+ * This type represent the data needed to make a list content import requests API request
+ */
+export type ListContentImportRequestsRequest = {
+    /**
+     * The import requests to skip (used to paginate the result), defaults to 0
+     */
+    skip?: number;
+    /**
+     * The import requests to take (used to paginate the result), defaults to 20.
+     * Cannot exceed [[MAX_CONTENT_EXPORT_IMPORT_PAGE_SIZE]]
+     */
+    take?: number;
+};
+
+/**
+ * This type represent the response of a list content import requests API request,
+ * sorted by [[ContentImportRequestResponse.createdDate]] descending
+ */
+export type ListContentImportRequestsResponse = PagedListResponse<ContentImportRequestResponse>;
+
+/**
+ * This type represent the error attached to a single failed imported row
+ */
+export type ContentImportItemError = {
+    /**
+     * The error code discriminator
+     */
+    code: string;
+    /**
+     * The human readable error message
+     */
+    message?: string;
+    /**
+     * The error additional details, their shape depends on [[code]]
+     */
+    details?: any;
+};
+
+/**
+ * This type represent the outcome of a single row of a content import. One item is written per
+ * content row plus one per translation row, so a content with 3 translated locales produces 4 items
+ */
+export type ContentImportRequestItemResponse = {
+    /**
+     * The content import request item unique id
+     */
+    id: ContentImportRequestItemId;
+    /**
+     * The space the contents are imported in
+     */
+    spaceId: string;
+    /**
+     * The unique id of the import request the item belongs to
+     */
+    importRequestId: ContentImportRequestId;
+    /**
+     * The zero based position of the row in the import file
+     */
+    itemIndex: number;
+    /**
+     * The public id of the imported content, null when the row did not carry a readable one
+     */
+    publicId: string | null;
+    /**
+     * The mnemonic id of the imported content definition, null when the row did not carry a
+     * readable one
+     */
+    definitionMnemonicId: string | null;
+    /**
+     * Whether the row describes the content itself or one of its translations
+     */
+    rowType: ContentImportRowType;
+    /**
+     * The locale the row has been imported in. Always null when [[rowType]] is `content`:
+     * only translation rows are locale specific
+     */
+    locale: string | null;
+    /**
+     * What the import did to the content. Null when the row failed, and on a translation row
+     * that carried nothing to apply, which succeeds as a no-op
+     */
+    action: ContentImportItemAction | null;
+    /**
+     * The outcome of the row
+     */
+    status: ContentImportItemStatus;
+    /**
+     * The unique id of the imported content, null when the row failed before the content
+     * could be resolved
+     */
+    contentId: ContentId | null;
+    /**
+     * The error describing why the row failed, null unless [[status]] is `failed`
+     */
+    error: ContentImportItemError | null;
+};
+
+/**
+ * This type represent the data needed to make a list content import request items API request
+ */
+export type ListContentImportRequestItemsRequest = {
+    /**
+     * The unique id of the import request to list the items of
+     */
+    importRequestId: ContentImportRequestId;
+    /**
+     * The items to skip (used to paginate the result), defaults to 0
+     */
+    skip?: number;
+    /**
+     * The items to take (used to paginate the result), defaults to 50.
+     * Cannot exceed [[MAX_CONTENT_EXPORT_IMPORT_PAGE_SIZE]]
+     */
+    take?: number;
+    /**
+     * This filter is used to list only the items with the given outcome, typically `failed` to
+     * review what an import could not apply. When omitted every item is returned
+     */
+    status?: ContentImportItemStatus;
+};
+
+/**
+ * This type represent the response of a list content import request items API request
+ */
+export type ListContentImportRequestItemsResponse = PagedListResponse<ContentImportRequestItemResponse>;
+
+/**
+ * The maximum number of items a content export or import list API request can take in a single page
+ */
+export const MAX_CONTENT_EXPORT_IMPORT_PAGE_SIZE = 100;