qodev-apollo-cli 1.1.0__tar.gz → 1.2.1__tar.gz

{qodev_apollo_cli-1.1.0 → qodev_apollo_cli-1.2.1}/CHANGELOG.md

@@ -6,6 +6,37 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [1.2.1] - 2026-07-08
+
+Follow-ups from code review of the v1.2.0 changes.
+
+### Fixed
+
+- **`deals set-role` no longer sends an explicit `null` role type.** Adding a contact without `--role-type` omitted the `opportunity_contact_role_type_id` key entirely instead of posting `null`, which Apollo may reject.
+- **`people search` no longer drops results.** When Apollo returns both `people` and `contacts` (matched CRM records), both are now shown — previously only the first non-empty list was kept.
+- **Conversation detail view is robust to raw dicts.** The participants/deals/summary/transcript sections read fields via a dict-or-model helper, so they render whether `conversations get` returns models or plain dicts (previously the sections silently rendered empty for dicts).
+- **`--stage-name` errors are bounded.** An unknown stage name lists at most 15 available names (`… (+N more)`) instead of dumping the entire list.
+
+### Note
+
+- `conversations search --query` maps to Apollo's universal `q_keywords` param. The conversations search endpoint is undocumented and keyword filtering hasn't been confirmed server-side; if a search returns everything unfiltered, that param is the thing to revisit.
+
+## [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

{qodev_apollo_cli-1.1.0 → qodev_apollo_cli-1.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: qodev-apollo-cli
-Version: 1.1.0
+Version: 1.2.1
 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.1
 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,7 +107,7 @@ $ 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`) |
@@ -113,6 +115,8 @@ $ qodev-apollo-cli usage
 | **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.1.0 → qodev_apollo_cli-1.2.1}/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,7 +76,7 @@ $ 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`) |
@@ -82,6 +84,8 @@ $ qodev-apollo-cli usage
 | **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.1.0 → qodev_apollo_cli-1.2.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "qodev-apollo-cli"
-version = "1.1.0"
+version = "1.2.1"
 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.1",
 ]
 
 [project.optional-dependencies]

{qodev_apollo_cli-1.1.0 → qodev_apollo_cli-1.2.1}/src/apollo_cli/app.py

@@ -27,6 +27,7 @@ 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
@@ -52,6 +53,7 @@ _sub_apps = [
     tasks_app,
     calls_app,
     conversations_app,
+    custom_fields_app,
     emails_app,
     news_app,
     jobs_app,

{qodev_apollo_cli-1.1.0 → qodev_apollo_cli-1.2.1}/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.1.0 → qodev_apollo_cli-1.2.1}/src/apollo_cli/commands/conversations.py

@@ -7,8 +7,12 @@ 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
-from apollo_cli.output import output, output_list
+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).")
 
