wealthbox-cli 1.0.0__py3-none-any.whl

wealthbox_tools/cli/workflows.py

@@ -0,0 +1,172 @@
+from __future__ import annotations
+
+from typing import Any
+
+import typer
+
+from wealthbox_tools.models import (
+    WorkflowCreateInput,
+    WorkflowListQuery,
+    WorkflowResourceType,
+    WorkflowStatus,
+    WorkflowStepCompleteInput,
+    WorkflowTemplateListQuery,
+)
+
+from ._util import OutputFormat, build_linked_to, handle_errors, output_result, parse_more_fields, run_client
+
+app = typer.Typer(
+    context_settings={"help_option_names": ["-h", "--help"]},
+    help="Manage Wealthbox workflows.",
+    no_args_is_help=True,
+)
+
+templates_app = typer.Typer(
+    context_settings={"help_option_names": ["-h", "--help"]},
+    help="List workflow templates.",
+    no_args_is_help=True,
+)
+app.add_typer(templates_app, name="templates")
+
+_DEFAULT_FIELDS = ["id", "label", "status", "workflow_template", "linked_to", "created_at"]
+_TEMPLATE_DEFAULT_FIELDS = ["id", "name", "description", "status"]
+
+
+@app.command("list", help="List workflows with optional filters.")
+@handle_errors
+def list_workflows(
+    resource_id: int | None = typer.Option(
+        None, "--resource-id", help="Filter by linked resource ID (requires --resource-type)"
+    ),
+    resource_type: WorkflowResourceType | None = typer.Option(
+        None, "--resource-type", help="Filter by linked resource type: Contact, Project"
+    ),
+    status: WorkflowStatus | None = typer.Option(None, "--status", help="active, completed, or scheduled"),
+    updated_since: str | None = typer.Option(None, "--updated-since"),
+    updated_before: str | None = typer.Option(None, "--updated-before"),
+    page: int | None = typer.Option(None),
+    per_page: int | None = typer.Option(None, "--per-page", help="Results per page (max 100)"),
+    verbose: bool = typer.Option(False, "--verbose", "-v", help="Show all fields"),
+    token: str | None = typer.Option(None, envvar="WEALTHBOX_TOKEN", hidden=True),
+    fmt: OutputFormat = typer.Option(OutputFormat.JSON, "--format"),
+) -> None:
+    query = WorkflowListQuery(
+        resource_id=resource_id,
+        resource_type=resource_type,
+        status=status,
+        updated_since=updated_since,
+        updated_before=updated_before,
+        page=page,
+        per_page=per_page,
+    )
+    output_result(
+        run_client(token, lambda c: c.list_workflows(query)), fmt, fields=None if verbose else _DEFAULT_FIELDS
+    )
+
+
+@app.command("get", help="Get a single workflow by ID.")
+@handle_errors
+def get_workflow(
+    workflow_id: int = typer.Argument(..., help="Workflow ID"),
+    token: str | None = typer.Option(None, envvar="WEALTHBOX_TOKEN", hidden=True),
+    fmt: OutputFormat = typer.Option(OutputFormat.JSON, "--format"),
+) -> None:
+    output_result(run_client(token, lambda c: c.get_workflow(workflow_id)), fmt)
+
+
+@app.command("add", help="Create a new workflow from a template.")
+@handle_errors
+def add_workflow(
+    template: int = typer.Option(..., "--template", help="Workflow template ID — see: wbox workflows templates list"),
+    label: str | None = typer.Option(None, "--label", help="Optional label for this workflow instance"),
+    contact: int | None = typer.Option(None, "--contact", help="Link to a Contact by ID"),
+    project: int | None = typer.Option(None, "--project", help="Link to a Project by ID"),
+    opportunity: int | None = typer.Option(None, "--opportunity", help="Link to an Opportunity by ID"),
+    visible_to: str | None = typer.Option(None, "--visible-to"),
+    starts_at: str | None = typer.Option(None, "--starts-at", help="Start date (e.g. 2026-06-01)"),
+    more_fields: str | None = typer.Option(
+        None, "--more-fields", help="JSON object for additional fields (e.g. workflow_milestones)"
+    ),
+    token: str | None = typer.Option(None, envvar="WEALTHBOX_TOKEN", hidden=True),
+    fmt: OutputFormat = typer.Option(OutputFormat.JSON, "--format"),
+) -> None:
+    payload: dict[str, Any] = {
+        "workflow_template": template,
+        "label": label,
+        "visible_to": visible_to,
+        "starts_at": starts_at,
+        "linked_to": build_linked_to(contact, project, opportunity),
+    }
+
+    if more_fields:
+        _reserved = {"workflow_template", "label", "visible_to", "starts_at", "linked_to"}
+        payload.update(parse_more_fields(more_fields, _reserved))
+
+    input_model = WorkflowCreateInput(**{k: v for k, v in payload.items() if v is not None})
+    output_result(run_client(token, lambda c: c.create_workflow(input_model)), fmt)
+
+
+@app.command("complete-step", help="Mark a workflow step as complete.")
+@handle_errors
+def complete_workflow_step(
+    workflow_id: int = typer.Argument(..., help="Workflow ID"),
+    step_id: int = typer.Argument(..., help="Step ID"),
+    outcome_id: int | None = typer.Option(
+        None, "--outcome-id", help="Workflow outcome ID (if step has multiple outcomes)"
+    ),
+    due_date: str | None = typer.Option(
+        None, "--due-date", help="Due date when restarting a step (requires --due-date-set)"
+    ),
+    due_date_set: bool = typer.Option(False, "--due-date-set", help="Whether the restarted step has a due date"),
+    token: str | None = typer.Option(None, envvar="WEALTHBOX_TOKEN", hidden=True),
+    fmt: OutputFormat = typer.Option(OutputFormat.JSON, "--format"),
+) -> None:
+    data = WorkflowStepCompleteInput(
+        workflow_outcome_id=outcome_id,
+        due_date_set=due_date_set,
+        due_date=due_date,
+    )
+    output_result(run_client(token, lambda c: c.complete_workflow_step(workflow_id, step_id, data)), fmt)
+
+
+@app.command("revert-step", help="Revert a completed workflow step.")
+@handle_errors
+def revert_workflow_step(
+    workflow_id: int = typer.Argument(..., help="Workflow ID"),
+    step_id: int = typer.Argument(..., help="Step ID"),
+    token: str | None = typer.Option(None, envvar="WEALTHBOX_TOKEN", hidden=True),
+    fmt: OutputFormat = typer.Option(OutputFormat.JSON, "--format"),
+) -> None:
+    output_result(run_client(token, lambda c: c.revert_workflow_step(workflow_id, step_id)), fmt)
+
+
+@templates_app.command("list", help="List available workflow templates.")
+@handle_errors
+def list_workflow_templates(
+    resource_id: int | None = typer.Option(None, "--resource-id", help="Filter by linked resource ID"),
+    resource_type: WorkflowResourceType | None = typer.Option(
+        None, "--resource-type", help="Filter by linked resource type: Contact, Project"
+    ),
+    status: WorkflowStatus | None = typer.Option(None, "--status", help="active, completed, or scheduled"),
+    updated_since: str | None = typer.Option(None, "--updated-since"),
+    updated_before: str | None = typer.Option(None, "--updated-before"),
+    page: int | None = typer.Option(None),
+    per_page: int | None = typer.Option(None, "--per-page", help="Results per page (max 100)"),
+    verbose: bool = typer.Option(False, "--verbose", "-v", help="Show all fields"),
+    token: str | None = typer.Option(None, envvar="WEALTHBOX_TOKEN", hidden=True),
+    fmt: OutputFormat = typer.Option(OutputFormat.JSON, "--format"),
+) -> None:
+    query = WorkflowTemplateListQuery(
+        resource_id=resource_id,
+        resource_type=resource_type,
+        status=status,
+        updated_since=updated_since,
+        updated_before=updated_before,
+        page=page,
+        per_page=per_page,
+    )
+    output_result(
+        run_client(token, lambda c: c.list_workflow_templates(query)),
+        fmt,
+        fields=None if verbose else _TEMPLATE_DEFAULT_FIELDS,
+    )

