@haiiro/docuflow 0.0.1 → 0.0.3

package/src/shared/documents/attachment-target.util.ts

@@ -1,64 +0,0 @@
-// An attachment points at the record it is attached to through one of its
-// target<Object>Id columns (targetCompanyId, targetTaskId, target<custom>Id).
-// The file belongs to that record, not to the attachment.
-const TARGET_KEY_PATTERN = /^target([A-Z][A-Za-z0-9]*)Id$/;
-
-export const getAttachmentTarget = (
-  attachment: Record<string, unknown>,
-): { objectNameSingular: string; recordId: string } | undefined => {
-  for (const [key, value] of Object.entries(attachment)) {
-    const match = TARGET_KEY_PATTERN.exec(key);
-
-    if (match !== null && typeof value === 'string' && value.length > 0) {
-      const [first, ...rest] = match[1];
-
-      return {
-        objectNameSingular: `${first.toLowerCase()}${rest.join('')}`,
-        recordId: value,
-      };
-    }
-  }
-
-  return undefined;
-};
-
-export type FileItem = { fileId: string; label: string; url?: string };
-
-export const readFileItems = (value: unknown): FileItem[] =>
-  Array.isArray(value)
-    ? value.flatMap((item: unknown) => {
-        if (typeof item !== 'object' || item === null) {
-          return [];
-        }
-
-        const { fileId, label, url } = item as Record<string, unknown>;
-
-        return typeof fileId === 'string' && fileId.length > 0 && typeof label === 'string'
-          ? [{ fileId, label, url: typeof url === 'string' ? url : undefined }]
-          : [];
-      })
-    : [];
-
-// "Договор 12.pdf" → "Договор 12".
-export const getDocumentNameFromFile = (fileName: string): string => {
-  const extensionStart = fileName.lastIndexOf('.');
-
-  return extensionStart > 0 ? fileName.slice(0, extensionStart) : fileName;
-};
-
-export const formatRecordLabel = (value: unknown): string | undefined => {
-  if (typeof value === 'string' && value.trim().length > 0) {
-    return value.trim();
-  }
-
-  if (typeof value === 'object' && value !== null) {
-    const { firstName, lastName } = value as Record<string, unknown>;
-    const fullName = [firstName, lastName]
-      .filter((part): part is string => typeof part === 'string' && part.length > 0)
-      .join(' ');
-
-    return fullName.length > 0 ? fullName : undefined;
-  }
-
-  return undefined;
-};

package/src/shared/engine.ts

@@ -1,11 +0,0 @@
-// Who does the server-side work of docflow in this workspace. APP: the
-// app's logic functions (any Twenty). FORK: the NorDiv fork server modules,
-// which then must not be doubled by the app.
-export type DocflowEngine = 'APP' | 'FORK';
-
-export const getDocflowEngine = (
-  value: string | undefined = process.env.DOCFLOW_ENGINE,
-): DocflowEngine => (value === 'FORK' ? 'FORK' : 'APP');
-
-export const isAppEngine = (value?: string): boolean =>
-  getDocflowEngine(value) === 'APP';

package/src/shared/form/form-field-builder.util.ts

