@erxes/api-shared 0.0.0-stage → 3.2.19-1

package/src/core-modules/email-content/renderEmailContent.ts

@@ -0,0 +1,88 @@
+import { blocksToHtml } from './blocksToHtml';
+import { EMAIL_CONTENT_FORMATS } from './constants';
+import { appendUnsubscribeFooter } from './emailFooter';
+import { expandRepeatRows } from './expandRepeatRows';
+import { replacePlaceholders } from './replacePlaceholders';
+import {
+  TEmailContent,
+  TEmailContentFormat,
+  TRenderEmailContentOptions,
+} from './types';
+
+/**
+ * What an email body was written in. Content saved before the format was
+ * recorded carries no marker, and block content is what that used to mean —
+ * so nothing has to be migrated for this to be right.
+ */
+export const resolveEmailContentFormat = (
+  email?: TEmailContent,
+): TEmailContentFormat => {
+  if (email?.contentFormat) {
+    return email.contentFormat;
+  }
+
+  return email?.contentJson
+    ? EMAIL_CONTENT_FORMATS.MAILY
+    : EMAIL_CONTENT_FORMATS.BLOCKS;
+};
+
+const renderBody = async (
+  email: TEmailContent,
+  {
+    replaceBlocks,
+    unsubscribeUrl,
+    postalAddress,
+    blocksConfig,
+  }: TRenderEmailContentOptions,
+) => {
+  const content = email.content || '';
+
+  if (resolveEmailContentFormat(email) === EMAIL_CONTENT_FORMATS.MAILY) {
+    // The editor rendered the email itself, so the footer is appended to its
+    // html rather than wrapped around it the way block content is.
+    return unsubscribeUrl
+      ? appendUnsubscribeFooter(content, { unsubscribeUrl, postalAddress })
+      : content;
+  }
+
+  const blocks = replaceBlocks ? await replaceBlocks(content) : content;
+
+  return blocksToHtml(blocks, {
+    ...blocksConfig,
+    ...(unsubscribeUrl
+      ? { wrapper: { email: true, unsubscribeUrl, postalAddress } }
+      : {}),
+  });
+};
+
+/**
+ * The body as html with its placeholders still in, a row reading
+ * `{{ list.$.field }}` already written once per item. A sender that resolves
+ * placeholders in one batch reads them from this.
+ */
+export const renderEmailBody = async (
+  email: TEmailContent,
+  options: TRenderEmailContentOptions = {},
+): Promise<string> => {
+  const body = await renderBody(email, options);
+
+  return options.countItems
+    ? expandRepeatRows(body, options.countItems)
+    : body;
+};
+
+/**
+ * The one place an email body becomes the html a recipient gets, whichever
+ * editor wrote it and whichever service is sending it.
+ */
+export const renderEmailContent = async (
+  email: TEmailContent,
+  options: TRenderEmailContentOptions = {},
+): Promise<string> => {
+  const { resolvers = [], onFields, markMissing } = options;
+
+  return replacePlaceholders(await renderEmailBody(email, options), resolvers, {
+    onFields,
+    markMissing,
+  });
+};

package/src/core-modules/email-content/replacePlaceholders.ts

