@twentyhq/call-recorder 1.0.0

package/src/logic-functions/recall-api/__tests__/verify-recall-webhook-signature.test.ts

@@ -0,0 +1,122 @@
+import { createHmac } from 'crypto';
+
+import { describe, expect, it } from 'vitest';
+
+import { verifyRecallWebhookSignature } from 'src/logic-functions/recall-api/verify-recall-webhook-signature.util';
+
+const SECRET_BYTES = Buffer.from('test-secret-abc123');
+const SECRET = `whsec_${SECRET_BYTES.toString('base64')}`;
+const WEBHOOK_ID = 'msg_123';
+const WEBHOOK_TIMESTAMP = '1760000000';
+const NOW = new Date(Number(WEBHOOK_TIMESTAMP) * 1000);
+
+const sign = (body: string): string =>
+  createHmac('sha256', SECRET_BYTES)
+    .update(`${WEBHOOK_ID}.${WEBHOOK_TIMESTAMP}.${body}`)
+    .digest('base64');
+
+describe('verifyRecallWebhookSignature', () => {
+  it('accepts valid Recall webhook-* signature headers', () => {
+    const body = JSON.stringify({ event: 'recording.done' });
+
+    const result = verifyRecallWebhookSignature({
+      rawBody: body,
+      secret: SECRET,
+      now: NOW,
+      headers: {
+        'webhook-id': WEBHOOK_ID,
+        'webhook-timestamp': WEBHOOK_TIMESTAMP,
+        'webhook-signature': `v1,${sign(body)}`,
+      },
+    });
+
+    expect(result).toEqual({ valid: true });
+  });
+
+  it('accepts valid svix-* signature headers', () => {
+    const body = JSON.stringify({ event: 'recording.done' });
+
+    const result = verifyRecallWebhookSignature({
+      rawBody: body,
+      secret: SECRET,
+      now: NOW,
+      headers: {
+        'svix-id': WEBHOOK_ID,
+        'svix-timestamp': WEBHOOK_TIMESTAMP,
+        'svix-signature': `v1,${sign(body)}`,
+      },
+    });
+
+    expect(result).toEqual({ valid: true });
+  });
+
+  it('rejects deliveries whose timestamp is outside of the tolerance', () => {
+    const body = JSON.stringify({ event: 'recording.done' });
+
+    const result = verifyRecallWebhookSignature({
+      rawBody: body,
+      secret: SECRET,
+      now: new Date(Number(WEBHOOK_TIMESTAMP) * 1000 + 6 * 60 * 1000),
+      headers: {
+        'webhook-id': WEBHOOK_ID,
+        'webhook-timestamp': WEBHOOK_TIMESTAMP,
+        'webhook-signature': `v1,${sign(body)}`,
+      },
+    });
+
+    expect(result).toEqual({
+      valid: false,
+      error: 'Webhook timestamp is outside of the allowed tolerance',
+    });
+  });
+
+  it('rejects non-numeric timestamps', () => {
+    const body = JSON.stringify({ event: 'recording.done' });
+
+    const result = verifyRecallWebhookSignature({
+      rawBody: body,
+      secret: SECRET,
+      now: NOW,
+      headers: {
+        'webhook-id': WEBHOOK_ID,
+        'webhook-timestamp': 'not-a-timestamp',
+        'webhook-signature': `v1,${sign(body)}`,
+      },
+    });
+
+    expect(result).toEqual({
+      valid: false,
+      error: 'Invalid webhook timestamp',
+    });
+  });
+
+  it('rejects missing signature headers', () => {
+    const result = verifyRecallWebhookSignature({
+      rawBody: '{}',
+      secret: SECRET,
+      headers: {},
+    });
+
+    expect(result).toEqual({
+      valid: false,
+      error: 'Missing webhook signature headers',
+    });
+  });
+
+  it('rejects signatures computed from a different body', () => {
+    const body = JSON.stringify({ event: 'recording.done' });
+
+    const result = verifyRecallWebhookSignature({
+      rawBody: JSON.stringify({ event: 'recording.failed' }),
+      secret: SECRET,
+      now: NOW,
+      headers: {
+        'webhook-id': WEBHOOK_ID,
+        'webhook-timestamp': WEBHOOK_TIMESTAMP,
+        'webhook-signature': `v1,${sign(body)}`,
+      },
+    });
+
+    expect(result.valid).toBe(false);
+  });
+});

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

