@stackbit/cms-core 0.7.6-develop.2 → 0.8.0-develop.1

package/src/utils/custom-actions.ts

@@ -0,0 +1,730 @@
+import _ from 'lodash';
+import { Config, mapModelFieldsRecursively } from '@stackbit/sdk';
+import * as StackbitTypes from '@stackbit/types';
+import { mapPromise, omitByNil } from '@stackbit/utils';
+import * as ContentStoreTypes from '../types';
+import {
+    CustomActionStateChange,
+    APICustomAction,
+    APICustomActionDocumentSpecifier,
+    APICustomActionDocument,
+    APICustomActionObject,
+    APICustomActionField,
+    APIGetCustomActionRequest,
+    APIRunCustomActionRequest,
+    APIRunCustomActionRequestBulk,
+    ContentStoreCustomActionMap,
+    ContentStoreCustomActionGlobal,
+    ContentStoreCustomActionBulk,
+    ContentStoreCustomActionDocument,
+    ContentStoreCustomActionObjectModel,
+    ContentStoreCustomActionField,
+    APICustomActionGlobal,
+    APICustomActionBulk,
+    ContentStoreCustomAction,
+    ContentStoreCustomActionObjectField
+} from '../types';
+import { createConfigDelegate } from './config-delegate';
+import { getContentSourceActionsForSourceThunk } from './document-hooks';
+import { mapStoreDocumentToCSIDocumentWithSource, mapStoreFieldToCSIField } from './store-to-csi-docs-converter';
+import {
+    getContentSourceDataByTypeAndProjectIdOrThrow,
+    getModelAndDocumentFieldForLocalizedFieldPath,
+    getUserContextForSrcTypeThunk
+} from '../content-store-utils';
+
+/**
+ * Removes "run" and "state" functions from actions of models, nested objects and fields.
+ * Sets "needsResolving" flag to let client know if the action needs additional resolving.
+ * @param {StackbitTypes.ModelMap} modelMap
+ */
+export function stripModelActions({ modelMap }: { modelMap: StackbitTypes.ModelMap }): StackbitTypes.ModelMap {
+    return _.mapValues(modelMap, (model) => {
+        if ('actions' in model) {
+            const { actions, ...restModel } = model;
+            model = restModel;
+        }
+
+        model = mapModelFieldsRecursively(model, (field) => {
+            if ('actions' in field && Array.isArray(field.actions)) {
+                const { actions, ...restField } = field;
+                field = restField;
+            }
+            return field;
+        });
+
+        return model;
+    });
+}
+
+export async function getGlobalAndBulkAPIActions({
+    stackbitConfig,
+    customActionMap,
+    contentSourceDataById,
+    userLogger,
+    pageUrl,
+    user,
+    locale,
+    currentPageDocument
+}: {
+    stackbitConfig: Config | null;
+    customActionMap: ContentStoreCustomActionMap;
+    contentSourceDataById: Record<string, ContentStoreTypes.ContentSourceData>;
+    userLogger: StackbitTypes.Logger;
+    pageUrl?: string;
+    user?: ContentStoreTypes.User;
+    locale?: string;
+    currentPageDocument?: APICustomActionDocumentSpecifier;
+}): Promise<(APICustomActionGlobal | APICustomActionBulk)[]> {
+    if (!stackbitConfig || !Array.isArray(stackbitConfig.actions)) {
+        return [];
+    }
+
+    const configDelegate = createConfigDelegate({
+        contentSourceDataById: contentSourceDataById,
+        logger: userLogger
+    });
+
+    return mapPromise(stackbitConfig.actions, async (action) => {
+        const actionId = `config.actions.${action.name}`;
+        const prevStoreAction = customActionMap[actionId] as ContentStoreCustomActionGlobal | ContentStoreCustomActionBulk | undefined;
+        const storeAction: ContentStoreCustomActionGlobal | ContentStoreCustomActionBulk = {
+            // if configuration is updated, the new action properties will override the stored action properties
+            ...action,
+            actionId,
+            label: action.label ?? _.startCase(action.name),
+            runningHandler: prevStoreAction?.runningHandler,
+            lastResultState: prevStoreAction?.lastResultState
+        };
+        customActionMap[actionId] = storeAction;
+
+        let state: StackbitTypes.CustomActionState | 'unknown';
+
+        if (storeAction.runningHandler) {
+            state = 'running';
+        } else if (storeAction.state) {
+            const pageDocument = getCSIDocumentWithSourceFromDocumentSpec(currentPageDocument, configDelegate);
+            state = await storeAction.state({
+                actionId: actionId,
+                currentLocale: locale,
+                currentUser: user ? { name: user.name, email: user.email } : undefined,
+                currentPageUrl: pageUrl,
+                currentPageDocument: pageDocument,
+                ...configDelegate
+            });
+        } else {
+            state = storeAction.lastResultState ?? 'enabled';
+        }
+
+        return omitByNil({
+            actionId: actionId,
+            type: storeAction.type,
+            name: storeAction.name,
+            label: storeAction.label,
+            icon: storeAction.icon,
+            state: state,
+            inputFields: storeAction.inputFields
+        });
+    });
+}
+
+export function convertDocumentActionToAPICustomDocumentAction({
+    action,
+    customActionMap,
+    csiDocument
+}: {
+    action: StackbitTypes.CustomActionDocument;
+    customActionMap: ContentStoreCustomActionMap;
+    csiDocument: StackbitTypes.DocumentWithSource;
+}): APICustomActionDocument {
+    const actionId = `${csiDocument.srcType}:${csiDocument.srcProjectId}:${csiDocument.id}:${action.name}`;
+
+    const prevStoreAction = customActionMap[actionId] as ContentStoreCustomActionDocument | undefined;
+    const storeAction: ContentStoreCustomActionDocument = {
+        // if configuration is updated, the new action properties will override the stored action properties
+        ...action,
+        type: 'document',
+        actionId,
+        label: action.label ?? _.startCase(action.name),
+        runningHandler: prevStoreAction?.runningHandler,
+        lastResultState: prevStoreAction?.lastResultState,
+        documentSpec: {
+            srcType: csiDocument.srcType,
+            srcProjectId: csiDocument.srcProjectId,
+            srcDocumentId: csiDocument.id
+        }
+    };
+    customActionMap[actionId] = storeAction;
+
+    let state: StackbitTypes.CustomActionState | 'unknown';
+    let needsResolving = false;
+    if (storeAction?.runningHandler) {
+        state = 'running';
+    } else if (action.state) {
+        state = 'unknown';
+        needsResolving = true;
+    } else {
+        state = storeAction?.lastResultState ?? 'enabled';
+    }
+
+    return omitByNil({
+        actionId: actionId,
+        type: 'document',
+        name: storeAction.name,
+        label: storeAction.label,
+        icon: storeAction.icon,
+        state: state,
+        inputFields: storeAction.inputFields,
+        needsResolving: needsResolving
+    });
+}
+
+export function convertObjectModelActionToAPICustomObjectAction({
+    action,
+    customActionMap,
+    csiParentDocument,
+    fieldPath
+}: {
+    action: StackbitTypes.CustomActionObjectModel;
+    customActionMap: ContentStoreCustomActionMap;
+    csiParentDocument: StackbitTypes.DocumentWithSource;
+    fieldPath: (string | number)[];
+}): APICustomActionObject {
+    const actionId = `${csiParentDocument.srcType}:${csiParentDocument.srcProjectId}:${csiParentDocument.id}:${fieldPath.join('.')}:${action.name}`;
+
+    const prevStoreAction = customActionMap[actionId] as ContentStoreCustomActionObjectModel | undefined;
+    const storeAction: ContentStoreCustomActionObjectModel = {
+        // if configuration is updated, the new action properties will override the stored action properties
+        ...action,
+        type: 'objectModel',
+        actionId,
+        label: action.label ?? _.startCase(action.name),
+        runningHandler: prevStoreAction?.runningHandler,
+        lastResultState: prevStoreAction?.lastResultState,
+        documentSpec: {
+            srcType: csiParentDocument.srcType,
+            srcProjectId: csiParentDocument.srcProjectId,
+            srcDocumentId: csiParentDocument.id
+        },
+        fieldPath
+    };
+    customActionMap[actionId] = storeAction;
+
+    let state: StackbitTypes.CustomActionState | 'unknown';
+    let needsResolving = false;
+    if (storeAction?.runningHandler) {
+        state = 'running';
+    } else if (action.state) {
+        state = 'unknown';
+        needsResolving = true;
+    } else {
+        state = storeAction?.lastResultState ?? 'enabled';
+    }
+
+    return omitByNil({
+        actionId: actionId,
+        type: 'object',
+        name: storeAction.name,
+        label: storeAction.label,
+        icon: storeAction.icon,
+        state: state,
+        inputFields: storeAction.inputFields,
+        needsResolving: needsResolving
+    });
+}
+
+export function convertFieldActionToAPICustomAction<T extends StackbitTypes.CustomActionField | StackbitTypes.CustomActionObjectField>({
+    action,
+    customActionMap,
+    csiParentDocument,
+    fieldPath
+}: {
+    action: T;
+    customActionMap: ContentStoreCustomActionMap;
+    csiParentDocument: StackbitTypes.DocumentWithSource;
+    fieldPath: (string | number)[];
+}): T extends StackbitTypes.CustomActionField ? APICustomActionField : APICustomActionObject {
+    const actionId = `${csiParentDocument.srcType}:${csiParentDocument.srcProjectId}:${csiParentDocument.id}:${fieldPath.join('.')}:${action.name}`;
+
+    const prevStoreAction = customActionMap[actionId] as ContentStoreCustomActionField | ContentStoreCustomActionObjectField | undefined;
+    const storeAction = {
+        // if configuration is updated, the new action properties will override the stored action properties
+        ...action,
+        type: action.type === 'object' ? 'objectField' : 'field',
+        actionId,
+        label: action.label ?? _.startCase(action.name),
+        runningHandler: prevStoreAction?.runningHandler,
+        lastResultState: prevStoreAction?.lastResultState,
+        documentSpec: {
+            srcType: csiParentDocument.srcType,
+            srcProjectId: csiParentDocument.srcProjectId,
+            srcDocumentId: csiParentDocument.id
+        },
+        fieldPath
+    } as ContentStoreCustomActionField | ContentStoreCustomActionObjectField;
+    customActionMap[actionId] = storeAction;
+
+    let state: StackbitTypes.CustomActionState | 'unknown';
+    let needsResolving = false;
+    if (storeAction?.runningHandler) {
+        state = 'running';
+    } else if (action.state) {
+        state = 'unknown';
+        needsResolving = true;
+    } else {
+        state = storeAction?.lastResultState ?? 'enabled';
+    }
+
+    return omitByNil({
+        actionId: actionId,
+        type: action.type ?? 'field',
+        name: storeAction.name,
+        label: storeAction.label,
+        icon: storeAction.icon,
+        state: state,
+        inputFields: storeAction.inputFields,
+        needsResolving: needsResolving
+    }) as T extends StackbitTypes.CustomActionField ? APICustomActionField : APICustomActionObject;
+}
+
+export async function resolveCustomActionsById({
+    getActionRequest,
+    customActionMap,
+    contentSourceDataById,
+    userLogger
+}: {
+    getActionRequest: APIGetCustomActionRequest;
+    customActionMap: ContentStoreCustomActionMap;
+    contentSourceDataById: Record<string, ContentStoreTypes.ContentSourceData>;
+    userLogger: StackbitTypes.Logger;
+}): Promise<APICustomAction[]> {
+    const result: APICustomAction[] = [];
+    const { customActionIds, locale, user, pageUrl, currentPageDocument } = getActionRequest;
+
+    const configDelegate = createConfigDelegate({
+        contentSourceDataById,
+        logger: userLogger
+    });
+
+    for (const actionId of customActionIds) {
+        const storeAction = customActionMap[actionId];
+        if (!storeAction) {
+            userLogger.debug(`getCustomActionsById: custom action not found, id: '${actionId}'`);
+            continue;
+        }
+
+        try {
+            let state: StackbitTypes.CustomActionState;
+            if (storeAction.runningHandler) {
+                state = 'running';
+            } else if (storeAction.state) {
+                const pageDocument = getCSIDocumentWithSourceFromDocumentSpec(currentPageDocument, configDelegate);
+                const commonStateOptions: StackbitTypes.CustomActionStateCommonOptions = {
+                    actionId: actionId,
+                    currentLocale: locale,
+                    currentUser: user
+                        ? {
+                              name: user.name,
+                              email: user.email
+                          }
+                        : undefined,
+                    currentPageUrl: pageUrl,
+                    currentPageDocument: pageDocument,
+                    ...configDelegate
+                };
+                if (storeAction.type === 'global' || storeAction.type === 'bulk') {
+                    state = await storeAction.state(commonStateOptions);
+                } else if (storeAction.type === 'document') {
+                    const { document, model } = getCSIDocumentAndModelWithSourceFromDocumentSpec({
+                        documentSpec: storeAction.documentSpec,
+                        contentSourceDataById
+                    });
+                    state = await storeAction.state({
+                        ...commonStateOptions,
+                        document: document,
+                        model: model
+                    });
+                } else if (storeAction.type === 'objectModel') {
+                    const stateObjectParams = getHandlerParamsForObjectModelAction({
+                        storeAction,
+                        contentSourceDataById
+                    });
+                    state = await storeAction.state({
+                        ...commonStateOptions,
+                        ...stateObjectParams
+                    });
+                } else if (storeAction.type === 'objectField') {
+                    const stateObjectParams = getHandlerParamsForObjectFieldAction({
+                        storeAction,
+                        contentSourceDataById
+                    });
+                    state = await storeAction.state({
+                        ...commonStateOptions,
+                        ...stateObjectParams
+                    });
+                } else if (storeAction.type === 'field') {
+                    const stateFieldParams = getHandlerParamsForFieldAction({
+                        storeAction,
+                        contentSourceDataById
+                    });
+                    state = await storeAction.state({
+                        ...commonStateOptions,
+                        ...stateFieldParams
+                    });
+                } else {
+                    const _exhaustiveCheck: never = storeAction;
+                    continue;
+                }
+            } else {
+                state = storeAction?.lastResultState ?? 'enabled';
+            }
+            result.push(
+                omitByNil({
+                    actionId: actionId,
+                    type: storeActionTypeToAPIActionType(storeAction.type),
+                    name: storeAction.name,
+                    label: storeAction.label,
+                    icon: storeAction.icon,
+                    state: state,
+                    inputFields: storeAction.inputFields
+                })
+            );
+        } catch (error: any) {
+            userLogger.warn(`getCustomActionsById: error resolving custom action, id: '${actionId}', error: ${error.message}`);
+        }
+    }
+
+    return result;
+}
+
+export function runCustomAction({
+    runActionRequest,
+    customActionMap,
+    contentSourceDataById,
+    userLogger,
+    stackbitConfig
+}: {
+    runActionRequest: APIRunCustomActionRequest;
+    customActionMap: ContentStoreCustomActionMap;
+    contentSourceDataById: Record<string, ContentStoreTypes.ContentSourceData>;
+    userLogger: StackbitTypes.Logger;
+    stackbitConfig: Config | null;
+}): Promise<CustomActionStateChange> {
+    const storeAction = customActionMap[runActionRequest.actionId];
+    if (!storeAction) {
+        throw new Error(`Error running action: action not found, action name: '${runActionRequest.actionName}' action ID: '${runActionRequest.actionId}'.`);
+    }
+    const prevResultState = storeAction.lastResultState;
+    if (storeAction.lastResultState && storeAction.lastResultState !== 'enabled') {
+        throw new Error(
+            `Error running action: action is not enabled, action name: '${runActionRequest.actionName}' action ID: '${runActionRequest.actionId}'.`
+        );
+    }
+
+    try {
+        const actionLogger = userLogger.createLogger({ label: `action:${storeAction.name}` });
+        const configDelegate = createConfigDelegate({ contentSourceDataById: contentSourceDataById, logger: actionLogger });
+        const currentPageDocument = getCSIDocumentWithSourceFromDocumentSpec(runActionRequest.currentPageDocument, configDelegate);
+
+        storeAction.runningHandler = true;
+        storeAction.lastResultState = 'running';
+
+        const commonRunOptions: StackbitTypes.CustomActionRunCommonOptions = {
+            actionId: storeAction.actionId,
+            inputData: runActionRequest.inputData,
+            currentLocale: runActionRequest.locale,
+            currentUser: runActionRequest.user,
+            currentPageUrl: runActionRequest.pageUrl,
+            currentPageDocument: currentPageDocument,
+            getContentSourceActionsForSource: getContentSourceActionsForSourceThunk({
+                getContentSourceDataById: () => contentSourceDataById,
+                logger: userLogger,
+                user: runActionRequest.user,
+                stackbitConfig: stackbitConfig
+            }),
+            getUserContextForContentSourceType: getUserContextForSrcTypeThunk(runActionRequest.user),
+            ...configDelegate
+        };
+
+        let promise;
+
+        if (storeAction.type === 'global') {
+            promise = storeAction.run(commonRunOptions);
+        } else if (storeAction.type === 'bulk') {
+            const documents = (runActionRequest as APIRunCustomActionRequestBulk).documents.map((documentSpec) => {
+                const { document } = getCSIDocumentAndModelWithSourceFromDocumentSpec({
+                    documentSpec,
+                    contentSourceDataById
+                });
+                return document;
+            });
+            promise = storeAction.run({
+                ...commonRunOptions,
+                documents
+            });
+        } else if (storeAction.type === 'document') {
+            const { document, model } = getCSIDocumentAndModelWithSourceFromDocumentSpec({
+                documentSpec: storeAction.documentSpec,
+                contentSourceDataById
+            });
+            promise = storeAction.run({
+                ...commonRunOptions,
+                document,
+                model,
+                contentSourceActions: commonRunOptions.getContentSourceActionsForSource({
+                    srcType: storeAction.documentSpec.srcType,
+                    srcProjectId: storeAction.documentSpec.srcProjectId
+                })!
+            });
+        } else if (storeAction.type === 'objectModel') {
+            const handlerObjectParams = getHandlerParamsForObjectModelAction({
+                storeAction,
+                contentSourceDataById
+            });
+            promise = storeAction.run({
+                ...commonRunOptions,
+                ...handlerObjectParams,
+                contentSourceActions: commonRunOptions.getContentSourceActionsForSource({
+                    srcType: storeAction.documentSpec.srcType,
+                    srcProjectId: storeAction.documentSpec.srcProjectId
+                })!
+            });
+        } else if (storeAction.type === 'objectField') {
+            const handlerObjectParams = getHandlerParamsForObjectFieldAction({
+                storeAction,
+                contentSourceDataById
+            });
+            promise = storeAction.run({
+                ...commonRunOptions,
+                ...handlerObjectParams,
+                contentSourceActions: commonRunOptions.getContentSourceActionsForSource({
+                    srcType: storeAction.documentSpec.srcType,
+                    srcProjectId: storeAction.documentSpec.srcProjectId
+                })!
+            });
+        } else if (storeAction.type === 'field') {
+            const handlerFieldParams = getHandlerParamsForFieldAction({ storeAction, contentSourceDataById });
+            promise = storeAction.run({
+                ...commonRunOptions,
+                ...handlerFieldParams,
+                contentSourceActions: commonRunOptions.getContentSourceActionsForSource({
+                    srcType: storeAction.documentSpec.srcType,
+                    srcProjectId: storeAction.documentSpec.srcProjectId
+                })!
+            });
+        } else {
+            throw new Error(`action type ${(storeAction as any).type} not supported`);
+        }
+
+        return promise
+            .then((actionResult) => {
+                storeAction.runningHandler = false;
+                storeAction.lastResultState = actionResult?.state;
+                userLogger.debug(`Action completed: ${storeAction.actionId}`);
+                return Promise.resolve(
+                    omitByNil({
+                        actionId: storeAction.actionId,
+                        actionName: storeAction.name,
+                        actionType: storeActionTypeToAPIActionType(storeAction.type),
+                        // TODO: resolve the state if state function is defined
+                        state: actionResult?.state ?? 'enabled',
+                        success: actionResult?.success,
+                        error: actionResult?.error
+                    })
+                );
+            })
+            .catch((error: any) => {
+                storeAction.runningHandler = false;
+                storeAction.lastResultState = prevResultState;
+                userLogger.debug(`Error running action: ${error.message}`);
+                return Promise.resolve({
+                    actionId: storeAction.actionId,
+                    actionName: storeAction.name,
+                    actionType: storeActionTypeToAPIActionType(storeAction.type),
+                    // TODO: resolve the state if state function is defined
+                    state: prevResultState ?? 'enabled',
+                    error: `Error running action: ${error.message}`
+                });
+            });
+    } catch (error: any) {
+        if (storeAction) {
+            storeAction.runningHandler = false;
+            storeAction.lastResultState = prevResultState;
+        }
+        userLogger.debug(`Error running action: ${error.message}`);
+        return Promise.resolve({
+            actionId: runActionRequest.actionId,
+            actionName: storeAction?.name ?? runActionRequest.actionName,
+            actionType: storeActionTypeToAPIActionType(storeAction?.type) ?? runActionRequest.actionType,
+            // TODO: resolve the state if state function is defined
+            state: prevResultState ?? 'enabled',
+            error: `Error running action: ${error.message}`
+        });
+    }
+}
+
+function getCSIDocumentWithSourceFromDocumentSpec(
+    documentSpec: APICustomActionDocumentSpecifier | undefined,
+    configDelegate: StackbitTypes.ConfigDelegate
+): StackbitTypes.DocumentWithSource | undefined {
+    return documentSpec
+        ? configDelegate.getDocumentById({
+              id: documentSpec.srcDocumentId,
+              srcType: documentSpec.srcType,
+              srcProjectId: documentSpec.srcProjectId
+          })
+        : undefined;
+}
+
+function getHandlerParamsForObjectModelAction({
+    storeAction,
+    contentSourceDataById
+}: {
+    storeAction: Pick<ContentStoreCustomActionObjectModel, 'documentSpec' | 'fieldPath'>;
+    contentSourceDataById: Record<string, ContentStoreTypes.ContentSourceData>;
+}): StackbitTypes.CustomActionObjectModelStateParams {
+    const fieldActionCommonParams = getHandlerParamsForFieldAction({
+        storeAction,
+        contentSourceDataById
+    });
+
+    if (!fieldActionCommonParams.documentField) {
+        throw new Error(`object document field not found at field path: ${storeAction.fieldPath.join('.')}`);
+    }
+
+    const documentField = fieldActionCommonParams.documentField as StackbitTypes.DocumentModelFieldNonLocalized;
+    const documentSpec = storeAction.documentSpec;
+    const contentSourceData = getContentSourceDataByTypeAndProjectIdOrThrow(documentSpec.srcType, documentSpec.srcProjectId, contentSourceDataById);
+    const objectModel = contentSourceData.modelMap[documentField.modelName];
+    if (!objectModel || objectModel.type !== 'object') {
+        throw new Error(`object model '${documentField.modelName}' not found`);
+    }
+
+    return {
+        ...fieldActionCommonParams,
+        documentField,
+        modelField: fieldActionCommonParams.modelField as StackbitTypes.FieldModel,
+        objectModel: {
+            ...objectModel,
+            srcType: documentSpec.srcType,
+            srcProjectId: documentSpec.srcProjectId
+        }
+    };
+}
+
+function getHandlerParamsForObjectFieldAction({
+    storeAction,
+    contentSourceDataById
+}: {
+    storeAction: Pick<ContentStoreCustomActionObjectField, 'documentSpec' | 'fieldPath'>;
+    contentSourceDataById: Record<string, ContentStoreTypes.ContentSourceData>;
+}): StackbitTypes.CustomActionObjectFieldStateParams {
+    const fieldActionCommonParams = getHandlerParamsForFieldAction({
+        storeAction,
+        contentSourceDataById
+    });
+
+    if (!fieldActionCommonParams.documentField) {
+        throw new Error(`object document field not found at field path: ${storeAction.fieldPath.join('.')}`);
+    }
+
+    return {
+        ...fieldActionCommonParams,
+        documentField: fieldActionCommonParams.documentField as StackbitTypes.DocumentObjectFieldNonLocalized,
+        modelField: fieldActionCommonParams.modelField as StackbitTypes.FieldObject
+    };
+}
+
+function getHandlerParamsForFieldAction({
+    storeAction,
+    contentSourceDataById
+}: {
+    storeAction: Pick<ContentStoreCustomActionField, 'documentSpec' | 'fieldPath'>;
+    contentSourceDataById: Record<string, ContentStoreTypes.ContentSourceData>;
+}): StackbitTypes.CustomActionFieldStateParams {
+    const documentSpec = storeAction.documentSpec;
+    const contentSourceData = getContentSourceDataByTypeAndProjectIdOrThrow(documentSpec.srcType, documentSpec.srcProjectId, contentSourceDataById);
+    const document = contentSourceData.documentMap[documentSpec.srcDocumentId];
+    const csiDocument = contentSourceData.csiDocumentMap[documentSpec.srcDocumentId];
+    if (!document || !csiDocument) {
+        throw new Error(
+            `document not found for srcType: ${documentSpec.srcType}, srcProjectId: ${documentSpec.srcProjectId}, srcDocumentId: ${documentSpec.srcDocumentId}`
+        );
+    }
+
+    const model = contentSourceData.modelMap[document.srcModelName];
+    if (!model) {
+        throw new Error(`model '${document.srcModelName}' not found`);
+    }
+
+    const mappedCSIDocument = mapStoreDocumentToCSIDocumentWithSource({ document, csiDocument });
+
+    // the documentField should be localized because fieldPath includes locales
+    const { modelField, documentField } = getModelAndDocumentFieldForLocalizedFieldPath({
+        document,
+        model,
+        fieldPath: storeAction.fieldPath,
+        modelMap: contentSourceData.modelMap
+    }) as {
+        // list items cannot have actions, therefore we can safely reduce the type to non list item fields
+        modelField: StackbitTypes.Field;
+        documentField: ContentStoreTypes.DocumentField;
+    };
+
+    const csiDocumentField = mapStoreFieldToCSIField(documentField);
+
+    return {
+        parentDocument: mappedCSIDocument,
+        parentModel: {
+            ...model,
+            srcType: documentSpec.srcType,
+            srcProjectId: documentSpec.srcProjectId
+        },
+        documentField: csiDocumentField,
+        modelField: modelField,
+        fieldPath: storeAction.fieldPath
+    };
+}
+
+function getCSIDocumentAndModelWithSourceFromDocumentSpec({
+    documentSpec,
+    contentSourceDataById
+}: {
+    documentSpec: APICustomActionDocumentSpecifier;
+    contentSourceDataById: Record<string, ContentStoreTypes.ContentSourceData>;
+}): {
+    document: StackbitTypes.DocumentWithSource;
+    model: StackbitTypes.ModelWithSource;
+} {
+    const contentSourceData = getContentSourceDataByTypeAndProjectIdOrThrow(documentSpec.srcType, documentSpec.srcProjectId, contentSourceDataById);
+    const document = contentSourceData.documentMap[documentSpec.srcDocumentId];
+    const csiDocument = contentSourceData.csiDocumentMap[documentSpec.srcDocumentId];
+    if (!document || !csiDocument) {
+        throw new Error(
+            `document not found, srcType: ${documentSpec.srcType}, srcProjectId: ${documentSpec.srcProjectId}, srcDocumentId: ${documentSpec.srcDocumentId}`
+        );
+    }
+    const mappedDocument = mapStoreDocumentToCSIDocumentWithSource({
+        document,
+        csiDocument
+    });
+    const model = contentSourceData.modelMap[mappedDocument.modelName];
+    if (!model) {
+        throw new Error(`model '${mappedDocument.modelName}' not found`);
+    }
+    return {
+        document: mappedDocument,
+        model: {
+            ...model,
+            srcType: documentSpec.srcType,
+            srcProjectId: documentSpec.srcProjectId
+        }
+    };
+}
+
+function storeActionTypeToAPIActionType(storeActionType: ContentStoreCustomAction['type']): APICustomAction['type'] {
+    if (storeActionType === 'objectModel' || storeActionType === 'objectField') {
+        return 'object';
+    }
+    return storeActionType;
+}