@haiiro/docuflow 0.0.0-stage → 0.0.2

package/src/server/task-completion.ts

@@ -0,0 +1,100 @@
+import { CoreGraphqlError } from 'src/shared/api/core-graphql.util';
+import { TASK_DONE_STATUS } from 'src/shared/docflow.constants';
+import { isAppEngine } from 'src/shared/engine';
+import { type FormValues } from 'src/shared/form/form-field.type';
+import {
+  findMissingRequiredFields,
+  parseFormFields,
+  parseFormValues,
+} from 'src/shared/form/form-fields.util';
+import { getTask, getWorkflowRun, updateTask, type DocflowTaskRecord } from 'src/server/records';
+import { answerFormStep } from 'src/server/workflow-engine';
+
+export type CompleteTaskResult =
+  | { status: 'DONE' }
+  | { status: 'NOT_FOUND' }
+  | { status: 'MISSING_REQUIRED'; labels: string[] }
+  | { status: 'FAILED'; message: string };
+
+export const isProcessTask = (task: DocflowTaskRecord): boolean =>
+  typeof task.smbWorkflowThreadId === 'string' &&
+  task.smbWorkflowThreadId.length > 0 &&
+  typeof task.smbWorkflowRunId === 'string' &&
+  typeof task.smbWorkflowStepId === 'string';
+
+// Answers the process step of a task as the person completing it. A step
+// that is no longer waiting (answered elsewhere, run stopped) is not an error.
+export const answerStepOfTask = async (
+  task: DocflowTaskRecord,
+  values: FormValues,
+): Promise<CompleteTaskResult | undefined> => {
+  if (!isProcessTask(task) || !isAppEngine()) {
+    return undefined;
+  }
+
+  const run = await getWorkflowRun('person', task.smbWorkflowRunId as string);
+
+  try {
+    const result = await answerFormStep({
+      state: run?.state,
+      stepId: task.smbWorkflowStepId as string,
+      threadId: task.smbWorkflowThreadId as string,
+      values,
+    });
+
+    return result.status === 'MISSING_REQUIRED'
+      ? { status: 'MISSING_REQUIRED', labels: result.labels }
+      : undefined;
+  } catch (error) {
+    const refreshedRun = await getWorkflowRun('person', task.smbWorkflowRunId as string);
+
+    if (refreshedRun?.state?.stepInfos?.[task.smbWorkflowStepId as string]?.status === 'SUCCESS') {
+      return undefined;
+    }
+
+    return {
+      status: 'FAILED',
+      message:
+        error instanceof CoreGraphqlError && error.userMessage !== undefined
+          ? error.userMessage
+          : 'Процесс не принял ответ. Для ответа на шаги процессов нужно право «Рабочие процессы».',
+    };
+  }
+};
+
+export const completeTask = async ({
+  taskId,
+  values,
+}: {
+  taskId: string;
+  values: FormValues | undefined;
+}): Promise<CompleteTaskResult> => {
+  const task = await getTask('person', taskId);
+
+  if (task === undefined) {
+    return { status: 'NOT_FOUND' };
+  }
+
+  const fields = parseFormFields(task.smbFormSchema);
+  const currentValues = values ?? parseFormValues(task.smbFormValues);
+
+  if (values !== undefined) {
+    await updateTask('person', taskId, { smbFormValues: values });
+  }
+
+  const missingFields = findMissingRequiredFields({ fields, values: currentValues });
+
+  if (missingFields.length > 0) {
+    return { status: 'MISSING_REQUIRED', labels: missingFields.map(({ label }) => label) };
+  }
+
+  const stepResult = await answerStepOfTask(task, currentValues);
+
+  if (stepResult !== undefined) {
+    return stepResult;
+  }
+
+  await updateTask('person', taskId, { status: TASK_DONE_STATUS });
+
+  return { status: 'DONE' };
+};

package/src/server/workflow-engine.ts