@@ -0,0 +1,28 @@
+import { type RecallBotRemovalResult } from 'src/logic-functions/types/recall-bot-operation-result.type';
+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 const cancelRecallBot = async ({
+  externalBotId,
+}: {
+  externalBotId: string;
+}): Promise<RecallBotRemovalResult> => {
+  const configResult = getRecallApiConfig();
+
+  if (!configResult.success) {
+    return { ok: false, status: null, errorMessage: configResult.error };
+  }
+
+  const result = await recallBotApiRequest<undefined>({
+    config: configResult.config,
+    path: `/bot/${externalBotId}/`,
+    method: 'DELETE',
+    allowNotFound: true,
+  });
+
+  if (!result.ok) {
+    return result;
+  }
+
+  return { ok: true };
+};

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

@@ -0,0 +1,47 @@
+import { isString } from '@sniptt/guards';
+
+import { type RecallBotOperationFailure } from 'src/logic-functions/types/recall-bot-operation-result.type';
+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';
+
+type CreateAsyncRecallTranscriptResult =
+  | { ok: true; transcriptId: string }
+  | RecallBotOperationFailure;
+
+export const createAsyncRecallTranscript = async ({
+  externalRecordingId,
+}: {
+  externalRecordingId: string;
+}): Promise<CreateAsyncRecallTranscriptResult> => {
+  const configResult = getRecallApiConfig();
+
+  if (!configResult.success) {
+    return { ok: false, status: null, errorMessage: configResult.error };
+  }
+
+  const result = await recallBotApiRequest<{ id?: unknown }>({
+    config: configResult.config,
+    path: `/recording/${externalRecordingId}/create_transcript/`,
+    method: 'POST',
+    body: {
+      provider: { recallai_async: { language_code: 'auto' } },
+      diarization: { use_separate_streams_when_available: true },
+    },
+    maxAttempts: 1,
+  });
+
+  if (!result.ok) {
+    return result;
+  }
+
+  if (!isString(result.data?.id)) {
+    return {
+      ok: false,
+      status: null,
+      errorMessage:
+        'Recall API created a transcript but the response did not include a transcript id',
+    };
+  }
+
+  return { ok: true, transcriptId: result.data.id };
+};

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

@@ -0,0 +1,28 @@
+import { type RecallBotRemovalResult } from 'src/logic-functions/types/recall-bot-operation-result.type';
+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 const ejectRecallBot = async ({
+  externalBotId,
+}: {
+  externalBotId: string;
+}): Promise<RecallBotRemovalResult> => {
+  const configResult = getRecallApiConfig();
+
+  if (!configResult.success) {
+    return { ok: false, status: null, errorMessage: configResult.error };
+  }
+
+  const result = await recallBotApiRequest<undefined>({
+    config: configResult.config,
+    path: `/bot/${externalBotId}/leave_call/`,
+    method: 'POST',
+    allowNotFound: true,
+  });
+
+  if (!result.ok) {
+    return result;
+  }
+
+  return { ok: true };
+};

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

