@twentyhq/call-recorder 1.0.0

package/src/logic-functions/flows/heal-call-recordings-missing-bot.util.ts

@@ -0,0 +1,82 @@
+import { isUndefined } from '@sniptt/guards';
+import { type CoreApiClient } from 'twenty-client-sdk/core';
+
+import { type CalendarEventRecord } from 'src/logic-functions/types/calendar-event-record.type';
+import { ensureCallRecorder } from 'src/logic-functions/flows/ensure-call-recorder.util';
+import { fetchCalendarEventsByIds } from 'src/logic-functions/data/fetch-calendar-events-by-ids.util';
+import { findOpenScheduledCallRecordings } from 'src/logic-functions/data/find-open-scheduled-call-recordings.util';
+import { getUniqueSortedIds } from 'src/logic-functions/utils/get-unique-sorted-ids.util';
+
+export type HealCallRecordingsMissingBotResult = {
+  scheduledCallRecordingIds: string[];
+};
+
+// Closes the create-winner crash gap: a run that inserted the row but died before POSTing leaves a botless recording, and the cron is the single writer that re-POSTs it.
+export const healCallRecordingsMissingBot = async ({
+  client,
+  now,
+}: {
+  client: CoreApiClient;
+  now: Date;
+}): Promise<HealCallRecordingsMissingBotResult> => {
+  const botlessCallRecordings = (
+    await findOpenScheduledCallRecordings(client)
+  ).filter((callRecording) => isUndefined(callRecording.externalBotId));
+
+  if (botlessCallRecordings.length === 0) {
+    return { scheduledCallRecordingIds: [] };
+  }
+
+  const calendarEventsById = new Map(
+    (
+      await fetchCalendarEventsByIds(
+        client,
+        getUniqueSortedIds(
+          botlessCallRecordings.map(
+            (callRecording) => callRecording.calendarEventId,
+          ),
+        ),
+      )
+    ).map((calendarEvent) => [calendarEvent.id, calendarEvent]),
+  );
+  const scheduledCallRecordingIds: string[] = [];
+
+  for (const callRecording of botlessCallRecordings) {
+    const calendarEvent = isUndefined(callRecording.calendarEventId)
+      ? undefined
+      : calendarEventsById.get(callRecording.calendarEventId);
+
+    if (isUndefined(calendarEvent) || hasMeetingEnded({ calendarEvent, now })) {
+      continue;
+    }
+
+    const didScheduleCallRecorder = await ensureCallRecorder(client, {
+      callRecording,
+      calendarEvent,
+    });
+
+    if (didScheduleCallRecorder) {
+      scheduledCallRecordingIds.push(callRecording.id);
+    }
+  }
+
+  return { scheduledCallRecordingIds };
+};
+
+const hasMeetingEnded = ({
+  calendarEvent,
+  now,
+}: {
+  calendarEvent: CalendarEventRecord;
+  now: Date;
+}): boolean => {
+  const reference = calendarEvent.endsAt ?? calendarEvent.startsAt;
+
+  if (isUndefined(reference)) {
+    return false;
+  }
+
+  const referenceTime = new Date(reference).getTime();
+
+  return !Number.isNaN(referenceTime) && referenceTime <= now.getTime();
+};

package/src/logic-functions/flows/ingest-call-recording-media.util.ts

