Imported from jeremylongshore/tons-of-skills-marketplace (plugins/saas-packs/fireflies-pack/skills/fireflies-migration-deep-dive/SKILL.md). Install upstream with npx skills add jeremylongshore/tons-of-skills-marketplace --skill fireflies-migration-deep-dive. Copyright stays with the author (MIT).

Fireflies.ai Migration Deep Dive

Current State

!npm list graphql graphql-request 2>/dev/null || echo 'No graphql packages'

Overview

Migrate to Fireflies.ai from other transcription platforms or custom recording systems. Covers historical recording import via uploadAudio, adapter pattern for gradual cutover, and data validation post-migration.

Prerequisites

• A lawful/authorized migration scope, documented consent and retention requirements, and named data owners.
• An inventory of recordings, transcripts, access rules, and deletion obligations; use synthetic fixtures for migration tests.
• A staged cutover plan with rollback, reconciliation, and a restricted evidence location.

Examples

Import a fictitious recording into staging, validate only approved metadata and derived action-item fields, and compare aggregate record counts with the source inventory. Disable the canary and retain the old path if consent, access, retention, or mapping checks fail.

Migration Types

Instructions

Step 1: Pre-Migration Assessment

// Inventory your current meeting data
interface MigrationInventory {
  totalRecordings: number;
  totalHours: number;
  formats: string[];        // mp3, mp4, wav, m4a, ogg
  averageDuration: number;  // minutes
  dateRange: { oldest: string; newest: string };
  platforms: string[];      // Zoom, Teams, etc.
}

// Fireflies supports: mp3, mp4, wav, m4a, ogg
// Size limits: 200MB audio, 100MB video (free), 1.5GB video (paid)
// Minimum: 50KB (can bypass with bypass_size_check: true)

Step 2: Batch Upload Historical Recordings

const FIREFLIES_API = "https://api.fireflies.ai/graphql";

interface UploadJob {
  url: string;        // Must be publicly accessible HTTPS URL
  title: string;
  attendees?: { displayName: string; email: string }[];
  referenceId: string; // Your internal ID for tracking
}

async function batchUpload(jobs: UploadJob[]) {
  const results: { id: string; status: string; error?: string }[] = [];

  for (const job of jobs) {
    try {
      const res = await fetch(FIREFLIES_API, {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          Authorization: `Bearer ${process.env.FIREFLIES_API_KEY}`,
        },
        body: JSON.stringify({
          query: `
            mutation($input: AudioUploadInput) {
              uploadAudio(input: $input) {
                success title message
              }
            }
          `,
          variables: {
            input: {
              url: job.url,
              title: job.title,
              attendees: job.attendees,
              client_reference_id: job.referenceId,
              webhook: process.env.WEBHOOK_URL,
            },
          },
        }),
      });

      const json = await res.json();
      if (json.errors) {
        results.push({ id: job.referenceId, status: "error", error: json.errors[0].message });
      } else {
        results.push({ id: job.referenceId, status: "uploaded" });
      }
    } catch (err) {
      results.push({ id: job.referenceId, status: "error", error: (err as Error).message });
    }

    // Rate limit: wait between uploads
    await new Promise(r => setTimeout(r, 2000));
  }

  return results;
}

Step 3: Upload with Authenticated URLs

If your recordings are behind auth (S3, GCS):

// Bearer token auth (e.g., pre-signed URLs with auth headers)
const upload = {
  url: "https://storage.example.com/recordings/meeting-123.mp3",
  title: "Q1 Planning",
  download_auth: {
    type: "bearer_token",
    bearer: { token: "your-storage-access-token" },
  },
  client_reference_id: "meeting-123",
};

// Basic auth
const uploadBasicAuth = {
  url: "https://recordings.example.com/files/meeting-456.mp3",
  title: "Sprint Review",
  download_auth: {
    type: "basic_auth",
    basic: { username: "api-user", password: "api-pass" },
  },
  client_reference_id: "meeting-456",
};

