heyleads 1.0.0__tar.gz

heyleads-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 HeyLeads
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

heyleads-1.0.0/PKG-INFO

@@ -0,0 +1,73 @@
+Metadata-Version: 2.4
+Name: heyleads
+Version: 1.0.0
+Summary: Official Python client for the HeyLeads API (LinkedIn outreach): campaigns, leads, lists, inbox, webhooks. Standard library only.
+License-Expression: MIT
+Project-URL: Homepage, https://app.heyleads.so/developers
+Project-URL: Documentation, https://app.heyleads.so/developers
+Keywords: heyleads,linkedin,outreach,api,sdk
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Developers
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# heyleads (Python)
+
+Python client for the [HeyLeads API](https://app.heyleads.so/developers). **Standard library only** (no `requests`, no dependencies); Python 3.9+.
+
+## Install
+
+```bash
+pip install heyleads
+```
+
+Create an API key in HeyLeads under **Settings → Integrations → API keys** (it starts with `hl_live_`) and keep it in an environment variable.
+
+```python
+import os
+from heyleads import HeyLeads, HeyLeadsError
+
+hl = HeyLeads(api_key=os.environ["HEYLEAD_API_KEY"])  # talks to https://app.heyleads.so unless you pass base_url
+
+campaign = hl.campaigns.create({"name": "Founders, Q4"})  # a draft: nothing is sent yet
+hl.campaigns.add_leads(campaign["id"], rows=[{"fullName": "Ada Lovelace", "linkedinUrl": "https://www.linkedin.com/in/ada-lovelace"}])  # queued
+hl.campaigns.launch(campaign["id"])  # running, not "sent": the engine paces every action within each account's limits
+
+for lead in hl.leads.iterate(status="active"):  # follows the cursor for you
+    print(lead["fullName"])
+
+try:
+    hl.lists.create("")
+except HeyLeadsError as e:
+    print(e.status, e.code, e.message, e.field_errors, e.request_id)
+```
+
+## Good to know
+
+- **Dicts in, dicts out**, with the API's own camelCase keys (`fullName`, `linkedinUrl`, `nextCursor`), so nothing is lost in translation and the [API reference](https://app.heyleads.so/developers/reference) is the documentation for every field. Options that are Python keyword arguments are snake_case and sent as camelCase (`campaign_id` → `campaignId`; `from_` → `from`).
+- **Queued, not sent.** There is no "send now": adding leads to a campaign is how HeyLeads contacts anyone, and a return means queued / running. People on the blacklist or marked do-not-contact are skipped and counted in the answer.
+- **Errors** are `HeyLeadsError` with `status`, `code`, `message`, `request_id`, and, for a 422, `field_errors` / `issues`. A network failure or timeout has `status == 0`.
+- **Retries.** A `429` is waited out using `Retry-After` (for any method: it was refused before it ran). Repeatable requests (`GET`, `PUT`, `DELETE`, and queued LinkedIn actions, which carry an `Idempotency-Key`) are also retried after a `502`/`503`/`504` or a network error; a `POST`/`PATCH` that may have run is **never** repeated. Tune with `max_retries` (default 2), `timeout` (30 s) and `max_retry_wait_seconds` (30: a longer `Retry-After` raises so you can decide).
+- **Paging.** `leads.list` / `inbox.threads` return `{items, nextCursor, total}`; `leads.iterate`, `lists.iterate_leads` and `inbox.iterate_threads` walk every page.
+- **Waiting for an action.** `hl.actions.wait(action["id"])` polls until it finishes (default up to 5 minutes); prefer webhooks in production.
+- **Webhooks.** Verify a delivery against the **raw** body:
+
+```python
+from heyleads import construct_webhook_event
+
+@app.post("/heylead")
+def hook():
+    try:
+        event = construct_webhook_event(os.environ["HEYLEAD_WEBHOOK_SECRET"], request.headers.get("x-heylead-signature"), request.get_data())  # raises ValueError if invalid or older than 5 minutes
+    except ValueError:
+        return "", 400
+    if event["event"] == "lead.positive_reply":
+        handle(event["data"])
+    return "", 200
+```
+
+The method list mirrors `GET /api/v1/openapi.json` one to one (`heyleads.SDK_OPERATIONS` maps each operation id to its method, and a test fails if they drift). The tests run the client against the real API handlers over HTTP.

heyleads-1.0.0/README.md

@@ -0,0 +1,56 @@
+# heyleads (Python)
+
+Python client for the [HeyLeads API](https://app.heyleads.so/developers). **Standard library only** (no `requests`, no dependencies); Python 3.9+.
+
+## Install
+
+```bash
+pip install heyleads
+```
+
+Create an API key in HeyLeads under **Settings → Integrations → API keys** (it starts with `hl_live_`) and keep it in an environment variable.
+
+```python
+import os
+from heyleads import HeyLeads, HeyLeadsError
+
+hl = HeyLeads(api_key=os.environ["HEYLEAD_API_KEY"])  # talks to https://app.heyleads.so unless you pass base_url
+
+campaign = hl.campaigns.create({"name": "Founders, Q4"})  # a draft: nothing is sent yet
+hl.campaigns.add_leads(campaign["id"], rows=[{"fullName": "Ada Lovelace", "linkedinUrl": "https://www.linkedin.com/in/ada-lovelace"}])  # queued
+hl.campaigns.launch(campaign["id"])  # running, not "sent": the engine paces every action within each account's limits
+
+for lead in hl.leads.iterate(status="active"):  # follows the cursor for you
+    print(lead["fullName"])
+
+try:
+    hl.lists.create("")
+except HeyLeadsError as e:
+    print(e.status, e.code, e.message, e.field_errors, e.request_id)
+```
+
+## Good to know
+
+- **Dicts in, dicts out**, with the API's own camelCase keys (`fullName`, `linkedinUrl`, `nextCursor`), so nothing is lost in translation and the [API reference](https://app.heyleads.so/developers/reference) is the documentation for every field. Options that are Python keyword arguments are snake_case and sent as camelCase (`campaign_id` → `campaignId`; `from_` → `from`).
+- **Queued, not sent.** There is no "send now": adding leads to a campaign is how HeyLeads contacts anyone, and a return means queued / running. People on the blacklist or marked do-not-contact are skipped and counted in the answer.
+- **Errors** are `HeyLeadsError` with `status`, `code`, `message`, `request_id`, and, for a 422, `field_errors` / `issues`. A network failure or timeout has `status == 0`.
+- **Retries.** A `429` is waited out using `Retry-After` (for any method: it was refused before it ran). Repeatable requests (`GET`, `PUT`, `DELETE`, and queued LinkedIn actions, which carry an `Idempotency-Key`) are also retried after a `502`/`503`/`504` or a network error; a `POST`/`PATCH` that may have run is **never** repeated. Tune with `max_retries` (default 2), `timeout` (30 s) and `max_retry_wait_seconds` (30: a longer `Retry-After` raises so you can decide).
+- **Paging.** `leads.list` / `inbox.threads` return `{items, nextCursor, total}`; `leads.iterate`, `lists.iterate_leads` and `inbox.iterate_threads` walk every page.
+- **Waiting for an action.** `hl.actions.wait(action["id"])` polls until it finishes (default up to 5 minutes); prefer webhooks in production.
+- **Webhooks.** Verify a delivery against the **raw** body:
+
+```python
+from heyleads import construct_webhook_event
+
+@app.post("/heylead")
+def hook():
+    try:
+        event = construct_webhook_event(os.environ["HEYLEAD_WEBHOOK_SECRET"], request.headers.get("x-heylead-signature"), request.get_data())  # raises ValueError if invalid or older than 5 minutes
+    except ValueError:
+        return "", 400
+    if event["event"] == "lead.positive_reply":
+        handle(event["data"])
+    return "", 200
+```
+
+The method list mirrors `GET /api/v1/openapi.json` one to one (`heyleads.SDK_OPERATIONS` maps each operation id to its method, and a test fails if they drift). The tests run the client against the real API handlers over HTTP.

heyleads-1.0.0/heyleads/__init__.py

@@ -0,0 +1,6 @@
+"""The HeyLeads Python client. See README.md and https://<your-host>/developers."""
+from .client import SDK_OPERATIONS, SDK_VERSION, HeyLeads
+from .errors import HeyLeadsError
+from .webhooks import construct_webhook_event, verify_webhook_signature
+
+__all__ = ["HeyLeads", "HeyLeadsError", "SDK_OPERATIONS", "SDK_VERSION", "construct_webhook_event", "verify_webhook_signature"]

heyleads-1.0.0/heyleads/client.py

@@ -0,0 +1,576 @@
+"""The HeyLeads API client. Standard library only (no dependencies); Python 3.9+.
+
+    from heyleads import HeyLeads
+
+    hl = HeyLeads(api_key=os.environ["HEYLEAD_API_KEY"], base_url="https://app.heyleads.so")
+    campaign = hl.campaigns.create({"name": "Founders, Q4"})  # a draft: nothing is sent yet
+    hl.campaigns.add_leads(campaign["id"], rows=[{"fullName": "Ada Lovelace", "linkedinUrl": "https://www.linkedin.com/in/ada-lovelace"}])  # queued
+    hl.campaigns.launch(campaign["id"])  # running, not "sent": the engine paces every action within each account's limits
+
+Requests and responses are plain dicts with the API's own camelCase keys (see the reference at /developers), so nothing is lost in translation. Options that are
+Python keyword arguments are snake_case and sent as camelCase. The method list mirrors GET /api/v1/openapi.json one to one (a test fails if they drift).
+"""
+from __future__ import annotations
+
+import json
+import random
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+import uuid
+from typing import Any, Callable, Dict, Iterator, List, Mapping, Optional, Tuple
+
+from .errors import HeyLeadsError
+
+SDK_VERSION = "1.0.0"
+# Where the hosted HeyLeads API lives.
+DEFAULT_BASE_URL = "https://app.heyleads.so"
+
+# (status, headers, body) for one request. Replaceable, so tests and proxies can supply their own.
+Transport = Callable[[str, str, Dict[str, str], Optional[bytes], float], Tuple[int, Mapping[str, str], bytes]]
+
+_IDEMPOTENT = {"GET", "PUT", "DELETE", "HEAD"}
+
+
+def _quote(value: str) -> str:
+    return urllib.parse.quote(str(value), safe="")
+
+
+def _camel(name: str) -> str:
+    head, *rest = name.split("_")
+    return head + "".join(p[:1].upper() + p[1:] for p in rest)
+
+
+def _query_value(v: Any) -> str:
+    if isinstance(v, bool):
+        return "true" if v else "false"
+    return str(v)
+
+
+def _default_transport(method: str, url: str, headers: Dict[str, str], body: Optional[bytes], timeout: float) -> Tuple[int, Mapping[str, str], bytes]:
+    req = urllib.request.Request(url, data=body, headers=headers, method=method)
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as res:  # noqa: S310 - the URL is the host the caller configured
+            return res.status, {k.lower(): v for k, v in res.headers.items()}, res.read()
+    except urllib.error.HTTPError as e:
+        return e.code, {k.lower(): v for k, v in (e.headers or {}).items()}, e.read()
+
+
+class HeyLeads:
+    """The client. One instance per API key; safe to share between threads."""
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: Optional[str] = None,
+        max_retries: int = 2,
+        timeout: float = 30.0,
+        max_retry_wait_seconds: float = 30.0,
+        transport: Optional[Transport] = None,
+        sleep: Optional[Callable[[float], None]] = None,
+    ) -> None:
+        """
+        Args:
+            api_key: `hl_live_…`. Keep it on your server.
+            base_url: your HeyLeads host, e.g. `https://app.heyleads.so` (no `/api/v1`). Defaults to $HEYLEAD_BASE_URL, else https://app.heyleads.so.
+            max_retries: retries after a 429 or a temporary failure. Default 2 (so up to 3 attempts). 0 turns retrying off.
+            timeout: per-attempt timeout in seconds.
+            max_retry_wait_seconds: the longest the client waits on a single `Retry-After`. A longer ask raises immediately so you can decide.
+        """
+        if not isinstance(api_key, str) or not api_key.startswith("hl_live_"):
+            raise TypeError("HeyLeads: pass your API key as `api_key` (it starts with hl_live_).")
+        import os
+
+        # The hosted product by default; `base_url` (or HEYLEAD_BASE_URL) points it at another host.
+        base = (base_url or os.environ.get("HEYLEAD_BASE_URL") or DEFAULT_BASE_URL).strip()
+        if not base.lower().startswith(("http://", "https://")):
+            raise TypeError("HeyLeads: `base_url` must start with https:// (for example https://app.heyleads.so).")
+        self._api_key = api_key
+        self._root = base.rstrip("/") + "/api/v1"
+        self._max_retries = max(0, int(max_retries))
+        self._timeout = float(timeout)
+        self._max_wait = float(max_retry_wait_seconds)
+        self._transport = transport or _default_transport
+        self._sleep = sleep or time.sleep
+        self.accounts = Accounts(self)
+        self.actions = Actions(self)
+        self.campaigns = Campaigns(self)
+        self.leads = Leads(self)
+        self.lists = Lists(self)
+        self.blacklist = Blacklist(self)
+        self.members = Members(self)
+        self.inbox = Inbox(self)
+        self.analytics = AnalyticsApi(self)
+        self.webhooks = Webhooks(self)
+
+    def workspace(self) -> dict:
+        """The workspace this key acts in: name, plan, time zone, working hours and how much it holds."""
+        return self.request("GET", "/workspace")
+
+    def me(self) -> dict:
+        """Who this key is: the workspace it acts in and its effective role. A cheap way to check a key works."""
+        return self.request("GET", "/me")
+
+    # ── the one place a request is made ──────────────────────────────────────────────────────────────────────────
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        query: Optional[Mapping[str, Any]] = None,
+        body: Any = None,
+        headers: Optional[Mapping[str, str]] = None,
+        repeatable: bool = False,
+    ) -> Any:
+        url = self._root + path
+        if query:
+            qs = urllib.parse.urlencode({k: _query_value(v) for k, v in query.items() if v is not None})
+            if qs:
+                url += "?" + qs
+        payload = None if body is None else json.dumps(body).encode("utf-8")
+        request_id = str(uuid.uuid4())
+        can_repeat = repeatable or method in _IDEMPOTENT
+        base_headers = {
+            "authorization": f"Bearer {self._api_key}",
+            "accept": "application/json",
+            "user-agent": f"heyleads-python/{SDK_VERSION}",
+            "x-request-id": request_id,
+            **({"content-type": "application/json"} if payload is not None else {}),
+            **{k.lower(): v for k, v in (headers or {}).items()},
+        }
+
+        attempt = 0
+        while True:
+            try:
+                status, res_headers, raw = self._transport(method, url, base_headers, payload, self._timeout)
+            except HeyLeadsError:
+                raise
+            except Exception as err:  # noqa: BLE001 - any transport failure is a network error to the caller
+                # The request may or may not have reached the server, so only a repeatable request is retried.
+                if attempt < self._max_retries and can_repeat:
+                    self._sleep(self._backoff(attempt))
+                    attempt += 1
+                    continue
+                timed_out = isinstance(err, TimeoutError) or "timed out" in str(err).lower()
+                raise HeyLeadsError(
+                    0,
+                    "timeout" if timed_out else "network_error",
+                    f"Timed out after {self._timeout:g} s" if timed_out else f"Network error: {err}",
+                ) from err
+
+            if 200 <= status < 300:
+                return None if status == 204 or not raw else json.loads(raw.decode("utf-8"))
+
+            error = _to_error(status, res_headers, raw)
+            delay = self._retry_delay(can_repeat, status, error, attempt)
+            if delay is None:
+                raise error
+            self._sleep(delay)
+            attempt += 1
+
+    def _backoff(self, attempt: int) -> float:
+        return min(8.0, 0.5 * 2**attempt) + random.random() * 0.25
+
+    def _retry_delay(self, repeatable: bool, status: int, error: HeyLeadsError, attempt: int) -> Optional[float]:
+        """Seconds to wait before retrying, or None to give up and raise."""
+        if attempt >= self._max_retries:
+            return None
+        # A feature the server has switched off will not come back on by waiting a few seconds.
+        if error.code == "actions_disabled":
+            return None
+        # 429: refused BEFORE it ran, so retrying is safe for every method. Our own 503 "unavailable" is also refused before it runs.
+        # Any other 5xx may have run: repeatable methods only.
+        safe = status == 429 or (status == 503 and error.code == "unavailable")
+        transient = status in (502, 503, 504)
+        if not safe and not (transient and repeatable):
+            return None
+        asked = error.retry_after_seconds
+        if asked is not None:
+            return None if asked > self._max_wait else float(asked)
+        return self._backoff(attempt)
+
+
+def _to_error(status: int, headers: Mapping[str, str], raw: bytes) -> HeyLeadsError:
+    envelope: dict = {}
+    try:
+        parsed = json.loads(raw.decode("utf-8"))
+        if isinstance(parsed, dict):
+            envelope = parsed
+    except Exception:  # noqa: BLE001 - not JSON (a proxy's error page): fall through to the generic message
+        pass
+    e = envelope.get("error") if isinstance(envelope.get("error"), dict) else {}
+    try:
+        header = float(headers.get("retry-after", ""))
+    except ValueError:
+        header = 0.0
+    return HeyLeadsError(
+        status,
+        e.get("code") or ("rate_limited" if status == 429 else "http_error"),
+        e.get("message") or f"HeyLeads API answered {status}",
+        e.get("requestId") or headers.get("x-request-id"),
+        e.get("fieldErrors"),
+        e.get("issues"),
+        e.get("retryAfterSeconds") if e.get("retryAfterSeconds") is not None else (header if header > 0 else None),
+    )
+
+
+class _Resource:
+    def __init__(self, client: HeyLeads) -> None:
+        self._c = client
+
+
+def _drop_none(d: Mapping[str, Any]) -> Dict[str, Any]:
+    return {k: v for k, v in d.items() if v is not None}
+
+
+def _iso(d: Any) -> Any:
+    return d.isoformat() if hasattr(d, "isoformat") else d
+
+
+def _pages(fetch: Callable[[Optional[str]], dict]) -> Iterator[dict]:
+    cursor: Optional[str] = None
+    while True:
+        page = fetch(cursor)
+        yield from page["items"]
+        cursor = page.get("nextCursor")
+        if not cursor:
+            return
+
+
+class Accounts(_Resource):
+    def _queue(self, account_id: str, path: str, body: Dict[str, Any], not_before: Any, expires_in_seconds: Optional[int], idempotency_key: Optional[str]) -> dict:
+        """Queue a LinkedIn action. It is QUEUED, never sent immediately: a worker runs it under the account's daily limits, warm-up and working hours,
+        and drops it if it expires first. Every call carries an Idempotency-Key (yours, or one generated here), so a retry after a network error
+        cannot queue it twice. Wait for the outcome with `hl.actions.wait(action["id"])` or the action.* webhooks."""
+        return self._c.request(
+            "POST",
+            f"/accounts/{_quote(account_id)}/{path}",
+            body=_drop_none({**body, "notBefore": _iso(not_before), "expiresInSeconds": expires_in_seconds}),
+            headers={"idempotency-key": idempotency_key or str(uuid.uuid4())},
+            repeatable=True,
+        )
+
+    def send_connection_request(self, account_id: str, profile_url: str, note: Optional[str] = None, *, not_before: Any = None, expires_in_seconds: Optional[int] = None, idempotency_key: Optional[str] = None) -> dict:
+        """A connection request, with or without a note (up to 300 characters, sent exactly as written)."""
+        return self._queue(account_id, "connection-requests", _drop_none({"profileUrl": profile_url, "note": note}), not_before, expires_in_seconds, idempotency_key)
+
+    def send_message(self, account_id: str, profile_url: str, text: str, override_reply_guard: Optional[bool] = None, *, not_before: Any = None, expires_in_seconds: Optional[int] = None, idempotency_key: Optional[str] = None) -> dict:
+        """A message to someone the account is connected to. Nothing is sent into a conversation they already answered unless `override_reply_guard` is True."""
+        return self._queue(account_id, "messages", _drop_none({"profileUrl": profile_url, "text": text, "overrideReplyGuard": override_reply_guard}), not_before, expires_in_seconds, idempotency_key)
+
+    def visit_profile(self, account_id: str, profile_url: str, *, not_before: Any = None, expires_in_seconds: Optional[int] = None, idempotency_key: Optional[str] = None) -> dict:
+        return self._queue(account_id, "profile-visits", {"profileUrl": profile_url}, not_before, expires_in_seconds, idempotency_key)
+
+    def follow(self, account_id: str, profile_url: str, *, not_before: Any = None, expires_in_seconds: Optional[int] = None, idempotency_key: Optional[str] = None) -> dict:
+        return self._queue(account_id, "follows", {"profileUrl": profile_url}, not_before, expires_in_seconds, idempotency_key)
+
+    def like_latest_post(self, account_id: str, profile_url: str, *, not_before: Any = None, expires_in_seconds: Optional[int] = None, idempotency_key: Optional[str] = None) -> dict:
+        return self._queue(account_id, "post-likes", {"profileUrl": profile_url}, not_before, expires_in_seconds, idempotency_key)
+
+    def endorse_skills(self, account_id: str, profile_url: str, max: Optional[int] = None, *, not_before: Any = None, expires_in_seconds: Optional[int] = None, idempotency_key: Optional[str] = None) -> dict:  # noqa: A002
+        return self._queue(account_id, "endorsements", _drop_none({"profileUrl": profile_url, "max": max}), not_before, expires_in_seconds, idempotency_key)
+
+    def list_actions(self, account_id: str, status: Optional[str] = None, type: Optional[str] = None, limit: Optional[int] = None, before: Optional[str] = None) -> dict:  # noqa: A002
+        """This account's queued and finished actions, newest first. Page back with the returned `nextBefore` as `before`."""
+        return self._c.request("GET", f"/accounts/{_quote(account_id)}/actions", query={"status": status, "type": type, "limit": limit, "before": before})
+
+    def list(self) -> List[dict]:
+        return self._c.request("GET", "/accounts")["items"]
+
+    def get(self, id: str) -> dict:  # noqa: A002
+        return self._c.request("GET", f"/accounts/{_quote(id)}")
+
+    def pause(self, id: str) -> dict:  # noqa: A002
+        """Stops all automation on the account until resumed."""
+        return self._c.request("POST", f"/accounts/{_quote(id)}/pause")
+
+    def resume(self, id: str) -> dict:  # noqa: A002
+        return self._c.request("POST", f"/accounts/{_quote(id)}/resume")
+
+    def set_tier(self, id: str, tier: str, sales_navigator: Optional[str] = None, recruiter: Optional[str] = None) -> dict:  # noqa: A002
+        """States which LinkedIn plan the account has until detection exists (`source: "declared"`). A detected plan is never overwritten (409);
+        `tier="unknown"` clears a declaration. InMail steps refuse to launch from a sender whose plan cannot send them."""
+        return self._c.request("PUT", f"/accounts/{_quote(id)}/tier", body=_drop_none({"tier": tier, "salesNavigator": sales_navigator, "recruiter": recruiter}))
+
+    def disconnect(self, id: str) -> None:  # noqa: A002
+        """Removes the account and its stored session from the workspace."""
+        self._c.request("DELETE", f"/accounts/{_quote(id)}")
+
+
+class Actions(_Resource):
+    def get(self, id: str) -> dict:  # noqa: A002
+        return self._c.request("GET", f"/actions/{_quote(id)}")
+
+    def cancel(self, id: str) -> dict:  # noqa: A002
+        """Only a queued action can be cancelled; a running one is left to finish."""
+        return self._c.request("POST", f"/actions/{_quote(id)}/cancel")
+
+    def wait(self, id: str, timeout_seconds: float = 300.0, interval_seconds: float = 3.0) -> dict:  # noqa: A002
+        """Polls until the action reaches a final status (succeeded, failed, cancelled, expired) and returns it, or raises a `timeout` HeyLeadsError.
+        An action can legitimately wait a long time (the account's working hours and daily limits come first), so prefer webhooks for production
+        and use this for scripts."""
+        deadline = time.monotonic() + timeout_seconds
+        while True:
+            action = self.get(id)
+            if action["status"] in ("succeeded", "failed", "cancelled", "expired"):
+                return action
+            if time.monotonic() + interval_seconds > deadline:
+                raise HeyLeadsError(0, "timeout", f"Action {id} is still {action['status']} after {timeout_seconds:g} s. It keeps its place in the queue.")
+            self._c._sleep(interval_seconds)
+
+
+class Campaigns(_Resource):
+    def list(self, status: Optional[str] = None) -> List[dict]:
+        return self._c.request("GET", "/campaigns", query={"status": status})["items"]
+
+    def create(self, body: Mapping[str, Any]) -> dict:
+        """Starts as a draft: nothing is sent until you `launch` it."""
+        return self._c.request("POST", "/campaigns", body=dict(body))
+
+    def get(self, id: str) -> dict:  # noqa: A002
+        return self._c.request("GET", f"/campaigns/{_quote(id)}")
+
+    def update(self, id: str, patch: Mapping[str, Any]) -> dict:  # noqa: A002
+        return self._c.request("PATCH", f"/campaigns/{_quote(id)}", body=dict(patch))
+
+    def delete(self, id: str) -> None:  # noqa: A002
+        self._c.request("DELETE", f"/campaigns/{_quote(id)}")
+
+    def save_graph(self, id: str, graph: Mapping[str, Any], expected_version: Optional[int] = None) -> dict:  # noqa: A002
+        """Replaces the whole graph. Pass the `graphVersion` you last read as `expected_version` so a concurrent edit is rejected instead of overwritten."""
+        return self._c.request("PUT", f"/campaigns/{_quote(id)}/graph", body=_drop_none({"graph": dict(graph), "expectedVersion": expected_version}))
+
+    def duplicate(self, id: str) -> dict:  # noqa: A002
+        return self._c.request("POST", f"/campaigns/{_quote(id)}/duplicate")
+
+    def launch(self, id: str) -> dict:  # noqa: A002
+        """Hands the campaign to the engine. A return means RUNNING, not that anything was sent. Needs an admin key."""
+        return self._c.request("POST", f"/campaigns/{_quote(id)}/launch")
+
+    def pause(self, id: str) -> dict:  # noqa: A002
+        return self._c.request("POST", f"/campaigns/{_quote(id)}/pause")
+
+    def resume(self, id: str) -> dict:  # noqa: A002
+        return self._c.request("POST", f"/campaigns/{_quote(id)}/resume")
+
+    def split_tests(self, id: str) -> List[dict]:  # noqa: A002
+        return self._c.request("GET", f"/campaigns/{_quote(id)}/split-tests")["items"]
+
+    def add_leads(self, campaign_id: str, rows: Optional[List[Mapping[str, Any]]] = None, lead_ids: Optional[List[str]] = None, **options: Any) -> dict:
+        """The only way to make HeyLeads contact someone. `rows` imports new leads and enrols them; `lead_ids` enrols existing ones. They are QUEUED:
+        the engine decides when each is contacted, within every account's safe limits. People on the blacklist or marked do-not-contact are skipped
+        and counted in the answer. Other options (`list_name`, `list_id`, `source`) are sent as the API's camelCase fields."""
+        body = _drop_none({"rows": rows, "leadIds": lead_ids, **{_camel(k): v for k, v in options.items()}})
+        return self._c.request("POST", f"/campaigns/{_quote(campaign_id)}/leads", body=body)
+
+    def stop_lead(self, campaign_id: str, lead_id: str) -> dict:
+        """Take ONE lead out of this campaign's sequence (nothing more is sent from it). Safe to repeat: a lead that already left answers
+        `changed: False`. Raises a 409 while the engine is mid-step on that lead."""
+        return self._c.request("POST", f"/campaigns/{_quote(campaign_id)}/leads/{_quote(lead_id)}/stop")
+
+
+class Leads(_Resource):
+    @staticmethod
+    def _query(filters: Mapping[str, Any]) -> Dict[str, Any]:
+        return {_camel(k): v for k, v in filters.items()}
+
+    def list(self, **filters: Any) -> dict:
+        """One page of leads. Filters (snake_case): search, campaign_id, list_id, status, connection, reply_category, account_id, do_not_contact, sort, cursor, limit."""
+        return self._c.request("GET", "/leads", query=self._query(filters))
+
+    def iterate(self, **filters: Any) -> Iterator[dict]:
+        """Every matching lead, following the cursor for you: `for lead in hl.leads.iterate(status="active"): ...`"""
+        filters.pop("cursor", None)
+        return _pages(lambda cursor: self.list(**filters, cursor=cursor))
+
+    def get(self, id: str) -> dict:  # noqa: A002
+        """The lead with its activity timeline and the ids of its conversations."""
+        return self._c.request("GET", f"/leads/{_quote(id)}")
+
+    def events(self, id: str, campaign_id: Optional[str] = None) -> List[dict]:  # noqa: A002
+        return self._c.request("GET", f"/leads/{_quote(id)}/events", query={"campaignId": campaign_id})["items"]
+
+    def check_identities(self, public_ids: Optional[List[str]] = None, people: Optional[List[Mapping[str, Any]]] = None) -> dict:
+        """What the workspace already knows about some people (up to 5,000): lead or new, the lists they are in, do-not-contact, blacklisted. Never writes.
+        Send `public_ids` (profile URLs or bare identifiers) or `people` (dicts with `profileUrl` and optional `fullName` and `company`, for the blacklist check).
+        Returns `{items, invalid}`."""
+        return self._c.request("POST", "/leads/identities", body=_drop_none({"publicIds": public_ids, "people": [dict(p) for p in people] if people is not None else None}))
+
+    def classify_signals(self, items: List[Mapping[str, Any]], icp: Optional[str] = None) -> dict:
+        """Intent Lens: what up to 100 comments say about the people who left them, ranked. Each item is a dict with an `id`, the comment `text` (empty for someone who only reacted)
+        and optionally `headline`, `title` and `company`; `icp` is a sentence describing your ideal customer (with a headline, title or company it adds a `fit` score).
+        Returns `{items, engine}`; each item has `intent`, `heat`, `tier`, `fit`, `quote` (their own words, cleaned for a message), `by`, `seniority` and `function`. Reads only."""
+        return self._c.request("POST", "/leads/signals", body=_drop_none({"items": [dict(i) for i in items], "icp": icp}))
+
+    def lookup(self, profile_url: Optional[str] = None, email: Optional[str] = None) -> List[dict]:
+        """Find a lead by LinkedIn profile URL or by email (exactly one). A profile URL matches at most one lead; an email can match several."""
+        return self._c.request("GET", "/leads/lookup", query={"profileUrl": profile_url, "email": email})["items"]
+
+    def tag(self, lead_ids: List[str], add: Optional[List[str]] = None, remove: Optional[List[str]] = None) -> dict:
+        """Add and/or remove tags on many leads at once."""
+        return self._c.request("POST", "/leads/tags", body=_drop_none({"leadIds": lead_ids, "add": add, "remove": remove}))
+
+    def set_tags(self, id: str, tags: List[str]) -> List[str]:  # noqa: A002
+        """Leave the lead with exactly these tags (an empty list clears them). Returns the tags as stored."""
+        return self._c.request("PUT", f"/leads/{_quote(id)}/tags", body={"tags": tags})["tags"]
+
+    def set_custom_fields(self, id: str, set: Optional[Mapping[str, str]] = None, unset: Optional[List[str]] = None) -> dict:  # noqa: A002
+        """Set and/or remove plain custom fields (the values templates use as {{variables}}). Returns the lead's custom fields."""
+        return self._c.request("PATCH", f"/leads/{_quote(id)}/custom-fields", body=_drop_none({"set": dict(set) if set is not None else None, "unset": unset}))["customFields"]
+
+    def set_do_not_contact(self, id: str, value: bool) -> dict:  # noqa: A002
+        """A do-not-contact lead is never contacted by any campaign."""
+        return self._c.request("POST", f"/leads/{_quote(id)}/do-not-contact", body={"value": value})
+
+
+class Lists(_Resource):
+    def list(self) -> List[dict]:
+        return self._c.request("GET", "/lists")["items"]
+
+    def derive(self, operation: str, list_ids: List[str], name: Optional[str] = None, exclude_list_ids: Optional[List[str]] = None, dry_run: bool = False) -> dict:
+        """A NEW list from existing ones. `combine`: anyone in any of `list_ids`; `intersect`: in all of them; `exclude`: in the one list in `list_ids`
+        and in none of `exclude_list_ids`. The sources are never changed, and if nobody matches no list is created (`list` is None). `dry_run=True` only counts."""
+        return self._c.request("POST", "/lists/derive", body=_drop_none({"name": name, "operation": operation, "listIds": list_ids, "excludeListIds": exclude_list_ids, "dryRun": True if dry_run else None}))
+
+    def create(self, name: str) -> dict:
+        """An empty list to import into. (Importing with a `list_name` creates one for you.)"""
+        return self._c.request("POST", "/lists", body={"name": name})
+
+    def get(self, id: str) -> dict:  # noqa: A002
+        return self._c.request("GET", f"/lists/{_quote(id)}")
+
+    def leads(self, id: str, **filters: Any) -> dict:  # noqa: A002
+        """The leads in a list, one page at a time (pass `nextCursor` back as `cursor`)."""
+        return self._c.request("GET", f"/lists/{_quote(id)}/leads", query={_camel(k): v for k, v in filters.items()})
+
+    def iterate_leads(self, id: str, **filters: Any) -> Iterator[dict]:  # noqa: A002
+        """Every lead in a list, following the cursor for you."""
+        filters.pop("cursor", None)
+        return _pages(lambda cursor: self.leads(id, **filters, cursor=cursor))
+
+    def add_leads(self, id: str, rows: List[Mapping[str, Any]], source: Optional[str] = None) -> dict:  # noqa: A002
+        """Import new leads (up to 5,000 per call). People already in the workspace are skipped, not moved. Nothing is contacted."""
+        return self._c.request("POST", f"/lists/{_quote(id)}/leads", body=_drop_none({"rows": [dict(r) for r in rows], "source": source}))
+
+    def add_people(self, people: List[Mapping[str, Any]], list_id: Optional[str] = None, list_name: Optional[str] = None, post_url: Optional[str] = None, source: Optional[str] = None) -> dict:
+        """Add people (up to 500) to a list in one call: new ones are imported, existing leads are put in it too, blacklisted and do-not-contact people are
+        skipped and counted. Send `list_id` or `list_name`. Each person is a dict with `profileUrl` and optional `fullName`, `headline`, `company`,
+        `reactionType` and so on. Safe to repeat. Nothing is contacted."""
+        return self._c.request("POST", "/lists/add-people", body=_drop_none({"listId": list_id, "listName": list_name, "people": [dict(p) for p in people], "postUrl": post_url, "source": source}))
+
+    def delete_created_leads(self, id: str, lead_ids: List[str]) -> dict:  # noqa: A002
+        """Take back leads that `add_people` CREATED (up to 500 ids), while each is still exactly what the import made it: made by you, source `extension:post-engagers`, under 15 minutes
+        old, only in this list, in no campaign, with no events, conversation, notes or tags, not do-not-contact. Each id is judged alone. Not a general delete.
+        Returns `{deleted, refused: [{leadId, reason}]}`."""
+        return self._c.request("DELETE", f"/lists/{_quote(id)}/created-leads", body={"leadIds": list(lead_ids)})
+
+    def remove_members(self, id: str, lead_ids: List[str]) -> dict:  # noqa: A002
+        """Take leads out of this list again (up to 5,000 ids): the undo of `add_members`. A lead whose home list this is stays in it; no lead is deleted.
+        Safe to repeat. Returns `{removed, notInList, atHome, notFound}`."""
+        return self._c.request("DELETE", f"/lists/{_quote(id)}/members", body={"leadIds": list(lead_ids)})
+
+    def add_members(self, id: str, lead_ids: List[str]) -> dict:  # noqa: A002
+        """Put leads that ALREADY exist (up to 5,000 ids) in this list as well; their home list is unchanged. Safe to repeat. Nothing is contacted.
+        Returns `{added, alreadyInList, notFound}`."""
+        return self._c.request("POST", f"/lists/{_quote(id)}/members", body={"leadIds": list(lead_ids)})
+
+
+class Blacklist(_Resource):
+    def list(self, kind: str, search: Optional[str] = None) -> dict:
+        """People (`kind="lead"`) or companies (`kind="company"`) this workspace never contacts, newest first. Returns `{items, total, limit}`."""
+        return self._c.request("GET", "/blacklist", query={"kind": kind, "search": search})
+
+    def add(self, kind: str, entries: List[str], dry_run: bool = False) -> dict:
+        """Add up to 100 entries of one kind: a profile URL, email or full name (people), or a company page URL or name. Bad entries come back in
+        `invalid`, not stored. Leads who match are skipped when added to a campaign. `dry_run=True` stores nothing. Needs an admin key."""
+        return self._c.request("POST", "/blacklist", body=_drop_none({"kind": kind, "entries": entries, "dryRun": True if dry_run else None}))
+
+    def remove(self, id: str) -> None:  # noqa: A002
+        """The person or company can be contacted again."""
+        self._c.request("DELETE", f"/blacklist/{_quote(id)}")
+
+
+class Members(_Resource):
+    def list(self) -> List[dict]:
+        return self._c.request("GET", "/members")["items"]
+
+    def invite(self, email: str, role: str) -> dict:
+        """Emails the person an invitation. A key cannot grant `admin` (403): invite as `member` and promote in the dashboard."""
+        return self._c.request("POST", "/members", body={"email": email, "role": role})
+
+    def set_role(self, user_id: str, role: str) -> dict:
+        """Switch a teammate between `member` and `client_viewer`. A key cannot grant `admin`, or change an admin or the owner."""
+        return self._c.request("PATCH", f"/members/{_quote(user_id)}", body={"role": role})
+
+    def remove(self, user_id: str) -> None:
+        """Remove a member or client viewer. A key cannot remove an admin or the owner."""
+        self._c.request("DELETE", f"/members/{_quote(user_id)}")
+
+
+class Inbox(_Resource):
+    def threads(self, **filters: Any) -> dict:
+        return self._c.request("GET", "/inbox/threads", query={_camel(k): v for k, v in filters.items()})
+
+    def iterate_threads(self, **filters: Any) -> Iterator[dict]:
+        filters.pop("cursor", None)
+        return _pages(lambda cursor: self.threads(**filters, cursor=cursor))
+
+    def thread(self, id: str) -> dict:  # noqa: A002
+        return self._c.request("GET", f"/inbox/threads/{_quote(id)}")
+
+
+class AnalyticsApi(_Resource):
+    def get(self, **query: Any) -> dict:
+        """Query (snake_case): days, from_, to, campaign_id, account_id. `from_` is sent as `from`."""
+        return self._c.request("GET", "/analytics", query={("from" if k == "from_" else _camel(k)): v for k, v in query.items()})
+
+
+class Webhooks(_Resource):
+    def list(self) -> List[dict]:
+        return self._c.request("GET", "/webhooks")["items"]
+
+    def create(self, url: str, event_types: List[str], campaign_ids: Optional[List[str]] = None) -> dict:
+        """The returned `secret` is shown ONCE. Store it: it is what you verify signatures with."""
+        return self._c.request("POST", "/webhooks", body=_drop_none({"url": url, "eventTypes": event_types, "campaignIds": campaign_ids}))
+
+    def get(self, id: str) -> dict:  # noqa: A002
+        return self._c.request("GET", f"/webhooks/{_quote(id)}")
+
+    def update(self, id: str, url: Optional[str] = None, event_types: Optional[List[str]] = None, campaign_ids: Optional[List[str]] = None, is_active: Optional[bool] = None) -> dict:  # noqa: A002
+        return self._c.request("PATCH", f"/webhooks/{_quote(id)}", body=_drop_none({"url": url, "eventTypes": event_types, "campaignIds": campaign_ids, "isActive": is_active}))
+
+    def delete(self, id: str) -> None:  # noqa: A002
+        self._c.request("DELETE", f"/webhooks/{_quote(id)}")
+
+    def deliveries(self, id: str, limit: Optional[int] = None, before: Optional[str] = None) -> dict:  # noqa: A002
+        return self._c.request("GET", f"/webhooks/{_quote(id)}/deliveries", query={"limit": limit, "before": before})
+
+    def test(self, id: str) -> dict:  # noqa: A002
+        """Queues a `webhook.test` event to this endpoint; see `deliveries` for the result."""
+        return self._c.request("POST", f"/webhooks/{_quote(id)}/test")
+
+    def rotate_secret(self, id: str) -> dict:  # noqa: A002
+        """Issues a new secret (shown once); the old one stops working immediately."""
+        return self._c.request("POST", f"/webhooks/{_quote(id)}/rotate-secret")
+
+
+# operationId (from the OpenAPI document) -> the SDK method that serves it. A test keeps this in step with the spec.
+SDK_OPERATIONS: Dict[str, str] = {
+    "listAccounts": "accounts.list", "getAccount": "accounts.get", "setAccountTier": "accounts.set_tier", "pauseAccount": "accounts.pause", "resumeAccount": "accounts.resume", "disconnectAccount": "accounts.disconnect",
+    "listCampaigns": "campaigns.list", "createCampaign": "campaigns.create", "getCampaign": "campaigns.get", "updateCampaign": "campaigns.update", "deleteCampaign": "campaigns.delete",
+    "saveCampaignGraph": "campaigns.save_graph", "duplicateCampaign": "campaigns.duplicate", "launchCampaign": "campaigns.launch", "pauseCampaign": "campaigns.pause", "resumeCampaign": "campaigns.resume",
+    "getSplitTests": "campaigns.split_tests", "addLeadsToCampaign": "campaigns.add_leads", "stopLeadInCampaign": "campaigns.stop_lead",
+    "getMe": "me", "getWorkspace": "workspace",
+    "listMembers": "members.list", "inviteMember": "members.invite", "updateMemberRole": "members.set_role", "removeMember": "members.remove",
+    "listBlacklist": "blacklist.list", "addToBlacklist": "blacklist.add", "removeFromBlacklist": "blacklist.remove",
+    "deriveList": "lists.derive", "listLists": "lists.list", "createList": "lists.create", "getList": "lists.get", "listListLeads": "lists.leads", "addLeadsToList": "lists.add_leads", "addMembersToList": "lists.add_members", "removeMembersFromList": "lists.remove_members", "deleteCreatedLeads": "lists.delete_created_leads", "addPeopleToList": "lists.add_people",
+    "listLeads": "leads.list", "getLead": "leads.get", "getLeadEvents": "leads.events", "setDoNotContact": "leads.set_do_not_contact",
+    "checkLeadIdentities": "leads.check_identities", "classifyLeadSignals": "leads.classify_signals", "lookupLead": "leads.lookup", "tagLeads": "leads.tag", "setLeadTags": "leads.set_tags", "updateLeadCustomFields": "leads.set_custom_fields",
+    "listInboxThreads": "inbox.threads", "getInboxThread": "inbox.thread",
+    "getAnalytics": "analytics.get",
+    "queueConnectionRequest": "accounts.send_connection_request", "queueMessage": "accounts.send_message", "queueProfileVisit": "accounts.visit_profile", "queueFollow": "accounts.follow",
+    "queuePostLike": "accounts.like_latest_post", "queueEndorsement": "accounts.endorse_skills", "listAccountActions": "accounts.list_actions", "getAction": "actions.get", "cancelAction": "actions.cancel",
+    "listWebhooks": "webhooks.list", "createWebhook": "webhooks.create", "getWebhook": "webhooks.get", "updateWebhook": "webhooks.update", "deleteWebhook": "webhooks.delete",
+    "listWebhookDeliveries": "webhooks.deliveries", "testWebhook": "webhooks.test", "rotateWebhookSecret": "webhooks.rotate_secret",
+}

