@twentyhq/call-recorder 1.0.0

package/src/front-components/hooks/use-calendar-event-recording.ts

@@ -0,0 +1,155 @@
+import { isUndefined } from '@sniptt/guards';
+import { useEffect, useState } from 'react';
+import { CoreApiClient } from 'twenty-client-sdk/core';
+
+type CalendarEventRecordingState = {
+  transcript: unknown;
+  videoFile: CalendarEventRecordingVideoFile | undefined;
+  isCalendarEventRecordingQueryLoading: boolean;
+  errorMessage: string | undefined;
+};
+
+type CalendarEventRecordingVideoFile = {
+  fileId: string;
+  label: string | null;
+  url: string | null;
+  extension: string | null;
+};
+
+type CalendarEventRecordingCallRecordingNode = {
+  id: string;
+  transcript: unknown;
+  video: CalendarEventRecordingVideoFile[] | null;
+};
+
+type CalendarEventRecordingCallRecordingEdge = {
+  node: CalendarEventRecordingCallRecordingNode;
+};
+
+const CALENDAR_EVENT_RECORDING_LOOKUP_LIMIT = 10;
+const CALENDAR_EVENT_RECORDING_ERROR_MESSAGE = 'Please try again later.';
+
+export const useCalendarEventRecording = (
+  calendarEventId: string | undefined,
+): CalendarEventRecordingState => {
+  const [state, setState] = useState<CalendarEventRecordingState>({
+    transcript: undefined,
+    videoFile: undefined,
+    isCalendarEventRecordingQueryLoading: !isUndefined(calendarEventId),
+    errorMessage: undefined,
+  });
+
+  useEffect(() => {
+    if (isUndefined(calendarEventId)) {
+      setState({
+        transcript: undefined,
+        videoFile: undefined,
+        isCalendarEventRecordingQueryLoading: false,
+        errorMessage: undefined,
+      });
+      return;
+    }
+
+    let cancelled = false;
+
+    const fetchRecording = async () => {
+      setState({
+        transcript: undefined,
+        videoFile: undefined,
+        isCalendarEventRecordingQueryLoading: true,
+        errorMessage: undefined,
+      });
+
+      try {
+        const client = new CoreApiClient();
+        const queryResult = await client.query({
+          callRecordings: {
+            __args: {
+              filter: { calendarEventId: { eq: calendarEventId } },
+              orderBy: [{ startedAt: 'DescNullsLast' }],
+              first: CALENDAR_EVENT_RECORDING_LOOKUP_LIMIT,
+            },
+            edges: {
+              node: {
+                id: true,
+                transcript: true,
+                video: {
+                  fileId: true,
+                  label: true,
+                  url: true,
+                  extension: true,
+                },
+              },
+            },
+          },
+        });
+
+        if (cancelled) {
+          return;
+        }
+
+        const callRecordingEdges = (queryResult.callRecordings?.edges ??
+          []) as CalendarEventRecordingCallRecordingEdge[];
+        const callRecordingNodes = callRecordingEdges.map(
+          (callRecordingEdge) => callRecordingEdge.node,
+        );
+        const callRecordingNode =
+          selectCalendarEventRecording(callRecordingNodes);
+
+        setState({
+          transcript: callRecordingNode?.transcript ?? undefined,
+          videoFile: isUndefined(callRecordingNode)
+            ? undefined
+            : getVideoFile(callRecordingNode),
+          isCalendarEventRecordingQueryLoading: false,
+          errorMessage: undefined,
+        });
+      } catch {
+        if (cancelled) {
+          return;
+        }
+
+        setState({
+          transcript: undefined,
+          videoFile: undefined,
+          isCalendarEventRecordingQueryLoading: false,
+          errorMessage: CALENDAR_EVENT_RECORDING_ERROR_MESSAGE,
+        });
+      }
+    };
+
+    fetchRecording();
+
+    return () => {
+      cancelled = true;
+    };
+  }, [calendarEventId]);
+
+  return state;
+};
+
+const hasTranscript = (
+  callRecordingNode: CalendarEventRecordingCallRecordingNode,
+): boolean =>
+  !isUndefined(callRecordingNode.transcript) &&
+  callRecordingNode.transcript !== null;
+
+const getVideoFile = (
+  callRecordingNode: CalendarEventRecordingCallRecordingNode,
+): CalendarEventRecordingVideoFile | undefined =>
+  callRecordingNode.video?.find(
+    (videoFile) => !isUndefined(videoFile.url) && videoFile.url !== null,
+  );
+
+const selectCalendarEventRecording = (
+  callRecordingNodes: CalendarEventRecordingCallRecordingNode[],
+): CalendarEventRecordingCallRecordingNode | undefined =>
+  callRecordingNodes.find(
+    (callRecordingNode) =>
+      hasTranscript(callRecordingNode) &&
+      !isUndefined(getVideoFile(callRecordingNode)),
+  ) ??
+  callRecordingNodes.find(hasTranscript) ??
+  callRecordingNodes.find(
+    (callRecordingNode) => !isUndefined(getVideoFile(callRecordingNode)),
+  );

