@twentyhq/call-recorder 1.0.0

package/src/logic-functions/recall-api/list-recall-transcripts.util.ts

@@ -0,0 +1,141 @@
+import { isArray, isUndefined } from '@sniptt/guards';
+
+import { type RecallBotOperationFailure } from 'src/logic-functions/types/recall-bot-operation-result.type';
+import { asRecord } from 'src/logic-functions/utils/as-record.util';
+import { getString } from 'src/logic-functions/utils/get-string.util';
+import { getRecallApiConfig } from 'src/logic-functions/recall-api/get-recall-api-config.util';
+import { recallBotApiRequest } from 'src/logic-functions/recall-api/recall-bot-api-request.util';
+import { type RecallTranscriptSummary } from 'src/logic-functions/recall-api/recall-transcript-summary.type';
+
+type ListRecallTranscriptsResult =
+  | { ok: true; transcripts: RecallTranscriptSummary[] }
+  | RecallBotOperationFailure;
+
+type RecallTranscriptListResponse = {
+  next?: unknown;
+  results?: unknown;
+};
+
+const RECALL_TRANSCRIPT_LIST_MAX_PAGES = 10;
+
+export const listRecallTranscripts = async ({
+  externalRecordingId,
+}: {
+  externalRecordingId: string;
+}): Promise<ListRecallTranscriptsResult> => {
+  const configResult = getRecallApiConfig();
+
+  if (!configResult.success) {
+    return { ok: false, status: null, errorMessage: configResult.error };
+  }
+
+  const transcripts: RecallTranscriptSummary[] = [];
+  let path: string | undefined = buildListRecallTranscriptsPath({
+    externalRecordingId,
+  });
+
+  for (
+    let pageIndex = 0;
+    !isUndefined(path) && pageIndex < RECALL_TRANSCRIPT_LIST_MAX_PAGES;
+    pageIndex++
+  ) {
+    const result = await recallBotApiRequest<RecallTranscriptListResponse>({
+      config: configResult.config,
+      path,
+      method: 'GET',
+    });
+
+    if (!result.ok) {
+      return result;
+    }
+
+    const pageTranscripts = extractRecallTranscriptSummaries(result.data);
+
+    if (isUndefined(pageTranscripts)) {
+      return {
+        ok: false,
+        status: result.status,
+        errorMessage: 'Recall API returned malformed transcript list',
+      };
+    }
+
+    transcripts.push(...pageTranscripts);
+    path = extractNextPath(result.data, configResult.config.baseUrl);
+  }
+
+  if (!isUndefined(path)) {
+    return {
+      ok: false,
+      status: null,
+      errorMessage: `Recall transcript list exceeded ${RECALL_TRANSCRIPT_LIST_MAX_PAGES} pages`,
+    };
+  }
+
+  return { ok: true, transcripts };
+};
+
+const buildListRecallTranscriptsPath = ({
+  externalRecordingId,
+}: {
+  externalRecordingId: string;
+}): string => {
+  const searchParams = new URLSearchParams({
+    recording_id: externalRecordingId,
+  });
+
+  return `/transcript/?${searchParams.toString()}`;
+};
+
+const extractRecallTranscriptSummaries = (
+  response: RecallTranscriptListResponse | undefined,
+): RecallTranscriptSummary[] | undefined => {
+  if (!isArray(response?.results)) {
+    return undefined;
+  }
+
+  const transcripts: RecallTranscriptSummary[] = [];
+
+  for (const result of response.results) {
+    const transcript = extractRecallTranscriptSummary(result);
+
+    if (isUndefined(transcript)) {
+      return undefined;
+    }
+
+    transcripts.push(transcript);
+  }
+
+  return transcripts;
+};
+
+const extractRecallTranscriptSummary = (
+  transcript: unknown,
+): RecallTranscriptSummary | undefined => {
+  const transcriptRecord = asRecord(transcript);
+  const transcriptId = getString(transcriptRecord?.id);
+
+  if (isUndefined(transcriptRecord) || isUndefined(transcriptId)) {
+    return undefined;
+  }
+
+  const status = asRecord(transcriptRecord.status);
+
+  return {
+    id: transcriptId,
+    statusCode: getString(status?.code),
+    statusSubCode: getString(status?.sub_code),
+  };
+};
+
+const extractNextPath = (
+  response: RecallTranscriptListResponse | undefined,
+  baseUrl: string,
+): string | undefined => {
+  const nextPage = getString(response?.next);
+
+  if (isUndefined(nextPage) || !nextPage.startsWith(baseUrl)) {
+    return undefined;
+  }
+
+  return nextPage.slice(baseUrl.length);
+};