heyleads-1.0.0/heyleads/errors.py

@@ -0,0 +1,39 @@
+"""Anything the API (or the network) answered that is not a success."""
+from __future__ import annotations
+
+from typing import Any, Optional
+
+
+class HeyLeadsError(Exception):
+    """Raised for every non-success answer.
+
+    Attributes:
+        status: HTTP status, or 0 when the request never got an answer (network error, timeout).
+        code: the API's error code: unauthenticated, forbidden, not_found, invalid, rate_limited, limit_reached, unavailable, unknown ...
+        request_id: quote this to HeyLeads support.
+        field_errors: field name -> message, for a 422 on bad input.
+        issues: campaign graph problems, for a 422 on a graph save or launch.
+        retry_after_seconds: for a 429, how long the API asked you to wait.
+    """
+
+    def __init__(
+        self,
+        status: int,
+        code: str,
+        message: str,
+        request_id: Optional[str] = None,
+        field_errors: Optional[dict] = None,
+        issues: Optional[list] = None,
+        retry_after_seconds: Optional[float] = None,
+    ) -> None:
+        super().__init__(message)
+        self.status = status
+        self.code = code
+        self.message = message
+        self.request_id = request_id
+        self.field_errors = field_errors
+        self.issues = issues
+        self.retry_after_seconds = retry_after_seconds
+
+    def __repr__(self) -> str:  # pragma: no cover - cosmetic
+        return f"HeyLeadsError(status={self.status}, code={self.code!r}, message={self.message!r}, request_id={self.request_id!r})"

