@kontent-ai/migration-toolkit 2.9.1 → 3.0.0-1

package/lib/import/utils/import.utils.ts

@@ -1,10 +1,12 @@
-import chalk from 'chalk';
-import type { MigrationItem } from '../../core/index.js';
+import chalk from "chalk";
+import { MigrationToolkitError } from "../../core/models/error.models.js";
+import type { MigrationItem } from "../../core/models/migration.models.js";
 
 export function throwErrorForMigrationItem(migrationItem: MigrationItem, message: string): never {
-    throw Error(
-        `Impot failed for item '${chalk.yellow(migrationItem.system.codename)}' in language '${chalk.cyan(
-            migrationItem.system.language
-        )}'. Reason: ${message}`
-    );
+	throw new MigrationToolkitError(
+		"importFailedForItem",
+		`Import failed for item '${chalk.yellow(migrationItem.system.codename)}' in language '${chalk.cyan(
+			migrationItem.system.language,
+		)}'. Reason: ${message}`,
+	);
 }

package/lib/index.ts

@@ -1,8 +1,12 @@
-// Public API
-export * from './core/index.js';
-export * from './export/index.js';
-export * from './file/index.js';
-export * from './import/index.js';
-export * from './toolkit/index.js';
-export * from './translation/index.js';
-export * from './zip/index.js';
+// biome-ignore lint/performance/noBarrelFile: We need to export the public API
+export { getDefaultLogger } from "./core/logs/loggers.js";
+export { MigrationToolkitError, MissingAssetError, MissingItemError } from "./core/models/error.models.js";
+export type { Logger, LogMessage, LogSpinnerData, LogSpinnerMessage } from "./core/models/log.models.js";
+export * from "./core/models/migration.models.js";
+export { defaultExternalIdGenerator, type ExternalIdGenerator } from "./core/utils/external-id.utils.js";
+export type { SourceExportItem } from "./export/export.models.js";
+export { elementsBuilder } from "./toolkit/elements-builder.js";
+export { exportAsync } from "./toolkit/export.js";
+export { extractAsync, storeAsync } from "./toolkit/file.js";
+export { importAsync } from "./toolkit/import.js";
+export { migrateAsync } from "./toolkit/migrate.js";

package/lib/metadata.ts

@@ -1,6 +1,5 @@
-
 export const libMetadata = {
-	name: '@kontent-ai/migration-toolkit',
-    timestamp: 'Tue, 11 Nov 2025 14:54:34 GMT',
-    version: '2.9.1'
+	name: "@kontent-ai/migration-toolkit",
+	timestamp: "Tue, 11 Nov 2025 14:54:34 GMT",
+	version: "2.9.1",
 };

package/lib/node/cli/actions/export-action.ts

@@ -1,45 +1,51 @@
-import { confirmExportAsync, defaultZipFilename, getDefaultLogger } from '../../../core/index.js';
-import { exportAsync, storeAsync } from '../../../toolkit/index.js';
-import type { CliArgumentsFetcher } from '../cli.models.js';
+import { getDefaultLogger } from "../../../core/logs/loggers.js";
+import { confirmExportAsync } from "../../../core/utils/confirm.utils.js";
+import { defaultZipFilename } from "../../../core/utils/global.utils.js";
+import { exportAsync } from "../../../toolkit/export.js";
+import { storeAsync } from "../../../toolkit/file.js";
+import type { CliArgumentsFetcher } from "../cli.models.js";
 
 export async function exportActionAsync(cliFetcher: CliArgumentsFetcher): Promise<void> {
-    const logger = getDefaultLogger();
-    const language = cliFetcher.getRequiredArgumentValue('language');
-    const environmentId = cliFetcher.getRequiredArgumentValue('sourceEnvironmentId');
-    const apiKey = cliFetcher.getRequiredArgumentValue('sourceApiKey');
-    const items = cliFetcher.getRequiredArgumentValue('items').split(',');
-    const baseUrl = cliFetcher.getOptionalArgumentValue('baseUrl');
-    const force = cliFetcher.getBooleanArgumentValue('force', false);
-    const filename = cliFetcher.getOptionalArgumentValue('filename') ?? defaultZipFilename;
+	const logger = getDefaultLogger();
+	const language = cliFetcher.getRequiredArgumentValue("language");
+	const environmentId = cliFetcher.getRequiredArgumentValue("sourceEnvironmentId");
+	const apiKey = cliFetcher.getRequiredArgumentValue("sourceApiKey");
+	const items = cliFetcher.getRequiredArgumentValue("items").split(",");
+	const baseUrl = cliFetcher.getOptionalArgumentValue("baseUrl");
+	const force = cliFetcher.getBooleanArgumentValue("force", false);
+	const skipMissingReferences = cliFetcher.getBooleanArgumentValue("skipMissingReferences", false);
+	const filename = cliFetcher.getOptionalArgumentValue("filename") ?? defaultZipFilename;
 
-    await confirmExportAsync({
-        force: force,
-        apiKey: apiKey,
-        environmentId: environmentId,
-        logger: logger,
-        dataToExport: {
-            itemsCount: items.length
-        }
-    });
+	await confirmExportAsync({
+		force,
+		apiKey,
+		environmentId,
+		logger,
+		dataToExport: {
+			itemsCount: items.length,
+		},
+		skipMissingReferences,
+	});
 
-    const exportedData = await exportAsync({
-        logger: logger,
-        environmentId: environmentId,
-        apiKey: apiKey,
-        baseUrl: baseUrl,
-        exportItems: items.map((m) => {
-            return {
-                itemCodename: m,
-                languageCodename: language
-            };
-        })
-    });
+	const exportedData = await exportAsync({
+		logger,
+		environmentId,
+		apiKey,
+		baseUrl,
+		exportItems: items.map((m) => {
+			return {
+				itemCodename: m,
+				languageCodename: language,
+			};
+		}),
+		skipMissingReferences,
+	});
 
-    await storeAsync({
-        data: exportedData,
-        filename: filename,
-        logger: logger
-    });
+	await storeAsync({
+		data: exportedData,
+		filename: filename,
+		logger: logger,
+	});
 
-    logger.log({ type: 'completed', message: `Export has been successful` });
+	logger.log({ type: "completed", message: `Export has been successful` });
 }

