ffx-cli 0.1.0__py3-none-any.whl

ffx/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

ffx/__main__.py

@@ -0,0 +1,4 @@
+from ffx.commands import app
+
+if __name__ == "__main__":
+    app()

ffx/api_client.py

@@ -0,0 +1,261 @@
+from __future__ import annotations
+
+from gql import Client, gql
+from gql.transport.httpx import HTTPXTransport
+
+from ffx.models import (
+    ActionItem,
+    Sentence,
+    Speaker,
+    Summary,
+    Topic,
+    Transcript,
+)
+
+FIREFLIES_API_URL = "https://api.fireflies.ai/graphql"
+
+# participants is [String!] (emails), not objects
+# analytics.speakers is the correct path (not speaker_talk_time_percentage)
+LIST_TRANSCRIPTS_QUERY = gql("""
+    query Transcripts($limit: Int, $skip: Int, $keyword: String, $fromDate: DateTime, $toDate: DateTime, $participants: [String!]) {
+        transcripts(limit: $limit, skip: $skip, keyword: $keyword, fromDate: $fromDate, toDate: $toDate, participants: $participants) {
+            id
+            title
+            date
+            duration
+            organizer_email
+            participants
+            summary {
+                action_items keywords overview gist bullet_gist
+                shorthand_bullet outline short_summary short_overview
+                meeting_type topics_discussed
+            }
+            analytics {
+                speakers {
+                    speaker_id name duration duration_pct word_count
+                    words_per_minute filler_words questions
+                    longest_monologue monologues_count
+                }
+            }
+        }
+    }
+""")
+
+GET_TRANSCRIPT_QUERY = gql("""
+    query Transcript($id: String!) {
+        transcript(id: $id) {
+            id
+            title
+            date
+            duration
+            organizer_email
+            participants
+            summary {
+                action_items keywords overview gist bullet_gist
+                shorthand_bullet outline short_summary short_overview
+                meeting_type topics_discussed
+            }
+            analytics {
+                speakers {
+                    speaker_id name duration duration_pct word_count
+                    words_per_minute filler_words questions
+                    longest_monologue monologues_count
+                }
+            }
+        }
+    }
+""")
+
+
+GET_TRANSCRIPT_WITH_SENTENCES_QUERY = gql("""
+    query Transcript($id: String!) {
+        transcript(id: $id) {
+            id
+            title
+            date
+            duration
+            organizer_email
+            participants
+            summary {
+                action_items keywords overview gist bullet_gist
+                shorthand_bullet outline short_summary short_overview
+                meeting_type topics_discussed
+            }
+            analytics {
+                speakers {
+                    speaker_id name duration duration_pct word_count
+                    words_per_minute filler_words questions
+                    longest_monologue monologues_count
+                }
+            }
+            sentences {
+                index
+                speaker_name
+                speaker_id
+                text
+                raw_text
+                start_time
+                end_time
+            }
+        }
+    }
+""")
+
+
+class AuthError(Exception):
+    pass
+
+
+class ApiError(Exception):
+    pass
+
+
+def _parse_transcript(raw: dict) -> Transcript:
+    summary_raw = raw.get("summary") or {}
+    analytics_raw = raw.get("analytics") or {}
+
+    # Most summary fields come back as strings (with newlines), not lists.
+    # Only keywords is a proper list. We store raw and use .action_items_list etc.
+    summary = Summary(
+        overview=summary_raw.get("overview"),
+        short_overview=summary_raw.get("short_overview"),
+        gist=summary_raw.get("gist"),
+        short_summary=summary_raw.get("short_summary"),
+        bullet_gist=summary_raw.get("bullet_gist"),
+        shorthand_bullet=summary_raw.get("shorthand_bullet"),
+        action_items=summary_raw.get("action_items"),
+        keywords=summary_raw.get("keywords") or [],
+        topics_discussed=summary_raw.get("topics_discussed"),
+        outline=summary_raw.get("outline"),
+        meeting_type=summary_raw.get("meeting_type"),
+    )
+
+    participants = raw.get("participants") or []
+
+    speakers = [
+        Speaker(
+            name=s.get("name", ""),
+            speaker_id=s.get("speaker_id"),
+            duration=s.get("duration", 0),
+            duration_pct=s.get("duration_pct", 0.0),
+            word_count=s.get("word_count", 0),
+            words_per_minute=s.get("words_per_minute", 0.0),
+            filler_words=s.get("filler_words", 0),
+            questions=s.get("questions", 0),
+            longest_monologue=s.get("longest_monologue", 0),
+            monologues_count=s.get("monologues_count", 0),
+        )
+        for s in (analytics_raw.get("speakers") or [])
+    ]
+
+    action_items = [
+        ActionItem(text=item, transcript_id=raw.get("id"))
+        for item in summary.action_items_list
+    ]
+
+    topics = [
+        Topic(text=t, transcript_id=raw.get("id"))
+        for t in summary.topics_list
+    ]
+
+    sentences = [
+        Sentence(
+            index=s.get("index", 0),
+            speaker_name=s.get("speaker_name", ""),
+            speaker_id=s.get("speaker_id"),
+            text=s.get("text", ""),
+            raw_text=s.get("raw_text", ""),
+            start_time=s.get("start_time", 0.0),
+            end_time=s.get("end_time", 0.0),
+        )
+        for s in (raw.get("sentences") or [])
+    ]
+
+    return Transcript(
+        id=raw["id"],
+        title=raw.get("title", "Untitled"),
+        date=str(raw.get("date", "")),
+        duration=raw.get("duration", 0),
+        organizer_email=raw.get("organizer_email"),
+        participants=participants,
+        summary=summary,
+        speakers=speakers,
+        action_items=action_items,
+        topics=topics,
+        sentences=sentences,
+        raw=raw,
+    )
+
+
+class FirefliesClient:
+    def __init__(self, api_key: str) -> None:
+        transport = HTTPXTransport(
+            url=FIREFLIES_API_URL,
+            headers={"Authorization": f"Bearer {api_key}"},
+        )
+        self._client = Client(transport=transport, fetch_schema_from_transport=False)
+
+    def _execute(self, query, variables: dict | None = None) -> dict:
+        try:
+            result = self._client.execute(query, variable_values=variables or {})
+            return result
+        except Exception as e:
+            msg = str(e).lower()
+            if "429" in str(e) or "rate limit" in msg:
+                raise ApiError("rate limit exceeded — retry later") from e
+            if "unauthenticated" in msg or "unauthorized" in msg or "401" in str(e):
+                raise AuthError("API key missing or expired") from e
+            if any(code in str(e) for code in ("500", "502", "503")):
+                raise ApiError(f"Fireflies API error: {e}") from e
+            raise ApiError(str(e)) from e
+
+    def list_transcripts(
+        self,
+        limit: int = 10,
+        skip: int = 0,
+        keyword: str | None = None,
+        from_date: str | None = None,
+        to_date: str | None = None,
+        participants: list[str] | None = None,
+    ) -> list[Transcript]:
+        vars: dict = {"limit": limit, "skip": skip}
+        if keyword:
+            vars["keyword"] = keyword
+        if from_date:
+            vars["fromDate"] = from_date
+        if to_date:
+            vars["toDate"] = to_date
+        if participants:
+            vars["participants"] = participants
+        result = self._execute(LIST_TRANSCRIPTS_QUERY, vars)
+        return [_parse_transcript(t) for t in (result.get("transcripts") or [])]
+
+    def get_transcript(self, transcript_id: str) -> Transcript | None:
+        result = self._execute(GET_TRANSCRIPT_QUERY, {"id": transcript_id})
+        raw = result.get("transcript")
+        if raw is None:
+            return None
+        return _parse_transcript(raw)
+
+    def get_transcript_with_sentences(self, transcript_id: str) -> Transcript | None:
+        result = self._execute(GET_TRANSCRIPT_WITH_SENTENCES_QUERY, {"id": transcript_id})
+        raw = result.get("transcript")
+        if raw is None:
+            return None
+        return _parse_transcript(raw)
+
+    def search_transcripts(
+        self,
+        query: str,
+        limit: int = 20,
+        from_date: str | None = None,
+        to_date: str | None = None,
+        participants: list[str] | None = None,
+    ) -> list[Transcript]:
+        return self.list_transcripts(
+            limit=limit,
+            keyword=query,
+            from_date=from_date,
+            to_date=to_date,
+            participants=participants,
+        )