package/src/front-components/types/calendar-event-participant-by-speaker-name.type.ts

@@ -0,0 +1,6 @@
+import { type CalendarEventRecordingParticipant } from 'src/front-components/types/calendar-event-recording-participant.type';
+
+export type CalendarEventParticipantBySpeakerName = Map<
+  string,
+  CalendarEventRecordingParticipant
+>;

package/src/front-components/types/calendar-event-recording-participant.type.ts

@@ -0,0 +1,7 @@
+export type CalendarEventRecordingParticipant = {
+  id: string;
+  avatarUrl: string | undefined;
+  displayName: string | undefined;
+  nameCandidates: string[];
+  placeholderColorSeed: string;
+};

package/src/front-components/types/transcript-entry.type.ts

@@ -0,0 +1,13 @@
+export type TranscriptWord = {
+  text: string;
+  startSeconds: number | undefined;
+  endSeconds: number | undefined;
+};
+
+export type TranscriptEntry = {
+  speakerName: string;
+  startSeconds: number | undefined;
+  endSeconds: number | undefined;
+  text: string;
+  words: TranscriptWord[];
+};

package/src/front-components/utils/__tests__/find-active-transcript-entry-index.test.ts

@@ -0,0 +1,66 @@
+import { describe, expect, it } from 'vitest';
+
+import { type TranscriptEntry } from 'src/front-components/types/transcript-entry.type';
+import { findActiveTranscriptEntryIndex } from 'src/front-components/utils/find-active-transcript-entry-index.util';
+
+const makeTranscriptEntry = ({
+  startSeconds,
+  endSeconds,
+}: {
+  startSeconds: number | undefined;
+  endSeconds: number | undefined;
+}): TranscriptEntry => ({
+  speakerName: 'Ada Lovelace',
+  startSeconds,
+  endSeconds,
+  text: 'Hello',
+  words: [{ text: 'Hello', startSeconds, endSeconds }],
+});
+
+describe('findActiveTranscriptEntryIndex', () => {
+  it('does not keep an open-ended entry active after the next entry starts', () => {
+    expect(
+      findActiveTranscriptEntryIndex(
+        [
+          makeTranscriptEntry({ startSeconds: 1, endSeconds: undefined }),
+          makeTranscriptEntry({ startSeconds: 10, endSeconds: 20 }),
+        ],
+        25,
+      ),
+    ).toBe(-1);
+  });
+
+  it('uses the next known start as the boundary for entries without an end time', () => {
+    expect(
+      findActiveTranscriptEntryIndex(
+        [
+          makeTranscriptEntry({ startSeconds: 1, endSeconds: undefined }),
+          makeTranscriptEntry({ startSeconds: 10, endSeconds: 20 }),
+        ],
+        9,
+      ),
+    ).toBe(0);
+
+    expect(
+      findActiveTranscriptEntryIndex(
+        [
+          makeTranscriptEntry({ startSeconds: 1, endSeconds: undefined }),
+          makeTranscriptEntry({ startSeconds: 10, endSeconds: 20 }),
+        ],
+        10,
+      ),
+    ).toBe(1);
+  });
+
+  it('keeps the final open-ended entry active after it starts', () => {
+    expect(
+      findActiveTranscriptEntryIndex(
+        [
+          makeTranscriptEntry({ startSeconds: 1, endSeconds: 2 }),
+          makeTranscriptEntry({ startSeconds: 10, endSeconds: undefined }),
+        ],
+        25,
+      ),
+    ).toBe(1);
+  });
+});

