@kontent-ai/migration-toolkit 1.0.0

package/lib/node/cli/app.ts

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+import chalk from 'chalk';
+
+import { handleError, exitProgram } from '../../core/index.js';
+import { exportActionAsync } from './actions/export-action.js';
+import { importActionAsync } from './actions/import-action.js';
+import { migrateActionAsync } from './actions/migrate-action.js';
+import { argumentsFetcherAsync } from './args/args-fetcher.js';
+
+const run = async () => {
+    const argsFetcher = await argumentsFetcherAsync();
+    const action = argsFetcher.getCliAction();
+
+    if (action === 'export') {
+        return await exportActionAsync(argsFetcher);
+    } else if (action === 'import') {
+        return await importActionAsync(argsFetcher);
+    } else if (action === 'migrate') {
+        return await migrateActionAsync(argsFetcher);
+    }
+
+    exitProgram({
+        message: `Invalid action '${chalk.red(action)}'`
+    });
+};
+
+run().catch((err) => {
+    handleError(err);
+});

package/lib/node/cli/args/args-fetcher.ts

@@ -0,0 +1,61 @@
+import yargs from 'yargs';
+import { hideBin } from 'yargs/helpers';
+import chalk from 'chalk';
+import { CliAction, exitProgram } from '../../../core/index.js';
+import { CliArgumentsFetcher } from '../cli.models.js';
+
+type ArgvResult = {
+    [x: string]: unknown;
+    _: (string | number)[];
+    $0: string;
+};
+
+export async function argumentsFetcherAsync(): Promise<CliArgumentsFetcher> {
+    const argv = yargs(hideBin(process.argv));
+    const resolvedArgv: ArgvResult = await argv.argv;
+
+    const getOptionalArgumentValue = (argName: string) => {
+        return resolvedArgv[argName]?.toString();
+    };
+
+    return {
+        getCliAction(): CliAction {
+            const command = resolvedArgv._?.[0]?.toString()?.toLowerCase();
+
+            if (command === <CliAction>'export') {
+                return 'export';
+            }
+            if (command === <CliAction>'import') {
+                return 'import';
+            }
+            if (command === <CliAction>'migrate') {
+                return 'migrate';
+            }
+
+            throw Error(`Unsupported command '${chalk.yellow(command)}'`);
+        },
+        getOptionalArgumentValue(argName: string): string | undefined {
+            return resolvedArgv[argName]?.toString();
+        },
+        getRequiredArgumentValue(argName: string): string {
+            const value = getOptionalArgumentValue(argName);
+
+            if (!value) {
+                exitProgram({
+                    message: `Missing '${chalk.yellow(argName)}' argument value`
+                });
+            }
+
+            return value;
+        },
+        getBooleanArgumentValue(argName: string, defaultValue: boolean): boolean {
+            const value = getOptionalArgumentValue(argName);
+
+            if (!value) {
+                return defaultValue;
+            }
+
+            return value.toLowerCase() === 'true'.toLowerCase();
+        }
+    };
+}

package/lib/node/cli/args/args-setter.ts

@@ -0,0 +1,35 @@
+import yargs from 'yargs';
+import { hideBin } from 'yargs/helpers';
+import { CliArgumentsSetter, Command, CommandOption } from '../cli.models.js';
+
+export function argumentsSetter(): CliArgumentsSetter {
+    const argv = yargs(hideBin(process.argv));
+
+    return {
+        withCommand(command: Command): CliArgumentsSetter {
+            argv.command(command.name, command.description, (yargs) => {
+                command.examples.forEach((example) => yargs.example(command.name, example));
+                command.options.forEach((option) => {
+                    yargs.positional(option.name, {
+                        alias: option.alias,
+                        describe: option.description,
+                        type: option.type,
+                        demandOption: option.isRequired
+                    });
+                });
+            });
+
+            return this;
+        },
+        withOption(option: CommandOption): CliArgumentsSetter {
+            argv.option(option.name, {
+                alias: option.alias,
+                description: option.description,
+                type: option.type,
+                demandOption: option.isRequired
+            });
+
+            return this;
+        }
+    };
+}

package/lib/node/cli/cli.models.ts