@@ -1,122 +0,0 @@
-import { FORM_FIELD_REQUIRED_SETTING } from 'src/shared/docflow.constants';
-import { type FormField } from 'src/shared/form/form-field.type';
-import { getFillableFormFields } from 'src/shared/form/form-fields.util';
-
-// What the field builder offers: the types the standard form step and the
-// fork render too, so one field list works in the app, in the fork and in
-// the workflow editor.
-export const BUILDER_FIELD_KINDS = [
-  { value: 'TEXT', label: 'Текст', type: 'TEXT' },
-  { value: 'NUMBER', label: 'Число', type: 'NUMBER' },
-  { value: 'DATE', label: 'Дата', type: 'DATE' },
-  { value: 'MEMBER', label: 'Сотрудник', type: 'RECORD', objectName: 'workspaceMember' },
-  { value: 'COMPANY', label: 'Компания', type: 'RECORD', objectName: 'company' },
-  { value: 'PERSON', label: 'Контакт', type: 'RECORD', objectName: 'person' },
-  { value: 'OPPORTUNITY', label: 'Сделка', type: 'RECORD', objectName: 'opportunity' },
-] as const;
-
-export type BuilderFieldKind = (typeof BUILDER_FIELD_KINDS)[number]['value'];
-
-const omitSetting = (settings: FormField['settings'], key: string): Record<string, unknown> =>
-  Object.fromEntries(Object.entries(settings ?? {}).filter(([settingKey]) => settingKey !== key));
-
-export const getBuilderFieldKind = (field: FormField): BuilderFieldKind | undefined =>
-  BUILDER_FIELD_KINDS.find(
-    (kind) =>
-      kind.type === field.type &&
-      (!('objectName' in kind) || kind.objectName === field.settings?.objectName),
-  )?.value;
-
-export const applyBuilderFieldKind = (field: FormField, kindValue: BuilderFieldKind): FormField => {
-  const kind = BUILDER_FIELD_KINDS.find((candidate) => candidate.value === kindValue);
-
-  if (kind === undefined) {
-    return field;
-  }
-
-  const settings = omitSetting(field.settings, 'objectName');
-
-  return {
-    ...field,
-    type: kind.type,
-    value: undefined,
-    settings: 'objectName' in kind ? { ...settings, objectName: kind.objectName } : settings,
-  };
-};
-
-const CYRILLIC_TO_LATIN: Record<string, string> = {
-  а: 'a', б: 'b', в: 'v', г: 'g', д: 'd', е: 'e', ё: 'e', ж: 'zh', з: 'z', и: 'i',
-  й: 'y', к: 'k', л: 'l', м: 'm', н: 'n', о: 'o', п: 'p', р: 'r', с: 's', т: 't',
-  у: 'u', ф: 'f', х: 'h', ц: 'ts', ч: 'ch', ш: 'sh', щ: 'sch', ъ: '', ы: 'y', ь: '',
-  э: 'e', ю: 'yu', я: 'ya',
-};
-
-// The name is what later steps write in a variable, {{step.summaDogovora}}:
-// latin letters and digits, readable from the label.
-export const buildFieldNameFromLabel = (label: string): string => {
-  const words = [...label.toLowerCase()]
-    .map((character) => CYRILLIC_TO_LATIN[character] ?? character)
-    .join('')
-    .split(/[^a-z0-9]+/)
-    .filter((word) => word.length > 0);
-  const name = words
-    .map((word, index) => (index === 0 ? word : word[0].toUpperCase() + word.slice(1)))
-    .join('');
-
-  return /^[a-z]/.test(name) ? name : `field${name}`;
-};
-
-export const buildUniqueFieldName = (label: string, takenNames: string[]): string => {
-  const baseName = buildFieldNameFromLabel(label);
-  let name = baseName;
-  let suffix = 2;
-
-  while (takenNames.includes(name)) {
-    name = `${baseName}${suffix}`;
-    suffix++;
-  }
-
-  return name;
-};
-
-export const buildNewBuilderField = (fields: FormField[], createId: () => string): FormField => ({
-  id: createId(),
-  name: buildUniqueFieldName(`field ${fields.length + 1}`, fields.map(({ name }) => name)),
-  label: '',
-  type: 'TEXT',
-  settings: {},
-});
-
-export const setFieldRequired = (field: FormField, isRequired: boolean): FormField => {
-  const settings = omitSetting(field.settings, FORM_FIELD_REQUIRED_SETTING);
-
-  return { ...field, settings: isRequired ? { ...settings, [FORM_FIELD_REQUIRED_SETTING]: true } : settings };
-};
-
-const OUTPUT_LEAF_TYPES: Record<string, string> = {
-  NUMBER: 'number',
-  DATE: 'string',
-  TEXT: 'string',
-};
-
-// The output schema of a step whose output is these fields, in the format the
-// workflow editor reads for its variable picker. A record comes out as { id }.
-export const buildFieldsOutputSchema = (fields: FormField[]): Record<string, unknown> =>
-  Object.fromEntries(
-    getFillableFormFields(fields).map((field) => [
-      field.name,
-      field.type === 'RECORD'
-        ? {
-            isLeaf: false,
-            type: 'object',
-            label: field.label,
-            value: { id: { isLeaf: true, type: 'string', label: 'Id', value: null } },
-          }
-        : {
-            isLeaf: true,
-            type: OUTPUT_LEAF_TYPES[field.type] ?? 'unknown',
-            label: field.label,
-            value: null,
-          },
-    ]),
-  );