heyleads-1.0.0/heyleads/webhooks.py

@@ -0,0 +1,57 @@
+"""Verify a webhook delivery. Dependency-free, and byte-for-byte the algorithm in docs/api/webhooks.md:
+
+    x-heylead-signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>" keyed with your whsec_ secret>
+"""
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import time
+from typing import Any, Optional, Union
+
+
+def verify_webhook_signature(
+    secret: str,
+    signature_header: Optional[str],
+    raw_body: Union[str, bytes],
+    now_seconds: Optional[float] = None,
+    tolerance_seconds: float = 300,
+) -> bool:
+    """True only if `signature_header` is a valid signature of the EXACT `raw_body` bytes you received, made with `secret`, and recent enough.
+
+    Pass the raw request body, never a re-serialised object: re-serialising changes the bytes.
+    """
+    if not signature_header:
+        return False
+    parts: dict = {}
+    for piece in signature_header.split(","):
+        i = piece.find("=")
+        if i > 0:
+            parts[piece[:i].strip()] = piece[i + 1 :].strip()
+    try:
+        t = float(parts.get("t", ""))
+    except ValueError:
+        return False
+    given = parts.get("v1")
+    now = time.time() if now_seconds is None else now_seconds
+    if not given or abs(now - t) > tolerance_seconds:
+        return False
+    body = raw_body if isinstance(raw_body, str) else raw_body.decode("utf-8")
+    # The timestamp is signed as the text the sender wrote, so use it as written (an integer, in practice).
+    t_text = parts["t"]
+    expected = hmac.new(secret.encode("utf-8"), f"{t_text}.{body}".encode("utf-8"), hashlib.sha256).hexdigest()
+    return hmac.compare_digest(expected, given)
+
+
+def construct_webhook_event(
+    secret: str,
+    signature_header: Optional[str],
+    raw_body: Union[str, bytes],
+    now_seconds: Optional[float] = None,
+    tolerance_seconds: float = 300,
+) -> Any:
+    """Verify, then parse. Raises ValueError if the signature is bad, so an unverified body is never handed to your code as an event."""
+    if not verify_webhook_signature(secret, signature_header, raw_body, now_seconds, tolerance_seconds):
+        raise ValueError("Invalid HeyLeads webhook signature")
+    return json.loads(raw_body if isinstance(raw_body, str) else raw_body.decode("utf-8"))