@@ -0,0 +1,28 @@
+import { CliAction } from '../../core/index.js';
+
+export interface Command {
+    readonly name: string;
+    readonly description: string;
+    readonly options: readonly CommandOption[];
+    readonly examples: string[];
+}
+
+export interface CommandOption {
+    readonly name: string;
+    readonly isRequired: boolean;
+    readonly alias?: string;
+    readonly description?: string;
+    readonly type?: 'boolean' | 'number' | 'string';
+}
+
+export type CliArgumentsSetter = {
+    withCommand(command: Command): CliArgumentsSetter;
+    withOption(option: CommandOption): CliArgumentsSetter;
+};
+
+export type CliArgumentsFetcher = {
+    getCliAction(): CliAction;
+    getOptionalArgumentValue(argName: string): string | undefined;
+    getRequiredArgumentValue(argName: string): string;
+    getBooleanArgumentValue(argName: string, defaultValue: boolean): boolean;
+};

package/lib/node/cli/commands.ts

@@ -0,0 +1,161 @@
+import { argumentsSetter } from './args/args-setter.js';
+
+export const cliArgs = argumentsSetter()
+    .withCommand({
+        name: 'export',
+        description: 'Exports content (items & assets) from Kontent.ai environment',
+        examples: [
+            `kontent-ai-migration-toolkit export --sourceEnvironmentId=x --sourceApiKey=x --language=default --items=itemA,itemB`
+        ],
+        options: [
+            {
+                name: `sourceApiKey`,
+                description: `Api key used for request authorization`,
+                type: 'string',
+                isRequired: true
+            },
+            {
+                name: `sourceEnvironmentId`,
+                description: `Environment id of the source environment`,
+                type: 'string',
+                isRequired: true
+            },
+            {
+                name: `language`,
+                description: `Language codename of items to export`,
+                type: 'string',
+                isRequired: true
+            },
+            {
+                name: `items`,
+                description: `Comma separated item codenames to export`,
+                type: 'string',
+                isRequired: true
+            },
+            {
+                name: `filename`,
+                description: `Name of items file to export / import`,
+                type: 'string',
+                isRequired: false
+            },
+            {
+                name: `assetsFilename`,
+                description: `Name of assets file to export / import`,
+                type: 'string',
+                isRequired: false
+            },
+            {
+                name: `baseUrl`,
+                description: `Custom base URL`,
+                type: 'string',
+                isRequired: false
+            }
+        ]
+    })
+
+    .withCommand({
+        name: 'import',
+        description: 'Imports content (items & assets) into Kontent.ai environment',
+        examples: [
+            `kontent-ai-migration-toolkit import --targetEnvironmentId=x --targetApiKey=x --filename=items.zip --assetsFilename=assets.zip`
+        ],
+        options: [
+            {
+                name: `targetApiKey`,
+                description: `Api key used for request authorization`,
+                type: 'string',
+                isRequired: true
+            },
+            {
+                name: `targetEnvironmentId`,
+                description: `Environment id of the target environment`,
+                type: 'string',
+                isRequired: true
+            },
+            {
+                name: `filename`,
+                description: `Name of items file to export / import`,
+                type: 'string',
+                isRequired: false
+            },
+            {
+                name: `assetsFilename`,
+                description: `Name of assets file to export / import`,
+                type: 'string',
+                isRequired: false
+            },
+            {
+                name: `baseUrl`,
+                description: `Custom base URL`,
+                type: 'string',
+                isRequired: false
+            }
+        ]
+    })
+
+    .withCommand({
+        name: 'migrate',
+        description:
+            'Migrates content (items & assets) from one Kontent.ai environment into another Kontent.ai environment',
+        examples: [
+            `kontent-ai-migration-toolkit migrate --targetEnvironmentId=x --targetApiKey=x --sourceEnvironmentId=x --sourceApiKey=x --language=default --items=itemA,itemB`
+        ],
+        options: [
+            {
+                name: `sourceApiKey`,
+                description: `Api key used for request authorization`,
+                type: 'string',
+                isRequired: true
+            },
+            {
+                name: `sourceEnvironmentId`,
+                description: `Environment id of the source environment`,
+                type: 'string',
+                isRequired: true
+            },
+            {
+                name: `language`,
+                description: `Language codename of items to export`,
+                type: 'string',
+                isRequired: true
+            },
+            {
+                name: `items`,
+                description: `Comma separated item codenames to export`,
+                type: 'string',
+                isRequired: true
+            },
+            {
+                name: `targetApiKey`,
+                description: `Api key used for request authorization`,
+                type: 'string',
+                isRequired: true
+            },
+            {
+                name: `targetEnvironmentId`,
+                description: `Environment id of the target environment`,
+                type: 'string',
+                isRequired: true
+            },
+            {
+                name: `baseUrl`,
+                description: `Custom base URL`,
+                type: 'string',
+                isRequired: false
+            }
+        ]
+    })
+
+    .withOption({
+        alias: `f`,
+        name: `force`,
+        description: `When enabled, confirmation is not required`,
+        type: 'boolean',
+        isRequired: false
+    })
+    .withOption({
+        alias: `h`,
+        name: `help`,
+        description: `Show help`,
+        isRequired: false
+    });