package/src/shared/form/form-field.type.ts

@@ -1,23 +0,0 @@
-// A field of a workflow FORM step and of a task form: one format for both, so
-// a step's fields become the task's fields as they are.
-export type FormFieldType =
-  | 'TEXT'
-  | 'NUMBER'
-  | 'DATE'
-  | 'SELECT'
-  | 'MULTI_SELECT'
-  | 'RECORD';
-
-export type FormField = {
-  id: string;
-  name: string;
-  label: string;
-  type: FormFieldType | string;
-  placeholder?: string;
-  value?: unknown;
-  settings?: Record<string, unknown> | null;
-};
-
-export type FormFieldRole = 'ASSIGNEE' | 'DUE_AT';
-
-export type FormValues = Record<string, unknown>;

package/src/shared/form/form-fields.util.ts

@@ -1,138 +0,0 @@
-import {
-  FORM_FIELD_REQUIRED_SETTING,
-  FORM_FIELD_ROLE_SETTING,
-} from 'src/shared/docflow.constants';
-import {
-  type FormField,
-  type FormFieldRole,
-  type FormValues,
-} from 'src/shared/form/form-field.type';
-
-export const getFormFieldRole = (
-  field: Pick<FormField, 'settings'>,
-): FormFieldRole | undefined => {
-  const role = field.settings?.[FORM_FIELD_ROLE_SETTING];
-
-  return role === 'ASSIGNEE' || role === 'DUE_AT' ? role : undefined;
-};
-
-export const isFormFieldRequired = (
-  field: Pick<FormField, 'settings'>,
-): boolean => field.settings?.[FORM_FIELD_REQUIRED_SETTING] === true;
-
-// The fields a person fills: the assignee and the deadline are set by the
-// process.
-export const getFillableFormFields = <TField extends Pick<FormField, 'settings'>>(
-  fields: TField[],
-): TField[] => fields.filter((field) => getFormFieldRole(field) === undefined);
-
-// A record picker answers with { id }, a multi-select with an array.
-export const isFormValueEmpty = (value: unknown): boolean => {
-  if (value === null || value === undefined) {
-    return true;
-  }
-
-  if (typeof value === 'string') {
-    return value.trim().length === 0;
-  }
-
-  if (Array.isArray(value)) {
-    return value.length === 0;
-  }
-
-  if (typeof value === 'object' && 'id' in value) {
-    const id = (value as { id: unknown }).id;
-
-    return typeof id !== 'string' || id.length === 0;
-  }
-
-  return false;
-};
-
-export const findMissingRequiredFields = <TField extends FormField>({
-  fields,
-  values,
-}: {
-  fields: TField[];
-  values: FormValues;
-}): TField[] =>
-  getFillableFormFields(fields).filter(
-    (field) => isFormFieldRequired(field) && isFormValueEmpty(values[field.name]),
-  );
-
-// A value for every field a person fills, typed or preset in the form. The
-// server checks required fields against exactly this object, so the page and
-// the server agree.
-export const buildFormValues = ({
-  fields,
-  values,
-}: {
-  fields: FormField[];
-  values: FormValues;
-}): FormValues =>
-  Object.fromEntries(
-    getFillableFormFields(fields).flatMap((field) => {
-      const value = field.name in values ? values[field.name] : field.value;
-
-      return value === undefined || value === null ? [] : [[field.name, value]];
-    }),
-  );
-
-// The answer of a form step carries every field, service ones included:
-// later steps read the assignee and the deadline from it.
-export const buildFormStepResponse = ({
-  fields,
-  values,
-}: {
-  fields: Pick<FormField, 'name' | 'value'>[];
-  values: FormValues;
-}): FormValues =>
-  Object.fromEntries(
-    fields.map((field) => [
-      field.name,
-      field.name in values ? values[field.name] : (field.value ?? null),
-    ]),
-  );
-
-const FORM_FIELD_NAME_PATTERN = /^[a-zA-Z][a-zA-Z0-9]*$/;
-
-// A task form is edited by people, so it is checked before it is saved:
-// unique names the engine can address, known types.
-export const getFormFieldsError = (fields: FormField[]): string | undefined => {
-  const names = new Set<string>();
-
-  for (const field of fields) {
-    if (!FORM_FIELD_NAME_PATTERN.test(field.name)) {
-      return `Имя поля «${field.label}» должно начинаться с латинской буквы и состоять из букв и цифр`;
-    }
-
-    if (names.has(field.name)) {
-      return `Поле «${field.name}» повторяется`;
-    }
-
-    if (field.label.trim().length === 0) {
-      return 'У каждого поля должно быть название';
-    }
-
-    names.add(field.name);
-  }
-
-  return undefined;
-};
-
-export const parseFormFields = (value: unknown): FormField[] =>
-  Array.isArray(value)
-    ? value.filter(
-        (field): field is FormField =>
-          typeof field === 'object' &&
-          field !== null &&
-          typeof (field as FormField).name === 'string' &&
-          typeof (field as FormField).label === 'string' &&
-          typeof (field as FormField).type === 'string',
-      )
-    : [];
-
-export const parseFormValues = (value: unknown): FormValues =>
-  typeof value === 'object' && value !== null && !Array.isArray(value)
-    ? (value as FormValues)
-    : {};