@@ -0,0 +1,128 @@
+import { isUndefined } from '@sniptt/guards';
+import { MetadataApiClient } from 'twenty-client-sdk/metadata';
+
+import { CALL_RECORDING_AUDIO_FIELD_UNIVERSAL_IDENTIFIER } from 'src/constants/call-recording-audio-field-universal-identifier';
+import { CALL_RECORDING_VIDEO_FIELD_UNIVERSAL_IDENTIFIER } from 'src/constants/call-recording-video-field-universal-identifier';
+import { extractRecallMediaUrls } from 'src/logic-functions/recall-api/extract-recall-media-urls.util';
+import { getRecallRecording } from 'src/logic-functions/recall-api/get-recall-recording.util';
+import { type CallRecordingMediaFile } from 'src/logic-functions/types/call-recording-media-file.type';
+import { type CallRecordingUpdateFields } from 'src/logic-functions/types/call-recording-update-fields.type';
+
+type CallRecordingMediaUpdateFields = Pick<
+  CallRecordingUpdateFields,
+  'audio' | 'video'
+>;
+
+const MEDIA_DOWNLOAD_TIMEOUT_MS = 120_000;
+
+export const ingestCallRecordingMedia = async ({
+  callRecordingId,
+  externalRecordingId,
+  hasAudio,
+  hasVideo,
+}: {
+  callRecordingId: string;
+  externalRecordingId: string;
+  hasAudio: boolean;
+  hasVideo: boolean;
+}): Promise<CallRecordingMediaUpdateFields> => {
+  if (hasAudio && hasVideo) {
+    return {};
+  }
+
+  const recordingResult = await getRecallRecording({ externalRecordingId });
+
+  if (!recordingResult.ok) {
+    console.warn(
+      `[call-recorder] failed to fetch Recall recording ${externalRecordingId} while ingesting media for call recording ${callRecordingId}: ${recordingResult.errorMessage}`,
+    );
+
+    return {};
+  }
+
+  const mediaUrls = extractRecallMediaUrls(recordingResult.recording);
+  const metadataClient = new MetadataApiClient();
+  const updateFields: CallRecordingMediaUpdateFields = {};
+
+  if (!hasVideo && !isUndefined(mediaUrls.videoUrl)) {
+    const video = await ingestMediaArtifact({
+      callRecordingId,
+      metadataClient,
+      url: mediaUrls.videoUrl,
+      fileName: 'video.mp4',
+      fieldMetadataUniversalIdentifier:
+        CALL_RECORDING_VIDEO_FIELD_UNIVERSAL_IDENTIFIER,
+    });
+
+    if (!isUndefined(video)) {
+      updateFields.video = video;
+    }
+  }
+
+  if (!hasAudio && !isUndefined(mediaUrls.audioUrl)) {
+    const audio = await ingestMediaArtifact({
+      callRecordingId,
+      metadataClient,
+      url: mediaUrls.audioUrl,
+      fileName: 'audio.mp3',
+      fieldMetadataUniversalIdentifier:
+        CALL_RECORDING_AUDIO_FIELD_UNIVERSAL_IDENTIFIER,
+    });
+
+    if (!isUndefined(audio)) {
+      updateFields.audio = audio;
+    }
+  }
+
+  return updateFields;
+};
+
+const ingestMediaArtifact = async ({
+  callRecordingId,
+  metadataClient,
+  url,
+  fileName,
+  fieldMetadataUniversalIdentifier,
+}: {
+  callRecordingId: string;
+  metadataClient: InstanceType<typeof MetadataApiClient>;
+  url: string;
+  fileName: string;
+  fieldMetadataUniversalIdentifier: string;
+}): Promise<CallRecordingMediaFile[] | undefined> => {
+  try {
+    const { buffer, contentType } = await downloadMediaFile(url);
+    const uploadedFile = await metadataClient.uploadFile(
+      buffer,
+      fileName,
+      contentType,
+      fieldMetadataUniversalIdentifier,
+    );
+
+    return [{ fileId: uploadedFile.id, label: fileName }];
+  } catch (error) {
+    console.warn(
+      `[call-recorder] failed to ingest ${fileName} for call recording ${callRecordingId}: ${error instanceof Error ? error.message : String(error)}`,
+    );
+
+    return undefined;
+  }
+};
+
+const downloadMediaFile = async (
+  url: string,
+): Promise<{ buffer: Buffer; contentType: string }> => {
+  const response = await fetch(url, {
+    signal: AbortSignal.timeout(MEDIA_DOWNLOAD_TIMEOUT_MS),
+  });
+
+  if (!response.ok) {
+    throw new Error(`download failed with status ${response.status}`);
+  }
+
+  return {
+    buffer: Buffer.from(await response.arrayBuffer()),
+    contentType:
+      response.headers.get('content-type') ?? 'application/octet-stream',
+  };
+};

package/src/logic-functions/flows/persist-call-recording-progress.util.ts

