qodev-apollo-cli 1.0.0__tar.gz → 1.2.0__tar.gz

{qodev_apollo_cli-1.0.0 → qodev_apollo_cli-1.2.0}/CHANGELOG.md

@@ -4,6 +4,30 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [Unreleased]
+
+## [1.2.0] - 2026-07-08
+
+Usage-driven UX improvements — every item here closes a gap where users had been dropping to raw curl or doing extra lookups.
+
+### Added
+
+- **people search — company-domain filter.** `people search --organization-domains acme.com,globex.com` (alias `--domains`) finds people at specific companies — the single most common raw-curl workaround (`q_organization_domains_list`). Also adds `--seniorities`, and `people search` now respects the global `--limit`/`--page` (it previously ignored them). Results render as a table instead of a raw dict.
+- **Filter deals/contacts by stage name.** `deals search --stage-name "Negotiation"` and `contacts search --stage-name "Customer"` resolve the name to an ID internally, removing the round-trip through `pipelines stages` / `contacts stages`. An unknown name fails loudly and lists the valid names.
+- **`conversations transcript ID`** — prints just the transcript (no metadata/summary), for when you only want the words.
+- **Deal contact roles.** `deals role-types` lists the available role types; `deals set-role DEAL_ID --contact-id C [--role-type "Decision Maker"] [--primary]` sets/updates a contact's role on a deal (read-modify-write; `--primary` makes them the sole primary contact). Previously only reachable via curl.
+- **`custom-fields list [--modality]`** — lists custom field definitions across contacts/accounts/opportunities.
+
+### Changed
+
+- Requires `qodev-apollo-api>=0.3.0` (for `update_opportunity_roles` and `list_custom_fields`).
+
+## [1.1.0] - 2026-07-08
+
+### Added
+
+- **conversations**: new command group exposing the recorded-conversation endpoints (Zoom/Teams/Meet). `conversations search [--query]` lists conversations; `conversations get ID` returns the full detail including transcript and AI call summary (outcome, pain points, objections, next steps). The underlying `qodev-apollo-api` client already supported `search_conversations`/`get_conversation` — only the CLI surface was missing. Note this is distinct from `calls`, which covers dialer/phone-call activity, not recorded meetings.
+
 ## [1.0.0] - 2026-07-01
 
 ### Added