package/src/shared/form/step-settings.util.ts

@@ -1,104 +0,0 @@
-import {
-  FORM_FIELD_DUE_IN_DAYS_SETTING,
-  FORM_FIELD_REQUIRED_SETTING,
-  FORM_FIELD_ROLE_SETTING,
-} from 'src/shared/docflow.constants';
-import { type FormField, type FormFieldRole } from 'src/shared/form/form-field.type';
-import { getFormFieldRole } from 'src/shared/form/form-fields.util';
-
-export type StepSettings = {
-  assignee: string | null;
-  dueInDays: number | null;
-  requiredFieldIds: string[];
-};
-
-const ASSIGNEE_FIELD = {
-  name: 'smbAssignee',
-  label: 'Исполнитель',
-  type: 'RECORD',
-} as const;
-const DUE_AT_FIELD = { name: 'smbDueAt', label: 'Срок', type: 'DATE' } as const;
-
-export const readStepSettings = (fields: FormField[]): StepSettings => {
-  const assignee = fields.find((field) => getFormFieldRole(field) === 'ASSIGNEE')?.value;
-  const dueInDays = fields.find((field) => getFormFieldRole(field) === 'DUE_AT')?.settings?.[
-    FORM_FIELD_DUE_IN_DAYS_SETTING
-  ];
-
-  return {
-    assignee: typeof assignee === 'string' && assignee.length > 0 ? assignee : null,
-    dueInDays: typeof dueInDays === 'number' && dueInDays > 0 ? dueInDays : null,
-    requiredFieldIds: fields
-      .filter(
-        (field) =>
-          getFormFieldRole(field) === undefined &&
-          field.settings?.[FORM_FIELD_REQUIRED_SETTING] === true,
-      )
-      .map(({ id }) => id),
-  };
-};
-
-const withRole = (
-  role: FormFieldRole,
-  existing: FormField | undefined,
-  template: { name: string; label: string; type: string },
-  patch: Pick<FormField, 'value' | 'settings'>,
-  createId: () => string,
-): FormField => ({
-  ...template,
-  ...existing,
-  id: existing?.id ?? createId(),
-  value: patch.value,
-  settings: { ...existing?.settings, ...patch.settings, [FORM_FIELD_ROLE_SETTING]: role },
-});
-
-// The role fields stay in the step's field list, where the server reads them;
-// an empty assignee or deadline removes its field.
-export const applyStepSettings = ({
-  fields,
-  settings,
-  createId,
-}: {
-  fields: FormField[];
-  settings: StepSettings;
-  createId: () => string;
-}): FormField[] => {
-  const ordinaryFields = fields
-    .filter((field) => getFormFieldRole(field) === undefined)
-    .map((field) => {
-      const { [FORM_FIELD_REQUIRED_SETTING]: _removed, ...rest } = field.settings ?? {};
-      const isRequired = settings.requiredFieldIds.includes(field.id);
-
-      return {
-        ...field,
-        settings: isRequired ? { ...rest, [FORM_FIELD_REQUIRED_SETTING]: true } : rest,
-      };
-    });
-  const roleFields: FormField[] = [];
-
-  if (settings.assignee !== null) {
-    roleFields.push(
-      withRole(
-        'ASSIGNEE',
-        fields.find((field) => getFormFieldRole(field) === 'ASSIGNEE'),
-        ASSIGNEE_FIELD,
-        { value: settings.assignee, settings: {} },
-        createId,
-      ),
-    );
-  }
-
-  if (settings.dueInDays !== null) {
-    roleFields.push(
-      withRole(
-        'DUE_AT',
-        fields.find((field) => getFormFieldRole(field) === 'DUE_AT'),
-        DUE_AT_FIELD,
-        { value: undefined, settings: { [FORM_FIELD_DUE_IN_DAYS_SETTING]: settings.dueInDays } },
-        createId,
-      ),
-    );
-  }
-
-  return [...roleFields, ...ordinaryFields];
-};