ffx/commands/__init__.py

@@ -0,0 +1,29 @@
+import typer
+from ffx.commands.auth import auth
+from ffx.commands.list_cmd import list_cmd
+from ffx.commands.get import get
+from ffx.commands.search import search
+from ffx.commands.summary import summary
+from ffx.commands.brief import brief
+from ffx.commands.action_items import action_items
+from ffx.commands.export import export
+from ffx.commands.topics import topics
+from ffx.commands.speaker import speaker
+from ffx.commands.transcript import transcript
+from ffx.commands.week import week, month
+
+app = typer.Typer(name="ffx", help="Fireflies.ai CLI", no_args_is_help=True)
+
+app.command()(auth)
+app.command("list")(list_cmd)
+app.command()(get)
+app.command()(search)
+app.command()(summary)
+app.command()(brief)
+app.command("action-items")(action_items)
+app.command()(export)
+app.command()(transcript)
+app.command()(topics)
+app.command()(speaker)
+app.command()(week)
+app.command()(month)

ffx/commands/action_items.py

@@ -0,0 +1,74 @@
+from __future__ import annotations
+from typing import Optional
+from datetime import datetime, timedelta, timezone
+
+import typer
+from ffx.config import Config
+from ffx.api_client import FirefliesClient, AuthError, ApiError
+from ffx.models import ActionItem
+from ffx.output import json_envelope, json_error
+
+
+def action_items(
+    days: Optional[int] = typer.Option(7, "--days", help="Last N days"),
+    owner: Optional[str] = typer.Option(None, "--filter", help="Filter action items by keyword"),
+    limit: int = typer.Option(20, "--limit"),
+    table: bool = typer.Option(False, "--table", help="Rich table output"),
+) -> None:
+    """List action items from recent meetings."""
+    json_mode = not table
+    config = Config()
+    if not config.api_key:
+        if json_mode:
+            typer.echo(json_error("API key not configured", "UNAUTHENTICATED", "Run: ffx auth"))
+        else:
+            typer.echo("API key not set. Run: ffx auth", err=True)
+        raise typer.Exit(2)
+
+    from_date = None
+    if days:
+        from_date = (datetime.now(timezone.utc) - timedelta(days=days)).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+    try:
+        client = FirefliesClient(config.api_key)
+        transcripts = client.list_transcripts(limit=limit, from_date=from_date)
+    except AuthError:
+        if json_mode:
+            typer.echo(json_error("API key may have expired", "UNAUTHENTICATED", "Run: ffx auth"))
+        else:
+            typer.echo("API key may have expired. Run: ffx auth", err=True)
+        raise typer.Exit(2)
+    except ApiError as e:
+        if json_mode:
+            typer.echo(json_error(str(e), "API_ERROR"))
+        else:
+            typer.echo(f"API error: {e}", err=True)
+        raise typer.Exit(2)
+
+    all_items: list[ActionItem] = []
+    for t in transcripts:
+        for item in t.action_items:
+            if owner:
+                text_lower = item.text.lower()
+                assignee_lower = (item.assignee or "").lower()
+                if owner.lower() not in text_lower and owner.lower() not in assignee_lower:
+                    continue
+            all_items.append(item)
+
+    if not all_items:
+        if json_mode:
+            typer.echo(json_envelope([], {"days": days, "owner": owner}))
+        else:
+            typer.echo("No action items found.")
+        return
+
+    if json_mode:
+        results = [
+            {"text": i.text, "assignee": i.assignee, "transcript_id": i.transcript_id}
+            for i in all_items
+        ]
+        typer.echo(json_envelope(results, {"days": days, "owner": owner}))
+    else:
+        for i, item in enumerate(all_items, 1):
+            assignee = f" ({item.assignee})" if item.assignee else ""
+            typer.echo(f"  {i}. {item.text}{assignee}")

