@kontent-ai/migration-toolkit 1.0.0

package/lib/core/models/core.models.ts

@@ -0,0 +1,134 @@
+import {
+    AssetModels,
+    ContentItemModels,
+    ContentTypeElements,
+    LanguageVariantModels,
+    WorkflowModels
+} from '@kontent-ai/management-sdk';
+import { MigrationElementType } from './migration.models.js';
+import { WorkflowStep } from '../helpers/workflow-helper.js';
+
+export type TargetItemState = 'exists' | 'doesNotExists';
+export type CliAction = 'export' | 'import' | 'migrate';
+export type GeneralItemType = 'exportedItem' | 'migrationItem';
+export type GeneralActionType = 'readFs' | 'skip' | 'writeFs' | 'download';
+export type EnvContext = 'browser' | 'node';
+
+export type MapiAction =
+    | 'list'
+    | 'view'
+    | 'archive'
+    | 'unpublish'
+    | 'changeWorkflowStep'
+    | 'publish'
+    | 'upload'
+    | 'create'
+    | 'upsert'
+    | 'createNewVersion';
+
+export type MapiType =
+    | 'contentType'
+    | 'asset'
+    | 'contentTypeSnippet'
+    | 'contentItem'
+    | 'languageVariant'
+    | 'language'
+    | 'collection'
+    | 'taxonomy'
+    | 'binaryFile'
+    | 'workflow';
+
+export interface ItemInfo {
+    readonly title: string;
+    readonly itemType: GeneralItemType | MapiType;
+}
+
+export interface ErrorData {
+    readonly message: string;
+    readonly requestData?: string;
+    readonly requestUrl?: string;
+    readonly isUnknownError: boolean;
+    readonly error: unknown;
+}
+
+export interface ReferencedDataInMigrationItems {
+    readonly itemCodenames: ReadonlySet<string>;
+    readonly assetCodenames: ReadonlySet<string>;
+}
+
+export interface ReferencedDataInLanguageVariants {
+    readonly itemIds: ReadonlySet<string>;
+    readonly assetIds: ReadonlySet<string>;
+}
+
+export interface ItemStateInSourceEnvironmentById {
+    readonly state: TargetItemState;
+    readonly id: string;
+    readonly item: Readonly<ContentItemModels.ContentItem> | undefined;
+}
+
+export interface AssetStateInSourceEnvironmentById {
+    readonly state: TargetItemState;
+    readonly id: string;
+    readonly asset: Readonly<AssetModels.Asset> | undefined;
+}
+
+export interface ItemStateInTargetEnvironmentByCodename {
+    readonly state: TargetItemState;
+    readonly itemCodename: string;
+    readonly item: Readonly<ContentItemModels.ContentItem> | undefined;
+    readonly externalIdToUse: string;
+}
+
+export interface LanguageVariantStateInTargetEnvironmentByCodename {
+    readonly state: TargetItemState;
+    readonly itemCodename: string;
+    readonly languageCodename: string;
+    readonly languageVariant: Readonly<LanguageVariantModels.ContentItemLanguageVariant> | undefined;
+    readonly workflow: Readonly<WorkflowModels.Workflow> | undefined;
+    readonly step: Readonly<WorkflowStep> | undefined;
+}
+
+export interface AssetStateInTargetEnvironmentByCodename {
+    readonly state: TargetItemState;
+    readonly assetCodename: string;
+    readonly asset: Readonly<AssetModels.Asset> | undefined;
+    readonly externalIdToUse: string;
+}
+
+export interface PackageMetadata {
+    readonly created: Date;
+    readonly environmentId: string;
+    readonly dataOverview: PackageDataOverview;
+}
+
+export interface PackageDataOverview {
+    readonly contentItemsCount: number;
+    readonly assetsCount: number;
+}
+
+export interface FlattenedContentTypeElement {
+    readonly codename: string;
+    readonly id: string;
+    readonly type: MigrationElementType;
+    readonly element: Readonly<ContentTypeElements.ContentTypeElementModel>;
+}
+
+export interface FlattenedContentType {
+    readonly contentTypeCodename: string;
+    readonly contentTypeId: string;
+    readonly elements: readonly FlattenedContentTypeElement[];
+}
+
+export interface OriginalManagementError {
+    response?: {
+        status?: number;
+        config?: {
+            url?: string;
+            data?: string;
+        };
+        data?: {
+            error_code?: number;
+        };
+    };
+}

