@stackbit/cms-core 0.2.1 → 0.3.0-develop.1

package/src/types/content-store-document-fields.ts

@@ -440,7 +440,7 @@ export type DocumentObjectFieldNonLocalized = {
     | { isUnset: true }
     | {
           isUnset?: false;
-          srcObjectLabel: string;
+          getPreview: (options: { delegate?: CSITypes.ConfigDelegate; locale?: string }) => DocumentObjectFieldPreview;
           fields: Record<string, DocumentField>;
       }
 );
@@ -453,12 +453,18 @@ export interface DocumentObjectFieldLocalized {
         string,
         {
             locale: string;
-            srcObjectLabel: string;
+            getPreview: (options: { delegate?: CSITypes.ConfigDelegate; locale?: string }) => DocumentObjectFieldPreview;
             fields: Record<string, DocumentField>;
         }
     >;
 }
 
+export interface DocumentObjectFieldPreview {
+    previewTitle?: string;
+    previewSubtitle?: string;
+    previewImage?: unknown;
+}
+
 export type DocumentObjectFieldAPI = {
     type: 'object';
     label?: string;
@@ -486,9 +492,9 @@ export type DocumentModelFieldNonLocalized = {
     | { isUnset: true }
     | {
           isUnset?: false;
-          srcObjectLabel: string;
           srcModelName: string;
           srcModelLabel: string;
+          getPreview: (options: { delegate?: CSITypes.ConfigDelegate; locale?: string }) => DocumentModelFieldPreview;
           fields: Record<string, DocumentField>;
       }
 );
@@ -501,9 +507,9 @@ export interface DocumentModelFieldLocalized {
         string,
         {
             locale: string;
-            srcObjectLabel: string;
             srcModelName: string;
             srcModelLabel: string;
+            getPreview: (options: { delegate?: CSITypes.ConfigDelegate; locale?: string }) => DocumentModelFieldPreview;
             fields: Record<string, DocumentField>;
         }
     >;
@@ -525,6 +531,12 @@ export type DocumentModelFieldAPI = {
 ) &
     ({ localized?: false } | { localized: true; locale: string });
 
+export interface DocumentModelFieldPreview {
+    previewTitle: string;
+    previewSubtitle?: string;
+    previewImage?: unknown;
+}
+
 /**
  * reference
  */

package/src/types/content-store-documents.ts

@@ -1,4 +1,4 @@
-import { DocumentStatus } from '@stackbit/types';
+import { DocumentStatus, ConfigDelegate } from '@stackbit/types';
 import { DocumentField, DocumentFieldAPI, DocumentFieldAPIForType, DocumentStringLikeFieldForType } from './content-store-document-fields';
 
 export interface Document {
@@ -9,7 +9,9 @@ export interface Document {
     srcEnvironment: string;
     srcObjectId: string;
     srcObjectUrl: string;
-    srcObjectLabel: string;
+    /** @deprecated used by older, non-csi cms interface  */
+    srcObjectLabel?: string;
+    getPreview: (options: { delegate?: ConfigDelegate; locale?: string }) => DocumentPreview;
     srcModelName: string;
     srcModelLabel: string;
     isChanged: boolean;
@@ -22,6 +24,12 @@ export interface Document {
     fields: Record<string, DocumentField>;
 }
 
+export interface DocumentPreview {
+    previewTitle: string;
+    previewSubtitle?: string;
+    previewImage?: unknown;
+}
+
 export interface Asset {
     type: 'asset';
     srcType: string;
@@ -85,8 +93,9 @@ export interface AssetFileFieldProps {
  */
 export type APIObject = APIDocumentObject | APIImageObject;
 
-export interface APIDocumentObject extends Omit<Document, 'fields' | 'type'> {
+export interface APIDocumentObject extends Omit<Document, 'getPreview' | 'fields' | 'type'> {
     type: 'object';
+    srcObjectLabel: string;
     fields: Record<string, DocumentFieldAPI>;
 }
 

package/src/types/content-store-types.ts

@@ -1,12 +1,14 @@
 import * as CSITypes from '@stackbit/types';
 import { Model } from '@stackbit/sdk';
 import { Asset, Document } from './content-store-documents';
+import { BackCompatContentSourceInterface } from '../utils/backward-compatibility';
 
 export interface ContentSourceData {
     /* Internal content source id computed by concatenating srcType and srcProjectId */
     id: string;
     /* The content source instance loaded from stackbitConfig.contentSources */
-    instance: CSITypes.ContentSourceInterface;
+    instance: BackCompatContentSourceInterface;
+    version: { interfaceVersion: string; contentSourceVersion: string };
     srcType: string;
     srcProjectId: string;
     locales?: CSITypes.Locale[];
@@ -16,6 +18,7 @@ export interface ContentSourceData {
     /* Map of extended and validated Models by model name */
     modelMap: Record<string, Model>;
     /* Array of original Models (as provided by content source)  */
+    csiSchema: CSITypes.Schema;
     csiModels: CSITypes.Model[];
     /* Map of original Models (as provided by content source) by model name */
     csiModelMap: Record<string, CSITypes.Model>;

package/src/utils/backward-compatibility.ts

@@ -0,0 +1,269 @@
+import * as CSITypes from '@stackbit/types';
+
+/**
+ * AnyContentSourceInterface is the union of the previous ContentSourceInterface
+ * versions.
+ *
+ * When changing the ContentSourceInterface in a way that it may break previous
+ * content source modules, create a new type by omitting the changed methods and
+ * redefine them with their new signatures. Then add the new type to the union.
+ */
+export type AnyContentSourceInterface = ContentSourceInterface_v0_1_0 | ContentSourceInterface_v0_2_0;
+
+export type ContentSourceInterface_v0_2_0 = CSITypes.ContentSourceInterface;
+
+export type ContentSourceInterface_v0_1_0 = Omit<
+    CSITypes.ContentSourceInterface,
+    | 'getVersion'
+    | 'init'
+    | 'destroy'
+    | 'getSchema'
+    | 'onFilesChange'
+    | 'startWatchingContentUpdates'
+    | 'stopWatchingContentUpdates'
+    | 'hasAccess'
+    | 'getDocuments'
+    | 'createDocument'
+    | 'updateDocument'
+> & {
+    init(options: {
+        logger: CSITypes.Logger;
+        userLogger: CSITypes.Logger;
+        userCommandSpawner?: CSITypes.UserCommandSpawner;
+        localDev: boolean;
+        webhookUrl?: string;
+        devAppRestartNeeded?: () => void;
+    }): Promise<void>;
+    getModels(): Promise<CSITypes.Model[]>;
+    getLocales(): Promise<CSITypes.Locale[]>;
+    onFilesChange?(options: { updatedFiles: string[] }): Promise<{ schemaChanged?: boolean; contentChangeEvent?: CSITypes.ContentChangeEvent }>;
+    startWatchingContentUpdates(options: {
+        getModelMap: () => CSITypes.ModelMap;
+        getDocument: ({ documentId }: { documentId: string }) => CSITypes.Document | undefined;
+        getAsset: ({ assetId }: { assetId: string }) => CSITypes.Asset | undefined;
+        onContentChange: (contentChangeEvent: CSITypes.ContentChangeEvent) => Promise<void>;
+        onSchemaChange: () => void;
+    }): void;
+    stopWatchingContentUpdates(): void;
+    hasAccess(options: { userContext?: unknown }): boolean | Promise<{ hasConnection: boolean; hasPermissions: boolean }>;
+    getDocuments(options: { modelMap: CSITypes.ModelMap }): Promise<CSITypes.Document[]>;
+    createDocument(options: {
+        updateOperationFields: Record<string, CSITypes.UpdateOperationField>;
+        model: CSITypes.Model;
+        modelMap: CSITypes.ModelMap;
+        locale?: string;
+        defaultLocaleDocumentId?: string;
+        userContext?: unknown;
+    }): Promise<CSITypes.Document>;
+    updateDocument(options: {
+        document: CSITypes.Document;
+        operations: CSITypes.UpdateOperation[];
+        modelMap: CSITypes.ModelMap;
+        userContext?: unknown;
+    }): Promise<CSITypes.Document>;
+};
+
+/**
+ * BackCompatContentSourceInterface redefines the ContentSourceInterface such
+ * that when its methods are called, it can correctly invoke the previous
+ * content source module versions.
+ *
+ * The parameters of its methods must be intersections of the parameters in the
+ * previous versions. For example, if a method in an older version received
+ * 'options.x', and a method in the newer version receives 'options.y', the
+ * matching method should receive both options '{ x } & { y }' to ensure that
+ * both the older and the newer content sources will receive what they need.
+ *
+ * The method return values must match the most recent content source versions.
+ */
+export type BackCompatContentSourceInterface = Omit<
+    CSITypes.ContentSourceInterface,
+    'getVersion' | 'onFilesChange' | 'startWatchingContentUpdates' | 'hasAccess' | 'getDocuments' | 'createDocument' | 'updateDocument'
+> & {
+    getVersion(): GetVersionReturn;
+    onFilesChange(options: BCOnFilesChangeOptions): OnFilesChangeReturn;
+    startWatchingContentUpdates?(options: BCStartWatchingOptions): StartWatchingReturn;
+    hasAccess(options: BCHasAccessOptions): HasAccessReturn;
+    getDocuments(options: BCGetDocumentsOptions): GetDocumentsReturn;
+    createDocument(options: BCCreateDocumentOptions): CreateDocumentReturn;
+    updateDocument(options: BCUpdateDocumentOptions): UpdateDocumentReturn;
+};
+
+export function backwardCompatibleContentSource(contentSource: AnyContentSourceInterface): BackCompatContentSourceInterface {
+    return new Proxy(contentSource, {
+        get(target: AnyContentSourceInterface, prop: keyof CSITypes.ContentSourceInterface): any {
+            switch (prop) {
+                case 'getVersion':
+                    return getVersion.bind(undefined, target);
+                case 'destroy':
+                    return destroy.bind(undefined, target);
+                case 'onFilesChange':
+                    return onFilesChange.bind(undefined, target);
+                case 'startWatchingContentUpdates':
+                    return startWatchingContentUpdates.bind(undefined, target);
+                case 'getSchema':
+                    return getSchema.bind(undefined, target);
+                case 'hasAccess':
+                    return hasAccess.bind(undefined, target);
+                case 'getDocuments':
+                    return getDocuments.bind(undefined, target);
+                case 'createDocument':
+                    return createDocument.bind(undefined, target);
+                case 'updateDocument':
+                    return updateDocument.bind(undefined, target);
+                default:
+                    return target[prop];
+            }
+        }
+    }) as BackCompatContentSourceInterface;
+}
+
+type ReturnTypeOfMethod<Method extends keyof CSITypes.ContentSourceInterface> = ReturnType<NonNullable<CSITypes.ContentSourceInterface[Method]>>;
+
+type GetVersionReturn = Promise<{ interfaceVersion: string; contentSourceVersion: string }>;
+export async function getVersion(contentSource: AnyContentSourceInterface): GetVersionReturn {
+    if ('getVersion' in contentSource) {
+        return contentSource.getVersion();
+    }
+    return {
+        interfaceVersion: '0.1.0',
+        contentSourceVersion: ''
+    };
+}
+
+type DestroyReturn = ReturnTypeOfMethod<'destroy'>;
+export async function destroy(contentSource: AnyContentSourceInterface): DestroyReturn {
+    if ('destroy' in contentSource) {
+        return contentSource.destroy();
+    }
+}
+
+type BCOnFilesChangeOptions = { updatedFiles: string[] };
+type OnFilesChangeReturn = ReturnTypeOfMethod<'onFilesChange'>;
+/**
+ * Converts the old onFilesChange API to the new one
+ * OLD: onFilesChange?(options: { updatedFiles: string[]; }):
+ *        Promise<{ schemaChanged?: boolean; contentChangeEvent?: ContentChangeEvent<DocumentContext, AssetContext> }>
+ * NEW: onFilesChange?(options: { updatedFiles: string[]; }):
+ *        Promise<{ invalidateSchema?: boolean; contentChanges?: ContentChanges<DocumentContext, AssetContext> }>
+ */
+export async function onFilesChange(contentSource: AnyContentSourceInterface, options: BCOnFilesChangeOptions): OnFilesChangeReturn {
+    const value = await contentSource.onFilesChange?.(options);
+    if (!value) {
+        return {};
+    }
+    // if there are properties from the new API return the value as is
+    if ('invalidateSchema' in value || 'contentChanges' in value) {
+        return value;
+    }
+    // if there are properties from the old API return convert to the new API value
+    const result: Awaited<OnFilesChangeReturn> = {};
+    if ('schemaChanged' in value) {
+        result.invalidateSchema = value.schemaChanged;
+    }
+    if ('contentChangeEvent' in value) {
+        result.contentChanges = value.contentChangeEvent;
+    }
+    return result;
+}
+
+type BCStartWatchingOptions = {
+    getModelMap: () => CSITypes.ModelMap;
+    getDocument: ({ documentId }: { documentId: string }) => CSITypes.Document | undefined;
+    getAsset: ({ assetId }: { assetId: string }) => CSITypes.Asset | undefined;
+    onContentChange: (contentChangeEvent: CSITypes.ContentChangeEvent) => Promise<void>;
+    onSchemaChange: () => void;
+};
+type StartWatchingReturn = ReturnTypeOfMethod<'startWatchingContentUpdates'>;
+/**
+ * Converts between the old startWatchingContentUpdates API and the new one.
+ * OLD: startWatchingContentUpdates(options: startWatchingContentUpdatesOptionsOld): void;
+ * NEW: startWatchingContentUpdates?(): void;
+ */
+export function startWatchingContentUpdates(contentSource: AnyContentSourceInterface, options: BCStartWatchingOptions): StartWatchingReturn {
+    contentSource.startWatchingContentUpdates?.(options);
+}
+
+/**
+ * Converts the old getModels() and getLocales() API methods to the new getSchema() API method.
+ * OLD:
+ *   getModels(): Promise<Model[]>;
+ *   getLocales(): Promise<Locale[]>
+ * NEW:
+ *   getSchema(): Promise<Schema<SchemaContext>>
+ */
+export async function getSchema(contentSource: AnyContentSourceInterface): Promise<CSITypes.Schema> {
+    if ('getSchema' in contentSource) {
+        return contentSource.getSchema();
+    }
+    const models = await contentSource.getModels();
+    const locales = await contentSource.getLocales();
+    return { models, locales, context: null };
+}
+
+type HasAccessReturn = ReturnTypeOfMethod<'hasAccess'>;
+type BCHasAccessOptions = { userContext?: unknown };
+/**
+ * Converts the old hasAccess API to the new one
+ * OLD: hasAccess(options: { userContext?: UserContext }): Promise<boolean>
+ * NEW: hasAccess(options: { userContext?: UserContext }): Promise<{ hasConnection: boolean; hasPermissions: boolean }>
+ */
+export async function hasAccess(contentSource: AnyContentSourceInterface, options: BCHasAccessOptions): HasAccessReturn {
+    const result = await contentSource.hasAccess(options);
+    if (typeof result === 'boolean') {
+        return {
+            hasConnection: result,
+            hasPermissions: result
+        };
+    }
+    return result;
+}
+
+type BCGetDocumentsOptions = { modelMap: CSITypes.ModelMap };
+type GetDocumentsReturn = ReturnTypeOfMethod<'getDocuments'>;
+/**
+ * Converts the old getDocuments API to the new one
+ * OLD: getDocuments(options: { modelMap: ModelMap }): Promise<Document[]>
+ * NEW: getDocuments(): Promise<Document[]>
+ */
+export async function getDocuments(contentSource: AnyContentSourceInterface, options: BCGetDocumentsOptions): GetDocumentsReturn {
+    return contentSource.getDocuments(options);
+}
+
+type BCCreateDocumentOptions = {
+    updateOperationFields: Record<string, CSITypes.UpdateOperationField>;
+    model: CSITypes.Model;
+    modelMap: CSITypes.ModelMap;
+    locale?: string;
+    defaultLocaleDocumentId?: string;
+    userContext?: unknown;
+};
+type CreateDocumentReturn = ReturnTypeOfMethod<'createDocument'>;
+/**
+ * Converts the old createDocument API to the new one
+ * OLD: createDocument(options: Options & { modelMap: ModelMap }): Promise<Document<DocumentContext>>
+ * NEW: createDocument(options: Options): Promise<{ documentId: string }>
+ */
+export async function createDocument(contentSource: AnyContentSourceInterface, options: BCCreateDocumentOptions): CreateDocumentReturn {
+    const result = await contentSource.createDocument(options);
+    if ('id' in result) {
+        return { documentId: result.id };
+    }
+    return result;
+}
+
+type UpdateDocumentReturn = ReturnTypeOfMethod<'updateDocument'>;
+type BCUpdateDocumentOptions = {
+    document: CSITypes.Document;
+    operations: CSITypes.UpdateOperation[];
+    modelMap: CSITypes.ModelMap;
+    userContext?: unknown;
+};
+/**
+ * Converts the old updateDocument API to the new one
+ * OLD: updateDocument(options: Options & { modelMap: ModelMap }): Promise<CSITypes.Document>;
+ * NEW: updateDocument(options: Options): Promise<void>
+ */
+export async function updateDocument(contentSource: AnyContentSourceInterface, options: BCUpdateDocumentOptions): UpdateDocumentReturn {
+    await contentSource.updateDocument(options);
+}

package/src/utils/config-delegate.ts

@@ -0,0 +1,277 @@
+import _ from 'lodash';
+import * as CSITypes from '@stackbit/types';
+import { getLocalizedFieldForLocale } from '@stackbit/types';
+import * as ContentStoreTypes from '../types';
+import { getContentSourceId } from '../content-store-utils';
+import { mapStoreDocumentToCSIDocumentWithSource } from './store-to-csi-docs-converter';
+
+export function getCreateConfigDelegateThunk({
+    getContentSourceDataById,
+    logger
+}: {
+    getContentSourceDataById: () => Record<string, ContentStoreTypes.ContentSourceData>;
+    logger: CSITypes.Logger;
+}): () => CSITypes.ConfigDelegate {
+    return () =>
+        createConfigDelegate({
+            contentSourceDataById: getContentSourceDataById(),
+            logger: logger
+        });
+}
+
+export function createConfigDelegate({
+    contentSourceDataById,
+    logger
+}: {
+    contentSourceDataById: Record<string, ContentStoreTypes.ContentSourceData>;
+    logger: CSITypes.Logger;
+}): CSITypes.ConfigDelegate {
+    return {
+        getDocumentById: ({ id, srcType, srcProjectId }) => {
+            const document = findDocumentByIdAndSourceTypeOrId({
+                contentSourceDataById,
+                documentId: id,
+                srcType,
+                srcProjectId,
+                logger
+            });
+            if (document) {
+                return mapStoreDocumentToCSIDocumentWithSource(document);
+            }
+            return undefined;
+        },
+        getModelByName: ({ modelName, srcType, srcProjectId }) => {
+            return findModelByNameAndSourceTypeOrId({
+                contentSourceDataById,
+                modelName,
+                srcType,
+                srcProjectId,
+                logger
+            });
+        },
+        getDefaultLocaleBySource: ({ srcType, srcProjectId }) => {
+            // if srcType and srcProjectId are provided, use them to get the specific contentSourceData without trying to infer the right model
+            if (srcType && srcProjectId) {
+                const contentSourceId = getContentSourceId(srcType, srcProjectId);
+                return contentSourceDataById[contentSourceId]?.defaultLocaleCode;
+            }
+            const contentSourcesData = findContentSourcesDataForTypeOrId({
+                contentSourceDataById,
+                srcType,
+                srcProjectId
+            });
+            if (contentSourcesData.length === 1) {
+                return contentSourcesData[0]!.defaultLocaleCode;
+            } else if (contentSourcesData.length > 1) {
+                logger.warn(
+                    `The getDefaultLocaleBySource() found more than one content sources for '${srcType}'. ` +
+                        `Please specify 'srcType' and 'srcProjectId' to narrow down the search.`
+                );
+            }
+            return undefined;
+        },
+        getDocumentFieldForFieldPath: ({ document, fromField, fieldPath, locale }): CSITypes.DocumentFieldNonLocalized | undefined => {
+            const fieldPathArr = _.toPath(fieldPath);
+            const contentSourceId = getContentSourceId(document.srcType, document.srcProjectId);
+            const contentSource = contentSourceDataById[contentSourceId];
+            if (!contentSource) {
+                return undefined;
+            }
+
+            function getNestedFieldFromFieldsForPath(
+                fields: Record<string, CSITypes.DocumentField>,
+                fieldPathArr: string[],
+                currentContentSource: ContentStoreTypes.ContentSourceData
+            ): CSITypes.DocumentFieldNonLocalized | undefined {
+                const fieldName = fieldPathArr[0];
+                fieldPathArr = fieldPathArr.slice(1);
+                if (!fieldName) {
+                    return undefined;
+                }
+                const field = fields[fieldName];
+                if (!field) {
+                    return undefined;
+                }
+                const resolvedLocale = locale ?? currentContentSource.defaultLocaleCode;
+                const nonLocalizedField = getLocalizedFieldForLocale(field, resolvedLocale);
+                if (!nonLocalizedField) {
+                    return undefined;
+                }
+                if (fieldPathArr.length === 0) {
+                    return nonLocalizedField;
+                }
+                return getNestedFieldFromLocalizedFieldForPath(nonLocalizedField, fieldPathArr, currentContentSource);
+            }
+
+            function getNestedFieldFromLocalizedFieldForPath(
+                nonLocalizedField: CSITypes.DocumentFieldNonLocalized,
+                fieldPathArr: string[],
+                currentContentSource: ContentStoreTypes.ContentSourceData
+            ): CSITypes.DocumentFieldNonLocalized | undefined {
+                if (nonLocalizedField.type === 'object' || nonLocalizedField.type === 'model') {
+                    return getNestedFieldFromFieldsForPath(nonLocalizedField.fields, fieldPathArr, currentContentSource);
+                } else if (nonLocalizedField.type === 'reference') {
+                    const refDocument = currentContentSource.documentMap[nonLocalizedField.refId];
+                    if (!refDocument) {
+                        return undefined;
+                    }
+                    const fields = mapStoreDocumentToCSIDocumentWithSource(refDocument).fields;
+                    return getNestedFieldFromFieldsForPath(fields, fieldPathArr, currentContentSource);
+                } else if (nonLocalizedField.type === 'cross-reference') {
+                    const contentSourceId = getContentSourceId(nonLocalizedField.refSrcType, nonLocalizedField.refProjectId);
+                    const contentSource = contentSourceDataById[contentSourceId];
+                    if (!contentSource) {
+                        return undefined;
+                    }
+                    const refDocument = contentSource.documentMap[nonLocalizedField.refId];
+                    if (!refDocument) {
+                        return undefined;
+                    }
+                    const fields = mapStoreDocumentToCSIDocumentWithSource(refDocument).fields;
+                    return getNestedFieldFromFieldsForPath(fields, fieldPathArr, contentSource);
+                } else if (nonLocalizedField.type === 'list') {
+                    const index = _.toNumber(fieldPathArr[0]);
+                    fieldPathArr = fieldPathArr.slice(1);
+                    if (_.isNaN(index)) {
+                        return undefined;
+                    }
+                    const localizedItem = nonLocalizedField.items[index];
+                    if (!localizedItem) {
+                        return undefined;
+                    }
+                    if (fieldPathArr.length === 0) {
+                        return localizedItem;
+                    }
+                    return getNestedFieldFromLocalizedFieldForPath(localizedItem, fieldPathArr, currentContentSource);
+                }
+                return undefined;
+            }
+
+            if (fromField) {
+                const resolvedLocale = locale ?? contentSource.defaultLocaleCode;
+                const nonLocalizedField = getLocalizedFieldForLocale(fromField, resolvedLocale);
+                if (!nonLocalizedField) {
+                    return undefined;
+                }
+                return getNestedFieldFromLocalizedFieldForPath(nonLocalizedField, fieldPathArr, contentSource);
+            } else {
+                return getNestedFieldFromFieldsForPath(document.fields, fieldPathArr, contentSource);
+            }
+        }
+    };
+}
+
+function findDocumentByIdAndSourceTypeOrId({
+    contentSourceDataById,
+    documentId,
+    srcType,
+    srcProjectId,
+    logger
+}: {
+    contentSourceDataById: Record<string, ContentStoreTypes.ContentSourceData>;
+    documentId: string;
+    srcType?: string;
+    srcProjectId?: string;
+    logger: CSITypes.Logger;
+}): ContentStoreTypes.Document | undefined {
+    // if srcType and srcProjectId are provided, use them to get the specific contentSourceData without trying to infer the right document
+    if (srcType && srcProjectId) {
+        const contentSourceId = getContentSourceId(srcType, srcProjectId);
+        return contentSourceDataById[contentSourceId]?.documentMap[documentId];
+    }
+    const contentSourcesData = findContentSourcesDataForTypeOrId({
+        contentSourceDataById,
+        srcType,
+        srcProjectId
+    });
+    const matchingDocuments = contentSourcesData.reduce((matchingDocuments: ContentStoreTypes.Document[], contentSourceData) => {
+        const document = contentSourceData.documentMap[documentId];
+        if (document) {
+            matchingDocuments.push(document);
+        }
+        return matchingDocuments;
+    }, []);
+    if (matchingDocuments.length === 1) {
+        return matchingDocuments[0];
+    } else if (matchingDocuments.length > 1) {
+        const matchedContentSources = matchingDocuments.map((document) => `srcType: ${document.srcType}, srcProjectId: ${document.srcProjectId}`).join('; ');
+        logger.warn(
+            `The getDocumentById() found more than one documents with ID '${documentId}' ` +
+                `in the following content sources ${matchedContentSources}. ` +
+                `Please specify 'srcType' and/or 'srcProjectId' to narrow down the search.`
+        );
+    }
+    return;
+}
+
+function findModelByNameAndSourceTypeOrId({
+    contentSourceDataById,
+    modelName,
+    srcType,
+    srcProjectId,
+    logger
+}: {
+    contentSourceDataById: Record<string, ContentStoreTypes.ContentSourceData>;
+    modelName: string;
+    srcType?: string;
+    srcProjectId?: string;
+    logger: CSITypes.Logger;
+}): CSITypes.ModelWithSource | undefined {
+    // if srcType and srcProjectId are provided, use them to get the specific contentSourceData without trying to infer the right model
+    if (srcType && srcProjectId) {
+        const contentSourceId = getContentSourceId(srcType, srcProjectId);
+        const contentSourceData = contentSourceDataById[contentSourceId];
+        const model = contentSourceData?.modelMap[modelName];
+        if (model) {
+            return {
+                ...model,
+                srcType: contentSourceData.srcType,
+                srcProjectId: contentSourceData.srcProjectId
+            };
+        }
+        return undefined;
+    }
+    const contentSourcesData = findContentSourcesDataForTypeOrId({
+        contentSourceDataById,
+        srcType,
+        srcProjectId
+    });
+    const matchingModels = contentSourcesData.reduce((matchingModels: CSITypes.ModelWithSource[], contentSourceData) => {
+        const model = contentSourceData.modelMap[modelName];
+        if (model) {
+            matchingModels.push({
+                ...model,
+                srcType: contentSourceData.srcType,
+                srcProjectId: contentSourceData.srcProjectId
+            });
+        }
+        return matchingModels;
+    }, []);
+    if (matchingModels.length === 1) {
+        return matchingModels[0]!;
+    } else if (matchingModels.length > 1) {
+        const matchedContentSources = matchingModels.map((model) => `srcType: ${model.srcType}, srcProjectId: ${model.srcProjectId}`).join('; ');
+        logger.warn(
+            `The getModelByName() found more than one model with name '${modelName}' ` +
+                `in the following content sources ${matchedContentSources}. ` +
+                `Please specify 'srcType' and/or 'srcProjectId' to narrow down the search.`
+        );
+    }
+    return;
+}
+
+function findContentSourcesDataForTypeOrId({
+    contentSourceDataById,
+    srcType,
+    srcProjectId
+}: {
+    contentSourceDataById: Record<string, ContentStoreTypes.ContentSourceData>;
+    srcType?: string;
+    srcProjectId?: string;
+}): ContentStoreTypes.ContentSourceData[] {
+    return _.filter(contentSourceDataById, (contentSourceData) => {
+        const srcTypeMatch = !srcType || contentSourceData.srcType === srcType;
+        const srcProjectIdMatch = !srcProjectId || contentSourceData.srcProjectId === srcProjectId;
+        return srcTypeMatch && srcProjectIdMatch;
+    });
+}