package/src/logic-functions/recall-api/list-scheduled-recall-bots.util.ts

@@ -0,0 +1,106 @@
+import { isString, isUndefined } from '@sniptt/guards';
+
+import { type RecallBotOperationFailure } from 'src/logic-functions/types/recall-bot-operation-result.type';
+import { asRecord } from 'src/logic-functions/utils/as-record.util';
+import { getRecallApiConfig } from 'src/logic-functions/recall-api/get-recall-api-config.util';
+import { recallBotApiRequest } from 'src/logic-functions/recall-api/recall-bot-api-request.util';
+
+export type RecallScheduledBot = {
+  id: string;
+  metadata: Record<string, unknown>;
+};
+
+type RecallBotListResponse = {
+  next?: unknown;
+  results?: unknown;
+};
+
+type ListScheduledRecallBotsResult =
+  | { ok: true; bots: RecallScheduledBot[] }
+  | RecallBotOperationFailure;
+
+const RECALL_BOT_LIST_MAX_PAGES = 10;
+
+export const listScheduledRecallBots = async ({
+  joinAtAfter,
+  joinAtBefore,
+}: {
+  joinAtAfter: string;
+  joinAtBefore: string;
+}): Promise<ListScheduledRecallBotsResult> => {
+  const configResult = getRecallApiConfig();
+
+  if (!configResult.success) {
+    return { ok: false, status: null, errorMessage: configResult.error };
+  }
+
+  const bots: RecallScheduledBot[] = [];
+  let path: string | undefined = `/bot/?join_at_after=${encodeURIComponent(
+    joinAtAfter,
+  )}&join_at_before=${encodeURIComponent(joinAtBefore)}`;
+
+  for (
+    let pageIndex = 0;
+    !isUndefined(path) && pageIndex < RECALL_BOT_LIST_MAX_PAGES;
+    pageIndex++
+  ) {
+    const result = await recallBotApiRequest<RecallBotListResponse>({
+      config: configResult.config,
+      path,
+      method: 'GET',
+    });
+
+    if (!result.ok) {
+      return result;
+    }
+
+    bots.push(...extractRecallBots(result.data));
+    path = extractNextPath(result.data, configResult.config.baseUrl);
+  }
+
+  if (!isUndefined(path)) {
+    return {
+      ok: false,
+      status: null,
+      errorMessage: `Recall bot list exceeded ${RECALL_BOT_LIST_MAX_PAGES} pages`,
+    };
+  }
+
+  return { ok: true, bots };
+};
+
+const extractRecallBots = (
+  response: RecallBotListResponse | undefined,
+): RecallScheduledBot[] => {
+  if (!Array.isArray(response?.results)) {
+    return [];
+  }
+
+  return response.results.flatMap((candidate: unknown) => {
+    const bot = asRecord(candidate);
+
+    if (isUndefined(bot) || !isString(bot.id)) {
+      return [];
+    }
+
+    return [
+      {
+        id: bot.id,
+        metadata: asRecord(bot.metadata) ?? {},
+      },
+    ];
+  });
+};
+
+const extractNextPath = (
+  response: RecallBotListResponse | undefined,
+  baseUrl: string,
+): string | undefined => {
+  const next = response?.next;
+
+  if (!isString(next) || !next.startsWith(baseUrl)) {
+    return undefined;
+  }
+
+  return next.slice(baseUrl.length);
+};

package/src/logic-functions/recall-api/normalize-recall-timestamp.util.ts

@@ -0,0 +1,14 @@
+import { isUndefined } from '@sniptt/guards';
+
+// Twenty rejects Recall's microsecond precision; truncate to millisecond ISO.
+export const normalizeRecallTimestamp = (
+  value: string | undefined,
+): string | undefined => {
+  if (isUndefined(value)) {
+    return undefined;
+  }
+
+  const parsed = new Date(value);
+
+  return Number.isNaN(parsed.getTime()) ? undefined : parsed.toISOString();
+};

package/src/logic-functions/recall-api/parse-recall-webhook-event.util.ts

