generect 0.1.0__tar.gz

generect-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+node_modules/
+dist/
+__pycache__/
+*.pyc
+.pytest_cache/
+*.egg-info/

generect-0.1.0/PKG-INFO

@@ -0,0 +1,45 @@
+Metadata-Version: 2.4
+Name: generect
+Version: 0.1.0
+Summary: Official Python SDK for the Generect Live API
+Project-URL: Documentation, https://docs.generect.com
+Project-URL: Repository, https://github.com/generect/generect-sdks
+Author-email: Generect <support@generect.com>
+License-Expression: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Requires-Dist: httpx<1,>=0.24
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# generect (Python SDK)
+
+```bash
+pip install generect
+```
+
+```python
+from generect import Generect
+
+g = Generect(api_key="YOUR_API_TOKEN")  # or env GENERECT_API_KEY
+
+count = g.search.database_leads_count(job_titles=["marketing manager"], locations=["Germany"])
+leads = g.search.database_leads(job_titles=["marketing manager"], locations=["Germany"], per_page=10)
+print(len(leads.data), "leads for", leads.amount_charged, "USD")
+
+email = g.email.find(lead_id=leads.data[0]["id"])   # billed only if a valid email is found
+
+job = g.enrich.database_leads_bulk(items=[{"linkedin_url": u} for u in urls])  # ≤50 items
+done = g.enrich.wait_leads_bulk(job.job_id)          # polls until completed / error
+```
+
+- Automatic retries with exponential backoff on `429`/`5xx` (configurable `max_retries`).
+- Typed errors: `InsufficientBalanceError` (402), `RateLimitError` (429), `AuthenticationError` (401)…
+- Every response exposes its real USD cost: `resp.amount_charged`.
+- Any endpoint, even future ones: `g.request("POST", "/search/database/leads/", json={...})`.
+
+Docs: https://docs.generect.com · Errors: https://docs.generect.com/api-reference/errors

generect-0.1.0/README.md

@@ -0,0 +1,27 @@
+# generect (Python SDK)
+
+```bash
+pip install generect
+```
+
+```python
+from generect import Generect
+
+g = Generect(api_key="YOUR_API_TOKEN")  # or env GENERECT_API_KEY
+
+count = g.search.database_leads_count(job_titles=["marketing manager"], locations=["Germany"])
+leads = g.search.database_leads(job_titles=["marketing manager"], locations=["Germany"], per_page=10)
+print(len(leads.data), "leads for", leads.amount_charged, "USD")
+
+email = g.email.find(lead_id=leads.data[0]["id"])   # billed only if a valid email is found
+
+job = g.enrich.database_leads_bulk(items=[{"linkedin_url": u} for u in urls])  # ≤50 items
+done = g.enrich.wait_leads_bulk(job.job_id)          # polls until completed / error
+```
+
+- Automatic retries with exponential backoff on `429`/`5xx` (configurable `max_retries`).
+- Typed errors: `InsufficientBalanceError` (402), `RateLimitError` (429), `AuthenticationError` (401)…
+- Every response exposes its real USD cost: `resp.amount_charged`.
+- Any endpoint, even future ones: `g.request("POST", "/search/database/leads/", json={...})`.
+
+Docs: https://docs.generect.com · Errors: https://docs.generect.com/api-reference/errors