package/src/front-components/utils/__tests__/format-transcript-timestamp.test.ts

@@ -0,0 +1,29 @@
+import { describe, expect, it } from 'vitest';
+
+import { formatTranscriptTimestamp } from 'src/front-components/utils/format-transcript-timestamp.util';
+
+describe('formatTranscriptTimestamp', () => {
+  it('formats sub-hour durations as minutes and padded seconds', () => {
+    expect(formatTranscriptTimestamp(0)).toBe('0:00');
+    expect(formatTranscriptTimestamp(5)).toBe('0:05');
+    expect(formatTranscriptTimestamp(65)).toBe('1:05');
+    expect(formatTranscriptTimestamp(3599)).toBe('59:59');
+  });
+
+  it('adds an hour part with padded minutes past one hour', () => {
+    expect(formatTranscriptTimestamp(3600)).toBe('1:00:00');
+    expect(formatTranscriptTimestamp(3725)).toBe('1:02:05');
+    expect(formatTranscriptTimestamp(7322)).toBe('2:02:02');
+  });
+
+  it('floors fractional seconds', () => {
+    expect(formatTranscriptTimestamp(1.9)).toBe('0:01');
+    expect(formatTranscriptTimestamp(59.999)).toBe('0:59');
+  });
+
+  it('clamps negative and non-finite input to zero', () => {
+    expect(formatTranscriptTimestamp(-12)).toBe('0:00');
+    expect(formatTranscriptTimestamp(Number.NaN)).toBe('0:00');
+    expect(formatTranscriptTimestamp(Number.POSITIVE_INFINITY)).toBe('0:00');
+  });
+});

package/src/front-components/utils/__tests__/get-speaker-name-match-keys.test.ts

@@ -0,0 +1,22 @@
+import { describe, expect, it } from 'vitest';
+
+import { getSpeakerNameMatchKeys } from 'src/front-components/utils/get-speaker-name-match-keys.util';
+
+describe('getSpeakerNameMatchKeys', () => {
+  it('matches transcript full names to compact calendar aliases', () => {
+    expect(getSpeakerNameMatchKeys('Martin Muller')).toContain('martmull');
+    expect(getSpeakerNameMatchKeys('Martmull92')).toContain('martmull');
+  });
+
+  it('keeps exact normalized full names available for regular participant names', () => {
+    expect(getSpeakerNameMatchKeys('Nitin Koche')).toEqual([
+      'nitin koche',
+      'nitinkoche',
+      'nitikoch',
+    ]);
+  });
+
+  it('folds accents before generating compact match keys', () => {
+    expect(getSpeakerNameMatchKeys('Martin Müller')).toContain('martmull');
+  });
+});

package/src/front-components/utils/__tests__/parse-transcript-entries.test.ts