@@ -0,0 +1,88 @@
+import { isUndefined } from '@sniptt/guards';
+
+import { getRecallWebhookBotMetadata } from 'src/logic-functions/recall-api/get-recall-webhook-bot-metadata.util';
+import { asRecord } from 'src/logic-functions/utils/as-record.util';
+import { getRecordAtPath } from 'src/logic-functions/utils/get-record-at-path.util';
+import { getString } from 'src/logic-functions/utils/get-string.util';
+import { normalizeRecallTimestamp } from 'src/logic-functions/recall-api/normalize-recall-timestamp.util';
+
+export type RecallWebhookBody = {
+  event?: unknown;
+  type?: unknown;
+  data?: unknown;
+  bot?: unknown;
+};
+
+export type RecallWebhookEvent = {
+  event: string;
+  statusCode: string | undefined;
+  statusTimestamp: string | undefined;
+  externalBotId: string | undefined;
+  externalRecordingId: string | undefined;
+  callRecordingIdFromMetadata: string | undefined;
+  recordingStartedAt: string | undefined;
+  recordingEndedAt: string | undefined;
+  transcriptId: string | undefined;
+  transcriptFailureSubCode: string | undefined;
+};
+
+// The only reader of raw webhook payloads; Recall delivers several body shapes per event family.
+export const parseRecallWebhookEvent = (
+  body: RecallWebhookBody,
+): RecallWebhookEvent | undefined => {
+  const event = getString(body.event) ?? getString(body.type);
+
+  if (isUndefined(event)) {
+    return undefined;
+  }
+
+  const data = asRecord(body.data);
+  const bot = asRecord(body.bot);
+
+  return {
+    event,
+    statusCode:
+      getString(getRecordAtPath(data, ['status', 'code'])) ??
+      getString(getRecordAtPath(data, ['data', 'code'])) ??
+      getString(getRecordAtPath(bot, ['status', 'code'])) ??
+      getStatusCodeFromEventName(event),
+    statusTimestamp: normalizeRecallTimestamp(
+      getString(getRecordAtPath(data, ['status', 'created_at'])) ??
+        getString(getRecordAtPath(data, ['data', 'updated_at'])) ??
+        getString(getRecordAtPath(bot, ['status', 'created_at'])),
+    ),
+    externalBotId:
+      getString(data?.bot_id) ??
+      getString(getRecordAtPath(data, ['bot', 'id'])) ??
+      getString(getRecordAtPath(data, ['recording', 'bot_id'])) ??
+      getString(getRecordAtPath(data, ['recording', 'bot', 'id'])) ??
+      getString(bot?.id),
+    externalRecordingId:
+      getString(getRecordAtPath(data, ['status', 'recording_id'])) ??
+      getString(getRecordAtPath(data, ['recording', 'id'])) ??
+      getString(data?.recording_id),
+    callRecordingIdFromMetadata: getString(
+      getRecallWebhookBotMetadata(body)?.twentyCallRecordingId,
+    ),
+    recordingStartedAt: normalizeRecallTimestamp(
+      getString(getRecordAtPath(data, ['recording', 'started_at'])),
+    ),
+    recordingEndedAt: normalizeRecallTimestamp(
+      getString(getRecordAtPath(data, ['recording', 'completed_at'])),
+    ),
+    transcriptId: getString(getRecordAtPath(data, ['transcript', 'id'])),
+    transcriptFailureSubCode: getString(
+      getRecordAtPath(data, ['status', 'sub_code']),
+    ),
+  };
+};
+
+const getStatusCodeFromEventName = (event: string): string | undefined => {
+  if (!event.startsWith('bot.')) {
+    return undefined;
+  }
+
+  const statusCode = event.slice('bot.'.length);
+
+  return statusCode === 'status_change' ? undefined : statusCode;
+};

package/src/logic-functions/recall-api/recall-bot-api-request.util.ts