@@ -21,6 +25,10 @@ async def search(
     """Search recorded conversations."""
     filters: dict = {}
     if query:
+        # `q_keywords` is Apollo's universal keyword-search param (contacts/accounts/deals/
+        # people all use it). The conversations/search endpoint is undocumented and we
+        # haven't confirmed it honours the filter server-side — if a search returns
+        # everything unfiltered, this is the param to revisit.
         filters["q_keywords"] = query
 
     async with ctx.client() as client:
@@ -46,3 +54,18 @@ async def get(
         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.1/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.1/src/apollo_cli/commands/deals.py

@@ -0,0 +1,171 @@
+"""Deals command group."""
+
+from __future__ import annotations
+
+from typing import Annotated, Any, cast
+
+from cyclopts import App, Parameter
+from qodev_apollo_api import RoleAssignment
+
+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.
+
+    ``opportunity_contact_role_type_id`` is only included when the existing role
+    actually has one — we never send an explicit ``null`` (see ``_clean_roles``).
+    """
+    roles: list[dict] = []
+    for r in getattr(deal, "opportunity_contact_roles", []) or []:
+        entry: dict = {"contact_id": r.contact_id, "is_primary": bool(r.is_primary)}
+        if r.role and r.role[0].opportunity_contact_role_type_id:
+            entry["opportunity_contact_role_type_id"] = r.role[0].opportunity_contact_role_type_id
+        roles.append(entry)
+    return roles
+
+
+def _clean_roles(roles: list[dict]) -> list[dict]:
+    """Drop any ``opportunity_contact_role_type_id`` that is ``None`` so we never POST an
+    explicit null (Apollo may reject roles without a role type — omit the key instead)."""
+    for r in roles:
+        if r.get("opportunity_contact_role_type_id") is None:
+            r.pop("opportunity_contact_role_type_id", None)
+    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, "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
+
+        # Entries are built dynamically (conditional keys, pop), so they're plain dicts;
+        # cast to the client's RoleAssignment TypedDict at the boundary.
+        updated = await client.update_opportunity_roles(id, cast("list[RoleAssignment]", _clean_roles(roles)))
+
+    output(updated, ctx=ctx, format_fn=format_deal_detail)

qodev_apollo_cli-1.2.1/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. Results live under "people"; matched
+    # CRM records come back under "contacts". Merge both so we never silently drop half.
+    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.1.0 → qodev_apollo_cli-1.2.1}/src/apollo_cli/formatters/conversations.py

@@ -6,6 +6,13 @@ from typing import Any
 
 from apollo_cli.formatters.generic import detail_table, list_table
 
+
+def _get(item: Any, key: str) -> Any:
+    """Read ``key`` from a Pydantic model (attr) or a dict — so the rich detail view
+    renders whether ``get_conversation()`` returns models or raw dicts."""
+    return item.get(key) if isinstance(item, dict) else getattr(item, key, None)
+
+
 CONVERSATION_LIST_COLUMNS = [
     ("ID", "id"),
     ("Topic", "topic"),
@@ -42,55 +49,63 @@ def format_conversation_list(items: list[Any], *, total: int = 0, page: int = 1)
 
 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"
+    topic = _get(data, "topic") 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 []
+    participants = _get(data, "participants_info") 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)
+            name = _get(p, "name") or "Unknown"
+            title = _get(p, "title")
+            account = _get(p, "account_name")
+            internal = _get(p, "is_internal_participant")
             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 []
+    deals = _get(data, "deals") 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)
+            name = _get(d, "name") or _get(d, "id") or "Unknown"
+            account = _get(d, "account_name")
             md += f"\n- {name}" + (f" ({account})" if account else "")
 
     # AI-generated call summary (detail endpoint only)
-    summary = getattr(data, "call_summary", None)
+    summary = _get(data, "call_summary")
     if summary:
         md += _format_summary(summary)
 
     # Transcript (detail endpoint only)
-    transcript = getattr(data, "transcript", None) or []
-    if transcript:
-        md += "\n\n## Transcript\n"
-        for seg in transcript:
-            speaker = getattr(seg, "participant_name", None) or "Unknown"
-            sentence = getattr(seg, "spoken_sentence", None) or ""
-            md += f"\n- **{speaker}:** {sentence}"
+    if _get(data, "transcript"):
+        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 = _get(data, "transcript") or []
+    if not segments:
+        return "## Transcript\n\n_No transcript available._"
+    lines = ["## Transcript", ""]
+    for seg in segments:
+        speaker = _get(seg, "participant_name") or "Unknown"
+        sentence = _get(seg, "spoken_sentence") 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)
+    outcome = _get(summary, "outcome")
     if outcome:
         md += f"\n**Outcome:** {outcome}\n"
-    pricing = getattr(summary, "pricing_discussion", None)
+    pricing = _get(summary, "pricing_discussion")
     if pricing:
         md += f"\n**Pricing discussion:** {pricing}\n"
 
@@ -99,11 +114,11 @@ def _format_summary(summary: Any) -> str:
         ("Objections", "objections", "text"),
         ("Next Steps", "next_steps", "step"),
     ):
-        items = getattr(summary, attr, None) or []
+        items = _get(summary, attr) or []
         if items:
             md += f"\n### {label}\n"
             for item in items:
-                text = getattr(item, field, None) or ""
-                who = getattr(item, "participant_name", None)
+                text = _get(item, field) or ""
+                who = _get(item, "participant_name")
                 md += f"\n- {text}" + (f" — _{who}_" if who else "")
     return md

qodev_apollo_cli-1.2.1/src/apollo_cli/formatters/people.py

@@ -0,0 +1,21 @@
+"""People-search formatters."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from apollo_cli.formatters.generic import list_table
+
+# People objects nest their company under `organization`; `list_table` reads dot paths.
+PEOPLE_LIST_COLUMNS = [
+    ("Name", "name"),
+    ("Title", "title"),
+    ("Company", "organization.name"),
+    ("Email", "email"),
+    ("LinkedIn", "linkedin_url"),
+]
+
+
+def format_people_list(items: list[Any], *, total: int = 0, page: int = 1) -> str:
+    """Format people-database search results as a markdown table."""
+    return list_table(items, PEOPLE_LIST_COLUMNS, title="People", total=total, page=page)