package/lib/node/cli/actions/import-action.ts

@@ -1,36 +1,39 @@
-import { confirmImportAsync, defaultZipFilename, getDefaultLogger } from '../../../core/index.js';
-import { extractAsync, importAsync } from '../../../toolkit/index.js';
-import type { CliArgumentsFetcher } from '../cli.models.js';
+import { getDefaultLogger } from "../../../core/logs/loggers.js";
+import { confirmImportAsync } from "../../../core/utils/confirm.utils.js";
+import { defaultZipFilename } from "../../../core/utils/global.utils.js";
+import { extractAsync } from "../../../toolkit/file.js";
+import { importAsync } from "../../../toolkit/import.js";
+import type { CliArgumentsFetcher } from "../cli.models.js";
 
 export async function importActionAsync(argsFetcher: CliArgumentsFetcher): Promise<void> {
-    const log = getDefaultLogger();
-    const environmentId = argsFetcher.getRequiredArgumentValue('targetEnvironmentId');
-    const apiKey = argsFetcher.getRequiredArgumentValue('targetApiKey');
-    const baseUrl = argsFetcher.getOptionalArgumentValue('baseUrl');
-    const createReportFile = argsFetcher.getBooleanArgumentValue('createReportFile', false);
-    const force = argsFetcher.getBooleanArgumentValue('force', false);
-    const filename = argsFetcher.getOptionalArgumentValue('filename') ?? defaultZipFilename;
+	const log = getDefaultLogger();
+	const environmentId = argsFetcher.getRequiredArgumentValue("targetEnvironmentId");
+	const apiKey = argsFetcher.getRequiredArgumentValue("targetApiKey");
+	const baseUrl = argsFetcher.getOptionalArgumentValue("baseUrl");
+	const createReportFile = argsFetcher.getBooleanArgumentValue("createReportFile", false);
+	const force = argsFetcher.getBooleanArgumentValue("force", false);
+	const filename = argsFetcher.getOptionalArgumentValue("filename") ?? defaultZipFilename;
 
-    await confirmImportAsync({
-        force: force,
-        apiKey: apiKey,
-        environmentId: environmentId,
-        logger: log
-    });
+	await confirmImportAsync({
+		force: force,
+		apiKey: apiKey,
+		environmentId: environmentId,
+		logger: log,
+	});
 
-    const importData = await extractAsync({
-        logger: log,
-        filename: filename
-    });
+	const importData = await extractAsync({
+		logger: log,
+		filename: filename,
+	});
 
-    await importAsync({
-        logger: log,
-        data: importData,
-        baseUrl: baseUrl,
-        environmentId: environmentId,
-        apiKey: apiKey,
-        createReportFile: createReportFile
-    });
+	await importAsync({
+		logger: log,
+		data: importData,
+		baseUrl: baseUrl,
+		environmentId: environmentId,
+		apiKey: apiKey,
+		createReportFile: createReportFile,
+	});
 
-    log.log({ type: 'completed', message: `Import has been successful` });
+	log.log({ type: "completed", message: `Import has been successful` });
 }

package/lib/node/cli/actions/migrate-action.ts

