@twentyhq/call-recorder 1.0.0

package/src/logic-functions/domain/compute-call-recording-charge.util.ts

@@ -0,0 +1,41 @@
+import { isUndefined } from '@sniptt/guards';
+
+import { CALL_RECORDING_MICRO_CREDITS_PER_HOUR } from 'src/logic-functions/constants/call-recording-micro-credits-per-hour';
+import { MILLISECONDS_PER_MINUTE } from 'src/logic-functions/constants/milliseconds-per-minute';
+
+const MILLISECONDS_PER_HOUR = 3_600_000;
+
+export type CallRecordingCharge = {
+  creditsUsedMicro: number;
+  quantityMinutes: number;
+};
+
+export const computeCallRecordingCharge = ({
+  startedAt,
+  endedAt,
+}: {
+  startedAt: string | undefined;
+  endedAt: string | undefined;
+}): CallRecordingCharge | undefined => {
+  if (isUndefined(startedAt) || isUndefined(endedAt)) {
+    return undefined;
+  }
+
+  const durationMilliseconds =
+    new Date(endedAt).getTime() - new Date(startedAt).getTime();
+
+  if (!Number.isFinite(durationMilliseconds) || durationMilliseconds <= 0) {
+    return undefined;
+  }
+
+  return {
+    creditsUsedMicro: Math.round(
+      (durationMilliseconds / MILLISECONDS_PER_HOUR) *
+        CALL_RECORDING_MICRO_CREDITS_PER_HOUR,
+    ),
+    quantityMinutes: Math.max(
+      1,
+      Math.round(durationMilliseconds / MILLISECONDS_PER_MINUTE),
+    ),
+  };
+};

package/src/logic-functions/domain/compute-call-recording-id-for-meeting.util.ts

@@ -0,0 +1,16 @@
+import { createHash } from 'crypto';
+
+// Same meeting key → same id: the primary key serializes concurrent creates.
+export const computeCallRecordingIdForMeeting = (
+  realMeetingKey: string,
+): string => {
+  const bytes = createHash('sha256').update(realMeetingKey).digest();
+
+  // v4 version/variant bits so server-side UUID validation accepts the hash.
+  bytes[6] = (bytes[6] & 0x0f) | 0x40;
+  bytes[8] = (bytes[8] & 0x3f) | 0x80;
+
+  const hex = bytes.subarray(0, 16).toString('hex');
+
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+};

package/src/logic-functions/domain/compute-real-meeting-key.util.ts