@@ -0,0 +1,105 @@
+import {
+  ANSWER_TOOL_CALL_MUTATION,
+  callCoreGraphql,
+  RUN_WORKFLOW_VERSION_MUTATION,
+} from 'src/shared/api/core-graphql.util';
+import { type FormValues } from 'src/shared/form/form-field.type';
+import {
+  buildFormStepResponse,
+  findMissingRequiredFields,
+  getFormFieldRole,
+} from 'src/shared/form/form-fields.util';
+import { type WorkflowRunState } from 'src/shared/workflow/workflow-run.type';
+import {
+  getFormStepAssignment,
+  getFormStepFields,
+  isFormStep,
+  resolveFormStepFields,
+} from 'src/shared/workflow/workflow-run.util';
+
+// The two calls the app makes to the workflow engine. Both run as the person
+// behind the current run: Twenty lets only a person with the "Workflows"
+// permission start a version or answer a step of a running process.
+export const runWorkflowVersion = async ({
+  workflowVersionId,
+  workflowRunId,
+  payload,
+}: {
+  workflowVersionId: string;
+  workflowRunId: string;
+  payload: Record<string, unknown>;
+}): Promise<string> => {
+  const data = await callCoreGraphql<{
+    runWorkflowVersion: { workflowRunId: string };
+  }>({
+    query: RUN_WORKFLOW_VERSION_MUTATION,
+    variables: { input: { workflowVersionId, workflowRunId, payload } },
+  });
+
+  return data.runWorkflowVersion.workflowRunId;
+};
+
+export type AnswerFormStepResult =
+  | { status: 'ANSWERED' }
+  | { status: 'NOT_WAITING' }
+  | { status: 'MISSING_REQUIRED'; labels: string[] };
+
+export const answerFormStep = async ({
+  state,
+  stepId,
+  threadId,
+  values,
+}: {
+  state: WorkflowRunState | null | undefined;
+  stepId: string;
+  threadId: string;
+  values: FormValues;
+}): Promise<AnswerFormStepResult> => {
+  const step = state?.flow?.steps?.find((candidate) => candidate.id === stepId);
+  const stepInfo = state?.stepInfos?.[stepId];
+
+  if (
+    step === undefined ||
+    !isFormStep(step) ||
+    stepInfo?.status !== 'PENDING' ||
+    stepInfo.threadId !== threadId
+  ) {
+    return { status: 'NOT_WAITING' };
+  }
+
+  const fields = resolveFormStepFields(
+    getFormStepFields(step),
+    state?.stepInfos,
+  );
+  const missingFields = findMissingRequiredFields({ fields, values });
+
+  if (missingFields.length > 0) {
+    return {
+      status: 'MISSING_REQUIRED',
+      labels: missingFields.map(({ label }) => label),
+    };
+  }
+
+  // The assignee goes out as { id }: the engine then puts the whole member
+  // into the step output, as for a record picked in the form.
+  const { assigneeWorkspaceMemberId } = getFormStepAssignment({
+    fields,
+    now: new Date(),
+  });
+  const response = buildFormStepResponse({
+    fields: fields.map((field) =>
+      getFormFieldRole(field) === 'ASSIGNEE' &&
+      assigneeWorkspaceMemberId !== undefined
+        ? { ...field, value: { id: assigneeWorkspaceMemberId } }
+        : field,
+    ),
+    values,
+  });
+
+  await callCoreGraphql({
+    query: ANSWER_TOOL_CALL_MUTATION,
+    variables: { input: { threadId, toolCallId: stepId, response } },
+  });
+
+  return { status: 'ANSWERED' };
+};

package/src/shared/api/core-graphql.util.ts