package/lib/core/models/log.models.ts

@@ -0,0 +1,31 @@
+import { GeneralActionType, GeneralItemType, MapiAction, MapiType } from '../index.js';
+
+export type DebugType =
+    | 'error'
+    | 'completed'
+    | 'warning'
+    | 'info'
+    | 'errorData'
+    | 'cancel'
+    | 'process'
+    | MapiType
+    | GeneralActionType
+    | MapiAction
+    | GeneralItemType;
+
+export interface LogMessage {
+    readonly type: DebugType;
+    readonly message: string;
+}
+
+export interface LogSpinnerMessage extends LogMessage {
+    readonly prefix?: string;
+}
+
+export type LogData = (data: LogMessage) => void;
+export type LogSpinnerData = (data: LogSpinnerMessage) => void;
+
+export interface Logger {
+    readonly logWithSpinnerAsync: <T>(func: (logData: LogSpinnerData) => Promise<T>) => Promise<T>;
+    readonly log: LogData;
+}

package/lib/core/models/migration.models.ts

@@ -0,0 +1,165 @@
+export type MigrationElementType =
+    | 'text'
+    | 'rich_text'
+    | 'number'
+    | 'multiple_choice'
+    | 'date_time'
+    | 'asset'
+    | 'modular_content'
+    | 'taxonomy'
+    | 'url_slug'
+    | 'custom'
+    | 'subpages';
+
+export type MigrationUrlSlugMode = 'autogenerated' | 'custom';
+
+export interface MigrationRichTextElementValue {
+    value: string;
+    components: readonly MigrationComponent[];
+}
+
+export interface MigrationUrlSlugElementValue {
+    value: string | undefined;
+    mode: MigrationUrlSlugMode;
+}
+
+export interface MigrationComponent {
+    system: {
+        id: string;
+        type: MigrationReference;
+    };
+    elements: MigrationElements;
+}
+
+export type MigrationElementValue =
+    | string
+    | undefined
+    | MigrationReference[]
+    | number
+    | MigrationRichTextElementValue
+    | MigrationUrlSlugElementValue;
+
+export interface MigrationElement<
+    TElementType extends MigrationElementType = MigrationElementType,
+    TValue extends MigrationElementValue = MigrationElementValue
+> {
+    /**
+     * Value of the element
+     */
+    readonly value: TValue;
+
+    /**
+     * Type of the element
+     */
+    readonly type: TElementType;
+}
+
+export namespace MigrationElementModels {
+    export interface TextElement extends MigrationElement<'text', string | undefined> {}
+    export interface NumberElement extends MigrationElement<'number', number | undefined> {}
+    export interface RichTextElement extends MigrationElement<'rich_text', MigrationRichTextElementValue | undefined> {}
+    export interface MultipleChoiceElement
+        extends MigrationElement<'multiple_choice', MigrationReference[] | undefined> {}
+    export interface DateTimeElement extends MigrationElement<'date_time', string | undefined> {}
+    export interface AssetElement extends MigrationElement<'asset', MigrationReference[] | undefined> {}
+    export interface LinkedItemsElement extends MigrationElement<'modular_content', MigrationReference[] | undefined> {}
+    export interface TaxonomyElement extends MigrationElement<'taxonomy', MigrationReference[] | undefined> {}
+    export interface UrlSlugElement extends MigrationElement<'url_slug', MigrationUrlSlugElementValue | undefined> {}
+    export interface CustomElement extends MigrationElement<'custom', string | undefined> {}
+    export interface SubpagesElement extends MigrationElement<'subpages', MigrationReference[] | undefined> {}
+}
+
+export interface MigrationElements {
+    [elementCodename: string]: MigrationElement;
+}
+
+export interface MigrationItemVersion<TElements extends MigrationElements = MigrationElements> {
+    readonly elements: TElements;
+    readonly workflow_step: MigrationReference;
+}
+
+export interface MigrationItem<TElements extends MigrationElements = MigrationElements> {
+    readonly system: {
+        /**
+         * Codename of the content item
+         */
+        readonly codename: string;
+        /**
+         * Name of the content item
+         */
+        readonly name: string;
+        /**
+         * Language of the language variant
+         */
+        readonly language: MigrationReference;
+        /**
+         * Content type of the item
+         */
+        readonly type: MigrationReference;
+        /**
+         * Collection of the item
+         */
+        readonly collection: MigrationReference;
+
+        /**
+         * Workflow of the item
+         */
+        readonly workflow: MigrationReference;
+    };
+    readonly versions: MigrationItemVersion<TElements>[];
+}
+
+export interface MigrationReference {
+    /**
+     * Codename of the referenced object
+     */
+    readonly codename: string;
+}
+
+export interface MigrationAssetDescription {
+    readonly language: MigrationReference;
+    readonly description?: string;
+}
+
+export interface MigrationAsset {
+    /**
+     * Codename of the asset
+     */
+    readonly codename: string;
+    /**
+     * Binary data of the asset
+     */
+    readonly binaryData: Buffer | Blob;
+    /**
+     * Filename of the asset, will be used as a filename in Kontent.ai after importing the asset
+     */
+    readonly filename: string;
+    /**
+     * Title of the asset
+     */
+    readonly title: string;
+
+    /**
+     * Optional
+     * Collection of the asset
+     */
+    readonly collection?: MigrationReference;
+
+    /**
+     * Optional.
+     * Descriptions of the assets
+     */
+    readonly descriptions?: readonly MigrationAssetDescription[];
+}
+
+export interface MigrationData {
+    /**
+     * Array of migration items to process (export / import)
+     */
+    readonly items: readonly MigrationItem[];
+
+    /**
+     * Array of migration assets to process
+     */
+    readonly assets: readonly MigrationAsset[];
+}