@@ -0,0 +1,48 @@
+import { isUndefined } from '@sniptt/guards';
+
+import { isNonEmptyString } from 'src/logic-functions/utils/is-non-empty-string.util';
+
+type ComputeRealMeetingKeyInput = {
+  calendarEventId: string;
+  conferenceLinkUrl: unknown;
+  iCalUid: string | undefined;
+  startsAt: string | undefined;
+};
+
+export const computeRealMeetingKey = ({
+  calendarEventId,
+  conferenceLinkUrl,
+  iCalUid,
+  startsAt,
+}: ComputeRealMeetingKeyInput): string => {
+  const normalizedConferenceLink = normalizeConferenceLink(conferenceLinkUrl);
+
+  if (!isUndefined(normalizedConferenceLink)) {
+    return `link:${normalizedConferenceLink}:${startsAt ?? ''}`;
+  }
+
+  if (isNonEmptyString(iCalUid)) {
+    return `ical:${iCalUid}:${startsAt ?? ''}`;
+  }
+
+  return `event:${calendarEventId}`;
+};
+
+const normalizeConferenceLink = (
+  conferenceLinkUrl: unknown,
+): string | undefined => {
+  if (!isNonEmptyString(conferenceLinkUrl)) {
+    return undefined;
+  }
+
+  const withoutProtocol = conferenceLinkUrl
+    .trim()
+    .toLowerCase()
+    .replace(/^https?:\/\//, '')
+    .replace(/^www\./, '');
+
+  const withoutQueryAndFragment = withoutProtocol.split(/[?#]/)[0];
+  const withoutTrailingSlash = withoutQueryAndFragment.replace(/\/+$/, '');
+
+  return withoutTrailingSlash === '' ? undefined : withoutTrailingSlash;
+};

package/src/logic-functions/domain/compute-recall-bot-join-at.util.ts

@@ -0,0 +1,34 @@
+import { DEFAULT_CALL_RECORDER_JOIN_EARLY_MINUTES } from 'src/logic-functions/constants/default-call-recorder-join-early-minutes';
+import { MILLISECONDS_PER_MINUTE } from 'src/logic-functions/constants/milliseconds-per-minute';
+import { CALL_RECORDER_JOIN_EARLY_MINUTES_ENV_VAR_NAME } from 'src/logic-functions/constants/call-recorder-join-early-minutes-env-var-name';
+import { getApplicationVariableValue } from 'src/logic-functions/utils/get-application-variable-value.util';
+import { isNonEmptyString } from 'src/logic-functions/utils/is-non-empty-string.util';
+
+export const computeRecallBotJoinAt = (meetingStartsAt: string): string => {
+  const meetingStartTimeInMilliseconds = new Date(meetingStartsAt).getTime();
+
+  if (Number.isNaN(meetingStartTimeInMilliseconds)) {
+    return meetingStartsAt;
+  }
+
+  return new Date(
+    meetingStartTimeInMilliseconds -
+      getRecallBotJoinEarlyMinutes() * MILLISECONDS_PER_MINUTE,
+  ).toISOString();
+};
+
+const getRecallBotJoinEarlyMinutes = (): number => {
+  const rawValue = getApplicationVariableValue(
+    CALL_RECORDER_JOIN_EARLY_MINUTES_ENV_VAR_NAME,
+  );
+
+  if (!isNonEmptyString(rawValue)) {
+    return DEFAULT_CALL_RECORDER_JOIN_EARLY_MINUTES;
+  }
+
+  const joinEarlyMinutes = Number(rawValue.trim());
+
+  return Number.isInteger(joinEarlyMinutes) && joinEarlyMinutes >= 0
+    ? joinEarlyMinutes
+    : DEFAULT_CALL_RECORDER_JOIN_EARLY_MINUTES;
+};

package/src/logic-functions/domain/is-call-recording-ingestion-complete.util.ts

@@ -0,0 +1,19 @@
+import { isNonEmptyArray, isNull, isUndefined } from '@sniptt/guards';
+
+import { type FilesFieldValue } from 'src/logic-functions/types/files-field-value.type';
+import { parseTranscriptMarker } from 'src/logic-functions/domain/parse-transcript-marker.util';
+
+export const isCallRecordingIngestionComplete = ({
+  transcript,
+  audio,
+  video,
+}: {
+  transcript: unknown;
+  audio: FilesFieldValue | undefined;
+  video: FilesFieldValue | undefined;
+}): boolean =>
+  !isNull(transcript) &&
+  !isUndefined(transcript) &&
+  isUndefined(parseTranscriptMarker(transcript)) &&
+  isNonEmptyArray(audio) &&
+  isNonEmptyArray(video);

package/src/logic-functions/domain/is-call-recording-status-downgrade.util.ts

@@ -0,0 +1,37 @@
+import { isUndefined } from '@sniptt/guards';
+
+import { CallRecordingStatus } from 'src/logic-functions/constants/call-recording-status';
+
+// Deliveries are unordered; a late event must never move status backwards.
+const CALL_RECORDING_STATUS_PROGRESSION: Record<CallRecordingStatus, number> = {
+  [CallRecordingStatus.SCHEDULED]: 0,
+  [CallRecordingStatus.JOINING]: 1,
+  [CallRecordingStatus.RECORDING]: 2,
+  [CallRecordingStatus.PROCESSING]: 3,
+  [CallRecordingStatus.FAILED]: 4,
+  [CallRecordingStatus.COMPLETED]: 5,
+};
+
+const getCallRecordingStatusRank = (status: string): number | undefined =>
+  status in CALL_RECORDING_STATUS_PROGRESSION
+    ? CALL_RECORDING_STATUS_PROGRESSION[status as CallRecordingStatus]
+    : undefined;
+
+export const isCallRecordingStatusDowngrade = ({
+  fromStatus,
+  toStatus,
+}: {
+  fromStatus: string | undefined;
+  toStatus: string;
+}): boolean => {
+  const fromRank = isUndefined(fromStatus)
+    ? undefined
+    : getCallRecordingStatusRank(fromStatus);
+  const toRank = getCallRecordingStatusRank(toStatus);
+
+  if (isUndefined(fromRank) || isUndefined(toRank)) {
+    return false;
+  }
+
+  return toRank < fromRank;
+};

package/src/logic-functions/domain/is-recall-recording-done-signal.util.ts

@@ -0,0 +1,13 @@
+export const isRecallRecordingDoneSignal = ({
+  event,
+  statusCode,
+}: {
+  event: string;
+  statusCode: string | undefined;
+}): boolean => {
+  return (
+    event === 'recording.done' ||
+    event === 'recording.failed' ||
+    statusCode === 'done'
+  );
+};

package/src/logic-functions/domain/map-recall-status-code-to-call-recording-status.util.ts

@@ -0,0 +1,26 @@
+import { CallRecordingStatus } from 'src/logic-functions/constants/call-recording-status';
+
+export const mapRecallStatusCodeToCallRecordingStatus = (
+  statusCode: string | undefined,
+): CallRecordingStatus | undefined => {
+  switch (statusCode) {
+    case 'joining_call':
+    case 'in_waiting_room':
+      return CallRecordingStatus.JOINING;
+    case 'in_call_not_recording':
+    case 'recording_permission_allowed':
+    case 'in_call_recording':
+      return CallRecordingStatus.RECORDING;
+    // 'done' stays PROCESSING: COMPLETED is set only after all artifacts are ingested.
+    case 'call_ended':
+    case 'analysis_done':
+    case 'done':
+      return CallRecordingStatus.PROCESSING;
+    case 'fatal':
+    case 'analysis_failed':
+    case 'recording_permission_denied':
+      return CallRecordingStatus.FAILED;
+    default:
+      return undefined;
+  }
+};

package/src/logic-functions/domain/parse-transcript-marker.util.ts

@@ -0,0 +1,29 @@
+import { isString, isUndefined } from '@sniptt/guards';
+
+import { type TranscriptMarker } from 'src/logic-functions/types/transcript-marker.type';
+import { asRecord } from 'src/logic-functions/utils/as-record.util';
+
+export const parseTranscriptMarker = (
+  transcript: unknown,
+): TranscriptMarker | undefined => {
+  const candidate = asRecord(transcript);
+
+  if (isUndefined(candidate)) {
+    return undefined;
+  }
+
+  if (candidate.status !== 'PENDING' && candidate.status !== 'FAILED') {
+    return undefined;
+  }
+
+  return {
+    recallTranscriptId: isString(candidate.recallTranscriptId)
+      ? candidate.recallTranscriptId
+      : null,
+    status: candidate.status,
+    ...(isString(candidate.requestedAt)
+      ? { requestedAt: candidate.requestedAt }
+      : {}),
+    ...(isString(candidate.subCode) ? { subCode: candidate.subCode } : {}),
+  };
+};

package/src/logic-functions/domain/resolve-call-recorder-policy-result.util.ts

@@ -0,0 +1,72 @@
+import { CallRecorderPreference } from 'src/constants/call-recorder-preference';
+import { type CallRecorderPolicyInput } from 'src/logic-functions/types/call-recorder-policy-input.type';
+import { isNonEmptyString } from 'src/logic-functions/utils/is-non-empty-string.util';
+import { type CallRecorderPolicyNotRequiredReason } from 'src/logic-functions/types/call-recorder-policy-not-required-reason.type';
+import { type CallRecorderPolicyRequiredReason } from 'src/logic-functions/types/call-recorder-policy-required-reason.type';
+import { type CallRecorderPolicyResult } from 'src/logic-functions/types/call-recorder-policy-result.type';
+
+type ResolveCallRecorderPolicyResultArgs = {
+  input: CallRecorderPolicyInput;
+  now: Date;
+};
+
+export const resolveCallRecorderPolicyResult = ({
+  input,
+  now,
+}: ResolveCallRecorderPolicyResultArgs): CallRecorderPolicyResult => {
+  if (input.isCanceled) {
+    return botNotRequired('EVENT_CANCELED');
+  }
+
+  if (input.callRecorderPreference === CallRecorderPreference.OFF) {
+    return botNotRequired('PREFERENCE_OFF');
+  }
+
+  if (!isNonEmptyString(input.conferenceLinkUrl)) {
+    return botNotRequired('MISSING_CONFERENCE_LINK');
+  }
+
+  if (
+    !isCalendarEventInFuture({
+      startsAt: input.startsAt,
+      endsAt: input.endsAt,
+      now,
+    })
+  ) {
+    return botNotRequired('EVENT_NOT_UPCOMING');
+  }
+
+  return botRequired('RECORDING_ENABLED');
+};
+
+const isCalendarEventInFuture = ({
+  startsAt,
+  endsAt,
+  now,
+}: {
+  startsAt: string | undefined;
+  endsAt: string | undefined;
+  now: Date;
+}): boolean => {
+  const reference = endsAt ?? startsAt;
+
+  if (!isNonEmptyString(reference)) {
+    return false;
+  }
+
+  const referenceTime = new Date(reference).getTime();
+
+  if (Number.isNaN(referenceTime)) {
+    return false;
+  }
+
+  return referenceTime > now.getTime();
+};
+
+const botRequired = (
+  reason: CallRecorderPolicyRequiredReason,
+): CallRecorderPolicyResult => ({ shouldRequestBot: true, reason });
+
+const botNotRequired = (
+  reason: CallRecorderPolicyNotRequiredReason,
+): CallRecorderPolicyResult => ({ shouldRequestBot: false, reason });

package/src/logic-functions/domain/should-complete-call-recording-ingestion.util.ts

@@ -0,0 +1,32 @@
+import { CallRecordingStatus } from 'src/logic-functions/constants/call-recording-status';
+import { type FilesFieldValue } from 'src/logic-functions/types/files-field-value.type';
+import { computeCallRecordingCharge } from 'src/logic-functions/domain/compute-call-recording-charge.util';
+import { isCallRecordingIngestionComplete } from 'src/logic-functions/domain/is-call-recording-ingestion-complete.util';
+import { type CallRecordingUpdateFields } from 'src/logic-functions/types/call-recording-update-fields.type';
+
+export const shouldCompleteCallRecordingIngestion = ({
+  current,
+  updateData,
+}: {
+  current: {
+    status?: string;
+    startedAt?: string;
+    endedAt?: string;
+    transcript?: unknown;
+    audio?: FilesFieldValue;
+    video?: FilesFieldValue;
+  };
+  updateData: CallRecordingUpdateFields;
+}): boolean =>
+  current.status !== CallRecordingStatus.COMPLETED &&
+  current.status !== CallRecordingStatus.FAILED &&
+  updateData.status !== CallRecordingStatus.FAILED &&
+  computeCallRecordingCharge({
+    startedAt: updateData.startedAt ?? current.startedAt,
+    endedAt: updateData.endedAt ?? current.endedAt,
+  }) !== undefined &&
+  isCallRecordingIngestionComplete({
+    transcript: updateData.transcript ?? current.transcript,
+    audio: updateData.audio ?? current.audio,
+    video: updateData.video ?? current.video,
+  });

package/src/logic-functions/flows/__tests__/charge-completed-call-recording.test.ts

@@ -0,0 +1,45 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { chargeCompletedCallRecording } from 'src/logic-functions/flows/charge-completed-call-recording.util';
+
+const chargeCreditsMock = vi.hoisted(() => vi.fn());
+
+vi.mock('twenty-sdk/billing', () => ({
+  chargeCredits: chargeCreditsMock,
+}));
+
+describe('chargeCompletedCallRecording', () => {
+  beforeEach(() => {
+    vi.spyOn(console, 'warn').mockImplementation(() => {});
+    chargeCreditsMock.mockReset();
+    chargeCreditsMock.mockResolvedValue(undefined);
+  });
+
+  it('charges prorated micro-credits with the recording duration in minutes', async () => {
+    await chargeCompletedCallRecording({
+      callRecordingId: 'call-recording-1',
+      startedAt: '2026-06-10T09:00:00.000Z',
+      endedAt: '2026-06-10T09:30:00.000Z',
+    });
+
+    expect(chargeCreditsMock).toHaveBeenCalledWith({
+      creditsUsedMicro: 500_000,
+      quantity: 30,
+      operationType: 'CALL_RECORDING',
+      resourceContext: 'recall',
+    });
+  });
+
+  it('skips and warns loudly when timestamps are unusable', async () => {
+    await chargeCompletedCallRecording({
+      callRecordingId: 'call-recording-1',
+      startedAt: undefined,
+      endedAt: '2026-06-10T09:30:00.000Z',
+    });
+
+    expect(chargeCreditsMock).not.toHaveBeenCalled();
+    expect(console.warn).toHaveBeenCalledWith(
+      expect.stringContaining('will not be billed'),
+    );
+  });
+});

package/src/logic-functions/flows/__tests__/complete-and-charge-call-recording.test.ts

@@ -0,0 +1,61 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+const completeCallRecordingIngestionMock = vi.hoisted(() => vi.fn());
+const chargeCompletedCallRecordingMock = vi.hoisted(() => vi.fn());
+
+vi.mock(
+  'src/logic-functions/data/complete-call-recording-ingestion.util',
+  () => ({
+    completeCallRecordingIngestion: completeCallRecordingIngestionMock,
+  }),
+);
+
+vi.mock(
+  'src/logic-functions/flows/charge-completed-call-recording.util',
+  () => ({
+    chargeCompletedCallRecording: chargeCompletedCallRecordingMock,
+  }),
+);
+
+import { completeAndChargeCallRecording } from 'src/logic-functions/flows/complete-and-charge-call-recording.util';
+
+describe('completeAndChargeCallRecording', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('charges exactly once when this path wins the completion claim', async () => {
+    completeCallRecordingIngestionMock.mockResolvedValue(true);
+
+    const claimed = await completeAndChargeCallRecording({} as never, {
+      id: 'call-recording-1',
+      startedAt: '2026-06-10T12:00:00.000Z',
+      endedAt: '2026-06-10T13:00:00.000Z',
+    });
+
+    expect(claimed).toBe(true);
+    expect(completeCallRecordingIngestionMock).toHaveBeenCalledWith(
+      {},
+      { id: 'call-recording-1' },
+    );
+    expect(chargeCompletedCallRecordingMock).toHaveBeenCalledTimes(1);
+    expect(chargeCompletedCallRecordingMock).toHaveBeenCalledWith({
+      callRecordingId: 'call-recording-1',
+      startedAt: '2026-06-10T12:00:00.000Z',
+      endedAt: '2026-06-10T13:00:00.000Z',
+    });
+  });
+
+  it('does not charge when another path already completed the recording', async () => {
+    completeCallRecordingIngestionMock.mockResolvedValue(false);
+
+    const claimed = await completeAndChargeCallRecording({} as never, {
+      id: 'call-recording-1',
+      startedAt: '2026-06-10T12:00:00.000Z',
+      endedAt: '2026-06-10T13:00:00.000Z',
+    });
+
+    expect(claimed).toBe(false);
+    expect(chargeCompletedCallRecordingMock).not.toHaveBeenCalled();
+  });
+});