generect-0.1.0/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "generect"
+version = "0.1.0"
+description = "Official Python SDK for the Generect Live API"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+authors = [{ name = "Generect", email = "support@generect.com" }]
+dependencies = ["httpx>=0.24,<1"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+[project.urls]
+Documentation = "https://docs.generect.com"
+Repository = "https://github.com/generect/generect-sdks"
+
+[project.optional-dependencies]
+dev = ["pytest>=7"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/generect"]

generect-0.1.0/src/generect/__init__.py

@@ -0,0 +1,22 @@
+from .client import ApiResponse, Generect
+from .errors import (
+    APIError,
+    AuthenticationError,
+    BadRequestError,
+    ForbiddenError,
+    GenerectError,
+    InsufficientBalanceError,
+    JobFailedError,
+    JobTimeoutError,
+    NotFoundError,
+    RateLimitError,
+    ServerError,
+)
+
+__version__ = "0.1.0"
+__all__ = [
+    "Generect", "ApiResponse", "GenerectError", "APIError", "BadRequestError",
+    "AuthenticationError", "InsufficientBalanceError", "ForbiddenError",
+    "NotFoundError", "RateLimitError", "ServerError", "JobFailedError",
+    "JobTimeoutError", "__version__",
+]

generect-0.1.0/src/generect/client.py

@@ -0,0 +1,332 @@
+"""Thin, dependency-light client for the Generect Live API.
+
+Design notes
+------------
+- Every method mirrors one documented endpoint 1:1 (paths pinned to the
+  OpenAPI spec in ``openapi/openapi.yaml``); filters are passed as keyword
+  arguments and sent verbatim, so new API fields work without an SDK update.
+- Responses come back as :class:`ApiResponse` — a ``dict`` of the raw body
+  with ``.data``, ``.meta`` and ``.amount_charged`` conveniences.
+- ``429`` and ``5xx`` are retried with exponential backoff + jitter;
+  other ``4xx`` raise immediately (the request itself must change).
+- Bulk endpoints return a job; ``wait()`` helpers poll until
+  ``completed`` / ``error`` (see docs: data stays null until completed).
+"""
+
+from __future__ import annotations
+
+import os
+import random
+import time
+from typing import Any, Optional
+
+import httpx
+
+from .errors import JobFailedError, JobTimeoutError, error_for
+
+DEFAULT_BASE_URL = "https://api.generect.com/api/v1"
+_TERMINAL_OK = "completed"
+_TERMINAL_FAIL = ("error", "failed")
+
+
+class ApiResponse(dict):
+    """Raw response body with typed accessors for the ``data``/``meta`` envelope."""
+
+    @property
+    def data(self) -> Any:
+        return self.get("data")
+
+    @property
+    def meta(self) -> dict:
+        return self.get("meta") or {}
+
+    @property
+    def amount_charged(self) -> Optional[float]:
+        """Real USD cost of this call, as billed (``meta.amount_charged``)."""
+        return self.meta.get("amount_charged")
+
+    @property
+    def job_id(self) -> Optional[str]:
+        return self.meta.get("job_id") or self.get("job_id")
+
+    @property
+    def status(self) -> Optional[str]:
+        return self.meta.get("status") or self.get("status")
+
+
+class Generect:
+    """Synchronous Generect API client.
+
+    >>> g = Generect(api_key="...")          # or env GENERECT_API_KEY
+    >>> g.search.database_leads(job_titles=["cto"], locations=["Germany"], per_page=5)
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 300.0,
+        max_retries: int = 3,
+        backoff_base: float = 1.0,
+        backoff_cap: float = 30.0,
+        transport: Optional[httpx.BaseTransport] = None,
+    ):
+        api_key = api_key or os.environ.get("GENERECT_API_KEY")
+        if not api_key:
+            raise ValueError("api_key is required (or set GENERECT_API_KEY)")
+        self._max_retries = max_retries
+        self._backoff_base = backoff_base
+        self._backoff_cap = backoff_cap
+        self._http = httpx.Client(
+            base_url=base_url.rstrip("/"),
+            timeout=httpx.Timeout(timeout, connect=10.0),
+            headers={
+                "Authorization": f"Token {api_key}",
+                "User-Agent": "generect-python/0.1.0",
+            },
+            transport=transport,
+        )
+        self.search = _Search(self)
+        self.enrich = _Enrich(self)
+        self.email = _Email(self)
+        self.phone = _Phone(self)
+        self.preview = _Preview(self)
+        self.accounts = _Accounts(self)
+        self.webhooks = _Webhooks(self)
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> "Generect":
+        return self
+
+    def __exit__(self, *exc) -> None:
+        self.close()
+
+    # -- core ---------------------------------------------------------------
+
+    def request(self, method: str, path: str, json: Optional[dict] = None,
+                params: Optional[dict] = None) -> ApiResponse:
+        """Escape hatch: call any endpoint. ``path`` must end with ``/``."""
+        if json is not None:
+            json = {k: v for k, v in json.items() if v is not None}
+        attempt = 0
+        while True:
+            try:
+                resp = self._http.request(method, path, json=json, params=params)
+            except httpx.TransportError:
+                if attempt >= self._max_retries:
+                    raise
+                self._sleep(attempt, None)
+                attempt += 1
+                continue
+            if resp.status_code < 400:
+                try:
+                    body = resp.json()
+                except ValueError:
+                    body = {}
+                return ApiResponse(body if isinstance(body, dict) else {"data": body})
+            retryable = resp.status_code == 429 or resp.status_code >= 500
+            if retryable and attempt < self._max_retries:
+                self._sleep(attempt, resp.headers.get("Retry-After"))
+                attempt += 1
+                continue
+            try:
+                body = resp.json()
+            except ValueError:
+                body = {}
+            detail = body.get("detail") if isinstance(body, dict) else None
+            raise error_for(resp.status_code, detail, body if isinstance(body, dict) else None)
+
+    def _sleep(self, attempt: int, retry_after: Optional[str]) -> None:
+        if retry_after:
+            try:
+                time.sleep(min(float(retry_after), self._backoff_cap))
+                return
+            except ValueError:
+                pass
+        delay = min(self._backoff_base * (2 ** attempt), self._backoff_cap)
+        time.sleep(delay + random.uniform(0, delay / 4))
+
+    def _wait_job(self, poll_path: str, job_id: str, *, wait_timeout: float,
+                  poll_interval: float) -> ApiResponse:
+        deadline = time.monotonic() + wait_timeout
+        interval = poll_interval
+        while True:
+            body = self.request("GET", poll_path)
+            status = body.status
+            if status == _TERMINAL_OK:
+                return body
+            if status in _TERMINAL_FAIL:
+                raise JobFailedError(job_id, body)
+            if time.monotonic() >= deadline:
+                raise JobTimeoutError(f"job {job_id} still '{status}' after {wait_timeout}s")
+            time.sleep(interval)
+            interval = min(interval * 1.5, 10.0)
+
+
+class _Namespace:
+    def __init__(self, client: Generect):
+        self._c = client
+
+
+class _Search(_Namespace):
+    """POST /search/{database|realtime}/... — database counts are free,
+    realtime counts are billed (see docs: Database vs Real-time)."""
+
+    def database_leads(self, **filters) -> ApiResponse:
+        return self._c.request("POST", "/search/database/leads/", json=filters)
+
+    def database_leads_count(self, **filters) -> ApiResponse:
+        return self._c.request("POST", "/search/database/leads/count/", json=filters)
+
+    def realtime_leads(self, **filters) -> ApiResponse:
+        return self._c.request("POST", "/search/realtime/leads/", json=filters)
+
+    def realtime_leads_count(self, **filters) -> ApiResponse:
+        return self._c.request("POST", "/search/realtime/leads/count/", json=filters)
+
+    def database_companies(self, **filters) -> ApiResponse:
+        return self._c.request("POST", "/search/database/companies/", json=filters)
+
+    def database_companies_count(self, **filters) -> ApiResponse:
+        return self._c.request("POST", "/search/database/companies/count/", json=filters)
+
+    def realtime_companies(self, **filters) -> ApiResponse:
+        return self._c.request("POST", "/search/realtime/companies/", json=filters)
+
+    def realtime_companies_count(self, **filters) -> ApiResponse:
+        return self._c.request("POST", "/search/realtime/companies/count/", json=filters)
+
+    def database_company_leads(self, **filters) -> ApiResponse:
+        return self._c.request("POST", "/search/database/company-leads/", json=filters)
+
+    def database_company_leads_count(self, **filters) -> ApiResponse:
+        return self._c.request("POST", "/search/database/company-leads/count/", json=filters)
+
+    def realtime_company_leads(self, **filters) -> ApiResponse:
+        return self._c.request("POST", "/search/realtime/company-leads/", json=filters)
+
+
+class _Enrich(_Namespace):
+    """POST /enrich/... — No Data No Charge: a not-found enrich is free."""
+
+    def database_lead(self, **kwargs) -> ApiResponse:
+        return self._c.request("POST", "/enrich/database/lead/", json=kwargs)
+
+    def realtime_lead(self, **kwargs) -> ApiResponse:
+        return self._c.request("POST", "/enrich/realtime/lead/", json=kwargs)
+
+    def database_company(self, **kwargs) -> ApiResponse:
+        return self._c.request("POST", "/enrich/database/company/", json=kwargs)
+
+    def realtime_company(self, **kwargs) -> ApiResponse:
+        return self._c.request("POST", "/enrich/realtime/company/", json=kwargs)
+
+    # bulk (max 50 items per request)
+    def database_leads_bulk(self, items: list, **kwargs) -> ApiResponse:
+        return self._c.request("POST", "/enrich/database/leads/bulk/", json={"items": items, **kwargs})
+
+    def realtime_leads_bulk(self, items: list, **kwargs) -> ApiResponse:
+        return self._c.request("POST", "/enrich/realtime/leads/bulk/", json={"items": items, **kwargs})
+
+    def database_companies_bulk(self, items: list, **kwargs) -> ApiResponse:
+        return self._c.request("POST", "/enrich/database/companies/bulk/", json={"items": items, **kwargs})
+
+    def realtime_companies_bulk(self, items: list, **kwargs) -> ApiResponse:
+        return self._c.request("POST", "/enrich/realtime/companies/bulk/", json={"items": items, **kwargs})
+
+    def leads_bulk_status(self, job_id: str) -> ApiResponse:
+        return self._c.request("GET", f"/enrich/leads/bulk/{job_id}/")
+
+    def companies_bulk_status(self, job_id: str) -> ApiResponse:
+        return self._c.request("GET", f"/enrich/companies/bulk/{job_id}/")
+
+    def wait_leads_bulk(self, job_id: str, *, wait_timeout: float = 600.0,
+                        poll_interval: float = 2.0) -> ApiResponse:
+        return self._c._wait_job(f"/enrich/leads/bulk/{job_id}/", job_id,
+                                 wait_timeout=wait_timeout, poll_interval=poll_interval)
+
+    def wait_companies_bulk(self, job_id: str, *, wait_timeout: float = 600.0,
+                            poll_interval: float = 2.0) -> ApiResponse:
+        return self._c._wait_job(f"/enrich/companies/bulk/{job_id}/", job_id,
+                                 wait_timeout=wait_timeout, poll_interval=poll_interval)
+
+
+class _Email(_Namespace):
+    """Email Finder bills only valid found emails; validation bills per email."""
+
+    def find(self, **kwargs) -> ApiResponse:
+        return self._c.request("POST", "/email/find/", json=kwargs)
+
+    def find_bulk(self, leads: list, **kwargs) -> ApiResponse:
+        return self._c.request("POST", "/email/find/bulk/", json={"leads": leads, **kwargs})
+
+    def find_bulk_status(self, job_id: str) -> ApiResponse:
+        return self._c.request("GET", f"/email/find/bulk/{job_id}/")
+
+    def wait_find_bulk(self, job_id: str, *, wait_timeout: float = 600.0,
+                       poll_interval: float = 2.0) -> ApiResponse:
+        return self._c._wait_job(f"/email/find/bulk/{job_id}/", job_id,
+                                 wait_timeout=wait_timeout, poll_interval=poll_interval)
+
+    def validate(self, emails: list, **kwargs) -> ApiResponse:
+        return self._c.request("POST", "/email/validate/", json={"emails": emails, **kwargs})
+
+
+class _Phone(_Namespace):
+    """Phone Finder — billed per found phone only."""
+
+    def find(self, **kwargs) -> ApiResponse:
+        return self._c.request("POST", "/phone/find/", json=kwargs)
+
+    def find_bulk(self, leads: list, **kwargs) -> ApiResponse:
+        return self._c.request("POST", "/phone/find/bulk/", json={"leads": leads, **kwargs})
+
+    def find_bulk_status(self, job_id: str) -> ApiResponse:
+        return self._c.request("GET", f"/phone/find/bulk/{job_id}/")
+
+    def wait_find_bulk(self, job_id: str, *, wait_timeout: float = 600.0,
+                       poll_interval: float = 2.0) -> ApiResponse:
+        return self._c._wait_job(f"/phone/find/bulk/{job_id}/", job_id,
+                                 wait_timeout=wait_timeout, poll_interval=poll_interval)
+
+
+class _Preview(_Namespace):
+    def leads(self, **filters) -> ApiResponse:
+        return self._c.request("POST", "/preview/leads/", json=filters)
+
+    def leads_count(self, **filters) -> ApiResponse:
+        return self._c.request("POST", "/preview/leads/count/", json=filters)
+
+
+class _Accounts(_Namespace):
+    def me(self) -> ApiResponse:
+        return self._c.request("GET", "/accounts/me/")
+
+    def usage(self, **params) -> ApiResponse:
+        return self._c.request("GET", "/accounts/usage/", params=params or None)
+
+    def transactions(self, **params) -> ApiResponse:
+        return self._c.request("GET", "/accounts/transactions/", params=params or None)
+
+
+class _Webhooks(_Namespace):
+    def list(self) -> ApiResponse:
+        return self._c.request("GET", "/webhooks/")
+
+    def create(self, **kwargs) -> ApiResponse:
+        return self._c.request("POST", "/webhooks/", json=kwargs)
+
+    def get(self, webhook_id: str) -> ApiResponse:
+        return self._c.request("GET", f"/webhooks/{webhook_id}/")
+
+    def update(self, webhook_id: str, **kwargs) -> ApiResponse:
+        return self._c.request("PATCH", f"/webhooks/{webhook_id}/", json=kwargs)
+
+    def delete(self, webhook_id: str) -> ApiResponse:
+        return self._c.request("DELETE", f"/webhooks/{webhook_id}/")
+
+    def test(self, webhook_id: str) -> ApiResponse:
+        return self._c.request("POST", f"/webhooks/{webhook_id}/test/")

generect-0.1.0/src/generect/errors.py

@@ -0,0 +1,81 @@
+"""Exception hierarchy mirroring the Generect API error envelope.
+
+Every API error is `{"status": "error", "status_code": <int>, "detail": <str|dict>}`
+(see https://docs.generect.com/api-reference/errors). The client raises the most
+specific subclass for the HTTP status and keeps the parsed body on the exception.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+
+class GenerectError(Exception):
+    """Base class for all SDK errors."""
+
+
+class APIError(GenerectError):
+    """An HTTP error response from the API."""
+
+    def __init__(self, status_code: int, detail: Any = None, body: Optional[dict] = None):
+        self.status_code = status_code
+        self.detail = detail
+        self.body = body or {}
+        super().__init__(f"HTTP {status_code}: {detail}")
+
+
+class BadRequestError(APIError):
+    """400 — invalid parameters, or a lookup that matched no record."""
+
+
+class AuthenticationError(APIError):
+    """401 — missing or invalid API token (remember the `Token ` prefix)."""
+
+
+class InsufficientBalanceError(APIError):
+    """402 — balance too low; top up or enable auto top-up."""
+
+
+class ForbiddenError(APIError):
+    """403 — the account or key is not entitled to this endpoint."""
+
+
+class NotFoundError(APIError):
+    """404 — resource does not exist (e.g. lead not found by email, expired job)."""
+
+
+class RateLimitError(APIError):
+    """429 — parallel-request or capacity limit hit; the client retries these
+    automatically with exponential backoff before raising."""
+
+
+class ServerError(APIError):
+    """5xx — transient server failure; retried automatically before raising."""
+
+
+class JobFailedError(GenerectError):
+    """A bulk job finished with status ``error``."""
+
+    def __init__(self, job_id: str, body: Optional[dict] = None):
+        self.job_id = job_id
+        self.body = body or {}
+        super().__init__(f"Bulk job {job_id} finished with status 'error'")
+
+
+class JobTimeoutError(GenerectError):
+    """A bulk job did not finish within ``wait_timeout`` seconds."""
+
+
+ERROR_BY_STATUS = {
+    400: BadRequestError,
+    401: AuthenticationError,
+    402: InsufficientBalanceError,
+    403: ForbiddenError,
+    404: NotFoundError,
+    429: RateLimitError,
+}
+
+
+def error_for(status_code: int, detail: Any, body: Optional[dict]) -> APIError:
+    cls = ERROR_BY_STATUS.get(status_code, ServerError if status_code >= 500 else APIError)
+    return cls(status_code, detail, body)

generect-0.1.0/tests/test_client.py

@@ -0,0 +1,102 @@
+"""Core behavior: auth header, retries, error mapping, envelope accessors, job polling."""
+
+import httpx
+import pytest
+
+from generect import (
+    Generect,
+    InsufficientBalanceError,
+    JobFailedError,
+    RateLimitError,
+)
+
+
+def make_client(handler, **kw):
+    kw.setdefault("backoff_base", 0.0)  # no real sleeping in tests
+    return Generect(api_key="test-key", transport=httpx.MockTransport(handler), **kw)
+
+
+def test_sends_token_auth_and_correct_url():
+    seen = {}
+
+    def handler(request):
+        seen["auth"] = request.headers["Authorization"]
+        seen["url"] = str(request.url)
+        seen["json"] = request.read()
+        return httpx.Response(200, json={"data": [], "meta": {"amount_charged": 0.0}})
+
+    g = make_client(handler)
+    g.search.database_leads(job_titles=["cto"], locations=None, per_page=5)
+    assert seen["auth"] == "Token test-key"
+    assert seen["url"] == "https://api.generect.com/api/v1/search/database/leads/"
+    assert b"locations" not in seen["json"]  # None fields dropped
+    assert b"job_titles" in seen["json"]
+
+
+def test_retries_429_then_succeeds():
+    calls = {"n": 0}
+
+    def handler(request):
+        calls["n"] += 1
+        if calls["n"] == 1:
+            return httpx.Response(429, json={"status": "error", "status_code": 429,
+                                             "detail": "Too Many Requests"})
+        return httpx.Response(200, json={"data": [{"id": "x"}], "meta": {"amount_charged": 0.0067}})
+
+    g = make_client(handler)
+    resp = g.search.database_leads(job_titles=["cto"])
+    assert calls["n"] == 2
+    assert resp.data == [{"id": "x"}]
+    assert resp.amount_charged == 0.0067
+
+
+def test_429_raises_after_retries_exhausted():
+    def handler(request):
+        return httpx.Response(429, json={"status": "error", "status_code": 429,
+                                         "detail": "Too Many Requests"})
+
+    g = make_client(handler, max_retries=1)
+    with pytest.raises(RateLimitError) as e:
+        g.enrich.realtime_lead(linkedin_url="https://linkedin.com/in/x")
+    assert e.value.status_code == 429
+
+
+def test_402_maps_to_insufficient_balance_and_no_retry():
+    calls = {"n": 0}
+
+    def handler(request):
+        calls["n"] += 1
+        return httpx.Response(402, json={"status": "error", "status_code": 402,
+                                         "detail": "Insufficient funds in the account."})
+
+    g = make_client(handler)
+    with pytest.raises(InsufficientBalanceError) as e:
+        g.email.find(lead_id="abc")
+    assert calls["n"] == 1  # 4xx (non-429) must not retry
+    assert "Insufficient funds" in str(e.value.detail)
+
+
+def test_wait_bulk_polls_until_completed():
+    states = iter([
+        {"data": None, "meta": {"status": "pending"}},
+        {"data": None, "meta": {"status": "processing"}},
+        {"data": [{"valid_email": "a@b.co"}], "meta": {"status": "completed", "amount_charged": 0.02}},
+    ])
+
+    def handler(request):
+        assert str(request.url).endswith("/email/find/bulk/j1/")
+        return httpx.Response(200, json=next(states))
+
+    g = make_client(handler)
+    resp = g.email.wait_find_bulk("j1", wait_timeout=5, poll_interval=0.0)
+    assert resp.status == "completed"
+    assert resp.data[0]["valid_email"] == "a@b.co"
+
+
+def test_wait_bulk_raises_on_error_status():
+    def handler(request):
+        return httpx.Response(200, json={"data": None, "meta": {"status": "error"}})
+
+    g = make_client(handler)
+    with pytest.raises(JobFailedError):
+        g.enrich.wait_leads_bulk("j2", wait_timeout=5, poll_interval=0.0)