wealthbox_tools/client/__init__.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+from .activity import ActivityMixin
+from .base import WealthboxAPIError, _WealthboxBase
+from .categories import CategoriesMixin
+from .comments import CommentsMixin
+from .contacts import ContactsMixin
+from .events import EventsMixin
+from .households import HouseholdsMixin
+from .me import MeMixin
+from .notes import NotesMixin
+from .opportunities import OpportunitiesMixin
+from .projects import ProjectsMixin
+from .tasks import TasksMixin
+from .users import UsersMixin
+from .workflows import WorkflowsMixin
+
+
+class WealthboxClient(
+    ActivityMixin,
+    CategoriesMixin,
+    CommentsMixin,
+    ContactsMixin,
+    EventsMixin,
+    HouseholdsMixin,
+    MeMixin,
+    NotesMixin,
+    OpportunitiesMixin,
+    ProjectsMixin,
+    TasksMixin,
+    UsersMixin,
+    WorkflowsMixin,
+    _WealthboxBase,
+):
+    """Async Wealthbox CRM API client.
+
+    Usage::
+
+        async with WealthboxClient() as client:
+            me = await client.get_me()
+            contacts = await client.list_contacts()
+    """
+
+
+__all__ = ["WealthboxClient", "WealthboxAPIError"]