@@ -0,0 +1,58 @@
+import { type CoreApiClient } from 'twenty-client-sdk/core';
+
+import { type FilesFieldValue } from 'src/logic-functions/types/files-field-value.type';
+import { completeAndChargeCallRecording } from 'src/logic-functions/flows/complete-and-charge-call-recording.util';
+import { shouldCompleteCallRecordingIngestion } from 'src/logic-functions/domain/should-complete-call-recording-ingestion.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 PersistCallRecordingProgressCurrent = {
+  status?: string;
+  startedAt?: string;
+  endedAt?: string;
+  transcript?: unknown;
+  audio?: FilesFieldValue;
+  video?: FilesFieldValue;
+};
+
+export const persistCallRecordingProgress = async (
+  client: CoreApiClient,
+  {
+    id,
+    current,
+    updateData,
+  }: {
+    id: string;
+    current: PersistCallRecordingProgressCurrent;
+    updateData: CallRecordingUpdateFields;
+  },
+): Promise<{ completesIngestion: boolean }> => {
+  const completesIngestion = shouldCompleteCallRecordingIngestion({
+    current,
+    updateData,
+  });
+
+  if (!completesIngestion) {
+    await updateCallRecording(client, { id, data: updateData });
+
+    return { completesIngestion: false };
+  }
+
+  // Strip status so COMPLETED is written only by the atomic claim — its single winner bills once.
+  const nonStatusUpdate: CallRecordingUpdateFields = { ...updateData };
+
+  delete nonStatusUpdate.status;
+  delete nonStatusUpdate.callRecorderFailureReason;
+
+  if (Object.keys(nonStatusUpdate).length > 0) {
+    await updateCallRecording(client, { id, data: nonStatusUpdate });
+  }
+
+  await completeAndChargeCallRecording(client, {
+    id,
+    startedAt: updateData.startedAt ?? current.startedAt,
+    endedAt: updateData.endedAt ?? current.endedAt,
+  });
+
+  return { completesIngestion: true };
+};

package/src/logic-functions/flows/reap-orphaned-call-recorders.util.ts