package/lib/core/utils/array.utils.ts

@@ -0,0 +1,49 @@
+import { MigrationElementValue, MigrationReference } from '../models/migration.models.js';
+
+export function parseAsMigrationReferencesArray(value: MigrationElementValue): readonly MigrationReference[] {
+    if (!value) {
+        return [];
+    }
+    if (Array.isArray(value)) {
+        return value;
+    }
+    throw Error(`Value is not an array`);
+}
+
+export function findRequired<T>(
+    array: readonly T[],
+    predicate: (item: T, index: number) => boolean,
+    errorMessage: string
+): T;
+export function findRequired<T>(
+    array: readonly T[],
+    predicate: (item: T, index: number) => boolean,
+    errorMessage: () => never
+): T;
+export function findRequired<T>(
+    array: readonly T[],
+    predicate: (item: T, index: number) => boolean,
+    errorMessage: string | (() => never)
+): T {
+    const item = array.find(predicate);
+
+    if (item) {
+        return item;
+    }
+
+    if (typeof errorMessage === 'string' || errorMessage instanceof String) {
+        throw Error(errorMessage.toString());
+    }
+    return errorMessage();
+}
+
+export async function mapAsync<Input, Result>(
+    array: readonly Input[],
+    callbackAsync: (item: Readonly<Input>, index: number, array: readonly Input[]) => Promise<Readonly<Result>>
+): Promise<Readonly<Result[]>> {
+    const results: Result[] = [];
+    for (let i = 0; i < array.length; i++) {
+        results.push(await callbackAsync(array[i], i, array));
+    }
+    return results;
+}

package/lib/core/utils/binary-data.utils.ts

@@ -0,0 +1,29 @@
+import { defaultHttpService, defaultRetryStrategy } from './http.utils.js';
+
+export async function getBinaryDataFromUrlAsync(url: string): Promise<{ data: Buffer | Blob; contentLength: number }> {
+    // temp fix for Kontent.ai Repository not validating url
+    url = url.replace('#', '%23');
+
+    const response = await defaultHttpService.getAsync<Buffer | Blob>(
+        {
+            url
+        },
+        {
+            responseType: 'arraybuffer',
+            retryStrategy: defaultRetryStrategy
+        }
+    );
+
+    const contentLengthHeader = response.headers.find((m) => m.header.toLowerCase() === 'content-length');
+    const contentLength = contentLengthHeader ? +contentLengthHeader.value : 0;
+
+    return { data: response.data, contentLength: contentLength };
+}
+
+export function geSizeInBytes(data: Blob | Buffer): number {
+    if (data instanceof Blob) {
+        return data.size;
+    }
+
+    return data.byteLength;
+}

package/lib/core/utils/confirm.utils.ts