@@ -0,0 +1,149 @@
+import { isArray, isUndefined } from '@sniptt/guards';
+
+import { CallRecordingStatus } from 'src/logic-functions/constants/call-recording-status';
+import { asRecord } from 'src/logic-functions/utils/as-record.util';
+import { getString } from 'src/logic-functions/utils/get-string.util';
+import { mapRecallStatusCodeToCallRecordingStatus } from 'src/logic-functions/domain/map-recall-status-code-to-call-recording-status.util';
+import { normalizeRecallTimestamp } from 'src/logic-functions/recall-api/normalize-recall-timestamp.util';
+
+export type RecallBotConvergence = {
+  status: CallRecordingStatus | undefined;
+  failureReason: string | undefined;
+  startedAt: string | undefined;
+  endedAt: string | undefined;
+  externalRecordingId: string | undefined;
+  isRecallRecordingDone: boolean;
+};
+
+type RecallBotStatusChange = {
+  code: string;
+  createdAt: string | undefined;
+};
+
+// Derives the state a full webhook history would have produced from GET /bot.
+export const extractRecallBotConvergence = (
+  bot: Record<string, unknown>,
+): RecallBotConvergence => {
+  const statusChanges = extractStatusChanges(bot);
+  const latestStatusChange = getLatestStatusChange(statusChanges);
+  const status = mapRecallStatusCodeToCallRecordingStatus(
+    latestStatusChange?.code,
+  );
+  const recording = extractFirstRecording(bot);
+
+  return {
+    status,
+    failureReason:
+      status === CallRecordingStatus.FAILED
+        ? latestStatusChange?.code
+        : undefined,
+    startedAt: normalizeRecallTimestamp(
+      recording?.startedAt ??
+        findStatusChangeTimestamp(statusChanges, 'in_call_recording'),
+    ),
+    endedAt: normalizeRecallTimestamp(
+      recording?.completedAt ??
+        findStatusChangeTimestamp(statusChanges, 'call_ended'),
+    ),
+    externalRecordingId: recording?.id,
+    isRecallRecordingDone:
+      !isUndefined(recording?.completedAt) ||
+      statusChanges.some((statusChange) => statusChange.code === 'done'),
+  };
+};
+
+const extractStatusChanges = (
+  bot: Record<string, unknown>,
+): RecallBotStatusChange[] => {
+  if (!isArray(bot.status_changes)) {
+    return [];
+  }
+
+  return bot.status_changes.flatMap((statusChange: unknown) => {
+    const code = getString(asRecord(statusChange)?.code);
+
+    if (isUndefined(code)) {
+      return [];
+    }
+
+    return [{ code, createdAt: getString(asRecord(statusChange)?.created_at) }];
+  });
+};
+
+const getLatestStatusChange = (
+  statusChanges: RecallBotStatusChange[],
+): RecallBotStatusChange | undefined =>
+  statusChanges.reduce<RecallBotStatusChange | undefined>(
+    (latestStatusChange, statusChange) => {
+      if (isUndefined(latestStatusChange)) {
+        return statusChange;
+      }
+
+      const statusChangeTime = getStatusChangeTime(statusChange);
+      const latestStatusChangeTime = getStatusChangeTime(latestStatusChange);
+
+      if (
+        isUndefined(statusChangeTime) &&
+        isUndefined(latestStatusChangeTime)
+      ) {
+        return statusChange;
+      }
+
+      if (isUndefined(statusChangeTime)) {
+        return latestStatusChange;
+      }
+
+      if (isUndefined(latestStatusChangeTime)) {
+        return statusChange;
+      }
+
+      return statusChangeTime >= latestStatusChangeTime
+        ? statusChange
+        : latestStatusChange;
+    },
+    undefined,
+  );
+
+const getStatusChangeTime = (
+  statusChange: RecallBotStatusChange,
+): number | undefined => {
+  const normalizedTimestamp = normalizeRecallTimestamp(statusChange.createdAt);
+
+  if (isUndefined(normalizedTimestamp)) {
+    return undefined;
+  }
+
+  return new Date(normalizedTimestamp).getTime();
+};
+
+const extractFirstRecording = (
+  bot: Record<string, unknown>,
+):
+  | {
+      id: string | undefined;
+      startedAt: string | undefined;
+      completedAt: string | undefined;
+    }
+  | undefined => {
+  if (!isArray(bot.recordings)) {
+    return undefined;
+  }
+
+  const recording = asRecord(bot.recordings[0]);
+
+  if (isUndefined(recording)) {
+    return undefined;
+  }
+
+  return {
+    id: getString(recording.id),
+    startedAt: getString(recording.started_at),
+    completedAt: getString(recording.completed_at),
+  };
+};
+
+const findStatusChangeTimestamp = (
+  statusChanges: RecallBotStatusChange[],
+  code: string,
+): string | undefined =>
+  statusChanges.find((statusChange) => statusChange.code === code)?.createdAt;

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