@@ -0,0 +1,183 @@
+import { isNull, isUndefined } from '@sniptt/guards';
+import { type CoreApiClient } from 'twenty-client-sdk/core';
+
+import { CallRecordingRequestStatus } from 'src/logic-functions/constants/call-recording-request-status';
+import { type CallRecordingRecord } from 'src/logic-functions/types/call-recording-record.type';
+import { cancelRecallBot } from 'src/logic-functions/recall-api/cancel-recall-bot.util';
+import { ejectRecallBot } from 'src/logic-functions/recall-api/eject-recall-bot.util';
+import { findCallRecordingsByIds } from 'src/logic-functions/data/find-call-recordings-by-ids.util';
+import { getCurrentWorkspaceId } from 'src/logic-functions/data/get-current-workspace-id.util';
+import { getUniqueSortedIds } from 'src/logic-functions/utils/get-unique-sorted-ids.util';
+import { isNonEmptyString } from 'src/logic-functions/utils/is-non-empty-string.util';
+import {
+  listScheduledRecallBots,
+  type RecallScheduledBot,
+} from 'src/logic-functions/recall-api/list-scheduled-recall-bots.util';
+
+export type ReapOrphanedCallRecordersResult = {
+  scannedBotCount: number;
+  canceledExternalBotIds: string[];
+};
+
+// Bots no open CallRecording request claims would still join; cancel them on Recall.
+export const reapOrphanedCallRecorders = async ({
+  client,
+  joinAtAfter,
+  joinAtBefore,
+}: {
+  client: CoreApiClient;
+  joinAtAfter: string;
+  joinAtBefore: string;
+}): Promise<ReapOrphanedCallRecordersResult> => {
+  const listResult = await listScheduledRecallBots({
+    joinAtAfter,
+    joinAtBefore,
+  });
+
+  if (!listResult.ok) {
+    console.warn(
+      `[call-recorder] failed to list Recall bots for orphan reaping: ${listResult.errorMessage}`,
+    );
+
+    return { scannedBotCount: 0, canceledExternalBotIds: [] };
+  }
+
+  const currentWorkspaceId = getCurrentWorkspaceId();
+
+  if (isUndefined(currentWorkspaceId)) {
+    console.warn(
+      '[call-recorder] cannot reap orphaned Recall bots: workspace id unavailable',
+    );
+
+    return {
+      scannedBotCount: listResult.bots.length,
+      canceledExternalBotIds: [],
+    };
+  }
+
+  const workspaceManagedBots = listResult.bots.filter((bot) =>
+    isCurrentWorkspaceManagedBot({ bot, currentWorkspaceId }),
+  );
+
+  if (workspaceManagedBots.length === 0) {
+    return {
+      scannedBotCount: listResult.bots.length,
+      canceledExternalBotIds: [],
+    };
+  }
+
+  const callRecordings = await findCallRecordingsByIds(
+    client,
+    getUniqueSortedIds(
+      workspaceManagedBots.map((bot) => getClaimedCallRecordingId(bot)),
+    ),
+  );
+  const callRecordingsById = new Map(
+    callRecordings.map((callRecording) => [callRecording.id, callRecording]),
+  );
+  const canceledExternalBotIds: string[] = [];
+
+  for (const bot of workspaceManagedBots) {
+    const claimedCallRecordingId = getClaimedCallRecordingId(bot);
+    const callRecording = isUndefined(claimedCallRecordingId)
+      ? undefined
+      : callRecordingsById.get(claimedCallRecordingId);
+
+    if (isBotClaimed({ bot, callRecording })) {
+      continue;
+    }
+
+    console.warn(
+      `[call-recorder] canceling orphaned Recall bot ${bot.id} (claimed callRecording: ${claimedCallRecordingId})`,
+    );
+
+    if (await cancelOrEjectRecallBot(bot.id)) {
+      canceledExternalBotIds.push(bot.id);
+    }
+  }
+
+  return {
+    scannedBotCount: listResult.bots.length,
+    canceledExternalBotIds,
+  };
+};
+
+const getClaimedCallRecordingId = (
+  bot: RecallScheduledBot,
+): string | undefined => {
+  const claimedCallRecordingId = bot.metadata.twentyCallRecordingId;
+
+  return normalizeOptionalString(claimedCallRecordingId);
+};
+
+const getClaimedWorkspaceId = (bot: RecallScheduledBot): string | undefined => {
+  const claimedWorkspaceId = bot.metadata.twentyWorkspaceId;
+
+  return normalizeOptionalString(claimedWorkspaceId);
+};
+
+const isCurrentWorkspaceManagedBot = ({
+  bot,
+  currentWorkspaceId,
+}: {
+  bot: RecallScheduledBot;
+  currentWorkspaceId: string;
+}): boolean => {
+  if (isUndefined(getClaimedCallRecordingId(bot))) {
+    return false;
+  }
+
+  const claimedWorkspaceId = getClaimedWorkspaceId(bot);
+
+  return claimedWorkspaceId === currentWorkspaceId;
+};
+
+const isBotClaimed = ({
+  bot,
+  callRecording,
+}: {
+  bot: RecallScheduledBot;
+  callRecording: CallRecordingRecord | undefined;
+}): boolean => {
+  if (
+    callRecording?.recordingRequestStatus !==
+    CallRecordingRequestStatus.REQUESTED
+  ) {
+    return false;
+  }
+
+  if (callRecording.externalBotId === bot.id) {
+    return true;
+  }
+
+  // An id-less REQUESTED recording may have a bot-id write-back in flight; spare its bot.
+  return isUndefined(callRecording.externalBotId);
+};
+
+const cancelOrEjectRecallBot = async (
+  externalBotId: string,
+): Promise<boolean> => {
+  const cancelResult = await cancelRecallBot({ externalBotId });
+
+  if (cancelResult.ok) {
+    return true;
+  }
+
+  // Deleting only works for not-yet-joined bots; eject the ones already in a call.
+  if (!isNull(cancelResult.status)) {
+    const ejectResult = await ejectRecallBot({ externalBotId });
+
+    if (ejectResult.ok) {
+      return true;
+    }
+  }
+
+  console.warn(
+    `[call-recorder] failed to cancel orphaned Recall bot ${externalBotId}: ${cancelResult.errorMessage}`,
+  );
+
+  return false;
+};
+
+const normalizeOptionalString = (value: unknown): string | undefined =>
+  isNonEmptyString(value) ? value.trim() : undefined;