@@ -0,0 +1,139 @@
+import chalk from 'chalk';
+import { Logger } from '../models/log.models.js';
+import { getMigrationManagementClient, managementClientUtils } from './management-client-utils.js';
+
+export async function confirmExportAsync(data: {
+    readonly force: boolean;
+    readonly environmentId: string;
+    readonly apiKey: string;
+    readonly logger: Logger;
+    readonly dataToExport: {
+        readonly itemsCount: number;
+    };
+}): Promise<void> {
+    const environment = await managementClientUtils(
+        getMigrationManagementClient({
+            environmentId: data.environmentId,
+            apiKey: data.apiKey
+        }),
+        data.logger
+    ).getEnvironmentAsync();
+
+    const text: string = `Are you sure to export '${chalk.cyan(
+        data.dataToExport.itemsCount
+    )}' content ${getItemsPluralText(data.dataToExport.itemsCount)} from ${chalk.yellow(
+        environment.name
+    )} (${chalk.yellow(environment.environment)}?`;
+
+    await confirmAsync({
+        force: data.force,
+        logger: data.logger,
+        action: 'Export',
+        message: text
+    });
+}
+
+export async function confirmMigrateAsync(data: {
+    readonly force: boolean;
+    readonly sourceEnvironment: {
+        readonly environmentId: string;
+        readonly apiKey: string;
+    };
+    readonly targetEnvironment: {
+        readonly environmentId: string;
+        readonly apiKey: string;
+    };
+    readonly logger: Logger;
+    readonly dataToMigrate: {
+        readonly itemsCount: number;
+    };
+}): Promise<void> {
+    const sourceEnvironment = await managementClientUtils(
+        getMigrationManagementClient({
+            environmentId: data.sourceEnvironment.environmentId,
+            apiKey: data.sourceEnvironment.apiKey
+        }),
+        data.logger
+    ).getEnvironmentAsync();
+    const targetEnvironment = await managementClientUtils(
+        getMigrationManagementClient({
+            environmentId: data.targetEnvironment.environmentId,
+            apiKey: data.targetEnvironment.apiKey
+        }),
+        data.logger
+    ).getEnvironmentAsync();
+
+    const text: string = `Are you sure to migrate '${chalk.cyan(data.dataToMigrate.itemsCount)}' ${getItemsPluralText(
+        data.dataToMigrate.itemsCount
+    )} from ${chalk.yellow(sourceEnvironment.name)} (${chalk.yellow(
+        sourceEnvironment.environment
+    )}) to environment ${chalk.yellow(targetEnvironment.name)} (${chalk.yellow(targetEnvironment.environment)}) ?`;
+
+    await confirmAsync({
+        force: data.force,
+        logger: data.logger,
+        action: 'Migrate',
+        message: text
+    });
+}
+
+export async function confirmImportAsync(data: {
+    readonly force: boolean;
+    readonly environmentId: string;
+    readonly apiKey: string;
+    readonly logger: Logger;
+}): Promise<void> {
+    const environment = await managementClientUtils(
+        getMigrationManagementClient({
+            environmentId: data.environmentId,
+            apiKey: data.apiKey
+        }),
+        data.logger
+    ).getEnvironmentAsync();
+
+    const text: string = `Are you sure to import data into ${chalk.yellow(environment.name)} (${chalk.yellow(
+        environment.environment
+    )})?`;
+
+    await confirmAsync({
+        force: data.force,
+        logger: data.logger,
+        action: 'Import',
+        message: text
+    });
+}
+
+async function confirmAsync(data: {
+    readonly action: string;
+    readonly message: string;
+    readonly force: boolean;
+    readonly logger: Logger;
+}): Promise<void> {
+    // Prompts is imported dynamically because it's a node.js only module and would not work if user
+    // tried using this library in a browser
+    const prompts = await import('prompts');
+
+    if (data.force) {
+        data.logger.log({
+            type: 'info',
+            message: `Skipping confirmation prompt due to the use of 'force' param`
+        });
+    } else {
+        const confirmed = await prompts.default({
+            type: 'confirm',
+            name: 'confirm',
+            message: `${chalk.cyan(data.action)}: ${data.message}`
+        });
+
+        if (!confirmed.confirm) {
+            throw Error(`Confirmation refused.`);
+        }
+    }
+}
+
+function getItemsPluralText(count: number): string {
+    if (count === 1) {
+        return 'item';
+    }
+    return 'items';
+}