@@ -0,0 +1,143 @@
+import dayjs from 'dayjs';
+import _ from 'lodash';
+import { blocksToHtml, escapeHtml } from './blocksToHtml';
+import { TEmailFieldOutcome } from './types';
+
+/** `{{ path }}`, or `{{ path | fallback }}` for a field with a default. */
+const PLACEHOLDER = /\{\{\s*([^{}|]+?)\s*(?:\|\s*([^{}]*?)\s*)?\}\}/g;
+
+/**
+ * What a source has for a placeholder: its value; `null` when the field is
+ * this source's but the record has nothing for it; `undefined` when the
+ * placeholder is not this source's at all, so the next source is asked.
+ */
+export type TPlaceholderValue = string | null | undefined;
+
+export type TPlaceholderResolver = (
+  path: string,
+) => Promise<TPlaceholderValue> | TPlaceholderValue;
+
+export type TReplacePlaceholdersOptions = {
+  /** Told once which fields had a value and which did not. */
+  onFields?: (fields: TEmailFieldOutcome[]) => void;
+  /**
+   * Preview only. An empty field without a default shows its own name, since
+   * a gap rendered silently cannot be told apart from a preview that works.
+   */
+  markMissing?: boolean;
+};
+
+export const collectPlaceholderPaths = (html?: string): string[] =>
+  html ? [...new Set([...html.matchAll(PLACEHOLDER)].map(([, path]) => path))] : [];
+
+/**
+ * The one pass that fills an email's placeholders. Sources are asked in
+ * order; a placeholder no source owns is left in place, which is what marks
+ * it as never wired up.
+ */
+export const replacePlaceholders = async (
+  html: string,
+  resolvers: TPlaceholderResolver[],
+  { onFields, markMissing }: TReplacePlaceholdersOptions = {},
+): Promise<string> => {
+  if (!html) {
+    return html;
+  }
+
+  const values = new Map<string, TPlaceholderValue>();
+
+  for (const path of collectPlaceholderPaths(html)) {
+    let value: TPlaceholderValue;
+
+    for (const resolve of resolvers) {
+      value = await resolve(path);
+
+      if (value !== undefined) {
+        break;
+      }
+    }
+
+    values.set(path, value === '' ? null : value);
+  }
+
+  onFields?.(
+    [...values]
+      .filter(([, value]) => value !== undefined)
+      .map(([id, value]) => ({ id, filled: !!value })),
+  );
+
+  return html.replace(PLACEHOLDER, (placeholder, path: string, fallback) => {
+    const value = values.get(path);
+
+    if (value) {
+      return value;
+    }
+
+    if (fallback) {
+      return fallback;
+    }
+
+    if (value === null) {
+      return markMissing ? `‹${path}›` : '';
+    }
+
+    return placeholder;
+  });
+};
+
+/** Owns every placeholder: a field of the record the email is written to. */
+export const recordPlaceholderResolver =
+  (record: object = {}): TPlaceholderResolver =>
+  (path) => {
+    const value = _.get(record, path);
+
+    if (value === undefined || value === null || value === '') {
+      return null;
+    }
+
+    if (value instanceof Date) {
+      return dayjs(value).format('YYYY-MM-DD');
+    }
+
+    return escapeHtml(String(value));
+  };
+
+const DOCUMENT_PREFIX = 'document.';
+
+const bodyHtml = (html: string) =>
+  html.match(/<body[^>]*>([\s\S]*?)<\/body>/i)?.[1]?.trim() || html;
+
+/**
+ * Owns `document.<id>`: the document rendered for the record the email is
+ * written to. Each service reaches documents its own way, so it supplies both
+ * the per-record print and the raw content used when printing gives nothing.
+ */
+export const documentPlaceholderResolver =
+  ({
+    print,
+    findContent,
+  }: {
+    print: (documentId: string) => Promise<string | undefined | null>;
+    findContent: (documentId: string) => Promise<string | undefined | null>;
+  }): TPlaceholderResolver =>
+  async (path) => {
+    if (!path.startsWith(DOCUMENT_PREFIX)) {
+      return undefined;
+    }
+
+    const documentId = path.slice(DOCUMENT_PREFIX.length);
+    let html = '';
+
+    try {
+      html = bodyHtml(String((await print(documentId)) || ''));
+    } catch {
+      // A document that cannot be printed for this record still has a body,
+      // so the email keeps it rather than losing the section entirely.
+    }
+
+    if (!html) {
+      html = blocksToHtml((await findContent(documentId)) || '');
+    }
+
+    return html || null;
+  };

package/src/core-modules/email-content/types.ts