heyleads-1.0.0/heyleads.egg-info/PKG-INFO

@@ -0,0 +1,73 @@
+Metadata-Version: 2.4
+Name: heyleads
+Version: 1.0.0
+Summary: Official Python client for the HeyLeads API (LinkedIn outreach): campaigns, leads, lists, inbox, webhooks. Standard library only.
+License-Expression: MIT
+Project-URL: Homepage, https://app.heyleads.so/developers
+Project-URL: Documentation, https://app.heyleads.so/developers
+Keywords: heyleads,linkedin,outreach,api,sdk
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Developers
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# heyleads (Python)
+
+Python client for the [HeyLeads API](https://app.heyleads.so/developers). **Standard library only** (no `requests`, no dependencies); Python 3.9+.
+
+## Install
+
+```bash
+pip install heyleads
+```
+
+Create an API key in HeyLeads under **Settings → Integrations → API keys** (it starts with `hl_live_`) and keep it in an environment variable.
+
+```python
+import os
+from heyleads import HeyLeads, HeyLeadsError
+
+hl = HeyLeads(api_key=os.environ["HEYLEAD_API_KEY"])  # talks to https://app.heyleads.so unless you pass base_url
+
+campaign = hl.campaigns.create({"name": "Founders, Q4"})  # a draft: nothing is sent yet
+hl.campaigns.add_leads(campaign["id"], rows=[{"fullName": "Ada Lovelace", "linkedinUrl": "https://www.linkedin.com/in/ada-lovelace"}])  # queued
+hl.campaigns.launch(campaign["id"])  # running, not "sent": the engine paces every action within each account's limits
+
+for lead in hl.leads.iterate(status="active"):  # follows the cursor for you
+    print(lead["fullName"])
+
+try:
+    hl.lists.create("")
+except HeyLeadsError as e:
+    print(e.status, e.code, e.message, e.field_errors, e.request_id)
+```
+
+## Good to know
+
+- **Dicts in, dicts out**, with the API's own camelCase keys (`fullName`, `linkedinUrl`, `nextCursor`), so nothing is lost in translation and the [API reference](https://app.heyleads.so/developers/reference) is the documentation for every field. Options that are Python keyword arguments are snake_case and sent as camelCase (`campaign_id` → `campaignId`; `from_` → `from`).
+- **Queued, not sent.** There is no "send now": adding leads to a campaign is how HeyLeads contacts anyone, and a return means queued / running. People on the blacklist or marked do-not-contact are skipped and counted in the answer.
+- **Errors** are `HeyLeadsError` with `status`, `code`, `message`, `request_id`, and, for a 422, `field_errors` / `issues`. A network failure or timeout has `status == 0`.
+- **Retries.** A `429` is waited out using `Retry-After` (for any method: it was refused before it ran). Repeatable requests (`GET`, `PUT`, `DELETE`, and queued LinkedIn actions, which carry an `Idempotency-Key`) are also retried after a `502`/`503`/`504` or a network error; a `POST`/`PATCH` that may have run is **never** repeated. Tune with `max_retries` (default 2), `timeout` (30 s) and `max_retry_wait_seconds` (30: a longer `Retry-After` raises so you can decide).
+- **Paging.** `leads.list` / `inbox.threads` return `{items, nextCursor, total}`; `leads.iterate`, `lists.iterate_leads` and `inbox.iterate_threads` walk every page.
+- **Waiting for an action.** `hl.actions.wait(action["id"])` polls until it finishes (default up to 5 minutes); prefer webhooks in production.
+- **Webhooks.** Verify a delivery against the **raw** body:
+
+```python
+from heyleads import construct_webhook_event
+
+@app.post("/heylead")
+def hook():
+    try:
+        event = construct_webhook_event(os.environ["HEYLEAD_WEBHOOK_SECRET"], request.headers.get("x-heylead-signature"), request.get_data())  # raises ValueError if invalid or older than 5 minutes
+    except ValueError:
+        return "", 400
+    if event["event"] == "lead.positive_reply":
+        handle(event["data"])
+    return "", 200
+```
+
+The method list mirrors `GET /api/v1/openapi.json` one to one (`heyleads.SDK_OPERATIONS` maps each operation id to its method, and a test fails if they drift). The tests run the client against the real API handlers over HTTP.

heyleads-1.0.0/heyleads.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+LICENSE
+README.md
+pyproject.toml
+heyleads/__init__.py
+heyleads/client.py
+heyleads/errors.py
+heyleads/webhooks.py
+heyleads.egg-info/PKG-INFO
+heyleads.egg-info/SOURCES.txt
+heyleads.egg-info/dependency_links.txt
+heyleads.egg-info/top_level.txt
+tests/test_client.py

heyleads-1.0.0/heyleads.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

heyleads-1.0.0/heyleads.egg-info/top_level.txt

@@ -0,0 +1 @@
+heyleads

heyleads-1.0.0/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "heyleads"
+version = "1.0.0"
+description = "Official Python client for the HeyLeads API (LinkedIn outreach): campaigns, leads, lists, inbox, webhooks. Standard library only."
+requires-python = ">=3.9"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = ["heyleads", "linkedin", "outreach", "api", "sdk"]
+readme = "README.md"
+dependencies = []
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Operating System :: OS Independent",
+  "Intended Audience :: Developers",
+]
+
+[project.urls]
+Homepage = "https://app.heyleads.so/developers"
+Documentation = "https://app.heyleads.so/developers"
+
+[tool.setuptools]
+packages = ["heyleads"]