@@ -0,0 +1,162 @@
+import { describe, expect, it } from 'vitest';
+
+import { parseTranscriptEntries } from 'src/front-components/utils/parse-transcript-entries.util';
+
+describe('parseTranscriptEntries', () => {
+  it('parses diarized entries into speaker, start time, and joined text', () => {
+    expect(
+      parseTranscriptEntries([
+        {
+          participant: { id: 100, name: 'Ada Lovelace' },
+          words: [
+            {
+              text: 'Hello',
+              start_timestamp: {
+                relative: 1.2,
+                absolute: '2026-06-12T10:00:01Z',
+              },
+              end_timestamp: {
+                relative: 1.6,
+                absolute: '2026-06-12T10:00:01Z',
+              },
+            },
+            {
+              text: 'there',
+              start_timestamp: {
+                relative: 1.7,
+                absolute: '2026-06-12T10:00:02Z',
+              },
+              end_timestamp: {
+                relative: 2.1,
+                absolute: '2026-06-12T10:00:02Z',
+              },
+            },
+          ],
+        },
+        {
+          participant: { id: 101, name: 'Grace Hopper' },
+          words: [
+            {
+              text: 'Hi',
+              start_timestamp: {
+                relative: 3.4,
+                absolute: '2026-06-12T10:00:03Z',
+              },
+            },
+          ],
+        },
+      ]),
+    ).toEqual([
+      {
+        speakerName: 'Ada Lovelace',
+        startSeconds: 1.2,
+        endSeconds: 2.1,
+        text: 'Hello there',
+        words: [
+          { text: 'Hello', startSeconds: 1.2, endSeconds: 1.6 },
+          { text: 'there', startSeconds: 1.7, endSeconds: 2.1 },
+        ],
+      },
+      {
+        speakerName: 'Grace Hopper',
+        startSeconds: 3.4,
+        endSeconds: undefined,
+        text: 'Hi',
+        words: [{ text: 'Hi', startSeconds: 3.4, endSeconds: undefined }],
+      },
+    ]);
+  });
+
+  it('falls back to an unknown speaker when the participant has no name', () => {
+    expect(
+      parseTranscriptEntries([
+        { participant: { id: 100, name: null }, words: [{ text: 'Hello' }] },
+        { words: [{ text: 'Hi' }] },
+      ]),
+    ).toEqual([
+      {
+        speakerName: 'Unknown speaker',
+        startSeconds: undefined,
+        endSeconds: undefined,
+        text: 'Hello',
+        words: [
+          { text: 'Hello', startSeconds: undefined, endSeconds: undefined },
+        ],
+      },
+      {
+        speakerName: 'Unknown speaker',
+        startSeconds: undefined,
+        endSeconds: undefined,
+        text: 'Hi',
+        words: [{ text: 'Hi', startSeconds: undefined, endSeconds: undefined }],
+      },
+    ]);
+  });
+
+  it('returns an undefined start time when the first word has no relative timestamp', () => {
+    expect(
+      parseTranscriptEntries([
+        {
+          participant: { name: 'Ada Lovelace' },
+          words: [
+            {
+              text: 'Hello',
+              start_timestamp: { absolute: '2026-06-12T10:00:01Z' },
+            },
+          ],
+        },
+      ]),
+    ).toEqual([
+      {
+        speakerName: 'Ada Lovelace',
+        startSeconds: undefined,
+        endSeconds: undefined,
+        text: 'Hello',
+        words: [
+          { text: 'Hello', startSeconds: undefined, endSeconds: undefined },
+        ],
+      },
+    ]);
+  });
+
+  it('skips entries without usable words instead of failing the whole transcript', () => {
+    expect(
+      parseTranscriptEntries([
+        { participant: { name: 'Ada Lovelace' }, words: [] },
+        { participant: { name: 'Grace Hopper' } },
+        {
+          participant: { name: 'Alan Turing' },
+          words: [{ text: '   ' }, 42, null],
+        },
+        { participant: { name: 'Joan Clarke' }, words: [{ text: 'Kept' }] },
+        'not an entry',
+      ]),
+    ).toEqual([
+      {
+        speakerName: 'Joan Clarke',
+        startSeconds: undefined,
+        endSeconds: undefined,
+        text: 'Kept',
+        words: [
+          { text: 'Kept', startSeconds: undefined, endSeconds: undefined },
+        ],
+      },
+    ]);
+  });
+
+  it('returns an empty list for an empty transcript array', () => {
+    expect(parseTranscriptEntries([])).toEqual([]);
+  });
+
+  it('returns undefined for values that are not a diarized transcript array', () => {
+    expect(parseTranscriptEntries(null)).toBeUndefined();
+    expect(parseTranscriptEntries(undefined)).toBeUndefined();
+    expect(parseTranscriptEntries('transcript text')).toBeUndefined();
+    expect(
+      parseTranscriptEntries({
+        recallTranscriptId: 'recall-transcript-1',
+        status: 'PENDING',
+      }),
+    ).toBeUndefined();
+  });
+});

package/src/front-components/utils/build-calendar-event-participant-by-speaker-name.util.ts

