custfind 1.1.0__tar.gz

custfind-1.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Parevo
+
+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.

custfind-1.1.0/PKG-INFO

@@ -0,0 +1,84 @@
+Metadata-Version: 2.4
+Name: custfind
+Version: 1.1.0
+Summary: Official Python client for the Custfind API: lead searches, email outreach, CRM and webhooks.
+License: MIT
+Project-URL: Documentation, https://custfind.com/developers
+Project-URL: Source, https://github.com/parevo/custfind-python
+Project-URL: Issues, https://github.com/parevo/custfind-python/issues
+Keywords: custfind,leads,lead-generation,api,sdk
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# custfind
+
+Official Python client for the [Custfind API](https://custfind.com/developers): start lead searches, read scored leads, write and send emails, move deals and receive webhooks. Standard library only; Python 3.9+.
+
+```bash
+pip install custfind
+```
+
+```python
+from custfind import Custfind
+
+cf = Custfind()  # reads CUSTFIND_API_KEY
+
+search = cf.searches.create(
+    sector="Dental clinic",
+    location="Kadıköy, Istanbul",
+    limit=25,                        # caps the credits this search reserves
+    external_customer_id="acme-42",  # optional: bill your own customer
+)
+cf.searches.wait_for_completion(search["job_id"])
+for lead in cf.searches.all_leads(search["job_id"]):
+    print(lead["name"], lead.get("email"), lead.get("score"))
+```
+
+## Safe retries
+
+Every write is sent with an `Idempotency-Key` that stays the same across retries, and network errors, `429` (respecting `Retry-After`), `5xx` and `409 idempotency_in_progress` are retried up to `max_retries` (3). Any other `409` is final and raised at once. Every write method takes `idempotency_key=`. A timed-out search is never started twice. Pass your own key to make retries across restarts safe too:
+
+```python
+cf.searches.create(idempotency_key=f"search-{order_id}", sector="Dental clinic", location="Izmir", limit=50)
+```
+
+## Errors
+
+Failed calls raise `CustfindError` with `.status` and the API's `.code` (`api_requires_paid_plan`, `customer_limit_reached`, `insufficient_scope`, …).
+
+## Webhooks
+
+```python
+from flask import Flask, request, abort
+from custfind import verify_webhook, WebhookVerificationError
+
+@app.post("/webhooks/custfind")
+def custfind_webhook():
+    try:
+        event = verify_webhook(request.get_data(), request.headers.get("Custfind-Signature"), SECRET)
+    except WebhookVerificationError:
+        abort(400)
+    if event["type"] == "search.completed":
+        ...
+    return "", 200
+```
+
+## Resources
+
+`searches`, `leads`, `outreach`, `pipelines`, `deals`, `webhooks`, `customers`, `sender_accounts`, plus `me()`, `balance()` and `usage()`. See the [API reference](https://custfind.com/developers).
+
+## Contributing
+
+This repository is a read-only mirror of `sdks/python` in Custfind's main repository, updated on every release. Issues are welcome here; pull requests are read and ported by hand, then closed, since the next release overwrites this repository.
+
+## Developing
+
+```bash
+python -m unittest discover -s tests -t .
+```
+
+## Changelog
+
+- **1.1.0** — Only `409 idempotency_in_progress` is retried (a final 409 used to be retried until it gave up). Read timeouts and dropped connections are retried on Python 3.9 too. Every write takes `idempotency_key=`. `searches.leads`/`all_leads` take every lead filter; new `leads.all`. `outreach.send` takes an aware `datetime`; `outreach.rewrite` needs a tone or an instruction. Plain-text error bodies are kept in the message.

custfind-1.1.0/README.md

@@ -0,0 +1,70 @@
+# custfind
+
+Official Python client for the [Custfind API](https://custfind.com/developers): start lead searches, read scored leads, write and send emails, move deals and receive webhooks. Standard library only; Python 3.9+.
+
+```bash
+pip install custfind
+```
+
+```python
+from custfind import Custfind
+
+cf = Custfind()  # reads CUSTFIND_API_KEY
+
+search = cf.searches.create(
+    sector="Dental clinic",
+    location="Kadıköy, Istanbul",
+    limit=25,                        # caps the credits this search reserves
+    external_customer_id="acme-42",  # optional: bill your own customer
+)
+cf.searches.wait_for_completion(search["job_id"])
+for lead in cf.searches.all_leads(search["job_id"]):
+    print(lead["name"], lead.get("email"), lead.get("score"))
+```
+
+## Safe retries
+
+Every write is sent with an `Idempotency-Key` that stays the same across retries, and network errors, `429` (respecting `Retry-After`), `5xx` and `409 idempotency_in_progress` are retried up to `max_retries` (3). Any other `409` is final and raised at once. Every write method takes `idempotency_key=`. A timed-out search is never started twice. Pass your own key to make retries across restarts safe too:
+
+```python
+cf.searches.create(idempotency_key=f"search-{order_id}", sector="Dental clinic", location="Izmir", limit=50)
+```
+
+## Errors
+
+Failed calls raise `CustfindError` with `.status` and the API's `.code` (`api_requires_paid_plan`, `customer_limit_reached`, `insufficient_scope`, …).
+
+## Webhooks
+
+```python
+from flask import Flask, request, abort
+from custfind import verify_webhook, WebhookVerificationError
+
+@app.post("/webhooks/custfind")
+def custfind_webhook():
+    try:
+        event = verify_webhook(request.get_data(), request.headers.get("Custfind-Signature"), SECRET)
+    except WebhookVerificationError:
+        abort(400)
+    if event["type"] == "search.completed":
+        ...
+    return "", 200
+```
+
+## Resources
+
+`searches`, `leads`, `outreach`, `pipelines`, `deals`, `webhooks`, `customers`, `sender_accounts`, plus `me()`, `balance()` and `usage()`. See the [API reference](https://custfind.com/developers).
+
+## Contributing
+
+This repository is a read-only mirror of `sdks/python` in Custfind's main repository, updated on every release. Issues are welcome here; pull requests are read and ported by hand, then closed, since the next release overwrites this repository.
+
+## Developing
+
+```bash
+python -m unittest discover -s tests -t .
+```
+
+## Changelog
+
+- **1.1.0** — Only `409 idempotency_in_progress` is retried (a final 409 used to be retried until it gave up). Read timeouts and dropped connections are retried on Python 3.9 too. Every write takes `idempotency_key=`. `searches.leads`/`all_leads` take every lead filter; new `leads.all`. `outreach.send` takes an aware `datetime`; `outreach.rewrite` needs a tone or an instruction. Plain-text error bodies are kept in the message.

custfind-1.1.0/custfind/__init__.py

@@ -0,0 +1,6 @@
+"""Official Python client for the Custfind API."""
+
+from .client import Custfind, CustfindError, __version__
+from .webhooks import WebhookVerificationError, verify_webhook
+
+__all__ = ["Custfind", "CustfindError", "WebhookVerificationError", "verify_webhook"]

custfind-1.1.0/custfind/client.py

@@ -0,0 +1,334 @@
+import datetime
+import http.client
+import json
+import os
+import random
+import time
+import uuid
+from typing import Any, Callable, Dict, Iterator, List, Optional, Union
+from urllib import error, parse, request
+
+__version__ = "1.1.0"
+
+DEFAULT_BASE_URL = "https://api.custfind.com"
+FINAL_STATUSES = ("completed", "failed", "cancelled")
+
+
+class CustfindError(Exception):
+    """An error response from the Custfind API, or a request that never got one."""
+
+    def __init__(self, status: int, code: str, message: Optional[str] = None, retry_after: Optional[int] = None):
+        self.status = status  # 0 when there was no response
+        self.code = code
+        self.retry_after = retry_after
+        super().__init__(message or (f"Custfind API error {status}: {code}" if status else f"Custfind request failed: {code}"))
+
+
+def _q(value: str) -> str:
+    return parse.quote(str(value), safe="")
+
+
+class Custfind:
+    """The Custfind API client.
+
+    Every write carries an Idempotency-Key that stays the same across its
+    retries, so a retried search never starts twice or reserves credits twice.
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 30.0,
+        max_retries: int = 3,
+    ):
+        self.api_key = api_key or os.environ.get("CUSTFIND_API_KEY")
+        if not self.api_key:
+            raise ValueError("Custfind: pass api_key or set CUSTFIND_API_KEY")
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self.searches = Searches(self)
+        self.leads = Leads(self)
+        self.outreach = Outreach(self)
+        self.pipelines = Pipelines(self)
+        self.deals = Deals(self)
+        self.webhooks = Webhooks(self)
+        self.customers = Customers(self)
+        self.sender_accounts = SenderAccounts(self)
+
+    def me(self) -> Dict[str, Any]:
+        return self.request("GET", "/v1/me")
+
+    def balance(self) -> Dict[str, Any]:
+        return self.request("GET", "/v1/balance")
+
+    def usage(self, **params: Any) -> Dict[str, Any]:
+        """from, to, group_by ("customer" | "api_key" | "none"), external_customer_id."""
+        return self.request("GET", "/v1/usage", query=params)
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        query: Optional[Dict[str, Any]] = None,
+        body: Any = None,
+        idempotency_key: Optional[str] = None,
+    ) -> Any:
+        url = self.base_url + path
+        if query:
+            clean = {k: v for k, v in query.items() if v is not None and v != ""}
+            if clean:
+                url += "?" + parse.urlencode(clean)
+        headers = {
+            "Authorization": f"Bearer {self.api_key}",
+            "Accept": "application/json",
+            "User-Agent": f"custfind-python/{__version__}",
+        }
+        data = None
+        if body is not None:
+            headers["Content-Type"] = "application/json"
+            data = json.dumps(body).encode()
+        if method != "GET":
+            headers["Idempotency-Key"] = idempotency_key or str(uuid.uuid4())
+
+        attempt = 0
+        while True:
+            req = request.Request(url, data=data, method=method, headers=headers)
+            try:
+                with request.urlopen(req, timeout=self.timeout) as resp:
+                    raw = resp.read()
+                    if resp.status == 204 or not raw:
+                        return None
+                    return json.loads(raw)
+            except error.HTTPError as exc:
+                retry_after = _int(exc.headers.get("Retry-After"))
+                try:
+                    raw = exc.read() or b""
+                except (OSError, http.client.HTTPException):
+                    raw = b""
+                finally:
+                    exc.close()
+                code, detail = f"http_{exc.code}", None
+                try:
+                    payload = json.loads(raw)
+                    if isinstance(payload, dict):
+                        code = payload.get("error") or code
+                        detail = payload.get("detail")
+                except ValueError:
+                    # A few routes answer in plain text ("invalid json body").
+                    detail = raw.decode("utf-8", "replace").strip() or None
+                # A 409 is retried only while an earlier attempt of the same
+                # write is still running; any other 409 ("invalid job state")
+                # is final, and a retry would only get it replayed.
+                retryable = exc.code == 429 or exc.code >= 500 or (exc.code == 409 and code == "idempotency_in_progress")
+                if retryable and attempt < self.max_retries:
+                    time.sleep(retry_after if retry_after is not None else _backoff(attempt))
+                    attempt += 1
+                    continue
+                message = f"Custfind API error {exc.code}: {code} ({detail})" if detail else None
+                raise CustfindError(exc.code, code, message, retry_after=retry_after) from None
+            except (OSError, http.client.HTTPException) as exc:
+                # URLError, timeouts (socket.timeout is not a TimeoutError on
+                # 3.9), dropped connections and truncated responses.
+                if attempt < self.max_retries:
+                    time.sleep(_backoff(attempt))
+                    attempt += 1
+                    continue
+                raise CustfindError(0, str(getattr(exc, "reason", exc))) from None
+
+
+def _int(value: Optional[str]) -> Optional[int]:
+    try:
+        return int(value) if value is not None else None
+    except ValueError:
+        return None
+
+
+def _backoff(attempt: int) -> float:
+    return min(8.0, 0.5 * 2**attempt) + random.random() * 0.25
+
+
+def _paginate(fetch: Callable[[int], Dict[str, Any]], page_size: int) -> Iterator[Dict[str, Any]]:
+    page = 1
+    while True:
+        res = fetch(page)
+        items = res.get("items") or []
+        yield from items
+        if not items or page * page_size >= res.get("total", 0):
+            return
+        page += 1
+
+
+class _Resource:
+    def __init__(self, client: Custfind):
+        self._c = client
+
+
+class Searches(_Resource):
+    def create(self, idempotency_key: Optional[str] = None, **params: Any) -> Dict[str, Any]:
+        """sector, location, limit, external_customer_id, search_mode, country_code, … Set limit: it caps the credits reserved."""
+        return self._c.request("POST", "/v1/searches", body=params, idempotency_key=idempotency_key)
+
+    def get(self, search_id: str) -> Dict[str, Any]:
+        return self._c.request("GET", f"/v1/searches/{_q(search_id)}")
+
+    def list(self, limit: Optional[int] = None) -> List[Dict[str, Any]]:
+        return self._c.request("GET", "/v1/searches", query={"limit": limit})
+
+    def cancel(self, search_id: str, idempotency_key: Optional[str] = None) -> Dict[str, Any]:
+        return self._c.request("POST", f"/v1/searches/{_q(search_id)}/cancel", idempotency_key=idempotency_key)
+
+    def leads(self, search_id: str, page: int = 1, page_size: int = 25, **filters: Any) -> Dict[str, Any]:
+        """One page of a search's leads; takes the same filters as leads.list."""
+        filters.pop("job_id", None)
+        return self._c.request("GET", f"/v1/searches/{_q(search_id)}/leads", query={"page": page, "page_size": page_size, **filters})
+
+    def all_leads(self, search_id: str, page_size: int = 100, **filters: Any) -> Iterator[Dict[str, Any]]:
+        """Every lead of a search, page by page. Iterate a finished search: while one runs, new leads can shift the pages."""
+        return _paginate(lambda page: self.leads(search_id, page=page, page_size=page_size, **filters), page_size)
+
+    def wait_for_completion(self, search_id: str, interval: float = 3.0, timeout: float = 1800.0) -> Dict[str, Any]:
+        """Poll until the search completes, fails or is cancelled."""
+        deadline = time.monotonic() + timeout
+        while True:
+            search = self.get(search_id)
+            if search.get("status") in FINAL_STATUSES:
+                return search
+            if time.monotonic() + interval > deadline:
+                raise CustfindError(0, "wait_timeout", f"search {search_id} still {search.get('status')}")
+            time.sleep(interval)
+
+
+class Leads(_Resource):
+    def list(self, **params: Any) -> Dict[str, Any]:
+        """page, page_size (max 100), q, job_id, category, contact (email|phone|both|website|none),
+        min_score, max_score, min_rating, max_rating, region, language, source,
+        outreach_status (none|pending|sent|opened|failed), unsubscribed (yes|no), stage_id, tag_id,
+        sort (score_desc, rating_desc, created_asc, name, …; newest first when omitted)."""
+        return self._c.request("GET", "/v1/leads", query=params)
+
+    def all(self, page_size: int = 100, **filters: Any) -> Iterator[Dict[str, Any]]:
+        """Every lead matching the filters, page by page."""
+        filters.pop("page", None)
+        return _paginate(lambda page: self.list(page=page, page_size=page_size, **filters), page_size)
+
+    def get(self, lead_id: str) -> Dict[str, Any]:
+        """The lead with its enrichment, emails and calls: {"lead", "enrichment", "outreach", "calls"}."""
+        return self._c.request("GET", f"/v1/leads/{_q(lead_id)}")
+
+    def outreach(self, lead_id: str) -> List[Dict[str, Any]]:
+        return self._c.request("GET", f"/v1/leads/{_q(lead_id)}/outreach")
+
+    def write_draft(self, lead_id: str, regenerate: bool = False, idempotency_key: Optional[str] = None) -> List[Dict[str, Any]]:
+        """Write the lead's draft if missing; regenerate=True rewrites it (one AI edit)."""
+        return self._c.request("POST", f"/v1/leads/{_q(lead_id)}/outreach", body={"regenerate": regenerate}, idempotency_key=idempotency_key)
+
+    def crm(self, lead_id: str) -> Dict[str, Any]:
+        """The lead's deal, notes, tasks, tags, emails and meetings."""
+        return self._c.request("GET", f"/v1/leads/{_q(lead_id)}/crm")
+
+    def add_note(self, lead_id: str, body: str, idempotency_key: Optional[str] = None) -> Dict[str, Any]:
+        return self._c.request("POST", f"/v1/leads/{_q(lead_id)}/notes", body={"body": body}, idempotency_key=idempotency_key)
+
+
+class Outreach(_Resource):
+    def list(self, **params: Any) -> Dict[str, Any]:
+        """page, page_size, job_id, status (draft|scheduled|sent|failed), channel, q,
+        sort (created_at_asc|sent_at_desc|sent_at_asc|lead_name_asc|lead_name_desc|engagement_score_desc).
+        The result has "items", "total", "page", "page_size" and "stats"."""
+        return self._c.request("GET", "/v1/outreach", query=params)
+
+    def get(self, message_id: str) -> Dict[str, Any]:
+        return self._c.request("GET", f"/v1/outreach/{_q(message_id)}")
+
+    def update(self, message_id: str, message: str, email_subject: Optional[str] = None, idempotency_key: Optional[str] = None) -> Dict[str, Any]:
+        body: Dict[str, Any] = {"message": message}
+        if email_subject is not None:
+            body["email_subject"] = email_subject
+        return self._c.request("PATCH", f"/v1/outreach/{_q(message_id)}", body=body, idempotency_key=idempotency_key)
+
+    def rewrite(
+        self, message_id: str, tone: Optional[str] = None, instruction: Optional[str] = None, idempotency_key: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """Rewrite with AI by tone (professional|short|casual) or instruction; one AI edit, refunded on failure."""
+        if not tone and not instruction:
+            raise ValueError("Custfind: rewrite needs a tone or an instruction")
+        body = {k: v for k, v in {"tone": tone, "instruction": instruction}.items() if v}
+        return self._c.request("POST", f"/v1/outreach/{_q(message_id)}/rewrite", body=body, idempotency_key=idempotency_key)
+
+    def send(
+        self, message_id: str, scheduled_at: Union[str, datetime.datetime, None] = None, idempotency_key: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """Send now, or at scheduled_at (an aware datetime or an RFC 3339 string)."""
+        if isinstance(scheduled_at, datetime.datetime):
+            if scheduled_at.tzinfo is None:
+                raise ValueError("Custfind: scheduled_at needs a timezone")
+            scheduled_at = scheduled_at.astimezone(datetime.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+        body = {"scheduled_at": scheduled_at} if scheduled_at else {}
+        return self._c.request("POST", f"/v1/outreach/{_q(message_id)}/send", body=body, idempotency_key=idempotency_key)
+
+
+class Pipelines(_Resource):
+    def list(self) -> List[Dict[str, Any]]:
+        return self._c.request("GET", "/v1/pipelines")
+
+
+class Deals(_Resource):
+    def create(self, lead_id: str, idempotency_key: Optional[str] = None, **params: Any) -> Dict[str, Any]:
+        """stage_id, title, value_cents, currency, assigned_user_id. Without stage_id the deal starts in the default pipeline's first stage."""
+        return self._c.request("POST", "/v1/deals", body={"lead_id": lead_id, **params}, idempotency_key=idempotency_key)
+
+    def update(self, deal_id: str, idempotency_key: Optional[str] = None, **params: Any) -> Dict[str, Any]:
+        """stage_id, pipeline_id, title, value_cents, currency, assigned_user_id."""
+        return self._c.request("PATCH", f"/v1/deals/{_q(deal_id)}", body=params, idempotency_key=idempotency_key)
+
+
+class Webhooks(_Resource):
+    def create(self, url: str, events: List[str], description: str = "", idempotency_key: Optional[str] = None) -> Dict[str, Any]:
+        """Register an endpoint; the returned "secret" is shown only now."""
+        body = {"url": url, "events": events, "description": description}
+        return self._c.request("POST", "/v1/webhooks", body=body, idempotency_key=idempotency_key)
+
+    def list(self) -> List[Dict[str, Any]]:
+        return self._c.request("GET", "/v1/webhooks")
+
+    def update(self, endpoint_id: str, idempotency_key: Optional[str] = None, **params: Any) -> Dict[str, Any]:
+        """enabled, events, url, description."""
+        return self._c.request("PATCH", f"/v1/webhooks/{_q(endpoint_id)}", body=params, idempotency_key=idempotency_key)
+
+    def delete(self, endpoint_id: str, idempotency_key: Optional[str] = None) -> None:
+        self._c.request("DELETE", f"/v1/webhooks/{_q(endpoint_id)}", idempotency_key=idempotency_key)
+
+    def send_test(self, endpoint_id: str, idempotency_key: Optional[str] = None) -> Dict[str, Any]:
+        return self._c.request("POST", f"/v1/webhooks/{_q(endpoint_id)}/test", idempotency_key=idempotency_key)
+
+    def deliveries(self, endpoint_id: str, limit: Optional[int] = None) -> List[Dict[str, Any]]:
+        return self._c.request("GET", f"/v1/webhooks/{_q(endpoint_id)}/deliveries", query={"limit": limit})
+
+
+class Customers(_Resource):
+    def list(self) -> List[Dict[str, Any]]:
+        return self._c.request("GET", "/v1/customers")
+
+    def get(self, customer_id: str) -> Dict[str, Any]:
+        return self._c.request("GET", f"/v1/customers/{_q(customer_id)}")
+
+    def set_limit(self, customer_id: str, monthly_credits: int, idempotency_key: Optional[str] = None) -> Dict[str, Any]:
+        body = {"monthly_credits": monthly_credits}
+        return self._c.request("PUT", f"/v1/customers/{_q(customer_id)}/limit", body=body, idempotency_key=idempotency_key)
+
+    def remove_limit(self, customer_id: str, idempotency_key: Optional[str] = None) -> None:
+        self._c.request("DELETE", f"/v1/customers/{_q(customer_id)}/limit", idempotency_key=idempotency_key)
+
+
+class SenderAccounts(_Resource):
+    def list(self, external_customer_id: Optional[str] = None) -> List[Dict[str, Any]]:
+        return self._c.request("GET", "/v1/sender-accounts", query={"external_customer_id": external_customer_id})
+
+    def create(self, idempotency_key: Optional[str] = None, **params: Any) -> Dict[str, Any]:
+        """name, email, smtp_host, smtp_port, smtp_user, smtp_pass, external_customer_id (optional)."""
+        return self._c.request("POST", "/v1/sender-accounts", body=params, idempotency_key=idempotency_key)
+
+    def delete(self, account_id: str, idempotency_key: Optional[str] = None) -> None:
+        self._c.request("DELETE", f"/v1/sender-accounts/{_q(account_id)}", idempotency_key=idempotency_key)

custfind-1.1.0/custfind/webhooks.py

@@ -0,0 +1,42 @@
+import hashlib
+import hmac
+import json
+import time
+from typing import Any, Dict, Optional, Union
+
+
+class WebhookVerificationError(Exception):
+    """A webhook delivery that did not verify."""
+
+
+def verify_webhook(
+    raw_body: Union[bytes, str],
+    signature_header: Optional[str],
+    secret: str,
+    tolerance_seconds: int = 300,
+) -> Dict[str, Any]:
+    """Verify a delivery and return its event.
+
+    Pass the raw request body exactly as received (before JSON parsing), the
+    Custfind-Signature header and your endpoint's whsec_ secret.
+    """
+    body = raw_body.encode() if isinstance(raw_body, str) else raw_body
+    timestamp = 0
+    signatures = []
+    for part in (signature_header or "").split(","):
+        key, _, value = part.strip().partition("=")
+        if key == "t":
+            try:
+                timestamp = int(value)
+            except ValueError:
+                timestamp = 0
+        elif key == "v1" and value:
+            signatures.append(value)
+    if not timestamp or not signatures:
+        raise WebhookVerificationError("malformed Custfind-Signature header")
+    if abs(time.time() - timestamp) > tolerance_seconds:
+        raise WebhookVerificationError("timestamp outside tolerance")
+    expected = hmac.new(secret.encode(), f"{timestamp}.".encode() + body, hashlib.sha256).hexdigest()
+    if not any(hmac.compare_digest(expected, s) for s in signatures):
+        raise WebhookVerificationError("signature mismatch")
+    return json.loads(body)

custfind-1.1.0/custfind.egg-info/PKG-INFO

@@ -0,0 +1,84 @@
+Metadata-Version: 2.4
+Name: custfind
+Version: 1.1.0
+Summary: Official Python client for the Custfind API: lead searches, email outreach, CRM and webhooks.
+License: MIT
+Project-URL: Documentation, https://custfind.com/developers
+Project-URL: Source, https://github.com/parevo/custfind-python
+Project-URL: Issues, https://github.com/parevo/custfind-python/issues
+Keywords: custfind,leads,lead-generation,api,sdk
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# custfind
+
+Official Python client for the [Custfind API](https://custfind.com/developers): start lead searches, read scored leads, write and send emails, move deals and receive webhooks. Standard library only; Python 3.9+.
+
+```bash
+pip install custfind
+```
+
+```python
+from custfind import Custfind
+
+cf = Custfind()  # reads CUSTFIND_API_KEY
+
+search = cf.searches.create(
+    sector="Dental clinic",
+    location="Kadıköy, Istanbul",
+    limit=25,                        # caps the credits this search reserves
+    external_customer_id="acme-42",  # optional: bill your own customer
+)
+cf.searches.wait_for_completion(search["job_id"])
+for lead in cf.searches.all_leads(search["job_id"]):
+    print(lead["name"], lead.get("email"), lead.get("score"))
+```
+
+## Safe retries
+
+Every write is sent with an `Idempotency-Key` that stays the same across retries, and network errors, `429` (respecting `Retry-After`), `5xx` and `409 idempotency_in_progress` are retried up to `max_retries` (3). Any other `409` is final and raised at once. Every write method takes `idempotency_key=`. A timed-out search is never started twice. Pass your own key to make retries across restarts safe too:
+
+```python
+cf.searches.create(idempotency_key=f"search-{order_id}", sector="Dental clinic", location="Izmir", limit=50)
+```
+
+## Errors
+
+Failed calls raise `CustfindError` with `.status` and the API's `.code` (`api_requires_paid_plan`, `customer_limit_reached`, `insufficient_scope`, …).
+
+## Webhooks
+
+```python
+from flask import Flask, request, abort
+from custfind import verify_webhook, WebhookVerificationError
+
+@app.post("/webhooks/custfind")
+def custfind_webhook():
+    try:
+        event = verify_webhook(request.get_data(), request.headers.get("Custfind-Signature"), SECRET)
+    except WebhookVerificationError:
+        abort(400)
+    if event["type"] == "search.completed":
+        ...
+    return "", 200
+```
+
+## Resources
+
+`searches`, `leads`, `outreach`, `pipelines`, `deals`, `webhooks`, `customers`, `sender_accounts`, plus `me()`, `balance()` and `usage()`. See the [API reference](https://custfind.com/developers).
+
+## Contributing
+
+This repository is a read-only mirror of `sdks/python` in Custfind's main repository, updated on every release. Issues are welcome here; pull requests are read and ported by hand, then closed, since the next release overwrites this repository.
+
+## Developing
+
+```bash
+python -m unittest discover -s tests -t .
+```
+
+## Changelog
+
+- **1.1.0** — Only `409 idempotency_in_progress` is retried (a final 409 used to be retried until it gave up). Read timeouts and dropped connections are retried on Python 3.9 too. Every write takes `idempotency_key=`. `searches.leads`/`all_leads` take every lead filter; new `leads.all`. `outreach.send` takes an aware `datetime`; `outreach.rewrite` needs a tone or an instruction. Plain-text error bodies are kept in the message.

custfind-1.1.0/custfind.egg-info/SOURCES.txt

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

custfind-1.1.0/custfind.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

custfind-1.1.0/custfind.egg-info/top_level.txt

@@ -0,0 +1 @@
+custfind

custfind-1.1.0/pyproject.toml

@@ -0,0 +1,21 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "custfind"
+version = "1.1.0"
+description = "Official Python client for the Custfind API: lead searches, email outreach, CRM and webhooks."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.9"
+dependencies = []
+keywords = ["custfind", "leads", "lead-generation", "api", "sdk"]
+
+[project.urls]
+Documentation = "https://custfind.com/developers"
+Source = "https://github.com/parevo/custfind-python"
+Issues = "https://github.com/parevo/custfind-python/issues"
+
+[tool.setuptools]
+packages = ["custfind"]

custfind-1.1.0/setup.cfg

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

custfind-1.1.0/tests/test_client.py

@@ -0,0 +1,182 @@
+import datetime
+import hashlib
+import hmac
+import json
+import threading
+import time
+import unittest
+from http.server import BaseHTTPRequestHandler, HTTPServer
+
+from custfind import Custfind, CustfindError, WebhookVerificationError, verify_webhook
+
+
+class _Server:
+    def __init__(self, respond):
+        self.seen = []
+        outer = self
+
+        class Handler(BaseHTTPRequestHandler):
+            def _handle(self):
+                length = int(self.headers.get("Content-Length") or 0)
+                body = self.rfile.read(length).decode() if length else ""
+                outer.seen.append({"method": self.command, "path": self.path, "headers": dict(self.headers), "body": body})
+                status, payload, extra = respond(len(outer.seen))
+                self.send_response(status)
+                extra = dict(extra or {})
+                self.send_header("Content-Type", extra.pop("Content-Type", "application/json"))
+                for k, v in extra.items():
+                    self.send_header(k, v)
+                if payload is None:
+                    data = b""
+                elif isinstance(payload, str):
+                    data = payload.encode()
+                else:
+                    data = json.dumps(payload).encode()
+                self.send_header("Content-Length", str(len(data)))
+                self.end_headers()
+                self.wfile.write(data)
+
+            do_GET = do_POST = do_PUT = do_PATCH = do_DELETE = _handle
+
+            def log_message(self, *args):
+                pass
+
+        self.httpd = HTTPServer(("127.0.0.1", 0), Handler)
+        self.url = f"http://127.0.0.1:{self.httpd.server_address[1]}"
+        threading.Thread(target=self.httpd.serve_forever, daemon=True).start()
+
+    def close(self):
+        self.httpd.shutdown()
+
+
+class ClientTest(unittest.TestCase):
+    def test_request_shape(self):
+        s = _Server(lambda n: (202, {"job_id": "j1", "status": "queued"}, None))
+        cf = Custfind(api_key="cf_live_test", base_url=s.url)
+        res = cf.searches.create(sector="Dental clinic", location="Istanbul", limit=25)
+        self.assertEqual(res["job_id"], "j1")
+        first = s.seen[0]
+        self.assertEqual((first["method"], first["path"]), ("POST", "/v1/searches"))
+        self.assertEqual(first["headers"]["Authorization"], "Bearer cf_live_test")
+        self.assertTrue(first["headers"].get("Idempotency-Key"))
+        self.assertEqual(json.loads(first["body"]), {"sector": "Dental clinic", "location": "Istanbul", "limit": 25})
+        cf.leads.list(min_score=70, contact="email")
+        self.assertEqual(s.seen[1]["path"], "/v1/leads?min_score=70&contact=email")
+        self.assertNotIn("Idempotency-Key", s.seen[1]["headers"])
+        s.close()
+
+    def test_retries_keep_the_idempotency_key(self):
+        plan = {1: (503, {"error": "x"}, None), 2: (429, {"error": "rate_limited"}, {"Retry-After": "0"})}
+        s = _Server(lambda n: plan.get(n, (202, {"job_id": "j2"}, None)))
+        cf = Custfind(api_key="k", base_url=s.url, max_retries=3)
+        self.assertEqual(cf.searches.create(sector="x")["job_id"], "j2")
+        self.assertEqual(len(s.seen), 3)
+        self.assertEqual(len({r["headers"]["Idempotency-Key"] for r in s.seen}), 1)
+        s.close()
+
+    def test_error_code(self):
+        s = _Server(lambda n: (402, {"error": "customer_limit_reached"}, None))
+        cf = Custfind(api_key="k", base_url=s.url)
+        with self.assertRaises(CustfindError) as ctx:
+            cf.searches.create(sector="x", external_customer_id="acme")
+        self.assertEqual((ctx.exception.status, ctx.exception.code), (402, "customer_limit_reached"))
+        self.assertEqual(len(s.seen), 1)
+        s.close()
+
+    def test_path_encoding_and_204(self):
+        s = _Server(lambda n: (204, None, None))
+        cf = Custfind(api_key="k", base_url=s.url)
+        self.assertIsNone(cf.customers.remove_limit("acme/eu 1"))
+        self.assertEqual(s.seen[0]["path"], "/v1/customers/acme%2Feu%201/limit")
+        s.close()
+
+    def test_wait_for_completion(self):
+        statuses = ["queued", "processing", "completed"]
+        s = _Server(lambda n: (200, {"id": "j", "status": statuses[min(n - 1, 2)]}, None))
+        cf = Custfind(api_key="k", base_url=s.url)
+        self.assertEqual(cf.searches.wait_for_completion("j", interval=0.01)["status"], "completed")
+        self.assertEqual(len(s.seen), 3)
+        s.close()
+
+
+    def test_conflict_retried_only_while_in_progress(self):
+        plan = {
+            1: (409, {"error": "idempotency_in_progress"}, {"Retry-After": "0"}),
+            2: (200, {"id": "j"}, None),
+        }
+        s = _Server(lambda n: plan.get(n, (409, {"error": "invalid job state"}, None)))
+        cf = Custfind(api_key="k", base_url=s.url)
+        self.assertEqual(cf.searches.cancel("j")["id"], "j")
+        self.assertEqual(len(s.seen), 2)
+        self.assertEqual(s.seen[0]["headers"]["Idempotency-Key"], s.seen[1]["headers"]["Idempotency-Key"])
+        with self.assertRaises(CustfindError) as ctx:
+            cf.searches.cancel("j")
+        self.assertEqual((ctx.exception.status, ctx.exception.code), (409, "invalid job state"))
+        self.assertEqual(len(s.seen), 3, "a final 409 is not retried")
+        s.close()
+
+    def test_plain_text_error_is_kept(self):
+        s = _Server(lambda n: (400, "invalid json body\n", {"Content-Type": "text/plain"}))
+        cf = Custfind(api_key="k", base_url=s.url)
+        with self.assertRaises(CustfindError) as ctx:
+            cf.deals.create("lead-1", idempotency_key="deal-1")
+        self.assertEqual(ctx.exception.code, "http_400")
+        self.assertIn("invalid json body", str(ctx.exception))
+        self.assertEqual(s.seen[0]["headers"]["Idempotency-Key"], "deal-1")
+        s.close()
+
+    def test_network_error_is_retried_then_raised(self):
+        cf = Custfind(api_key="k", base_url="http://127.0.0.1:1", max_retries=1)
+        with self.assertRaises(CustfindError) as ctx:
+            cf.me()
+        self.assertEqual(ctx.exception.status, 0)
+
+    def test_all_leads_filters_and_pages(self):
+        pages = {1: {"items": [{"id": "a"}, {"id": "b"}], "total": 3}, 2: {"items": [{"id": "c"}], "total": 3}}
+        s = _Server(lambda n: (200, pages[n], None))
+        cf = Custfind(api_key="k", base_url=s.url)
+        ids = [lead["id"] for lead in cf.searches.all_leads("j1", page_size=2, min_score=60, sort="score_desc")]
+        self.assertEqual(ids, ["a", "b", "c"])
+        self.assertEqual(s.seen[1]["path"], "/v1/searches/j1/leads?page=2&page_size=2&min_score=60&sort=score_desc")
+        s.close()
+
+    def test_send_takes_an_aware_datetime(self):
+        s = _Server(lambda n: (202, {"id": "m"}, None))
+        cf = Custfind(api_key="k", base_url=s.url)
+        at = datetime.datetime(2026, 3, 1, 9, 0, tzinfo=datetime.timezone(datetime.timedelta(hours=3)))
+        cf.outreach.send("m", scheduled_at=at)
+        self.assertEqual(json.loads(s.seen[0]["body"]), {"scheduled_at": "2026-03-01T06:00:00Z"})
+        with self.assertRaises(ValueError):
+            cf.outreach.send("m", scheduled_at=datetime.datetime(2026, 3, 1, 9, 0))
+        with self.assertRaises(ValueError):
+            cf.outreach.rewrite("m")
+        self.assertEqual(len(s.seen), 1)
+        s.close()
+
+
+class WebhookTest(unittest.TestCase):
+    def test_verifies_a_signature_made_by_the_api(self):
+        # Signed by the API's shared.WebhookSignatureValue.
+        body = b'{"id":"evt_1","type":"search.completed","created_at":"2023-11-14T22:13:20Z","organization_id":"org_1","data":{"id":"job_1","status":"completed","leads_found":12}}'
+        header = "t=1700000000,v1=09714fde5144a52b4b8218ce4fbd186b9cb1fce94a75f5396bfbc54f6fbee486"
+        event = verify_webhook(body, header, "whsec_test", tolerance_seconds=10**10)
+        self.assertEqual(event["data"]["leads_found"], 12)
+
+    def test_verify(self):
+        secret = "whsec_test"
+        body = json.dumps({"id": "evt", "type": "search.completed", "data": {"id": "j"}}).encode()
+        t = int(time.time())
+        sig = hmac.new(secret.encode(), f"{t}.".encode() + body, hashlib.sha256).hexdigest()
+        self.assertEqual(verify_webhook(body, f"t={t},v1={sig}", secret)["type"], "search.completed")
+        for bad_body, header, key in [
+            (body + b" ", f"t={t},v1={sig}", secret),
+            (body, f"t={t},v1={sig}", "whsec_other"),
+            (body, f"t={t - 3600},v1={sig}", secret),
+            (body, "garbage", secret),
+        ]:
+            with self.assertRaises(WebhookVerificationError):
+                verify_webhook(bad_body, header, key)
+
+
+if __name__ == "__main__":
+    unittest.main()