wealthbox_tools/client/activity.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+from typing import Any
+
+from wealthbox_tools.models import ActivityListQuery
+
+
+class ActivityMixin:
+    """Activity Resource"""
+    async def list_activity(self, query: ActivityListQuery | None = None) -> dict[str, Any]:
+        params = query.model_dump(exclude_none=True) if query else None
+        resp = await self._request("GET", "/activity", params=params)  # type: ignore[attr-defined]
+        return resp.json()

wealthbox_tools/client/base.py

@@ -0,0 +1,216 @@
+from __future__ import annotations
+
+import asyncio
+import collections
+import json
+import logging
+import os
+import pathlib
+import time
+from collections.abc import Callable
+from typing import Any
+
+import httpx
+
+log = logging.getLogger(__name__)
+
+BASE_URL = "https://api.crmworkspace.com/v1"
+
+
+class WealthboxAPIError(Exception):
+    """Raised when the Wealthbox API returns an error response."""
+
+    def __init__(self, status_code: int, detail: str, response: httpx.Response | httpx.Request):
+        self.status_code = status_code
+        self.detail = detail
+        self.response = response
+        super().__init__(f"[{status_code}] {detail}")
+
+
+class RateLimiter:
+    """Async sliding-window rate limiter: 300 requests per 5-minute window."""
+
+    def __init__(
+        self,
+        rate: float = 1.0,       # kept for backward compat, unused
+        window: float = 300.0,   # 5-minute window
+        limit: int = 300,        # 300 req per window = 1/s average
+        state_file: pathlib.Path | None = None,
+    ):
+        self._window = window
+        self._limit = limit
+        self._timestamps: collections.deque[float] = collections.deque()
+        self._lock = asyncio.Lock()
+        self._state_file = state_file or pathlib.Path.home() / ".wbox_rate_limit.json"
+        self._load_state()
+
+    def _load_state(self) -> None:
+        try:
+            raw = json.loads(self._state_file.read_text())
+            wall_ts = raw.get("timestamps", [])
+        except (FileNotFoundError, json.JSONDecodeError, OSError):
+            return
+        now_mono, now_wall = time.monotonic(), time.time()
+        offset = now_mono - now_wall          # wall → monotonic
+        cutoff = now_wall - self._window
+        for ts in wall_ts:
+            if ts > cutoff:
+                self._timestamps.append(ts + offset)
+
+    def _prune_expired(self, now: float) -> None:
+        while self._timestamps and (now - self._timestamps[0]) >= self._window:
+            self._timestamps.popleft()
+
+    def _save_state(self) -> None:
+        try:
+            now_mono, now_wall = time.monotonic(), time.time()
+            offset = now_wall - now_mono      # monotonic → wall
+            cutoff = now_wall - self._window
+            wall_ts = [ts + offset for ts in self._timestamps if (ts + offset) > cutoff]
+            tmp = self._state_file.with_suffix(".tmp")
+            tmp.write_text(json.dumps({"timestamps": wall_ts}))
+            os.replace(tmp, self._state_file)  # atomic swap
+        except OSError:
+            pass   # never crash CLI over a cache file
+
+    async def acquire(self) -> None:
+        async with self._lock:
+            now = time.monotonic()
+            self._prune_expired(now)
+            if len(self._timestamps) >= self._limit:
+                sleep_for = self._window - (now - self._timestamps[0])
+                if sleep_for > 0:
+                    await asyncio.sleep(sleep_for)
+                self._prune_expired(time.monotonic())
+            self._timestamps.append(time.monotonic())
+
+
+class _WealthboxBase:
+    """Core HTTP client. Resource mixins are combined into WealthboxClient."""
+
+    def __init__(
+        self,
+        token: str | None = None,
+        base_url: str = BASE_URL,
+        rate_limit: bool = True,
+        max_429_retries: int = 5,
+    ):
+        self._token = token or os.environ.get("WEALTHBOX_TOKEN", "")
+        if not self._token:
+            raise ValueError(
+                "Wealthbox token required. Pass token= or set WEALTHBOX_TOKEN env var."
+            )
+        self._rate_limiter = RateLimiter() if rate_limit else None
+        self._max_429_retries = max_429_retries
+        self._http = httpx.AsyncClient(
+            base_url=base_url,
+            headers={"ACCESS_TOKEN": self._token},
+            timeout=30.0,
+        )
+
+    async def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict | None = None,
+        json: dict | None = None,
+    ) -> httpx.Response:
+        if self._rate_limiter:
+            await self._rate_limiter.acquire()
+
+        retries = 0
+        while True:
+            try:
+                response = await self._http.request(method, path, params=params, json=json)
+            except httpx.RequestError as exc:
+                raise WealthboxAPIError(0, f"Request failed: {exc}", exc.request) from exc  # type: ignore[arg-type]
+
+            if response.status_code != 429:
+                break
+
+            retries += 1
+            if retries > self._max_429_retries:
+                raise WealthboxAPIError(
+                    429,
+                    f"Rate limited after {self._max_429_retries} retries.",
+                    response,
+                )
+
+            raw_retry = response.headers.get("Retry-After", "5")
+            try:
+                retry_after = float(raw_retry)
+            except ValueError:
+                log.warning("Malformed Retry-After header %r, defaulting to 5s", raw_retry)
+                retry_after = 5.0
+
+            await asyncio.sleep(max(retry_after, 0.0))
+
+        if response.is_error:
+            try:
+                detail = response.json().get("error", response.text)
+            except Exception:
+                detail = response.text
+            raise WealthboxAPIError(response.status_code, detail, response)
+
+        return response
+
+    async def fetch_all_pages(
+        self,
+        path: str,
+        params: dict[str, Any],
+        collection_key: str,
+        on_progress: Callable[[int, int], None] | None = None,
+    ) -> dict[str, Any]:
+        """
+        Fetch every page from a paginated list endpoint.
+
+        Calls GET `path` with `params` (plus page/per_page overrides),
+        collecting items under `collection_key` until all pages are fetched.
+        Calls on_progress(page_num, total_fetched) after each page if provided.
+        Returns {"<collection_key>": [...all items...], "meta": {"total_count": N}}.
+        """
+        all_items: list[Any] = []
+        base_params = {**params, "per_page": 100}
+        page = 1
+
+        while True:
+            base_params["page"] = page
+            resp = await self._request("GET", path, params=base_params)
+            try:
+                data = resp.json()
+            except Exception:
+                raise WealthboxAPIError(
+                    resp.status_code,
+                    f"Invalid JSON in response from {path} (page {page})",
+                    resp,
+                )
+
+            items = data.get(collection_key, [])
+            all_items.extend(items)
+
+            if on_progress:
+                on_progress(page, len(all_items))
+
+            total_count = data.get("meta", {}).get("total_count")
+            if total_count is not None:
+                if page * 100 >= total_count:
+                    break
+            else:
+                if len(items) < 100:  # fallback if meta missing
+                    break
+
+            page += 1
+
+        return {collection_key: all_items, "meta": {"total_count": len(all_items)}}
+
+    async def aclose(self) -> None:
+        if self._rate_limiter:
+            self._rate_limiter._save_state()
+        await self._http.aclose()
+
+    async def __aenter__(self) -> "_WealthboxBase":  # type: ignore[return-value]
+        return self  # type: ignore[return-value]
+
+    async def __aexit__(self, *args: object) -> None:
+        await self.aclose()

