fireflies-api 0.5.0

package/dist/speaker-analytics-l45LXqO1.d.cts

@@ -0,0 +1,275 @@
+import { S as Speaker, T as Transcript } from './action-items-CC9yUxHY.cjs';
+
+/**
+ * Options for normalizing a Fireflies transcript to provider-agnostic format.
+ */
+interface NormalizationOptions {
+    /**
+     * Time unit for timestamps in sentences.
+     * @default 'seconds'
+     */
+    timeUnit?: 'seconds' | 'milliseconds';
+    /**
+     * Include original Fireflies data in source.rawData.
+     * @default false
+     */
+    includeRawData?: boolean;
+    /**
+     * Include AI-detected filters (sentiment, questions, tasks) in sentences.
+     * @default true
+     */
+    includeAIFilters?: boolean;
+    /**
+     * Include summary data if available.
+     * @default true
+     */
+    includeSummary?: boolean;
+    /**
+     * Custom speaker name resolver (e.g., map "Speaker 1" to real name).
+     */
+    resolveSpeakerName?: (speaker: Speaker, transcript: Transcript) => string;
+    /**
+     * Custom participant enrichment (e.g., add roles from external source).
+     */
+    enrichParticipant?: (email: string, transcript: Transcript) => Partial<NormalizedParticipant>;
+}
+/**
+ * A provider-agnostic normalized meeting transcript.
+ */
+interface NormalizedMeeting {
+    /** Prefixed ID: "fireflies:abc123" */
+    id: string;
+    /** Meeting title */
+    title: string;
+    /** Meeting date */
+    date: Date;
+    /** Duration in seconds */
+    duration: number;
+    /** URL to view the transcript */
+    url: string;
+    /** Speakers identified in the transcript */
+    speakers: NormalizedSpeaker[];
+    /** Transcribed sentences */
+    sentences: NormalizedSentence[];
+    /** Meeting participants */
+    participants: NormalizedParticipant[];
+    /** AI-generated summary (if available and enabled) */
+    summary?: NormalizedSummary;
+    /** Meeting attendees with join/leave times */
+    attendees?: NormalizedAttendee[];
+    /** Channels the transcript is shared to */
+    channels?: NormalizedChannel[];
+    /** Meeting analytics */
+    analytics?: NormalizedAnalytics;
+    /** Source provider information */
+    source: {
+        provider: 'fireflies';
+        originalId: string;
+        rawData?: Transcript;
+    };
+}
+/**
+ * A normalized speaker in the transcript.
+ */
+interface NormalizedSpeaker {
+    /** Speaker ID */
+    id: string;
+    /** Speaker name */
+    name: string;
+}
+/**
+ * A normalized sentence in the transcript.
+ */
+interface NormalizedSentence {
+    /** Zero-based index */
+    index: number;
+    /** Speaker ID */
+    speakerId: string;
+    /** Speaker name */
+    speakerName: string;
+    /** Processed text */
+    text: string;
+    /** Original unprocessed text */
+    rawText: string;
+    /** Start time (in timeUnit) */
+    startTime: number;
+    /** End time (in timeUnit) */
+    endTime: number;
+    /** AI-detected sentiment */
+    sentiment?: 'positive' | 'negative' | 'neutral';
+    /** Whether this sentence is a question */
+    isQuestion?: boolean;
+    /** Whether this sentence is an action item */
+    isActionItem?: boolean;
+}
+/**
+ * A normalized meeting participant.
+ */
+interface NormalizedParticipant {
+    /** Participant name */
+    name: string;
+    /** Email address */
+    email?: string;
+    /** Role in the meeting */
+    role?: 'organizer' | 'attendee';
+}
+/**
+ * A normalized meeting summary.
+ */
+interface NormalizedSummary {
+    /** High-level overview */
+    overview?: string;
+    /** Key points or bullet summary */
+    keyPoints?: string[];
+    /** Action items text */
+    actionItems?: string;
+    /** Structured outline */
+    outline?: string;
+    /** Topics discussed */
+    topics?: string[];
+}
+/**
+ * A normalized meeting attendee with join/leave times.
+ */
+interface NormalizedAttendee {
+    /** Attendee name */
+    name: string;
+    /** Email address */
+    email?: string;
+    /** Phone number */
+    phoneNumber?: string;
+    /** Time they joined */
+    joinTime?: Date;
+    /** Time they left */
+    leaveTime?: Date;
+}
+/**
+ * A normalized channel.
+ */
+interface NormalizedChannel {
+    /** Channel ID */
+    id: string;
+    /** Channel title */
+    title: string;
+    /** Whether the channel is private */
+    isPrivate: boolean;
+}
+/**
+ * Normalized meeting analytics.
+ */
+interface NormalizedAnalytics {
+    /** Sentiment breakdown (percentages 0-100) */
+    sentiments?: {
+        positive: number;
+        neutral: number;
+        negative: number;
+    };
+}
+
+/**
+ * Statistics for a single speaker in the meeting.
+ */
+interface SpeakerStats {
+    /** Speaker name from transcript */
+    name: string;
+    /** Speaker ID from transcript */
+    id: string;
+    /** Total talk time in seconds */
+    talkTime: number;
+    /** Percentage of total meeting talk time (0-100) */
+    talkTimePercentage: number;
+    /** Number of sentences spoken */
+    sentenceCount: number;
+    /** Total words spoken */
+    wordCount: number;
+    /** Words per minute (based on talk time) */
+    wordsPerMinute: number;
+    /** Average words per sentence */
+    averageSentenceLength: number;
+    /** Number of speaking turns (consecutive sentence groups) */
+    turnCount: number;
+}
+/**
+ * Overall meeting speaker analytics.
+ */
+interface SpeakerAnalytics {
+    /** Per-speaker statistics, sorted by talk time descending */
+    speakers: SpeakerStats[];
+    /** Total meeting duration from sentences (seconds) */
+    totalDuration: number;
+    /** Total talk time across all speakers (seconds) */
+    totalTalkTime: number;
+    /** Total sentences in transcript */
+    totalSentences: number;
+    /** Total words spoken */
+    totalWords: number;
+    /** Name of speaker with most talk time */
+    dominantSpeaker: string;
+    /** Talk time percentage of dominant speaker */
+    dominantSpeakerPercentage: number;
+    /** Balance indicator: balanced, unbalanced, or dominated */
+    balance: 'balanced' | 'unbalanced' | 'dominated';
+}
+/**
+ * Options for speaker analysis.
+ */
+interface SpeakerAnalyticsOptions {
+    /**
+     * Merge speakers with identical names into a single entry (default: true).
+     *
+     * Fireflies' speaker diarization can incorrectly assign multiple speaker IDs
+     * to the same person, especially with:
+     * - Multiple audio channels/microphones
+     * - Short utterances being misattributed
+     * - Audio quality issues causing speaker model confusion
+     *
+     * This commonly manifests as rapid alternation between two IDs for the same
+     * speaker name, resulting in inflated turn counts and split statistics.
+     *
+     * When enabled (default), speakers are grouped by name rather than ID,
+     * combining their talk time, word counts, and other metrics. Turn counting
+     * uses speaker names, so consecutive sentences from the same person count
+     * as one turn regardless of ID changes.
+     *
+     * Set to `false` to preserve the raw speaker IDs from Fireflies, which may
+     * be useful for debugging diarization issues or when you have confirmed that
+     * multiple people share the same display name.
+     */
+    mergeSpeakersByName?: boolean;
+    /** Round percentages to integers (default: true) */
+    roundPercentages?: boolean;
+    /** Threshold for 'unbalanced' classification (default: 40) */
+    unbalancedThreshold?: number;
+    /** Threshold for 'dominated' classification (default: 60) */
+    dominatedThreshold?: number;
+}
+/**
+ * Analyze speaker participation in a transcript.
+ *
+ * Computes talk time percentages, word counts, and participation metrics
+ * for each speaker in the meeting.
+ *
+ * @param transcript - The transcript to analyze
+ * @param options - Analysis options
+ * @returns Speaker analytics with per-speaker stats and totals
+ *
+ * @example
+ * ```typescript
+ * import { FirefliesClient, analyzeSpeakers } from 'fireflies-api';
+ *
+ * const client = new FirefliesClient({ apiKey: 'your-api-key' });
+ * const transcript = await client.transcripts.get({ id: 'transcript-id' });
+ *
+ * const analytics = analyzeSpeakers(transcript);
+ *
+ * console.log(`${analytics.speakers.length} speakers`);
+ * console.log(`Dominant: ${analytics.dominantSpeaker} (${analytics.dominantSpeakerPercentage}%)`);
+ *
+ * for (const speaker of analytics.speakers) {
+ *   console.log(`${speaker.name}: ${speaker.talkTimePercentage}% talk time, ${speaker.wordCount} words`);
+ * }
+ * ```
+ */
+declare function analyzeSpeakers(transcript: Transcript, options?: SpeakerAnalyticsOptions): SpeakerAnalytics;
+
+export { type NormalizedMeeting as N, type SpeakerAnalytics as S, type NormalizationOptions as a, type NormalizedAnalytics as b, type NormalizedAttendee as c, type NormalizedChannel as d, type NormalizedParticipant as e, type NormalizedSentence as f, type NormalizedSpeaker as g, type NormalizedSummary as h, type SpeakerAnalyticsOptions as i, type SpeakerStats as j, analyzeSpeakers as k };

