Skip to content

The open alternative to Salesforce, designed for AI.

Import Fathom recording media asynchronously (#25433)

nitin91bbb180339a
diff --git a/packages/twenty-apps/public/fathom/CHANGELOG.md b/packages/twenty-apps/public/fathom/CHANGELOG.md
index d090b3a9fe2..6c0b4e25999 100644
--- a/packages/twenty-apps/public/fathom/CHANGELOG.md
+++ b/packages/twenty-apps/public/fathom/CHANGELOG.md
@@ -2,6 +2,16 @@
All notable changes to this application are documented in this file.
+## Unreleased
+
+- Import available Fathom video, or audio for audio-only recordings, into the
+ Call Recording's media fields when it is within the 500 MB limit.
+- Record why media could not be imported in Fathom's internal import state,
+ skip automatic retries of a settled failure, and let Sync Fathom Call clear
+ it to try again.
+- Hold a recording in Processing until its media lands or is settled as
+ unavailable, rather than completing it as soon as the transcript arrives.
+
## 0.1.0
- Add per-user Fathom OAuth and signed webhook registration.
diff --git a/packages/twenty-apps/public/fathom/README.md b/packages/twenty-apps/public/fathom/README.md
index 4d764fd8e82..591e1508c48 100644
--- a/packages/twenty-apps/public/fathom/README.md
+++ b/packages/twenty-apps/public/fathom/README.md
@@ -6,6 +6,7 @@
- Fathom recordings saved as Call Recordings
- Transcripts, summaries, and action items
+- Recording video, or audio for audio-only calls
- Links to matching calendar events when the match is unambiguous
- Automatic sync for new recordings
- A 31-day import when a Fathom account is connected, and manual imports of
@@ -23,6 +24,16 @@ emails do not need to match.
- Twenty only links a recording to a calendar event when its meeting URL and
scheduled time identify one clear match.
+- Fathom generates the downloadable video in the background, so a recording
+ stays in Processing for a few minutes after its transcript arrives, until its
+ media lands or is settled as unavailable.
+- Media is skipped for recordings above 500 MB, for recordings Fathom has no
+ downloadable media for, and for limited-access shares that the connected
+ account may view but not download. Fathom records the reason internally so
+ automatic syncs do not retry a settled failure.
+- Once a reason is recorded, automatic syncs stop asking Fathom to generate the
+ same file again. Running Sync Fathom Call on that recording clears the reason
+ and tries once more, which is how a re-shared recording gets its media.
- Disconnect and reconnect Fathom after changing the webhook URL or webhook
scopes so Fathom receives the new registration.
diff --git a/packages/twenty-apps/public/fathom/src/__tests__/media-import-ownership.integration-test.ts b/packages/twenty-apps/public/fathom/src/__tests__/media-import-ownership.integration-test.ts
new file mode 100644
index 00000000000..864e93f423e
--- /dev/null
+++ b/packages/twenty-apps/public/fathom/src/__tests__/media-import-ownership.integration-test.ts
@@ -0,0 +1,145 @@
+import { randomUUID } from 'node:crypto';
+import { CoreApiClient } from 'twenty-client-sdk/core';
+import { MetadataApiClient } from 'twenty-client-sdk/metadata';
+import { describe, expect, it } from 'vitest';
+
+import { APPLICATION_UNIVERSAL_IDENTIFIER } from 'src/constants/universal-identifiers';
+import { claimFathomMediaImport } from 'src/logic-functions/utils/claim-fathom-media-import.util';
+import { updateFathomRecordingImport } from 'src/logic-functions/utils/update-fathom-recording-import.util';
+
+const createFathomApplicationCoreApiClient = async (): Promise<CoreApiClient> => {
+ const metadataApiClient = new MetadataApiClient();
+ const applicationsResult = await metadataApiClient.query({
+ findManyApplications: {
+ id: true,
+ universalIdentifier: true,
+ },
+ });
+ const fathomApplication = applicationsResult.findManyApplications.find(
+ (application) =>
+ application.universalIdentifier === APPLICATION_UNIVERSAL_IDENTIFIER,
+ );
+
+ if (!fathomApplication) {
+ throw new Error('Expected the Fathom application to be installed');
+ }
+
+ const applicationTokenResult = await metadataApiClient.mutation({
+ generateApplicationToken: {
+ __args: { applicationId: fathomApplication.id },
+ applicationAccessToken: { token: true },
+ },
+ });
+
+ return new CoreApiClient({
+ headers: {
+ Authorization: `Bearer ${applicationTokenResult.generateApplicationToken.applicationAccessToken.token}`,
+ },
+ });
+};
+
+describe('Fathom recording import ownership', () => {
+ it.each([
+ {
+ changedField: 'owner',
+ fields: { connectedAccountId: randomUUID() },
+ },
+ {
+ changedField: 'download',
+ fields: { mediaDownloadId: randomUUID() },
+ },
+ {
+ changedField: 'claim',
+ fields: { mediaImportClaimedAt: null },
+ },
+ ])('rejects a worker after its $changedField changes', async ({ fields }) => {
+ const coreApiClient = await createFathomApplicationCoreApiClient();
+ const fathomRecordingImportId = randomUUID();
+ const connectedAccountId = randomUUID();
+ const downloadId = randomUUID();
+
+ await coreApiClient.mutation({
+ createFathomRecordingImport: {
+ __args: {
+ data: {
+ id: fathomRecordingImportId,
+ recordingId: randomUUID(),
+ connectedAccountId,
+ mediaDownloadId: downloadId,
+ },
+ },
+ id: true,
+ },
+ });
+
+ try {
+ const now = new Date();
+ const claims = await Promise.all(
+ [now, new Date(now.getTime() + 1)].map((claimTime) =>
+ claimFathomMediaImport({
+ coreApiClient,
+ fathomRecordingImportId,
+ now: claimTime,
+ }),
+ ),
+ );
+ const successfulClaims = claims.filter((claim) => claim !== undefined);
+
+ expect(successfulClaims).toHaveLength(1);
+
+ const claim = successfulClaims[0];
+
+ if (!claim) {
+ throw new Error('Expected one worker to claim the recording import');
+ }
+
+ const writeContext = {
+ fathomRecordingImportId,
+ connectedAccountId,
+ downloadId,
+ claimedAt: claim.claimedAt,
+ };
+
+ expect(
+ await updateFathomRecordingImport({
+ coreApiClient,
+ writeContext,
+ fields: { mediaFailureReason: 'download_expired' },
+ }),
+ ).toBe(true);
+
+ await coreApiClient.mutation({
+ updateFathomRecordingImport: {
+ __args: { id: fathomRecordingImportId, data: fields },
+ id: true,
+ },
+ });
+
+ expect(
+ await updateFathomRecordingImport({
+ coreApiClient,
+ writeContext,
+ fields: { mediaFailureReason: null },
+ }),
+ ).toBe(false);
+
+ const current = await coreApiClient.query({
+ fathomRecordingImport: {
+ __args: { filter: { id: { eq: fathomRecordingImportId } } },
+ mediaFailureReason: true,
+ },
+ });
+
+ expect(current.fathomRecordingImport?.mediaFailureReason).toBe(
+ 'download_expired',
+ );
+ } finally {
+ await coreApiClient.mutation({
+ destroyFathomRecordingImport: {
+ __args: { id: fathomRecordingImportId },
+ id: true,
+ },
+ });
+ }
+ });
+});
diff --git a/packages/twenty-apps/public/fathom/src/constants/fathom.constant.ts b/packages/twenty-apps/public/fathom/src/constants/fathom.constant.ts
index 08468ab88da..c8bf4908592 100644
--- a/packages/twenty-apps/public/fathom/src/constants/fathom.constant.ts
+++ b/packages/twenty-apps/public/fathom/src/constants/fathom.constant.ts
@@ -6,7 +6,7 @@ export const FATHOM_BACKFILL_ROUTE_PATH = '/fathom/backfill';
export const FATHOM_BACKFILL_MAX_WINDOW_DAYS = 3_650;
export const FATHOM_INITIAL_BACKFILL_DAYS = 31;
export const FATHOM_BACKFILL_BATCH_SIZE = 5;
-export const FATHOM_BACKFILL_BATCH_STAGGER_MILLISECONDS = 20_000;
+export const FATHOM_IMPORT_SLOT_INTERVAL_MILLISECONDS = 20_000;
export const FATHOM_BACKFILL_JOB_RETRY_LIMIT = 3;
export const FATHOM_REQUEST_RETRY_MAX_ELAPSED_MILLISECONDS = 10_000;
export const MAX_FATHOM_MEETING_PAGES = 20;
@@ -18,3 +18,7 @@ export const FATHOM_MEDIA_DOWNLOAD_TIMEOUT_MILLISECONDS = 120_000;
export const FATHOM_MEDIA_UPLOAD_TIMEOUT_MILLISECONDS = 12 * 60 * 1_000;
export const FATHOM_MEDIA_IMPORT_CLAIM_DURATION_MILLISECONDS = 20 * 60 * 1_000;
export const FATHOM_MEDIA_FILE_FOLDER = 'FilesField';
+export const FATHOM_MEDIA_DOWNLOAD_INITIAL_POLL_DELAY_MILLISECONDS = 60_000;
+export const FATHOM_MEDIA_DOWNLOAD_MAX_POLL_DELAY_MILLISECONDS = 300_000;
+export const FATHOM_MEDIA_DOWNLOAD_POLL_BACKOFF_EXPONENT = 1.5;
+export const FATHOM_MEDIA_DOWNLOAD_MAX_POLL_ATTEMPTS = 12;
diff --git a/packages/twenty-apps/public/fathom/src/constants/universal-identifiers.ts b/packages/twenty-apps/public/fathom/src/constants/universal-identifiers.ts
index c58a385b321..7826d3abc32 100644
--- a/packages/twenty-apps/public/fathom/src/constants/universal-identifiers.ts
+++ b/packages/twenty-apps/public/fathom/src/constants/universal-identifiers.ts
@@ -49,6 +49,10 @@ export const FATHOM_RECORDING_IMPORT_CALL_RECORDING_INDEX_UNIVERSAL_IDENTIFIER =
'f0c4e74a-a426-46f8-a76d-a78e00202f8a';
export const FATHOM_RECORDING_IMPORT_CALL_RECORDING_INDEX_FIELD_UNIVERSAL_IDENTIFIER =
'130da502-a1ff-4add-818f-8b272978d01c';
+export const FATHOM_REQUEST_MEDIA_DOWNLOAD_UNIVERSAL_IDENTIFIER =
+ '87b12e47-2a6c-49e3-aafa-1bb29c0ce01f';
+export const FATHOM_IMPORT_MEDIA_DOWNLOAD_UNIVERSAL_IDENTIFIER =
+ '4b46124e-ef53-4649-b414-cc5ae47111ff';
export const CALL_RECORDING_VIDEO_FIELD_UNIVERSAL_IDENTIFIER =
'bb9523d3-457e-4f4b-8c79-27a77afb87da';
export const CALL_RECORDING_AUDIO_FIELD_UNIVERSAL_IDENTIFIER =
diff --git a/packages/twenty-apps/public/fathom/src/logic-functions/fathom-backfill-batch.ts b/packages/twenty-apps/public/fathom/src/logic-functions/fathom-backfill-batch.ts
index fd35c51c735..9959ecc5ac2 100644
--- a/packages/twenty-apps/public/fathom/src/logic-functions/fathom-backfill-batch.ts
+++ b/packages/twenty-apps/public/fathom/src/logic-functions/fathom-backfill-batch.ts
@@ -1,13 +1,11 @@
import { CoreApiClient } from 'twenty-client-sdk/core';
import { defineLogicFunction } from 'twenty-sdk/define';
-import {
- getConnection,
- RetryableLogicFunctionError,
-} from 'twenty-sdk/logic-function';
+import { getConnection } from 'twenty-sdk/logic-function';
import { isDefined } from 'src/utils/is-defined';
import { FATHOM_BACKFILL_BATCH_UNIVERSAL_IDENTIFIER } from 'src/constants/universal-identifiers';
import { type SerializedFathomMeeting } from 'src/logic-functions/types/serialized-fathom-meeting.type';
+import { buildRetryableFathomError } from 'src/logic-functions/utils/build-retryable-fathom-error.util';
import { createFathomClient } from 'src/logic-functions/utils/create-fathom-client.util';
import { hydrateFathomMeeting } from 'src/logic-functions/utils/hydrate-fathom-meeting.util';
import { isTransientFathomError } from 'src/logic-functions/utils/is-transient-fathom-error.util';
@@ -32,7 +30,10 @@ export const fathomBackfillBatchHandler = async (payload: {
// Only a RetryableLogicFunctionError makes the platform retry, so a rate
// limit or a Fathom outage is rethrown as one.
if (isTransientFathomError(error)) {
- throw new RetryableLogicFunctionError(toErrorMessage(error));
+ throw buildRetryableFathomError({
+ operation: `hydrate recording ${serializedMeeting.recordingId}`,
+ error,
+ });
}
// One unreadable recording must not cost the rest of the batch.
@@ -51,11 +52,16 @@ export const fathomBackfillBatchHandler = async (payload: {
// meetings already imported, which costs calls but cannot duplicate
// records: the CallRecording id is derived from the recording.
results.push(
- await syncFathomMeetingToCallRecording({ coreApiClient, meeting }).catch(
- (error: unknown) => {
- throw new RetryableLogicFunctionError(toErrorMessage(error));
- },
- ),
+ await syncFathomMeetingToCallRecording({
+ coreApiClient,
+ meeting,
+ connectedAccountId: payload.connectedAccountId,
+ }).catch((error: unknown) => {
+ throw buildRetryableFathomError({
+ operation: `sync recording ${serializedMeeting.recordingId}`,
+ error,
+ });
+ }),
);
}
diff --git a/packages/twenty-apps/public/fathom/src/logic-functions/fathom-backfill-worker.ts b/packages/twenty-apps/public/fathom/src/logic-functions/fathom-backfill-worker.ts
index 57a7d4b9293..d6b59ba6f99 100644
--- a/packages/twenty-apps/public/fathom/src/logic-functions/fathom-backfill-worker.ts
+++ b/packages/twenty-apps/public/fathom/src/logic-functions/fathom-backfill-worker.ts
@@ -16,9 +16,9 @@ import {
import { type FathomBackfillWorkerPayload } from 'src/logic-functions/types/fathom-backfill-worker-payload.type';
import { createFathomClient } from 'src/logic-functions/utils/create-fathom-client.util';
import { excludeDeletedFathomMeetings } from 'src/logic-functions/utils/exclude-deleted-fathom-meetings.util';
-import { enqueueFathomJobOrThrow } from 'src/logic-functions/utils/enqueue-fathom-job-or-throw.util';
+import { enqueueFathomJobsOrThrow } from 'src/logic-functions/utils/enqueue-fathom-jobs-or-throw.util';
import { listFathomMeetingPage } from 'src/logic-functions/utils/list-fathom-meeting-page.util';
-import { reserveFathomBackfillBatchSlots } from 'src/logic-functions/utils/reserve-fathom-backfill-batch-slots.util';
+import { reserveFathomImportSlots } from 'src/logic-functions/utils/reserve-fathom-import-slots.util';
import { serializeFathomMeeting } from 'src/logic-functions/utils/serialize-fathom-meeting.util';
import { chunkIntoBatches } from 'src/utils/chunk-into-batches.util';
@@ -64,18 +64,17 @@ export const fathomBackfillWorkerHandler = async (
importableMeetings,
FATHOM_BACKFILL_BATCH_SIZE,
);
- const { batchDelays, continuationDelay } =
- await reserveFathomBackfillBatchSlots({
- connectedAccountId: payload.connectedAccountId,
- batchCount: meetingBatches.length,
- });
+ const { slotDelays, continuationDelay } = await reserveFathomImportSlots({
+ connectedAccountId: payload.connectedAccountId,
+ slotCount: meetingBatches.length,
+ });
for (const [batchIndex, meetings] of meetingBatches.entries()) {
- await enqueueFathomJobOrThrow({
+ await enqueueFathomJobsOrThrow({
logicFunctionUniversalIdentifier:
FATHOM_BACKFILL_BATCH_UNIVERSAL_IDENTIFIER,
- payload: { connectedAccountId: payload.connectedAccountId, meetings },
- delayMs: batchDelays[batchIndex],
+ payloads: [{ connectedAccountId: payload.connectedAccountId, meetings }],
+ delayMs: slotDelays[batchIndex],
});
}
@@ -93,15 +92,17 @@ export const fathomBackfillWorkerHandler = async (
}
if (hasMoreMeetings && !isPageBoundReached) {
- await enqueueFathomJobOrThrow({
+ await enqueueFathomJobsOrThrow({
logicFunctionUniversalIdentifier:
FATHOM_BACKFILL_WORKER_UNIVERSAL_IDENTIFIER,
- payload: {
- connectedAccountId: payload.connectedAccountId,
- createdAfter,
- cursor: meetingPage.nextCursor,
- pageIndex: pageIndex + 1,
- },
+ payloads: [
+ {
+ connectedAccountId: payload.connectedAccountId,
+ createdAfter,
+ cursor: meetingPage.nextCursor,
+ pageIndex: pageIndex + 1,
+ },
+ ],
delayMs: continuationDelay,
});
}
diff --git a/packages/twenty-apps/public/fathom/src/logic-functions/fathom-import-media-download.ts b/packages/twenty-apps/public/fathom/src/logic-functions/fathom-import-media-download.ts
new file mode 100644
index 00000000000..967f646f9e8
--- /dev/null
+++ b/packages/twenty-apps/public/fathom/src/logic-functions/fathom-import-media-download.ts
@@ -0,0 +1,14 @@
+import { defineLogicFunction } from 'twenty-sdk/define';
+
+import { FATHOM_IMPORT_MEDIA_DOWNLOAD_UNIVERSAL_IDENTIFIER } from 'src/constants/universal-identifiers';
+import { runFathomMediaImport } from 'src/logic-functions/utils/run-fathom-media-import.util';
+
+export const fathomImportMediaDownloadHandler = runFathomMediaImport;
+
+export default defineLogicFunction({
+ universalIdentifier: FATHOM_IMPORT_MEDIA_DOWNLOAD_UNIVERSAL_IDENTIFIER,
+ name: 'fathom-import-media-download',
+ description: 'Resumes media generation and upload for one Fathom recording.',
+ timeoutSeconds: 900,
+ handler: fathomImportMediaDownloadHandler,
+});
diff --git a/packages/twenty-apps/public/fathom/src/logic-functions/fathom-register-connection.ts b/packages/twenty-apps/public/fathom/src/logic-functions/fathom-register-connection.ts
index 6e4c5f29687..7c243edaf76 100644
--- a/packages/twenty-apps/public/fathom/src/logic-functions/fathom-register-connection.ts
+++ b/packages/twenty-apps/public/fathom/src/logic-functions/fathom-register-connection.ts
@@ -1,16 +1,13 @@
import { isNonEmptyString } from '@sniptt/guards';
import { defineLogicFunction } from 'twenty-sdk/define';
-import {
- getConnection,
- kv,
- RetryableLogicFunctionError,
-} from 'twenty-sdk/logic-function';
+import { getConnection, kv } from 'twenty-sdk/logic-function';
import { isDefined } from 'src/utils/is-defined';
import { FATHOM_INITIAL_BACKFILL_DAYS } from 'src/constants/fathom.constant';
import { FATHOM_REGISTER_CONNECTION_UNIVERSAL_IDENTIFIER } from 'src/constants/universal-identifiers';
import { type FathomConnectionHookPayload } from 'src/logic-functions/types/fathom-connection-hook-payload.type';
import { type FathomWebhookRegistration } from 'src/logic-functions/types/fathom-webhook-registration.type';
+import { buildRetryableFathomError } from 'src/logic-functions/utils/build-retryable-fathom-error.util';
import { createFathomClient } from 'src/logic-functions/utils/create-fathom-client.util';
import { deleteStaleFathomWebhook } from 'src/logic-functions/utils/delete-stale-fathom-webhook.util';
import { enqueueFathomBackfillWorker } from 'src/logic-functions/utils/enqueue-fathom-backfill-worker.util';
@@ -19,7 +16,6 @@ import { getFathomWebhookDestinationUrl } from 'src/logic-functions/utils/get-fa
import { getFathomWebhookRegistrationKey } from 'src/logic-functions/utils/get-fathom-webhook-registration-key.util';
import { isTransientFathomError } from 'src/logic-functions/utils/is-transient-fathom-error.util';
import { storeFathomWebhookRegistration } from 'src/logic-functions/utils/store-fathom-webhook-registration.util';
-import { toErrorMessage } from 'src/logic-functions/utils/to-error-message.util';
// The hook retries as a whole, so the flag keeps a retry after a failed enqueue
// from skipping the import behind the already active registration.
@@ -107,7 +103,10 @@ export const fathomRegisterConnectionHandler = async (
})
.catch((error: unknown) => {
if (isTransientFathomError(error)) {
- throw new RetryableLogicFunctionError(toErrorMessage(error));
+ throw buildRetryableFathomError({
+ operation: 'webhook registration',
+ error,
+ });
}
throw error;
diff --git a/packages/twenty-apps/public/fathom/src/logic-functions/fathom-request-media-download.ts b/packages/twenty-apps/public/fathom/src/logic-functions/fathom-request-media-download.ts
new file mode 100644
index 00000000000..3cb19087bce
--- /dev/null
+++ b/packages/twenty-apps/public/fathom/src/logic-functions/fathom-request-media-download.ts
@@ -0,0 +1,14 @@
+import { defineLogicFunction } from 'twenty-sdk/define';
+
+import { FATHOM_REQUEST_MEDIA_DOWNLOAD_UNIVERSAL_IDENTIFIER } from 'src/constants/universal-identifiers';
+import { runFathomMediaImport } from 'src/logic-functions/utils/run-fathom-media-import.util';
+
+export const fathomRequestMediaDownloadHandler = runFathomMediaImport;
+
+export default defineLogicFunction({
+ universalIdentifier: FATHOM_REQUEST_MEDIA_DOWNLOAD_UNIVERSAL_IDENTIFIER,
+ name: 'fathom-request-media-download',
+ description: 'Requests and imports media for one Fathom recording.',
+ timeoutSeconds: 900,
+ handler: fathomRequestMediaDownloadHandler,
+});
diff --git a/packages/twenty-apps/public/fathom/src/logic-functions/fathom-sync-call.ts b/packages/twenty-apps/public/fathom/src/logic-functions/fathom-sync-call.ts
index b2b8ffeb644..d86be9bd526 100644
--- a/packages/twenty-apps/public/fathom/src/logic-functions/fathom-sync-call.ts
+++ b/packages/twenty-apps/public/fathom/src/logic-functions/fathom-sync-call.ts
@@ -80,6 +80,8 @@ export const fathomSyncCallHandler = async (
fathomClient,
serializedMeeting: serializeFathomMeeting(meeting),
}),
+ connectedAccountId: connection.id,
+ retryMedia: true,
});
return { success: true, recordingId, ...syncResult };
diff --git a/packages/twenty-apps/public/fathom/src/logic-functions/fathom-webhook.ts b/packages/twenty-apps/public/fathom/src/logic-functions/fathom-webhook.ts
index c7428e5ff67..c88c686cabf 100644
--- a/packages/twenty-apps/public/fathom/src/logic-functions/fathom-webhook.ts
+++ b/packages/twenty-apps/public/fathom/src/logic-functions/fathom-webhook.ts
@@ -89,6 +89,7 @@ export const fathomWebhookHandler = async (
const syncResult = await syncFathomMeetingToCallRecording({
coreApiClient: new CoreApiClient({ runAs: 'application' }),
meeting: meetingParseResult.value,
+ connectedAccountId,
});
return { success: true, ...syncResult };
diff --git a/packages/twenty-apps/public/fathom/src/logic-functions/schemas/__tests__/fathom-media-download-payload.schema.test.ts b/packages/twenty-apps/public/fathom/src/logic-functions/schemas/__tests__/fathom-media-download-payload.schema.test.ts
new file mode 100644
index 00000000000..000db4a68ba
--- /dev/null
+++ b/packages/twenty-apps/public/fathom/src/logic-functions/schemas/__tests__/fathom-media-download-payload.schema.test.ts
@@ -0,0 +1,48 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+ fathomImportMediaDownloadPayloadSchema,
+ fathomRequestMediaDownloadPayloadSchema,
+} from 'src/logic-functions/schemas/fathom-media-download-payload.schema';
+
+describe('fathom media download payload schemas', () => {
+ it('accepts a local call recording identifier', () => {
+ expect(
+ fathomRequestMediaDownloadPayloadSchema.safeParse({
+ callRecordingId: 'call-recording-id',
+ }).success,
+ ).toBe(true);
+ });
+
+ it('accepts a generation-fenced poll payload', () => {
+ expect(
+ fathomImportMediaDownloadPayloadSchema.safeParse({
+ callRecordingId: 'call-recording-id',
+ downloadId: 'download-id',
+ attempt: 0,
+ }).success,
+ ).toBe(true);
+ });
+
+ it('rejects a poll payload without its download generation', () => {
+ expect(
+ fathomImportMediaDownloadPayloadSchema.safeParse({
+ callRecordingId: 'call-recording-id',
+ attempt: 0,
+ }).success,
+ ).toBe(false);
+ });
+
+ it.each([-1, 0.5, Number.NaN])(
+ 'rejects invalid poll attempt %s',
+ (attempt) => {
+ expect(
+ fathomImportMediaDownloadPayloadSchema.safeParse({
+ callRecordingId: 'call-recording-id',
+ downloadId: 'download-id',
+ attempt,
+ }).success,
+ ).toBe(false);
+ },
+ );
+});
diff --git a/packages/twenty-apps/public/fathom/src/logic-functions/schemas/fathom-media-download-payload.schema.ts b/packages/twenty-apps/public/fathom/src/logic-functions/schemas/fathom-media-download-payload.schema.ts
new file mode 100644
index 00000000000..eb218d2252b
--- /dev/null
+++ b/packages/twenty-apps/public/fathom/src/logic-functions/schemas/fathom-media-download-payload.schema.ts
@@ -0,0 +1,26 @@
+import { z } from 'zod';
+
+export const fathomRequestMediaDownloadPayloadSchema = z.object({
+ callRecordingId: z.string().trim().min(1),
+ rateLimitAttempt: z.number().int().nonnegative().optional(),
+});
+
+export const fathomImportMediaDownloadPayloadSchema =
+ fathomRequestMediaDownloadPayloadSchema.extend({
+ downloadId: z.string().trim().min(1),
+ attempt: z.number().int().nonnegative(),
+ });
+
+export const fathomMediaImportPayloadSchema =
+ fathomRequestMediaDownloadPayloadSchema.extend({
+ downloadId: z.string().trim().min(1).optional(),
+ attempt: z.number().int().nonnegative().default(0),
+ });
+
+export type FathomRequestMediaDownloadPayload = z.infer<
+ typeof fathomRequestMediaDownloadPayloadSchema
+>;
+
+export type FathomImportMediaDownloadPayload = z.infer<
+ typeof fathomImportMediaDownloadPayloadSchema
+>;
diff --git a/packages/twenty-apps/public/fathom/src/logic-functions/types/call-recording-sync-fields.type.ts b/packages/twenty-apps/public/fathom/src/logic-functions/types/call-recording-sync-fields.type.ts
index b8554edd3e8..a8e3dde4097 100644
--- a/packages/twenty-apps/public/fathom/src/logic-functions/types/call-recording-sync-fields.type.ts
+++ b/packages/twenty-apps/public/fathom/src/logic-functions/types/call-recording-sync-fields.type.ts
@@ -5,7 +5,6 @@ export type CallRecordingSyncFields = {
title?: string;
status?: 'PROCESSING' | 'COMPLETED';
recordingRequestStatus?: 'REQUESTED';
- externalRecordingId?: string;
startedAt?: string;
endedAt?: string;
transcript?: TranscriptEntry[];
diff --git a/packages/twenty-apps/public/fathom/src/logic-functions/utils/__tests__/build-fathom-call-recording-upsert-fields.test.ts b/packages/twenty-apps/public/fathom/src/logic-functions/utils/__tests__/build-fathom-call-recording-upsert-fields.test.ts
new file mode 100644
index 00000000000..ddb4e575ea7
--- /dev/null
+++ b/packages/twenty-apps/public/fathom/src/logic-functions/utils/__tests__/build-fathom-call-recording-upsert-fields.test.ts
@@ -0,0 +1,202 @@
+import { describe, expect, it } from 'vitest';
+
+import { type CallRecordingMediaState } from 'src/logic-functions/types/call-recording-media-state.type';
+import { type CallRecordingSyncFields } from 'src/logic-functions/types/call-recording-sync-fields.type';
+import { buildFathomCallRecordingUpsertFields } from 'src/logic-functions/utils/build-fathom-call-recording-upsert-fields.util';
+
+const buildFields = ({
+ existingCallRecording,
+ retryMedia = false,
+ sharedFields = { transcript: [] },
+}: {
+ existingCallRecording?: Partial<CallRecordingMediaState>;
+ retryMedia?: boolean;
+ sharedFields?: CallRecordingSyncFields;
+} = {}) =>
+ buildFathomCallRecordingUpsertFields({
+ sharedFields,
+ existingCallRecording: existingCallRecording
+ ? {
+ hasVideo: false,
+ hasAudio: false,
+ hasTranscript: false,
+ hasSummary: false,
+ failureReason: undefined,
+ downloadId: undefined,
+ connectedAccountId: undefined,
+ ...existingCallRecording,
+ }
+ : undefined,
+ connectedAccountId: 'current-connected-account-id',
+ callRecordingId: 'call-recording-id',
+ recordingId: '123',
+ retryMedia,
+ });
+
+describe('buildFathomCallRecordingUpsertFields', () => {
+ it('creates new recordings in processing while media is pending', () => {
+ const fields = buildFields();
+
+ expect(fields.createCallRecordingFields).toEqual({
+ transcript: [],
+ status: 'PROCESSING',
+ });
+ expect(fields.recordingImportFields).toEqual({
+ callRecordingId: 'call-recording-id',
+ recordingId: '123',
+ connectedAccountId: 'current-connected-account-id',
+ });
+ });
+
+ it('does not move an existing recording back to processing automatically', () => {
+ expect(buildFields().updateCallRecordingFields).not.toHaveProperty(
+ 'status',
+ );
+ });
+
+ it('does not request an automatic retry for settled media', () => {
+ const fields = buildFields({
+ existingCallRecording: {
+ failureReason: 'download_forbidden',
+ connectedAccountId: 'connected-account-id',
+ },
+ });
+
+ expect(fields.isMediaDownloadRequestNeeded).toBe(false);
+ });
+
+ it('reopens a settled failure only for an explicit media retry', () => {
+ const fields = buildFields({
+ retryMedia: true,
+ existingCallRecording: {
+ failureReason: 'download_forbidden',
+ connectedAccountId: 'previous-connected-account-id',
+ },
+ });
+
+ expect(fields.updateCallRecordingFields).toEqual({
+ transcript: [],
+ status: 'PROCESSING',
+ });
+ expect(fields.recordingImportFields).toEqual({
+ callRecordingId: 'call-recording-id',
+ recordingId: '123',
+ connectedAccountId: 'current-connected-account-id',
+ mediaDownloadId: null,
+ mediaUploadCheckpoint: null,
+ mediaFailureReason: null,
+ mediaImportClaimedAt: null,
+ });
+ expect(fields.isMediaDownloadRequestNeeded).toBe(true);
+ });
+
+ it('keeps the owner of an active private Fathom download', () => {
+ const fields = buildFields({
+ existingCallRecording: {
+ downloadId: 'download-id',
+ connectedAccountId: 'current-connected-account-id',
+ },
+ });
+
+ expect(fields.recordingImportFields).not.toHaveProperty(
+ 'connectedAccountId',
+ );
+ expect(fields.isMediaDownloadRequestNeeded).toBe(false);
+ });
+
+ it('replaces a download owned by another connection', () => {
+ const fields = buildFields({
+ existingCallRecording: {
+ downloadId: 'download-id',
+ connectedAccountId: 'previous-connected-account-id',
+ },
+ });
+
+ expect(fields.updateCallRecordingFields).toEqual({
+ transcript: [],
+ });
+ expect(fields.recordingImportFields).toEqual({
+ callRecordingId: 'call-recording-id',
+ recordingId: '123',
+ connectedAccountId: 'current-connected-account-id',
+ mediaDownloadId: null,
+ mediaUploadCheckpoint: null,
+ mediaImportClaimedAt: null,
+ });
+ expect(fields.isMediaDownloadRequestNeeded).toBe(true);
+ });
+
+ it.each([undefined, 'current-connected-account-id'])(
+ 'requests missing media after an interrupted enqueue with owner %s',
+ (connectedAccountId) => {
+ const fields = buildFields({
+ existingCallRecording: { connectedAccountId },
+ });
+
+ expect(fields.isMediaDownloadRequestNeeded).toBe(true);
+ expect(fields.updateCallRecordingFields).not.toHaveProperty('status');
+ },
+ );
+
+ it('preserves populated transcript and summary on a repeated import', () => {
+ const fields = buildFields({
+ existingCallRecording: { hasTranscript: true, hasSummary: true },
+ sharedFields: {
+ transcript: [
+ {
+ participant: { name: 'Speaker' },
+ words: [{ text: 'New source transcript' }],
+ },
+ ],
+ summary: { markdown: 'New source summary', blocknote: null },
+ },
+ });
+
+ expect(fields.updateCallRecordingFields.transcript).toBeUndefined();
+ expect(fields.updateCallRecordingFields.summary).toBeUndefined();
+ });
+
+ it('fills an empty summary without replacing a populated transcript', () => {
+ const fields = buildFields({
+ existingCallRecording: { hasTranscript: true, hasSummary: false },
+ sharedFields: {
+ transcript: [
+ {
+ participant: { name: 'Speaker' },
+ words: [{ text: 'New source transcript' }],
+ },
+ ],
+ summary: { markdown: 'New source summary', blocknote: null },
+ },
+ });
+
+ expect(fields.updateCallRecordingFields.transcript).toBeUndefined();
+ expect(fields.updateCallRecordingFields.summary).toEqual({
+ markdown: 'New source summary',
+ blocknote: null,
+ });
+ });
+
+ it.each([
+ 'download_forbidden',
+ 'no_downloadable_media',
+ 'download_expired',
+ 'media_file_too_large',
+ 'download_timed_out',
+ 'connected_account_unavailable',
+ 'completed_without_file',
+ ])('does not automatically reopen terminal failure %s', (failureReason) => {
+ const fields = buildFields({
+ existingCallRecording: {
+ connectedAccountId: 'previous-connected-account-id',
+ failureReason,
+ },
+ });
+
+ expect(fields.isMediaDownloadRequestNeeded).toBe(false);
+ expect(fields.recordingImportFields).not.toHaveProperty(
+ 'mediaFailureReason',
+ );
+ expect(fields.updateCallRecordingFields).not.toHaveProperty('status');
+ });
+});
diff --git a/packages/twenty-apps/public/fathom/src/logic-functions/utils/__tests__/get-fathom-media-download-poll-delay.test.ts b/packages/twenty-apps/public/fathom/src/logic-functions/utils/__tests__/get-fathom-media-download-poll-delay.test.ts
new file mode 100644
index 00000000000..52770fd22a9
--- /dev/null
+++ b/packages/twenty-apps/public/fathom/src/logic-functions/utils/__tests__/get-fathom-media-download-poll-delay.test.ts
@@ -0,0 +1,28 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+ FATHOM_MEDIA_DOWNLOAD_INITIAL_POLL_DELAY_MILLISECONDS,
+ FATHOM_MEDIA_DOWNLOAD_MAX_POLL_ATTEMPTS,
+ FATHOM_MEDIA_DOWNLOAD_MAX_POLL_DELAY_MILLISECONDS,
+} from 'src/constants/fathom.constant';
+import { getFathomMediaDownloadPollDelay } from 'src/logic-functions/utils/get-fathom-media-download-poll-delay.util';
+
+describe('getFathomMediaDownloadPollDelay', () => {
+ it('starts at the initial delay and grows with each attempt', () => {
+ expect(getFathomMediaDownloadPollDelay(0)).toBe(
+ FATHOM_MEDIA_DOWNLOAD_INITIAL_POLL_DELAY_MILLISECONDS,
+ );
+ expect(getFathomMediaDownloadPollDelay(1)).toBeGreaterThan(
+ getFathomMediaDownloadPollDelay(0),
+ );
+ expect(getFathomMediaDownloadPollDelay(2)).toBeGreaterThan(
+ getFathomMediaDownloadPollDelay(1),
+ );
+ });
+
+ it('caps the delay so a stalled download keeps polling on a fixed cadence', () => {
+ expect(
+ getFathomMediaDownloadPollDelay(FATHOM_MEDIA_DOWNLOAD_MAX_POLL_ATTEMPTS),
+ ).toBe(FATHOM_MEDIA_DOWNLOAD_MAX_POLL_DELAY_MILLISECONDS);
+ });
+});
diff --git a/packages/twenty-apps/public/fathom/src/logic-functions/utils/__tests__/get-fathom-media-failure-reason-for-error.test.ts b/packages/twenty-apps/public/fathom/src/logic-functions/utils/__tests__/get-fathom-media-failure-reason-for-error.test.ts
new file mode 100644
index 00000000000..96bcca027b7
--- /dev/null
+++ b/packages/twenty-apps/public/fathom/src/logic-functions/utils/__tests__/get-fathom-media-failure-reason-for-error.test.ts
@@ -0,0 +1,29 @@
+import { FathomError } from 'fathom-typescript/sdk/models/errors';
+import { describe, expect, it } from 'vitest';
+
+import { getFathomMediaFailureReasonForError } from 'src/logic-functions/utils/get-fathom-media-failure-reason-for-error.util';
+
+describe('getFathomMediaFailureReasonForError', () => {
+ it.each([
+ [403, 'download_forbidden'],
+ [422, 'no_downloadable_media'],
+ [404, undefined],
+ [429, undefined],
+ [503, undefined],
+ ])('classifies Fathom status %i as %s', (status, expectedReason) => {
+ const error = new FathomError('Download request failed', {
+ request: new Request('https://api.fathom.ai/external/v1/recordings/1'),
+ response: new Response(null, { status }),
+ body: '',
+ });
+
+ expect(getFathomMediaFailureReasonForError(error)).toBe(expectedReason);
+ });
+
+ it.each([undefined, null, new Error('Upload failed'), { statusCode: 403 }])(
+ 'does not classify unrelated errors: %s',
+ (error) => {
+ expect(getFathomMediaFailureReasonForError(error)).toBeUndefined();
+ },
+ );
+});
diff --git a/packages/twenty-apps/public/fathom/src/logic-functions/utils/__tests__/get-fathom-retry-after-delay.test.ts b/packages/twenty-apps/public/fathom/src/logic-functions/utils/__tests__/get-fathom-retry-after-delay.test.ts
new file mode 100644
index 00000000000..c6bc0577615
--- /dev/null
+++ b/packages/twenty-apps/public/fathom/src/logic-functions/utils/__tests__/get-fathom-retry-after-delay.test.ts
@@ -0,0 +1,62 @@
+import { FathomError } from 'fathom-typescript/sdk/models/errors';
+import { describe, expect, it } from 'vitest';
+
+import { getFathomRetryAfterDelay } from 'src/logic-functions/utils/get-fathom-retry-after-delay.util';
+
+const NOW = new Date('2026-09-05T12:00:00.000Z');
+
+describe('getFathomRetryAfterDelay', () => {
+ it.each([
+ ['120', 120_000],
+ ['0', 0],
+ ['1.5', 1_500],
+ [' 90 ', 90_000],
+ ['Sat, 05 Sep 2026 12:02:00 GMT', 120_000],
+ ['Sat, 05 Sep 2026 12:00:00 GMT', 0],
+ ['Sat, 05 Sep 2026 11:59:00 GMT', 60_000],
+ [undefined, 60_000],
+ ['', 60_000],
+ [' ', 60_000],
+ ['invalid', 60_000],
+ ['-1', 60_000],
+ ['Infinity', 60_000],
+ ['NaN', 60_000],
+ ['1e309', 60_000],
+ ['1e308', 60_000],
+ ])(
+ 'delays retry-after %s by %i milliseconds',
+ (retryAfter, expectedDelay) => {
+ const error = new FathomError('Rate limit exceeded', {
+ request: new Request('https://api.fathom.ai/external/v1/meetings'),
+ response: new Response(null, {
+ status: 429,
+ headers:
+ retryAfter === undefined ? {} : { 'retry-after': retryAfter },
+ }),
+ body: '',
+ });
+
+ expect(getFathomRetryAfterDelay({ error, now: NOW })).toBe(expectedDelay);
+ },
+ );
+
+ it('does not classify other Fathom errors as rate limits', () => {
+ const error = new FathomError('Service unavailable', {
+ request: new Request('https://api.fathom.ai/external/v1/meetings'),
+ response: new Response(null, {
+ status: 503,
+ headers: { 'retry-after': '120' },
+ }),
+ body: '',
+ });
+
+ expect(getFathomRetryAfterDelay({ error, now: NOW })).toBeUndefined();
+ });
+
+ it.each([undefined, null, new Error('Request failed'), { statusCode: 429 }])(
+ 'ignores errors without a Fathom rate-limit response: %s',
+ (error) => {
+ expect(getFathomRetryAfterDelay({ error, now: NOW })).toBeUndefined();
+ },
+ );
+});
diff --git a/packages/twenty-apps/public/fathom/src/logic-functions/utils/apply-fathom-media-download.util.ts b/packages/twenty-apps/public/fathom/src/logic-functions/utils/apply-fathom-media-download.util.ts
new file mode 100644
index 00000000000..98543c817a2
--- /dev/null
+++ b/packages/twenty-apps/public/fathom/src/logic-functions/utils/apply-fathom-media-download.util.ts
@@ -0,0 +1,98 @@
+import { type RecordingDownload } from 'fathom-typescript/sdk/models/shared';
+import { type CoreApiClient } from 'twenty-client-sdk/core';
+
+import { FATHOM_MEDIA_FAILURE_REASON } from 'src/constants/fathom-media-failure-reason.constant';
+import { type FathomMediaUploadCheckpoint } from 'src/logic-functions/types/fathom-media-upload-checkpoint.type';
+import { type FathomMediaWriteContext } from 'src/logic-functions/types/fathom-media-write-context.type';
+import { completeFathomMediaFileUpload } from 'src/logic-functions/utils/complete-fathom-media-file-upload.util';
+import { getFathomMediaDownloadFailureReason } from 'src/logic-functions/utils/get-fathom-media-download-failure-reason.util';
+import { importFathomMediaFile } from 'src/logic-functions/utils/import-fathom-media-file.util';
+import { recordFathomMediaFailure } from 'src/logic-functions/utils/record-fathom-media-failure.util';
+import { settleCallRecordingMedia } from 'src/logic-functions/utils/settle-call-recording-media.util';
+import { isDefined } from 'src/utils/is-defined';
+
+export const applyFathomMediaDownload = async ({
+ coreApiClient,
+ callRecordingId,
+ writeContext,
+ uploadCheckpoint,
+ download,
+}: {
+ coreApiClient: Pick<CoreApiClient, 'query' | 'mutation'>;
+ callRecordingId: string;
+ writeContext: FathomMediaWriteContext & { downloadId: string };
+ uploadCheckpoint: FathomMediaUploadCheckpoint | undefined;
+ download: Pick<
+ RecordingDownload,
+ 'status' | 'failureReason' | 'video' | 'audio'
+ >;
+}): Promise<'imported' | 'pending' | 'unavailable' | 'stale'> => {
+ const updateOptions = { coreApiClient, callRecordingId, writeContext };
+
+ if (uploadCheckpoint?.downloadId === writeContext.downloadId) {
+ await completeFathomMediaFileUpload({ fileId: uploadCheckpoint.fileId });
+ const isApplied = await settleCallRecordingMedia({
+ ...updateOptions,
+ fields: {
+ [uploadCheckpoint.kind]: [
+ {
+ fileId: uploadCheckpoint.fileId,
+ label:
+ uploadCheckpoint.kind === 'video' ? 'video.mp4' : 'audio.mp3',
+ },
+ ],
+ mediaFailureReason: null,
+ },
+ });
+
+ return isApplied ? 'imported' : 'stale';
+ }
+
+ if (download.status === 'processing') {
+ return 'pending';
+ }
+
+ const downloadFile = download.video ?? download.audio;
+ const failureReason = getFathomMediaDownloadFailureReason(download);
+
+ if (isDefined(failureReason) || !isDefined(downloadFile)) {
+ const isApplied = await recordFathomMediaFailure({
+ ...updateOptions,
+ reason:
+ failureReason ?? FATHOM_MEDIA_FAILURE_REASON.COMPLETED_WITHOUT_FILE,
+ });
+
+ return isApplied ? 'unavailable' : 'stale';
+ }
+
+ const kind = isDefined(download.video) ? 'video' : 'audio';
+ const result = await importFathomMediaFile({
+ ...updateOptions,
+ downloadId: writeContext.downloadId,
+ kind,
+ downloadFile,
+ });
+
+ if (result.outcome === 'stale') {
+ return 'stale';
+ }
+
+ if (result.outcome !== 'imported') {
+ const isApplied = await recordFathomMediaFailure({
+ ...updateOptions,
+ reason:
+ result.outcome === 'too-large'
+ ? FATHOM_MEDIA_FAILURE_REASON.FILE_TOO_LARGE
+ : FATHOM_MEDIA_FAILURE_REASON.COMPLETED_WITHOUT_FILE,
+ });
+
+ return isApplied ? 'unavailable' : 'stale';
+ }
+
+ const isApplied = await settleCallRecordingMedia({
+ ...updateOptions,
+ fields: { [kind]: result.files, mediaFailureReason: null },
+ });
+
+ return isApplied ? 'imported' : 'stale';
+};
diff --git a/packages/twenty-apps/public/fathom/src/logic-functions/utils/build-fathom-call-recording-upsert-fields.util.ts b/packages/twenty-apps/public/fathom/src/logic-functions/utils/build-fathom-call-recording-upsert-fields.util.ts
new file mode 100644
index 00000000000..0ea27258dcd
--- /dev/null
+++ b/packages/twenty-apps/public/fathom/src/logic-functions/utils/build-fathom-call-recording-upsert-fields.util.ts
@@ -0,0 +1,94 @@
+import { isDefined } from 'src/utils/is-defined';
+
+import { type CallRecordingSyncFields } from 'src/logic-functions/types/call-recording-sync-fields.type';
+import { type CallRecordingMediaState } from 'src/logic-functions/types/call-recording-media-state.type';
+import { type FathomRecordingImportFields } from 'src/logic-functions/types/fathom-recording-import-fields.type';
+
+export const buildFathomCallRecordingUpsertFields = ({
+ sharedFields,
+ existingCallRecording,
+ connectedAccountId,
+ callRecordingId,
+ recordingId,
+ retryMedia,
+}: {
+ sharedFields: CallRecordingSyncFields;
+ existingCallRecording:
+ | Pick<
+ CallRecordingMediaState,
+ | 'hasVideo'
+ | 'hasAudio'
+ | 'failureReason'
+ | 'downloadId'
+ | 'connectedAccountId'
+ | 'hasTranscript'
+ | 'hasSummary'
+ >
+ | undefined;
+ connectedAccountId: string;
+ callRecordingId: string;
+ recordingId: string;
+ retryMedia: boolean;
+}): {
+ createCallRecordingFields: CallRecordingSyncFields;
+ updateCallRecordingFields: CallRecordingSyncFields;
+ recordingImportFields: FathomRecordingImportFields & {
+ callRecordingId: string;
+ recordingId: string;
+ };
+ isMediaDownloadRequestNeeded: boolean;
+} => {
+ const isRetryingSettledMedia =
+ retryMedia &&
+ isDefined(existingCallRecording?.failureReason) &&
+ !existingCallRecording.hasVideo &&
+ !existingCallRecording.hasAudio;
+ const hasActiveDownloadForCurrentConnection =
+ !isRetryingSettledMedia &&
+ isDefined(existingCallRecording?.downloadId) &&
+ existingCallRecording.connectedAccountId === connectedAccountId;
+ const isReplacingActiveDownload =
+ isDefined(existingCallRecording) &&
+ existingCallRecording.connectedAccountId !== connectedAccountId &&
+ !existingCallRecording.hasVideo &&
+ !existingCallRecording.hasAudio &&
+ !isDefined(existingCallRecording.failureReason);
+ const isMissingMedia =
+ !existingCallRecording?.hasVideo &&
+ !existingCallRecording?.hasAudio &&
+ !isDefined(existingCallRecording?.downloadId) &&
+ !isDefined(existingCallRecording?.failureReason);
+ const ownershipFields = hasActiveDownloadForCurrentConnection
+ ? {}
+ : { connectedAccountId };
+
+ return {
+ createCallRecordingFields: {
+ ...sharedFields,
+ status: 'PROCESSING',
+ },
+ updateCallRecordingFields: {
+ ...sharedFields,
+ ...(existingCallRecording?.hasTranscript
+ ? { transcript: undefined }
+ : {}),
+ ...(existingCallRecording?.hasSummary ? { summary: undefined } : {}),
+ ...(isRetryingSettledMedia ? { status: 'PROCESSING' } : {}),
+ },
+ recordingImportFields: {
+ callRecordingId,
+ recordingId,
+ ...ownershipFields,
+ ...(isReplacingActiveDownload || isRetryingSettledMedia
+ ? {
+ mediaDownloadId: null,
+ mediaUploadCheckpoint: null,
+ mediaImportClaimedAt: null,
+ }
+ : {}),
+ ...(isRetryingSettledMedia ? { mediaFailureReason: null } : {}),
+ },
+ isMediaDownloadRequestNeeded:
+ isRetryingSettledMedia || isReplacingActiveDownload || isMissingMedia,
+ };
+};
diff --git a/packages/twenty-apps/public/fathom/src/logic-functions/utils/build-retryable-fathom-error.util.ts b/packages/twenty-apps/public/fathom/src/logic-functions/utils/build-retryable-fathom-error.util.ts
new file mode 100644
index 00000000000..943d06fe1ae
--- /dev/null
+++ b/packages/twenty-apps/public/fathom/src/logic-functions/utils/build-retryable-fathom-error.util.ts
@@ -0,0 +1,17 @@
+import { RetryableLogicFunctionError } from 'twenty-sdk/logic-function';
+
+import { toErrorMessage } from 'src/logic-functions/utils/to-error-message.util';
+
+export const buildRetryableFathomError = ({
+ operation,
+ error,
+}: {
+ operation: string;
+ error: unknown;
+}): RetryableLogicFunctionError =>
+ Object.assign(
+ new RetryableLogicFunctionError(
+ `[fathom] ${operation} failed: ${toErrorMessage(error)}`,
+ ),
+ { cause: error },
+ );
diff --git a/packages/twenty-apps/public/fathom/src/logic-functions/utils/enqueue-fathom-backfill-worker.util.ts b/packages/twenty-apps/public/fathom/src/logic-functions/utils/enqueue-fathom-backfill-worker.util.ts
index 3e2861e5893..e4f1ff3caf0 100644
--- a/packages/twenty-apps/public/fathom/src/logic-functions/utils/enqueue-fathom-backfill-worker.util.ts
+++ b/packages/twenty-apps/public/fathom/src/logic-functions/utils/enqueue-fathom-backfill-worker.util.ts
@@ -1,5 +1,5 @@
import { FATHOM_BACKFILL_WORKER_UNIVERSAL_IDENTIFIER } from 'src/constants/universal-identifiers';
-import { enqueueFathomJobOrThrow } from 'src/logic-functions/utils/enqueue-fathom-job-or-throw.util';
+import { enqueueFathomJobsOrThrow } from 'src/logic-functions/utils/enqueue-fathom-jobs-or-throw.util';
export const enqueueFathomBackfillWorker = async ({
connectedAccountId,
@@ -8,8 +8,8 @@ export const enqueueFathomBackfillWorker = async ({
connectedAccountId: string;
days: number;
}): Promise<void> =>
- enqueueFathomJobOrThrow({
+ enqueueFathomJobsOrThrow({
logicFunctionUniversalIdentifier:
FATHOM_BACKFILL_WORKER_UNIVERSAL_IDENTIFIER,
- payload: { connectedAccountId, days },
+ payloads: [{ connectedAccountId, days }],
});
diff --git a/packages/twenty-apps/public/fathom/src/logic-functions/utils/enqueue-fathom-job-or-throw.util.ts b/packages/twenty-apps/public/fathom/src/logic-functions/utils/enqueue-fathom-job-or-throw.util.ts
deleted file mode 100644
index dc83d4f7a95..00000000000
--- a/packages/twenty-apps/public/fathom/src/logic-functions/utils/enqueue-fathom-job-or-throw.util.ts
+++ /dev/null
@@ -1,24 +0,0 @@
-import { enqueueJobs, type EnqueueJobsInput } from 'twenty-sdk/logic-function';
-
-import { FATHOM_BACKFILL_JOB_RETRY_LIMIT } from 'src/constants/fathom.constant';
-
-// enqueueJobs applies one delayMs to every payload of a call, so each
-// staggered batch goes through its own call.
-export const enqueueFathomJobOrThrow = async ({
- payload,
- ...options
-}: Pick<EnqueueJobsInput, 'logicFunctionUniversalIdentifier' | 'delayMs'> & {
- payload: Record<string, unknown>;
-}): Promise<void> => {
- const enqueueResult = await enqueueJobs({
- ...options,
- payloads: [payload],
- retryLimit: FATHOM_BACKFILL_JOB_RETRY_LIMIT,
- });
-
- if (!enqueueResult.enqueued) {
- throw new Error(
- `Failed to enqueue Fathom job ${options.logicFunctionUniversalIdentifier}`,
- );
- }
-};
diff --git a/packages/twenty-apps/public/fathom/src/logic-functions/utils/enqueue-fathom-jobs-or-throw.util.ts b/packages/twenty-apps/public/fathom/src/logic-functions/utils/enqueue-fathom-jobs-or-throw.util.ts
new file mode 100644
index 00000000000..22cbb23eb97
--- /dev/null
+++ b/packages/twenty-apps/public/fathom/src/logic-functions/utils/enqueue-fathom-jobs-or-throw.util.ts
@@ -0,0 +1,30 @@
+import { enqueueJobs, type EnqueueJobsInput } from 'twenty-sdk/logic-function';
+
+import { FATHOM_BACKFILL_JOB_RETRY_LIMIT } from 'src/constants/fathom.constant';
+import { chunkIntoBatches } from 'src/utils/chunk-into-batches.util';
+
+const MAX_FATHOM_JOBS_PER_ENQUEUE = 200;
+
+export const enqueueFathomJobsOrThrow = async ({
+ payloads,
+ ...options
+}: Pick<EnqueueJobsInput, 'logicFunctionUniversalIdentifier' | 'delayMs'> & {
+ payloads: Record<string, unknown>[];
+}): Promise<void> => {
+ for (const payloadBatch of chunkIntoBatches(
+ payloads,
+ MAX_FATHOM_JOBS_PER_ENQUEUE,
+ )) {
+ const enqueueResult = await enqueueJobs({
+ ...options,
+ payloads: payloadBatch,
+ retryLimit: FATHOM_BACKFILL_JOB_RETRY_LIMIT,
+ });
+
+ if (!enqueueResult.enqueued) {
+ throw new Error(
+ `Failed to enqueue Fathom job ${options.logicFunctionUniversalIdentifier}`,
+ );
+ }
+ }
+};
diff --git a/packages/twenty-apps/public/fathom/src/logic-functions/utils/enqueue-fathom-media-download-poll.util.ts b/packages/twenty-apps/public/fathom/src/logic-functions/utils/enqueue-fathom-media-download-poll.util.ts
new file mode 100644
index 00000000000..a77aeb7597b
--- /dev/null
+++ b/packages/twenty-apps/public/fathom/src/logic-functions/utils/enqueue-fathom-media-download-poll.util.ts
@@ -0,0 +1,30 @@
+import { FATHOM_IMPORT_MEDIA_DOWNLOAD_UNIVERSAL_IDENTIFIER } from 'src/constants/universal-identifiers';
+import { type FathomImportMediaDownloadPayload } from 'src/logic-functions/schemas/fathom-media-download-payload.schema';
+import { enqueueFathomJobsOrThrow } from 'src/logic-functions/utils/enqueue-fathom-jobs-or-throw.util';
+import { getFathomMediaDownloadPollDelay } from 'src/logic-functions/utils/get-fathom-media-download-poll-delay.util';
+import { reserveFathomImportSlots } from 'src/logic-functions/utils/reserve-fathom-import-slots.util';
+
+export const enqueueFathomMediaDownloadPoll = async ({
+ connectedAccountId,
+ notBeforeDelayMilliseconds,
+ ...payload
+}: FathomImportMediaDownloadPayload & {
+ connectedAccountId: string;
+ notBeforeDelayMilliseconds?: number;
+}): Promise<void> => {
+ const { slotDelays } = await reserveFathomImportSlots({
+ connectedAccountId,
+ slotCount: 1,
+ notBeforeDelayMilliseconds: Math.max(
+ notBeforeDelayMilliseconds ?? 0,
+ getFathomMediaDownloadPollDelay(payload.attempt),
+ ),
+ });
+
+ await enqueueFathomJobsOrThrow({
+ logicFunctionUniversalIdentifier:
+ FATHOM_IMPORT_MEDIA_DOWNLOAD_UNIVERSAL_IDENTIFIER,
+ payloads: [payload],
+ delayMs: slotDelays[0],
+ });
+};
diff --git a/packages/twenty-apps/public/fathom/src/logic-functions/utils/enqueue-fathom-media-download-request.util.ts b/packages/twenty-apps/public/fathom/src/logic-functions/utils/enqueue-fathom-media-download-request.util.ts
new file mode 100644
index 00000000000..0f0d3f8bd07
--- /dev/null
+++ b/packages/twenty-apps/public/fathom/src/logic-functions/utils/enqueue-fathom-media-download-request.util.ts
@@ -0,0 +1,26 @@
+import { FATHOM_REQUEST_MEDIA_DOWNLOAD_UNIVERSAL_IDENTIFIER } from 'src/constants/universal-identifiers';
+import { type FathomRequestMediaDownloadPayload } from 'src/logic-functions/schemas/fathom-media-download-payload.schema';
+import { enqueueFathomJobsOrThrow } from 'src/logic-functions/utils/enqueue-fathom-jobs-or-throw.util';
+import { reserveFathomImportSlots } from 'src/logic-functions/utils/reserve-fathom-import-slots.util';
+
+export const enqueueFathomMediaDownloadRequest = async ({
+ connectedAccountId,
+ notBeforeDelayMilliseconds,
+ ...payload
+}: FathomRequestMediaDownloadPayload & {
+ connectedAccountId: string;
+ notBeforeDelayMilliseconds?: number;
+}): Promise<void> => {
+ const { slotDelays } = await reserveFathomImportSlots({
+ connectedAccountId,
+ slotCount: 1,
+ notBeforeDelayMilliseconds,
+ });
+
+ await enqueueFathomJobsOrThrow({
+ logicFunctionUniversalIdentifier:
+ FATHOM_REQUEST_MEDIA_DOWNLOAD_UNIVERSAL_IDENTIFIER,
+ payloads: [payload],
+ delayMs: slotDelays[0],
+ });
+};
diff --git a/packages/twenty-apps/public/fathom/src/logic-functions/utils/get-fathom-backfill-schedule-key.util.ts b/packages/twenty-apps/public/fathom/src/logic-functions/utils/get-fathom-import-schedule-key.util.ts
similarity index 66%
rename from packages/twenty-apps/public/fathom/src/logic-functions/utils/get-fathom-backfill-schedule-key.util.ts
rename to packages/twenty-apps/public/fathom/src/logic-functions/utils/get-fathom-import-schedule-key.util.ts
index 3644176f79d..302129d1895 100644
--- a/packages/twenty-apps/public/fathom/src/logic-functions/utils/get-fathom-backfill-schedule-key.util.ts
+++ b/packages/twenty-apps/public/fathom/src/logic-functions/utils/get-fathom-import-schedule-key.util.ts
@@ -1,3 +1,3 @@
-export const getFathomBackfillScheduleKey = (
+export const getFathomImportScheduleKey = (
connectedAccountId: string,
): string => `fathom-backfill-schedule:${connectedAccountId}`;
diff --git a/packages/twenty-apps/public/fathom/src/logic-functions/utils/get-fathom-media-download-poll-delay.util.ts b/packages/twenty-apps/public/fathom/src/logic-functions/utils/get-fathom-media-download-poll-delay.util.ts
new file mode 100644
index 00000000000..442b04265ab
--- /dev/null
+++ b/packages/twenty-apps/public/fathom/src/logic-functions/utils/get-fathom-media-download-poll-delay.util.ts
@@ -0,0 +1,14 @@
+import {
+ FATHOM_MEDIA_DOWNLOAD_INITIAL_POLL_DELAY_MILLISECONDS,
+ FATHOM_MEDIA_DOWNLOAD_MAX_POLL_DELAY_MILLISECONDS,
+ FATHOM_MEDIA_DOWNLOAD_POLL_BACKOFF_EXPONENT,
+} from 'src/constants/fathom.constant';
+
+export const getFathomMediaDownloadPollDelay = (attempt: number): number =>
+ Math.min(
+ Math.round(
+ FATHOM_MEDIA_DOWNLOAD_INITIAL_POLL_DELAY_MILLISECONDS *
+ FATHOM_MEDIA_DOWNLOAD_POLL_BACKOFF_EXPONENT ** attempt,
+ ),
+ FATHOM_MEDIA_DOWNLOAD_MAX_POLL_DELAY_MILLISECONDS,
+ );
diff --git a/packages/twenty-apps/public/fathom/src/logic-functions/utils/get-fathom-media-failure-reason-for-error.util.ts b/packages/twenty-apps/public/fathom/src/logic-functions/utils/get-fathom-media-failure-reason-for-error.util.ts
new file mode 100644
index 00000000000..c0e60da9f6e
--- /dev/null
+++ b/packages/twenty-apps/public/fathom/src/logic-functions/utils/get-fathom-media-failure-reason-for-error.util.ts
@@ -0,0 +1,24 @@
+import { FathomError } from 'fathom-typescript/sdk/models/errors';
+
+import { FATHOM_MEDIA_FAILURE_REASON } from 'src/constants/fathom-media-failure-reason.constant';
+
+const FORBIDDEN_STATUS_CODE = 403;
+const UNPROCESSABLE_STATUS_CODE = 422;
+
+export const getFathomMediaFailureReasonForError = (
+ error: unknown,
+): string | undefined => {
+ if (!(error instanceof FathomError)) {
+ return undefined;
+ }
+
+ if (error.statusCode === UNPROCESSABLE_STATUS_CODE) {
+ return FATHOM_MEDIA_FAILURE_REASON.NO_DOWNLOADABLE_MEDIA;
+ }
+
+ if (error.statusCode === FORBIDDEN_STATUS_CODE) {
+ return FATHOM_MEDIA_FAILURE_REASON.DOWNLOAD_FORBIDDEN;
+ }
+
+ return undefined;
+};
diff --git a/packages/twenty-apps/public/fathom/src/logic-functions/utils/get-fathom-retry-after-delay.util.ts b/packages/twenty-apps/public/fathom/src/logic-functions/utils/get-fathom-retry-after-delay.util.ts
new file mode 100644
index 00000000000..049dc716744
--- /dev/null
+++ b/packages/twenty-apps/public/fathom/src/logic-functions/utils/get-fathom-retry-after-delay.util.ts
@@ -0,0 +1,31 @@
+import { isNonEmptyString } from '@sniptt/guards';
+import { FathomError } from 'fathom-typescript/sdk/models/errors';
+
+const FATHOM_RATE_LIMIT_FALLBACK_DELAY_MILLISECONDS = 60_000;
+
+export const getFathomRetryAfterDelay = ({
+ error,
+ now,
+}: {
+ error: unknown;
+ now: Date;
+}): number | undefined => {
+ if (!(error instanceof FathomError) || error.statusCode !== 429) {
+ return undefined;
+ }
+
+ const retryAfter = error.headers.get('retry-after')?.trim();
+
+ if (!isNonEmptyString(retryAfter)) {
+ return FATHOM_RATE_LIMIT_FALLBACK_DELAY_MILLISECONDS;
+ }
+
+ const retryAfterSeconds = Number(retryAfter);
+ const delayMilliseconds = Number.isNaN(retryAfterSeconds)
+ ? Date.parse(retryAfter) - now.getTime()
+ : retryAfterSeconds * 1_000;
+
+ return Number.isFinite(delayMilliseconds) && delayMilliseconds >= 0
+ ? delayMilliseconds
+ : FATHOM_RATE_LIMIT_FALLBACK_DELAY_MILLISECONDS;
+};
diff --git a/packages/twenty-apps/public/fathom/src/logic-functions/utils/release-fathom-media-import-claim.util.ts b/packages/twenty-apps/public/fathom/src/logic-functions/utils/release-fathom-media-import-claim.util.ts
new file mode 100644
index 00000000000..1f9a84bb0c5
--- /dev/null
+++ b/packages/twenty-apps/public/fathom/src/logic-functions/utils/release-fathom-media-import-claim.util.ts
@@ -0,0 +1,26 @@
+import { type CoreApiClient } from 'twenty-client-sdk/core';
+
+import { type FathomMediaImportClaim } from 'src/logic-functions/utils/claim-fathom-media-import.util';
+
+export const releaseFathomMediaImportClaim = async ({
+ coreApiClient,
+ fathomRecordingImportId,
+ claim,
+}: {
+ coreApiClient: Pick<CoreApiClient, 'mutation'>;
+ fathomRecordingImportId: string;
+ claim: FathomMediaImportClaim;
+}): Promise<void> => {
+ await coreApiClient.mutation({
+ updateFathomRecordingImports: {
+ __args: {
+ filter: {
+ id: { eq: fathomRecordingImportId },
+ mediaImportClaimedAt: { eq: claim.claimedAt },
+ },
+ data: { mediaImportClaimedAt: null },
+ },
+ id: true,
+ },
+ });
+};
diff --git a/packages/twenty-apps/public/fathom/src/logic-functions/utils/reserve-fathom-backfill-batch-slots.util.ts b/packages/twenty-apps/public/fathom/src/logic-functions/utils/reserve-fathom-backfill-batch-slots.util.ts
deleted file mode 100644
index fdb750e9801..00000000000
--- a/packages/twenty-apps/public/fathom/src/logic-functions/utils/reserve-fathom-backfill-batch-slots.util.ts
+++ /dev/null
@@ -1,42 +0,0 @@
-import { kv } from 'twenty-sdk/logic-function';
-
-import { FATHOM_BACKFILL_BATCH_STAGGER_MILLISECONDS } from 'src/constants/fathom.constant';
-import { getFathomBackfillScheduleKey } from 'src/logic-functions/utils/get-fathom-backfill-schedule-key.util';
-
-type FathomBackfillSchedule = {
- nextBatchAvailableAt: number;
-};
-
-// Every backfill of one connected account, initial or manual, appends its
-// batches to the same per-account timeline so Fathom sees one paced stream
-// per token instead of parallel bursts.
-export const reserveFathomBackfillBatchSlots = async ({
- connectedAccountId,
- batchCount,
-}: {
- connectedAccountId: string;
- batchCount: number;
-}): Promise<{ batchDelays: number[]; continuationDelay: number }> => {
- const now = Date.now();
- const scheduleKey = getFathomBackfillScheduleKey(connectedAccountId);
- const existingSchedule = await kv.get<FathomBackfillSchedule>(scheduleKey);
- const scheduleStart = Math.max(
- now,
- existingSchedule?.nextBatchAvailableAt ?? now,
- );
- const batchDelays = Array.from(
- { length: batchCount },
- (_, batchIndex) =>
- scheduleStart -
- now +
- batchIndex * FATHOM_BACKFILL_BATCH_STAGGER_MILLISECONDS,
- );
- const nextBatchAvailableAt =
- scheduleStart + batchCount * FATHOM_BACKFILL_BATCH_STAGGER_MILLISECONDS;
-
- if (batchCount > 0) {
- await kv.set(scheduleKey, { nextBatchAvailableAt });
- }
-
- return { batchDelays, continuationDelay: nextBatchAvailableAt - now };
-};
diff --git a/packages/twenty-apps/public/fathom/src/logic-functions/utils/reserve-fathom-import-slots.util.ts b/packages/twenty-apps/public/fathom/src/logic-functions/utils/reserve-fathom-import-slots.util.ts
new file mode 100644
index 00000000000..5c17c2729d6
--- /dev/null
+++ b/packages/twenty-apps/public/fathom/src/logic-functions/utils/reserve-fathom-import-slots.util.ts
@@ -0,0 +1,41 @@
+import { kv } from 'twenty-sdk/logic-function';
+
+import { FATHOM_IMPORT_SLOT_INTERVAL_MILLISECONDS } from 'src/constants/fathom.constant';
+import { getFathomImportScheduleKey } from 'src/logic-functions/utils/get-fathom-import-schedule-key.util';
+
+type FathomImportSchedule = {
+ nextBatchAvailableAt: number;
+};
+
+export const reserveFathomImportSlots = async ({
+ connectedAccountId,
+ slotCount,
+ notBeforeDelayMilliseconds = 0,
+}: {
+ connectedAccountId: string;
+ slotCount: number;
+ notBeforeDelayMilliseconds?: number;
+}): Promise<{ slotDelays: number[]; continuationDelay: number }> => {
+ const now = Date.now();
+ const scheduleKey = getFathomImportScheduleKey(connectedAccountId);
+ const existingSchedule = await kv.get<FathomImportSchedule>(scheduleKey);
+ const scheduleStart = Math.max(
+ now + notBeforeDelayMilliseconds,
+ existingSchedule?.nextBatchAvailableAt ?? now,
+ );
+ const slotDelays = Array.from(
+ { length: slotCount },
+ (_, slotIndex) =>
+ scheduleStart -
+ now +
+ slotIndex * FATHOM_IMPORT_SLOT_INTERVAL_MILLISECONDS,
+ );
+ const nextSlotAvailableAt =
+ scheduleStart + slotCount * FATHOM_IMPORT_SLOT_INTERVAL_MILLISECONDS;
+
+ if (slotCount > 0) {
+ await kv.set(scheduleKey, { nextBatchAvailableAt: nextSlotAvailableAt });
+ }
+
+ return { slotDelays, continuationDelay: nextSlotAvailableAt - now };
+};
diff --git a/packages/twenty-apps/public/fathom/src/logic-functions/utils/resolve-fathom-media-import-target.util.ts b/packages/twenty-apps/public/fathom/src/logic-functions/utils/resolve-fathom-media-import-target.util.ts
new file mode 100644
index 00000000000..593f994a4a5
--- /dev/null
+++ b/packages/twenty-apps/public/fathom/src/logic-functions/utils/resolve-fathom-media-import-target.util.ts
@@ -0,0 +1,74 @@
+import { isNonEmptyString } from '@sniptt/guards';
+import { type CoreApiClient } from 'twenty-client-sdk/core';
+import { isDefined } from 'src/utils/is-defined';
+
+import { findCallRecordingMediaState } from 'src/logic-functions/utils/find-call-recording-media-state.util';
+import { isFathomMediaSettled } from 'src/logic-functions/utils/is-fathom-media-settled.util';
+import { type FathomMediaUploadCheckpoint } from 'src/logic-functions/types/fathom-media-upload-checkpoint.type';
+
+export type ResolveFathomMediaImportTargetResult =
+ | {
+ status: 'proceed';
+ fathomRecordingImportId: string;
+ connectedAccountId: string;
+ recordingId: number;
+ downloadId: string | undefined;
+ uploadCheckpoint: FathomMediaUploadCheckpoint | undefined;
+ }
+ | { status: 'skipped'; reason: string };
+
+export const resolveFathomMediaImportTarget = async ({
+ coreApiClient,
+ callRecordingId,
+}: {
+ coreApiClient: Pick<CoreApiClient, 'query'>;
+ callRecordingId: string;
+}): Promise<ResolveFathomMediaImportTargetResult> => {
+ const mediaState = await findCallRecordingMediaState({
+ coreApiClient,
+ callRecordingId,
+ });
+
+ if (!isDefined(mediaState)) {
+ return { status: 'skipped', reason: 'no matching call recording' };
+ }
+
+ if (!isNonEmptyString(mediaState.fathomRecordingImportId)) {
+ return { status: 'skipped', reason: 'call recording has no Fathom import' };
+ }
+
+ const recordingId = Number(mediaState.recordingId);
+
+ if (!Number.isSafeInteger(recordingId) || recordingId <= 0) {
+ return {
+ status: 'skipped',
+ reason: 'call recording has an invalid Fathom id',
+ };
+ }
+
+ if (isFathomMediaSettled(mediaState)) {
+ return {
+ status: 'skipped',
+ reason:
+ mediaState.hasVideo || mediaState.hasAudio
+ ? 'media already imported'
+ : `media unavailable: ${mediaState.failureReason}`,
+ };
+ }
+
+ if (!isNonEmptyString(mediaState.connectedAccountId)) {
+ return {
+ status: 'skipped',
+ reason: 'call recording has no Fathom connected account',
+ };
+ }
+
+ return {
+ status: 'proceed',
+ fathomRecordingImportId: mediaState.fathomRecordingImportId,
+ connectedAccountId: mediaState.connectedAccountId,
+ recordingId,
+ downloadId: mediaState.downloadId,
+ uploadCheckpoint: mediaState.uploadCheckpoint,
+ };
+};
diff --git a/packages/twenty-apps/public/fathom/src/logic-functions/utils/run-fathom-media-import.util.ts b/packages/twenty-apps/public/fathom/src/logic-functions/utils/run-fathom-media-import.util.ts
new file mode 100644
index 00000000000..fbaa3dfcf42
--- /dev/null
+++ b/packages/twenty-apps/public/fathom/src/logic-functions/utils/run-fathom-media-import.util.ts
@@ -0,0 +1,229 @@
+import { Fathom } from 'fathom-typescript';
+import { type RecordingDownload } from 'fathom-typescript/sdk/models/shared';
+import { CoreApiClient } from 'twenty-client-sdk/core';
+import { getConnection } from 'twenty-sdk/logic-function';
+
+import { FATHOM_MEDIA_FAILURE_REASON } from 'src/constants/fathom-media-failure-reason.constant';
+import {
+ FATHOM_MEDIA_DOWNLOAD_MAX_POLL_ATTEMPTS,
+ FATHOM_MEDIA_IMPORT_CLAIM_DURATION_MILLISECONDS,
+} from 'src/constants/fathom.constant';
+import { fathomMediaImportPayloadSchema } from 'src/logic-functions/schemas/fathom-media-download-payload.schema';
+import { applyFathomMediaDownload } from 'src/logic-functions/utils/apply-fathom-media-download.util';
+import { buildRetryableFathomError } from 'src/logic-functions/utils/build-retryable-fathom-error.util';
+import { claimFathomMediaImport } from 'src/logic-functions/utils/claim-fathom-media-import.util';
+import { completeFathomCallRecordingImport } from 'src/logic-functions/utils/complete-fathom-call-recording-import.util';
+import { enqueueFathomMediaDownloadPoll } from 'src/logic-functions/utils/enqueue-fathom-media-download-poll.util';
+import { enqueueFathomMediaDownloadRequest } from 'src/logic-functions/utils/enqueue-fathom-media-download-request.util';
+import { getFathomMediaFailureReasonForError } from 'src/logic-functions/utils/get-fathom-media-failure-reason-for-error.util';
+import { getFathomRetryAfterDelay } from 'src/logic-functions/utils/get-fathom-retry-after-delay.util';
+import { recordFathomMediaFailure } from 'src/logic-functions/utils/record-fathom-media-failure.util';
+import { releaseFathomMediaImportClaim } from 'src/logic-functions/utils/release-fathom-media-import-claim.util';
+import { resolveFathomMediaImportTarget } from 'src/logic-functions/utils/resolve-fathom-media-import-target.util';
+import { updateFathomMediaDownloadId } from 'src/logic-functions/utils/update-fathom-media-download-id.util';
+import { isDefined } from 'src/utils/is-defined';
+
+const MAX_RATE_LIMIT_RETRIES = 3;
+
+export const runFathomMediaImport = async (rawPayload: unknown) => {
+ const payload = fathomMediaImportPayloadSchema.parse(rawPayload);
+ const { callRecordingId, attempt } = payload;
+ const coreApiClient = new CoreApiClient({ runAs: 'application' });
+ const recordingContext = { coreApiClient, callRecordingId };
+ const fathomRecordingImportId = callRecordingId;
+ const claim = await claimFathomMediaImport({
+ coreApiClient,
+ fathomRecordingImportId,
+ now: new Date(),
+ }).catch((error: unknown) => {
+ throw buildRetryableFathomError({
+ operation: `claim media import callRecordingId=${callRecordingId}`,
+ error,
+ });
+ });
+
+ try {
+ const target = await resolveFathomMediaImportTarget(recordingContext);
+
+ if (target.status === 'skipped') {
+ await completeFathomCallRecordingImport(recordingContext);
+
+ return { success: true, outcome: 'skipped' };
+ }
+
+ if (
+ isDefined(payload.downloadId) &&
+ payload.downloadId !== target.downloadId
+ ) {
+ return { success: true, outcome: 'stale' };
+ }
+
+ const enqueueNextAttempt = async ({
+ downloadId,
+ nextAttempt = attempt,
+ rateLimitAttempt = payload.rateLimitAttempt,
+ delay,
+ }: {
+ downloadId: string | undefined;
+ nextAttempt?: number;
+ rateLimitAttempt?: number;
+ delay?: number;
+ }) => {
+ const options = {
+ callRecordingId,
+ connectedAccountId: target.connectedAccountId,
+ rateLimitAttempt,
+ notBeforeDelayMilliseconds: delay,
+ };
+
+ if (isDefined(downloadId)) {
+ await enqueueFathomMediaDownloadPoll({
+ ...options,
+ downloadId,
+ attempt: nextAttempt,
+ });
+ } else {
+ await enqueueFathomMediaDownloadRequest(options);
+ }
+ };
+
+ if (!isDefined(claim)) {
+ await enqueueNextAttempt({
+ downloadId: target.downloadId,
+ delay: FATHOM_MEDIA_IMPORT_CLAIM_DURATION_MILLISECONDS,
+ });
+
+ return { success: true, outcome: 'in-progress' };
+ }
+
+ let writeContext = {
+ fathomRecordingImportId: target.fathomRecordingImportId,
+ connectedAccountId: target.connectedAccountId,
+ claimedAt: claim.claimedAt,
+ downloadId: target.downloadId ?? null,
+ };
+
+ try {
+ const connection = await getConnection(target.connectedAccountId);
+ const fathomClient = new Fathom({
+ security: { bearerAuth: connection.accessToken },
+ retryConfig: { strategy: 'none' },
+ });
+ let download: Pick<
+ RecordingDownload,
+ 'downloadId' | 'status' | 'failureReason' | 'video' | 'audio'
+ >;
+
+ if (
+ isDefined(target.uploadCheckpoint) &&
+ target.uploadCheckpoint.downloadId === target.downloadId
+ ) {
+ download = { downloadId: target.downloadId, status: 'completed' };
+ } else if (isDefined(target.downloadId)) {
+ download = await fathomClient.getRecordingDownload({
+ recordingId: target.recordingId,
+ downloadId: target.downloadId,
+ });
+ } else {
+ download = await fathomClient.createRecordingDownload({
+ recordingId: target.recordingId,
+ });
+ }
+
+ if (!isDefined(download.downloadId)) {
+ throw new Error('Fathom download did not return an identifier');
+ }
+
+ if (!isDefined(target.downloadId)) {
+ const isApplied = await updateFathomMediaDownloadId({
+ ...recordingContext,
+ writeContext,
+ downloadId: download.downloadId,
+ });
+
+ if (!isApplied) {
+ return { success: true, outcome: 'stale' };
+ }
+ }
+
+ writeContext = { ...writeContext, downloadId: download.downloadId };
+ const outcome = await applyFathomMediaDownload({
+ ...recordingContext,
+ writeContext: { ...writeContext, downloadId: download.downloadId },
+ uploadCheckpoint: target.uploadCheckpoint,
+ download,
+ });
+
+ if (outcome !== 'pending') {
+ return { success: true, outcome };
+ }
+
+ if (attempt + 1 >= FATHOM_MEDIA_DOWNLOAD_MAX_POLL_ATTEMPTS) {
+ const isApplied = await recordFathomMediaFailure({
+ ...recordingContext,
+ writeContext,
+ reason: FATHOM_MEDIA_FAILURE_REASON.DOWNLOAD_TIMED_OUT,
+ });
+
+ return { success: true, outcome: isApplied ? 'unavailable' : 'stale' };
+ }
+
+ await enqueueNextAttempt({
+ downloadId: download.downloadId,
+ nextAttempt: attempt + 1,
+ rateLimitAttempt: 0,
+ });
+
+ return { success: true, outcome: 'pending' };
+ } catch (error) {
+ const retryDelay = getFathomRetryAfterDelay({ error, now: new Date() });
+
+ if (
+ isDefined(retryDelay) &&
+ (payload.rateLimitAttempt ?? 0) < MAX_RATE_LIMIT_RETRIES
+ ) {
+ await enqueueNextAttempt({
+ downloadId: writeContext.downloadId ?? undefined,
+ rateLimitAttempt: (payload.rateLimitAttempt ?? 0) + 1,
+ delay: retryDelay,
+ });
+
+ return { success: true, outcome: 'rate-limited' };
+ }
+
+ const failureReason = isDefined(retryDelay)
+ ? 'rate_limit_exhausted'
+ : getFathomMediaFailureReasonForError(error);
+
+ if (!isDefined(failureReason)) {
+ throw error;
+ }
+
+ const isApplied = await recordFathomMediaFailure({
+ ...recordingContext,
+ writeContext,
+ reason: failureReason,
+ });
+
+ return { success: true, outcome: isApplied ? 'unavailable' : 'stale' };
+ }
+ } catch (error) {
+ throw buildRetryableFathomError({
+ operation: `media import callRecordingId=${callRecordingId}`,
+ error,
+ });
+ } finally {
+ if (isDefined(claim)) {
+ await releaseFathomMediaImportClaim({
+ coreApiClient,
+ fathomRecordingImportId,
+ claim,
+ }).catch((error: unknown) => {
+ throw buildRetryableFathomError({
+ operation: `release media import callRecordingId=${callRecordingId}`,
+ error,
+ });
+ });
+ }
+ }
+};
diff --git a/packages/twenty-apps/public/fathom/src/logic-functions/utils/sync-fathom-meeting-to-call-recording.util.ts b/packages/twenty-apps/public/fathom/src/logic-functions/utils/sync-fathom-meeting-to-call-recording.util.ts
index 8b46e27963a..c997828d50a 100644
--- a/packages/twenty-apps/public/fathom/src/logic-functions/utils/sync-fathom-meeting-to-call-recording.util.ts
+++ b/packages/twenty-apps/public/fathom/src/logic-functions/utils/sync-fathom-meeting-to-call-recording.util.ts
@@ -3,19 +3,28 @@ import { type Meeting } from 'fathom-typescript/sdk/models/shared';
import { type CoreApiClient } from 'twenty-client-sdk/core';
import { type CallRecordingSyncFields } from 'src/logic-functions/types/call-recording-sync-fields.type';
+import { buildFathomCallRecordingUpsertFields } from 'src/logic-functions/utils/build-fathom-call-recording-upsert-fields.util';
+import { completeFathomCallRecordingImport } from 'src/logic-functions/utils/complete-fathom-call-recording-import.util';
import { computeCallRecordingIdForFathomMeeting } from 'src/logic-functions/utils/compute-call-recording-id-for-fathom-meeting.util';
+import { enqueueFathomMediaDownloadRequest } from 'src/logic-functions/utils/enqueue-fathom-media-download-request.util';
+import { findCallRecordingMediaState } from 'src/logic-functions/utils/find-call-recording-media-state.util';
import { findMatchingCalendarEvent } from 'src/logic-functions/utils/find-matching-calendar-event.util';
import { formatFathomSummary } from 'src/logic-functions/utils/format-fathom-summary.util';
import { getFathomMeetingTitle } from 'src/logic-functions/utils/get-fathom-meeting-title.util';
import { mapFathomTranscriptToEntries } from 'src/logic-functions/utils/map-fathom-transcript-to-entries.util';
import { upsertCallRecording } from 'src/logic-functions/utils/upsert-call-recording.util';
+import { upsertFathomRecordingImport } from 'src/logic-functions/utils/upsert-fathom-recording-import.util';
export const syncFathomMeetingToCallRecording = async ({
coreApiClient,
meeting,
+ connectedAccountId,
+ retryMedia = false,
}: {
coreApiClient: Pick<CoreApiClient, 'query' | 'mutation'>;
meeting: Meeting;
+ connectedAccountId: string;
+ retryMedia?: boolean;
}): Promise<{
callRecordingId: string;
calendarEventId?: string;
@@ -31,14 +40,16 @@ export const syncFathomMeetingToCallRecording = async ({
meeting,
});
const title = getFathomMeetingTitle(meeting);
- // Fathom exposes no pending state, so a summary still missing when we sync is
- // one it never generated: waiting on it would strand the recording.
- const isComplete = transcriptEntries.length > 0;
- const fields: CallRecordingSyncFields = {
+ const callRecordingId = computeCallRecordingIdForFathomMeeting(
+ meeting.recordingId,
+ );
+ const existingCallRecording = await findCallRecordingMediaState({
+ coreApiClient,
+ callRecordingId,
+ });
+ const sharedFields: CallRecordingSyncFields = {
...(isNonEmptyString(title) ? { title } : {}),
- status: isComplete ? 'COMPLETED' : 'PROCESSING',
recordingRequestStatus: 'REQUESTED',
- externalRecordingId: String(meeting.recordingId),
startedAt: meeting.recordingStartTime.toISOString(),
endedAt: meeting.recordingEndTime.toISOString(),
...(transcriptEntries.length === 0
@@ -49,14 +60,45 @@ export const syncFathomMeetingToCallRecording = async ({
: {}),
...(calendarEventId === undefined ? {} : { calendarEventId }),
};
- const callRecordingId = computeCallRecordingIdForFathomMeeting(
- meeting.recordingId,
- );
+ const {
+ createCallRecordingFields,
+ updateCallRecordingFields,
+ recordingImportFields,
+ isMediaDownloadRequestNeeded,
+ } = buildFathomCallRecordingUpsertFields({
+ sharedFields,
+ existingCallRecording,
+ connectedAccountId,
+ callRecordingId,
+ recordingId: String(meeting.recordingId),
+ retryMedia,
+ });
+
const upsertResult = await upsertCallRecording({
coreApiClient,
callRecordingId,
- fields,
+ createFields: createCallRecordingFields,
+ updateFields: updateCallRecordingFields,
+ expectedUpdatedAt: existingCallRecording?.updatedAt,
+ });
+
+ await upsertFathomRecordingImport({
+ coreApiClient,
+ fathomRecordingImportId: callRecordingId,
+ fields: recordingImportFields,
+ expectedUpdatedAt: existingCallRecording?.fathomRecordingImportUpdatedAt,
+ });
+
+ await completeFathomCallRecordingImport({
+ coreApiClient,
+ callRecordingId,
});
+ if (upsertResult.created || isMediaDownloadRequestNeeded) {
+ await enqueueFathomMediaDownloadRequest({
+ callRecordingId,
+ connectedAccountId,
+ });
+ }
return {
callRecordingId,
diff --git a/packages/twenty-apps/public/fathom/src/logic-functions/utils/update-fathom-media-download-id.util.ts b/packages/twenty-apps/public/fathom/src/logic-functions/utils/update-fathom-media-download-id.util.ts
new file mode 100644
index 00000000000..7e454633a35
--- /dev/null
+++ b/packages/twenty-apps/public/fathom/src/logic-functions/utils/update-fathom-media-download-id.util.ts
@@ -0,0 +1,21 @@
+import { type CoreApiClient } from 'twenty-client-sdk/core';
+import { type FathomMediaWriteContext } from 'src/logic-functions/types/fathom-media-write-context.type';
+import { updateFathomRecordingImport } from 'src/logic-functions/utils/update-fathom-recording-import.util';
+
+export const updateFathomMediaDownloadId = async ({
+ coreApiClient,
+ downloadId,
+ writeContext,
+}: {
+ coreApiClient: Pick<CoreApiClient, 'mutation'>;
+ downloadId: string | null;
+ writeContext: FathomMediaWriteContext;
+}): Promise<boolean> =>
+ updateFathomRecordingImport({
+ coreApiClient,
+ writeContext,
+ fields: {
+ mediaDownloadId: downloadId,
+ mediaUploadCheckpoint: null,
+ },
+ });
diff --git a/packages/twenty-apps/public/fathom/src/logic-functions/utils/upsert-call-recording.util.ts b/packages/twenty-apps/public/fathom/src/logic-functions/utils/upsert-call-recording.util.ts
index c1181dd1d4c..3707d9134c8 100644
--- a/packages/twenty-apps/public/fathom/src/logic-functions/utils/upsert-call-recording.util.ts
+++ b/packages/twenty-apps/public/fathom/src/logic-functions/utils/upsert-call-recording.util.ts
@@ -1,81 +1,64 @@
+import { isNonEmptyArray } from '@sniptt/guards';
import { type CoreApiClient } from 'twenty-client-sdk/core';
-import { isDefined } from 'src/utils/is-defined';
import { type CallRecordingSyncFields } from 'src/logic-functions/types/call-recording-sync-fields.type';
-
-const doesCallRecordingExist = async ({
- coreApiClient,
- callRecordingId,
-}: {
- coreApiClient: Pick<CoreApiClient, 'query'>;
- callRecordingId: string;
-}): Promise<boolean> => {
- const queryResult = await coreApiClient.query({
- callRecordings: {
- __args: {
- filter: { id: { eq: callRecordingId } },
- first: 1,
- },
- edges: { node: { id: true } },
- },
- });
-
- return isDefined(queryResult.callRecordings?.edges?.[0]?.node);
-};
-
-const updateCallRecording = async ({
- coreApiClient,
- callRecordingId,
- fields,
-}: {
- coreApiClient: Pick<CoreApiClient, 'mutation'>;
- callRecordingId: string;
- fields: CallRecordingSyncFields;
-}): Promise<void> => {
- await coreApiClient.mutation({
- updateCallRecording: {
- __args: {
- id: callRecordingId,
- data: fields,
- },
- id: true,
- },
- });
-};
+import { isDefined } from 'src/utils/is-defined';
export const upsertCallRecording = async ({
coreApiClient,
callRecordingId,
- fields,
+ createFields,
+ updateFields,
+ expectedUpdatedAt,
}: {
coreApiClient: Pick<CoreApiClient, 'query' | 'mutation'>;
callRecordingId: string;
- fields: CallRecordingSyncFields;
+ createFields: CallRecordingSyncFields;
+ updateFields: CallRecordingSyncFields;
+ expectedUpdatedAt: string | undefined;
}): Promise<{ callRecordingId: string; created: boolean }> => {
- if (await doesCallRecordingExist({ coreApiClient, callRecordingId })) {
- await updateCallRecording({ coreApiClient, callRecordingId, fields });
+ if (!isDefined(expectedUpdatedAt)) {
+ try {
+ await coreApiClient.mutation({
+ createCallRecording: {
+ __args: { data: { id: callRecordingId, ...createFields } },
+ id: true,
+ },
+ });
+ } catch (error) {
+ const result = await coreApiClient.query({
+ callRecordings: {
+ __args: { filter: { id: { eq: callRecordingId } }, first: 1 },
+ edges: { node: { id: true } },
+ },
+ });
- return { callRecordingId, created: false };
- }
+ if (!isDefined(result.callRecordings?.edges[0]?.node)) {
+ throw error;
+ }
- try {
- await coreApiClient.mutation({
- createCallRecording: {
- __args: {
- data: { id: callRecordingId, ...fields },
- },
- id: true,
- },
- });
+ return { callRecordingId, created: false };
+ }
return { callRecordingId, created: true };
- } catch (error) {
- if (!(await doesCallRecordingExist({ coreApiClient, callRecordingId }))) {
- throw error;
- }
+ }
- await updateCallRecording({ coreApiClient, callRecordingId, fields });
+ const result = await coreApiClient.mutation({
+ updateCallRecordings: {
+ __args: {
+ filter: {
+ id: { eq: callRecordingId },
+ updatedAt: { eq: expectedUpdatedAt },
+ },
+ data: updateFields,
+ },
+ id: true,
+ },
+ });
- return { callRecordingId, created: false };
+ if (!isNonEmptyArray(result.updateCallRecordings)) {
+ throw new Error('Fathom recording changed during import; retry the import');
}
+
+ return { callRecordingId, created: false };
};