Import Fathom recording media into call recordings

Closed
EH
2mo ago
+2256-10

Context

The Fathom app synced transcripts, summaries and action items but never the recording itself, so CallRecording.video and .audio stayed empty for every Fathom import.

Fathom does supply them. Their download API (shipped July 2026) generates a downloadable file per recording and returns a short-lived signed URL, and fathom-typescript@0.0.43 (already pinned, and the current latest) exposes createRecordingDownload and getRecordingDownload. So the gap was entirely on our side.

Two properties shape the design. The download is asynchronous: video is generated in the background, while audio-only recordings can come back completed on the first call. And the response carries video or audio, never both.

Changes

Request and poll (fathom-request-media-download, fathom-import-media-download)
The request function asks Fathom for a download and imports inline when the file is already there, which is the audio-only path. Video returns processing, so it schedules a poll that backs off from 60s to a 300s cap and gives up after 12 attempts. The growing interval is deliberate: status polls count against Fathom's global 60/min budget, which a backfill already spends near its ceiling on transcripts and summaries. Download requests get their own 30/min bucket, so media does not compete with the limit that is already tight.

Streaming to storage (import-fathom-media-file.util.ts, put-fathom-media-body-to-upload-target.util.ts)
Media never lands on disk. The download body is piped straight into the presigned PUT via node:http, so memory stays flat regardless of recording size. This is ported from call-recorder, including the reason it does not use fetch for the upload leg (it buffers request bodies and OOMs Lambda). Files are capped at 500 MB, rejected early against Fathom's declared file_size_bytes before the body is opened.

A new fathomMediaFailureReason field on CallRecording
Written on every terminal outcome: over the size cap, no downloadable media (422), limited-access share (403), Fathom's own generation_failed/generation_timeout, expired download, completed-without-file, exhausted poll budget, and a failed enqueue. Cleared on a successful import.

Its real job is stopping repeat work. Without it, every re-sync of a recording with no downloadable media asked Fathom to generate the file again and burned the download budget to fail identically. The import guard now skips a recording whose reason is recorded. Sync Fathom Call clears it first, so syncing a call by hand stays the way to retry after a share is widened.

Completion now waits on media
A recording used to complete as soon as its transcript arrived, so it read as done while its video was still generating. It now stays in PROCESSING until media lands or is settled as unavailable, matching what COMPLETED already means for call-recorder recordings. A re-sync reads the media already on the record rather than reopening a finished recording, and a sync with no connected account completes on the transcript alone.

The summary is deliberately still not part of the rule. Fathom reports no pending state for it, so a missing summary is one it never generated. It does report media as still generating, which is what makes media safe to wait on.

Role
Granted UPLOAD_FILE, without which createFileUpload and completeFileUpload are both denied.

Wired into all three sync paths (webhook, fathom-sync-call, fathom-backfill-batch) by threading connectedAccountId through syncFathomMeetingToCallRecording. A failed media enqueue is logged and recorded rather than raised, so it cannot cost the transcript and summary already written.

Depends on a follow-up PR

One gap in the PROCESSING hold is knowingly left open here: a media job that dies after its platform retries are spent writes no reason, leaving that recording in PROCESSING until something syncs it again. The reconciler in a separate PR closes it. Every other terminal path writes a reason and releases the recording.

Tests

80 unit tests pass (was 38). New coverage for the poll backoff and its cap, the import guard (forged recording id, already-imported, settled failure), every branch of the download-apply (processing, failed, expired, completed video, completed audio, over-cap, completed-without-file), both handlers (payload validation, immediate import, scheduled poll, exhausted budget, 403 and 422 recorded, 429 handed back for redelivery), and the status rule (held while generating, completed on re-sync, reopened on an explicit retry, completed with no connected account).

yarn typecheck, yarn lint and yarn twenty dev:build are clean; the manifest carries both logic functions, the new field and the permission flag.

Not covered

  • Whether "downloads are private to the API client that created them" is app-bound or token-bound under OAuth is unverified; it needs a live Fathom account. If it is token-bound, a refreshed token could fail the poll, and the fix is collapsing request and poll into the single 900s function.
  • Two chains started for the same recording while the first is still in flight cost a duplicate transfer. Deterministic job ids would collapse them, but jobs/jobId on enqueueJobs exists only on main and is not in any published twenty-sdk (2.37.0 included). Worth revisiting once it ships.

Generated by Claude Code