Apply production-ready Fireflies.ai SDK patterns for TypeScript and Python.
Use when implementing Fireflies.ai integrations, refactoring SDK usage,
or establishing team coding standards for Fireflies.ai.
Trigger with phrases like "fireflies SDK patterns", "fireflies best practices",
"fireflies code patterns", "idiomatic fireflies".
Production-ready patterns for the Fireflies.ai GraphQL API. Fireflies has no official SDK -- all interaction is via HTTP POST to https://api.fireflies.ai/graphql. These patterns provide typed wrappers, error handling, caching, and multi-tenant support.
Prerequisites
FIREFLIES_API_KEY environment variable set
TypeScript 5+ or Python 3.10+
Optional: graphql-request for typed queries
Instructions
Step 1: Typed GraphQL Client (TypeScript)
// lib/fireflies-client.ts
const FIREFLIES_API = "https://api.fireflies.ai/graphql";
interface FirefliesError {
message: string;
code?: string;
extensions?: { status: number; helpUrls?: string[] };
}
interface FirefliesResponse<T> {
data?: T;
errors?: FirefliesError[];
}
export class FirefliesClient {
private apiKey: string;
private baseUrl: string;
constructor(apiKey?: string) {
this.apiKey = apiKey || process.env.FIREFLIES_API_KEY!;
this.baseUrl = FIREFLIES_API;
if (!this.apiKey) throw new Error("FIREFLIES_API_KEY is required");
}
async query<T = any>(gql: string, variables?: Record<string, any>): Promise<T> {
const res = await fetch(this.baseUrl, {
method: "POST",
headers: {
"Content-Type": "application/json",
Authorization: `Bearer ${this.apiKey}`,
},
body: JSON.stringify({ query: gql, variables }),
});
const json: FirefliesResponse<T> = await res.json();
if (json.errors?.length) {
const err = json.errors[0];
const error = new Error(`Fireflies: ${err.message}`) as any;
error.code = err.code;
error.status = err.extensions?.status;
throw error;
}
return json.data!;
}
// Convenience methods for common queries
async getUser() {
return this.query<{ user: any }>(`{ user { name email user_id is_admin } }`);
}
async getTranscripts(limit = 20) {
return this.query<{ transcripts: any[] }>(`
query($limit: Int) {
transcripts(limit: $limit) {
id title date duration organizer_email participants
summary { overview action_items keywords }
}
}
`, { limit });
}
async getTranscript(id: string) {
return this.query<{ transcript: any }>(`
query($id: String!) {
transcript(id: $id) {
id title date duration
speakers { id name }
sentences { speaker_name text start_time end_time }
summary { overview action_items keywords short_summary }
analytics {
sentiments { positive_pct negative_pct neutral_pct }
speakers { name duration word_count questions }
}
}
}
`, { id });
}
}
Step 2: Singleton Pattern
// lib/fireflies.ts
let instance: FirefliesClient | null = null;
export function getFirefliesClient(): FirefliesClient {
if (!instance) {
instance = new FirefliesClient();
}
return instance;
}
Step 3: Multi-Tenant Factory
const tenantClients = new Map<string, FirefliesClient>();
export function getClientForTenant(tenantId: string): FirefliesClient {
if (!tenantClients.has(tenantId)) {
const apiKey = getTenantApiKey(tenantId); // from your secret store
tenantClients.set(tenantId, new FirefliesClient(apiKey));
}
return tenantClients.get(tenantId)!;
}