heyleads-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

heyleads-1.0.0/tests/test_client.py

@@ -0,0 +1,243 @@
+"""Unit tests with a fake transport: paths, methods, bodies, query strings, error mapping, retries, paging, webhooks. Run: python3 -I -m unittest discover -s tests"""
+import hashlib
+import hmac
+import json
+import os
+import sys
+import unittest
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+
+from heyleads import HeyLeads, HeyLeadsError, SDK_OPERATIONS, construct_webhook_event, verify_webhook_signature  # noqa: E402
+
+KEY = "hl_live_" + "a" * 32
+BASE = "https://app.heylead.test"
+
+
+class Fake:
+    """Answers from a script of (status, headers, body) and records every request."""
+
+    def __init__(self, *script):
+        self.script = list(script)
+        self.calls = []
+
+    def __call__(self, method, url, headers, body, timeout):
+        self.calls.append({"method": method, "url": url, "headers": headers, "body": json.loads(body) if body else None, "timeout": timeout})
+        step = self.script.pop(0) if len(self.script) > 1 else self.script[0]
+        if isinstance(step, Exception):
+            raise step
+        status, headers, payload = step
+        return status, headers, (payload if isinstance(payload, bytes) else json.dumps(payload).encode())
+
+
+def ok(payload=None, status=200):
+    return (status, {}, payload if payload is not None else {})
+
+
+def err(status, code, message="no", extra=None, headers=None):
+    return (status, headers or {}, {"error": {"code": code, "message": message, "requestId": "req_1", **(extra or {})}})
+
+
+def client(*script, **kw):
+    fake = Fake(*(script or (ok(),)))
+    slept = []
+    hl = HeyLeads(api_key=KEY, base_url=BASE, transport=fake, sleep=slept.append, **kw)
+    return hl, fake, slept
+
+
+class Construction(unittest.TestCase):
+    def test_refuses_a_missing_or_malformed_key_and_a_missing_host(self):
+        with self.assertRaises(TypeError):
+            HeyLeads(api_key="", base_url=BASE)
+        with self.assertRaises(TypeError):
+            HeyLeads(api_key="sk-nope", base_url=BASE)
+        old = os.environ.pop("HEYLEAD_BASE_URL", None)
+        try:
+            with self.assertRaisesRegex(TypeError, "base_url"):
+                HeyLeads(api_key=KEY, base_url="app.heyleads.so")
+            self.assertTrue(HeyLeads(api_key=KEY)._root.startswith("https://app.heyleads.so/"))  # the hosted product by default
+        finally:
+            if old is not None:
+                os.environ["HEYLEAD_BASE_URL"] = old
+
+    def test_sends_the_key_a_user_agent_and_a_request_id_and_tolerates_a_trailing_slash(self):
+        fake = Fake(ok({"items": []}))
+        HeyLeads(api_key=KEY, base_url=BASE + "///", transport=fake).accounts.list()
+        c = fake.calls[0]
+        self.assertEqual(c["url"], f"{BASE}/api/v1/accounts")
+        self.assertEqual(c["headers"]["authorization"], f"Bearer {KEY}")
+        self.assertTrue(c["headers"]["user-agent"].startswith("heyleads-python/"))
+        self.assertEqual(len(c["headers"]["x-request-id"]), 36)
+
+
+class Requests(unittest.TestCase):
+    def test_paths_methods_bodies_and_query_strings(self):
+        hl, fake, _ = client(ok({"items": []}))
+        hl.accounts.list_actions("a/b", status="queued", limit=5)
+        self.assertEqual(fake.calls[-1]["url"], f"{BASE}/api/v1/accounts/a%2Fb/actions?status=queued&limit=5")
+        hl.campaigns.update("c1", {"name": "New"})
+        self.assertEqual((fake.calls[-1]["method"], fake.calls[-1]["body"]), ("PATCH", {"name": "New"}))
+        hl.leads.list(search="ada", do_not_contact=True, campaign_id="c1")
+        self.assertEqual(fake.calls[-1]["url"], f"{BASE}/api/v1/leads?search=ada&doNotContact=true&campaignId=c1")
+        hl.blacklist.add("lead", ["a@b.co"], dry_run=True)
+        self.assertEqual(fake.calls[-1]["body"], {"kind": "lead", "entries": ["a@b.co"], "dryRun": True})
+        hl.blacklist.add("lead", ["a@b.co"])
+        self.assertNotIn("dryRun", fake.calls[-1]["body"])
+        hl.lists.derive("exclude", ["A"], name="x", exclude_list_ids=["B"])
+        self.assertEqual(fake.calls[-1]["body"], {"name": "x", "operation": "exclude", "listIds": ["A"], "excludeListIds": ["B"]})
+        hl.accounts.set_tier("acc", "sales_navigator", sales_navigator="connected")
+        self.assertEqual((fake.calls[-1]["method"], fake.calls[-1]["body"]), ("PUT", {"tier": "sales_navigator", "salesNavigator": "connected"}))
+        hl.analytics.get(days=7, campaign_id="c")
+        self.assertEqual(fake.calls[-1]["url"], f"{BASE}/api/v1/analytics?days=7&campaignId=c")
+        hl.analytics.get(from_="2026-10-01", to="2026-10-07")
+        self.assertIn("from=2026-10-01&to=2026-10-07", fake.calls[-1]["url"])
+        hl.leads.lookup(profile_url="https://www.linkedin.com/in/ada")
+        self.assertIn("profileUrl=https%3A%2F%2Fwww.linkedin.com%2Fin%2Fada", fake.calls[-1]["url"])
+
+    def test_returns_the_unwrapped_pieces(self):
+        hl, _, _ = client(ok({"items": [{"id": "a"}]}))
+        self.assertEqual(hl.accounts.list(), [{"id": "a"}])
+        hl2, _, _ = client(ok({"tags": ["x"]}))
+        self.assertEqual(hl2.leads.set_tags("l", ["x"]), ["x"])
+        hl3, _, _ = client(ok({"customFields": {"k": "v"}}))
+        self.assertEqual(hl3.leads.set_custom_fields("l", set={"k": "v"}), {"k": "v"})
+
+    def test_204_is_none(self):
+        hl, fake, _ = client((204, {}, b""))
+        self.assertIsNone(hl.accounts.disconnect("a"))
+        self.assertEqual(fake.calls[0]["method"], "DELETE")
+
+    def test_queued_actions_carry_an_idempotency_key_yours_or_generated(self):
+        hl, fake, _ = client(ok({"id": "x"}, 201))
+        hl.accounts.send_message("a", "https://www.linkedin.com/in/ada", "Hi", idempotency_key="mine-1")
+        self.assertEqual(fake.calls[0]["headers"]["idempotency-key"], "mine-1")
+        self.assertEqual(fake.calls[0]["body"], {"profileUrl": "https://www.linkedin.com/in/ada", "text": "Hi"})
+        hl.accounts.visit_profile("a", "https://www.linkedin.com/in/ada", expires_in_seconds=60)
+        self.assertEqual(len(fake.calls[1]["headers"]["idempotency-key"]), 36)
+        self.assertEqual(fake.calls[1]["body"]["expiresInSeconds"], 60)
+
+    def test_paging_follows_the_cursor(self):
+        hl, fake, _ = client(ok({"items": [{"id": 1}, {"id": 2}], "nextCursor": "c2"}), ok({"items": [{"id": 3}], "nextCursor": None}))
+        self.assertEqual([x["id"] for x in hl.leads.iterate(status="active")], [1, 2, 3])
+        self.assertNotIn("cursor", fake.calls[0]["url"])
+        self.assertIn("cursor=c2", fake.calls[1]["url"])
+        self.assertIn("status=active", fake.calls[1]["url"])
+
+
+class Errors(unittest.TestCase):
+    def test_maps_the_error_envelope(self):
+        hl, _, _ = client(err(422, "invalid", "Give it a name.", {"fieldErrors": {"name": "Give it a name."}}))
+        with self.assertRaises(HeyLeadsError) as cm:
+            hl.lists.create("")
+        e = cm.exception
+        self.assertEqual((e.status, e.code, e.request_id, e.field_errors), (422, "invalid", "req_1", {"name": "Give it a name."}))
+        self.assertEqual(str(e), "Give it a name.")
+
+    def test_a_non_json_error_page_still_raises_something_readable(self):
+        hl, _, _ = client((502, {}, b"<html>Bad gateway</html>"), max_retries=0)
+        with self.assertRaises(HeyLeadsError) as cm:
+            hl.accounts.list()
+        self.assertEqual((cm.exception.status, cm.exception.code), (502, "http_error"))
+
+    def test_network_errors_and_timeouts_raise_with_status_zero(self):
+        hl, _, _ = client(ConnectionError("down"), max_retries=0)
+        with self.assertRaises(HeyLeadsError) as cm:
+            hl.accounts.list()
+        self.assertEqual((cm.exception.status, cm.exception.code), (0, "network_error"))
+        hl2, _, _ = client(TimeoutError("slow"), max_retries=0)
+        with self.assertRaises(HeyLeadsError) as cm2:
+            hl2.accounts.list()
+        self.assertEqual(cm2.exception.code, "timeout")
+
+
+class Retries(unittest.TestCase):
+    def test_a_429_is_waited_out_for_any_method_using_retry_after(self):
+        hl, fake, slept = client(err(429, "rate_limited", headers={"retry-after": "2"}, extra={"retryAfterSeconds": 2}), ok({"id": "c"}, 201))
+        self.assertEqual(hl.campaigns.create({"name": "x"}), {"id": "c"})
+        self.assertEqual(len(fake.calls), 2)
+        self.assertEqual(slept, [2.0])
+
+    def test_a_retry_after_longer_than_the_cap_raises_so_the_caller_decides(self):
+        hl, fake, _ = client(err(429, "rate_limited", extra={"retryAfterSeconds": 120}))
+        with self.assertRaises(HeyLeadsError) as cm:
+            hl.accounts.list()
+        self.assertEqual(cm.exception.retry_after_seconds, 120)
+        self.assertEqual(len(fake.calls), 1)
+
+    def test_a_503_is_retried_for_repeatable_requests_only(self):
+        hl, fake, _ = client(err(503, "x"), ok({"items": []}))
+        hl.accounts.list()
+        self.assertEqual(len(fake.calls), 2)
+        hl2, fake2, _ = client(err(503, "x"), ok({"id": "c"}))
+        with self.assertRaises(HeyLeadsError):
+            hl2.campaigns.create({"name": "x"})  # a POST that may have run is never repeated
+        self.assertEqual(len(fake2.calls), 1)
+
+    def test_a_queued_action_may_be_repeated_because_it_is_idempotent(self):
+        hl, fake, _ = client(ConnectionError("blip"), ok({"id": "a"}, 201))
+        hl.accounts.follow("acc", "https://www.linkedin.com/in/ada", idempotency_key="k")
+        self.assertEqual(len(fake.calls), 2)
+        self.assertEqual(fake.calls[0]["headers"]["idempotency-key"], fake.calls[1]["headers"]["idempotency-key"])
+
+    def test_retries_stop_at_max_retries_and_actions_disabled_is_never_retried(self):
+        hl, fake, _ = client(err(503, "x"), max_retries=1)
+        with self.assertRaises(HeyLeadsError):
+            hl.accounts.list()
+        self.assertEqual(len(fake.calls), 2)
+        hl2, fake2, _ = client(err(503, "actions_disabled"))
+        with self.assertRaises(HeyLeadsError):
+            hl2.accounts.list()
+        self.assertEqual(len(fake2.calls), 1)
+
+
+class ActionsWait(unittest.TestCase):
+    def test_polls_until_final_then_returns(self):
+        hl, fake, slept = client(ok({"status": "queued"}), ok({"status": "running"}), ok({"status": "succeeded"}))
+        self.assertEqual(hl.actions.wait("a", interval_seconds=1, timeout_seconds=60)["status"], "succeeded")
+        self.assertEqual(len(fake.calls), 3)
+        self.assertEqual(slept, [1, 1])
+
+    def test_gives_up_with_a_timeout_error(self):
+        hl, _, _ = client(ok({"status": "queued"}))
+        with self.assertRaises(HeyLeadsError) as cm:
+            hl.actions.wait("a", interval_seconds=10, timeout_seconds=5)
+        self.assertEqual(cm.exception.code, "timeout")
+
+
+class Webhooks(unittest.TestCase):
+    def sign(self, secret, t, body):
+        return f"t={t},v1=" + hmac.new(secret.encode(), f"{t}.{body}".encode(), hashlib.sha256).hexdigest()
+
+    def test_verifies_the_exact_body_and_rejects_everything_else(self):
+        body = '{"event":"lead.replied","data":{"id":"l"}}'
+        header = self.sign("whsec_x", 1_760_000_000, body)
+        self.assertTrue(verify_webhook_signature("whsec_x", header, body, now_seconds=1_760_000_100))
+        self.assertTrue(verify_webhook_signature("whsec_x", header, body.encode(), now_seconds=1_760_000_100))
+        self.assertFalse(verify_webhook_signature("whsec_x", header, body + " ", now_seconds=1_760_000_100))
+        self.assertFalse(verify_webhook_signature("whsec_other", header, body, now_seconds=1_760_000_100))
+        self.assertFalse(verify_webhook_signature("whsec_x", header, body, now_seconds=1_760_000_000 + 301))
+        self.assertFalse(verify_webhook_signature("whsec_x", header, body, now_seconds=1_760_000_000 - 301))
+        for bad in (None, "", "garbage", "t=abc,v1=00", "t=1760000000", "v1=00"):
+            self.assertFalse(verify_webhook_signature("whsec_x", bad, body, now_seconds=1_760_000_100), bad)
+
+    def test_construct_parses_only_after_verifying(self):
+        body = '{"event":"lead.replied","data":{"id":"l"}}'
+        header = self.sign("whsec_x", 1_760_000_000, body)
+        self.assertEqual(construct_webhook_event("whsec_x", header, body, now_seconds=1_760_000_001)["data"], {"id": "l"})
+        with self.assertRaises(ValueError):
+            construct_webhook_event("whsec_x", "t=1,v1=00", body, now_seconds=1)
+
+
+class Surface(unittest.TestCase):
+    def test_every_mapped_method_exists_on_the_client(self):
+        hl, _, _ = client()
+        for op, path in SDK_OPERATIONS.items():
+            obj = hl
+            for part in path.split("."):
+                obj = getattr(obj, part, None)
+                self.assertIsNotNone(obj, f"{op} -> {path}")
+            self.assertTrue(callable(obj), f"{op} -> {path}")
+
+
+if __name__ == "__main__":
+    unittest.main()