package/lib/core/utils/error.utils.ts

@@ -0,0 +1,65 @@
+import { SharedModels } from '@kontent-ai/management-sdk';
+import chalk from 'chalk';
+import { ErrorData, OriginalManagementError } from '../models/core.models.js';
+
+export function extractErrorData(error: unknown): ErrorData {
+    let isUnknownError: boolean = true;
+    let message: string = `Unknown error`;
+    let requestUrl: string | undefined = undefined;
+    let requestData: string | undefined = undefined;
+
+    if (error instanceof SharedModels.ContentManagementBaseKontentError) {
+        isUnknownError = false;
+        message = `${error.message}`;
+
+        const originalError: OriginalManagementError | undefined = error.originalError as
+            | OriginalManagementError
+            | undefined;
+
+        requestUrl = originalError?.response?.config?.url;
+        requestData = originalError?.response?.config?.data;
+        message += error.validationErrors.map((m) => m.message).join(', ');
+    } else if (error instanceof Error) {
+        message = error.message;
+    }
+
+    const errorData: ErrorData = {
+        message: message,
+        requestData: requestData,
+        requestUrl: requestUrl,
+        error: error,
+        isUnknownError: isUnknownError
+    };
+
+    return errorData;
+}
+
+export function is404Error(error: unknown): boolean {
+    if (error instanceof SharedModels.ContentManagementBaseKontentError) {
+        const originalError = error.originalError as OriginalManagementError | undefined;
+
+        if (originalError?.response?.status === 404) {
+            return true;
+        }
+    }
+
+    return false;
+}
+
+export function handleError(error: unknown): void {
+    const errorData = extractErrorData(error);
+
+    if (errorData.isUnknownError) {
+        console.error(error);
+    }
+
+    if (errorData.requestData) {
+        console.log(`${chalk.red('Request data')}: ${errorData.requestData}`);
+    }
+
+    if (errorData.requestUrl) {
+        console.log(`${chalk.red('Request url')}: ${errorData.requestUrl}`);
+    }
+
+    console.error(`${chalk.red('Error:')} ${errorData.message}`);
+}

package/lib/core/utils/external-id.utils.ts

@@ -0,0 +1,9 @@
+export interface ExternalIdGenerator {
+    readonly assetExternalId: (codename: string) => string;
+    readonly contentItemExternalId: (codename: string) => string;
+}
+
+export const defaultExternalIdGenerator: ExternalIdGenerator = {
+    assetExternalId: (codename) => `asset_${codename}`,
+    contentItemExternalId: (codename) => `item_${codename}`
+};

package/lib/core/utils/global.utils.ts

@@ -0,0 +1,59 @@
+import { format } from 'bytes';
+import { ITrackingEventData, getTrackingService } from '@kontent-ai-consulting/tools-analytics';
+import { isBrowser, isNode, isWebWorker } from 'browser-or-node';
+import { EnvContext } from '../models/core.models.js';
+
+export const isNotUndefined = <T>(item: T | undefined): item is T => item !== undefined;
+
+export function formatBytes(bytes: number): string {
+    return format(bytes);
+}
+
+export function sleepAsync(ms: number): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export function exitProgram(data: { readonly message: string }): never {
+    throw Error(data.message);
+}
+
+export function getCurrentEnvironment(): EnvContext {
+    if (isNode) {
+        return 'node';
+    }
+    if (isBrowser || isWebWorker) {
+        return 'browser';
+    }
+
+    throw Error(`Invalid current environment. This library can be used in node.js or in browsers.`);
+}
+
+export function getDefaultZipFilename(): string {
+    return `data.zip`;
+}
+
+export async function executeWithTrackingAsync<TResult>(data: {
+    func: () => Promise<TResult extends void ? void : Readonly<TResult>>;
+    event: Readonly<ITrackingEventData>;
+}): Promise<TResult extends void ? void : Readonly<TResult>> {
+    const trackingService = getTrackingService();
+    const event = await trackingService.trackEventAsync(data.event);
+
+    try {
+        const result = await data.func();
+
+        await trackingService.setEventResultAsync({
+            eventId: event.eventId,
+            result: 'success'
+        });
+
+        return result;
+    } catch (error) {
+        await trackingService.setEventResultAsync({
+            eventId: event.eventId,
+            result: 'fail'
+        });
+
+        throw error;
+    }
+}