@@ -0,0 +1,45 @@
+import { isUndefined } from '@sniptt/guards';
+
+import { type CalendarEventParticipantBySpeakerName } from 'src/front-components/types/calendar-event-participant-by-speaker-name.type';
+import { type CalendarEventRecordingParticipant } from 'src/front-components/types/calendar-event-recording-participant.type';
+import { getSpeakerNameMatchKeys } from 'src/front-components/utils/get-speaker-name-match-keys.util';
+
+export const buildCalendarEventParticipantBySpeakerName = (
+  calendarEventParticipants: CalendarEventRecordingParticipant[],
+): CalendarEventParticipantBySpeakerName => {
+  const calendarEventParticipantBySpeakerName: CalendarEventParticipantBySpeakerName =
+    new Map();
+  const ambiguousSpeakerNameMatchKeys = new Set<string>();
+
+  for (const calendarEventParticipant of calendarEventParticipants) {
+    for (const nameCandidate of calendarEventParticipant.nameCandidates) {
+      const speakerNameMatchKeys = getSpeakerNameMatchKeys(nameCandidate);
+
+      for (const speakerNameMatchKey of speakerNameMatchKeys) {
+        const matchingCalendarEventParticipant =
+          calendarEventParticipantBySpeakerName.get(speakerNameMatchKey);
+
+        if (ambiguousSpeakerNameMatchKeys.has(speakerNameMatchKey)) {
+          continue;
+        }
+
+        if (isUndefined(matchingCalendarEventParticipant)) {
+          calendarEventParticipantBySpeakerName.set(
+            speakerNameMatchKey,
+            calendarEventParticipant,
+          );
+          continue;
+        }
+
+        if (
+          matchingCalendarEventParticipant.id !== calendarEventParticipant.id
+        ) {
+          calendarEventParticipantBySpeakerName.delete(speakerNameMatchKey);
+          ambiguousSpeakerNameMatchKeys.add(speakerNameMatchKey);
+        }
+      }
+    }
+  }
+
+  return calendarEventParticipantBySpeakerName;
+};

package/src/front-components/utils/find-active-transcript-entry-index.util.ts

@@ -0,0 +1,77 @@
+import { isUndefined } from '@sniptt/guards';
+
+import { type TranscriptEntry } from 'src/front-components/types/transcript-entry.type';
+
+export const findActiveTranscriptEntryIndex = (
+  entries: TranscriptEntry[],
+  currentTimeSeconds: number,
+): number => {
+  for (let entryIndex = entries.length - 1; entryIndex >= 0; entryIndex--) {
+    const entry = entries[entryIndex];
+
+    if (
+      isTranscriptEntryActive({
+        entries,
+        entry,
+        entryIndex,
+        currentTimeSeconds,
+      })
+    ) {
+      return entryIndex;
+    }
+  }
+
+  return -1;
+};
+
+const isTranscriptEntryActive = ({
+  entries,
+  entry,
+  entryIndex,
+  currentTimeSeconds,
+}: {
+  entries: TranscriptEntry[];
+  entry: TranscriptEntry;
+  entryIndex: number;
+  currentTimeSeconds: number;
+}): boolean => {
+  if (
+    isUndefined(entry.startSeconds) ||
+    currentTimeSeconds < entry.startSeconds
+  ) {
+    return false;
+  }
+
+  if (!isUndefined(entry.endSeconds)) {
+    return currentTimeSeconds <= entry.endSeconds;
+  }
+
+  const nextTranscriptEntryStartSeconds = findNextTranscriptEntryStartSeconds(
+    entries,
+    entryIndex,
+  );
+
+  return isUndefined(nextTranscriptEntryStartSeconds)
+    ? true
+    : currentTimeSeconds < nextTranscriptEntryStartSeconds;
+};
+
+const findNextTranscriptEntryStartSeconds = (
+  entries: TranscriptEntry[],
+  entryIndex: number,
+): number | undefined => {
+  for (
+    let nextEntryIndex = entryIndex + 1;
+    nextEntryIndex < entries.length;
+    nextEntryIndex++
+  ) {
+    const nextTranscriptEntryStartSeconds =
+      entries[nextEntryIndex].startSeconds;
+
+    if (!isUndefined(nextTranscriptEntryStartSeconds)) {
+      return nextTranscriptEntryStartSeconds;
+    }
+  }
+
+  return undefined;
+};

