@stackbit/cms-core 0.0.20 → 0.0.21-alpha.0

package/src/content-store.ts

@@ -0,0 +1,2329 @@
+import _ from 'lodash';
+import slugify from 'slugify';
+import path from 'path';
+import sanitizeFilename from 'sanitize-filename';
+import {
+    Config,
+    extendConfig,
+    Field,
+    FieldList,
+    FieldListItems,
+    FieldListProps,
+    FieldModelProps,
+    FieldObjectProps,
+    FieldSpecificProps,
+    loadConfigFromDir,
+    Model
+} from '@stackbit/sdk';
+import { mapPromise, omitByNil } from '@stackbit/utils';
+import * as CSITypes from './content-source-interface';
+import { isLocalizedField, getLocalizedFieldForLocale } from './content-source-interface';
+import * as ContentStoreTypes from './content-store-types';
+import { IMAGE_MODEL } from './common/common-schema';
+import { Timer } from './utils/timer';
+import { UserCommandSpawner } from './common/common-types';
+
+export interface ContentSourceOptions {
+    logger: ContentStoreTypes.Logger;
+    userLogger: ContentStoreTypes.Logger;
+    localDev: boolean;
+    stackbitYamlDir: string;
+    contentSources: CSITypes.ContentSourceInterface[];
+    userCommandSpawner?: UserCommandSpawner;
+    onSchemaChangeCallback: () => void;
+    onContentChangeCallback: (contentChanges: ContentStoreTypes.ContentChangeResult) => void;
+    handleConfigAssets: (config: Config) => Promise<Config>;
+}
+
+interface ContentSourceData {
+    id: string;
+    instance: CSITypes.ContentSourceInterface;
+    type: string;
+    projectId: string;
+    locales?: CSITypes.Locale[];
+    defaultLocaleCode?: string;
+    /* Array of extended and validated Models */
+    models: Model[];
+    /* Map of extended and validated Models by model name */
+    modelMap: Record<string, Model>;
+    /* Map of original Models (as provided by content source) by model name */
+    csiModelMap: Record<string, Model>;
+    /* Array of original content source Documents */
+    csiDocuments: CSITypes.Document[];
+    /* Map of original content source Documents by document ID */
+    csiDocumentMap: Record<string, CSITypes.Document>;
+    /* Array of converted content-store Documents */
+    documents: ContentStoreTypes.Document[];
+    /* Map of converted content-store Documents by document ID */
+    documentMap: Record<string, ContentStoreTypes.Document>;
+    /* Array of original content source Assets */
+    csiAssets: CSITypes.Asset[];
+    /* Map of original content source Assets by asset ID */
+    csiAssetMap: Record<string, CSITypes.Asset>;
+    /* Array of converted content-store Assets */
+    assets: ContentStoreTypes.Asset[];
+    /* Map of converted content-store Assets by asset ID */
+    assetMap: Record<string, ContentStoreTypes.Asset>;
+}
+
+export class ContentStore {
+    private readonly contentSources: CSITypes.ContentSourceInterface[];
+    private readonly logger: ContentStoreTypes.Logger;
+    private readonly userLogger: ContentStoreTypes.Logger;
+    private readonly userCommandSpawner?: UserCommandSpawner;
+    private readonly localDev: boolean;
+    private readonly stackbitYamlDir: string; // TODO: remove stackbitYamlDir, ContentStore should not be aware of filesystem, instead pass autoreloading Config object
+    private readonly onSchemaChangeCallback: () => void;
+    private readonly onContentChangeCallback: (contentChanges: ContentStoreTypes.ContentChangeResult) => void;
+    private readonly handleConfigAssets: (config: Config) => Promise<Config>;
+    private contentSourceDataById: Record<string, ContentSourceData> = {};
+    private contentUpdatesWatchTimer: Timer;
+    private rawStackbitConfig: any;
+    private presets?: Record<string, any>;
+
+    constructor(options: ContentSourceOptions) {
+        this.logger = options.logger.createLogger({ label: 'content-store' });
+        this.userLogger = options.userLogger.createLogger({ label: 'content-store' });
+        this.localDev = options.localDev;
+        this.userCommandSpawner = options.userCommandSpawner;
+        this.stackbitYamlDir = options.stackbitYamlDir; // TODO: remove stackbitYamlDir, ContentStore should not be aware of filesystem, instead pass autoreloading Config object
+        this.contentSources = options.contentSources;
+        this.onSchemaChangeCallback = options.onSchemaChangeCallback;
+        this.onContentChangeCallback = options.onContentChangeCallback;
+        this.handleConfigAssets = options.handleConfigAssets;
+        this.contentUpdatesWatchTimer = new Timer({ timerCallback: () => this.handleTimerTimeout(), logger: this.logger });
+    }
+
+    async init(): Promise<void> {
+        this.logger.debug('init');
+        this.rawStackbitConfig = await this.loadStackbitConfig();
+
+        this.logger.debug('init => load content source data');
+        for (const contentSourceInstance of this.contentSources) {
+            await this.loadContentSourceData({ contentSourceInstance, init: true });
+        }
+
+        this.contentUpdatesWatchTimer.startTimer();
+    }
+
+    async reset() {
+        this.logger.debug('reset');
+
+        this.contentUpdatesWatchTimer.stopTimer();
+        this.rawStackbitConfig = await this.loadStackbitConfig();
+
+        this.logger.debug('reset => load content source data');
+        for (const contentSourceInstance of this.contentSources) {
+            await this.loadContentSourceData({ contentSourceInstance, init: false });
+        }
+
+        this.contentUpdatesWatchTimer.startTimer();
+    }
+
+    /**
+     * This method is called when contentUpdatesWatchTimer receives timeout.
+     * It then notifies all content sources to stop watching for content changes.
+     */
+    handleTimerTimeout() {
+        for (const contentSourceInstance of this.contentSources) {
+            contentSourceInstance.stopWatchingContentUpdates();
+        }
+    }
+
+    /**
+     * This method is called when user interacts with Stackbit application.
+     * It is used to reset contentUpdatesWatchTimer. When the timer is over
+     * all content sources are notified to stop watching for content updates.
+     */
+    async keepAlive() {
+        if (!this.contentUpdatesWatchTimer.isRunning()) {
+            this.logger.debug('keepAlive => contentUpdatesWatchTimer is not running => load content source data');
+            for (const contentSourceInstance of this.contentSources) {
+                await this.loadContentSourceData({ contentSourceInstance, init: false });
+            }
+        }
+        this.contentUpdatesWatchTimer.resetTimer();
+    }
+
+    /**
+     * This method is called when a content source notifies Stackbit of models
+     * changes via webhook. When this happens, all content source data
+     *
+     * For example, Contentful notifies Stackbit of any content-type changes via
+     * special webhook.
+     *
+     * @param contentSourceId
+     */
+    async onContentSourceSchemaChange({ contentSourceId }: { contentSourceId: string }) {
+        this.logger.debug('onContentSourceSchemaChange', { contentSourceId });
+        const contentSourceData = this.getContentSourceDataByIdOrThrow(contentSourceId);
+        await this.loadContentSourceData({
+            contentSourceInstance: contentSourceData.instance,
+            init: false
+        });
+        this.onSchemaChangeCallback();
+    }
+
+    async onFilesChange(
+        updatedFiles: string[]
+    ): Promise<{ stackbitConfigUpdated?: boolean; schemaChanged?: boolean; contentChanges: ContentStoreTypes.ContentChangeResult }> {
+        this.logger.debug('onFilesChange');
+
+        const stackbitConfigUpdated = _.some(updatedFiles, (filePath) => isStackbitConfigFile(filePath));
+        this.logger.debug(`stackbitConfigUpdated: ${stackbitConfigUpdated}`);
+        if (stackbitConfigUpdated) {
+            this.rawStackbitConfig = await this.loadStackbitConfig();
+        }
+
+        let someContentSourceSchemaUpdated = false;
+        const contentChanges: ContentStoreTypes.ContentChangeResult = {
+            updatedDocuments: [],
+            updatedAssets: [],
+            deletedDocuments: [],
+            deletedAssets: []
+        };
+
+        for (const contentSourceInstance of this.contentSources) {
+            const contentSourceId = getContentSourceIdForContentSource(contentSourceInstance);
+            this.logger.debug(`call onFilesChange for contentSource: ${contentSourceId}`);
+            const { schemaChanged, contentChangeEvent } = contentSourceInstance.onFilesChange?.({ updatedFiles: updatedFiles }) ?? {};
+            this.logger.debug(`schemaChanged: ${schemaChanged}, has contentChangeEvent: ${!!contentChangeEvent}`);
+            // if schema is changed, there is no need to return contentChanges
+            // because schema changes reloads everything and implies content changes
+            if (stackbitConfigUpdated || schemaChanged) {
+                if (schemaChanged) {
+                    someContentSourceSchemaUpdated = true;
+                }
+                await this.loadContentSourceData({ contentSourceInstance, init: false });
+            } else if (contentChangeEvent) {
+                const contentChangeResult = this.onContentChange(contentSourceId, contentChangeEvent);
+                contentChanges.updatedDocuments = contentChanges.updatedDocuments.concat(contentChangeResult.updatedDocuments);
+                contentChanges.updatedAssets = contentChanges.updatedAssets.concat(contentChangeResult.updatedAssets);
+                contentChanges.deletedDocuments = contentChanges.deletedDocuments.concat(contentChangeResult.deletedDocuments);
+                contentChanges.deletedAssets = contentChanges.deletedAssets.concat(contentChangeResult.deletedAssets);
+            }
+        }
+
+        return {
+            stackbitConfigUpdated,
+            schemaChanged: someContentSourceSchemaUpdated || stackbitConfigUpdated,
+            contentChanges: contentChanges
+        };
+    }
+
+    async loadStackbitConfig() {
+        this.logger.debug('loadStackbitConfig');
+        // TODO: use esbuild to watch for stackbit.config.js changes and notify
+        //  the content-store via onStackbitConfigChange with updated rawConfig
+        const { config, errors } = await loadConfigFromDir({ dirPath: this.stackbitYamlDir });
+        for (const error of errors) {
+            this.userLogger.warn(error.message);
+        }
+        if (!config) {
+            this.userLogger.error(`could not load stackbit config`);
+        }
+        return config;
+    }
+
+    async loadContentSourceData({ contentSourceInstance, init }: { contentSourceInstance: CSITypes.ContentSourceInterface; init: boolean }) {
+        // TODO: defer loading content if content is already loading for a specific content source
+
+        // TODO: optimize: cache raw responses from contentSource
+        //  e.g.: getModels(), getDocuments(), getAssets()
+        //  ana use the cached response to remap documents when only stackbitConfig changes
+
+        const contentSourceId = getContentSourceIdForContentSource(contentSourceInstance);
+        this.logger.debug('loadContentSourceData', { contentSourceId, init });
+
+        if (init) {
+            await contentSourceInstance.init({
+                logger: this.logger,
+                userLogger: this.userLogger,
+                userCommandSpawner: this.userCommandSpawner,
+                localDev: this.localDev
+            });
+        } else {
+            contentSourceInstance.stopWatchingContentUpdates();
+            await contentSourceInstance.reset();
+        }
+
+        const csiModels = await contentSourceInstance.getModels();
+        const locales = await contentSourceInstance?.getLocales();
+        const result = await extendConfig({ dirPath: this.stackbitYamlDir, config: this.rawStackbitConfig, externalModels: csiModels });
+        const config = await this.handleConfigAssets(result.config);
+        const models = config.models;
+        const modelMap = _.keyBy(models, 'name');
+        const defaultLocaleCode = locales?.find((locale) => locale.default)?.code;
+
+        for (const error of result.errors) {
+            this.userLogger.warn(error.message);
+        }
+
+        // TODO: load presets externally from config, and create additional map
+        //  that maps presetIds by model name instead of storing that map inside every model
+        this.presets = config.presets;
+
+        const csiDocuments = await contentSourceInstance.getDocuments({ modelMap });
+        const csiAssets = await contentSourceInstance.getAssets();
+        const csiDocumentMap = _.keyBy(csiDocuments, 'id');
+        const csiAssetMap = _.keyBy(csiAssets, 'id');
+
+        const contentStoreDocuments = mapCSIDocumentsToStoreDocuments({
+            csiDocuments,
+            contentSourceInstance,
+            modelMap,
+            defaultLocaleCode
+        });
+        const contentStoreAssets = mapCSIAssetsToStoreAssets({
+            csiAssets,
+            contentSourceInstance,
+            defaultLocaleCode
+        });
+        const documentMap = _.keyBy(contentStoreDocuments, 'srcObjectId');
+        const assetMap = _.keyBy(contentStoreAssets, 'srcObjectId');
+
+        this.logger.debug('loaded content source data', {
+            contentSourceId,
+            locales,
+            defaultLocaleCode,
+            modelCount: models.length,
+            documentCount: contentStoreDocuments.length,
+            assetCount: contentStoreAssets.length
+        });
+
+        this.contentSourceDataById[contentSourceId] = {
+            id: contentSourceId,
+            type: contentSourceInstance.getContentSourceType(),
+            projectId: contentSourceInstance.getProjectId(),
+            instance: contentSourceInstance,
+            locales: locales,
+            defaultLocaleCode: defaultLocaleCode,
+            models: models,
+            modelMap: modelMap,
+            csiModelMap: _.keyBy(csiModels, 'name'),
+            csiDocuments: csiDocuments,
+            csiDocumentMap: csiDocumentMap,
+            documents: contentStoreDocuments,
+            documentMap: documentMap,
+            csiAssets: csiAssets,
+            csiAssetMap: csiAssetMap,
+            assets: contentStoreAssets,
+            assetMap: assetMap
+        };
+
+        contentSourceInstance.startWatchingContentUpdates({
+            getModelMap: () => {
+                const contentSourceData = this.getContentSourceDataByIdOrThrow(contentSourceId);
+                return contentSourceData.csiModelMap;
+            },
+            getDocument({ documentId }: { documentId: string }) {
+                return csiDocumentMap[documentId];
+            },
+            getAsset({ assetId }: { assetId: string }) {
+                return csiAssetMap[assetId];
+            },
+            onContentChange: (contentChangeEvent: CSITypes.ContentChangeEvent) => {
+                this.logger.debug('content source called onContentChange', { contentSourceId });
+                const result = this.onContentChange(contentSourceId, contentChangeEvent);
+                this.onContentChangeCallback(result);
+            },
+            onSchemaChange: async () => {
+                this.logger.debug('content source called onSchemaChange', { contentSourceId });
+                await this.loadContentSourceData({
+                    contentSourceInstance: contentSourceInstance,
+                    init: false
+                });
+                this.onSchemaChangeCallback();
+            }
+        });
+    }
+
+    onContentChange(contentSourceId: string, contentChangeEvent: CSITypes.ContentChangeEvent): ContentStoreTypes.ContentChangeResult {
+        // TODO: prevent content change process for contentSourceId if loading content is in progress
+
+        this.logger.debug('onContentChange', {
+            contentSourceId,
+            documentCount: contentChangeEvent.documents.length,
+            assetCount: contentChangeEvent.assets.length,
+            deletedDocumentCount: contentChangeEvent.deletedDocumentIds.length,
+            deletedAssetCount: contentChangeEvent.deletedAssetIds.length
+        });
+
+        const result: ContentStoreTypes.ContentChangeResult = {
+            updatedDocuments: [],
+            updatedAssets: [],
+            deletedDocuments: [],
+            deletedAssets: []
+        };
+
+        const contentSourceData = this.getContentSourceDataByIdOrThrow(contentSourceId);
+
+        // update contentSourceData with deleted documents
+        contentChangeEvent.deletedDocumentIds.forEach((docId) => {
+            // delete document from documents map
+            delete contentSourceData.documentMap[docId];
+            delete contentSourceData.csiDocumentMap[docId];
+
+            // delete document from document array
+            const index = contentSourceData.documents.findIndex((document) => document.srcObjectId === docId);
+            if (index !== -1) {
+                // the indexes of documents and csiDocuments are always the same as they are always updated at the same time
+                contentSourceData.documents.splice(index, 1);
+                contentSourceData.csiDocuments.splice(index, 1);
+            }
+
+            result.deletedDocuments.push({
+                srcType: contentSourceData.type,
+                srcProjectId: contentSourceData.projectId,
+                srcObjectId: docId
+            });
+        });
+
+        // update contentSourceData with deleted assets
+        contentChangeEvent.deletedAssetIds.forEach((assetId) => {
+            // delete document from asset map
+            delete contentSourceData.assetMap[assetId];
+            delete contentSourceData.csiAssetMap[assetId];
+
+            // delete document from asset array
+            const index = contentSourceData.assets.findIndex((asset) => asset.srcObjectId === assetId);
+            if (index !== -1) {
+                // the indexes of assets and csiAssets are always the same as they are always updated at the same time
+                contentSourceData.assets.splice(index, 1);
+                contentSourceData.csiAssets.splice(index, 1);
+            }
+
+            result.deletedAssets.push({
+                srcType: contentSourceData.type,
+                srcProjectId: contentSourceData.projectId,
+                srcObjectId: assetId
+            });
+        });
+
+        // map csi documents and assets to content store documents and assets
+        const documents = mapCSIDocumentsToStoreDocuments({
+            csiDocuments: contentChangeEvent.documents,
+            contentSourceInstance: contentSourceData.instance,
+            modelMap: contentSourceData.modelMap,
+            defaultLocaleCode: contentSourceData.defaultLocaleCode
+        });
+        const assets = mapCSIAssetsToStoreAssets({
+            csiAssets: contentChangeEvent.assets,
+            contentSourceInstance: contentSourceData.instance,
+            defaultLocaleCode: contentSourceData.defaultLocaleCode
+        });
+
+        // update contentSourceData with new or updated documents and assets
+        Object.assign(contentSourceData.csiDocumentMap, _.keyBy(contentChangeEvent.documents, 'id'));
+        Object.assign(contentSourceData.csiAssets, _.keyBy(contentChangeEvent.assets, 'id'));
+        Object.assign(contentSourceData.documentMap, _.keyBy(documents, 'srcObjectId'));
+        Object.assign(contentSourceData.assetMap, _.keyBy(assets, 'srcObjectId'));
+
+        for (let idx = 0; idx < documents.length; idx++) {
+            // the indexes of mapped documents and documents from changeEvent are the same
+            const document = documents[idx]!;
+            const csiDocument = contentChangeEvent.documents[idx]!;
+            const dataIndex = contentSourceData.documents.findIndex((existingDoc) => existingDoc.srcObjectId === document.srcObjectId);
+            if (dataIndex === -1) {
+                contentSourceData.documents.push(document);
+                contentSourceData.csiDocuments.push(csiDocument);
+            } else {
+                // the indexes of documents and csiDocuments are always the same as they are always updated at the same time
+                contentSourceData.documents.splice(dataIndex, 1, document);
+                contentSourceData.csiDocuments.splice(dataIndex, 1, csiDocument);
+            }
+            result.updatedDocuments.push({
+                srcType: contentSourceData.type,
+                srcProjectId: contentSourceData.projectId,
+                srcObjectId: document.srcObjectId
+            });
+        }
+
+        for (let idx = 0; idx < assets.length; idx++) {
+            // the indexes of mapped assets and assets from changeEvent are the same
+            const asset = assets[idx]!;
+            const csiAsset = contentChangeEvent.assets[idx]!;
+            const index = contentSourceData.assets.findIndex((existingAsset) => existingAsset.srcObjectId === asset.srcObjectId);
+            if (index === -1) {
+                contentSourceData.assets.push(asset);
+                contentSourceData.csiAssets.push(csiAsset);
+            } else {
+                // the indexes of assets and csiAssets are always the same as they are always updated at the same time
+                contentSourceData.assets.splice(index, 1, asset);
+                contentSourceData.csiAssets.splice(index, 1, csiAsset);
+            }
+            result.updatedAssets.push({
+                srcType: contentSourceData.type,
+                srcProjectId: contentSourceData.projectId,
+                srcObjectId: asset.srcObjectId
+            });
+        }
+
+        return result;
+    }
+
+    getModels(): Record<string, Record<string, Record<string, Model>>> {
+        return _.reduce(
+            this.contentSourceDataById,
+            (result: Record<string, Record<string, Record<string, Model>>>, contentSourceData) => {
+                const contentSourceType = contentSourceData.instance.getContentSourceType();
+                const srcProjectId = contentSourceData.instance.getProjectId();
+                _.set(result, [contentSourceType, srcProjectId], contentSourceData.modelMap);
+                return result;
+            },
+            {}
+        );
+    }
+
+    getLocales(): string[] {
+        return _.reduce(
+            this.contentSourceDataById,
+            (result: string[], contentSourceData) => {
+                const locales = (contentSourceData.locales ?? []).map((locale) => locale.code);
+                return result.concat(locales);
+            },
+            []
+        );
+    }
+
+    getPresets(): Record<string, any> {
+        return this.presets ?? {};
+    }
+
+    getContentSourceEnvironment({ srcProjectId, srcType }: { srcProjectId: string; srcType: string }): string {
+        const contentSourceId = getContentSourceId(srcType, srcProjectId);
+        const contentSourceData = this.getContentSourceDataByIdOrThrow(contentSourceId);
+        return contentSourceData.instance.getProjectEnvironment();
+    }
+
+    hasAccess({ srcType, srcProjectId, user }: { srcType: string; srcProjectId: string; user?: ContentStoreTypes.User }): Promise<boolean> {
+        const contentSourceId = getContentSourceId(srcType, srcProjectId);
+        const contentSourceData = this.getContentSourceDataByIdOrThrow(contentSourceId);
+        const userContext = getUserContextForSrcType(srcType, user);
+        return contentSourceData.instance.hasAccess({ userContext });
+    }
+
+    hasChanges({
+        srcType,
+        srcProjectId,
+        documents
+    }: {
+        srcType?: string;
+        srcProjectId?: string;
+        documents?: { srcType: string; srcProjectId: string; srcObjectId: string }[];
+    }): {
+        hasChanges: boolean;
+        changedObjects: {
+            srcType: string;
+            srcProjectId: string;
+            srcObjectId: string;
+        }[];
+    } {
+        let result: (ContentStoreTypes.Document | ContentStoreTypes.Asset)[];
+        if (srcType && srcProjectId) {
+            const contentSourceId = getContentSourceId(srcType, srcProjectId);
+            const contentSourceData = this.getContentSourceDataByIdOrThrow(contentSourceId);
+            result = [...contentSourceData.documents, ...contentSourceData.assets];
+        } else if (documents && documents.length > 0) {
+            const documentsBySourceId = _.groupBy(documents, (document) => getContentSourceId(document.srcType, document.srcProjectId));
+            result = _.reduce(
+                documentsBySourceId,
+                (result: (ContentStoreTypes.Document | ContentStoreTypes.Asset)[], documents, contentSourceId) => {
+                    const contentSourceData = this.getContentSourceDataByIdOrThrow(contentSourceId);
+                    for (const document of documents) {
+                        if (document.srcObjectId in contentSourceData.documentMap) {
+                            result.push(contentSourceData.documentMap[document.srcObjectId]!);
+                        } else if (document.srcObjectId in contentSourceData.assetMap) {
+                            result.push(contentSourceData.assetMap[document.srcObjectId]!);
+                        }
+                    }
+                    return result;
+                },
+                []
+            );
+        } else {
+            result = _.reduce(
+                this.contentSourceDataById,
+                (result: (ContentStoreTypes.Document | ContentStoreTypes.Asset)[], contentSourceData) => {
+                    return result.concat(contentSourceData.documents, contentSourceData.assets);
+                },
+                []
+            );
+        }
+        const changedDocuments = result.filter((document) => document.status === 'added' || document.status === 'modified');
+        return {
+            hasChanges: !_.isEmpty(changedDocuments),
+            changedObjects: changedDocuments.map((item) => ({
+                srcType: item.srcType,
+                srcProjectId: item.srcProjectId,
+                srcObjectId: item.srcObjectId
+            }))
+        };
+    }
+
+    getDocument({
+        srcDocumentId,
+        srcProjectId,
+        srcType
+    }: {
+        srcDocumentId: string;
+        srcProjectId: string;
+        srcType: string;
+    }): ContentStoreTypes.Document | undefined {
+        const contentSourceId = getContentSourceId(srcType, srcProjectId);
+        const contentSourceData = this.getContentSourceDataByIdOrThrow(contentSourceId);
+        return contentSourceData.documentMap[srcDocumentId];
+    }
+
+    getDocuments(): ContentStoreTypes.Document[] {
+        return _.reduce(
+            this.contentSourceDataById,
+            (documents: ContentStoreTypes.Document[], contentSourceData) => {
+                return documents.concat(contentSourceData.documents);
+            },
+            []
+        );
+    }
+
+    getAsset({ srcAssetId, srcProjectId, srcType }: { srcAssetId: string; srcProjectId: string; srcType: string }): ContentStoreTypes.Asset | undefined {
+        const contentSourceId = getContentSourceId(srcType, srcProjectId);
+        const contentSourceData = this.getContentSourceDataByIdOrThrow(contentSourceId);
+        return contentSourceData.assetMap[srcAssetId];
+    }
+
+    getAssets(): ContentStoreTypes.Asset[] {
+        return _.reduce(
+            this.contentSourceDataById,
+            (assets: ContentStoreTypes.Asset[], contentSourceData) => {
+                return assets.concat(contentSourceData.assets);
+            },
+            []
+        );
+    }
+
+    getLocalizedApiObjects({ locale }: { locale?: string }): ContentStoreTypes.APIObject[] {
+        return _.reduce(
+            this.contentSourceDataById,
+            (objects: ContentStoreTypes.APIObject[], contentSourceData) => {
+                locale = locale ?? contentSourceData.defaultLocaleCode;
+                const documentObjects = mapDocumentsToLocalizedApiObjects(contentSourceData.documents, locale);
+                const imageObjects = mapAssetsToLocalizedApiImages(contentSourceData.assets, locale);
+                return objects.concat(documentObjects, imageObjects);
+            },
+            []
+        );
+    }
+
+    getApiAssets({
+        srcType,
+        srcProjectId,
+        pageSize = 20,
+        pageNum = 1,
+        searchQuery
+    }: { srcType?: string; srcProjectId?: string; pageSize?: number; pageNum?: number; searchQuery?: string } = {}): {
+        assets: ContentStoreTypes.APIAsset[];
+        pageSize: number;
+        pageNum: number;
+        totalPages: number;
+    } {
+        let assets: ContentStoreTypes.APIAsset[];
+        if (srcProjectId && srcType) {
+            const contentSourceId = getContentSourceId(srcType, srcProjectId);
+            const contentSourceData = this.getContentSourceDataByIdOrThrow(contentSourceId);
+            assets = mapStoreAssetsToAPIAssets(contentSourceData.assets, contentSourceData.defaultLocaleCode);
+        } else {
+            assets = _.reduce(
+                this.contentSourceDataById,
+                (result: ContentStoreTypes.APIAsset[], contentSourceData) => {
+                    const assets = mapStoreAssetsToAPIAssets(contentSourceData.assets, contentSourceData.defaultLocaleCode);
+                    return result.concat(assets);
+                },
+                []
+            );
+        }
+
+        let filteredFiles = assets;
+        if (searchQuery) {
+            const sanitizedSearchQuery = sanitizeFilename(searchQuery).toLowerCase();
+            filteredFiles = assets.filter((asset) => asset.fileName && path.basename(asset.fileName).toLowerCase().includes(sanitizedSearchQuery));
+        }
+        const sortedAssets = _.orderBy(filteredFiles, ['fileName'], ['asc']);
+        const skip = (pageNum - 1) * pageSize;
+        const totalPages = Math.ceil(filteredFiles.length / pageSize);
+        const pagesAssets = sortedAssets.slice(skip, skip + pageSize);
+
+        return {
+            assets: pagesAssets,
+            pageSize: pageSize,
+            pageNum: pageNum,
+            totalPages: totalPages
+        };
+    }
+
+    async createAndLinkDocument({
+        srcType,
+        srcProjectId,
+        srcDocumentId,
+        fieldPath,
+        modelName,
+        object,
+        index,
+        locale,
+        user
+    }: {
+        srcType: string;
+        srcProjectId: string;
+        srcDocumentId: string;
+        fieldPath: (string | number)[];
+        modelName?: string;
+        object?: Record<string, any>;
+        index?: number;
+        locale?: string;
+        user?: ContentStoreTypes.User;
+    }): Promise<{ srcDocumentId: string }> {
+        this.logger.debug('createAndLinkDocument', { srcType, srcProjectId, srcDocumentId, fieldPath, modelName, index, locale });
+
+        const contentSourceId = getContentSourceId(srcType, srcProjectId);
+        const contentSourceData = this.getContentSourceDataByIdOrThrow(contentSourceId);
+
+        // get the document that is being updated
+        const document = contentSourceData.documentMap[srcDocumentId];
+        const csiDocument = contentSourceData.csiDocumentMap[srcDocumentId];
+        if (!document || !csiDocument) {
+            throw new Error(`no document with id '${srcDocumentId}' was found in ${contentSourceData.id}`);
+        }
+
+        // get the document model
+        const documentModelName = document.srcModelName;
+        const csiModelMap = contentSourceData.csiModelMap;
+        const model = csiModelMap[documentModelName];
+        if (!model) {
+            throw new Error(`error updating document, could not find document model: '${documentModelName}'`);
+        }
+
+        // get the 'reference' model field in the updated document that will be used to link the new document
+        locale = locale ?? contentSourceData.defaultLocaleCode;
+        const modelField = getModelFieldForFieldAtPath(document, model, fieldPath, csiModelMap, locale);
+        if (!modelField) {
+            throw Error(`the "fieldPath" points to non existing model field: ${fieldPath.join('.')}`);
+        }
+        const fieldProps = modelField.type === 'list' ? modelField.items! : modelField;
+        if (fieldProps.type !== 'reference') {
+            throw Error(`error in "createAndLinkDocument", this operation can only be used on reference field: ${fieldPath.join('.')}`);
+        }
+
+        // get the model name for the new document
+        if (!modelName && fieldProps.models.length === 1) {
+            modelName = fieldProps.models[0];
+        }
+        if (!modelName) {
+            throw Error(`error in "createAndLinkDocument", missing "modelName": ${fieldPath.join('.')}`);
+        }
+
+        // create the new document
+        const result = await this.createDocument({
+            object: object,
+            srcProjectId: srcProjectId,
+            srcType: srcType,
+            modelName: modelName,
+            locale: locale,
+            user: user
+        });
+
+        // update the document by linking the field to the created document
+        const userContext = getUserContextForSrcType(srcType, user);
+        const field = {
+            type: 'reference',
+            refType: 'document',
+            refId: result.srcDocumentId
+        } as const;
+        const updatedDocument = await contentSourceData.instance.updateDocument({
+            document: csiDocument,
+            modelMap: csiModelMap,
+            userContext: userContext,
+            operations: [
+                modelField.type === 'list'
+                    ? {
+                          opType: 'insert',
+                          fieldPath: fieldPath,
+                          modelField: modelField,
+                          locale: locale,
+                          index: index,
+                          item: field
+                      }
+                    : {
+                          opType: 'set',
+                          fieldPath: fieldPath,
+                          modelField: modelField,
+                          locale: locale,
+                          field: field
+                      }
+            ]
+        });
+        return { srcDocumentId: updatedDocument.id };
+    }
+
+    async uploadAndLinkAsset({
+        srcType,
+        srcProjectId,
+        srcDocumentId,
+        fieldPath,
+        asset,
+        index,
+        locale,
+        user
+    }: {
+        srcType: string;
+        srcProjectId: string;
+        srcDocumentId: string;
+        fieldPath: (string | number)[];
+        asset: ContentStoreTypes.UploadAssetData;
+        index?: number;
+        locale?: string;
+        user?: ContentStoreTypes.User;
+    }): Promise<{ srcDocumentId: string }> {
+        this.logger.debug('uploadAndLinkAsset', { srcType, srcProjectId, srcDocumentId, fieldPath, index, locale });
+
+        // get the document that is being updated
+        const contentSourceId = getContentSourceId(srcType, srcProjectId);
+        const contentSourceData = this.getContentSourceDataByIdOrThrow(contentSourceId);
+        const document = contentSourceData.documentMap[srcDocumentId];
+        const csiDocument = contentSourceData.csiDocumentMap[srcDocumentId];
+        if (!document || !csiDocument) {
+            throw new Error(`no document with id '${srcDocumentId}' was found in ${contentSourceData.id}`);
+        }
+
+        // get the document model
+        const documentModelName = document.srcModelName;
+        const csiModelMap = contentSourceData.csiModelMap;
+        const csiModel = csiModelMap[documentModelName];
+        if (!csiModel) {
+            throw new Error(`error updating document, could not find document model: '${documentModelName}'`);
+        }
+
+        // get the 'reference' model field in the updated document that will be used to link the new asset
+        locale = locale ?? contentSourceData.defaultLocaleCode;
+        const modelField = getModelFieldForFieldAtPath(document, csiModel, fieldPath, csiModelMap, locale);
+        if (!modelField) {
+            throw Error(`the "fieldPath" points to non existing model field: ${fieldPath.join('.')}`);
+        }
+        const fieldProps = modelField.type === 'list' ? modelField.items! : modelField;
+        if (fieldProps.type !== 'reference' && fieldProps.type !== 'image') {
+            throw Error(`error in "uploadAndLinkAsset", this operation can only be used on reference and image fields: ${fieldPath.join('.')}`);
+        }
+
+        // upload the new asset
+        const userContext = getUserContextForSrcType(srcType, user);
+        const result = await contentSourceData.instance.uploadAsset({
+            url: asset.url,
+            fileName: asset.metadata.name,
+            mimeType: asset.metadata.type,
+            locale: locale,
+            userContext: userContext
+        });
+
+        // update the document by linking the field to the created asset
+        const field = {
+            type: 'reference',
+            refType: 'asset',
+            refId: result.id
+        } as const;
+        const updatedDocument = await contentSourceData.instance.updateDocument({
+            document: csiDocument,
+            modelMap: csiModelMap,
+            userContext: userContext,
+            operations: [
+                modelField.type === 'list'
+                    ? {
+                          opType: 'insert',
+                          fieldPath: fieldPath,
+                          modelField: modelField,
+                          locale: locale,
+                          index: index,
+                          item: field
+                      }
+                    : {
+                          opType: 'set',
+                          fieldPath: fieldPath,
+                          modelField: modelField,
+                          locale: locale,
+                          field: field
+                      }
+            ]
+        });
+        return { srcDocumentId: updatedDocument.id };
+    }
+
+    async createDocument({
+        srcType,
+        srcProjectId,
+        modelName,
+        object,
+        locale,
+        user
+    }: {
+        srcType: string;
+        srcProjectId: string;
+        modelName: string;
+        object?: Record<string, any>;
+        locale?: string;
+        user?: ContentStoreTypes.User;
+    }): Promise<{ srcDocumentId: string }> {
+        this.logger.debug('createDocument', { srcType, srcProjectId, modelName, locale });
+
+        const contentSourceId = getContentSourceId(srcType, srcProjectId);
+        const contentSourceData = this.getContentSourceDataByIdOrThrow(contentSourceId);
+        const modelMap = contentSourceData.modelMap;
+        const model = modelMap[modelName];
+        if (!model) {
+            throw new Error(`no model with name '${modelName}' was found`);
+        }
+
+        locale = locale ?? contentSourceData.defaultLocaleCode;
+        const userContext = getUserContextForSrcType(srcType, user);
+        const result = await createDocumentRecursively({
+            object,
+            model,
+            modelMap,
+            locale,
+            userContext,
+            contentSourceInstance: contentSourceData.instance
+        });
+        this.logger.debug('created document', { srcType, srcProjectId, srcDocumentId: result.document.id, modelName });
+
+        // do not update cache in contentSourceData.documents and documentMap,
+        // instead wait for contentSource to call onContentChange(contentChangeEvent)
+        // and use data from contentChangeEvent to update the cache
+        // const newDocuments = [result.document, ...result.referencedDocuments];
+        // contentSourceData.documentMap = Object.assign(contentSourceData.documentMap, _.keyBy(newDocuments, 'srcObjectId'));
+
+        return { srcDocumentId: result.document.id };
+    }
+
+    async updateDocument({
+        srcType,
+        srcProjectId,
+        srcDocumentId,
+        updateOperations,
+        user
+    }: {
+        srcType: string;
+        srcProjectId: string;
+        srcDocumentId: string;
+        updateOperations: ContentStoreTypes.UpdateOperation[];
+        user?: ContentStoreTypes.User;
+    }): Promise<{ srcDocumentId: string }> {
+        this.logger.debug('updateDocument');
+
+        const contentSourceId = getContentSourceId(srcType, srcProjectId);
+        const contentSourceData = this.getContentSourceDataByIdOrThrow(contentSourceId);
+        const userContext = getUserContextForSrcType(srcType, user);
+        const document = contentSourceData.documentMap[srcDocumentId];
+        const csiDocument = contentSourceData.csiDocumentMap[srcDocumentId];
+        if (!document || !csiDocument) {
+            throw new Error(`no document with id '${srcDocumentId}' was found in ${contentSourceData.id}`);
+        }
+
+        const modelMap = contentSourceData.modelMap;
+        const csiModelMap = contentSourceData.csiModelMap;
+        const documentModelName = document.srcModelName;
+        const model = modelMap[documentModelName];
+        if (!model) {
+            throw new Error(`error updating document, could not find document model: '${documentModelName}'`);
+        }
+
+        const operations = await mapPromise(
+            updateOperations,
+            async (updateOperation): Promise<CSITypes.UpdateOperation> => {
+                const locale = updateOperation.locale ?? contentSourceData.defaultLocaleCode;
+                const modelField = getModelFieldForFieldAtPath(document, model, updateOperation.fieldPath, modelMap, locale);
+                switch (updateOperation.opType) {
+                    case 'set':
+                        const field = await convertOperationField({
+                            operationField: updateOperation.field,
+                            fieldPath: updateOperation.fieldPath,
+                            locale: updateOperation.locale,
+                            modelField,
+                            modelMap,
+                            userContext,
+                            contentSourceInstance: contentSourceData.instance
+                        });
+                        return {
+                            ...updateOperation,
+                            modelField,
+                            field
+                        };
+                    case 'unset':
+                        return { ...updateOperation, modelField };
+                    case 'insert':
+                        const item = await convertOperationField({
+                            operationField: updateOperation.item,
+                            fieldPath: updateOperation.fieldPath,
+                            locale: updateOperation.locale,
+                            modelField,
+                            modelMap,
+                            userContext,
+                            contentSourceInstance: contentSourceData.instance
+                        });
+                        return {
+                            ...updateOperation,
+                            modelField,
+                            item
+                        };
+                    case 'remove':
+                        return { ...updateOperation, modelField };
+                    case 'reorder':
+                        return { ...updateOperation, modelField };
+                }
+            }
+        );
+
+        const updatedDocumentResult = await contentSourceData.instance.updateDocument({
+            document: csiDocument,
+            modelMap: csiModelMap,
+            userContext,
+            operations
+        });
+
+        // do not update cache in contentSourceData.documents and documentMap,
+        // instead wait for contentSource to call onContentChange(contentChangeEvent)
+        // and use data from contentChangeEvent to update the cache
+        // contentSourceData.documentMap = Object.assign(contentSourceData.documentMap, { [document.srcObjectId]: document });
+
+        return { srcDocumentId: updatedDocumentResult.id };
+    }
+
+    async duplicateDocument({
+        srcType,
+        srcProjectId,
+        srcDocumentId,
+        object,
+        user
+    }: {
+        srcType: string;
+        srcProjectId: string;
+        srcDocumentId: string;
+        object?: Record<string, any>;
+        user?: ContentStoreTypes.User;
+    }): Promise<{ srcDocumentId: string }> {
+        this.logger.debug('duplicateDocument');
+
+        const contentSourceId = getContentSourceId(srcType, srcProjectId);
+        const contentSourceData = this.getContentSourceDataByIdOrThrow(contentSourceId);
+        const document = contentSourceData.documentMap[srcDocumentId];
+        if (!document) {
+            throw new Error(`no document with id '${srcDocumentId}' was found in ${contentSourceData.id}`);
+        }
+        const modelMap = contentSourceData.modelMap;
+        const model = modelMap[document.srcModelName];
+        if (!model) {
+            throw new Error(`no model with name '${document.srcModelName}' was found`);
+        }
+
+        const userContext = getUserContextForSrcType(srcType, user);
+
+        // TODO: take the data from the provided 'object' and merge them with
+        //   DocumentFields of the existing Document:
+        //   Option 1: Map the DocumentFields of the existing Document into flat
+        //     object with '$$ref' and '$type' properties for references and
+        //     nested objects (needs to be implemented), and then merge it with
+        //     the provided object recursively, and then pass that object to
+        //     createNestedObjectRecursively()
+        //   Options 2: Converting the provided object into a Document with
+        //     DocumentFields and then merging both documents into a single
+        //     Document and then calling mapStoreFieldsToOperationFields (needs to be implemented)
+        //   While doing all that, need to handle existing references in the
+        //     existing Document and to duplicate the referenced documents if their
+        //     model is marked as 'duplicatable' and to reuse the existing documents
+        //     if their model is marked as non-duplicatable.
+        const updateOperationFields = mapStoreFieldsToOperationFields({
+            documentFields: document.fields,
+            modelFields: model.fields!,
+            modelMap: contentSourceData.modelMap
+        });
+
+        const documentResult = await contentSourceData.instance.createDocument({
+            updateOperationFields,
+            // TODO: pass csiModel
+            model,
+            // TODO: pass csiModelMap
+            modelMap,
+            locale: contentSourceData.defaultLocaleCode,
+            userContext
+        });
+
+        return { srcDocumentId: documentResult.id };
+    }
+
+    async uploadAssets({
+        srcType,
+        srcProjectId,
+        assets,
+        locale,
+        user
+    }: {
+        srcType: string;
+        srcProjectId: string;
+        assets: ContentStoreTypes.UploadAssetData[];
+        locale?: string;
+        user?: ContentStoreTypes.User;
+    }): Promise<ContentStoreTypes.APIAsset[]> {
+        this.logger.debug('uploadAssets');
+
+        const contentSourceId = getContentSourceId(srcType, srcProjectId);
+        const contentSourceData = this.getContentSourceDataByIdOrThrow(contentSourceId);
+        const sourceAssets: CSITypes.Asset[] = [];
+        const userContext = getUserContextForSrcType(srcType, user);
+
+        locale = locale ?? contentSourceData.defaultLocaleCode;
+
+        for (const asset of assets) {
+            let base64 = undefined;
+            if (asset.data) {
+                const matchResult = asset.data.match(/;base64,([\s\S]+)$/);
+                if (matchResult) {
+                    base64 = matchResult[1];
+                }
+            }
+            const sourceAsset = await contentSourceData.instance.uploadAsset({
+                url: asset.url,
+                base64: base64,
+                fileName: asset.metadata.name,
+                mimeType: asset.metadata.type,
+                locale: locale,
+                userContext: userContext
+            });
+            sourceAssets.push(sourceAsset);
+        }
+        const storeAssets = mapCSIAssetsToStoreAssets({
+            csiAssets: sourceAssets,
+            contentSourceInstance: contentSourceData.instance,
+            defaultLocaleCode: contentSourceData.defaultLocaleCode
+        });
+        return mapStoreAssetsToAPIAssets(storeAssets, locale);
+    }
+
+    async deleteDocument({
+        srcType,
+        srcProjectId,
+        srcDocumentId,
+        user
+    }: {
+        srcType: string;
+        srcProjectId: string;
+        srcDocumentId: string;
+        user?: ContentStoreTypes.User;
+    }) {
+        this.logger.debug('deleteDocument');
+
+        const userContext = getUserContextForSrcType(srcType, user);
+        const contentSourceId = getContentSourceId(srcType, srcProjectId);
+        const contentSourceData = this.getContentSourceDataByIdOrThrow(contentSourceId);
+        const csiDocument = contentSourceData.csiDocumentMap[srcDocumentId];
+        if (!csiDocument) {
+            throw new Error(`no document with id '${srcDocumentId}' was found in ${contentSourceData.id}`);
+        }
+        await contentSourceData.instance.deleteDocument({ document: csiDocument, userContext });
+
+        // do not update cache in contentSourceData.documents and documentMap,
+        // instead wait for contentSource to call onContentChange(contentChangeEvent)
+        // and use data from contentChangeEvent to update the cache
+        // delete contentSourceData.documentMap[srcDocumentId];
+    }
+
+    async validateDocuments({
+        objects,
+        locale,
+        user
+    }: {
+        objects: { srcType: string; srcProjectId: string; srcObjectId: string }[];
+        locale?: string;
+        user?: ContentStoreTypes.User;
+    }): Promise<{ errors: ContentStoreTypes.ValidationError[] }> {
+        this.logger.debug('validateDocuments');
+
+        const objectsBySourceId = _.groupBy(objects, (object) => getContentSourceId(object.srcType, object.srcProjectId));
+        let errors: ContentStoreTypes.ValidationError[] = [];
+        for (const [contentSourceId, contentSourceObjects] of Object.entries(objectsBySourceId)) {
+            const contentSourceData = this.getContentSourceDataByIdOrThrow(contentSourceId);
+            locale = locale ?? contentSourceData.defaultLocaleCode;
+            const { documents, assets } = getCSIDocumentsAndAssetsFromContentSourceDataByIds(contentSourceData, contentSourceObjects);
+            const userContext = getUserContextForSrcType(contentSourceData.type, user);
+            const internalValidationErrors = internalValidateContent(documents, assets, contentSourceData);
+            const validationResult = await contentSourceData.instance.validateDocuments({ documents, assets, locale, userContext });
+            errors = errors.concat(
+                internalValidationErrors,
+                validationResult.errors.map((validationError) => ({
+                    message: validationError.message,
+                    srcType: contentSourceData.type,
+                    srcProjectId: contentSourceData.projectId,
+                    srcObjectType: validationError.objectType,
+                    srcObjectId: validationError.objectId,
+                    fieldPath: validationError.fieldPath,
+                    isUniqueValidation: validationError.isUniqueValidation
+                }))
+            );
+        }
+
+        return { errors };
+
+        /* validate for multiple sources
+        const objectsBySourceId = _.groupBy(objects, (document) => getContentSourceId(document.srcType, document.srcProjectId));
+        const contentSourceIds = Object.keys(objectsBySourceId);
+        return reducePromise(
+            contentSourceIds,
+            async (result: ContentStoreTypes.ValidationError[], contentSourceId) => {
+                const documents = documentsBySourceId[contentSourceId]!;
+                const contentSourceData = this.getContentSourceDataByIdOrThrow(contentSourceId);
+                const validationErrors = await contentSourceData.instance.validateDocuments({ documentIds: documents.map((document) => document.srcObjectId) });
+                return result.concat(validationErrors);
+            },
+            []
+        );
+         */
+    }
+
+    async publishDocuments({ objects, user }: { objects: { srcType: string; srcProjectId: string; srcObjectId: string }[]; user?: ContentStoreTypes.User }) {
+        this.logger.debug('publishDocuments');
+
+        const objectsBySourceId = _.groupBy(objects, (object) => getContentSourceId(object.srcType, object.srcProjectId));
+        for (const [contentSourceId, contentSourceObjects] of Object.entries(objectsBySourceId)) {
+            const contentSourceData = this.getContentSourceDataByIdOrThrow(contentSourceId);
+            const userContext = getUserContextForSrcType(contentSourceData.type, user);
+            const { documents, assets } = getCSIDocumentsAndAssetsFromContentSourceDataByIds(contentSourceData, contentSourceObjects);
+            await contentSourceData.instance.publishDocuments({ documents, assets, userContext });
+        }
+    }
+
+    private getContentSourceDataByIdOrThrow(contentSourceId: string): ContentSourceData {
+        const contentSourceData = this.contentSourceDataById[contentSourceId];
+        if (!contentSourceData) {
+            throw new Error(`no content source for id '${contentSourceId}' was found`);
+        }
+        return contentSourceData;
+    }
+}
+
+export function getContentSourceId(contentSourceType: string, srcProjectId: string) {
+    return contentSourceType + ':' + srcProjectId;
+}
+
+function getUserContextForSrcType(srcType: string, user?: ContentStoreTypes.User): unknown {
+    return user?.connections?.find((connection) => connection.type === srcType);
+}
+
+function mapCSIAssetsToStoreAssets({
+    csiAssets,
+    contentSourceInstance,
+    defaultLocaleCode
+}: {
+    csiAssets: CSITypes.Asset[];
+    contentSourceInstance: CSITypes.ContentSourceInterface;
+    defaultLocaleCode?: string;
+}): ContentStoreTypes.Asset[] {
+    const extra = {
+        srcType: contentSourceInstance.getContentSourceType(),
+        srcProjectId: contentSourceInstance.getProjectId(),
+        srcProjectUrl: contentSourceInstance.getProjectManageUrl(),
+        srcEnvironment: contentSourceInstance.getProjectEnvironment()
+    };
+    return csiAssets.map((csiAsset) => sourceAssetToStoreAsset({ csiAsset, defaultLocaleCode, extra }));
+}
+
+function sourceAssetToStoreAsset({
+    csiAsset,
+    defaultLocaleCode,
+    extra
+}: {
+    csiAsset: CSITypes.Asset;
+    defaultLocaleCode?: string;
+    extra: { srcType: string; srcProjectId: string; srcProjectUrl: string; srcEnvironment: string };
+}): ContentStoreTypes.Asset {
+    return {
+        type: 'asset',
+        ...extra,
+        srcObjectId: csiAsset.id,
+        srcObjectUrl: csiAsset.manageUrl,
+        srcObjectLabel: getObjectLabel(csiAsset.fields, IMAGE_MODEL, defaultLocaleCode),
+        srcModelName: IMAGE_MODEL.name,
+        srcModelLabel: IMAGE_MODEL.label!,
+        isChanged: csiAsset.status === 'added' || csiAsset.status === 'modified',
+        status: csiAsset.status,
+        createdAt: csiAsset.createdAt,
+        createdBy: csiAsset.createdBy,
+        updatedAt: csiAsset.updatedAt,
+        updatedBy: csiAsset.updatedBy,
+        fields: {
+            title: {
+                label: 'Title',
+                ...csiAsset.fields.title
+            },
+            file: {
+                label: 'File',
+                ...csiAsset.fields.file
+            }
+        }
+    };
+}
+
+function mapCSIDocumentsToStoreDocuments({
+    csiDocuments,
+    contentSourceInstance,
+    modelMap,
+    defaultLocaleCode
+}: {
+    csiDocuments: CSITypes.Document[];
+    contentSourceInstance: CSITypes.ContentSourceInterface;
+    modelMap: Record<string, Model>;
+    defaultLocaleCode?: string;
+}): ContentStoreTypes.Document[] {
+    const extra = {
+        srcType: contentSourceInstance.getContentSourceType(),
+        srcProjectId: contentSourceInstance.getProjectId(),
+        srcProjectUrl: contentSourceInstance.getProjectManageUrl(),
+        srcEnvironment: contentSourceInstance.getProjectEnvironment()
+    };
+    return csiDocuments.map((csiDocument) =>
+        mapCSIDocumentToStoreDocument({ csiDocument, model: modelMap[csiDocument.modelName]!, modelMap, defaultLocaleCode, extra })
+    );
+}
+
+function mapCSIDocumentToStoreDocument({
+    csiDocument,
+    model,
+    modelMap,
+    defaultLocaleCode,
+    extra
+}: {
+    csiDocument: CSITypes.Document;
+    model: Model;
+    modelMap: Record<string, Model>;
+    defaultLocaleCode?: string;
+    extra: { srcType: string; srcProjectId: string; srcProjectUrl: string; srcEnvironment: string };
+}): ContentStoreTypes.Document {
+    return {
+        type: 'document',
+        ...extra,
+        srcObjectId: csiDocument.id,
+        srcObjectUrl: csiDocument.manageUrl,
+        srcObjectLabel: getObjectLabel(csiDocument.fields, model, defaultLocaleCode),
+        srcModelLabel: model.label ?? _.startCase(csiDocument.modelName),
+        srcModelName: csiDocument.modelName,
+        isChanged: csiDocument.status === 'added' || csiDocument.status === 'modified',
+        status: csiDocument.status,
+        createdAt: csiDocument.createdAt,
+        createdBy: csiDocument.createdBy,
+        updatedAt: csiDocument.updatedAt,
+        updatedBy: csiDocument.updatedBy,
+        fields: mapCSIFieldsToStoreFields({
+            csiDocumentFields: csiDocument.fields,
+            modelFields: model.fields ?? [],
+            context: {
+                modelMap,
+                defaultLocaleCode
+            }
+        })
+    };
+}
+
+type MapContext = {
+    modelMap: Record<string, Model>;
+    defaultLocaleCode?: string;
+};
+
+function mapCSIFieldsToStoreFields({
+    csiDocumentFields,
+    modelFields,
+    context
+}: {
+    csiDocumentFields: Record<string, CSITypes.DocumentField>;
+    modelFields: Field[];
+    context: MapContext;
+}): Record<string, ContentStoreTypes.DocumentField> {
+    return modelFields.reduce((result: Record<string, ContentStoreTypes.DocumentField>, modelField) => {
+        const csiDocumentField = csiDocumentFields[modelField.name];
+        const docField = mapCSIFieldToStoreField({
+            csiDocumentField,
+            modelField,
+            context
+        });
+        docField.label = modelField.label;
+        result[modelField.name] = docField;
+        return result;
+    }, {});
+}
+
+function mapCSIFieldToStoreField({
+    csiDocumentField,
+    modelField,
+    context
+}: {
+    csiDocumentField: CSITypes.DocumentField | undefined;
+    modelField: FieldSpecificProps;
+    context: MapContext;
+}): ContentStoreTypes.DocumentField {
+    if (!csiDocumentField) {
+        const isUnset = ['object', 'model', 'reference', 'richText', 'markdown', 'image', 'file', 'json'].includes(modelField.type);
+        return {
+            type: modelField.type,
+            ...(isUnset ? { isUnset } : null),
+            ...(modelField.type === 'list' ? { items: [] } : null)
+        } as ContentStoreTypes.DocumentField;
+    }
+    // TODO: check if need to add "options" to "enum" and subtype/min/max to "number"
+    switch (modelField.type) {
+        case 'object':
+            return mapObjectField(csiDocumentField as CSITypes.DocumentObjectField, modelField, context);
+        case 'model':
+            return mapModelField(csiDocumentField as CSITypes.DocumentModelField, modelField, context);
+        case 'list':
+            return mapListField(csiDocumentField as CSITypes.DocumentListField, modelField, context);
+        case 'richText':
+            return mapRichTextField(csiDocumentField as CSITypes.DocumentRichTextField);
+        case 'markdown':
+            return mapMarkdownField(csiDocumentField as CSITypes.DocumentValueField);
+        default:
+            return csiDocumentField as ContentStoreTypes.DocumentField;
+    }
+}
+
+function mapObjectField(
+    csiDocumentField: CSITypes.DocumentObjectField,
+    modelField: FieldObjectProps,
+    context: MapContext
+): ContentStoreTypes.DocumentObjectField {
+    if (!isLocalizedField(csiDocumentField)) {
+        return {
+            type: csiDocumentField.type,
+            srcObjectLabel: getObjectLabel(csiDocumentField.fields ?? {}, modelField ?? [], context.defaultLocaleCode),
+            fields: mapCSIFieldsToStoreFields({
+                csiDocumentFields: csiDocumentField.fields ?? {},
+                modelFields: modelField.fields ?? [],
+                context
+            })
+        };
+    }
+    return {
+        type: csiDocumentField.type,
+        localized: true,
+        locales: _.mapValues(csiDocumentField.locales, (locale) => {
+            return {
+                locale: locale.locale,
+                srcObjectLabel: getObjectLabel(locale.fields ?? {}, modelField, locale.locale),
+                fields: mapCSIFieldsToStoreFields({
+                    csiDocumentFields: locale.fields ?? {},
+                    modelFields: modelField.fields ?? [],
+                    context
+                })
+            };
+        })
+    };
+}
+
+function mapModelField(csiDocumentField: CSITypes.DocumentModelField, modelField: FieldModelProps, context: MapContext): ContentStoreTypes.DocumentModelField {
+    if (!isLocalizedField(csiDocumentField)) {
+        const model = context.modelMap[csiDocumentField.modelName]!;
+        return {
+            type: csiDocumentField.type,
+            srcObjectLabel: getObjectLabel(csiDocumentField.fields ?? {}, model, context.defaultLocaleCode),
+            srcModelName: csiDocumentField.modelName,
+            srcModelLabel: model.label ?? _.startCase(model.name),
+            fields: mapCSIFieldsToStoreFields({
+                csiDocumentFields: csiDocumentField.fields ?? {},
+                modelFields: model.fields ?? [],
+                context
+            })
+        };
+    }
+    return {
+        type: csiDocumentField.type,
+        localized: true,
+        locales: _.mapValues(csiDocumentField.locales, (locale) => {
+            const model = context.modelMap[locale.modelName]!;
+            return {
+                locale: locale.locale,
+                srcObjectLabel: getObjectLabel(locale.fields ?? {}, model, locale.locale),
+                srcModelName: locale.modelName,
+                srcModelLabel: model.label ?? _.startCase(model.name),
+                fields: mapCSIFieldsToStoreFields({
+                    csiDocumentFields: locale.fields ?? {},
+                    modelFields: model.fields ?? [],
+                    context
+                })
+            };
+        })
+    };
+}
+
+function mapListField(csiDocumentField: CSITypes.DocumentListField, modelField: FieldListProps, context: MapContext): ContentStoreTypes.DocumentListField {
+    if (!isLocalizedField(csiDocumentField)) {
+        return {
+            type: csiDocumentField.type,
+            items: csiDocumentField.items.map((item) =>
+                mapCSIFieldToStoreField({
+                    csiDocumentField: item,
+                    modelField: modelField.items ?? { type: 'string' },
+                    context
+                })
+            )
+        };
+    }
+    return {
+        type: csiDocumentField.type,
+        localized: true,
+        locales: _.mapValues(csiDocumentField.locales, (locale) => {
+            return {
+                locale: locale.locale,
+                items: (locale.items ?? []).map((item) =>
+                    mapCSIFieldToStoreField({
+                        csiDocumentField: item,
+                        modelField: modelField.items ?? { type: 'string' },
+                        context
+                    })
+                )
+            };
+        })
+    };
+}
+
+function mapRichTextField(csiDocumentField: CSITypes.DocumentRichTextField): ContentStoreTypes.DocumentRichTextField {
+    if (!isLocalizedField(csiDocumentField)) {
+        return {
+            ...csiDocumentField,
+            multiElement: true
+        };
+    }
+    return {
+        type: csiDocumentField.type,
+        localized: true,
+        locales: _.mapValues(csiDocumentField.locales, (locale) => {
+            return {
+                ...locale,
+                multiElement: true
+            };
+        })
+    };
+}
+
+function mapMarkdownField(csiDocumentField: CSITypes.DocumentValueField): ContentStoreTypes.DocumentMarkdownField {
+    if (!isLocalizedField(csiDocumentField)) {
+        return {
+            type: 'markdown',
+            value: csiDocumentField.value,
+            multiElement: true
+        };
+    }
+    return {
+        type: 'markdown',
+        localized: true,
+        locales: _.mapValues(csiDocumentField.locales, (locale) => {
+            return {
+                ...locale,
+                multiElement: true
+            };
+        })
+    };
+}
+
+function mapStoreFieldsToOperationFields({
+    documentFields,
+    modelFields,
+    modelMap
+}: {
+    documentFields: Record<string, ContentStoreTypes.DocumentField>;
+    modelFields: Field[];
+    modelMap: Record<string, Model>;
+}): Record<string, CSITypes.UpdateOperationField> {
+    // TODO: implement
+    throw new Error(`duplicateDocument not implemented yet`);
+}
+
+function getContentSourceIdForContentSource(contentSource: CSITypes.ContentSourceInterface): string {
+    return getContentSourceId(contentSource.getContentSourceType(), contentSource.getProjectId());
+}
+
+function extractTokensFromString(input: string): string[] {
+    return input.match(/(?<={)[^}]+(?=})/g) || [];
+}
+
+function sanitizeSlug(slug: string) {
+    return slug
+        .split('/')
+        .map((part) => slugify(part, { lower: true }))
+        .join('/');
+}
+
+function getObjectLabel(
+    documentFields: Record<string, CSITypes.DocumentField | CSITypes.AssetFileField>,
+    modelOrObjectField: Model | FieldObjectProps,
+    locale?: string
+): string {
+    const labelField = modelOrObjectField.labelField;
+    let label = null;
+    if (labelField) {
+        const field = _.get(documentFields, labelField, null);
+        if (field && ['string', 'url', 'slug', 'text', 'markdown', 'number', 'enum', 'date', 'datetime', 'color', 'image', 'file'].includes(field.type)) {
+            if (isLocalizedField(field) && locale) {
+                label = _.get(field, ['locales', locale, 'value'], null);
+            } else if (!isLocalizedField(field)) {
+                label = _.get(field, 'value', null);
+            }
+        }
+    }
+    if (!label) {
+        label = _.get(modelOrObjectField, 'label');
+    }
+    if (!label && _.has(modelOrObjectField, 'name')) {
+        label = _.startCase(_.get(modelOrObjectField, 'name'));
+    }
+    return label;
+}
+
+function mapDocumentsToLocalizedApiObjects(documents: ContentStoreTypes.Document[], locale?: string): ContentStoreTypes.APIDocumentObject[] {
+    return documents.map((document) => documentToLocalizedApiObject(document, locale));
+}
+
+function documentToLocalizedApiObject(document: ContentStoreTypes.Document, locale?: string): ContentStoreTypes.APIDocumentObject {
+    const { type, fields, ...rest } = document;
+    return {
+        type: 'object',
+        ...rest,
+        fields: toLocalizedAPIFields(fields, locale)
+    };
+}
+
+function toLocalizedAPIFields(docFields: Record<string, ContentStoreTypes.DocumentField>, locale?: string): Record<string, ContentStoreTypes.DocumentFieldAPI> {
+    return _.mapValues(docFields, (docField) => toLocalizedAPIField(docField, locale));
+}
+
+function toLocalizedAPIField(docField: ContentStoreTypes.DocumentField, locale?: string, isListItem = false): ContentStoreTypes.DocumentFieldAPI {
+    const hasUnsetFlag = ['object', 'model', 'reference', 'richText', 'markdown', 'image', 'file', 'json'].includes(docField.type);
+    let docFieldLocalized: ContentStoreTypes.DocumentFieldNonLocalized;
+    let unset = false;
+    if (docField.localized) {
+        const { locales, localized, ...base } = docField;
+        const localeProps = locale ? locales[locale] : undefined;
+        docFieldLocalized = {
+            ...base,
+            ...localeProps,
+            ...(hasUnsetFlag && !localeProps ? { isUnset: true } : null)
+        } as ContentStoreTypes.DocumentFieldNonLocalized;
+    } else {
+        docFieldLocalized = docField;
+    }
+
+    locale = locale ?? docFieldLocalized.locale;
+    const commonProps = isListItem
+        ? null
+        : {
+              localized: !!docField.localized,
+              ...(locale ? { locale } : null)
+          };
+
+    if (docFieldLocalized.type === 'object' || docFieldLocalized.type === 'model') {
+        return {
+            ...docFieldLocalized,
+            type: 'object',
+            ...commonProps,
+            ...(docFieldLocalized.isUnset
+                ? null
+                : {
+                      fields: toLocalizedAPIFields(docFieldLocalized.fields, locale)
+                  })
+        } as ContentStoreTypes.DocumentObjectFieldAPI | ContentStoreTypes.DocumentModelFieldAPI;
+    } else if (docFieldLocalized.type === 'reference') {
+        const { type, refType, ...rest } = docFieldLocalized;
+        // if reference field isUnset === true, it behaves like a regular object
+        if (rest.isUnset) {
+            return {
+                type: 'object',
+                ...rest,
+                ...commonProps
+            };
+        }
+        return {
+            type: 'unresolved_reference',
+            refType: refType === 'asset' ? 'image' : 'object',
+            ...rest,
+            ...commonProps
+        };
+    } else if (docFieldLocalized.type === 'list') {
+        const { items, ...rest } = docFieldLocalized;
+        return {
+            ...rest,
+            ...commonProps,
+            items: items.map((field) => toLocalizedAPIField(field, locale, true))
+        };
+    } else {
+        return {
+            ...docFieldLocalized,
+            ...commonProps
+        };
+    }
+}
+
+function mapAssetsToLocalizedApiImages(assets: ContentStoreTypes.Asset[], locale?: string): ContentStoreTypes.APIImageObject[] {
+    return assets.map((asset) => assetToLocalizedApiImage(asset, locale));
+}
+
+function assetToLocalizedApiImage(asset: ContentStoreTypes.Asset, locale?: string): ContentStoreTypes.APIImageObject {
+    const { type, fields, ...rest } = asset;
+    return {
+        type: 'image',
+        ...rest,
+        fields: localizeAssetFields(fields, locale)
+    };
+}
+
+function localizeAssetFields(assetFields: ContentStoreTypes.AssetFields, locale?: string): ContentStoreTypes.AssetFieldsAPI {
+    const fields: ContentStoreTypes.AssetFieldsAPI = {
+        title: {
+            type: 'string' as const,
+            value: null as any
+        },
+        url: {
+            type: 'string' as const,
+            value: null as any
+        }
+    };
+    const titleFieldNonLocalized = getDocumentFieldForLocale(assetFields.title, locale);
+    fields.title.value = titleFieldNonLocalized?.value;
+    fields.title.locale = locale ?? titleFieldNonLocalized?.locale;
+    const assetFileField = assetFields.file;
+    if (assetFileField.localized) {
+        if (locale) {
+            fields.url.value = assetFileField.locales[locale]?.url ?? null;
+            fields.url.locale = locale;
+        }
+    } else {
+        fields.url.value = assetFileField.url;
+        fields.url.locale = assetFileField.locale;
+    }
+    return fields;
+}
+
+function mapStoreAssetsToAPIAssets(assets: ContentStoreTypes.Asset[], locale?: string): ContentStoreTypes.APIAsset[] {
+    return assets.map((asset) => storeAssetToAPIAsset(asset, locale));
+}
+
+function storeAssetToAPIAsset(asset: ContentStoreTypes.Asset, locale?: string): ContentStoreTypes.APIAsset {
+    const assetTitleField = asset.fields.title;
+    const localizedTitleField = assetTitleField.localized ? assetTitleField.locales[locale!]! : assetTitleField;
+    const assetFileField = asset.fields.file;
+    const localizedFileField = assetFileField.localized ? assetFileField.locales[locale!]! : assetFileField;
+    return {
+        objectId: asset.srcObjectId,
+        createdAt: asset.createdAt,
+        url: localizedFileField.url,
+        ...omitByNil({
+            title: localizedTitleField.value,
+            fileName: localizedFileField.fileName,
+            contentType: localizedFileField.contentType,
+            size: localizedFileField.size,
+            width: localizedFileField.dimensions?.width,
+            height: localizedFileField.dimensions?.height
+        })
+    };
+}
+
+/**
+ * Iterates recursively objects with $$type and $$ref, creating nested objects
+ * as needed and returns standard ContentSourceInterface Documents
+ */
+async function createDocumentRecursively({
+    object,
+    model,
+    modelMap,
+    locale,
+    userContext,
+    contentSourceInstance
+}: {
+    object?: Record<string, any>;
+    model: Model;
+    modelMap: Record<string, Model>;
+    locale?: string;
+    userContext: unknown;
+    contentSourceInstance: CSITypes.ContentSourceInterface;
+}): Promise<{ document: CSITypes.Document; newRefDocuments: CSITypes.Document[] }> {
+    if (model.type === 'page') {
+        const tokens = extractTokensFromString(String(model.urlPath));
+        const slugField = _.last(tokens);
+        if (object && slugField && slugField in object) {
+            const slugFieldValue = object[slugField];
+            object[slugField] = sanitizeSlug(slugFieldValue);
+        }
+    }
+
+    const nestedResult = await createNestedObjectRecursively({
+        object,
+        modelFields: model.fields ?? [],
+        fieldPath: [],
+        modelMap,
+        locale,
+        userContext,
+        contentSourceInstance
+    });
+    const document = await contentSourceInstance.createDocument({
+        updateOperationFields: nestedResult.fields,
+        // TODO: pass csiModel
+        model,
+        // TODO: pass csiModelMap
+        modelMap,
+        locale,
+        userContext
+    });
+    return {
+        document: document,
+        newRefDocuments: nestedResult.newRefDocuments
+    };
+}
+
+async function createNestedObjectRecursively({
+    object,
+    modelFields,
+    fieldPath,
+    modelMap,
+    locale,
+    userContext,
+    contentSourceInstance
+}: {
+    object?: Record<string, any>;
+    modelFields: Field[];
+    fieldPath: (string | number)[];
+    modelMap: Record<string, Model>;
+    locale?: string;
+    userContext: unknown;
+    contentSourceInstance: CSITypes.ContentSourceInterface;
+}): Promise<{
+    fields: Record<string, CSITypes.UpdateOperationField>;
+    newRefDocuments: CSITypes.Document[];
+}> {
+    object = object ?? {};
+    const result: {
+        fields: Record<string, CSITypes.UpdateOperationField>;
+        newRefDocuments: CSITypes.Document[];
+    } = {
+        fields: {},
+        newRefDocuments: []
+    };
+    const objectFieldNames = Object.keys(object);
+    for (const modelField of modelFields) {
+        const fieldName = modelField.name;
+        let value;
+        if (fieldName in object) {
+            value = object[fieldName];
+            _.pull(objectFieldNames, fieldName);
+        } else if (modelField.const) {
+            value = modelField.const;
+        } else if (!_.isNil(modelField.default)) {
+            value = modelField.default;
+        }
+        if (!_.isNil(value)) {
+            const fieldResult = await createNestedField({
+                value,
+                modelField,
+                fieldPath: fieldPath.concat(fieldName),
+                modelMap,
+                locale,
+                userContext,
+                contentSourceInstance
+            });
+            result.fields[fieldName] = fieldResult.field;
+            result.newRefDocuments = result.newRefDocuments.concat(fieldResult.newRefDocuments);
+        }
+    }
+    if (objectFieldNames.length > 0) {
+        throw new Error(`no model fields found when creating a document with fields: '${objectFieldNames.join(', ')}'`);
+    }
+
+    return result;
+}
+
+async function createNestedField({
+    value,
+    modelField,
+    fieldPath,
+    modelMap,
+    locale,
+    userContext,
+    contentSourceInstance
+}: {
+    value: any;
+    modelField: FieldSpecificProps;
+    fieldPath: (string | number)[];
+    modelMap: Record<string, Model>;
+    locale?: string;
+    userContext: unknown;
+    contentSourceInstance: CSITypes.ContentSourceInterface;
+}): Promise<{ field: CSITypes.UpdateOperationField; newRefDocuments: CSITypes.Document[] }> {
+    if (modelField.type === 'object') {
+        const result = await createNestedObjectRecursively({
+            object: value,
+            modelFields: modelField.fields,
+            fieldPath,
+            modelMap,
+            locale,
+            userContext,
+            contentSourceInstance
+        });
+        return {
+            field: {
+                type: 'object',
+                fields: result.fields
+            },
+            newRefDocuments: result.newRefDocuments
+        };
+    } else if (modelField.type === 'model') {
+        let { $$type, ...rest } = value;
+        const modelNames = modelField.models;
+        // for backward compatibility check if the object has 'type' instead of '$$type' because older projects use
+        // the 'type' property in default values
+        if (!$$type && 'type' in rest) {
+            $$type = rest.type;
+            rest = _.omit(rest, 'type');
+        }
+        const modelName = $$type ?? (modelNames.length === 1 ? modelNames[0] : null);
+        if (!modelName) {
+            throw new Error(`no $$type was specified for nested model`);
+        }
+        const model = modelMap[modelName];
+        if (!model) {
+            throw new Error(`no model with name '${modelName}' was found`);
+        }
+        const result = await createNestedObjectRecursively({
+            object: rest,
+            modelFields: model.fields ?? [],
+            fieldPath,
+            modelMap,
+            locale,
+            userContext,
+            contentSourceInstance
+        });
+        return {
+            field: {
+                type: 'model',
+                modelName: modelName,
+                fields: result.fields
+            },
+            newRefDocuments: result.newRefDocuments
+        };
+    } else if (modelField.type === 'image') {
+        let refId: string | undefined;
+        if (_.isPlainObject(value)) {
+            refId = value.$$ref;
+        } else {
+            refId = value;
+        }
+        if (!refId) {
+            throw new Error(`reference field must specify a value`);
+        }
+        return {
+            field: {
+                type: 'reference',
+                refType: 'asset',
+                refId: refId
+            },
+            newRefDocuments: []
+        };
+    } else if (modelField.type === 'reference') {
+        let { $$ref: refId = null, $$type: modelName = null, ...rest } = _.isPlainObject(value) ? value : { $$ref: value };
+        if (refId) {
+            return {
+                field: {
+                    type: 'reference',
+                    refType: 'document',
+                    refId: refId
+                },
+                newRefDocuments: []
+            };
+        } else {
+            const modelNames = modelField.models;
+            if (!modelName) {
+                // for backward compatibility check if the object has 'type' instead of '$$type' because older projects use
+                // the 'type' property in default values
+                if ('type' in rest) {
+                    modelName = rest.type;
+                    rest = _.omit(rest, 'type');
+                } else if (modelNames.length === 1) {
+                    modelName = modelNames[0];
+                }
+            }
+            const model = modelMap[modelName];
+            if (!model) {
+                throw new Error(`no model with name '${modelName}' was found`);
+            }
+            const { document, newRefDocuments } = await createDocumentRecursively({
+                object: rest,
+                model: model,
+                modelMap,
+                locale,
+                userContext,
+                contentSourceInstance
+            });
+            return {
+                field: {
+                    type: 'reference',
+                    refType: 'document',
+                    refId: document.id
+                },
+                newRefDocuments: [document, ...newRefDocuments]
+            };
+        }
+    } else if (modelField.type === 'list') {
+        if (!Array.isArray(value)) {
+            throw new Error(`value for list field must be array`);
+        }
+        const itemsField = modelField.items;
+        if (!itemsField) {
+            throw new Error(`list field does not define items`);
+        }
+        const arrayResult = await mapPromise(value, async (item, index) => {
+            return createNestedField({
+                value: item,
+                modelField: itemsField,
+                fieldPath: fieldPath.concat(index),
+                modelMap,
+                locale,
+                userContext,
+                contentSourceInstance
+            });
+        });
+        return {
+            field: {
+                type: 'list',
+                items: arrayResult.map((result) => result.field)
+            },
+            newRefDocuments: arrayResult.reduce((result: CSITypes.Document[], { newRefDocuments }) => result.concat(newRefDocuments), [])
+        };
+    }
+    return {
+        field: {
+            type: modelField.type,
+            value: value
+        },
+        newRefDocuments: []
+    };
+}
+
+function getModelFieldForFieldAtPath(
+    document: ContentStoreTypes.Document,
+    model: Model,
+    fieldPath: (string | number)[],
+    modelMap: Record<string, Model>,
+    locale?: string
+): Field {
+    if (_.isEmpty(fieldPath)) {
+        throw new Error('the fieldPath can not be empty');
+    }
+
+    function getField(docField: ContentStoreTypes.DocumentField, modelField: FieldSpecificProps, fieldPath: (string | number)[]): Field {
+        const fieldName = _.head(fieldPath);
+        if (typeof fieldName === 'undefined') {
+            throw new Error('the first fieldPath item must be string');
+        }
+        const childFieldPath = _.tail(fieldPath);
+        let childDocField: ContentStoreTypes.DocumentField | undefined;
+        let childModelField: Field | undefined;
+        switch (docField.type) {
+            case 'object':
+                const localizedObjectField = getDocumentFieldForLocale(docField, locale);
+                if (!localizedObjectField) {
+                    throw new Error(`locale for field was not found`);
+                }
+                if (localizedObjectField.isUnset) {
+                    throw new Error(`field is not set`);
+                }
+                childDocField = localizedObjectField.fields[fieldName];
+                childModelField = _.find((modelField as FieldObjectProps).fields, (field) => field.name === fieldName);
+                if (!childDocField || !childModelField) {
+                    throw new Error(`field ${fieldName} doesn't exist`);
+                }
+                if (childFieldPath.length === 0) {
+                    return childModelField;
+                }
+                return getField(childDocField, childModelField, childFieldPath);
+            case 'model':
+                const localizedModelField = getDocumentFieldForLocale(docField, locale);
+                if (!localizedModelField) {
+                    throw new Error(`locale for field was not found`);
+                }
+                if (localizedModelField.isUnset) {
+                    throw new Error(`field is not set`);
+                }
+                const modelName = localizedModelField.srcModelName;
+                const childModel = modelMap[modelName];
+                if (!childModel) {
+                    throw new Error(`model ${modelName} doesn't exist`);
+                }
+                childModelField = _.find(childModel.fields, (field) => field.name === fieldName);
+                childDocField = localizedModelField.fields![fieldName];
+                if (!childDocField || !childModelField) {
+                    throw new Error(`field ${fieldName} doesn't exist`);
+                }
+                if (childFieldPath.length === 0) {
+                    return childModelField;
+                }
+                return getField(childDocField, childModelField!, childFieldPath);
+            case 'list':
+                const localizedListField = getDocumentFieldForLocale(docField, locale);
+                if (!localizedListField) {
+                    throw new Error(`locale for field was not found`);
+                }
+                const listItem = localizedListField.items && localizedListField.items[fieldName as number];
+                const listItemsModel = (modelField as FieldListProps).items;
+                if (!listItem || !listItemsModel) {
+                    throw new Error(`field ${fieldName} doesn't exist`);
+                }
+                if (childFieldPath.length === 0) {
+                    return modelField as FieldList;
+                }
+                if (!Array.isArray(listItemsModel)) {
+                    return getField(listItem, listItemsModel, childFieldPath);
+                } else {
+                    const fieldListItems = (listItemsModel as FieldListItems[]).find((listItemsModel) => listItemsModel.type === listItem.type);
+                    if (!fieldListItems) {
+                        throw new Error('cannot find matching field model');
+                    }
+                    return getField(listItem, fieldListItems, childFieldPath);
+                }
+            default:
+                if (!_.isEmpty(childFieldPath)) {
+                    throw new Error('illegal fieldPath');
+                }
+                return modelField as Field;
+        }
+    }
+
+    const fieldName = _.head(fieldPath);
+    const childFieldPath = _.tail(fieldPath);
+
+    if (typeof fieldName !== 'string') {
+        throw new Error('the first fieldPath item must be string');
+    }
+
+    const childDocField = document.fields[fieldName];
+    const childModelField = _.find(model.fields, { name: fieldName });
+
+    if (!childDocField || !childModelField) {
+        throw new Error(`field ${fieldName} doesn't exist`);
+    }
+
+    if (childFieldPath.length === 0) {
+        return childModelField;
+    }
+
+    return getField(childDocField, childModelField, childFieldPath);
+}
+
+async function convertOperationField({
+    operationField,
+    fieldPath,
+    modelField,
+    modelMap,
+    locale,
+    userContext,
+    contentSourceInstance
+}: {
+    operationField: ContentStoreTypes.UpdateOperationField;
+    fieldPath: (string | number)[];
+    modelField: Field;
+    modelMap: Record<string, Model>;
+    locale?: string;
+    userContext: unknown;
+    contentSourceInstance: CSITypes.ContentSourceInterface;
+}): Promise<CSITypes.UpdateOperationField> {
+    // for insert operations, the modelField will be of the list, so get the modelField of the list items
+    const modelFieldOrListItems: FieldSpecificProps = modelField.type === 'list' ? modelField.items! : modelField;
+    switch (operationField.type) {
+        case 'object': {
+            const result = await createNestedObjectRecursively({
+                object: operationField.object,
+                modelFields: (modelFieldOrListItems as FieldObjectProps).fields,
+                fieldPath: fieldPath,
+                modelMap,
+                locale,
+                userContext,
+                contentSourceInstance
+            });
+            return {
+                type: operationField.type,
+                fields: result.fields
+            };
+        }
+        case 'model': {
+            const model = modelMap[operationField.modelName];
+            if (!model) {
+                throw new Error(`error updating document, could not find document model: '${operationField.modelName}'`);
+            }
+            const result = await createNestedObjectRecursively({
+                object: operationField.object,
+                modelFields: model.fields!,
+                fieldPath,
+                modelMap,
+                locale,
+                userContext,
+                contentSourceInstance
+            });
+            return {
+                type: operationField.type,
+                modelName: operationField.modelName,
+                fields: result.fields
+            };
+        }
+        case 'list': {
+            if (modelField.type !== 'list') {
+                throw new Error(`'the operation field type '${operationField.type}' does not match the model field type '${modelField.type}'`);
+            }
+            const result = await mapPromise(operationField.items, async (item, index) => {
+                const result = await createNestedField({
+                    value: item,
+                    modelField: modelField.items!,
+                    fieldPath,
+                    modelMap,
+                    locale,
+                    userContext,
+                    contentSourceInstance
+                });
+                return result.field;
+            });
+            return {
+                type: operationField.type,
+                items: result
+            };
+        }
+        case 'string':
+            if (typeof operationField.value !== 'string') {
+                return {
+                    type: operationField.type,
+                    value: ''
+                };
+            }
+            return operationField as CSITypes.UpdateOperationField;
+        case 'enum':
+            if (typeof operationField.value !== 'string') {
+                if (modelFieldOrListItems.type !== 'enum') {
+                    throw new Error(`'the operation field type 'enum' does not match the model field type '${modelFieldOrListItems.type}'`);
+                }
+                const option = modelFieldOrListItems.options[0]!;
+                const optionValue = typeof option === 'object' ? option.value : option;
+                return {
+                    type: operationField.type,
+                    value: optionValue
+                };
+            }
+            return operationField as CSITypes.UpdateOperationField;
+        case 'image':
+            return operationField as CSITypes.UpdateOperationField;
+        default:
+            return operationField as CSITypes.UpdateOperationField;
+    }
+}
+
+function getDocumentFieldForLocale<Type extends ContentStoreTypes.FieldType>(
+    docField: ContentStoreTypes.DocumentFieldForType<Type>,
+    locale?: string
+): ContentStoreTypes.DocumentFieldNonLocalizedForType<Type> | null {
+    if (docField.localized) {
+        if (!locale) {
+            return null;
+        }
+        const { localized, locales, ...base } = docField;
+        const localizedField = locales[locale];
+        if (!localizedField) {
+            return null;
+        }
+        return ({
+            ...base,
+            ...localizedField
+        } as unknown) as ContentStoreTypes.DocumentFieldNonLocalizedForType<Type>;
+    } else {
+        return docField;
+    }
+}
+
+function isStackbitConfigFile(filePath: string) {
+    const pathObject = path.parse(filePath);
+    const isInDotStackbitFolder = pathObject.dir.startsWith('.stackbit');
+    const isMainStackbitConfigFile = pathObject.name === 'stackbit' && ['yaml', 'yml'].includes(pathObject.ext.substring(1));
+    return isMainStackbitConfigFile || isInDotStackbitFolder;
+}
+
+function getCSIDocumentsAndAssetsFromContentSourceDataByIds(
+    contentSourceData: ContentSourceData,
+    objects: { srcObjectId: string }[]
+): {
+    documents: CSITypes.Document[];
+    assets: CSITypes.Asset[];
+} {
+    const documents: CSITypes.Document[] = [];
+    const assets: CSITypes.Asset[] = [];
+    for (const object of objects) {
+        if (object.srcObjectId in contentSourceData.csiDocumentMap) {
+            documents.push(contentSourceData.csiDocumentMap[object.srcObjectId]!);
+        } else if (object.srcObjectId in contentSourceData.csiAssetMap) {
+            assets.push(contentSourceData.csiAssetMap[object.srcObjectId]!);
+        }
+    }
+    return {
+        documents,
+        assets
+    };
+}
+
+function internalValidateContent(
+    documents: CSITypes.Document[],
+    assets: CSITypes.Asset[],
+    contentSourceData: ContentSourceData
+): ContentStoreTypes.ValidationError[] {
+
+    const errors: ContentStoreTypes.ValidationError[] = [];
+    _.forEach(documents, (document) => {
+        _.forEach(document.fields, (documentField, fieldName) => {
+            const localizedField = getLocalizedFieldForLocale(documentField)!;
+            errors.push(...validateDocumentFields(document, localizedField, [fieldName], contentSourceData));
+        })
+    })
+    return errors;
+}
+
+function validateDocumentFields(
+    document: CSITypes.Document,
+    documentField: CSITypes.DocumentFieldNonLocalized,
+    fieldPath: (string | number)[],
+    contentSourceData: ContentSourceData
+): ContentStoreTypes.ValidationError[] {
+    const errors: ContentStoreTypes.ValidationError[] = [];
+
+    if (documentField.type === 'object') {
+        _.forEach(documentField.fields, (documentField, fieldName) => {
+            const localizedField = getLocalizedFieldForLocale(documentField)!;
+            errors.push(...validateDocumentFields(document, localizedField, fieldPath.concat(fieldName), contentSourceData));
+        });
+    } else if (documentField.type === 'model') {
+        _.forEach(documentField.fields, (documentField, fieldName) => {
+            const localizedField = getLocalizedFieldForLocale(documentField)!;
+            errors.push(...validateDocumentFields(document, localizedField, fieldPath.concat(fieldName), contentSourceData));
+        });
+    } else if (documentField.type === 'reference') {
+        const objRef = documentField.refType === 'asset'
+            ? contentSourceData.assetMap[documentField.refId]
+            : contentSourceData.documentMap[documentField.refId];
+        if (!objRef) {
+            errors.push({
+                fieldPath,
+                srcType: contentSourceData.type,
+                srcProjectId: contentSourceData.projectId,
+                srcObjectType: documentField.refType,
+                srcObjectId: document.id,
+                message: `Can't find referenced ${documentField.refType}: ${documentField.refId}`
+            });
+        }
+    } else if (documentField.type === 'list') {
+        _.forEach(documentField.items, (documentField, i) => {
+            const localizedField = getLocalizedFieldForLocale(documentField)!;
+            errors.push(...validateDocumentFields(document, documentField, fieldPath.concat(i), contentSourceData));
+        });
+    }
+
+    return errors;
+}