package/lib/toolkit/elements-builder.ts

@@ -0,0 +1,84 @@
+import { MigrationElementModels } from '../core/index.js';
+
+export const elementsBuilder = {
+    textElement: (data: Omit<MigrationElementModels.TextElement, 'type'>): MigrationElementModels.TextElement => {
+        return {
+            ...data,
+            type: 'text'
+        };
+    },
+    assetElement: (data: Omit<MigrationElementModels.AssetElement, 'type'>): MigrationElementModels.AssetElement => {
+        return {
+            ...data,
+            type: 'asset'
+        };
+    },
+    customElement: (data: Omit<MigrationElementModels.CustomElement, 'type'>): MigrationElementModels.CustomElement => {
+        return {
+            ...data,
+            type: 'custom'
+        };
+    },
+    dateTimeElement: (
+        data: Omit<MigrationElementModels.DateTimeElement, 'type'>
+    ): MigrationElementModels.DateTimeElement => {
+        return {
+            ...data,
+            type: 'date_time'
+        };
+    },
+    linkedItemsElement: (
+        data: Omit<MigrationElementModels.LinkedItemsElement, 'type'>
+    ): MigrationElementModels.LinkedItemsElement => {
+        return {
+            ...data,
+            type: 'modular_content'
+        };
+    },
+    multipleChoiceElement: (
+        data: Omit<MigrationElementModels.MultipleChoiceElement, 'type'>
+    ): MigrationElementModels.MultipleChoiceElement => {
+        return {
+            ...data,
+            type: 'multiple_choice'
+        };
+    },
+    numberElement: (data: Omit<MigrationElementModels.NumberElement, 'type'>): MigrationElementModels.NumberElement => {
+        return {
+            ...data,
+            type: 'number'
+        };
+    },
+    richTextElement: (
+        data: Omit<MigrationElementModels.RichTextElement, 'type'>
+    ): MigrationElementModels.RichTextElement => {
+        return {
+            ...data,
+            type: 'rich_text'
+        };
+    },
+    subpagesElement: (
+        data: Omit<MigrationElementModels.SubpagesElement, 'type'>
+    ): MigrationElementModels.SubpagesElement => {
+        return {
+            ...data,
+            type: 'subpages'
+        };
+    },
+    taxonomyElement: (
+        data: Omit<MigrationElementModels.TaxonomyElement, 'type'>
+    ): MigrationElementModels.TaxonomyElement => {
+        return {
+            ...data,
+            type: 'taxonomy'
+        };
+    },
+    urlSlugElement: (
+        data: Omit<MigrationElementModels.UrlSlugElement, 'type'>
+    ): MigrationElementModels.UrlSlugElement => {
+        return {
+            ...data,
+            type: 'url_slug'
+        };
+    }
+};

package/lib/toolkit/export.ts

@@ -0,0 +1,21 @@
+import { libMetadata } from '../metadata.js';
+import { MigrationData, executeWithTrackingAsync } from '../core/index.js';
+import { ExportConfig, exportManager } from '../export/index.js';
+
+export async function exportAsync(config: ExportConfig): Promise<MigrationData> {
+    return await executeWithTrackingAsync({
+        event: {
+            tool: 'migrationToolkit',
+            package: {
+                name: libMetadata.name,
+                version: libMetadata.version
+            },
+            action: 'export',
+            relatedEnvironmentId: undefined,
+            details: {}
+        },
+        func: async () => {
+            return await exportManager(config).exportAsync();
+        }
+    });
+}

package/lib/toolkit/file.ts