wealthbox_tools/client/categories.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+from typing import Any
+
+from wealthbox_tools.models import CategoryListQuery, CategoryType
+
+
+class CategoriesMixin:
+    """Categories Resources"""
+
+    async def list_categories(self, category: CategoryType, query: CategoryListQuery | None = None) -> dict[str, Any]:
+        params = query.model_dump(exclude_none=True) if query else None
+        resp = await self._request("GET", f"/categories/{category}", params=params)  # type: ignore[attr-defined]
+        return resp.json()

wealthbox_tools/client/comments.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+from typing import Any
+
+from wealthbox_tools.models import CommentListQuery
+
+
+class CommentsMixin:
+    """Comments Resource"""
+
+    async def list_comments(self, query: CommentListQuery | None = None) -> dict[str, Any]:
+        params = query.model_dump(exclude_none=True) if query else None
+        resp = await self._request("GET", "/comments", params=params)  # type: ignore[attr-defined]
+        return resp.json()

wealthbox_tools/client/contacts.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from wealthbox_tools.models import ContactCreateInput, ContactListQuery, ContactUpdateInput
+
+
+class ContactsMixin:
+    """Contact resource methods. Mixed into WealthboxClient."""
+
+    async def list_contacts(self, query: ContactListQuery | None = None) -> dict[str, Any]:
+        params = query.model_dump(exclude_none=True) if query else None
+        resp = await self._request("GET", "/contacts", params=params)  # type: ignore[attr-defined]
+        return resp.json()
+
+    async def get_contact(self, contact_id: int) -> dict[str, Any]:
+        resp = await self._request("GET", f"/contacts/{contact_id}")  # type: ignore[attr-defined]
+        return resp.json()
+
+    async def create_contact(self, data: ContactCreateInput) -> dict[str, Any]:
+        payload = data.model_dump(exclude_none=True)
+        resp = await self._request("POST", "/contacts", json=payload)  # type: ignore[attr-defined]
+        return resp.json()
+
+    async def update_contact(self, contact_id: int, data: ContactUpdateInput) -> dict[str, Any]:
+        payload = data.model_dump(exclude_unset=True)
+        resp = await self._request("PUT", f"/contacts/{contact_id}", json=payload)  # type: ignore[attr-defined]
+        return resp.json()
+
+    async def delete_contact(self, contact_id: int) -> None:
+        await self._request("DELETE", f"/contacts/{contact_id}")  # type: ignore[attr-defined]
+
+    async def list_all_contacts(
+        self,
+        query: ContactListQuery | None = None,
+        on_progress: Callable[[int, int], None] | None = None,
+    ) -> dict[str, Any]:
+        """Fetch all pages of contacts. Use when client-side filtering requires the full dataset."""
+        params = query.model_dump(exclude_none=True) if query else {}
+        # Remove pagination fields — fetch_all_pages controls these
+        params.pop("page", None)
+        params.pop("per_page", None)
+        return await self.fetch_all_pages("/contacts", params, "contacts", on_progress=on_progress)  # type: ignore[attr-defined]