@@ -0,0 +1,98 @@
+// Mutations of the workflow engine (run a version, answer a form step) live
+// in the core GraphQL schema, outside the generated record client, so they
+// are sent as plain requests with the token Twenty gives the app.
+type CoreGraphqlResponse<TData> = {
+  data?: TData;
+  errors?: { message?: string; extensions?: { userFriendlyMessage?: unknown } }[];
+};
+
+export class CoreGraphqlError extends Error {
+  constructor(
+    message: string,
+    readonly userMessage: string | undefined,
+  ) {
+    super(message);
+    this.name = 'CoreGraphqlError';
+  }
+}
+
+const readUserMessage = (value: unknown): string | undefined => {
+  if (typeof value === 'string') {
+    return value;
+  }
+
+  if (typeof value === 'object' && value !== null && 'message' in value) {
+    const message = (value as { message: unknown }).message;
+
+    return typeof message === 'string' ? message : undefined;
+  }
+
+  return undefined;
+};
+
+export const callCoreGraphql = async <TData>({
+  query,
+  variables,
+}: {
+  query: string;
+  variables: Record<string, unknown>;
+}): Promise<TData> => {
+  const apiUrl = process.env.TWENTY_API_URL;
+  const token = process.env.TWENTY_APP_ACCESS_TOKEN;
+
+  if (apiUrl === undefined || token === undefined) {
+    throw new CoreGraphqlError(
+      'TWENTY_API_URL or TWENTY_APP_ACCESS_TOKEN is not set',
+      undefined,
+    );
+  }
+
+  const response = await fetch(`${apiUrl.replace(/\/$/, '')}/graphql`, {
+    method: 'POST',
+    headers: {
+      'content-type': 'application/json',
+      authorization: `Bearer ${token}`,
+    },
+    body: JSON.stringify({ query, variables }),
+  });
+
+  const body = (await response.json()) as CoreGraphqlResponse<TData>;
+  const [firstError] = body.errors ?? [];
+
+  if (firstError !== undefined || body.data === undefined) {
+    throw new CoreGraphqlError(
+      firstError?.message ?? `GraphQL request failed with ${response.status}`,
+      readUserMessage(firstError?.extensions?.userFriendlyMessage),
+    );
+  }
+
+  return body.data;
+};
+
+export const RUN_WORKFLOW_VERSION_MUTATION = `mutation RunWorkflowVersion($input: RunWorkflowVersionInput!) {
+  runWorkflowVersion(input: $input) { workflowRunId }
+}`;
+
+export const ANSWER_TOOL_CALL_MUTATION = `mutation AnswerToolCall($input: AnswerToolCallInput!) {
+  answerToolCall(input: $input) { streamId }
+}`;
+
+export const UPDATE_WORKFLOW_VERSION_STEP_MUTATION = `mutation UpdateWorkflowVersionStep($input: UpdateWorkflowVersionStepInput!) {
+  updateWorkflowVersionStep(input: $input) { id }
+}`;
+
+export const CREATE_WORKFLOW_VERSION_STEP_MUTATION = `mutation CreateWorkflowVersionStep($input: CreateWorkflowVersionStepInput!) {
+  createWorkflowVersionStep(input: $input) { __typename }
+}`;
+
+export const DELETE_WORKFLOW_VERSION_STEP_MUTATION = `mutation DeleteWorkflowVersionStep($input: DeleteWorkflowVersionStepInput!) {
+  deleteWorkflowVersionStep(input: $input) { __typename }
+}`;
+
+export const UPDATE_WORKFLOW_VERSION_TRIGGER_MUTATION = `mutation UpdateWorkflowVersionTrigger($input: UpdateWorkflowVersionTriggerInput!) {
+  updateWorkflowVersionTrigger(input: $input) { __typename }
+}`;
+
+export const CREATE_DRAFT_FROM_WORKFLOW_VERSION_MUTATION = `mutation CreateDraftFromWorkflowVersion($input: CreateDraftFromWorkflowVersionInput!) {
+  createDraftFromWorkflowVersion(input: $input) { id }
+}`;

package/src/shared/api/object-summaries.ts

@@ -0,0 +1,79 @@
+import { MetadataApiClient } from 'twenty-client-sdk/metadata';
+
+export type ObjectSummary = {
+  nameSingular: string;
+  namePlural: string;
+  labelSingular: string;
+  labelFieldName?: string;
+};
+
+const OBJECTS_PAGE_SIZE = 100;
+
+// Names and label fields of the workspace objects, read once per run. The
+// metadata API cannot filter by name, so it is paged through.
+export const getObjectSummaries = async (): Promise<Map<string, ObjectSummary>> => {
+  const client = new MetadataApiClient();
+  const summaries = new Map<string, ObjectSummary>();
+  let after: string | undefined;
+
+  do {
+    const { objects } = await client.query({
+      objects: {
+        __args: {
+          paging: { first: OBJECTS_PAGE_SIZE, ...(after !== undefined ? { after } : {}) },
+          filter: {},
+        },
+        pageInfo: { hasNextPage: true, endCursor: true },
+        edges: {
+          node: {
+            nameSingular: true,
+            namePlural: true,
+            labelSingular: true,
+            labelIdentifierFieldMetadataId: true,
+            fieldsList: { id: true, name: true },
+          },
+        },
+      },
+    });
+
+    for (const { node } of objects.edges) {
+      summaries.set(node.nameSingular, {
+        nameSingular: node.nameSingular,
+        namePlural: node.namePlural,
+        labelSingular: node.labelSingular,
+        labelFieldName: node.fieldsList?.find(
+          (field) => field.id === node.labelIdentifierFieldMetadataId,
+        )?.name,
+      });
+    }
+
+    after =
+      objects.pageInfo.hasNextPage === true
+        ? (objects.pageInfo.endCursor ?? undefined)
+        : undefined;
+  } while (after !== undefined);
+
+  return summaries;
+};
+
+export type SelectOption = { value: string; label: string };
+
+// A SELECT field of a form takes its options from a field of an object
+// (settings.selectedFieldId), like the standard form step does.
+export const getFieldOptions = async (fieldId: string): Promise<SelectOption[]> => {
+  const { fields } = await new MetadataApiClient().query({
+    fields: {
+      __args: { filter: { id: { eq: fieldId } }, paging: { first: 1 } },
+      edges: { node: { options: true } },
+    },
+  });
+  const options = fields.edges[0]?.node.options;
+
+  return Array.isArray(options)
+    ? options.flatMap((option: unknown) => {
+        const { value, label } = (option ?? {}) as Record<string, unknown>;
+
+        return typeof value === 'string' && typeof label === 'string' ? [{ value, label }] : [];
+      })
+    : [];
+};