{qodev_apollo_cli-1.0.0 → qodev_apollo_cli-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: qodev-apollo-cli
-Version: 1.0.0
+Version: 1.2.0
 Summary: Agent-friendly CLI for the Apollo API
 Project-URL: Homepage, https://github.com/qodevai/apollo-cli
 Project-URL: Repository, https://github.com/qodevai/apollo-cli
@@ -19,7 +19,7 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Typing :: Typed
 Requires-Python: >=3.11
 Requires-Dist: cyclopts>=3.0
-Requires-Dist: qodev-apollo-api>=0.1.0
+Requires-Dist: qodev-apollo-api>=0.3.0
 Requires-Dist: rich>=13.0
 Provides-Extra: dev
 Requires-Dist: mypy>=1.13.0; extra == 'dev'
@@ -88,7 +88,7 @@ $ qodev-apollo-cli usage
 
 | Group | Subcommand | Description |
 |---|---|---|
-| **contacts** | `search` | Search contacts (`--query`, `--stage-id`, `--linkedin-url`) |
+| **contacts** | `search` | Search contacts (`--query`, `--stage-id`, `--stage-name`, `--linkedin-url`) |
 | | `get` | Get contact details by ID |
 | | `create` | Create a new contact (`--first-name`, `--last-name`, `--email`, etc.) |
 | | `update` | Update contact (`--title`, `--label-ids`) |
@@ -96,8 +96,10 @@ $ qodev-apollo-cli usage
 | | `stages` | List all contact stages |
 | **accounts** | `search` | Search companies/accounts (`--query`, `--domain`) |
 | | `get` | Get account details by ID |
-| **deals** | `search` | Search opportunities/deals (`--query`, `--stage-id`) |
+| **deals** | `search` | Search opportunities/deals (`--query`, `--stage-id`, `--stage-name`) |
 | | `get` | Get deal details by ID |
+| | `role-types` | List opportunity contact role types |
+| | `set-role` | Set/update a contact's role on a deal (`--contact-id`, `--role-type`, `--primary`) |
 | **pipelines** | `list` | List all deal pipelines |
 | | `get` | Get pipeline details |
 | | `stages` | List stages in a pipeline |
@@ -105,12 +107,16 @@ $ qodev-apollo-cli usage
 | | `get` | Get stage details |
 | **enrich** | `org` | Enrich organization by domain (FREE - no credits) |
 | | `person` | Enrich person by email (1 credit per lookup) |
-| **people** | `search` | Search people database (`--person-titles`, `--q-organization-domains`) |
+| **people** | `search` | Search people database (`--titles`, `--seniorities`, `--locations`, `--organization-domains`) |
 | **notes** | `search` | Search notes (`--contact-id`, `--account-id`, `--opportunity-id`) |
 | | `create` | Create a note (`--contact-ids`, `--account-ids`, `--opportunity-ids`, `--content`) |
 | **tasks** | `search` | Search tasks (`--type`, `--status`) |
 | | `create` | Create a task (`--contact-ids`, `--note`, `--due-at`) |
 | **calls** | `search` | Search call activities |
+| **conversations** | `search` | Search recorded conversations (`--query`) |
+| | `get` | Get a conversation with transcript and AI summary |
+| | `transcript` | Print just the transcript of a conversation |
+| **custom-fields** | `list` | List custom field definitions (`--modality`) |
 | **emails** | `search` | Search email activities |
 | **news** | `search` | Search news (`--categories`) |
 | **jobs** | `search` | Search job postings (`--job-titles`, `--company-domains`) |

{qodev_apollo_cli-1.0.0 → qodev_apollo_cli-1.2.0}/README.md

@@ -57,7 +57,7 @@ $ qodev-apollo-cli usage
 
 | Group | Subcommand | Description |
 |---|---|---|
-| **contacts** | `search` | Search contacts (`--query`, `--stage-id`, `--linkedin-url`) |
+| **contacts** | `search` | Search contacts (`--query`, `--stage-id`, `--stage-name`, `--linkedin-url`) |
 | | `get` | Get contact details by ID |
 | | `create` | Create a new contact (`--first-name`, `--last-name`, `--email`, etc.) |
 | | `update` | Update contact (`--title`, `--label-ids`) |
@@ -65,8 +65,10 @@ $ qodev-apollo-cli usage
 | | `stages` | List all contact stages |
 | **accounts** | `search` | Search companies/accounts (`--query`, `--domain`) |
 | | `get` | Get account details by ID |
-| **deals** | `search` | Search opportunities/deals (`--query`, `--stage-id`) |
+| **deals** | `search` | Search opportunities/deals (`--query`, `--stage-id`, `--stage-name`) |
 | | `get` | Get deal details by ID |
+| | `role-types` | List opportunity contact role types |
+| | `set-role` | Set/update a contact's role on a deal (`--contact-id`, `--role-type`, `--primary`) |
 | **pipelines** | `list` | List all deal pipelines |
 | | `get` | Get pipeline details |
 | | `stages` | List stages in a pipeline |
@@ -74,12 +76,16 @@ $ qodev-apollo-cli usage
 | | `get` | Get stage details |
 | **enrich** | `org` | Enrich organization by domain (FREE - no credits) |
 | | `person` | Enrich person by email (1 credit per lookup) |
-| **people** | `search` | Search people database (`--person-titles`, `--q-organization-domains`) |
+| **people** | `search` | Search people database (`--titles`, `--seniorities`, `--locations`, `--organization-domains`) |
 | **notes** | `search` | Search notes (`--contact-id`, `--account-id`, `--opportunity-id`) |
 | | `create` | Create a note (`--contact-ids`, `--account-ids`, `--opportunity-ids`, `--content`) |
 | **tasks** | `search` | Search tasks (`--type`, `--status`) |
 | | `create` | Create a task (`--contact-ids`, `--note`, `--due-at`) |
 | **calls** | `search` | Search call activities |
+| **conversations** | `search` | Search recorded conversations (`--query`) |
+| | `get` | Get a conversation with transcript and AI summary |
+| | `transcript` | Print just the transcript of a conversation |
+| **custom-fields** | `list` | List custom field definitions (`--modality`) |
 | **emails** | `search` | Search email activities |
 | **news** | `search` | Search news (`--categories`) |
 | **jobs** | `search` | Search job postings (`--job-titles`, `--company-domains`) |

{qodev_apollo_cli-1.0.0 → qodev_apollo_cli-1.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "qodev-apollo-cli"
-version = "1.0.0"
+version = "1.2.0"
 description = "Agent-friendly CLI for the Apollo API"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -20,7 +20,7 @@ classifiers = [
 dependencies = [
     "cyclopts>=3.0",
     "rich>=13.0",
-    "qodev-apollo-api>=0.1.0",
+    "qodev-apollo-api>=0.3.0",
 ]
 
 [project.optional-dependencies]
@@ -48,7 +48,7 @@ build-backend = "hatchling.build"
 packages = ["src/apollo_cli"]
 
 [tool.uv.sources]
-qodev-apollo-api = { path = "../../libs/apollo" }
+qodev-apollo-api = { path = "../apollo-api" }
 
 [tool.ruff]
 target-version = "py311"

{qodev_apollo_cli-1.0.0 → qodev_apollo_cli-1.2.0}/src/apollo_cli/app.py

@@ -26,6 +26,8 @@ app.meta.group_parameters = Group("Global Options", sort_key=0)
 from apollo_cli.commands.accounts import accounts_app  # noqa: E402
 from apollo_cli.commands.calls import calls_app  # noqa: E402
 from apollo_cli.commands.contacts import contacts_app  # noqa: E402
+from apollo_cli.commands.conversations import conversations_app  # noqa: E402
+from apollo_cli.commands.custom_fields import custom_fields_app  # noqa: E402
 from apollo_cli.commands.deals import deals_app  # noqa: E402
 from apollo_cli.commands.emails import emails_app  # noqa: E402
 from apollo_cli.commands.enrich import enrich_app  # noqa: E402
@@ -50,6 +52,8 @@ _sub_apps = [
     notes_app,
     tasks_app,
     calls_app,
+    conversations_app,
+    custom_fields_app,
     emails_app,
     news_app,
     jobs_app,

{qodev_apollo_cli-1.0.0 → qodev_apollo_cli-1.2.0}/src/apollo_cli/commands/contacts.py

@@ -14,7 +14,7 @@ from apollo_cli.formatters.contacts import (
 )
 from apollo_cli.linkedin import apollo_canonical_linkedin_url
 from apollo_cli.output import error, output, output_list
-from apollo_cli.util import parse_comma_list
+from apollo_cli.util import parse_comma_list, resolve_stage_id
 
 contacts_app = App(name="contacts", help="Manage contacts.")
 
@@ -24,6 +24,12 @@ async def search(
     *,
     query: Annotated[str, Parameter(name=["--query", "-q"], help="Search keyword")] = "",
     stage_id: Annotated[str | None, Parameter(name="--stage-id", help="Filter by stage ID")] = None,
+    stage_name: Annotated[
+        str | None,
+        Parameter(
+            name="--stage-name", help="Filter by stage name (resolved to an ID; avoids a `contacts stages` lookup)"
+        ),
+    ] = None,
     linkedin_url: Annotated[str | None, Parameter(name="--linkedin-url", help="Filter by LinkedIn URL")] = None,
 ) -> None:
     """Search contacts by keyword or filter."""
@@ -38,6 +44,11 @@ async def search(
         filters["linkedin_url"] = apollo_canonical_linkedin_url(linkedin_url)
 
     async with ctx.client() as client:
+        if stage_name:
+            stages_ = await client.get_contact_stages()
+            filters.setdefault("contact_stage_ids", []).append(
+                resolve_stage_id(stage_name, stages_, kind="contact stage")
+            )
         result = await client.search_contacts(page=ctx.page, limit=ctx.limit, **filters)
 
     output_list(

qodev_apollo_cli-1.2.0/src/apollo_cli/commands/conversations.py

@@ -0,0 +1,67 @@
+"""Conversations command group."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from cyclopts import App, Parameter
+
+from apollo_cli.context import ctx
+from apollo_cli.formatters.conversations import (
+    format_conversation_detail,
+    format_conversation_list,
+    format_transcript,
+)
+from apollo_cli.output import output, output_json, output_list, output_markdown
+
+conversations_app = App(name="conversations", help="Recorded conversations (Zoom/Teams/Meet).")
+
+
+@conversations_app.command
+async def search(
+    *,
+    query: Annotated[str, Parameter(name=["--query", "-q"], help="Search keyword (topic/title)")] = "",
+) -> None:
+    """Search recorded conversations."""
+    filters: dict = {}
+    if query:
+        filters["q_keywords"] = query
+
+    async with ctx.client() as client:
+        result = await client.search_conversations(page=ctx.page, limit=ctx.limit, **filters)
+
+    output_list(
+        items=result.items,
+        total=result.total,
+        page=result.page,
+        limit=ctx.limit,
+        ctx=ctx,
+        format_fn=format_conversation_list,
+        resource_name="Conversations",
+    )
+
+
+@conversations_app.command
+async def get(
+    id: Annotated[str, Parameter(help="Conversation ID")],
+) -> None:
+    """Get conversation details by ID (includes transcript and AI summary)."""
+    async with ctx.client() as client:
+        conversation = await client.get_conversation(id)
+
+    output(conversation, ctx=ctx, format_fn=format_conversation_detail)
+
+
+@conversations_app.command
+async def transcript(
+    id: Annotated[str, Parameter(help="Conversation ID")],
+) -> None:
+    """Print just the transcript of a conversation (no metadata or summary)."""
+    async with ctx.client() as client:
+        conversation = await client.get_conversation(id)
+
+    segments = getattr(conversation, "transcript", None) or []
+    if ctx.json_mode:
+        output_json(segments)
+    else:
+        output_markdown(format_transcript(conversation))

qodev_apollo_cli-1.2.0/src/apollo_cli/commands/custom_fields.py

@@ -0,0 +1,48 @@
+"""Custom fields command group."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from cyclopts import App, Parameter
+
+from apollo_cli.context import ctx
+from apollo_cli.formatters.generic import list_table
+from apollo_cli.output import output_list
+
+custom_fields_app = App(name="custom-fields", help="Custom field definitions.")
+
+CUSTOM_FIELD_COLUMNS = [
+    ("ID", "id"),
+    ("Modality", "modality"),
+    ("Name", "name"),
+    ("Type", "type"),
+    ("CRM Field", "mapped_crm_field"),
+]
+
+
+@custom_fields_app.command(name="list")
+async def list_fields(
+    *,
+    modality: Annotated[
+        str | None,
+        Parameter(name="--modality", help="Filter by modality: contact, account, or opportunity"),
+    ] = None,
+) -> None:
+    """List custom field definitions across contacts, accounts, and opportunities."""
+    async with ctx.client() as client:
+        fields = await client.list_custom_fields()
+
+    if modality:
+        target = modality.strip().lower()
+        fields = [f for f in fields if (f.modality or "").lower() == target]
+
+    output_list(
+        items=fields,
+        total=len(fields),
+        page=1,
+        limit=len(fields) or 1,
+        ctx=ctx,
+        format_fn=lambda items, **kw: list_table(items, CUSTOM_FIELD_COLUMNS, title="Custom Fields", **kw),
+        resource_name="Custom Fields",
+    )

qodev_apollo_cli-1.2.0/src/apollo_cli/commands/deals.py

@@ -0,0 +1,161 @@
+"""Deals command group."""
+
+from __future__ import annotations
+
+from typing import Annotated, Any
+
+from cyclopts import App, Parameter
+
+from apollo_cli.context import ctx
+from apollo_cli.formatters.deals import format_deal_detail, format_deal_list
+from apollo_cli.formatters.generic import list_table
+from apollo_cli.output import error, output, output_list
+from apollo_cli.util import resolve_stage_id
+
+deals_app = App(name="deals", help="Manage deals/opportunities.")
+
+
+@deals_app.command
+async def search(
+    *,
+    query: Annotated[str, Parameter(name=["--query", "-q"], help="Search keyword")] = "",
+    stage_id: Annotated[str | None, Parameter(name="--stage-id", help="Filter by deal stage ID")] = None,
+    stage_name: Annotated[
+        str | None,
+        Parameter(
+            name="--stage-name", help="Filter by stage name (resolved to an ID; avoids a `pipelines stages` lookup)"
+        ),
+    ] = None,
+) -> None:
+    """Search deals by keyword or filter."""
+    filters: dict = {}
+    if query:
+        filters["q_keywords"] = query
+    stage_ids: list[str] = []
+    if stage_id:
+        stage_ids.append(stage_id)
+
+    async with ctx.client() as client:
+        if stage_name:
+            all_stages = await client.list_all_stages()
+            stage_ids.append(resolve_stage_id(stage_name, all_stages.items, kind="deal stage"))
+        if stage_ids:
+            filters["opportunity_stage_ids"] = stage_ids
+        result = await client.search_deals(page=ctx.page, limit=ctx.limit, **filters)
+
+    output_list(
+        items=result.items,
+        total=result.total,
+        page=result.page,
+        limit=ctx.limit,
+        ctx=ctx,
+        format_fn=format_deal_list,
+        resource_name="Deals",
+    )
+
+
+@deals_app.command
+async def get(
+    id: Annotated[str, Parameter(help="Deal ID")],
+) -> None:
+    """Get deal details by ID."""
+    async with ctx.client() as client:
+        deal = await client.get_deal(id)
+
+    output(deal, ctx=ctx, format_fn=format_deal_detail)
+
+
+ROLE_TYPE_COLUMNS = [("ID", "id"), ("Name", "name"), ("Display Order", "display_order")]
+
+
+@deals_app.command(name="role-types")
+async def role_types() -> None:
+    """List the available opportunity contact role types (e.g. Decision Maker, Champion)."""
+    async with ctx.client() as client:
+        result = await client.list_opportunity_contact_role_types()
+
+    output_list(
+        items=result.items,
+        total=result.total,
+        page=1,
+        limit=len(result.items) or 1,
+        ctx=ctx,
+        format_fn=lambda items, **kw: list_table(items, ROLE_TYPE_COLUMNS, title="Role Types", **kw),
+        resource_name="Role Types",
+    )
+
+
+def _existing_roles(deal: Any) -> list[dict]:
+    """Flatten a deal's current opportunity_contact_roles into update_roles entries."""
+    roles: list[dict] = []
+    for r in getattr(deal, "opportunity_contact_roles", []) or []:
+        role_type_id = None
+        if r.role:
+            role_type_id = r.role[0].opportunity_contact_role_type_id
+        roles.append(
+            {
+                "contact_id": r.contact_id,
+                "opportunity_contact_role_type_id": role_type_id,
+                "is_primary": bool(r.is_primary),
+            }
+        )
+    return roles
+
+
+@deals_app.command(name="set-role")
+async def set_role(
+    id: Annotated[str, Parameter(help="Deal ID")],
+    *,
+    contact_id: Annotated[str, Parameter(name="--contact-id", help="Contact ID to add/update on the deal")],
+    role_type: Annotated[
+        str | None,
+        Parameter(name="--role-type", help="Role type ID or name (e.g. 'Decision Maker'); resolved to an ID"),
+    ] = None,
+    primary: Annotated[
+        bool,
+        Parameter(name="--primary", help="Mark this contact as the primary contact (unsets any other primary)"),
+    ] = False,
+) -> None:
+    """Set or update a contact's role on a deal.
+
+    Reads the deal's current contact roles, applies the change, and writes the full
+    set back (Apollo's update_roles replaces all roles). Add ``--primary`` to make
+    this contact the single primary contact.
+    """
+    async with ctx.client() as client:
+        deal = await client.get_deal(id)
+        roles = _existing_roles(deal)
+
+        role_type_id: str | None = None
+        if role_type:
+            role_type_id = role_type
+            # Resolve a human name to an ID when it isn't already an ID.
+            rt_result = await client.list_opportunity_contact_role_types()
+            names = {rt.name.lower(): rt.id for rt in rt_result.items if rt.name}
+            ids = {rt.id for rt in rt_result.items}
+            if role_type not in ids:
+                resolved = names.get(role_type.lower())
+                if resolved is None:
+                    error(
+                        f"No role type {role_type!r}. Available: "
+                        + ", ".join(sorted(rt.name for rt in rt_result.items if rt.name)),
+                        ctx=ctx,
+                        code="unknown_role_type",
+                        exit_code=2,
+                    )
+                    return
+                role_type_id = resolved
+
+        entry = next((r for r in roles if r["contact_id"] == contact_id), None)
+        if entry is None:
+            entry = {"contact_id": contact_id, "opportunity_contact_role_type_id": None, "is_primary": False}
+            roles.append(entry)
+        if role_type_id is not None:
+            entry["opportunity_contact_role_type_id"] = role_type_id
+        if primary:
+            for r in roles:
+                r["is_primary"] = r["contact_id"] == contact_id
+
+        updated = await client.update_opportunity_roles(id, roles)
+
+    output(updated, ctx=ctx, format_fn=format_deal_detail)

qodev_apollo_cli-1.2.0/src/apollo_cli/commands/people.py

@@ -0,0 +1,68 @@
+"""People database search command group."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from cyclopts import App, Parameter
+
+from apollo_cli.context import ctx
+from apollo_cli.formatters.people import format_people_list
+from apollo_cli.output import output_list
+from apollo_cli.util import parse_comma_list
+
+people_app = App(name="people", help="People database search.")
+
+
+@people_app.command
+async def search(
+    *,
+    keywords: Annotated[str | None, Parameter(name="--keywords", help="Search keywords")] = None,
+    titles: Annotated[str | None, Parameter(name="--titles", help="Comma-separated job titles")] = None,
+    seniorities: Annotated[
+        str | None,
+        Parameter(name="--seniorities", help="Comma-separated seniorities (e.g. owner,vp,director,manager)"),
+    ] = None,
+    locations: Annotated[str | None, Parameter(name="--locations", help="Comma-separated person locations")] = None,
+    organization_domains: Annotated[
+        str | None,
+        Parameter(
+            name=["--organization-domains", "--domains"],
+            help="Comma-separated company domains — find people at these companies (e.g. acme.com,globex.com)",
+        ),
+    ] = None,
+) -> None:
+    """Search Apollo's global people database.
+
+    Respects the global ``--limit`` / ``--page`` options for pagination.
+    """
+    filters: dict = {"page": ctx.page, "per_page": ctx.limit}
+    if keywords:
+        filters["q_keywords"] = keywords
+    if titles:
+        filters["person_titles"] = parse_comma_list(titles)
+    if seniorities:
+        filters["person_seniorities"] = parse_comma_list(seniorities)
+    if locations:
+        filters["person_locations"] = parse_comma_list(locations)
+    if organization_domains:
+        filters["q_organization_domains_list"] = parse_comma_list(organization_domains)
+
+    async with ctx.client() as client:
+        result = await client.search_people(**filters)
+
+    # search_people returns the raw Apollo dict; people live under "people" (and
+    # sometimes "contacts" for matched CRM records).
+    items = result.get("people") or result.get("contacts") or []
+    pagination = result.get("pagination", {})
+    total = pagination.get("total_entries", len(items))
+
+    output_list(
+        items=items,
+        total=total,
+        page=ctx.page,
+        limit=ctx.limit,
+        ctx=ctx,
+        format_fn=format_people_list,
+        resource_name="People",
+    )

qodev_apollo_cli-1.2.0/src/apollo_cli/formatters/conversations.py

@@ -0,0 +1,117 @@
+"""Conversation-specific formatters."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from apollo_cli.formatters.generic import detail_table, list_table
+
+CONVERSATION_LIST_COLUMNS = [
+    ("ID", "id"),
+    ("Topic", "topic"),
+    ("Type", "conversation_type"),
+    ("Start", "start_time"),
+    ("Duration", "duration"),
+    ("Host", "host"),
+    ("State", "state"),
+]
+
+CONVERSATION_DETAIL_FIELDS = [
+    ("ID", "id"),
+    ("Topic", "topic"),
+    ("Type", "conversation_type"),
+    ("Start", "start_time"),
+    ("Duration (s)", "duration"),
+    ("Host", "host"),
+    ("Host ID", "host_id"),
+    ("State", "state"),
+    ("Internal", "is_internal"),
+    ("Private", "is_private"),
+    ("Comments", "comment_count"),
+    ("Participants", "participant_names"),
+    ("Accounts", "account_names"),
+    ("Recording", "video_recording.url"),
+    ("Pushed to CRM", "pushed_to_crm"),
+]
+
+
+def format_conversation_list(items: list[Any], *, total: int = 0, page: int = 1) -> str:
+    """Format a list of conversations as a markdown table."""
+    return list_table(items, CONVERSATION_LIST_COLUMNS, title="Conversations", total=total, page=page)
+
+
+def format_conversation_detail(data: Any) -> str:
+    """Format a single conversation (with transcript & summary) as a markdown detail view."""
+    topic = getattr(data, "topic", None) or "Conversation"
+    md = detail_table(data, CONVERSATION_DETAIL_FIELDS, title=f"Conversation: {topic}")
+
+    # Participants (richer than the participant_names list in the metadata table)
+    participants = getattr(data, "participants_info", None) or []
+    if participants:
+        md += "\n\n## Participants\n"
+        for p in participants:
+            name = getattr(p, "name", None) or "Unknown"
+            title = getattr(p, "title", None)
+            account = getattr(p, "account_name", None)
+            internal = getattr(p, "is_internal_participant", None)
+            suffix = ", ".join(x for x in [title, account] if x)
+            tag = " (internal)" if internal else ""
+            md += f"\n- **{name}**{tag}" + (f" — {suffix}" if suffix else "")
+
+    # Associated deals
+    deals = getattr(data, "deals", None) or []
+    if deals:
+        md += "\n\n## Deals\n"
+        for d in deals:
+            name = getattr(d, "name", None) or getattr(d, "id", "Unknown")
+            account = getattr(d, "account_name", None)
+            md += f"\n- {name}" + (f" ({account})" if account else "")
+
+    # AI-generated call summary (detail endpoint only)
+    summary = getattr(data, "call_summary", None)
+    if summary:
+        md += _format_summary(summary)
+
+    # Transcript (detail endpoint only)
+    if getattr(data, "transcript", None):
+        md += "\n\n" + format_transcript(data)
+
+    return md
+
+
+def format_transcript(data: Any) -> str:
+    """Render just the transcript of a conversation as `**Speaker:** sentence` lines."""
+    segments = getattr(data, "transcript", None) or []
+    if not segments:
+        return "## Transcript\n\n_No transcript available._"
+    lines = ["## Transcript", ""]
+    for seg in segments:
+        speaker = getattr(seg, "participant_name", None) or "Unknown"
+        sentence = getattr(seg, "spoken_sentence", None) or ""
+        lines.append(f"- **{speaker}:** {sentence}")
+    return "\n".join(lines)
+
+
+def _format_summary(summary: Any) -> str:
+    """Render the AI call summary (outcome, pain points, objections, next steps)."""
+    md = "\n\n## Call Summary\n"
+    outcome = getattr(summary, "outcome", None)
+    if outcome:
+        md += f"\n**Outcome:** {outcome}\n"
+    pricing = getattr(summary, "pricing_discussion", None)
+    if pricing:
+        md += f"\n**Pricing discussion:** {pricing}\n"
+
+    for label, attr, field in (
+        ("Pain Points", "pain_points", "text"),
+        ("Objections", "objections", "text"),
+        ("Next Steps", "next_steps", "step"),
+    ):
+        items = getattr(summary, attr, None) or []
+        if items:
+            md += f"\n### {label}\n"
+            for item in items:
+                text = getattr(item, field, None) or ""
+                who = getattr(item, "participant_name", None)
+                md += f"\n- {text}" + (f" — _{who}_" if who else "")
+    return md