Step 4: Direct File Upload (No Public URL)

For files that can't be made publicly accessible:

// Step 1: Get a pre-signed upload URL from Fireflies
const { createUploadUrl } = await firefliesQuery(`
  mutation($input: CreateUploadUrlInput!) {
    createUploadUrl(input: $input) {
      url
      meeting_id
    }
  }
`, { input: { /* file metadata */ } });

// Step 2: Upload file directly to the pre-signed URL
await fetch(createUploadUrl.url, {
  method: "PUT",
  body: fileBuffer,
});

// Step 3: Confirm the upload
await firefliesQuery(`
  mutation($input: ConfirmUploadInput!) {
    confirmUpload(input: $input) {
      success
    }
  }
`, { input: { meeting_id: createUploadUrl.meeting_id } });

Step 5: Track Migration Progress via Webhooks

// Webhook handler tracks which uploads have completed
const migrationTracker = new Map<string, { status: string; meetingId?: string }>();

async function handleMigrationWebhook(event: any) {
  if (event.eventType === "Transcription completed" && event.clientReferenceId) {
    migrationTracker.set(event.clientReferenceId, {
      status: "completed",
      meetingId: event.meetingId,
    });

    // Check progress
    const completed = [...migrationTracker.values()].filter(v => v.status === "completed").length;
    const total = migrationTracker.size;
    console.log(`Migration progress: ${completed}/${total} (${Math.round(completed/total*100)}%)`);
  }
}

Step 6: Validate Migration

async function validateMigration(expectedIds: string[]) {
  const results = {
    found: 0,
    missing: [] as string[],
    hasSummary: 0,
    hasSentences: 0,
  };

  for (const refId of expectedIds) {
    const tracker = migrationTracker.get(refId);
    if (!tracker?.meetingId) {
      results.missing.push(refId);
      continue;
    }

    results.found++;

    // Verify transcript quality
    const { transcript } = await firefliesQuery(`
      query($id: String!) {
        transcript(id: $id) {
          id title
          sentences { text }
          summary { overview action_items }
        }
      }
    `, { id: tracker.meetingId });

    if (transcript.summary?.overview) results.hasSummary++;
    if (transcript.sentences?.length > 0) results.hasSentences++;

    await new Promise(r => setTimeout(r, 1100)); // Rate limit
  }

  console.log(`Validation: ${results.found}/${expectedIds.length} found`);
  console.log(`With summary: ${results.hasSummary}`);
  console.log(`With sentences: ${results.hasSentences}`);
  console.log(`Missing: ${results.missing.length}`);

  return results;
}

Step 7: Adapter Pattern for Gradual Cutover

interface TranscriptionService {
  getTranscript(id: string): Promise<any>;
  searchTranscripts(query: string): Promise<any[]>;
}

class FirefliesService implements TranscriptionService {
  async getTranscript(id: string) {
    return firefliesQuery(`
      query($id: String!) {
        transcript(id: $id) {
          id title date duration
          sentences { speaker_name text start_time end_time }
          summary { overview action_items }
        }
      }
    `, { id });
  }

  async searchTranscripts(query: string) {
    const data = await firefliesQuery(`
      query($keyword: String) {
        transcripts(keyword: $keyword, limit: 20) {
          id title date duration
        }
      }
    `, { keyword: query });
    return data.transcripts;
  }
}

// Gradual cutover with feature flag
function getTranscriptionService(): TranscriptionService {
  if (process.env.USE_FIREFLIES === "true") {
    return new FirefliesService();
  }
  return new LegacyTranscriptionService();
}

Error Handling

Output

• Pre-migration inventory assessed
• Historical recordings uploaded via uploadAudio mutation
• Migration progress tracked via webhooks and clientReferenceId
• Post-migration validation confirming transcript quality
• Adapter layer enabling gradual platform cutover

Resources

• Upload Audio Mutation
• Fireflies API Docs

Next Steps

For monitoring the migrated system, see fireflies-observability.