@@ -0,0 +1,165 @@
+import { isUndefined } from '@sniptt/guards';
+
+import { RECALL_API_MAX_ATTEMPTS } from 'src/logic-functions/constants/recall-api-max-attempts';
+import { RECALL_API_RETRY_DELAY_MS } from 'src/logic-functions/constants/recall-api-retry-delay-ms';
+import { type RecallApiConfig } from 'src/logic-functions/recall-api/get-recall-api-config.util';
+
+type RecallBotApiRequestArgs = {
+  config: RecallApiConfig;
+  path: string;
+  method: 'GET' | 'POST' | 'PATCH' | 'DELETE';
+  body?: unknown;
+  allowNotFound?: boolean;
+  maxAttempts?: number;
+};
+
+type RecallBotApiRequestResult<TData> =
+  | {
+      ok: true;
+      status: number;
+      data: TData;
+    }
+  | {
+      ok: false;
+      status: number | null;
+      errorMessage: string;
+    };
+
+// Bot creates tolerate retries because duplicates stay unclaimed and get reaped.
+// Callers that cannot retry idempotently can lower maxAttempts.
+export const recallBotApiRequest = async <TData>(
+  requestArgs: RecallBotApiRequestArgs,
+): Promise<RecallBotApiRequestResult<TData>> => {
+  const maxAttempts = requestArgs.maxAttempts ?? RECALL_API_MAX_ATTEMPTS;
+
+  for (let attemptNumber = 1; ; attemptNumber++) {
+    const { result, isRetryable } =
+      await performRecallBotApiRequestAttempt<TData>(requestArgs);
+
+    if (!isRetryable || attemptNumber >= maxAttempts) {
+      return result;
+    }
+
+    await sleep(RECALL_API_RETRY_DELAY_MS * attemptNumber);
+  }
+};
+
+const performRecallBotApiRequestAttempt = async <TData>({
+  config,
+  path,
+  method,
+  body,
+  allowNotFound = false,
+}: RecallBotApiRequestArgs): Promise<{
+  result: RecallBotApiRequestResult<TData>;
+  isRetryable: boolean;
+}> => {
+  let response: Response;
+
+  try {
+    response = await fetch(`${config.baseUrl}${path}`, {
+      method,
+      headers: {
+        Authorization: buildRecallApiAuthorizationHeader(config.apiKey),
+        ...(isUndefined(body) ? {} : { 'Content-Type': 'application/json' }),
+      },
+      ...(isUndefined(body) ? {} : { body: JSON.stringify(body) }),
+    });
+  } catch (error) {
+    return {
+      isRetryable: true,
+      result: {
+        ok: false,
+        status: null,
+        errorMessage: `Recall API request failed: ${
+          error instanceof Error ? error.message : String(error)
+        }`,
+      },
+    };
+  }
+
+  if (allowNotFound && response.status === 404) {
+    return {
+      isRetryable: false,
+      result: {
+        ok: true,
+        status: response.status,
+        data: undefined as TData,
+      },
+    };
+  }
+
+  if (response.status === 204) {
+    return {
+      isRetryable: false,
+      result: {
+        ok: true,
+        status: response.status,
+        data: undefined as TData,
+      },
+    };
+  }
+
+  if (!response.ok) {
+    return {
+      isRetryable: isRetryableRecallApiStatus(response.status),
+      result: {
+        ok: false,
+        status: response.status,
+        errorMessage: await extractRecallApiErrorMessage(response),
+      },
+    };
+  }
+
+  try {
+    return {
+      isRetryable: false,
+      result: {
+        ok: true,
+        status: response.status,
+        data: (await response.json()) as TData,
+      },
+    };
+  } catch (error) {
+    return {
+      isRetryable: false,
+      result: {
+        ok: false,
+        status: response.status,
+        errorMessage: `Recall API returned a non-JSON response: ${
+          error instanceof Error ? error.message : String(error)
+        }`,
+      },
+    };
+  }
+};
+
+const isRetryableRecallApiStatus = (status: number): boolean =>
+  status === 429 || status >= 500;
+
+const sleep = (delayMs: number): Promise<void> =>
+  new Promise((resolve) => {
+    setTimeout(resolve, delayMs);
+  });
+
+const buildRecallApiAuthorizationHeader = (apiKey: string): string => {
+  const trimmedApiKey = apiKey.trim();
+
+  return trimmedApiKey.toLowerCase().startsWith('token ')
+    ? trimmedApiKey
+    : `Token ${trimmedApiKey}`;
+};
+
+const extractRecallApiErrorMessage = async (
+  response: Response,
+): Promise<string> => {
+  const fallback = `Recall API responded with HTTP ${response.status}`;
+
+  try {
+    const body = (await response.json()) as unknown;
+
+    return `${fallback}: ${JSON.stringify(body)}`;
+  } catch {
+    return fallback;
+  }
+};

package/src/logic-functions/recall-api/recall-transcript-summary.type.ts

@@ -0,0 +1,5 @@
+export type RecallTranscriptSummary = {
+  id: string;
+  statusCode: string | undefined;
+  statusSubCode: string | undefined;
+};

package/src/logic-functions/recall-api/reschedule-recall-bot.util.ts

