devrel-origin 0.2.14__py3-none-any.whl

devrel_origin/tools/api_client.py

@@ -0,0 +1,393 @@
+"""
+PostHog API v2 async client (legacy — retained for interface compatibility).
+
+Originally a typed, retryable wrapper around PostHog's REST API.
+OpenClaw does not have an equivalent external API, so this module is kept
+as a structural dependency for agent imports but is not used for live API calls.
+The PostHogClient class and its DTOs remain functional for testing and
+reference purposes.
+"""
+
+import logging
+from dataclasses import dataclass, field
+from typing import Any, Optional
+
+import httpx
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# Configuration
+# ---------------------------------------------------------------------------
+
+DEFAULT_HOST = "https://app.posthog.com"
+API_TIMEOUT = 30.0
+MAX_RETRIES = 2
+
+
+# ---------------------------------------------------------------------------
+# Data transfer objects
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class InsightQuery:
+    """Parameters for a PostHog insight query."""
+
+    insight: str = "TRENDS"  # TRENDS, FUNNELS, RETENTION, PATHS, LIFECYCLE
+    events: list[dict[str, Any]] = field(default_factory=list)
+    properties: list[dict[str, Any]] = field(default_factory=list)
+    date_from: str = "-7d"
+    date_to: Optional[str] = None
+    interval: str = "day"
+    breakdown: Optional[str] = None
+    breakdown_type: Optional[str] = None
+    filter_test_accounts: bool = True
+
+    def to_dict(self) -> dict[str, Any]:
+        d: dict[str, Any] = {
+            "insight": self.insight,
+            "events": self.events,
+            "properties": self.properties,
+            "date_from": self.date_from,
+            "interval": self.interval,
+            "filter_test_accounts": self.filter_test_accounts,
+        }
+        if self.date_to:
+            d["date_to"] = self.date_to
+        if self.breakdown:
+            d["breakdown"] = self.breakdown
+            d["breakdown_type"] = self.breakdown_type or "event"
+        return d
+
+
+@dataclass
+class FeatureFlag:
+    """PostHog feature flag representation."""
+
+    key: str
+    name: str = ""
+    active: bool = True
+    rollout_percentage: Optional[int] = None
+    filters: dict[str, Any] = field(default_factory=dict)
+    ensure_experience_continuity: bool = False
+
+
+@dataclass
+class Experiment:
+    """PostHog experiment representation."""
+
+    name: str
+    feature_flag_key: str
+    description: str = ""
+    start_date: Optional[str] = None
+    end_date: Optional[str] = None
+    parameters: dict[str, Any] = field(default_factory=dict)
+
+
+# ---------------------------------------------------------------------------
+# Client
+# ---------------------------------------------------------------------------
+
+
+class PostHogClient:
+    """
+    Typed async client for the PostHog REST API v2.
+
+    Usage::
+
+        client = PostHogClient(api_key="phx_...", project_id="12345")
+        trends = await client.query_insights(
+            InsightQuery(events=[{"id": "$pageview"}])
+        )
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        project_id: str = "",
+        host: str = DEFAULT_HOST,
+    ):
+        self.api_key = api_key
+        self.project_id = project_id
+        self.host = host.rstrip("/")
+        self._client = httpx.AsyncClient(
+            base_url=self.host,
+            headers={
+                "Authorization": f"Bearer {api_key}",
+                "Content-Type": "application/json",
+            },
+            timeout=API_TIMEOUT,
+        )
+
+    async def close(self) -> None:
+        await self._client.aclose()
+
+    # -- helpers ----------------------------------------------------------
+
+    def _url(self, path: str) -> str:
+        """Build a project-scoped API URL."""
+        if self.project_id:
+            return f"/api/projects/{self.project_id}{path}"
+        return f"/api{path}"
+
+    async def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Optional[dict[str, Any]] = None,
+        params: Optional[dict[str, Any]] = None,
+    ) -> dict[str, Any]:
+        """Execute an HTTP request with retry logic."""
+        url = self._url(path)
+        last_error: Optional[Exception] = None
+
+        for attempt in range(1, MAX_RETRIES + 2):
+            try:
+                resp = await self._client.request(method, url, json=json, params=params)
+                resp.raise_for_status()
+                return resp.json()
+            except (httpx.HTTPStatusError, httpx.RequestError) as exc:
+                last_error = exc
+                logger.warning(f"PostHog API {method} {url} failed (attempt {attempt}): {exc}")
+                if attempt <= MAX_RETRIES:
+                    import asyncio
+
+                    await asyncio.sleep(1.0 * attempt)
+
+        raise last_error  # type: ignore[misc]
+
+    # -- Event Capture ----------------------------------------------------
+
+    async def capture(
+        self,
+        distinct_id: str,
+        event: str,
+        properties: Optional[dict[str, Any]] = None,
+    ) -> dict[str, Any]:
+        """Capture a single event."""
+        return await self._request(
+            "POST",
+            "/capture/",
+            json={
+                "api_key": self.api_key,
+                "distinct_id": distinct_id,
+                "event": event,
+                "properties": properties or {},
+            },
+        )
+
+    async def capture_batch(self, events: list[dict[str, Any]]) -> dict[str, Any]:
+        """Capture a batch of events."""
+        return await self._request(
+            "POST",
+            "/capture/",
+            json={"api_key": self.api_key, "batch": events},
+        )
+
+    # -- Insights / Queries -----------------------------------------------
+
+    async def query_insights(self, query: InsightQuery) -> dict[str, Any]:
+        """Run an insight query (trends, funnels, retention, etc.)."""
+        return await self._request("POST", "/insights/", json=query.to_dict())
+
+    async def get_insight(self, insight_id: int) -> dict[str, Any]:
+        """Fetch a saved insight by ID."""
+        return await self._request("GET", f"/insights/{insight_id}/")
+
+    async def list_insights(self, limit: int = 100, offset: int = 0) -> dict[str, Any]:
+        """List saved insights with pagination."""
+        return await self._request(
+            "GET",
+            "/insights/",
+            params={"limit": limit, "offset": offset},
+        )
+
+    # -- Feature Flags ----------------------------------------------------
+
+    async def create_feature_flag(self, flag: FeatureFlag) -> dict[str, Any]:
+        """Create a new feature flag."""
+        payload: dict[str, Any] = {
+            "key": flag.key,
+            "name": flag.name,
+            "active": flag.active,
+            "filters": flag.filters,
+            "ensure_experience_continuity": flag.ensure_experience_continuity,
+        }
+        if flag.rollout_percentage is not None:
+            payload["rollout_percentage"] = flag.rollout_percentage
+        return await self._request("POST", "/feature_flags/", json=payload)
+
+    async def get_feature_flag(self, flag_id: int) -> dict[str, Any]:
+        """Fetch a feature flag by ID."""
+        return await self._request("GET", f"/feature_flags/{flag_id}/")
+
+    async def list_feature_flags(self, limit: int = 100) -> dict[str, Any]:
+        """List all feature flags."""
+        return await self._request("GET", "/feature_flags/", params={"limit": limit})
+
+    async def update_feature_flag(self, flag_id: int, updates: dict[str, Any]) -> dict[str, Any]:
+        """Patch a feature flag."""
+        return await self._request("PATCH", f"/feature_flags/{flag_id}/", json=updates)
+
+    async def delete_feature_flag(self, flag_id: int) -> dict[str, Any]:
+        """Delete a feature flag."""
+        return await self._request("DELETE", f"/feature_flags/{flag_id}/")
+
+    # -- Experiments ------------------------------------------------------
+
+    async def create_experiment(self, experiment: Experiment) -> dict[str, Any]:
+        """Create a new experiment."""
+        return await self._request(
+            "POST",
+            "/experiments/",
+            json={
+                "name": experiment.name,
+                "feature_flag_key": experiment.feature_flag_key,
+                "description": experiment.description,
+                "start_date": experiment.start_date,
+                "end_date": experiment.end_date,
+                "parameters": experiment.parameters,
+            },
+        )
+
+    async def get_experiment(self, experiment_id: int) -> dict[str, Any]:
+        """Fetch an experiment by ID."""
+        return await self._request("GET", f"/experiments/{experiment_id}/")
+
+    async def list_experiments(self, limit: int = 100) -> dict[str, Any]:
+        """List all experiments."""
+        return await self._request("GET", "/experiments/", params={"limit": limit})
+
+    async def get_experiment_results(self, experiment_id: int) -> dict[str, Any]:
+        """Fetch experiment results with statistical analysis."""
+        return await self._request("GET", f"/experiments/{experiment_id}/results/")
+
+    # -- Cohorts ----------------------------------------------------------
+
+    async def create_cohort(
+        self,
+        name: str,
+        groups: list[dict[str, Any]],
+        is_static: bool = False,
+    ) -> dict[str, Any]:
+        """Create a new cohort."""
+        return await self._request(
+            "POST",
+            "/cohorts/",
+            json={
+                "name": name,
+                "groups": groups,
+                "is_static": is_static,
+            },
+        )
+
+    async def get_cohort(self, cohort_id: int) -> dict[str, Any]:
+        """Fetch a cohort by ID."""
+        return await self._request("GET", f"/cohorts/{cohort_id}/")
+
+    async def list_cohorts(self, limit: int = 100) -> dict[str, Any]:
+        """List all cohorts."""
+        return await self._request("GET", "/cohorts/", params={"limit": limit})
+
+    # -- Annotations ------------------------------------------------------
+
+    async def create_annotation(
+        self,
+        content: str,
+        date_marker: str,
+        scope: str = "organization",
+    ) -> dict[str, Any]:
+        """Create a date annotation (e.g., deploy marker)."""
+        return await self._request(
+            "POST",
+            "/annotations/",
+            json={
+                "content": content,
+                "date_marker": date_marker,
+                "scope": scope,
+            },
+        )
+
+    async def list_annotations(self, limit: int = 100) -> dict[str, Any]:
+        """List all annotations."""
+        return await self._request("GET", "/annotations/", params={"limit": limit})
+
+    # -- Persons ----------------------------------------------------------
+
+    async def get_person(self, distinct_id: str) -> dict[str, Any]:
+        """Look up a person by distinct_id."""
+        result = await self._request(
+            "GET",
+            "/persons/",
+            params={"distinct_id": distinct_id},
+        )
+        persons = result.get("results", [])
+        if not persons:
+            raise ValueError(f"No person found for distinct_id={distinct_id}")
+        return persons[0]
+
+    async def list_persons(self, limit: int = 100, offset: int = 0) -> dict[str, Any]:
+        """List persons with pagination."""
+        return await self._request(
+            "GET",
+            "/persons/",
+            params={"limit": limit, "offset": offset},
+        )
+
+    # -- Actions ----------------------------------------------------------
+
+    async def list_actions(self, limit: int = 100) -> dict[str, Any]:
+        """List defined actions."""
+        return await self._request("GET", "/actions/", params={"limit": limit})
+
+    # -- HogQL / Query API -----------------------------------------------
+
+    async def event_volumes(self, days: int = 7, limit: int = 50) -> list[tuple[str, int]]:
+        """Return [(event_name, count), ...] for the top events in the period.
+
+        Used by Cyra to auto-detect a funnel candidate (highest-volume
+        $pageview to custom_event chain).
+        """
+        query = {
+            "kind": "EventsQuery",
+            "select": ["event", "count()"],
+            "after": f"-{days}d",
+            "orderBy": ["-count()"],
+            "limit": limit,
+        }
+        data = await self._request("POST", "/query/", json={"query": query})
+        results = data.get("results", [])
+        return [(row[0], int(row[1])) for row in results]
+
+    async def funnel_query(
+        self,
+        events: list[str],
+        days: int = 7,
+    ) -> list[dict]:
+        """Run a funnel query for the given event sequence.
+
+        Returns one dict per step with keys: name, count, average_conversion_time.
+        """
+        query = {
+            "kind": "FunnelsQuery",
+            "series": [{"event": e, "kind": "EventsNode"} for e in events],
+            "dateRange": {"date_from": f"-{days}d"},
+        }
+        data = await self._request("POST", "/query/", json={"query": query})
+        return data.get("results", [])
+
+    # -- Session Recordings -----------------------------------------------
+
+    async def list_session_recordings(
+        self,
+        limit: int = 50,
+        offset: int = 0,
+        date_from: Optional[str] = None,
+    ) -> dict[str, Any]:
+        """List session recordings."""
+        params: dict[str, Any] = {"limit": limit, "offset": offset}
+        if date_from:
+            params["date_from"] = date_from
+        return await self._request("GET", "/session_recordings/", params=params)

devrel_origin/tools/apollo_client.py

@@ -0,0 +1,305 @@
+# tools/apollo_client.py
+"""
+Apollo.io API async client.
+
+Provides typed async access to Apollo's REST API for:
+- People search (find contacts by title, company, industry)
+- Organization search (find companies by criteria)
+- Person enrichment (enrich by email or LinkedIn URL)
+- Organization enrichment (enrich by domain)
+
+Authentication: x-api-key header.
+Rate limits: ~50 RPM standard plan; handled via tenacity retry on 429.
+"""
+
+import logging
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any
+
+import httpx
+from tenacity import (
+    retry,
+    retry_if_exception_type,
+    stop_after_attempt,
+    wait_exponential,
+)
+
+if TYPE_CHECKING:
+    from devrel_origin.tools.instantly_client import InstantlyLead
+
+logger = logging.getLogger(__name__)
+
+
+# ---------------------------------------------------------------------------
+# Errors
+# ---------------------------------------------------------------------------
+
+
+class ApolloAPIError(Exception):
+    """Non-retryable error from the Apollo API (4xx except 429)."""
+
+    def __init__(self, status_code: int, detail: str):
+        self.status_code = status_code
+        self.detail = detail
+        super().__init__(f"Apollo API error {status_code}: {detail}")
+
+
+# ---------------------------------------------------------------------------
+# Data Transfer Objects
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class ApolloContact:
+    """A contact/person from Apollo."""
+
+    id: str
+    first_name: str
+    last_name: str
+    email: str | None = None
+    title: str | None = None
+    company_name: str | None = None
+    company_domain: str | None = None
+    linkedin_url: str | None = None
+    phone: str | None = None
+
+    def to_instantly_lead(self) -> "InstantlyLead":
+        """Convert to InstantlyLead for Instantly upload.
+
+        Field mapping:
+        - email -> email (empty string if None)
+        - first_name -> first_name
+        - last_name -> last_name
+        - company_name -> company_name
+        - phone, linkedin_url, title -> custom_variables (only if set)
+        """
+        from devrel_origin.tools.instantly_client import InstantlyLead
+
+        return InstantlyLead(
+            email=self.email or "",
+            first_name=self.first_name,
+            last_name=self.last_name,
+            company_name=self.company_name or "",
+            custom_variables={
+                k: v
+                for k, v in {
+                    "phone": self.phone,
+                    "linkedin_url": self.linkedin_url,
+                    "title": self.title,
+                }.items()
+                if v
+            },
+        )
+
+
+@dataclass
+class ApolloOrganization:
+    """An organization from Apollo."""
+
+    id: str
+    name: str
+    domain: str | None = None
+    industry: str | None = None
+    estimated_headcount: int | None = None
+    tech_stack: list[str] = field(default_factory=list)
+    funding_stage: str | None = None
+    funding_total: float | None = None
+    description: str | None = None
+    linkedin_url: str | None = None
+
+
+@dataclass
+class PeopleSearchResult:
+    """Result from people search endpoint."""
+
+    contacts: list[ApolloContact]
+    total: int
+    page: int
+    per_page: int
+
+
+@dataclass
+class OrgSearchResult:
+    """Result from organization search endpoint."""
+
+    organizations: list[ApolloOrganization]
+    total: int
+    page: int
+    per_page: int
+
+
+# ---------------------------------------------------------------------------
+# Client
+# ---------------------------------------------------------------------------
+
+
+class ApolloClient:
+    """Async client for the Apollo.io REST API."""
+
+    BASE_URL = "https://api.apollo.io/v1"
+
+    def __init__(self, api_key: str):
+        self._api_key = api_key
+        self._client = httpx.AsyncClient(
+            base_url=self.BASE_URL,
+            headers={"x-api-key": api_key, "Content-Type": "application/json"},
+            timeout=30.0,
+        )
+
+    async def close(self) -> None:
+        await self._client.aclose()
+
+    async def __aenter__(self) -> "ApolloClient":
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        await self.close()
+
+    def _raise_for_status(self, response: httpx.Response) -> None:
+        if response.status_code == 429:
+            raise httpx.HTTPStatusError("Rate limited", request=response.request, response=response)
+        if response.status_code >= 400:
+            try:
+                detail = response.json().get("message", response.text)
+            except Exception:
+                detail = response.text
+            raise ApolloAPIError(status_code=response.status_code, detail=detail)
+
+    @retry(
+        stop=stop_after_attempt(3),
+        wait=wait_exponential(multiplier=2, min=4, max=60),
+        retry=retry_if_exception_type(httpx.HTTPStatusError),
+    )
+    async def _post(self, path: str, payload: dict[str, Any]) -> dict[str, Any]:
+        response = await self._client.post(path, json=payload)
+        self._raise_for_status(response)
+        return response.json()
+
+    @staticmethod
+    def _parse_contact(data: dict[str, Any]) -> ApolloContact:
+        return ApolloContact(
+            id=data.get("id", ""),
+            first_name=data.get("first_name", ""),
+            last_name=data.get("last_name", ""),
+            email=data.get("email"),
+            title=data.get("title"),
+            company_name=data.get("organization_name") or data.get("company_name"),
+            company_domain=data.get("organization", {}).get("primary_domain")
+            if isinstance(data.get("organization"), dict)
+            else data.get("company_domain"),
+            linkedin_url=data.get("linkedin_url"),
+            phone=data.get("sanitized_phone") or data.get("phone"),
+        )
+
+    @staticmethod
+    def _parse_organization(data: dict[str, Any]) -> ApolloOrganization:
+        tech = data.get("technologies") or data.get("tech_stack") or []
+        if isinstance(tech, list):
+            tech_names = [t if isinstance(t, str) else t.get("name", "") for t in tech]
+        else:
+            tech_names = []
+
+        return ApolloOrganization(
+            id=data.get("id", ""),
+            name=data.get("name", ""),
+            domain=data.get("primary_domain") or data.get("domain"),
+            industry=data.get("industry"),
+            estimated_headcount=data.get("estimated_num_employees"),
+            tech_stack=tech_names,
+            funding_stage=data.get("latest_funding_stage") or data.get("funding_stage"),
+            funding_total=data.get("total_funding"),
+            description=data.get("short_description") or data.get("description"),
+            linkedin_url=data.get("linkedin_url"),
+        )
+
+    async def search_people(
+        self,
+        *,
+        titles: list[str] | None = None,
+        domains: list[str] | None = None,
+        industries: list[str] | None = None,
+        page: int = 1,
+        per_page: int = 25,
+        **extra: Any,
+    ) -> PeopleSearchResult:
+        """Search for people by title, domain, or industry."""
+        payload: dict[str, Any] = {"page": page, "per_page": min(per_page, 100)}
+        if titles:
+            payload["person_titles"] = titles
+        if domains:
+            payload["q_organization_domains"] = domains
+        if industries:
+            payload["organization_industry_tag_ids"] = industries
+        payload.update(extra)
+
+        data = await self._post("/mixed_people/api_search", payload)
+        contacts = [self._parse_contact(c) for c in data.get("people", [])]
+        pagination = data.get("pagination", {})
+        return PeopleSearchResult(
+            contacts=contacts,
+            total=pagination.get("total_entries", data.get("total_entries", len(contacts))),
+            page=pagination.get("page", page),
+            per_page=pagination.get("per_page", per_page),
+        )
+
+    async def search_organizations(
+        self,
+        *,
+        industries: list[str] | None = None,
+        min_headcount: int | None = None,
+        max_headcount: int | None = None,
+        page: int = 1,
+        per_page: int = 25,
+        **extra: Any,
+    ) -> OrgSearchResult:
+        """Search for organizations by industry and headcount range."""
+        payload: dict[str, Any] = {"page": page, "per_page": per_page}
+        if industries:
+            payload["organization_industry_tag_ids"] = industries
+        if min_headcount is not None or max_headcount is not None:
+            payload["organization_num_employees_ranges"] = [
+                f"{min_headcount or 1},{max_headcount or 100_000}"
+            ]
+        payload.update(extra)
+
+        data = await self._post("/mixed_companies/search", payload)
+        orgs = [self._parse_organization(o) for o in data.get("organizations", [])]
+        pagination = data.get("pagination", {})
+        return OrgSearchResult(
+            organizations=orgs,
+            total=pagination.get("total_entries", len(orgs)),
+            page=pagination.get("page", page),
+            per_page=pagination.get("per_page", per_page),
+        )
+
+    async def enrich_person(
+        self,
+        *,
+        person_id: str | None = None,
+        email: str | None = None,
+        linkedin_url: str | None = None,
+    ) -> ApolloContact | None:
+        """Enrich a person by ID, email, or LinkedIn URL. Returns None if not found."""
+        if not person_id and not email and not linkedin_url:
+            raise ValueError("Provide at least one of person_id, email, or linkedin_url")
+        payload: dict[str, Any] = {}
+        if person_id:
+            payload["id"] = person_id
+        if email:
+            payload["email"] = email
+        if linkedin_url:
+            payload["linkedin_url"] = linkedin_url
+
+        data = await self._post("/people/match", payload)
+        person = data.get("person")
+        if not person:
+            return None
+        return self._parse_contact(person)
+
+    async def enrich_organization(self, *, domain: str) -> ApolloOrganization | None:
+        """Enrich an organization by domain. Returns None if not found."""
+        data = await self._post("/organizations/enrich", {"domain": domain})
+        org = data.get("organization")
+        if not org:
+            return None
+        return self._parse_organization(org)