package/src/front-components/utils/format-transcript-timestamp.util.ts

@@ -0,0 +1,16 @@
+export const formatTranscriptTimestamp = (totalSeconds: number): string => {
+  const safeSeconds = Number.isFinite(totalSeconds)
+    ? Math.max(0, Math.floor(totalSeconds))
+    : 0;
+
+  const hours = Math.floor(safeSeconds / 3600);
+  const minutes = Math.floor((safeSeconds % 3600) / 60);
+  const seconds = safeSeconds % 60;
+  const paddedSeconds = String(seconds).padStart(2, '0');
+
+  if (hours > 0) {
+    return `${hours}:${String(minutes).padStart(2, '0')}:${paddedSeconds}`;
+  }
+
+  return `${minutes}:${paddedSeconds}`;
+};

package/src/front-components/utils/get-absolute-avatar-url.util.ts

@@ -0,0 +1,48 @@
+// Duplicates minimal front image URL logic for this app.
+// Remove once shared front utilities can be imported safely in front components.
+import { isNonEmptyString } from 'src/logic-functions/utils/is-non-empty-string.util';
+
+type GetImageAbsoluteUrlArgs = {
+  imageUrl: string;
+  baseUrl: string;
+};
+
+const getImageAbsoluteUrl = ({
+  imageUrl,
+  baseUrl,
+}: GetImageAbsoluteUrlArgs): string => {
+  const lowerCaseImageUrl = imageUrl.toLowerCase();
+  const isAlreadyAbsoluteUrl =
+    ['http:', 'https:', 'data:', 'blob:'].some((scheme) =>
+      lowerCaseImageUrl.startsWith(scheme),
+    ) || imageUrl.startsWith('//');
+
+  if (isAlreadyAbsoluteUrl) {
+    return imageUrl;
+  }
+
+  if (imageUrl.startsWith('/')) {
+    return new URL(`/files${imageUrl}`, baseUrl).toString();
+  }
+
+  return new URL(`/files/${imageUrl}`, baseUrl).toString();
+};
+
+export const getAbsoluteAvatarUrl = (
+  avatarUrl: string | null | undefined,
+): string | undefined => {
+  if (!isNonEmptyString(avatarUrl)) {
+    return undefined;
+  }
+
+  const apiBaseUrl = process.env.TWENTY_API_URL;
+
+  if (!isNonEmptyString(apiBaseUrl)) {
+    return avatarUrl.trim();
+  }
+
+  return getImageAbsoluteUrl({
+    imageUrl: avatarUrl.trim(),
+    baseUrl: apiBaseUrl,
+  });
+};

package/src/front-components/utils/get-calendar-event-participant-for-speaker-name.util.ts

@@ -0,0 +1,24 @@
+import { isUndefined } from '@sniptt/guards';
+
+import { type CalendarEventParticipantBySpeakerName } from 'src/front-components/types/calendar-event-participant-by-speaker-name.type';
+import { type CalendarEventRecordingParticipant } from 'src/front-components/types/calendar-event-recording-participant.type';
+import { getSpeakerNameMatchKeys } from 'src/front-components/utils/get-speaker-name-match-keys.util';
+
+export const getCalendarEventParticipantForSpeakerName = ({
+  speakerName,
+  calendarEventParticipantBySpeakerName,
+}: {
+  speakerName: string;
+  calendarEventParticipantBySpeakerName: CalendarEventParticipantBySpeakerName;
+}): CalendarEventRecordingParticipant | undefined => {
+  for (const speakerNameMatchKey of getSpeakerNameMatchKeys(speakerName)) {
+    const calendarEventParticipant =
+      calendarEventParticipantBySpeakerName.get(speakerNameMatchKey);
+
+    if (!isUndefined(calendarEventParticipant)) {
+      return calendarEventParticipant;
+    }
+  }
+
+  return undefined;
+};