@twentyhq/call-recorder 1.0.0

package/src/logic-functions/flows/handle-recall-webhook.util.ts

@@ -0,0 +1,672 @@
+import { isNonEmptyArray, isNull, isUndefined } from '@sniptt/guards';
+import { type CoreApiClient } from 'twenty-client-sdk/core';
+
+import { CallRecordingStatus } from 'src/logic-functions/constants/call-recording-status';
+import { type FilesFieldValue } from 'src/logic-functions/types/files-field-value.type';
+import { buildFailedTranscriptMarker } from 'src/logic-functions/domain/build-failed-transcript-marker.util';
+import { buildTranscriptFailureReason } from 'src/logic-functions/domain/build-transcript-failure-reason.util';
+import { downloadTranscript } from 'src/logic-functions/flows/download-transcript.util';
+import { extractRecallBotConvergence } from 'src/logic-functions/recall-api/extract-recall-bot-convergence.util';
+import { getRecallBot } from 'src/logic-functions/recall-api/get-recall-bot.util';
+import { getString } from 'src/logic-functions/utils/get-string.util';
+import { ingestCallRecordingMedia } from 'src/logic-functions/flows/ingest-call-recording-media.util';
+import { isCallRecordingStatusDowngrade } from 'src/logic-functions/domain/is-call-recording-status-downgrade.util';
+import { isRecallRecordingDoneSignal } from 'src/logic-functions/domain/is-recall-recording-done-signal.util';
+import { mapRecallStatusCodeToCallRecordingStatus } from 'src/logic-functions/domain/map-recall-status-code-to-call-recording-status.util';
+import {
+  parseRecallWebhookEvent,
+  type RecallWebhookBody,
+  type RecallWebhookEvent,
+} from 'src/logic-functions/recall-api/parse-recall-webhook-event.util';
+import { parseTranscriptMarker } from 'src/logic-functions/domain/parse-transcript-marker.util';
+import { persistCallRecordingProgress } from 'src/logic-functions/flows/persist-call-recording-progress.util';
+import { reconcileCallRecordingTranscriptArtifact } from 'src/logic-functions/flows/reconcile-call-recording-transcript-artifact.util';
+import { updateCallRecording } from 'src/logic-functions/data/update-call-recording.util';
+import { type CallRecordingUpdateFields } from 'src/logic-functions/types/call-recording-update-fields.type';
+
+type MatchedCallRecording = {
+  id: string;
+  status?: string;
+  startedAt?: string;
+  endedAt?: string;
+  externalRecordingId?: string;
+  transcript?: unknown;
+  audio?: FilesFieldValue;
+  video?: FilesFieldValue;
+};
+
+type ExternalRecordingIdResolution = {
+  externalRecordingId: string | undefined;
+  providerLookupFailed: boolean;
+};
+
+type RecallWebhookHandlerResult =
+  | {
+      status: 'updated';
+      callRecordingId: string;
+      event: string;
+      callRecordingStatus: string;
+    }
+  | {
+      status: 'updated';
+      callRecordingId: string;
+      event: string;
+      transcriptOutcome: 'FILLED' | 'FAILED';
+    }
+  | {
+      status: 'skipped';
+      event: string | null;
+      reason: string;
+    };
+
+export const handleRecallWebhook = async ({
+  client,
+  body,
+}: {
+  client: CoreApiClient;
+  body: RecallWebhookBody;
+}): Promise<RecallWebhookHandlerResult> => {
+  const webhookEvent = parseRecallWebhookEvent(body);
+
+  if (isUndefined(webhookEvent)) {
+    return {
+      status: 'skipped',
+      event: null,
+      reason: 'missing event type',
+    };
+  }
+
+  const { event } = webhookEvent;
+
+  if (event === 'transcript.done' || event === 'transcript.failed') {
+    return handleRecallTranscriptEvent({ client, webhookEvent, event });
+  }
+
+  return handleRecallStatusEvent({ client, webhookEvent });
+};
+
+const handleRecallStatusEvent = async ({
+  client,
+  webhookEvent,
+}: {
+  client: CoreApiClient;
+  webhookEvent: RecallWebhookEvent;
+}): Promise<RecallWebhookHandlerResult> => {
+  const { event, statusCode } = webhookEvent;
+  const callRecordingStatus = mapRecallEventToCallRecordingStatus({
+    event,
+    statusCode,
+  });
+
+  if (isUndefined(callRecordingStatus)) {
+    return {
+      status: 'skipped',
+      event,
+      reason: `unsupported Recall event status ${statusCode ?? event}`,
+    };
+  }
+
+  const callRecording = await findMatchingCallRecording({
+    client,
+    webhookEvent,
+  });
+
+  if (isUndefined(callRecording)) {
+    return {
+      status: 'skipped',
+      event,
+      reason: 'no matching call recording',
+    };
+  }
+
+  if (
+    isCallRecordingStatusDowngrade({
+      fromStatus: callRecording.status,
+      toStatus: callRecordingStatus,
+    })
+  ) {
+    return {
+      status: 'skipped',
+      event,
+      reason: `stale status event (${callRecording.status} -> ${callRecordingStatus})`,
+    };
+  }
+
+  const updateData: CallRecordingUpdateFields = {
+    ...(isUndefined(webhookEvent.externalBotId)
+      ? {}
+      : { externalBotId: webhookEvent.externalBotId }),
+    ...buildExternalRecordingIdUpdate(webhookEvent),
+    ...buildCallRecordingStatusUpdate({
+      reason: getRecallWebhookFailureReason(webhookEvent),
+      status: callRecordingStatus,
+    }),
+    ...buildRecordingTimestampsUpdate({ webhookEvent, callRecording }),
+  };
+
+  if (isRecallRecordingDoneSignal({ event, statusCode })) {
+    const externalRecordingIdResolution = await resolveExternalRecordingId({
+      callRecording,
+      webhookEvent,
+    });
+
+    Object.assign(
+      updateData,
+      await buildTranscriptArtifactUpdate({
+        callRecording,
+        externalRecordingId: externalRecordingIdResolution.externalRecordingId,
+      }),
+    );
+
+    Object.assign(
+      updateData,
+      await buildMediaIngestionUpdate({
+        callRecording,
+        externalRecordingId: externalRecordingIdResolution.externalRecordingId,
+      }),
+    );
+
+    const terminalArtifactGateFailureUpdate =
+      buildTerminalArtifactGateFailureUpdate({
+        callRecording,
+        providerLookupFailed:
+          externalRecordingIdResolution.providerLookupFailed,
+        updateData,
+        webhookEvent,
+      });
+
+    if (!isUndefined(terminalArtifactGateFailureUpdate)) {
+      Object.assign(updateData, terminalArtifactGateFailureUpdate);
+    }
+  }
+
+  const { completesIngestion } = await persistCallRecordingProgress(client, {
+    id: callRecording.id,
+    current: callRecording,
+    updateData,
+  });
+
+  return {
+    status: 'updated',
+    event,
+    callRecordingId: callRecording.id,
+    callRecordingStatus: completesIngestion
+      ? CallRecordingStatus.COMPLETED
+      : (updateData.status ?? callRecordingStatus),
+  };
+};
+
+const findMatchingCallRecording = async ({
+  client,
+  webhookEvent,
+}: {
+  client: CoreApiClient;
+  webhookEvent: RecallWebhookEvent;
+}): Promise<MatchedCallRecording | undefined> => {
+  if (!isUndefined(webhookEvent.callRecordingIdFromMetadata)) {
+    return findCallRecordingByFilter(client, {
+      id: { eq: webhookEvent.callRecordingIdFromMetadata },
+    });
+  }
+
+  if (isUndefined(webhookEvent.externalBotId)) {
+    return undefined;
+  }
+
+  return findCallRecordingByFilter(client, {
+    externalBotId: { eq: webhookEvent.externalBotId },
+  });
+};
+
+const findCallRecordingByFilter = async (
+  client: CoreApiClient,
+  filter: Record<string, unknown>,
+): Promise<MatchedCallRecording | undefined> => {
+  const queryResult = await client.query({
+    callRecordings: {
+      __args: {
+        filter,
+        first: 1,
+      },
+      edges: {
+        node: {
+          id: true,
+          status: true,
+          startedAt: true,
+          endedAt: true,
+          externalRecordingId: true,
+          transcript: true,
+          audio: { fileId: true },
+          video: { fileId: true },
+        },
+      },
+    },
+  });
+
+  const node = queryResult.callRecordings?.edges?.[0]?.node;
+
+  if (isUndefined(node) || isNull(node)) {
+    return undefined;
+  }
+
+  return {
+    id: node.id,
+    status: getString(node.status),
+    startedAt: getString(node.startedAt),
+    endedAt: getString(node.endedAt),
+    externalRecordingId: getString(node.externalRecordingId),
+    transcript: node.transcript ?? undefined,
+    audio: node.audio ?? undefined,
+    video: node.video ?? undefined,
+  };
+};
+
+const mapRecallEventToCallRecordingStatus = ({
+  event,
+  statusCode,
+}: {
+  event: string;
+  statusCode: string | undefined;
+}): CallRecordingStatus | undefined => {
+  if (event === 'recording.done') {
+    return CallRecordingStatus.PROCESSING;
+  }
+
+  if (event === 'recording.failed') {
+    return CallRecordingStatus.FAILED;
+  }
+
+  return mapRecallStatusCodeToCallRecordingStatus(statusCode);
+};
+
+const buildRecordingTimestampsUpdate = ({
+  webhookEvent,
+  callRecording,
+}: {
+  webhookEvent: RecallWebhookEvent;
+  callRecording: MatchedCallRecording;
+}): { startedAt?: string; endedAt?: string } => {
+  const { event, statusCode, statusTimestamp } = webhookEvent;
+
+  const impliesRecordingStarted = statusCode === 'in_call_recording';
+  const impliesRecordingEnded =
+    event === 'recording.done' ||
+    statusCode === 'call_ended' ||
+    statusCode === 'done';
+
+  const startedAt =
+    webhookEvent.recordingStartedAt ??
+    (impliesRecordingStarted ? statusTimestamp : undefined);
+  const endedAt =
+    webhookEvent.recordingEndedAt ??
+    (impliesRecordingEnded ? statusTimestamp : undefined);
+
+  return {
+    ...(!isUndefined(startedAt) && isUndefined(callRecording.startedAt)
+      ? { startedAt }
+      : {}),
+    ...(!isUndefined(endedAt) && isUndefined(callRecording.endedAt)
+      ? { endedAt }
+      : {}),
+  };
+};
+
+const buildExternalRecordingIdUpdate = (
+  webhookEvent: RecallWebhookEvent,
+): { externalRecordingId?: string } =>
+  isUndefined(webhookEvent.externalRecordingId)
+    ? {}
+    : { externalRecordingId: webhookEvent.externalRecordingId };
+
+type NonFailedCallRecordingStatus = Exclude<
+  CallRecordingStatus,
+  CallRecordingStatus.FAILED
+>;
+
+type CallRecordingStatusUpdate =
+  | {
+      status: NonFailedCallRecordingStatus;
+    }
+  | {
+      status: CallRecordingStatus.FAILED;
+      callRecorderFailureReason: string;
+    };
+
+type TerminalArtifactGateFailureUpdate = {
+  status: CallRecordingStatus.FAILED;
+  callRecorderFailureReason: string;
+};
+
+const buildCallRecordingStatusUpdate = ({
+  reason,
+  status,
+}: {
+  reason: string;
+  status: CallRecordingStatus;
+}): CallRecordingStatusUpdate => {
+  if (status === CallRecordingStatus.FAILED) {
+    return { status, callRecorderFailureReason: reason };
+  }
+
+  return { status };
+};
+
+const buildTerminalArtifactGateFailureUpdate = ({
+  callRecording,
+  providerLookupFailed,
+  updateData,
+  webhookEvent,
+}: {
+  callRecording: MatchedCallRecording;
+  providerLookupFailed: boolean;
+  updateData: CallRecordingUpdateFields;
+  webhookEvent: RecallWebhookEvent;
+}): TerminalArtifactGateFailureUpdate | undefined => {
+  if (updateData.status === CallRecordingStatus.FAILED) {
+    return isUndefined(updateData.callRecorderFailureReason)
+      ? {
+          status: CallRecordingStatus.FAILED,
+          callRecorderFailureReason:
+            getRecallWebhookFailureReason(webhookEvent),
+        }
+      : undefined;
+  }
+
+  if (
+    providerLookupFailed ||
+    hasRecordingArtifactPath({ callRecording, updateData })
+  ) {
+    return undefined;
+  }
+
+  return {
+    status: CallRecordingStatus.FAILED,
+    callRecorderFailureReason: 'recording_artifacts_unavailable',
+  };
+};
+
+const getRecallWebhookFailureReason = ({
+  event,
+  statusCode,
+}: RecallWebhookEvent): string => statusCode ?? event;
+
+const hasRecordingArtifactPath = ({
+  callRecording,
+  updateData,
+}: {
+  callRecording: MatchedCallRecording;
+  updateData: CallRecordingUpdateFields;
+}): boolean => {
+  return (
+    !isUndefined(
+      updateData.externalRecordingId ?? callRecording.externalRecordingId,
+    ) ||
+    isNonEmptyArray(updateData.audio ?? callRecording.audio) ||
+    isNonEmptyArray(updateData.video ?? callRecording.video) ||
+    hasReachableTranscript(updateData.transcript ?? callRecording.transcript)
+  );
+};
+
+const hasReachableTranscript = (transcript: unknown): boolean => {
+  if (isNull(transcript) || isUndefined(transcript)) {
+    return false;
+  }
+
+  const marker = parseTranscriptMarker(transcript);
+
+  return isUndefined(marker) || marker.status === 'PENDING';
+};
+
+const isTranscriptUnset = (callRecording: MatchedCallRecording): boolean =>
+  isUndefined(callRecording.transcript);
+
+const buildMediaIngestionUpdate = async ({
+  callRecording,
+  externalRecordingId,
+}: {
+  callRecording: MatchedCallRecording;
+  externalRecordingId: string | undefined;
+}): Promise<Pick<CallRecordingUpdateFields, 'audio' | 'video'>> => {
+  const hasAudio = isNonEmptyArray(callRecording.audio);
+  const hasVideo = isNonEmptyArray(callRecording.video);
+
+  if (hasAudio && hasVideo) {
+    return {};
+  }
+
+  if (isUndefined(externalRecordingId)) {
+    console.warn(
+      `[call-recorder] cannot ingest media for call recording ${callRecording.id}: no Recall recording id available`,
+    );
+
+    return {};
+  }
+
+  return ingestCallRecordingMedia({
+    callRecordingId: callRecording.id,
+    externalRecordingId,
+    hasAudio,
+    hasVideo,
+  });
+};
+
+const buildTranscriptArtifactUpdate = async ({
+  callRecording,
+  externalRecordingId,
+}: {
+  callRecording: MatchedCallRecording;
+  externalRecordingId: string | undefined;
+}): Promise<CallRecordingUpdateFields> => {
+  if (isUndefined(externalRecordingId)) {
+    console.warn(
+      `[call-recorder] cannot reconcile transcript for call recording ${callRecording.id}: no Recall recording id available`,
+    );
+
+    return {};
+  }
+
+  const transcriptArtifactResult =
+    await reconcileCallRecordingTranscriptArtifact({
+      callRecordingId: callRecording.id,
+      currentStatus: callRecording.status,
+      externalRecordingId,
+      requestedAt: new Date().toISOString(),
+      transcript: callRecording.transcript,
+    });
+
+  return {
+    ...(isUndefined(callRecording.externalRecordingId)
+      ? { externalRecordingId }
+      : {}),
+    ...transcriptArtifactResult.updateData,
+  };
+};
+
+const resolveExternalRecordingId = async ({
+  callRecording,
+  webhookEvent,
+}: {
+  callRecording: MatchedCallRecording;
+  webhookEvent: RecallWebhookEvent;
+}): Promise<ExternalRecordingIdResolution> => {
+  const externalRecordingId =
+    webhookEvent.externalRecordingId ?? callRecording.externalRecordingId;
+
+  if (!isUndefined(externalRecordingId)) {
+    return { externalRecordingId, providerLookupFailed: false };
+  }
+
+  if (isUndefined(webhookEvent.externalBotId)) {
+    return { externalRecordingId: undefined, providerLookupFailed: false };
+  }
+
+  return fetchExternalRecordingIdFromRecallBot(webhookEvent.externalBotId);
+};
+
+const fetchExternalRecordingIdFromRecallBot = async (
+  externalBotId: string,
+): Promise<ExternalRecordingIdResolution> => {
+  const botResult = await getRecallBot({ externalBotId });
+
+  if (!botResult.ok) {
+    console.warn(
+      `[call-recorder] failed to fetch Recall bot ${externalBotId} while resolving a recording id: ${botResult.errorMessage}`,
+    );
+
+    return { externalRecordingId: undefined, providerLookupFailed: true };
+  }
+
+  return {
+    externalRecordingId: extractRecallBotConvergence(botResult.bot)
+      .externalRecordingId,
+    providerLookupFailed: false,
+  };
+};
+
+const handleRecallTranscriptEvent = async ({
+  client,
+  webhookEvent,
+  event,
+}: {
+  client: CoreApiClient;
+  webhookEvent: RecallWebhookEvent;
+  event: 'transcript.done' | 'transcript.failed';
+}): Promise<RecallWebhookHandlerResult> => {
+  const callRecording = await findMatchingCallRecording({
+    client,
+    webhookEvent,
+  });
+
+  if (isUndefined(callRecording)) {
+    return {
+      status: 'skipped',
+      event,
+      reason: 'no matching call recording',
+    };
+  }
+
+  const { transcriptId } = webhookEvent;
+
+  if (event === 'transcript.failed') {
+    return applyTranscriptFailure({
+      client,
+      callRecording,
+      event,
+      transcriptId,
+      subCode: webhookEvent.transcriptFailureSubCode ?? null,
+    });
+  }
+
+  if (isUndefined(transcriptId)) {
+    return {
+      status: 'skipped',
+      event,
+      reason: 'missing transcript id',
+    };
+  }
+
+  const downloadResult = await downloadTranscript({ transcriptId });
+
+  switch (downloadResult.outcome) {
+    case 'filled': {
+      const updateData: CallRecordingUpdateFields = {
+        transcript: downloadResult.content as Record<string, unknown>,
+        ...(isUndefined(callRecording.externalRecordingId)
+          ? buildExternalRecordingIdUpdate(webhookEvent)
+          : {}),
+      };
+
+      await persistCallRecordingProgress(client, {
+        id: callRecording.id,
+        current: callRecording,
+        updateData,
+      });
+
+      return {
+        status: 'updated',
+        event,
+        callRecordingId: callRecording.id,
+        transcriptOutcome: 'FILLED',
+      };
+    }
+    case 'failed':
+      return applyTranscriptFailure({
+        client,
+        callRecording,
+        event,
+        transcriptId,
+        subCode: downloadResult.subCode,
+      });
+    case 'pending':
+    case 'error': {
+      // 200-acked either way, Svix never redelivers; the cron re-check retries this.
+      const reason =
+        downloadResult.outcome === 'pending'
+          ? 'transcript not downloadable yet'
+          : downloadResult.errorMessage;
+
+      console.warn(
+        `[call-recorder] could not fill transcript for call recording ${callRecording.id}: ${reason}`,
+      );
+
+      return {
+        status: 'skipped',
+        event,
+        reason,
+      };
+    }
+  }
+};
+
+const applyTranscriptFailure = async ({
+  client,
+  callRecording,
+  event,
+  transcriptId,
+  subCode,
+}: {
+  client: CoreApiClient;
+  callRecording: MatchedCallRecording;
+  event: string;
+  transcriptId: string | undefined;
+  subCode: string | null;
+}): Promise<RecallWebhookHandlerResult> => {
+  const existingMarker = parseTranscriptMarker(callRecording.transcript);
+
+  if (!isTranscriptUnset(callRecording) && isUndefined(existingMarker)) {
+    return {
+      status: 'skipped',
+      event,
+      reason: 'transcript already filled',
+    };
+  }
+
+  console.warn(
+    `[call-recorder] transcript failed for call recording ${callRecording.id}${isNull(subCode) ? '' : ` (${subCode})`}`,
+  );
+
+  await updateCallRecording(client, {
+    id: callRecording.id,
+    data: {
+      transcript: buildFailedTranscriptMarker({
+        recallTranscriptId:
+          transcriptId ?? existingMarker?.recallTranscriptId ?? null,
+        subCode,
+      }),
+      callRecorderFailureReason: buildTranscriptFailureReason(subCode),
+      ...(isCallRecordingStatusDowngrade({
+        fromStatus: callRecording.status,
+        toStatus: CallRecordingStatus.FAILED,
+      })
+        ? {}
+        : { status: CallRecordingStatus.FAILED }),
+    },
+  });
+
+  return {
+    status: 'updated',
+    event,
+    callRecordingId: callRecording.id,
+    transcriptOutcome: 'FAILED',
+  };
+};