package/dist/types-BX-3JcRI.d.cts

@@ -0,0 +1,41 @@
+import { W as WebhookPayload, F as FirefliesClient } from './types-C_XxdRd1.cjs';
+import { T as Transcript } from './action-items-CC9yUxHY.cjs';
+
+/**
+ * Context provided to webhook event handlers.
+ */
+interface WebhookHandlerContext {
+    /** The parsed and validated webhook payload */
+    payload: WebhookPayload;
+    /** The full transcript, if apiKey provided and autoFetch enabled */
+    transcript?: Transcript;
+    /** FirefliesClient instance, available if apiKey provided */
+    client?: FirefliesClient;
+}
+/**
+ * Handler function for webhook events.
+ */
+type WebhookEventHandler = (context: WebhookHandlerContext) => void | Promise<void>;
+/**
+ * Error handler function for webhook processing errors.
+ */
+type WebhookErrorHandler = (error: Error, payload?: WebhookPayload) => void | Promise<void>;
+/**
+ * Options for configuring webhook middleware.
+ */
+interface WebhookMiddlewareOptions {
+    /** Webhook secret for signature verification (required) */
+    secret: string;
+    /** API key for auto-fetching transcripts (optional) */
+    apiKey?: string;
+    /** Auto-fetch transcript when apiKey is provided (default: true if apiKey provided) */
+    autoFetch?: boolean;
+    /** Handler called for 'Transcription completed' events */
+    onTranscriptionCompleted?: WebhookEventHandler;
+    /** Generic handler called for all events (runs before specific handlers) */
+    onEvent?: WebhookEventHandler;
+    /** Handler called when an error occurs during processing */
+    onError?: WebhookErrorHandler;
+}
+
+export type { WebhookMiddlewareOptions as W };