wealthbox_tools/client/events.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from typing import Any
+
+from wealthbox_tools.models import EventCreateInput, EventListQuery, EventUpdateInput
+
+
+class EventsMixin:
+    """Event resource methods. Mixed into WealthboxClient."""
+
+    async def list_events(self, query: EventListQuery | None = None) -> dict[str, Any]:
+        params = query.model_dump(exclude_none=True) if query else None
+        resp = await self._request("GET", "/events", params=params)  # type: ignore[attr-defined]
+        return resp.json()
+
+    async def get_event(self, event_id: int) -> dict[str, Any]:
+        resp = await self._request("GET", f"/events/{event_id}")  # type: ignore[attr-defined]
+        return resp.json()
+
+    async def create_event(self, data: EventCreateInput) -> dict[str, Any]:
+        payload = data.model_dump(exclude_none=True)
+        resp = await self._request("POST", "/events", json=payload)  # type: ignore[attr-defined]
+        return resp.json()
+
+    async def update_event(self, event_id: int, data: EventUpdateInput) -> dict[str, Any]:
+        payload = data.model_dump(exclude_unset=True)
+        resp = await self._request("PUT", f"/events/{event_id}", json=payload)  # type: ignore[attr-defined]
+        return resp.json()
+
+    async def delete_event(self, event_id: int) -> None:
+        await self._request("DELETE", f"/events/{event_id}")  # type: ignore[attr-defined]