@@ -1,52 +1,56 @@
-import { confirmMigrateAsync, getDefaultLogger } from '../../../core/index.js';
-import type { SourceExportItem } from '../../../export/index.js';
-import { migrateAsync } from '../../../toolkit/index.js';
-import type { CliArgumentsFetcher } from '../cli.models.js';
+import { getDefaultLogger } from "../../../core/logs/loggers.js";
+import { confirmMigrateAsync } from "../../../core/utils/confirm.utils.js";
+import type { SourceExportItem } from "../../../export/export.models.js";
+import { migrateAsync } from "../../../toolkit/migrate.js";
+import type { CliArgumentsFetcher } from "../cli.models.js";
 
 export async function migrateActionAsync(argsFetcher: CliArgumentsFetcher): Promise<void> {
-    const log = getDefaultLogger();
-    const sourceEnvironmentId = argsFetcher.getRequiredArgumentValue('sourceEnvironmentId');
-    const sourceApiKey = argsFetcher.getRequiredArgumentValue('sourceApiKey');
-    const targetEnvironmentId = argsFetcher.getRequiredArgumentValue('targetEnvironmentId');
-    const targetApiKey = argsFetcher.getRequiredArgumentValue('targetApiKey');
-    const force = argsFetcher.getBooleanArgumentValue('force', false);
-    const items = argsFetcher.getRequiredArgumentValue('items')?.split(',');
-    const language = argsFetcher.getRequiredArgumentValue('language');
-    const migrateItems: readonly SourceExportItem[] = items.map((m) => {
-        return {
-            itemCodename: m,
-            languageCodename: language
-        };
-    });
+	const logger = getDefaultLogger();
+	const sourceEnvironmentId = argsFetcher.getRequiredArgumentValue("sourceEnvironmentId");
+	const sourceApiKey = argsFetcher.getRequiredArgumentValue("sourceApiKey");
+	const targetEnvironmentId = argsFetcher.getRequiredArgumentValue("targetEnvironmentId");
+	const targetApiKey = argsFetcher.getRequiredArgumentValue("targetApiKey");
+	const force = argsFetcher.getBooleanArgumentValue("force", false);
+	const skipMissingReferences = argsFetcher.getBooleanArgumentValue("skipMissingReferences", false);
+	const items = argsFetcher.getRequiredArgumentValue("items").split(",");
+	const language = argsFetcher.getRequiredArgumentValue("language");
+	const migrateItems: readonly SourceExportItem[] = items.map((m) => {
+		return {
+			itemCodename: m,
+			languageCodename: language,
+		};
+	});
 
-    await confirmMigrateAsync({
-        force: force,
-        sourceEnvironment: {
-            apiKey: sourceApiKey,
-            environmentId: sourceEnvironmentId
-        },
-        targetEnvironment: {
-            apiKey: targetApiKey,
-            environmentId: targetEnvironmentId
-        },
-        logger: log,
-        dataToMigrate: {
-            itemsCount: migrateItems.length
-        }
-    });
+	await confirmMigrateAsync({
+		skipMissingReferences,
+		force,
+		sourceEnvironment: {
+			apiKey: sourceApiKey,
+			environmentId: sourceEnvironmentId,
+		},
+		targetEnvironment: {
+			apiKey: targetApiKey,
+			environmentId: targetEnvironmentId,
+		},
+		logger,
+		dataToMigrate: {
+			itemsCount: migrateItems.length,
+		},
+	});
 
-    await migrateAsync({
-        logger: log,
-        sourceEnvironment: {
-            environmentId: sourceEnvironmentId,
-            apiKey: sourceApiKey,
-            items: migrateItems
-        },
-        targetEnvironment: {
-            environmentId: targetEnvironmentId,
-            apiKey: targetApiKey
-        }
-    });
+	await migrateAsync({
+		logger,
+		sourceEnvironment: {
+			environmentId: sourceEnvironmentId,
+			apiKey: sourceApiKey,
+			items: migrateItems,
+			skipMissingReferences,
+		},
+		targetEnvironment: {
+			environmentId: targetEnvironmentId,
+			apiKey: targetApiKey,
+		},
+	});
 
-    log.log({ type: 'completed', message: `Migration has been successful` });
+	logger.log({ type: "completed", message: `Migration has been successful` });
 }

package/lib/node/cli/app.ts

@@ -1,32 +1,32 @@
 #!/usr/bin/env node