@@ -0,0 +1,10 @@
+import { getString } from 'src/logic-functions/utils/get-string.util';
+
+export type RecallBotResponse = {
+  id?: unknown;
+  bot_id?: unknown;
+};
+
+export const extractRecallBotId = (
+  response: RecallBotResponse | undefined,
+): string | undefined => getString(response?.id) ?? getString(response?.bot_id);

package/src/logic-functions/recall-api/extract-recall-media-urls.util.ts

@@ -0,0 +1,30 @@
+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';
+
+export type RecallMediaUrls = {
+  videoUrl: string | undefined;
+  audioUrl: string | undefined;
+};
+
+// Pre-signed URLs expire within hours; always re-extract from a fresh GET /recording.
+export const extractRecallMediaUrls = (
+  recording: Record<string, unknown>,
+): RecallMediaUrls => {
+  const mediaShortcuts = asRecord(recording.media_shortcuts);
+
+  return {
+    videoUrl: extractArtifactDownloadUrl(mediaShortcuts, 'video_mixed'),
+    audioUrl: extractArtifactDownloadUrl(mediaShortcuts, 'audio_mixed'),
+  };
+};
+
+// v1.11 exposes download_url flat on the artifact; older artifacts nest it under data.
+const extractArtifactDownloadUrl = (
+  mediaShortcuts: Record<string, unknown> | undefined,
+  artifactKey: string,
+): string | undefined =>
+  getString(getRecordAtPath(mediaShortcuts, [artifactKey, 'download_url'])) ??
+  getString(
+    getRecordAtPath(mediaShortcuts, [artifactKey, 'data', 'download_url']),
+  );

package/src/logic-functions/recall-api/extract-twenty-workspace-id-from-recall-webhook.util.ts

@@ -0,0 +1,8 @@
+import { getRecallWebhookBotMetadata } from 'src/logic-functions/recall-api/get-recall-webhook-bot-metadata.util';
+import { type RecallWebhookBody } from 'src/logic-functions/recall-api/parse-recall-webhook-event.util';
+import { getString } from 'src/logic-functions/utils/get-string.util';
+
+export const extractTwentyWorkspaceIdFromRecallWebhook = (
+  body: RecallWebhookBody,
+): string | undefined =>
+  getString(getRecallWebhookBotMetadata(body)?.twentyWorkspaceId);

package/src/logic-functions/recall-api/get-recall-api-config.util.ts