@@ -0,0 +1,49 @@
+import { EMAIL_CONTENT_FORMATS } from './constants';
+import type { TBlocksToHtmlConfig } from './blocksToHtml';
+import type { TRepeatCounter } from './expandRepeatRows';
+import type { TPlaceholderResolver } from './replacePlaceholders';
+
+export type TEmailContentFormat =
+  (typeof EMAIL_CONTENT_FORMATS)[keyof typeof EMAIL_CONTENT_FORMATS];
+
+/**
+ * An email body as it is sent. `blocks` content is a serialized block
+ * document; `maily` content is the html the email editor rendered, with its
+ * fields left as `{{ … }}` placeholders. Which one it is is said outright
+ * rather than guessed from which field happens to be set.
+ */
+export type TEmailContent = {
+  content?: string;
+  contentJson?: Record<string, unknown>;
+  contentFormat?: TEmailContentFormat;
+};
+
+/** Whether the record being rendered for had something for this field. */
+export type TEmailFieldOutcome = { id: string; filled: boolean };
+
+export type TRenderEmailContentOptions = {
+  /** Where each placeholder's value comes from, asked in order. */
+  resolvers?: TPlaceholderResolver[];
+  /**
+   * Block content keeps its placeholders as nodes of its own document format,
+   * so the module that owns that format substitutes them before rendering.
+   */
+  replaceBlocks?: (content: string) => Promise<string> | string;
+  /** Footer the recipient is owed, in whichever shape the format needs. */
+  unsubscribeUrl?: string;
+  postalAddress?: string;
+  blocksConfig?: TBlocksToHtmlConfig;
+  /**
+   * Told once per render which fields the record answered and which it did
+   * not — the only moment both are known together.
+   */
+  onFields?: (fields: TEmailFieldOutcome[]) => void;
+  /**
+   * Preview only. A field the record has nothing for is rendered as its own
+   * name instead of as nothing, because a preview that shows a gap silently
+   * cannot be told apart from one that is working.
+   */
+  markMissing?: boolean;
+  /** How many items a list holds, for rows written once per item. */
+  countItems?: TRepeatCounter;
+};

package/src/core-modules/email-content/unresolvedPlaceholders.ts

@@ -0,0 +1,27 @@
+/**
+ * A rendered email has no reason to still contain `{{ … }}`.
+ *
+ * A record with nothing for a field falls back to that field's own default,
+ * or to nothing at all — never to the placeholder's own text. So a marker
+ * that survived rendering is always something not wired up, not a person
+ * whose data was thin, and that difference is the whole point: a campaign
+ * that went out with `{{ firstName }}` in it should be answerable without
+ * guessing which of the two it was.
+ */
+const PLACEHOLDER = /\{\{\s*([^{}]+?)\s*\}\}/g;
+
+export const findUnresolvedPlaceholders = (html?: string): string[] => {
+  if (!html) {
+    return [];
+  }
+
+  return Array.from(
+    new Set([...html.matchAll(PLACEHOLDER)].map((match) => match[1])),
+  );
+};
+
+/** What to put in front of someone reading a failure. */
+export const describeUnresolvedPlaceholders = (placeholders: string[]) =>
+  `unresolved placeholder${placeholders.length > 1 ? 's' : ''}: ${placeholders
+    .map((placeholder) => `{{ ${placeholder} }}`)
+    .join(', ')}`;

package/src/core-modules/forms/index.ts

@@ -0,0 +1,2 @@
+export * from './utils';
+export * from './types';

package/src/core-modules/forms/types.ts

@@ -0,0 +1,86 @@
+import type { TPropertyValueUsageHandler } from '../properties/valueUsage';
+
+export type PropertySystemFieldType =
+  | 'text'
+  | 'textarea'
+  | 'number'
+  | 'boolean'
+  | 'date'
+  | 'select'
+  | 'multiSelect'
+  | 'relation'
+  | 'file'
+  | 'phone';
+
+export interface IPropertySystemField {
+  code: string;
+  name: string;
+  type: PropertySystemFieldType;
+  // Fields sharing a group: at least one must show on create and be filled in.
+  requiredGroup?: string;
+  // Always holds a value (a default, or set by the server), so "required" means nothing.
+  alwaysFilled?: boolean;
+  // Shown on the create form until an admin decides otherwise.
+  visibleToCreateByDefault?: boolean;
+  // Off on records until an admin turns it on.
+  hiddenByDefault?: boolean;
+  // The create flow cannot take this field, so it never shows there.
+  notOnCreate?: boolean;
+  // Shown apart from the laid-out fields (e.g. tags above the form).
+  outsideLayout?: boolean;
+}
+
+// Featured fields: created at runtime by a plugin feature, stored in
+// propertiesData like custom fields, but only their owner may change them.
+export type FeaturedFieldType =
+  | 'text'
+  | 'number'
+  | 'boolean'
+  | 'date'
+  | 'select'
+  | 'multiSelect';
+
+export interface IFeaturedFieldOwner {
+  plugin: string;
+  module: string;
+  // Instance-scoped owner (e.g. one score campaign); absent for fields a
+  // plugin declares once in its meta.
+  refId?: string;
+}
+
+export interface IFeaturedFieldDefinition {
+  key: string;
+  name: string;
+  type: FeaturedFieldType;
+  options?: { label: string; value: string }[];
+  index?: { unique?: boolean };
+}
+
+export interface IFeaturedFieldGroup {
+  key: string;
+  name: string;
+}
+
+// Declared once in a plugin's meta, on any content type (e.g. core:customer).
+export interface IPropertyFeaturedFields {
+  contentType: string;
+  module: string;
+  group: IFeaturedFieldGroup;
+  fields: IFeaturedFieldDefinition[];
+}
+
+export interface IPropertyType {
+  type: string;
+  description: string;
+  systemFields?: IPropertySystemField[];
+  // Declared when a content type's forms render Basic information from field
+  // renderers; only then may it be laid out in Settings.
+  systemFieldsLayout?: { defaultLayout: string[][] };
+}
+
+export interface IPropertyMeta {
+  types: IPropertyType[];
+  featuredFields?: IPropertyFeaturedFields[];
+  // Records live in the plugin, so only it can say which hold a value.
+  valueUsage?: TPropertyValueUsageHandler;
+}