package/src/shared/api/rest-filter.util.ts

@@ -0,0 +1,37 @@
+// Filters of the Twenty REST API: `and(field[eq]:'value',or(...))`. The
+// parser counts brackets and quotes without escaping, so text a person types
+// loses those characters before it becomes part of a filter.
+const UNSAFE_FILTER_CHARACTERS = /[()[\]'",]/g;
+
+export const sanitizeFilterText = (text: string): string =>
+  text.replace(UNSAFE_FILTER_CHARACTERS, ' ').trim();
+
+const quote = (value: string): string => `'${sanitizeFilterText(value)}'`;
+
+export const restEq = (field: string, value: string): string =>
+  `${field}[eq]:${quote(value)}`;
+
+export const restNeq = (field: string, value: string): string =>
+  `${field}[neq]:${quote(value)}`;
+
+export const restIsNull = (field: string): string => `${field}[is]:NULL`;
+
+export const restLt = (field: string, value: string): string =>
+  `${field}[lt]:${quote(value)}`;
+
+export const restIn = (field: string, values: string[]): string =>
+  `${field}[in]:[${values.map((value) => `"${sanitizeFilterText(value)}"`).join(',')}]`;
+
+export const restIlike = (field: string, text: string): string =>
+  `${field}[ilike]:'%${sanitizeFilterText(text)}%'`;
+
+export const restAnd = (...conditions: (string | undefined)[]): string | undefined => {
+  const present = conditions.filter(
+    (condition): condition is string => condition !== undefined,
+  );
+
+  return present.length === 0 ? undefined : `and(${present.join(',')})`;
+};
+
+export const restOr = (...conditions: string[]): string =>
+  `or(${conditions.join(',')})`;

package/src/shared/api/rest-response.util.ts

@@ -0,0 +1,43 @@
+export type RestPageInfo = {
+  hasNextPage?: boolean;
+  endCursor?: string | null;
+};
+
+export type RestList<TRecord> = {
+  records: TRecord[];
+  pageInfo: RestPageInfo;
+};
+
+type RestEnvelope = {
+  data?: Record<string, unknown>;
+  pageInfo?: RestPageInfo;
+};
+
+// Every REST answer carries its records under one key of `data`
+// (`tasks`, `createTask`, `updateTask`...): the shape is read once here.
+const readDataValue = (response: unknown): unknown => {
+  const data = (response as RestEnvelope | null)?.data;
+
+  if (typeof data !== 'object' || data === null) {
+    return undefined;
+  }
+
+  return Object.values(data)[0];
+};
+
+export const readRestList = <TRecord>(response: unknown): RestList<TRecord> => {
+  const value = readDataValue(response);
+
+  return {
+    records: Array.isArray(value) ? (value as TRecord[]) : [],
+    pageInfo: (response as RestEnvelope | null)?.pageInfo ?? {},
+  };
+};
+
+export const readRestRecord = <TRecord>(response: unknown): TRecord | undefined => {
+  const value = readDataValue(response);
+
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+    ? (value as TRecord)
+    : undefined;
+};

package/src/shared/bitrix/bitrix-client.ts

@@ -0,0 +1,114 @@
+import { type BitrixGrant, type BitrixPortal } from 'src/shared/bitrix/bitrix.type';
+import { BITRIX_OAUTH_TOKEN_URL, parseBitrixGrant } from 'src/shared/bitrix/bitrix.util';
+
+const TOKEN_REFRESH_MARGIN_MS = 60_000;
+
+export class BitrixError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'BitrixError';
+  }
+}
+
+const getClientCredentials = (): { clientId: string; clientSecret: string } => {
+  const clientId = process.env.BITRIX_CLIENT_ID;
+  const clientSecret = process.env.BITRIX_CLIENT_SECRET;
+
+  if (!clientId || !clientSecret) {
+    throw new BitrixError('BITRIX_CLIENT_ID and BITRIX_CLIENT_SECRET are not set');
+  }
+
+  return { clientId, clientSecret };
+};
+
+export const isBitrixConfigured = (): boolean =>
+  Boolean(process.env.BITRIX_CLIENT_ID) && Boolean(process.env.BITRIX_CLIENT_SECRET);
+
+// The one proof a portal request has to pass: its refresh token is exchanged
+// with the app's client secret, and the portal id, REST address and tokens
+// are taken from the answer of oauth.bitrix.info, not from the request.
+export const exchangeBitrixRefreshToken = async (
+  refreshToken: string,
+): Promise<BitrixGrant> => {
+  const { clientId, clientSecret } = getClientCredentials();
+  const url = new URL(BITRIX_OAUTH_TOKEN_URL);
+
+  url.searchParams.set('grant_type', 'refresh_token');
+  url.searchParams.set('client_id', clientId);
+  url.searchParams.set('client_secret', clientSecret);
+  url.searchParams.set('refresh_token', refreshToken);
+
+  let response: Response;
+
+  try {
+    response = await fetch(url, { redirect: 'error' });
+  } catch {
+    // The URL carries the client secret, so the original error is not kept.
+    throw new BitrixError('oauth.bitrix.info is unreachable');
+  }
+
+  const grant = parseBitrixGrant(await response.json().catch(() => null), Date.now());
+
+  if (!response.ok || grant === undefined) {
+    throw new BitrixError(`Bitrix24 did not accept the refresh token (HTTP ${response.status})`);
+  }
+
+  return grant;
+};
+
+export const withFreshBitrixToken = async (
+  portal: BitrixPortal,
+): Promise<{ portal: BitrixPortal; isRefreshed: boolean }> => {
+  if (portal.expiresAt - TOKEN_REFRESH_MARGIN_MS > Date.now()) {
+    return { portal, isRefreshed: false };
+  }
+
+  const grant = await exchangeBitrixRefreshToken(portal.refreshToken);
+
+  if (grant.memberId !== portal.memberId) {
+    throw new BitrixError('The refreshed token belongs to another portal');
+  }
+
+  return {
+    portal: {
+      ...portal,
+      accessToken: grant.accessToken,
+      refreshToken: grant.refreshToken,
+      expiresAt: grant.expiresAt,
+      restEndpoint: grant.restEndpoint,
+    },
+    isRefreshed: true,
+  };
+};
+
+export const callBitrix = async <TResult>({
+  restEndpoint,
+  accessToken,
+  method,
+  params,
+}: {
+  restEndpoint: string;
+  accessToken: string;
+  method: string;
+  params: Record<string, unknown>;
+}): Promise<TResult> => {
+  const response = await fetch(`${restEndpoint}${method}.json`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ ...params, auth: accessToken }),
+    redirect: 'error',
+  });
+  const body = (await response.json().catch(() => null)) as {
+    result?: TResult;
+    error?: string;
+    error_description?: string;
+  } | null;
+
+  if (!response.ok || body === null || body.error !== undefined) {
+    throw new BitrixError(
+      `Bitrix24 ${method} failed: ${body?.error ?? response.status} ${body?.error_description ?? ''}`.trim(),
+    );
+  }
+
+  return body.result as TResult;
+};

package/src/shared/bitrix/bitrix.type.ts

@@ -0,0 +1,25 @@
+// A Bitrix24 portal linked to this workspace. Kept in the app's key-value
+// store, never in records: it holds tokens.
+export type BitrixPortal = {
+  memberId: string;
+  portalDomain: string;
+  restEndpoint: string;
+  accessToken: string;
+  refreshToken: string;
+  expiresAt: number;
+  // Sent by the portal with every event; proves an event comes from it.
+  applicationToken?: string;
+};
+
+export type BitrixGrant = Omit<BitrixPortal, 'applicationToken'> & {
+  bitrixUserId?: string;
+};
+
+export type BitrixRequest = {
+  authId?: string;
+  refreshId?: string;
+  memberId?: string;
+  event?: string;
+  applicationToken?: string;
+  domain?: string;
+};