wealthbox_tools/client/households.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from typing import Any
+
+from wealthbox_tools.models import HouseholdMemberInput
+
+
+class HouseholdsMixin:
+    """Household membership methods."""
+
+    async def add_household_member(
+        self, household_id: int, data: HouseholdMemberInput
+    ) -> dict[str, Any]:
+        payload = data.model_dump(exclude_none=True)
+        resp = await self._request(  # type: ignore[attr-defined]
+            "POST", f"/households/{household_id}/members", json=payload
+        )
+        return resp.json()
+
+    async def remove_household_member(
+        self, household_id: int, member_id: int
+    ) -> dict[str, Any]:
+        resp = await self._request(  # type: ignore[attr-defined]
+            "DELETE", f"/households/{household_id}/members/{member_id}"
+        )
+        # Wealthbox typically returns the household body, but may return empty body.
+        try:
+            return resp.json()
+        except ValueError:
+            return {"ok": True, "household_id": household_id, "member_id": member_id}

wealthbox_tools/client/me.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+class MeMixin:
+    """Me Resource"""
+
+    async def get_me(self) -> dict[str, Any]:
+        resp = await self._request("GET", "/me")  # type: ignore[attr-defined]
+        return resp.json()

wealthbox_tools/client/notes.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+from typing import Any
+
+from wealthbox_tools.models import NoteCreateInput, NoteListQuery, NoteUpdateInput
+
+
+class NotesMixin:
+    """Note resource methods. Mixed into WealthboxClient. (No delete — API does not support it.)"""
+
+    async def list_notes(self, query: NoteListQuery | None = None) -> dict[str, Any]:
+        params = query.model_dump(exclude_none=True) if query else None
+        resp = await self._request("GET", "/notes", params=params)  # type: ignore[attr-defined]
+        return resp.json()
+
+    async def get_note(self, note_id: int) -> dict[str, Any]:
+        resp = await self._request("GET", f"/notes/{note_id}")  # type: ignore[attr-defined]
+        return resp.json()
+
+    async def create_note(self, data: NoteCreateInput) -> dict[str, Any]:
+        payload = data.model_dump(exclude_none=True)
+        resp = await self._request("POST", "/notes", json=payload)  # type: ignore[attr-defined]
+        return resp.json()
+
+    async def update_note(self, note_id: int, data: NoteUpdateInput) -> dict[str, Any]:
+        payload = data.model_dump(exclude_unset=True)
+        resp = await self._request("PUT", f"/notes/{note_id}", json=payload)  # type: ignore[attr-defined]
+        return resp.json()

wealthbox_tools/client/opportunities.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from typing import Any
+
+from wealthbox_tools.models import OpportunityCreateInput, OpportunityListQuery, OpportunityUpdateInput
+
+
+class OpportunitiesMixin:
+    """Opportunities Resource"""
+
+    async def list_opportunities(self, query: OpportunityListQuery | None = None) -> dict[str, Any]:
+        params = query.model_dump(exclude_none=True) if query else None
+        resp = await self._request("GET", "/opportunities", params=params)  # type: ignore[attr-defined]
+        return resp.json()
+
+    async def get_opportunity(self, opportunity_id: int) -> dict[str, Any]:
+        resp = await self._request("GET", f"/opportunities/{opportunity_id}")  # type: ignore[attr-defined]
+        return resp.json()
+
+    async def create_opportunity(self, data: OpportunityCreateInput) -> dict[str, Any]:
+        payload = data.model_dump(exclude_none=True)
+        resp = await self._request("POST", "/opportunities", json=payload)  # type: ignore[attr-defined]
+        return resp.json()
+
+    async def update_opportunity(self, opportunity_id: int, data: OpportunityUpdateInput) -> dict[str, Any]:
+        payload = data.model_dump(exclude_unset=True)
+        resp = await self._request("PUT", f"/opportunities/{opportunity_id}", json=payload)  # type: ignore[attr-defined]
+        return resp.json()
+
+    async def delete_opportunity(self, opportunity_id: int) -> None:
+        await self._request("DELETE", f"/opportunities/{opportunity_id}")  # type: ignore[attr-defined]