package/src/shared/workflow/launch-step.util.ts

@@ -1,56 +0,0 @@
-import {
-  DOCFLOW_LAUNCH_PARAMETERS_KEY,
-  LAUNCH_PARAMETERS_STEP_INPUT,
-} from 'src/shared/docflow.constants';
-import { type FormField, type FormValues } from 'src/shared/form/form-field.type';
-import { getFillableFormFields, parseFormFields } from 'src/shared/form/form-fields.util';
-import { type WorkflowStep } from 'src/shared/workflow/workflow-run.type';
-
-const isPlainRecord = (value: unknown): value is Record<string, unknown> =>
-  typeof value === 'object' && value !== null && !Array.isArray(value);
-
-// The "Launch with parameters" step is the app's workflow action whose input
-// takes the parameters of the run; the fork finds it by the same input.
-export const isLaunchParametersStep = (step: WorkflowStep): boolean => {
-  const input = step.settings?.input;
-
-  if (step.type !== 'LOGIC_FUNCTION' || !isPlainRecord(input)) {
-    return false;
-  }
-
-  return (
-    isPlainRecord(input.logicFunctionInput) &&
-    input.logicFunctionInput.parameters === LAUNCH_PARAMETERS_STEP_INPUT
-  );
-};
-
-export const findLaunchParametersStep = (
-  steps: WorkflowStep[] | null | undefined,
-): WorkflowStep | undefined => (steps ?? []).find(isLaunchParametersStep);
-
-export const parseLaunchFields = (value: unknown): FormField[] =>
-  getFillableFormFields(parseFormFields(value));
-
-// Every parameter goes into the run, an empty one as null: a later step that
-// reads {{launch.contract}} gets an empty value, never the text "undefined".
-export const buildLaunchParameters = ({
-  fields,
-  values,
-}: {
-  fields: FormField[];
-  values: FormValues;
-}): FormValues =>
-  Object.fromEntries(
-    fields.map((field) => {
-      const value = field.name in values ? values[field.name] : field.value;
-
-      return [field.name, value === undefined || value === '' ? null : value];
-    }),
-  );
-
-export const buildLaunchPayload = (parameters: FormValues): Record<string, unknown> => ({
-  [DOCFLOW_LAUNCH_PARAMETERS_KEY]: parameters,
-});
-
-export const readLaunchParameters = (value: unknown): FormValues =>
-  isPlainRecord(value) ? value : {};

