@kontent-ai/migration-toolkit 1.0.1 → 1.2.0

package/lib/core/logs/loggers.ts

@@ -63,12 +63,7 @@ function getLogDataMessage(data: LogSpinnerMessage): string {
 
     if (data.type === 'info') {
         typeColor = chalk.cyan;
-    } else if (
-        data.type === 'error' ||
-        data.type === 'errorData' ||
-        data.type === 'warning' ||
-        data.type === 'cancel'
-    ) {
+    } else if (data.type === 'error' || data.type === 'errorData' || data.type === 'warning' || data.type === 'cancel') {
         typeColor = chalk.red;
     } else if (data.type === 'completed') {
         typeColor = chalk.green;

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

@@ -1,17 +1,9 @@
-import {
-    AssetModels,
-    ContentItemModels,
-    ContentTypeElements,
-    LanguageVariantModels,
-    WorkflowModels
-} from '@kontent-ai/management-sdk';
+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 =
@@ -26,6 +18,8 @@ export type MapiAction =
     | 'upsert'
     | 'createNewVersion';
 
+export type MigrationItemType = 'exportItem';
+
 export type MapiType =
     | 'contentType'
     | 'asset'
@@ -40,7 +34,7 @@ export type MapiType =
 
 export interface ItemInfo {
     readonly title: string;
-    readonly itemType: GeneralItemType | MapiType;
+    readonly itemType: MapiType | MigrationItemType;
 }
 
 export interface ErrorData {
@@ -121,14 +115,14 @@ export interface FlattenedContentType {
 }
 
 export interface OriginalManagementError {
-    response?: {
-        status?: number;
-        config?: {
-            url?: string;
-            data?: string;
+    readonly response?: {
+        readonly status?: number;
+        readonly config?: {
+            readonly url?: string;
+            readonly data?: string;
         };
-        data?: {
-            error_code?: number;
+        readonly data?: {
+            readonly error_code?: number;
         };
     };
 }

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

@@ -1,4 +1,4 @@
-import { GeneralActionType, GeneralItemType, MapiAction, MapiType } from '../index.js';
+import { MigrationItemType, MapiAction, MapiType } from '../index.js';
 
 export type DebugType =
     | 'error'
@@ -8,10 +8,13 @@ export type DebugType =
     | 'errorData'
     | 'cancel'
     | 'process'
+    | 'readFs'
+    | 'skip'
+    | 'writeFs'
+    | 'download'
+    | MigrationItemType
     | MapiType
-    | GeneralActionType
-    | MapiAction
-    | GeneralItemType;
+    | MapiAction;
 
 export interface LogMessage {
     readonly type: DebugType;

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

@@ -1,165 +1,85 @@
-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;
-}
+import { z } from 'zod';
+import {
+    MigrationComponentSchema,
+    MigrationElementTypeSchema,
+    MigrationElementValueSchema,
+    MigrationReferenceSchema,
+    MigrationUrlSlugElementValueSchema,
+    MigrationUrlSlugModeSchema,
+    MigrationRichTextElementValueSchema,
+    MigrationElementSchema,
+    MigrationElementsSchema,
+    MigrationAssetDescriptionSchema,
+    MigrationDataSchema,
+    MigrationAssetSchema,
+    MigrationItemVersionSchema,
+    MigrationItemSchema,
+    MigrationItemSystemSchema
+} from './migration.schema.js';
 
 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;
+    type MigrationElementDef<
+        TElementType extends MigrationElementType = MigrationElementType,
+        TValue extends MigrationElementValue = MigrationElementValue
+    > = {
+        readonly value: TValue | undefined;
+        readonly type: TElementType;
     };
-    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 type TextElement = MigrationElementDef<'text', string>;
+    export type NumberElement = MigrationElementDef<'number', number>;
+    export type RichTextElement = MigrationElementDef<'rich_text', MigrationRichTextElementValue>;
+    export type MultipleChoiceElement = MigrationElementDef<'multiple_choice', MigrationReference[]>;
+    export type DateTimeElement = MigrationElementDef<'date_time', string>;
+    export type AssetElement = MigrationElementDef<'asset', MigrationReference[]>;
+    export type LinkedItemsElement = MigrationElementDef<'modular_content', MigrationReference[]>;
+    export type TaxonomyElement = MigrationElementDef<'taxonomy', MigrationReference[]>;
+    export type UrlSlugElement = MigrationElementDef<'url_slug', MigrationUrlSlugElementValue>;
+    export type CustomElement = MigrationElementDef<'custom', string>;
+    export type SubpagesElement = MigrationElementDef<'subpages', MigrationReference[]>;
 }
 
-export interface MigrationAsset {
-    /**
-     * Codename of the asset
-     */
+export type MigrationReference<T extends string = string> = z.infer<typeof MigrationReferenceSchema> & {
+    readonly codename: T;
+};
+export type MigrationItemSystem<
+    TLanguage extends string = string,
+    TType extends string = string,
+    TCollection extends string = string,
+    TWorkflow extends string = string
+> = z.infer<typeof MigrationItemSystemSchema> & {
     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[];
-}
+    readonly name: string;
+    readonly language: MigrationReference<TLanguage>;
+    readonly type: MigrationReference<TType>;
+    readonly collection: MigrationReference<TCollection>;
+    readonly workflow: MigrationReference<TWorkflow>;
+};
+export type MigrationUrlSlugMode = z.infer<typeof MigrationUrlSlugModeSchema>;
+export type MigrationElementType = z.infer<typeof MigrationElementTypeSchema>;
+export type MigrationUrlSlugElementValue = z.infer<typeof MigrationUrlSlugElementValueSchema>;
+export type MigrationRichTextElementValue = z.infer<typeof MigrationRichTextElementValueSchema>;
+export type MigrationComponent = z.infer<typeof MigrationComponentSchema>;
+export type MigrationElementValue = z.infer<typeof MigrationElementValueSchema>;
+export type MigrationElement = z.infer<typeof MigrationElementSchema>;
+export type MigrationElements = z.infer<typeof MigrationElementsSchema>;
+export type MigrationAssetDescription = z.infer<typeof MigrationAssetDescriptionSchema>;
+export type MigrationAsset = z.infer<typeof MigrationAssetSchema>;
+export type MigrationData = z.infer<typeof MigrationDataSchema>;
+
+export type MigrationItemVersion<
+    TElements extends MigrationElements = MigrationElements,
+    TWorkflowStepCodename extends string = string
+> = z.infer<typeof MigrationItemVersionSchema> & {
+    readonly elements: Readonly<TElements>;
+    readonly workflow_step: MigrationReference<TWorkflowStepCodename>;
+};
+
+export type MigrationItem<
+    TElements extends MigrationElements = MigrationElements,
+    TSystem extends MigrationItemSystem = MigrationItemSystem,
+    TWorkflowStepCodename extends string = string
+> = z.infer<typeof MigrationItemSchema> & {
+    readonly versions: Readonly<MigrationItemVersion<TElements, TWorkflowStepCodename>[]>;
+    readonly system: TSystem;
+};

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

@@ -0,0 +1,178 @@
+import { z } from 'zod';
+
+interface Elements {
+    readonly [key: string]: Element;
+}
+
+type UrlSlugMode = 'autogenerated' | 'custom';
+
+type UrlSlugElementValue = {
+    readonly value?: string;
+    readonly mode: UrlSlugMode;
+};
+
+type Reference = { readonly codename: string };
+
+type Component = {
+    readonly system: {
+        readonly id: string;
+        readonly type: Reference;
+    };
+    readonly elements: Elements;
+};
+
+type RichTextElementValue = {
+    readonly value: string;
+    readonly components: Readonly<Component[]>;
+};
+
+type ElementValue = string | undefined | number | Reference[] | RichTextElementValue | UrlSlugElementValue;
+
+type Element = {
+    readonly type: ElementType;
+    readonly value?: ElementValue;
+};
+
+type ElementType =
+    | 'text'
+    | 'rich_text'
+    | 'number'
+    | 'multiple_choice'
+    | 'date_time'
+    | 'asset'
+    | 'modular_content'
+    | 'taxonomy'
+    | 'url_slug'
+    | 'custom'
+    | 'subpages';
+
+export const MigrationUrlSlugModeSchema = z.enum(['autogenerated', 'custom']).readonly();
+export const MigrationElementTypeSchema = z
+    .enum([
+        'text',
+        'rich_text',
+        'number',
+        'multiple_choice',
+        'date_time',
+        'asset',
+        'modular_content',
+        'taxonomy',
+        'url_slug',
+        'custom',
+        'subpages'
+    ])
+    .readonly();
+
+export const MigrationReferenceSchema = z
+    .strictObject({
+        codename: z.string().readonly()
+    })
+    .readonly();
+
+/**
+ * ZodType is needed to be specified here due to the use of 'lazy' & circular dependency between types
+ * Otherwise TS has no way of statically inferring the type
+ */
+export const MigrationElementsSchema: z.ZodReadonly<z.ZodType<Elements>> = z
+    .record(
+        z.string(),
+        z.lazy(() => MigrationElementSchema)
+    )
+    .readonly();
+
+export const MigrationComponentSchema = z
+    .strictObject({
+        system: z.strictObject({
+            id: z.string(),
+            type: MigrationReferenceSchema
+        }),
+        elements: MigrationElementsSchema
+    })
+    .readonly();
+
+export const MigrationUrlSlugElementValueSchema = z
+    .strictObject({
+        value: z.optional(z.string()),
+        mode: MigrationUrlSlugModeSchema
+    })
+    .readonly();
+
+export const MigrationRichTextElementValueSchema = z
+    .strictObject({
+        value: z.string(),
+        components: z.array(MigrationComponentSchema).readonly()
+    })
+    .readonly();
+
+export const MigrationElementValueSchema = z.union([
+    z.string(),
+    z.undefined(),
+    z.number(),
+    z.array(MigrationReferenceSchema),
+    MigrationRichTextElementValueSchema,
+    MigrationUrlSlugElementValueSchema
+]);
+
+export const MigrationElementSchema = z
+    .strictObject({
+        type: MigrationElementTypeSchema,
+        value: MigrationElementValueSchema
+    })
+    .readonly();
+
+export const MigrationItemVersionSchema = z
+    .strictObject({
+        workflow_step: MigrationReferenceSchema,
+        elements: MigrationElementsSchema
+    })
+    .readonly();
+
+export const MigrationItemSystemSchema = z.strictObject({
+    codename: z.string(),
+    name: z.string(),
+    language: MigrationReferenceSchema,
+    type: MigrationReferenceSchema,
+    collection: MigrationReferenceSchema,
+    workflow: MigrationReferenceSchema
+});
+
+export const MigrationItemSchema = z
+    .strictObject({
+        system: MigrationItemSystemSchema,
+        versions: z.array(MigrationItemVersionSchema).readonly()
+    })
+    .readonly();
+
+export const MigrationAssetDescriptionSchema = z
+    .strictObject({
+        language: MigrationReferenceSchema,
+        description: z.optional(z.string())
+    })
+    .readonly();
+
+const BaseMigrationAssetSchema = z.strictObject({
+    codename: z.string(),
+    filename: z.string(),
+    title: z.string(),
+    collection: z.optional(MigrationReferenceSchema),
+    descriptions: z.optional(z.array(MigrationAssetDescriptionSchema)).readonly()
+});
+
+export const MigrationAssetSchema = BaseMigrationAssetSchema.extend({
+    binaryData: z.union([z.instanceof(Buffer), z.instanceof(Blob)])
+}).readonly();
+
+export const ZipMigrationAssetSchema = BaseMigrationAssetSchema.extend({
+    _zipFilename: z.string()
+}).readonly();
+
+export const MigrationAssetsSchema = z.array(MigrationAssetSchema).readonly();
+export const ZipMigrationAssetsSchema = z.array(ZipMigrationAssetSchema).readonly();
+export const MigrationItemsSchema = z.array(MigrationItemSchema).readonly();
+
+export const MigrationDataSchema = z
+    .strictObject({
+        items: MigrationItemsSchema,
+        assets: MigrationAssetsSchema
+    })
+    .readonly();

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

@@ -23,7 +23,7 @@ export async function confirmExportAsync(data: {
         data.dataToExport.itemsCount
     )}' content ${getItemsPluralText(data.dataToExport.itemsCount)} from ${chalk.yellow(
         environment.name
-    )} (${chalk.yellow(environment.environment)}?`;
+    )} (${chalk.magenta(environment.environment)})?`;
 
     await confirmAsync({
         force: data.force,
@@ -65,9 +65,9 @@ export async function confirmMigrateAsync(data: {
 
     const text: string = `Are you sure to migrate '${chalk.cyan(data.dataToMigrate.itemsCount)}' ${getItemsPluralText(
         data.dataToMigrate.itemsCount
-    )} from ${chalk.yellow(sourceEnvironment.name)} (${chalk.yellow(
+    )} from ${chalk.yellow(sourceEnvironment.name)} (${chalk.magenta(
         sourceEnvironment.environment
-    )}) to environment ${chalk.yellow(targetEnvironment.name)} (${chalk.yellow(targetEnvironment.environment)}) ?`;
+    )}) to environment ${chalk.yellow(targetEnvironment.name)} (${chalk.magenta(targetEnvironment.environment)}) ?`;
 
     await confirmAsync({
         force: data.force,
@@ -91,7 +91,7 @@ export async function confirmImportAsync(data: {
         data.logger
     ).getEnvironmentAsync();
 
-    const text: string = `Are you sure to import data into ${chalk.yellow(environment.name)} (${chalk.yellow(
+    const text: string = `Are you sure to import data into ${chalk.yellow(environment.name)} (${chalk.magenta(
         environment.environment
     )})?`;
 

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

@@ -1,6 +1,7 @@
 import { SharedModels } from '@kontent-ai/management-sdk';
 import chalk from 'chalk';
 import { ErrorData, OriginalManagementError } from '../models/core.models.js';
+import { ZodError } from 'zod';
 
 export function extractErrorData(error: unknown): ErrorData {
     let isUnknownError: boolean = true;
@@ -10,15 +11,17 @@ export function extractErrorData(error: unknown): ErrorData {
 
     if (error instanceof SharedModels.ContentManagementBaseKontentError) {
         isUnknownError = false;
-        message = `${error.message}`;
-
-        const originalError: OriginalManagementError | undefined = error.originalError as
-            | OriginalManagementError
-            | undefined;
+        const originalError = error.originalError as OriginalManagementError | undefined;
 
         requestUrl = originalError?.response?.config?.url;
         requestData = originalError?.response?.config?.data;
-        message += error.validationErrors.map((m) => m.message).join(', ');
+
+        message = `${error.message}: ${error.validationErrors.map((m) => m.message).join(', ')}`;
+    } else if (error instanceof ZodError) {
+        isUnknownError = false;
+        message = `Found '${chalk.red(error.issues.length)}' parsing errors: \n${error.issues.reduce<string>((current, issue, index) => {
+            return (current += `\n${index + 1}. ${chalk.red(issue.message)} (${chalk.yellow('path')}: ${issue.path.join(',')})`);
+        }, '')}`;
     } else if (error instanceof Error) {
         message = error.message;
     }

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

@@ -3,6 +3,8 @@ import { ITrackingEventData, getTrackingService } from '@kontent-ai-consulting/t
 import { isBrowser, isNode, isWebWorker } from 'browser-or-node';
 import { EnvContext } from '../models/core.models.js';
 
+export type Writeable<T> = { -readonly [P in keyof T]: T[P] };
+
 export const isNotUndefined = <T>(item: T | undefined): item is T => item !== undefined;
 
 export function formatBytes(bytes: number): string {
@@ -28,9 +30,7 @@ export function getCurrentEnvironment(): EnvContext {
     throw Error(`Invalid current environment. This library can be used in node.js or in browsers.`);
 }
 
-export function getDefaultZipFilename(): string {
-    return `data.zip`;
-}
+export const defaultZipFilename: string = 'data.zip';
 
 export async function executeWithTrackingAsync<TResult>(data: {
     func: () => Promise<TResult extends void ? void : Readonly<TResult>>;