ffx/commands/auth.py

@@ -0,0 +1,20 @@
+import typer
+from ffx.config import Config
+
+
+def auth() -> None:
+    """Configure your Fireflies API key."""
+    config = Config()
+
+    if config.api_key:
+        confirm = typer.confirm("An API key is already set. Overwrite?")
+        if not confirm:
+            raise typer.Exit(0)
+
+    key = typer.prompt("Enter your Fireflies API key", hide_input=True)
+    if not key or not key.strip():
+        typer.echo("Error: API key cannot be empty.", err=True)
+        raise typer.Exit(1)
+
+    config.set("api_key", key.strip())
+    typer.echo("API key saved. Run: ffx list to verify.")

ffx/commands/brief.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+import typer
+from ffx.config import Config
+from ffx.api_client import FirefliesClient, AuthError, ApiError
+from ffx.output import json_error, print_summary_brief
+
+
+def brief(
+    transcript_id: str = typer.Argument(..., help="Transcript ID"),
+    table: bool = typer.Option(False, "--table", help="Rich table output"),
+) -> None:
+    """Show a formatted AI brief for a meeting."""
+    json_mode = not table
+    config = Config()
+    if not config.api_key:
+        if json_mode:
+            typer.echo(json_error("API key not configured", "UNAUTHENTICATED", "Run: ffx auth"))
+        else:
+            typer.echo("API key not set. Run: ffx auth", err=True)
+        raise typer.Exit(2)
+
+    try:
+        client = FirefliesClient(config.api_key)
+        t = client.get_transcript(transcript_id)
+    except AuthError:
+        if json_mode:
+            typer.echo(json_error("API key may have expired", "UNAUTHENTICATED", "Run: ffx auth"))
+        else:
+            typer.echo("API key may have expired. Run: ffx auth", err=True)
+        raise typer.Exit(2)
+    except ApiError as e:
+        if json_mode:
+            typer.echo(json_error(str(e), "API_ERROR"))
+        else:
+            typer.echo(f"API error: {e}", err=True)
+        raise typer.Exit(2)
+
+    if t is None:
+        if json_mode:
+            typer.echo(json_error("Transcript not found", "NOT_FOUND"))
+        else:
+            typer.echo(f"Transcript '{transcript_id}' not found.", err=True)
+        raise typer.Exit(3)
+
+    print_summary_brief(t, json_mode=json_mode)

