fireflies-api 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Björn Schotte
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,64 @@
+# fireflies-api
+
+TypeScript SDK for [Fireflies.ai](https://fireflies.ai) with realtime transcription streaming.
+
+## Features
+
+- Full GraphQL API coverage
+- **Live transcription streaming** via Socket.IO (key differentiator)
+- Auto-pagination for large datasets
+- TypeScript-first with full type coverage
+- Works with Node.js 18+ and Bun
+
+## Quick Start
+
+```bash
+npm install fireflies-api
+```
+
+```typescript
+import { FirefliesClient } from 'fireflies-api';
+
+const client = new FirefliesClient({
+  apiKey: process.env.FIREFLIES_API_KEY!,
+});
+
+// List recent transcripts
+const transcripts = await client.transcripts.list({ limit: 10 });
+
+for (const t of transcripts) {
+  console.log(`${t.title} - ${t.date}`);
+}
+```
+
+## Realtime Transcription
+
+Stream live transcription from an active meeting:
+
+```typescript
+for await (const chunk of client.realtime.stream('meeting-id')) {
+  console.log(`${chunk.speaker_name}: ${chunk.text}`);
+}
+```
+
+## Documentation
+
+- [Getting Started](docs/getting-started.md) - Installation and configuration
+- [Transcripts](docs/transcripts.md) - Query and manage transcripts
+- [Realtime Streaming](docs/realtime.md) - Live transcription
+- [Users & Teams](docs/users-and-teams.md) - User management
+- [Bites](docs/bites.md) - Clips and soundbites
+- [Meetings](docs/meetings.md) - Active meetings and bot management
+- [Audio Upload](docs/audio-upload.md) - Upload audio for transcription
+- [AI Apps](docs/ai-apps.md) - AI application outputs
+- [Pagination](docs/pagination.md) - Auto-pagination patterns
+- [Error Handling](docs/error-handling.md) - Error types and recovery
+- [Migration Guide](docs/migration.md) - Migrating from official SDK
+
+## API Reference
+
+For Fireflies API field details, see [docs.fireflies.ai](https://docs.fireflies.ai).
+
+## License
+
+MIT

package/dist/action-items-CC9yUxHY.d.cts

@@ -0,0 +1,380 @@
+/**
+ * A meeting transcript from Fireflies.
+ */
+interface Transcript {
+    /** Unique identifier for the transcript */
+    id: string;
+    /** Title of the meeting */
+    title: string;
+    /** Email of the meeting organizer */
+    organizer_email: string;
+    /**
+     * Email of the meeting host
+     * @deprecated Use organizer_email instead
+     */
+    host_email?: string;
+    /** User who owns this transcript */
+    user?: User;
+    /** List of speakers identified in the transcript */
+    speakers: Speaker[];
+    /** URL to view the transcript in Fireflies app */
+    transcript_url: string;
+    /** List of participant email addresses */
+    participants: string[];
+    /** Detailed attendee information from calendar invite */
+    meeting_attendees: MeetingAttendee[];
+    /** Attendance tracking with join/leave times (v2.10.0+) */
+    meeting_attendance: MeetingAttendance[];
+    /** Fireflies user IDs with access */
+    fireflies_users: string[];
+    /** Workspace user IDs with access (v2.20.0+) */
+    workspace_users: string[];
+    /** Duration of the meeting in minutes */
+    duration: number;
+    /** ISO 8601 date string of the meeting */
+    dateString: string;
+    /** Unix timestamp in milliseconds */
+    date: number;
+    /**
+     * URL to download audio (expires after 24h).
+     * Requires Pro plan or higher.
+     */
+    audio_url?: string;
+    /**
+     * URL to download video (expires after 24h).
+     * Requires Business plan or higher.
+     */
+    video_url?: string;
+    /** Transcribed sentences with speaker attribution */
+    sentences: Sentence[];
+    /** Calendar event ID */
+    calendar_id?: string;
+    /** AI-generated meeting summary */
+    summary?: Summary;
+    /** Meeting metadata and processing status */
+    meeting_info?: MeetingInfo;
+    /** Alternative calendar ID field */
+    cal_id?: string;
+    /** Type of calendar (google, outlook, etc.) */
+    calendar_type?: string;
+    /** AI Apps output preview */
+    apps_preview?: AppsPreview;
+    /** Link to the original meeting */
+    meeting_link?: string;
+    /**
+     * Meeting analytics and metrics.
+     * Requires Pro plan or higher.
+     */
+    analytics?: MeetingAnalytics;
+    /** Channels this transcript is shared to (v2.11.0+) */
+    channels: Channel[];
+}
+/**
+ * A Fireflies user.
+ */
+interface User {
+    /** Unique user ID */
+    user_id: string;
+    /** User's email address */
+    email: string;
+    /** User's display name */
+    name?: string;
+    /** Number of transcripts */
+    num_transcripts?: number;
+    /** Whether user is admin */
+    is_admin?: boolean;
+}
+/**
+ * A speaker identified in the transcript.
+ */
+interface Speaker {
+    /** Unique speaker ID within this transcript */
+    id: string;
+    /** Speaker's name (may be auto-detected or manually assigned) */
+    name: string;
+}
+/**
+ * A single sentence in the transcript.
+ */
+interface Sentence {
+    /** Zero-based index of the sentence */
+    index: number;
+    /** Processed text with formatting */
+    text: string;
+    /** Original unprocessed text */
+    raw_text: string;
+    /** Start time as decimal seconds string */
+    start_time: string;
+    /** End time as decimal seconds string */
+    end_time: string;
+    /** ID of the speaker */
+    speaker_id: string;
+    /** Name of the speaker */
+    speaker_name: string;
+    /** AI-detected filters and tags */
+    ai_filters?: AIFilter;
+}
+/**
+ * AI-generated meeting summary sections.
+ */
+interface Summary {
+    /** Action items extracted from the meeting */
+    action_items?: string;
+    /** Key topics and keywords */
+    keywords?: string;
+    /** Structured outline of the meeting */
+    outline?: string;
+    /** High-level overview */
+    overview?: string;
+    /** Shorthand bullet point summary */
+    shorthand_bullet?: string;
+    /** Detailed meeting notes */
+    notes?: string;
+    /** Very brief summary (1-2 sentences) */
+    gist?: string;
+    /** Brief bullet point summary */
+    bullet_gist?: string;
+    /** Short summary paragraph */
+    short_summary?: string;
+    /** Short overview paragraph */
+    short_overview?: string;
+    /** Detected meeting type (standup, interview, etc.) */
+    meeting_type?: string;
+    /** List of topics discussed */
+    topics_discussed?: string[];
+    /** Chapter markers for the transcript */
+    transcript_chapters?: string[];
+    /** Custom summary sections */
+    extended_sections?: SummarySection[];
+}
+/**
+ * Custom summary section from AI Apps.
+ */
+interface SummarySection {
+    /** Section title */
+    title: string;
+    /** Section content */
+    content: string;
+}
+/**
+ * Attendee information from calendar invite.
+ */
+interface MeetingAttendee {
+    /** Display name */
+    displayName: string;
+    /** Email address */
+    email: string;
+    /** Phone number if provided */
+    phoneNumber?: string;
+    /** Full name */
+    name: string;
+    /** Location if provided */
+    location?: string;
+}
+/**
+ * Attendance tracking with join/leave times.
+ * Available in API v2.10.0+.
+ */
+interface MeetingAttendance {
+    /** Attendee name */
+    name: string;
+    /** ISO 8601 timestamp when they joined */
+    join_time: string;
+    /** ISO 8601 timestamp when they left (null if still in meeting) */
+    leave_time?: string;
+}
+/**
+ * Meeting metadata and processing status.
+ */
+interface MeetingInfo {
+    /** Whether the Fireflies bot (Fred) joined the meeting */
+    fred_joined: boolean;
+    /** Whether this was a silent recording (no bot audio) */
+    silent_meeting: boolean;
+    /** Status of AI summary processing */
+    summary_status: SummaryStatus;
+}
+/**
+ * Summary processing status.
+ */
+type SummaryStatus = 'processing' | 'processed' | 'failed' | 'skipped';
+/**
+ * AI-detected content filters for a sentence.
+ */
+interface AIFilter {
+    /** Task or action item */
+    task?: string;
+    /** Pricing discussion */
+    pricing?: string;
+    /** Metric or KPI mentioned */
+    metric?: string;
+    /** Question asked */
+    question?: string;
+    /** Date and time mention */
+    date_and_time?: string;
+    /** Cleaned up text */
+    text_cleanup?: string;
+    /** Sentiment analysis (positive, negative, neutral) */
+    sentiment?: string;
+}
+/**
+ * Channel for sharing transcripts (v2.11.0+).
+ */
+interface Channel {
+    /** Unique channel ID */
+    id: string;
+    /** Channel title */
+    title: string;
+    /** Whether the channel is private */
+    is_private?: boolean;
+    /** ISO 8601 creation timestamp */
+    created_at?: string;
+    /** ISO 8601 last update timestamp */
+    updated_at?: string;
+    /** User ID of channel creator */
+    created_by?: string;
+    /** Channel members */
+    members?: ChannelMember[];
+}
+/**
+ * A member of a channel.
+ */
+interface ChannelMember {
+    /** User ID */
+    user_id: string;
+    /** Email address */
+    email: string;
+    /** Display name */
+    name: string;
+}
+/**
+ * AI Apps output preview.
+ */
+interface AppsPreview {
+    /** Array of AI app outputs */
+    outputs: AIAppOutput[];
+}
+/**
+ * Output from an AI App.
+ */
+interface AIAppOutput {
+    /** Transcript identifier */
+    transcript_id?: string;
+    /** User identifier */
+    user_id?: string;
+    /** App identifier */
+    app_id?: string;
+    /** Timestamp when generated (Unix timestamp) */
+    created_at?: number;
+    /** App title */
+    title?: string;
+    /** The prompt used */
+    prompt?: string;
+    /** The AI response */
+    response?: string;
+}
+/**
+ * Meeting analytics and metrics.
+ * Requires Pro plan or higher.
+ */
+interface MeetingAnalytics {
+    /** Sentiment breakdown */
+    sentiments?: Sentiments;
+}
+/**
+ * Sentiment percentages for a meeting.
+ */
+interface Sentiments {
+    /** Percentage of negative sentiment (0-100) */
+    negative_pct?: number;
+    /** Percentage of neutral sentiment (0-100) */
+    neutral_pct?: number;
+    /** Percentage of positive sentiment (0-100) */
+    positive_pct?: number;
+}
+
+/**
+ * A single action item extracted from the transcript.
+ */
+interface ActionItem {
+    /** The action item text */
+    text: string;
+    /** Detected assignee name (if found in text) */
+    assignee?: string;
+    /** Detected due date (if found in text) */
+    dueDate?: string;
+    /** Original line number in action_items string (1-indexed) */
+    lineNumber: number;
+    /** Related sentence from transcript (if AIFilter.task matched) */
+    sourceSentence?: {
+        speakerName: string;
+        text: string;
+        startTime: number;
+    };
+}
+/**
+ * Result of action item extraction.
+ */
+interface ActionItemsResult {
+    /** Extracted action items */
+    items: ActionItem[];
+    /** Total count of action items */
+    totalItems: number;
+    /** Items with detected assignees */
+    assignedItems: number;
+    /** Items with detected due dates */
+    datedItems: number;
+    /** Unique assignees found */
+    assignees: string[];
+}
+/**
+ * Options for action item extraction.
+ */
+interface ActionItemOptions {
+    /**
+     * Attempt to detect assignees from text patterns (default: true).
+     * Looks for patterns like "@Alice", "Alice:", "assigned to Alice".
+     */
+    detectAssignees?: boolean;
+    /**
+     * Attempt to detect due dates from text patterns (default: true).
+     * Looks for patterns like "by Friday", "due 2024-01-15", "EOD".
+     */
+    detectDueDates?: boolean;
+    /**
+     * Match action items with AIFilter.task in sentences (default: false).
+     * When enabled, correlates summary items with source sentences.
+     */
+    includeSourceSentences?: boolean;
+    /**
+     * Known participant names for better assignee matching (default: []).
+     * Improves accuracy by limiting to actual meeting participants.
+     */
+    participantNames?: string[];
+}
+/**
+ * Extract structured action items from a transcript.
+ *
+ * Parses the action_items field from the transcript summary into
+ * structured data with optional assignee and due date detection.
+ *
+ * **Note:** These action items are generated by Fireflies' AI processing
+ * during transcription. For custom action item extraction or different
+ * interpretation logic, consider running your own LLM calls on the
+ * transcript sentences directly.
+ *
+ * @param transcript - The transcript to extract action items from
+ * @param options - Extraction options
+ * @returns Structured action items with metadata
+ *
+ * @example
+ * ```typescript
+ * const result = extractActionItems(transcript);
+ * for (const item of result.items) {
+ *   console.log(`${item.text} -> ${item.assignee ?? 'unassigned'}`);
+ * }
+ * ```
+ */
+declare function extractActionItems(transcript: Transcript, options?: ActionItemOptions): ActionItemsResult;
+
+export { type ActionItemsResult as A, type Channel as C, type MeetingAnalytics as M, type Speaker as S, type Transcript as T, type User as U, type ActionItemOptions as a, type ActionItem as b, type AIAppOutput as c, type AIFilter as d, type AppsPreview as e, type ChannelMember as f, type MeetingAttendance as g, type MeetingAttendee as h, type MeetingInfo as i, type Sentence as j, type Sentiments as k, type Summary as l, type SummarySection as m, type SummaryStatus as n, extractActionItems as o };