@@ -0,0 +1,70 @@
+import { fileManager } from '../file/index.js';
+import {
+    Logger,
+    executeWithTrackingAsync,
+    getDefaultZipFilename,
+    getDefaultLogger,
+    MigrationData
+} from '../core/index.js';
+import { zipManager } from '../zip/index.js';
+import { libMetadata } from '../metadata.js';
+
+export interface StoreConfig {
+    readonly data: MigrationData;
+    readonly filename?: string;
+    readonly logger?: Logger;
+}
+
+export interface ExtractConfig {
+    readonly filename?: string;
+    readonly logger?: Logger;
+}
+
+export async function storeAsync(config: StoreConfig): Promise<void> {
+    const logger = config.logger ?? getDefaultLogger();
+    const filename: string = getDefaultZipFilename();
+
+    await executeWithTrackingAsync<void>({
+        event: {
+            tool: 'migrationToolkit',
+            package: {
+                name: libMetadata.name,
+                version: libMetadata.version
+            },
+            action: 'store',
+            relatedEnvironmentId: undefined,
+            details: {}
+        },
+        func: async () => {
+            const zipData = await zipManager(logger).createZipAsync(config.data);
+
+            if (zipData instanceof Buffer) {
+                await fileManager(logger).writeFileAsync(filename, zipData);
+            } else {
+                throw Error(`Cannot store '${filename}' on File system because the provided zip is not a Buffer`);
+            }
+        }
+    });
+}
+
+export async function extractAsync(config: ExtractConfig): Promise<MigrationData> {
+    const logger = config.logger ?? getDefaultLogger();
+    const filename: string = getDefaultZipFilename();
+
+    return await executeWithTrackingAsync({
+        event: {
+            tool: 'migrationToolkit',
+            package: {
+                name: libMetadata.name,
+                version: libMetadata.version
+            },
+            action: 'extract',
+            relatedEnvironmentId: undefined,
+            details: {}
+        },
+        func: async () => {
+            const fileData = await fileManager(logger).loadFileAsync(filename);
+            return await zipManager(logger).parseZipAsync(fileData);
+        }
+    });
+}

package/lib/toolkit/import.ts

@@ -0,0 +1,21 @@
+import { executeWithTrackingAsync } from '../core/index.js';
+import { ImportConfig, ImportResult, importManager } from '../import/index.js';
+import { libMetadata } from '../metadata.js';
+
+export async function importAsync(config: ImportConfig): Promise<ImportResult> {
+    return await executeWithTrackingAsync({
+        event: {
+            tool: 'migrationToolkit',
+            package: {
+                name: libMetadata.name,
+                version: libMetadata.version
+            },
+            action: 'import',
+            relatedEnvironmentId: undefined,
+            details: {}
+        },
+        func: async () => {
+            return await importManager(config).importAsync();
+        }
+    });
+}

package/lib/toolkit/index.ts

@@ -0,0 +1,5 @@
+export * from './export.js';
+export * from './import.js';
+export * from './elements-builder.js';
+export * from './migrate.js';
+export * from './file.js';

package/lib/toolkit/migrate.ts

@@ -0,0 +1,71 @@
+import { libMetadata } from '../metadata.js';
+import { IRetryStrategyOptions } from '@kontent-ai/core-sdk';
+import {
+    ExternalIdGenerator,
+    Logger,
+    ManagementClientConfig,
+    MigrationData,
+    executeWithTrackingAsync,
+    getDefaultLogger
+} from '../core/index.js';
+import { SourceExportItem } from '../export/index.js';
+import { exportAsync } from './export.js';
+import { importAsync } from './import.js';
+import { ImportResult } from '../import/index.js';
+
+export interface MigrationSource extends ManagementClientConfig {
+    readonly items: readonly SourceExportItem[];
+}
+
+export interface MigrationTarget extends ManagementClientConfig {}
+
+export interface MigrationConfig {
+    readonly retryStrategy?: IRetryStrategyOptions;
+    readonly externalIdGenerator?: ExternalIdGenerator;
+    readonly logger?: Logger;
+    readonly sourceEnvironment: MigrationSource;
+    readonly targetEnvironment: MigrationTarget;
+}
+
+export interface MigrationResult {
+    readonly migrationData: MigrationData;
+    readonly importResult: ImportResult;
+}
+
+export async function migrateAsync(config: MigrationConfig): Promise<MigrationResult> {
+    const logger = config.logger ?? getDefaultLogger();
+
+    return await executeWithTrackingAsync({
+        event: {
+            tool: 'migrationToolkit',
+            package: {
+                name: libMetadata.name,
+                version: libMetadata.version
+            },
+            action: 'migrate',
+            relatedEnvironmentId: undefined,
+            details: {
+                itemsCount: config.sourceEnvironment.items.length
+            }
+        },
+        func: async () => {
+            const migrationData = await exportAsync({
+                ...config.sourceEnvironment,
+                logger: logger,
+                exportItems: config.sourceEnvironment.items
+            });
+
+            const importResult = await importAsync({
+                ...config.targetEnvironment,
+                logger: logger,
+                data: migrationData,
+                externalIdGenerator: config.externalIdGenerator
+            });
+
+            return {
+                importResult,
+                migrationData
+            };
+        }
+    });
+}