@@ -0,0 +1,56 @@
+import { isUndefined } from '@sniptt/guards';
+
+import { getRecallBotAutomaticLeave } from 'src/logic-functions/constants/recall-bot-automatic-leave';
+import { getRecallBotRecordingConfig } from 'src/logic-functions/constants/recall-bot-recording-config';
+import { type RecallBotScheduleResult } from 'src/logic-functions/types/recall-bot-operation-result.type';
+import {
+  extractRecallBotId,
+  type RecallBotResponse,
+} from 'src/logic-functions/recall-api/extract-recall-bot-id.util';
+import { getRecallApiConfig } from 'src/logic-functions/recall-api/get-recall-api-config.util';
+import { recallBotApiRequest } from 'src/logic-functions/recall-api/recall-bot-api-request.util';
+import { type ScheduleRecallBotArgs } from 'src/logic-functions/recall-api/schedule-recall-bot.util';
+
+type RescheduleRecallBotArgs = ScheduleRecallBotArgs & {
+  externalBotId: string;
+};
+
+export const rescheduleRecallBot = async ({
+  externalBotId,
+  meetingUrl,
+  joinAt,
+  metadata,
+}: RescheduleRecallBotArgs): Promise<RecallBotScheduleResult> => {
+  const configResult = getRecallApiConfig();
+
+  if (!configResult.success) {
+    return { ok: false, status: null, errorMessage: configResult.error };
+  }
+
+  const automaticLeave = getRecallBotAutomaticLeave();
+
+  const result = await recallBotApiRequest<RecallBotResponse>({
+    config: configResult.config,
+    path: `/bot/${externalBotId}/`,
+    method: 'PATCH',
+    body: {
+      meeting_url: meetingUrl,
+      join_at: joinAt,
+      bot_name: configResult.config.botName,
+      ...(isUndefined(automaticLeave)
+        ? {}
+        : { automatic_leave: automaticLeave }),
+      recording_config: getRecallBotRecordingConfig(),
+      metadata,
+    },
+  });
+
+  if (!result.ok) {
+    return result;
+  }
+
+  return {
+    ok: true,
+    externalBotId: extractRecallBotId(result.data) ?? externalBotId,
+  };
+};

package/src/logic-functions/recall-api/retrieve-recall-transcript.util.ts

@@ -0,0 +1,71 @@
+import { isUndefined } from '@sniptt/guards';
+
+import { type RecallBotOperationFailure } from 'src/logic-functions/types/recall-bot-operation-result.type';
+import { asRecord } from 'src/logic-functions/utils/as-record.util';
+import { getRecallApiConfig } from 'src/logic-functions/recall-api/get-recall-api-config.util';
+import { getString } from 'src/logic-functions/utils/get-string.util';
+import { recallBotApiRequest } from 'src/logic-functions/recall-api/recall-bot-api-request.util';
+
+export type RecallTranscriptDetails = {
+  downloadUrl: string | undefined;
+  statusCode: string | undefined;
+  statusSubCode: string | undefined;
+};
+
+type RetrieveRecallTranscriptResult =
+  | { ok: true; transcript: RecallTranscriptDetails }
+  | RecallBotOperationFailure;
+
+export const retrieveRecallTranscript = async ({
+  transcriptId,
+}: {
+  transcriptId: string;
+}): Promise<RetrieveRecallTranscriptResult> => {
+  const configResult = getRecallApiConfig();
+
+  if (!configResult.success) {
+    return { ok: false, status: null, errorMessage: configResult.error };
+  }
+
+  const result = await recallBotApiRequest<Record<string, unknown>>({
+    config: configResult.config,
+    path: `/transcript/${transcriptId}/`,
+    method: 'GET',
+  });
+
+  if (!result.ok) {
+    return result;
+  }
+
+  const transcript = extractRecallTranscriptDetails(result.data);
+
+  if (isMalformedRecallTranscriptDetails(transcript)) {
+    return {
+      ok: false,
+      status: result.status,
+      errorMessage: 'Recall API returned malformed transcript details',
+    };
+  }
+
+  return { ok: true, transcript };
+};
+
+const extractRecallTranscriptDetails = (
+  response: Record<string, unknown> | undefined,
+): RecallTranscriptDetails => {
+  const data = asRecord(response?.data);
+  const status = asRecord(response?.status);
+
+  return {
+    downloadUrl: getString(data?.download_url),
+    statusCode: getString(status?.code),
+    statusSubCode: getString(status?.sub_code),
+  };
+};
+
+const isMalformedRecallTranscriptDetails = ({
+  downloadUrl,
+  statusCode,
+}: RecallTranscriptDetails): boolean =>
+  (isUndefined(downloadUrl) && isUndefined(statusCode)) ||
+  (isUndefined(downloadUrl) && statusCode === 'done');