package/src/core-modules/forms/utils.ts

@@ -0,0 +1,34 @@
+import { IFeaturedFieldOwner } from './types';
+
+// Deterministic, so an owner can address its field by code without storing ids.
+export const featuredFieldCode = (owner: IFeaturedFieldOwner, key: string) =>
+  [owner.plugin, owner.module, owner.refId, key].filter(Boolean).join(':');
+
+export const generateFieldsFromSchema = async (
+  queSchema: any,
+  namePrefix: string,
+) => {
+  const fields: any = [];
+
+  // field definitions
+  const { paths = [] } = queSchema || {};
+
+  for (const name of Object.keys(paths)) {
+    const path = paths[name];
+    const { label, selectOptions } = path?.options || {};
+    const type = path.instance;
+
+    if (['String', 'Number', 'Date', 'Boolean'].includes(type) && label) {
+      // add to fields list
+      fields.push({
+        _id: Math.random(),
+        name: `${namePrefix}${name}`,
+        label,
+        type: path.instance,
+        selectOptions,
+      });
+    }
+  }
+
+  return fields;
+};

package/src/core-modules/import-export/index.ts

@@ -0,0 +1,7 @@
+export * from './types';
+export * from './worker';
+export * from './zodSchemas';
+export * from './utils/exportCursor';
+export * from './utils/importExportRuntime';
+export * from './utils/headerMatcher';
+export * from './utils/importUtils';

package/src/core-modules/import-export/types.ts