@@ -0,0 +1,59 @@
+import { isUndefined } from '@sniptt/guards';
+
+import { CALL_RECORDER_NAME_ENV_VAR_NAME } from 'src/logic-functions/constants/call-recorder-name-env-var-name';
+import { DEFAULT_CALL_RECORDER_NAME } from 'src/logic-functions/constants/default-call-recorder-name';
+import { DEFAULT_RECALL_REGION } from 'src/logic-functions/constants/default-recall-region';
+import { RECALL_API_KEY_ENV_VAR_NAME } from 'src/logic-functions/constants/recall-api-key-env-var-name';
+import { RECALL_REGION_ENV_VAR_NAME } from 'src/logic-functions/constants/recall-region-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 type RecallApiConfig = {
+  apiKey: string;
+  baseUrl: string;
+  botName: string;
+};
+
+export const getRecallApiConfig = ():
+  | {
+      success: true;
+      config: RecallApiConfig;
+    }
+  | {
+      success: false;
+      error: string;
+    } => {
+  const apiKey = normalizeOptionalString(
+    getApplicationVariableValue(RECALL_API_KEY_ENV_VAR_NAME),
+  );
+
+  if (isUndefined(apiKey)) {
+    return {
+      success: false,
+      error:
+        'RECALL_API_KEY server variable is not set. A server admin must set it on the Call Recorder application registration before scheduling bots.',
+    };
+  }
+
+  const region =
+    normalizeOptionalString(
+      getApplicationVariableValue(RECALL_REGION_ENV_VAR_NAME),
+    ) ?? DEFAULT_RECALL_REGION;
+  const botName =
+    normalizeOptionalString(
+      getApplicationVariableValue(CALL_RECORDER_NAME_ENV_VAR_NAME),
+    ) ?? DEFAULT_CALL_RECORDER_NAME;
+
+  return {
+    success: true,
+    config: {
+      apiKey,
+      baseUrl: `https://${region}.recall.ai/api/v1`,
+      botName,
+    },
+  };
+};
+
+const normalizeOptionalString = (
+  value: string | undefined,
+): string | undefined => (isNonEmptyString(value) ? value.trim() : undefined);

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

@@ -0,0 +1,42 @@
+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';
+
+type GetRecallBotResult =
+  | { ok: true; bot: Record<string, unknown> }
+  | RecallBotOperationFailure;
+
+export const getRecallBot = async ({
+  externalBotId,
+}: {
+  externalBotId: string;
+}): Promise<GetRecallBotResult> => {
+  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: `/bot/${externalBotId}/`,
+    method: 'GET',
+  });
+
+  if (!result.ok) {
+    return result;
+  }
+
+  const bot = asRecord(result.data);
+
+  if (bot === undefined) {
+    return {
+      ok: false,
+      status: result.status,
+      errorMessage: 'Recall API returned an empty bot response',
+    };
+  }
+
+  return { ok: true, bot };
+};

package/src/logic-functions/recall-api/get-recall-recording.util.ts

@@ -0,0 +1,31 @@
+import { type RecallBotOperationFailure } from 'src/logic-functions/types/recall-bot-operation-result.type';
+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';
+
+type GetRecallRecordingResult =
+  | { ok: true; recording: Record<string, unknown> }
+  | RecallBotOperationFailure;
+
+export const getRecallRecording = async ({
+  externalRecordingId,
+}: {
+  externalRecordingId: string;
+}): Promise<GetRecallRecordingResult> => {
+  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: `/recording/${externalRecordingId}/`,
+    method: 'GET',
+  });
+
+  if (!result.ok) {
+    return result;
+  }
+
+  return { ok: true, recording: result.data ?? {} };
+};

package/src/logic-functions/recall-api/get-recall-webhook-bot-metadata.util.ts

@@ -0,0 +1,18 @@
+import { type RecallWebhookBody } from 'src/logic-functions/recall-api/parse-recall-webhook-event.util';
+import { asRecord } from 'src/logic-functions/utils/as-record.util';
+import { getRecordAtPath } from 'src/logic-functions/utils/get-record-at-path.util';
+
+// Recall delivers bot metadata under several body shapes per event family; this is the single reader of all of them.
+export const getRecallWebhookBotMetadata = (
+  body: RecallWebhookBody,
+): Record<string, unknown> | undefined => {
+  const data = asRecord(body.data);
+  const bot = asRecord(body.bot);
+
+  return (
+    asRecord(bot?.metadata) ??
+    asRecord(getRecordAtPath(data, ['bot', 'metadata'])) ??
+    asRecord(getRecordAtPath(data, ['recording', 'metadata'])) ??
+    asRecord(data?.metadata)
+  );
+};