package/src/shared/workflow/run-target-record.util.ts

@@ -1,70 +0,0 @@
-import { TRIGGER_STEP_ID } from 'src/shared/docflow.constants';
-import { type WorkflowRunState } from 'src/shared/workflow/workflow-run.type';
-
-const UUID_PATTERN =
-  /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-
-// Task targets Twenty creates for every installation; other objects have
-// their own target fields only when they are set up for tasks.
-const TARGET_FIELD_NAME_BY_OBJECT_NAME: Record<string, string> = {
-  person: 'targetPersonId',
-  company: 'targetCompanyId',
-  opportunity: 'targetOpportunityId',
-};
-
-const readRecord = (value: unknown): Record<string, unknown> | undefined =>
-  typeof value === 'object' && value !== null && !Array.isArray(value)
-    ? (value as Record<string, unknown>)
-    : undefined;
-
-const readUuid = (value: unknown): string | undefined =>
-  typeof value === 'string' && UUID_PATTERN.test(value) ? value : undefined;
-
-// A run started by an event on a deal, or launched from a deal's page, gives
-// its tasks to that deal, so the task shows in the deal's card.
-export const getRunTargetRecord = (
-  state: WorkflowRunState | null | undefined,
-): { targetFieldName: string; recordId: string } | undefined => {
-  const trigger = state?.flow?.trigger;
-  const payload = readRecord(state?.stepInfos?.[TRIGGER_STEP_ID]?.result);
-
-  if (trigger === undefined || trigger === null || payload === undefined) {
-    return undefined;
-  }
-
-  const settings = readRecord(trigger.settings) ?? {};
-  let objectNameSingular: string | undefined;
-  let recordId: string | undefined;
-
-  if (trigger.type === 'DATABASE_EVENT') {
-    const eventName = settings.eventName;
-
-    objectNameSingular =
-      typeof eventName === 'string' ? eventName.split('.')[0] : undefined;
-    recordId =
-      readUuid(payload.recordId) ??
-      readUuid(readRecord(readRecord(payload.properties)?.after)?.id);
-  }
-
-  if (trigger.type === 'MANUAL') {
-    const availability = readRecord(settings.availability);
-
-    objectNameSingular =
-      availability?.type === 'SINGLE_RECORD' &&
-      typeof availability.objectNameSingular === 'string'
-        ? availability.objectNameSingular
-        : typeof settings.objectType === 'string'
-          ? settings.objectType
-          : undefined;
-    recordId = readUuid(readRecord(payload.record)?.id);
-  }
-
-  const targetFieldName =
-    objectNameSingular !== undefined
-      ? TARGET_FIELD_NAME_BY_OBJECT_NAME[objectNameSingular]
-      : undefined;
-
-  return targetFieldName !== undefined && recordId !== undefined
-    ? { targetFieldName, recordId }
-    : undefined;
-};

package/src/shared/workflow/workflow-run.type.ts

@@ -1,35 +0,0 @@
-import { type FormField } from 'src/shared/form/form-field.type';
-
-// The part of a workflow run's state docflow reads. The engine keeps a copy
-// of the version in the run, so a run is read as it was when it started.
-export type WorkflowStepInfo = {
-  status?: string;
-  threadId?: string;
-  result?: unknown;
-  error?: unknown;
-};
-
-export type WorkflowStep = {
-  id: string;
-  name: string;
-  type: string;
-  settings?: { input?: unknown; outputSchema?: unknown } & Record<string, unknown>;
-  nextStepIds?: string[] | null;
-};
-
-export type WorkflowTrigger = {
-  type: string;
-  name?: string | null;
-  nextStepIds?: string[] | null;
-  settings?: Record<string, unknown> | null;
-};
-
-export type WorkflowRunState = {
-  flow?: { trigger?: WorkflowTrigger | null; steps?: WorkflowStep[] | null };
-  stepInfos?: Record<string, WorkflowStepInfo | undefined>;
-};
-
-export type WorkflowFormStep = WorkflowStep & {
-  type: 'FORM';
-  settings: { input: FormField[] };
-};