@@ -0,0 +1,204 @@
+import { z } from 'zod';
+
+export interface IImportExportContext<TModels = any> {
+  subdomain: string;
+  processId: string;
+  models?: TModels;
+  [key: string]: any;
+}
+
+export type ImportHeaderDataType =
+  | 'text'
+  | 'number'
+  | 'date'
+  | 'boolean'
+  | 'select'
+  | 'multiSelect';
+
+export interface ImportHeaderDefinition {
+  label: string;
+  key: string;
+  aliases?: string[];
+  isDefault?: boolean;
+  type?: 'system' | 'customProperty';
+  /** Custom property code, unqualified by row. */
+  code?: string;
+  /** 1-based row of a repeating property group. */
+  rowIndex?: number;
+  dataType?: ImportHeaderDataType;
+  options?: string[];
+  /** Human-readable shape of an accepted value, e.g. `YYYY-MM-DD`. */
+  example?: string;
+  required?: boolean;
+}
+
+export interface ImportColumnMapping {
+  index: number;
+  header: string;
+  key: string;
+}
+
+export interface ImportExportTypeDefinition {
+  label: string;
+  contentType: string;
+  permissions?: string[];
+}
+
+export interface InsertImportRowsInputData {
+  moduleName: string;
+  collectionName: string;
+  rows: any[];
+  userId: string;
+}
+export interface BatchSkipRowInputData {
+  moduleName: string;
+  collectionName: string;
+  rowData: any;
+}
+export interface BatchSkipRowArgs {
+  subdomain: string;
+  data: BatchSkipRowInputData;
+}
+
+export interface InsertImportRowsArgs {
+  subdomain: string;
+  data: InsertImportRowsInputData;
+}
+
+export interface InsertImportRowsResult {
+  successRows: any[];
+  errorRows: Array<
+    Record<string, any> & {
+      error?: string;
+    }
+  >;
+}
+
+export interface TImportHandlers {
+  insertImportRows: (
+    args: InsertImportRowsArgs,
+    ctx: IImportExportContext,
+  ) => Promise<InsertImportRowsResult>;
+  getImportHeaders: (
+    args: {
+      subdomain: string;
+      data: { moduleName: string; collectionName: string };
+    },
+    ctx: IImportExportContext,
+  ) => Promise<ImportHeaderDefinition[]>;
+
+  whenReady?: () => void;
+  batchSkipRow?: (
+    args: BatchSkipRowArgs,
+    ctx: IImportExportContext,
+  ) => Promise<boolean>;
+}
+
+export interface ImportConfig extends TImportHandlers {
+  types?: ImportExportTypeDefinition[];
+}
+
+export type GetExportData = {
+  moduleName: string;
+  collectionName: string;
+  cursor?: string;
+  limit: number;
+  filters?: Record<string, unknown>;
+  ids?: string[];
+  selectedFields?: string[];
+};
+export interface GetExportDataArgs {
+  subdomain: string;
+  data: GetExportData;
+}
+
+export interface TExportHandlers {
+  getExportHeaders: (
+    args: {
+      subdomain: string;
+      data: {
+        moduleName: string;
+        collectionName: string;
+        filters?: Record<string, unknown>;
+      };
+    },
+    ctx: IImportExportContext,
+  ) => Promise<ImportHeaderDefinition[]>;
+  getExportData: (
+    args: GetExportDataArgs,
+    ctx: IImportExportContext,
+  ) => Promise<Record<string, any>[]>;
+  whenReady?: () => void;
+}
+
+export interface ExportConfig extends TExportHandlers {
+  types?: ImportExportTypeDefinition[];
+}
+
+export interface ImportExportImportMeta {
+  configured: boolean;
+  hasGetImportHeaders?: boolean;
+  hasInsertImportRows?: boolean;
+  types?: ImportExportTypeDefinition[];
+}
+
+export interface ImportExportExportMeta {
+  configured: boolean;
+  hasGetExportHeaders?: boolean;
+  hasGetExportData?: boolean;
+  hasUploadFile?: boolean;
+  types?: ImportExportTypeDefinition[];
+}
+
+export interface ImportExportMeta {
+  import?: ImportExportImportMeta;
+  export?: ImportExportExportMeta;
+}
+
+export interface ImportExportConfigs {
+  createContext?: (
+    subdomain: string,
+    context: IImportExportContext,
+  ) => Promise<IImportExportContext>;
+  import?: ImportConfig;
+  export?: ExportConfig;
+}
+
+export interface ImportJobData {
+  subdomain: string;
+  data: {
+    importId: string;
+    entityType: string;
+    fileKey: string;
+    userId: string;
+  };
+}
+
+export interface ExportJobData {
+  subdomain: string;
+  data: {
+    exportId: string;
+    entityType: string;
+  };
+}
+
+export type TGetImportHeadersOutput = ImportHeaderDefinition[];
+export type TInsertImportRowsInput = InsertImportRowsInputData;
+export type TBatchSkipRowInput = BatchSkipRowInputData;
+
+export const InsertImportRowsInputSchema = z.object({
+  subdomain: z.string(),
+  data: z.object({
+    moduleName: z.string(),
+    collectionName: z.string(),
+    rows: z.array(z.record(z.any())),
+  }),
+});
+
+export enum TImportExportProducers {
+  INSERT_IMPORT_ROWS = 'insertImportRows',
+  GET_IMPORT_HEADERS = 'getImportHeaders',
+  BATCH_SKIP_ROW = 'batchSkipRow',
+  GET_EXPORT_HEADERS = 'getExportHeaders',
+  GET_EXPORT_DATA = 'getExportData',
+}