-import chalk from 'chalk';
-
-import { match } from 'ts-pattern';
-import { exitProgram, handleError } 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';
-import { cliArgs } from './commands.js';
+import chalk from "chalk";
+import { match } from "ts-pattern";
+import { handleError } from "../../core/utils/error.utils.js";
+import { exitProgram } from "../../core/utils/global.utils.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";
+import { cliArgs } from "./commands.js";
 
 // Need to register --help commands
 cliArgs.registerCommands();
 
 const run = async () => {
-    const argsFetcher = await argumentsFetcherAsync();
-    const action = argsFetcher.getCliAction();
+	const argsFetcher = await argumentsFetcherAsync();
+	const action = argsFetcher.getCliAction();
 
-    return await match(action)
-        .with('export', async () => await exportActionAsync(argsFetcher))
-        .with('import', async () => await importActionAsync(argsFetcher))
-        .with('migrate', async () => await migrateActionAsync(argsFetcher))
-        .otherwise(() =>
-            exitProgram({
-                message: `Invalid action '${chalk.red(action)}'`
-            })
-        );
+	return await match(action)
+		.with("export", async () => await exportActionAsync(argsFetcher))
+		.with("import", async () => await importActionAsync(argsFetcher))
+		.with("migrate", async () => await migrateActionAsync(argsFetcher))
+		.otherwise(() =>
+			exitProgram({
+				message: `Invalid action '${chalk.red(action)}'`,
+			}),
+		);
 };
 
 run().catch((err) => {
-    handleError(err);
+	handleError(err);
 });

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

@@ -1,60 +1,61 @@
-import chalk from 'chalk';
-import { match } from 'ts-pattern';
-import yargs from 'yargs';
-import { hideBin } from 'yargs/helpers';
-import type { CliAction, LiteralUnion } from '../../../core/index.js';
-import { exitProgram } from '../../../core/index.js';
-import type { CliArgumentsFetcher } from '../cli.models.js';
+import chalk from "chalk";
+import { match } from "ts-pattern";
+import yargs from "yargs";
+import { hideBin } from "yargs/helpers";
+import type { CliAction, LiteralUnion } from "../../../core/models/core.models.js";
+import { MigrationToolkitError } from "../../../core/models/error.models.js";
+import { exitProgram } from "../../../core/utils/global.utils.js";
+import type { CliArgumentsFetcher } from "../cli.models.js";
 
 type ArgvResult = {
-    [x: string]: unknown;
-    _: (string | number)[];
-    $0: string;
+	[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() as LiteralUnion<CliAction>;
-
-            return match(command)
-                .returnType<CliAction>()
-                .with('export', () => 'export')
-                .with('import', () => 'import')
-                .with('migrate', () => 'migrate')
-                .otherwise(() => {
-                    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();
-        }
-    };
+	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() as LiteralUnion<CliAction>;
+
+			return match(command)
+				.returnType<CliAction>()
+				.with("export", () => "export")
+				.with("import", () => "import")
+				.with("migrate", () => "migrate")
+				.otherwise(() => {
+					throw new MigrationToolkitError("unsupportedCommand", `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

@@ -1,38 +1,40 @@
-import yargs from 'yargs';
-import { hideBin } from 'yargs/helpers';
-import type { CliArgumentsSetter, Command, CommandOption } from '../cli.models.js';
+import yargs from "yargs";
+import { hideBin } from "yargs/helpers";
+import type { CliArgumentsSetter, Command, CommandOption } from "../cli.models.js";
 
 export function argumentsSetter(): CliArgumentsSetter {
-    const argv = yargs(hideBin(process.argv));
+	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 {
+		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;
+		},
+		withOption(option: CommandOption): CliArgumentsSetter {
+			argv.option(option.name, {
+				alias: option.alias,
+				description: option.description,
+				type: option.type,
+				demandOption: option.isRequired,
+			});
 
-            return this;
-        },
-        registerCommands(): void {
-            argv.parseSync();
-        }
-    };
+			return this;
+		},
+		registerCommands(): void {
+			argv.parseSync();
+		},
+	};
 }

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

@@ -1,29 +1,29 @@
-import type { CliAction } from '../../core/index.js';
+import type { CliAction } from "../../core/models/core.models.js";
 
 export interface Command {
-    readonly name: string;
-    readonly description: string;
-    readonly options: readonly CommandOption[];
-    readonly examples: string[];
+	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';
+	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;
-    registerCommands(): void;
+	withCommand(command: Command): CliArgumentsSetter;
+	withOption(option: CommandOption): CliArgumentsSetter;
+	registerCommands(): void;
 };
 
 export type CliArgumentsFetcher = {
-    getCliAction(): CliAction;
-    getOptionalArgumentValue(argName: string): string | undefined;
-    getRequiredArgumentValue(argName: string): string;
-    getBooleanArgumentValue(argName: string, defaultValue: boolean): boolean;
+	getCliAction(): CliAction;
+	getOptionalArgumentValue(argName: string): string | undefined;
+	getRequiredArgumentValue(argName: string): string;
+	getBooleanArgumentValue(argName: string, defaultValue: boolean): boolean;
 };