ffx/commands/export.py

@@ -0,0 +1,129 @@
+from __future__ import annotations
+import csv
+import io
+import json
+from enum import Enum
+
+import typer
+from ffx.config import Config
+from ffx.api_client import FirefliesClient, AuthError, ApiError
+from ffx.output import json_error
+
+
+class ExportFormat(str, Enum):
+    json = "json"
+    md = "md"
+    obsidian = "obsidian"
+    csv = "csv"
+
+
+def _to_md(t) -> str:
+    lines = [f"# {t.title}", "", f"**Date:** {t.display_date}"]
+    if t.organizer_email:
+        lines.append(f"**Organizer:** {t.organizer_email}")
+    if t.participants:
+        names = ", ".join(t.participants)
+        lines.append(f"**Participants:** {names}")
+    lines.append("")
+    if t.summary and t.summary.overview:
+        lines += ["## Overview", "", t.summary.overview, ""]
+    if t.summary and t.summary.bullet_gist_list:
+        lines += ["## Key Points", ""]
+        for b in t.summary.bullet_gist_list:
+            lines.append(f"- {b}")
+        lines.append("")
+    if t.summary and t.summary.action_items_list:
+        lines += ["## Action Items", ""]
+        for item in t.summary.action_items_list:
+            lines.append(f"- [ ] {item}")
+        lines.append("")
+    if t.summary and t.summary.keywords:
+        lines.append(f"**Keywords:** {', '.join(t.summary.keywords)}")
+    return "\n".join(lines)
+
+
+def _yaml_str(s: str) -> str:
+    if any(c in s for c in (':', '#', '"', "'", '{', '[', '>', '|', '\n')):
+        escaped = s.replace('\\', '\\\\').replace('"', '\\"')
+        return f'"{escaped}"'
+    return s
+
+
+def _to_obsidian(t) -> str:
+    participants = list(t.participants)
+    keywords = (t.summary.keywords if t.summary else []) or []
+    frontmatter = [
+        "---",
+        f"title: {_yaml_str(t.title)}",
+        f"date: {t.display_date}",
+        f"duration: {t.duration // 60 if t.duration else 0}m",
+        f"organizer: {t.organizer_email or ''}",
+        "participants:",
+    ]
+    for p in participants:
+        frontmatter.append(f"  - {p}")
+    frontmatter.append("tags:")
+    for k in keywords:
+        frontmatter.append(f"  - {_yaml_str(k)}")
+    frontmatter += ["source: fireflies", f"transcript_id: {t.id}", "---", ""]
+    md_body = _to_md(t)
+    # Strip the first line (# Title) since it's in frontmatter
+    body_lines = md_body.split("\n")
+    body = "\n".join(body_lines[1:]) if body_lines else ""
+    return "\n".join(frontmatter) + body
+
+
+def _to_csv(t) -> str:
+    output = io.StringIO()
+    writer = csv.writer(output)
+    writer.writerow(["id", "title", "date", "duration_seconds", "organizer_email", "participants", "overview", "keywords"])
+    participants_str = "|".join(t.participants)
+    overview = t.summary.overview if t.summary else ""
+    keywords = "|".join(t.summary.keywords if t.summary else [])
+    writer.writerow([t.id, t.title, t.display_date, t.duration, t.organizer_email or "", participants_str, overview or "", keywords])
+    return output.getvalue()
+
+
+def export(
+    transcript_id: str = typer.Argument(..., help="Transcript ID"),
+    format: ExportFormat = typer.Option(ExportFormat.json, "--format", help="Output format: json|md|obsidian|csv"),
+) -> None:
+    """Export a meeting transcript in various formats."""
+    config = Config()
+    if not config.api_key:
+        typer.echo(json_error("API key not configured", "UNAUTHENTICATED", "Run: ffx auth"))
+        raise typer.Exit(2)
+
+    try:
+        client = FirefliesClient(config.api_key)
+        t = client.get_transcript(transcript_id)
+    except AuthError:
+        typer.echo("API key may have expired. Run: ffx auth", err=True)
+        raise typer.Exit(2)
+    except ApiError as e:
+        typer.echo(f"API error: {e}", err=True)
+        raise typer.Exit(2)
+
+    if t is None:
+        typer.echo(f"Transcript '{transcript_id}' not found.", err=True)
+        raise typer.Exit(3)
+
+    if format == ExportFormat.json:
+        typer.echo(json.dumps({
+            "id": t.id, "title": t.title, "date": t.display_date,
+            "duration_seconds": t.duration, "organizer_email": t.organizer_email,
+            "participants": t.participants,
+            "summary": {
+                "overview": t.summary.overview,
+                "bullet_gist": t.summary.bullet_gist_list,
+                "action_items": t.summary.action_items_list,
+                "keywords": t.summary.keywords,
+                "topics_discussed": t.summary.topics_list,
+            } if t.summary else None,
+        }, indent=2))
+    elif format == ExportFormat.md:
+        typer.echo(_to_md(t))
+    elif format == ExportFormat.obsidian:
+        typer.echo(_to_obsidian(t))
+    elif format == ExportFormat.csv:
+        typer.echo(_to_csv(t), nl=False)

ffx/commands/get.py

@@ -0,0 +1,64 @@
+from __future__ import annotations
+import json
+import typer
+from ffx.config import Config
+from ffx.api_client import FirefliesClient, AuthError, ApiError
+from ffx.output import json_error, transcript_detail
+
+
+def get(
+    transcript_id: str = typer.Argument(..., help="Transcript ID"),
+    table: bool = typer.Option(False, "--table", help="Rich table output"),
+) -> None:
+    """Fetch a single transcript by ID."""
+    json_mode = not table
+    config = Config()
+    if not config.api_key:
+        if json_mode:
+            typer.echo(json_error("API key not configured", "UNAUTHENTICATED", "Run: ffx auth"))
+        else:
+            typer.echo("API key not set. Run: ffx auth", err=True)
+        raise typer.Exit(2)
+
+    try:
+        client = FirefliesClient(config.api_key)
+        t = client.get_transcript(transcript_id)
+    except AuthError:
+        if json_mode:
+            typer.echo(json_error("API key may have expired", "UNAUTHENTICATED", "Run: ffx auth"))
+        else:
+            typer.echo("API key may have expired. Run: ffx auth", err=True)
+        raise typer.Exit(2)
+    except ApiError as e:
+        if json_mode:
+            typer.echo(json_error(str(e), "API_ERROR"))
+        else:
+            typer.echo(f"API error: {e}", err=True)
+        raise typer.Exit(2)
+
+    if t is None:
+        if json_mode:
+            typer.echo(json_error(f"Transcript {transcript_id!r} not found", "NOT_FOUND"))
+        else:
+            typer.echo(f"Transcript '{transcript_id}' not found.", err=True)
+        raise typer.Exit(3)
+
+    if json_mode:
+        typer.echo(json.dumps({
+            "id": t.id,
+            "title": t.title,
+            "date": t.display_date,
+            "duration_seconds": t.duration,
+            "organizer_email": t.organizer_email,
+            "participants": t.participants,
+            "summary": {
+                "overview": t.summary.overview,
+                "gist": t.summary.gist,
+                "bullet_gist": t.summary.bullet_gist_list,
+                "keywords": t.summary.keywords,
+                "topics_discussed": t.summary.topics_list,
+                "action_items": t.summary.action_items_list,
+            } if t.summary else None,
+        }, indent=2))
+    else:
+        transcript_detail(t)