easydata-api 1.0.1__py3-none-any.whl

easydata_api/__init__.py

@@ -0,0 +1,79 @@
+"""EasyData - LinkedIn data enrichment.
+
+    from easydata_api import EasyData
+
+    ed = EasyData()  # reads EASYDATA_API_KEY
+
+    # One record, in this call, at twice the credits.
+    r = ed.profiles_enrich.sync("https://linkedin.com/in/satyanadella")
+    print(r.result.data["full_name"])
+
+    # A batch of any size, streamed as it drains.
+    batch = ed.profiles_enrich(urls, external_id="crm-sync")
+    for entry in ed.results(batch.batch_id):
+        if entry.ok:
+            save(entry.data)
+
+Everything is a batch, including a batch of one, and you are billed per record
+that resolves: a failure costs nothing.
+"""
+
+from .client import (
+    DEFAULT_BASE_URL,
+    OPERATIONS,
+    Batch,
+    EasyData,
+    RateLimits,
+    ResultEntry,
+    ResultsPage,
+    SyncResult,
+)
+from .errors import (
+    CapacityUnavailable,
+    Conflict,
+    EasyDataError,
+    EmailUnverified,
+    InternalError,
+    InvalidAPIKey,
+    InvalidRequest,
+    NotFound,
+    NotImplementedYet,
+    QuotaExhausted,
+    RateLimited,
+    TransportError,
+    UnprocessableTarget,
+    UpstreamTimeout,
+)
+from .webhooks import Delivery, VerificationError, verify, verify_ed25519
+
+__version__ = "1.0.1"
+
+__all__ = [
+    "EasyData",
+    "Batch",
+    "ResultEntry",
+    "ResultsPage",
+    "SyncResult",
+    "RateLimits",
+    "OPERATIONS",
+    "DEFAULT_BASE_URL",
+    "EasyDataError",
+    "InvalidRequest",
+    "InvalidAPIKey",
+    "QuotaExhausted",
+    "EmailUnverified",
+    "NotFound",
+    "Conflict",
+    "UnprocessableTarget",
+    "RateLimited",
+    "NotImplementedYet",
+    "InternalError",
+    "UpstreamTimeout",
+    "CapacityUnavailable",
+    "TransportError",
+    "verify",
+    "verify_ed25519",
+    "Delivery",
+    "VerificationError",
+    "__version__",
+]

easydata_api/client.py

@@ -0,0 +1,642 @@
+"""The EasyData client.
+
+Zero dependencies, on purpose. It is one HTTP call shape against one envelope,
+and a data-enrichment script is the last place anyone wants a transitive
+dependency tree - so this is `urllib` and nothing else. Ed25519 webhook
+verification is the single exception and is an optional extra; the HMAC scheme
+is in the standard library and always available.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import random
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+import uuid
+from dataclasses import dataclass, field
+from typing import Any, Iterator, Mapping, Sequence
+
+from .errors import EasyDataError, RateLimited, TransportError, error_for
+
+__all__ = [
+    "EasyData",
+    "Batch",
+    "ResultEntry",
+    "ResultsPage",
+    "SyncResult",
+    "RateLimits",
+    "OPERATIONS",
+]
+
+DEFAULT_BASE_URL = "https://api.easydata.win/v1"
+
+#: Every operation, as `attribute name -> path`. The client builds one method
+#: per entry rather than defining nine near-identical methods, because they ARE
+#: identical: one request shape, one response shape, and the operation is the
+#: path. A new operation is a row here.
+OPERATIONS: dict[str, str] = {
+    "profiles_enrich": "/profiles/enrich",
+    "profiles_activity": "/profiles/activity",
+    "profiles_posts": "/profiles/posts",
+    "profiles_comments": "/profiles/comments",
+    "profiles_reactions": "/profiles/reactions",
+    "companies_enrich": "/companies/enrich",
+    "posts_enrich": "/posts/enrich",
+    "sales_search_people": "/sales/search/people",
+    "sales_search_companies": "/sales/search/companies",
+}
+
+# Statuses a batch can hold that mean it is still going to produce something.
+_LIVE = ("queued", "processing")
+
+
+@dataclass
+class RateLimits:
+    """The ceilings, read off the response headers of the last call.
+
+    Every field is None when the deployment publishes no ceiling for it, which
+    is what "no limit" looks like on the wire: an ABSENT header, never a zero.
+    Treating a missing header as 0 would make an unlimited account look
+    completely blocked.
+    """
+
+    limit: int | None = None
+    remaining: int | None = None
+    reset: int | None = None
+    concurrent_batch_limit: int | None = None
+    concurrent_batch_remaining: int | None = None
+    sync_limit: int | None = None
+    sync_remaining: int | None = None
+    sync_reset: int | None = None
+    sync_concurrent_limit: int | None = None
+    sync_concurrent_remaining: int | None = None
+
+    @classmethod
+    def from_headers(cls, headers: Mapping[str, str]) -> "RateLimits":
+        def num(name: str) -> int | None:
+            raw = headers.get(name)
+            if raw is None:
+                return None
+            try:
+                return int(raw)
+            except (TypeError, ValueError):
+                return None
+
+        return cls(
+            limit=num("X-RateLimit-Limit"),
+            remaining=num("X-RateLimit-Remaining"),
+            reset=num("X-RateLimit-Reset"),
+            concurrent_batch_limit=num("X-Concurrent-Batch-Limit"),
+            concurrent_batch_remaining=num("X-Concurrent-Batch-Remaining"),
+            sync_limit=num("X-Sync-Limit"),
+            sync_remaining=num("X-Sync-Remaining"),
+            sync_reset=num("X-Sync-Reset"),
+            sync_concurrent_limit=num("X-Sync-Concurrent-Limit"),
+            sync_concurrent_remaining=num("X-Sync-Concurrent-Remaining"),
+        )
+
+
+@dataclass
+class ResultEntry:
+    """One row of a batch's results, as the cursor returns it.
+
+    `raw` is the whole entry as JSON. The named fields are the ones every
+    operation has; `data` is the record itself and its shape is the
+    operation's.
+    """
+
+    item_index: int
+    input: Any
+    status: str
+    credits_used: float
+    data: Any | None = None
+    error: Mapping[str, Any] | None = None
+    page: int | None = None
+    created_at: str = ""
+    raw: Mapping[str, Any] = field(default_factory=dict)
+
+    @property
+    def ok(self) -> bool:
+        return self.status == "succeeded"
+
+    @classmethod
+    def from_json(cls, d: Mapping[str, Any]) -> "ResultEntry":
+        return cls(
+            item_index=int(d.get("item_index", 0)),
+            input=d.get("input"),
+            status=str(d.get("status", "")),
+            credits_used=float(d.get("credits_used", 0) or 0),
+            data=d.get("data"),
+            error=d.get("error"),
+            page=d.get("page"),
+            created_at=str(d.get("created_at", "")),
+            raw=d,
+        )
+
+
+@dataclass
+class Batch:
+    """A submission and its progress."""
+
+    batch_id: str
+    operation: str
+    status: str
+    total: int = 0
+    succeeded: int = 0
+    failed: int = 0
+    pending: int = 0
+    results_available: int = 0
+    credits_used: float = 0.0
+    external_id: str = ""
+    created_at: str = ""
+    completed_at: str | None = None
+    recommended_poll_ms: int = 2000
+    raw: Mapping[str, Any] = field(default_factory=dict)
+
+    @property
+    def done(self) -> bool:
+        """True once the batch will produce nothing further."""
+        return self.status not in _LIVE
+
+    @classmethod
+    def from_json(cls, d: Mapping[str, Any]) -> "Batch":
+        return cls(
+            batch_id=str(d.get("batch_id", "")),
+            operation=str(d.get("operation", "")),
+            status=str(d.get("status", "")),
+            total=int(d.get("total", 0) or 0),
+            succeeded=int(d.get("succeeded", 0) or 0),
+            failed=int(d.get("failed", 0) or 0),
+            pending=int(d.get("pending", 0) or 0),
+            results_available=int(d.get("results_available", 0) or 0),
+            credits_used=float(d.get("credits_used", 0) or 0),
+            external_id=str(d.get("external_id", "") or ""),
+            created_at=str(d.get("created_at", "") or ""),
+            completed_at=d.get("completed_at"),
+            recommended_poll_ms=int(d.get("recommended_poll_ms", 2000) or 2000),
+            raw=d,
+        )
+
+
+@dataclass
+class SyncResult:
+    """What a `/sync` call answers with: one batch, one entry.
+
+    `complete` is the field to branch on. A synchronous request that ran out of
+    deadline hands back what landed and leaves the target queued at priority -
+    so `complete` is False, `result` may be None, and `batch_id` is still a real
+    batch you can read later. It is never a timeout you have to parse, and
+    nothing already paid for is lost.
+    """
+
+    batch_id: str
+    operation: str
+    status: str
+    complete: bool
+    result: ResultEntry | None
+    credits_used: float = 0.0
+    raw: Mapping[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_json(cls, d: Mapping[str, Any]) -> "SyncResult":
+        entry = d.get("result")
+        return cls(
+            batch_id=str(d.get("batch_id", "")),
+            operation=str(d.get("operation", "")),
+            status=str(d.get("status", "")),
+            complete=bool(d.get("complete", False)),
+            result=ResultEntry.from_json(entry) if isinstance(entry, Mapping) else None,
+            credits_used=float(d.get("credits_used", 0) or 0),
+            raw=d,
+        )
+
+
+@dataclass
+class ResultsPage:
+    """One read of the results cursor.
+
+    `recommended_poll_ms` is the server's own number and is 0 once the batch is
+    terminal, which is the signal that there is nothing left to wait for.
+    """
+
+    status: str
+    entries: list[ResultEntry]
+    next_cursor: str
+    has_more: bool
+    recommended_poll_ms: int = 0
+
+    @property
+    def still_running(self) -> bool:
+        return self.status in _LIVE
+
+
+class _Operation:
+    """One operation, callable three ways.
+
+    `ed.profiles_enrich(targets)` submits a batch, `.sync(target)` does the
+    blocking single lookup, and `.collect(targets)` submits and drains. They are
+    the same operation, which is why they are one object rather than three
+    method names that have to be kept in step.
+    """
+
+    def __init__(self, client: "EasyData", path: str) -> None:
+        self._client = client
+        self._path = path
+
+    def __call__(self, targets: Sequence[Any], **kwargs: Any) -> Batch:
+        return self._client.submit(self._path, targets, **kwargs)
+
+    def sync(self, target: Any, **kwargs: Any) -> SyncResult:
+        return self._client.submit_sync(self._path, target, **kwargs)
+
+    def collect(self, targets: Sequence[Any], **kwargs: Any) -> list[ResultEntry]:
+        """Submit and return every entry, blocking until the batch is done."""
+        timeout = kwargs.pop("timeout", None)
+        batch = self(targets, **kwargs)
+        return list(self._client.results(batch.batch_id, timeout=timeout))
+
+
+class EasyData:
+    """The client.
+
+    >>> ed = EasyData()                     # reads EASYDATA_API_KEY
+    >>> r = ed.profiles_enrich.sync("https://linkedin.com/in/satyanadella")
+    >>> r.result.data["full_name"]
+
+    Retries are on by default and cover exactly the failures that are safe to
+    repeat: 429, 5xx and a transport error. Submissions carry an
+    `Idempotency-Key` so that repeating one is free - a retried submit resolves
+    to the batch the first attempt created rather than creating a second one and
+    charging for it twice.
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str | None = None,
+        timeout: float = 120.0,
+        max_retries: int = 3,
+        user_agent: str = "easydata-python/1.0",
+    ) -> None:
+        key = api_key or os.environ.get("EASYDATA_API_KEY", "")
+        if not key:
+            raise ValueError(
+                "no API key: pass api_key= or set EASYDATA_API_KEY in the environment"
+            )
+        self.api_key = key
+        self.base_url = (base_url or os.environ.get("EASYDATA_BASE_URL") or DEFAULT_BASE_URL).rstrip("/")
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self.user_agent = user_agent
+
+        #: The ceilings from the most recent response. Updated on every call,
+        #: including a failed one - a 429 is where they matter most.
+        self.rate_limits = RateLimits()
+
+        for attr, path in OPERATIONS.items():
+            setattr(self, attr, _Operation(self, path))
+
+    # ---------------------------------------------------------------- submit
+
+    def submit(
+        self,
+        path: str,
+        targets: Sequence[Any],
+        *,
+        external_id: str | None = None,
+        callback_url: str | None = None,
+        webhook_tag: str | None = None,
+        max_results: int | None = None,
+        enrich: bool | None = None,
+        find_emails: bool | None = None,
+        include_results: bool | None = None,
+        idempotency_key: str | None = None,
+    ) -> Batch:
+        """Submit a batch. Answers 202 with the batch; nothing has run yet.
+
+        A batch of one is a batch. There is no separate single-target path and
+        no ceiling to discover between one target and fifty thousand.
+        """
+        if not targets:
+            raise ValueError("targets is empty: a batch needs at least one target")
+
+        body: dict[str, Any] = {"targets": list(targets)}
+        _put(body, external_id=external_id, callback_url=callback_url,
+             webhook_tag=webhook_tag, max_results=max_results, enrich=enrich,
+             find_emails=find_emails, include_results=include_results)
+
+        data = self._request(
+            "POST", path, body=body,
+            # Minted here rather than left to the caller, because the retry
+            # below is ours: without a key, our own retry of a submission that
+            # actually succeeded creates a second batch and bills it.
+            idempotency_key=idempotency_key or str(uuid.uuid4()),
+        )
+        return Batch.from_json(data)
+
+    def submit_sync(
+        self,
+        path: str,
+        target: Any,
+        *,
+        external_id: str | None = None,
+        max_results: int | None = None,
+        idempotency_key: str | None = None,
+    ) -> SyncResult:
+        """One entity, answered in this response, at twice the credits.
+
+        `target`, singular - not a list of one. The bounds are refusals rather
+        than downgrades: no `enrich`, no webhooks, and one upstream page for a
+        paged operation.
+        """
+        if isinstance(target, (list, tuple, set)):
+            raise ValueError(
+                "sync takes ONE target, not a sequence - submit a batch for several"
+            )
+
+        body: dict[str, Any] = {"target": target}
+        _put(body, external_id=external_id, max_results=max_results)
+
+        data = self._request(
+            "POST", path + "/sync", body=body,
+            idempotency_key=idempotency_key or str(uuid.uuid4()),
+        )
+        return SyncResult.from_json(data)
+
+    # --------------------------------------------------------------- batches
+
+    def batch(self, batch_id: str) -> Batch:
+        """One batch's current state."""
+        return Batch.from_json(self._request("GET", f"/batches/{batch_id}"))
+
+    def batches(
+        self,
+        *,
+        status: str | None = None,
+        operation: str | None = None,
+        external_id: str | None = None,
+        limit: int = 50,
+        offset: int = 0,
+    ) -> list[Batch]:
+        """List your batches, newest first."""
+        query = {"limit": limit, "offset": offset}
+        _put(query, status=status, operation=operation, external_id=external_id)
+        # `data` is the array itself, not an object wrapping one: the listing's
+        # own pagination lives in `meta` (total, hasMore) like every other
+        # response's does.
+        data = self._request("GET", "/batches", query=query)
+        return [Batch.from_json(b) for b in (data or [])]
+
+    def cancel(self, batch_id: str) -> Batch:
+        """Stop a batch. Entries already delivered stay delivered and charged."""
+        return Batch.from_json(self._request("POST", f"/batches/{batch_id}/cancel"))
+
+    def results_page(
+        self,
+        batch_id: str,
+        *,
+        cursor: str = "",
+        page_size: int = 100,
+    ) -> "ResultsPage":
+        """One page of the cursor, and the cursor to continue from.
+
+        `results()` is the loop you usually want. This is the layer under it,
+        for a caller that owns its own paging - a worker that stores the cursor
+        between runs, or a request handler that must return rather than block.
+        The cursor is opaque: hand back exactly what you were given.
+        """
+        query: dict[str, Any] = {"limit": page_size}
+        if cursor:
+            query["cursor"] = cursor
+
+        data, meta = self._request(
+            "GET", f"/batches/{batch_id}/results", query=query, with_meta=True
+        )
+        return ResultsPage(
+            status=str(data.get("status", "")),
+            entries=[ResultEntry.from_json(e) for e in (data.get("entries") or [])],
+            next_cursor=str(meta.get("nextCursor") or ""),
+            has_more=bool(meta.get("hasMore")),
+            recommended_poll_ms=int(meta.get("recommendedPollMs") or 0),
+        )
+
+    def results(
+        self,
+        batch_id: str,
+        *,
+        page_size: int = 100,
+        wait: bool = True,
+        timeout: float | None = None,
+    ) -> Iterator[ResultEntry]:
+        """Stream a batch's entries, yielding each one as it becomes readable.
+
+        This is the whole point of the cursor: results are readable WHILE the
+        batch is still processing, so a long batch starts producing rows
+        immediately rather than after it finishes.
+
+        With `wait=True` (the default) the iterator keeps the cursor open until
+        the batch reaches a terminal state, sleeping for as long as the API's
+        own `recommended_poll_ms` says between empty reads. With `wait=False` it
+        yields what is readable right now and stops.
+
+        The cursor is monotonic and gapless, so resuming is exact: an entry is
+        yielded once, and a batch still filling in never re-delivers one you
+        have already seen.
+        """
+        cursor = ""
+        deadline = None if timeout is None else time.monotonic() + timeout
+
+        while True:
+            page = self.results_page(batch_id, cursor=cursor, page_size=page_size)
+            yield from page.entries
+
+            if page.next_cursor:
+                cursor = page.next_cursor
+
+            if page.has_more:
+                continue
+
+            if not wait or page.status not in _LIVE:
+                return
+
+            if deadline is not None and time.monotonic() >= deadline:
+                raise TimeoutError(
+                    f"batch {batch_id} was still {page.status} after {timeout}s; "
+                    "its results remain readable - call results() again with the "
+                    "same batch id"
+                )
+
+            # The server's own number. Polling faster than this does not make
+            # the scrape finish sooner; it only spends the request budget the
+            # rate limiter is counting.
+            time.sleep((page.recommended_poll_ms or 2000) / 1000.0)
+
+    def wait(self, batch_id: str, *, timeout: float | None = None) -> Batch:
+        """Block until a batch reaches a terminal state, and return it.
+
+        Use `results()` instead when you want the rows: this polls the batch
+        row, which tells you the counters and not the records.
+        """
+        deadline = None if timeout is None else time.monotonic() + timeout
+        while True:
+            b = self.batch(batch_id)
+            if b.done:
+                return b
+            if deadline is not None and time.monotonic() >= deadline:
+                raise TimeoutError(f"batch {batch_id} was still {b.status} after {timeout}s")
+            time.sleep(b.recommended_poll_ms / 1000.0)
+
+    # --------------------------------------------------------------- account
+
+    def account(self) -> Mapping[str, Any]:
+        """The allowance, the ceilings, and the webhook signing secret."""
+        return self._request("GET", "/account")
+
+    def usage(
+        self,
+        *,
+        from_: str | None = None,
+        to: str | None = None,
+        external_id: str | None = None,
+    ) -> Mapping[str, Any]:
+        """Spend, by day and operation."""
+        query: dict[str, Any] = {}
+        _put(query, to=to, external_id=external_id)
+        if from_:
+            query["from"] = from_
+        return self._request("GET", "/usage", query=query)
+
+    # ------------------------------------------------------------- transport
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        body: Mapping[str, Any] | None = None,
+        query: Mapping[str, Any] | None = None,
+        idempotency_key: str | None = None,
+        with_meta: bool = False,
+    ) -> Any:
+        url = self.base_url + path
+        if query:
+            clean = {k: v for k, v in query.items() if v is not None}
+            if clean:
+                url += "?" + urllib.parse.urlencode(clean)
+
+        payload = json.dumps(body).encode() if body is not None else None
+        headers = {
+            "X-API-Key": self.api_key,
+            "Accept": "application/json",
+            "User-Agent": self.user_agent,
+        }
+        if payload is not None:
+            headers["Content-Type"] = "application/json"
+        if idempotency_key:
+            headers["Idempotency-Key"] = idempotency_key
+
+        last: EasyDataError | None = None
+        for attempt in range(self.max_retries + 1):
+            try:
+                status, out, resp_headers = self._once(method, url, payload, headers)
+            except (urllib.error.URLError, TimeoutError, OSError) as exc:
+                # The request never produced a response. Safe to repeat: a
+                # submission carries an idempotency key, and everything else
+                # here is a read.
+                last = TransportError(f"could not reach {url}: {exc}")
+                if attempt >= self.max_retries:
+                    raise last from exc
+                time.sleep(self._backoff(attempt, None))
+                continue
+
+            self.rate_limits = RateLimits.from_headers(resp_headers)
+
+            if 200 <= status < 300:
+                envelope = out if isinstance(out, Mapping) else {}
+                data = envelope.get("data", envelope)
+                return (data, envelope.get("meta") or {}) if with_meta else data
+
+            retry_after = _retry_after(resp_headers)
+            err = error_for(status, out if isinstance(out, Mapping) else {}, retry_after=retry_after)
+
+            # 429 and 5xx are the two the server is telling us to try again on.
+            # Everything else is a refusal that repeating cannot fix, and
+            # retrying it would only spend the rate budget on a certain no.
+            if status != 429 and status < 500:
+                raise err
+            if attempt >= self.max_retries:
+                raise err
+            last = err
+            time.sleep(self._backoff(attempt, retry_after))
+
+        raise last or EasyDataError("request failed")  # pragma: no cover
+
+    def _once(
+        self, method: str, url: str, payload: bytes | None, headers: Mapping[str, str]
+    ) -> tuple[int, Any, dict[str, str]]:
+        req = urllib.request.Request(url, data=payload, method=method)
+        for k, v in headers.items():
+            req.add_header(k, v)
+
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+                return resp.status, _decode(resp.read()), dict(resp.headers)
+        except urllib.error.HTTPError as exc:
+            # An HTTP error IS a response - the API said no, in the envelope -
+            # so it is decoded here rather than raised as a transport failure.
+            return exc.code, _decode(exc.read()), dict(exc.headers or {})
+
+    def _backoff(self, attempt: int, retry_after: float | None) -> float:
+        """The server's own number when it sent one, otherwise exponential.
+
+        Jittered because the failure that produces a retry storm is the one
+        every client sees at the same instant, and an unjittered backoff
+        reconverges them on the same second.
+        """
+        if retry_after is not None:
+            return min(retry_after, 60.0)
+        return min(2.0**attempt, 30.0) * (0.5 + random.random() / 2)
+
+    def verify_webhook(self, secret: str, headers: Mapping[str, str], body: bytes, **kw: Any):
+        """Convenience for `easydata.webhooks.verify`. See that module."""
+        from . import webhooks
+
+        return webhooks.verify(secret, headers, body, **kw)
+
+
+def _put(d: dict[str, Any], **kwargs: Any) -> None:
+    """Sets the keyword arguments that were actually given.
+
+    Absent is not the same as false here: `enrich=False` is a caller saying so,
+    and dropping it because it is falsy would silently send a different request
+    than the one they wrote.
+    """
+    for k, v in kwargs.items():
+        if v is not None:
+            d[k] = v
+
+
+def _decode(raw: bytes) -> Any:
+    if not raw:
+        return {}
+    try:
+        return json.loads(raw)
+    except ValueError:
+        # A body that is not JSON is a proxy or a gateway answering, not this
+        # API. Keep it: it is the only evidence of what actually replied.
+        return {"error": {"type": "", "message": raw[:500].decode("utf-8", "replace")}}
+
+
+def _retry_after(headers: Mapping[str, str]) -> float | None:
+    raw = headers.get("Retry-After") or headers.get("retry-after")
+    if raw is None:
+        return None
+    try:
+        return max(float(raw), 0.0)
+    except (TypeError, ValueError):
+        return None

easydata_api/errors.py

@@ -0,0 +1,199 @@
+"""The error vocabulary, as exceptions.
+
+One class per `error.type` the API publishes, all under `EasyDataError`, so a
+caller can catch the family or the one case they know how to handle. The type
+string is the contract - the class is a convenience over it - which is why
+`EasyDataError.type` is always the string the API sent, including for a type
+this version of the SDK has never heard of.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Mapping
+
+
+class EasyDataError(Exception):
+    """Any error the API reported, or any failure to reach it."""
+
+    #: The `error.type` string. Empty only for a transport failure.
+    type: str = ""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        type: str = "",
+        status: int = 0,
+        request_id: str = "",
+        field: str = "",
+        retry_after: float | None = None,
+        body: Mapping[str, Any] | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        if type:
+            self.type = type
+        self.status = status
+        self.request_id = request_id
+        self.field = field
+        self.retry_after = retry_after
+        self.body = dict(body or {})
+
+    def __str__(self) -> str:  # pragma: no cover - formatting only
+        parts = [self.message]
+        if self.type:
+            parts.append(f"type={self.type}")
+        if self.status:
+            parts.append(f"status={self.status}")
+        if self.request_id:
+            # Quote this at support and the request can be found in one query.
+            parts.append(f"request_id={self.request_id}")
+        if self.field:
+            parts.append(f"field={self.field}")
+        return " ".join(parts)
+
+
+class InvalidRequest(EasyDataError):
+    """400. `field` names the offending key when the API could identify one.
+
+    An unknown key in the body is refused rather than ignored, so this is also
+    what a typo looks like - which is the point of refusing it.
+    """
+
+    type = "invalid_request"
+
+
+class InvalidAPIKey(EasyDataError):
+    """401. Missing, malformed, revoked or expired. Never metered."""
+
+    type = "invalid_api_key"
+
+
+class QuotaExhausted(EasyDataError):
+    """403. The monthly allowance is spent. Waiting is the fix."""
+
+    type = "quota_exhausted"
+
+
+class EmailUnverified(EasyDataError):
+    """403, and NOT the same as a spent allowance.
+
+    The default allowance is gated on somebody on the organization having
+    confirmed their email address. Clicking the link fixes it; waiting for next
+    month does not.
+    """
+
+    type = "email_unverified"
+
+
+class NotFound(EasyDataError):
+    """404. A batch id that is not yours, or is not a batch."""
+
+    type = "not_found"
+
+
+class Conflict(EasyDataError):
+    """409. Most often an `Idempotency-Key` replayed with a different body."""
+
+    type = "conflict"
+
+
+class UnprocessableTarget(EasyDataError):
+    """422. The request was well-formed and the target was not usable."""
+
+    type = "unprocessable_target"
+
+
+class RateLimited(EasyDataError):
+    """429. `retry_after` carries the server's own number, in seconds.
+
+    The client retries this for you by default - see `EasyData(max_retries=)`.
+    Seeing it means the retries were exhausted or were switched off.
+    """
+
+    type = "rate_limited"
+
+
+class NotImplementedYet(EasyDataError):
+    """501. The operation is published and its scraper is not live yet."""
+
+    type = "not_implemented"
+
+
+class InternalError(EasyDataError):
+    """500. Ours. Retried by default."""
+
+    type = "internal_error"
+
+
+class UpstreamTimeout(EasyDataError):
+    """504-shaped: the upstream did not answer in time."""
+
+    type = "upstream_timeout"
+
+
+class CapacityUnavailable(EasyDataError):
+    """No worker in the pool can run this operation right now."""
+
+    type = "capacity_unavailable"
+
+
+class TransportError(EasyDataError):
+    """The request never produced an API response: DNS, TLS, socket, timeout.
+
+    Distinct from every class above, which all mean "the API answered and said
+    no". A caller retrying on its own needs to know which of the two it got.
+    """
+
+
+#: Built from the classes rather than typed out again - a table written twice
+#: is a table that disagrees with itself after one rename.
+_BY_TYPE = {
+    cls.type: cls
+    for cls in (
+        InvalidRequest,
+        InvalidAPIKey,
+        QuotaExhausted,
+        EmailUnverified,
+        NotFound,
+        Conflict,
+        UnprocessableTarget,
+        RateLimited,
+        NotImplementedYet,
+        InternalError,
+        UpstreamTimeout,
+        CapacityUnavailable,
+    )
+}
+
+
+def error_for(
+    status: int,
+    body: Mapping[str, Any],
+    *,
+    retry_after: float | None = None,
+) -> EasyDataError:
+    """Builds the exception for one error response.
+
+    An unrecognised `error.type` becomes a plain `EasyDataError` carrying that
+    string, never a crash: the vocabulary is allowed to grow, and an SDK a
+    version behind should still hand the caller something they can read and
+    report.
+    """
+    err = body.get("error") if isinstance(body, Mapping) else None
+    if not isinstance(err, Mapping):
+        err = {}
+
+    etype = str(err.get("type") or "")
+    message = str(err.get("message") or f"HTTP {status}")
+    cls = _BY_TYPE.get(etype, EasyDataError)
+
+    return cls(
+        message,
+        type=etype,
+        status=status,
+        request_id=str(err.get("requestId") or err.get("request_id") or ""),
+        field=str(err.get("field") or ""),
+        retry_after=retry_after,
+        body=body,
+    )

easydata_api/webhooks.py

@@ -0,0 +1,234 @@
+"""Verifying a webhook delivery.
+
+Two schemes ride on every delivery and you need only one of them.
+
+`X-EasyData-Signature: t=<unix>,v1=<hex>` is an HMAC-SHA256 over
+`<t>.<raw body>`, keyed with your webhook secret. It needs nothing but the
+standard library.
+
+`X-EasyData-Signature-Ed25519: t=<unix>,kid=<key id>,wid=<endpoint id>,v1b=<b64url>`
+signs `<t>.<wid>.<raw body>` and is checked against the public key published at
+`https://api.easydata.win/.well-known/webhook-keys.json`. Verifying it needs no
+secret at all, so a partner, a queue consumer or an edge function can check a
+delivery you forwarded to them. It needs `cryptography`, which is why it is an
+optional extra rather than a dependency.
+
+Two rules that are easy to get wrong and silent when you do:
+
+* **Verify against the RAW body**, exactly the bytes that arrived. Re-serialising
+  the parsed JSON changes key order and whitespace, and the signature will not
+  match a body you rebuilt.
+* **Never verify against `X-EasyData-Timestamp`.** It carries the same unix
+  seconds, but it sits OUTSIDE both signed messages - anyone replaying a captured
+  delivery can set it to whatever passes a freshness check. The `t` inside the
+  signature header is the only copy that cannot be edited without breaking the
+  signature, and it is the one both functions here read.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import time
+from typing import Any, Mapping, NamedTuple
+
+__all__ = ["Delivery", "verify", "verify_ed25519", "VerificationError"]
+
+#: The default freshness window, in seconds. Generous enough for a retry and a
+#: clock that is a little out, short enough that a captured delivery goes stale.
+DEFAULT_TOLERANCE = 300
+
+
+class VerificationError(Exception):
+    """The delivery did not verify. Answer 400 and do not process it."""
+
+
+class Delivery(NamedTuple):
+    """A verified delivery, unpacked."""
+
+    id: str
+    event: str
+    created_at: str
+    data: Mapping[str, Any]
+    #: The whole parsed body, for anything this tuple does not name.
+    body: Mapping[str, Any]
+
+
+def verify(
+    secret: str,
+    headers: Mapping[str, str],
+    body: bytes,
+    *,
+    tolerance: int = DEFAULT_TOLERANCE,
+) -> Delivery:
+    """Verifies the HMAC signature and returns the delivery.
+
+    Raises `VerificationError` on anything wrong - a missing header, a stale
+    timestamp, a bad digest - because there is nothing useful a caller can do
+    with a delivery that half-verified.
+
+        @app.post("/webhooks/easydata")
+        def hook():
+            try:
+                d = verify(SECRET, request.headers, request.get_data())
+            except VerificationError:
+                return "", 400
+            if seen(d.id):        # X-EasyData-Delivery, stable across retries
+                return "", 200
+            handle(d.event, d.data)
+            return "", 200
+    """
+    if not secret:
+        raise VerificationError("no signing secret: read it from GET /v1/account")
+
+    raw = _header(headers, "X-EasyData-Signature")
+    if not raw:
+        raise VerificationError("no X-EasyData-Signature header")
+
+    parts = _parse(raw)
+    ts, sig = parts.get("t"), parts.get("v1")
+    if not ts or not sig:
+        raise VerificationError(f"malformed signature header: {raw!r}")
+
+    _check_age(ts, tolerance)
+
+    expected = hmac.new(secret.encode(), f"{ts}.".encode() + body, hashlib.sha256).hexdigest()
+    # Constant time: a byte-at-a-time comparison leaks where the first
+    # difference is, which is enough to forge a digest given enough attempts.
+    if not hmac.compare_digest(expected, sig):
+        raise VerificationError("signature does not match")
+
+    return _delivery(body)
+
+
+def verify_ed25519(
+    public_key_b64: str,
+    headers: Mapping[str, str],
+    body: bytes,
+    *,
+    webhook_id: str,
+    tolerance: int = DEFAULT_TOLERANCE,
+) -> Delivery:
+    """Verifies the Ed25519 signature. Needs `pip install easydata-api[ed25519]`.
+
+    `webhook_id` is YOUR endpoint's id, and passing it is not optional.
+
+    One key signs for every customer on the deployment, so a delivery another
+    customer legitimately received is a genuinely signed message. Without
+    checking that `wid` is your endpoint, replaying theirs against your receiver
+    verifies. The HMAC scheme needs no equivalent check, because your secret is
+    only yours.
+    """
+    # Everything that can be decided without the optional dependency is decided
+    # first. The `wid` check below is the security-relevant one and it is pure
+    # string comparison; importing ahead of it turned "this delivery is not
+    # yours" into "you have not installed cryptography", which is the wrong
+    # answer to the more important question.
+    if not webhook_id:
+        raise VerificationError(
+            "webhook_id is required: one key signs for every customer, so a "
+            "delivery is only yours if wid matches your endpoint"
+        )
+
+    raw = _header(headers, "X-EasyData-Signature-Ed25519")
+    if not raw:
+        raise VerificationError("no X-EasyData-Signature-Ed25519 header")
+
+    parts = _parse(raw)
+    ts, wid, sig = parts.get("t"), parts.get("wid"), parts.get("v1b")
+    if not ts or not wid or not sig:
+        raise VerificationError(f"malformed signature header: {raw!r}")
+
+    if not hmac.compare_digest(wid, webhook_id):
+        raise VerificationError(
+            f"delivery was addressed to endpoint {wid}, not to {webhook_id}"
+        )
+
+    _check_age(ts, tolerance)
+
+    try:
+        from cryptography.exceptions import InvalidSignature
+        from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
+    except ImportError as exc:  # pragma: no cover - depends on the extra
+        raise VerificationError(
+            "Ed25519 verification needs the `cryptography` package: "
+            "pip install easydata-api[ed25519]. The HMAC scheme in verify() needs nothing."
+        ) from exc
+
+    key = Ed25519PublicKey.from_public_bytes(_b64(public_key_b64))
+    message = f"{ts}.{wid}.".encode() + body
+    try:
+        key.verify(_b64(sig), message)
+    except InvalidSignature as exc:
+        raise VerificationError("signature does not match") from exc
+
+    return _delivery(body)
+
+
+def _delivery(body: bytes) -> Delivery:
+    try:
+        parsed = json.loads(body)
+    except ValueError as exc:
+        raise VerificationError("body is not JSON") from exc
+    if not isinstance(parsed, dict):
+        raise VerificationError("body is not an object")
+
+    # The event's own fields are in `data`, one level down. Reading the top
+    # level instead is the quietest bug this API can hand you: the signature
+    # still verifies, the handler still returns 2xx, and every field is None.
+    return Delivery(
+        id=str(parsed.get("id", "")),
+        event=str(parsed.get("event", "")),
+        created_at=str(parsed.get("createdAt", "")),
+        data=parsed.get("data") or {},
+        body=parsed,
+    )
+
+
+def _check_age(ts: str, tolerance: int) -> None:
+    try:
+        sent = int(ts)
+    except ValueError as exc:
+        raise VerificationError(f"signature timestamp is not a number: {ts!r}") from exc
+    if tolerance > 0 and abs(time.time() - sent) > tolerance:
+        raise VerificationError(f"signature timestamp is outside {tolerance}s")
+
+
+def _parse(header: str) -> dict[str, str]:
+    out: dict[str, str] = {}
+    for part in header.split(","):
+        k, _, v = part.strip().partition("=")
+        if k:
+            out[k] = v
+    return out
+
+
+def _header(headers: Mapping[str, str], name: str) -> str:
+    """HTTP header names are case-insensitive and half the frameworks lowercase
+    them, so look the obvious ways before giving up."""
+    for key in (name, name.lower(), name.upper(), name.replace("-", "_").upper()):
+        if key in headers:
+            return str(headers[key])
+    for key, value in headers.items():
+        if key.lower() == name.lower():
+            return str(value)
+    return ""
+
+
+def _b64(s: str) -> bytes:
+    """Decodes base64 in whichever of the four spellings arrived.
+
+    The signature is base64url without padding and a public key is pasted into
+    an env file by a human, so which alphabet and whether it is padded is not
+    worth failing a deployment over.
+    """
+    import base64
+
+    for decoder in (base64.urlsafe_b64decode, base64.b64decode):
+        for candidate in (s, s + "=" * (-len(s) % 4)):
+            try:
+                return decoder(candidate)
+            except Exception:  # noqa: BLE001 - trying the next spelling
+                continue
+    raise VerificationError(f"could not decode base64: {s[:16]!r}...")

easydata_api-1.0.1.dist-info/METADATA

@@ -0,0 +1,185 @@
+Metadata-Version: 2.4
+Name: easydata-api
+Version: 1.0.1
+Summary: Official Python client for the EasyData LinkedIn enrichment API
+Author-email: EasyData Development <dev@easydata.win>
+License-Expression: MIT
+Project-URL: Homepage, https://easydata.win
+Project-URL: Documentation, https://easydata.win/docs/api
+Project-URL: Reference, https://easydata.win/openapi.yaml
+Keywords: linkedin,enrichment,data,api,scraping
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: ed25519
+Requires-Dist: cryptography>=42; extra == "ed25519"
+Dynamic: license-file
+
+# EasyData for Python
+
+The official client for the [EasyData](https://easydata.win) LinkedIn
+enrichment API.
+
+```bash
+pip install easydata-api
+```
+
+Zero dependencies. The client is `urllib` and the webhook HMAC is
+`hmac`/`hashlib`, both standard library - an enrichment script should not drag a
+dependency tree in behind it. Only the asymmetric webhook scheme needs an extra
+(`pip install easydata-api[ed25519]`), and most receivers never use it.
+
+## One record
+
+```python
+from easydata_api import EasyData
+
+ed = EasyData()  # reads EASYDATA_API_KEY
+
+r = ed.profiles_enrich.sync("https://linkedin.com/in/satyanadella")
+print(r.result.data["full_name"])
+```
+
+`.sync()` takes **one** target and answers with **one** record, in the response.
+It costs double, it accepts no webhooks and no `enrich`, and for a paged
+operation it returns one upstream page. Those bounds are refusals, not quiet
+downgrades.
+
+If the deadline expires first you get `complete=False` and a real `batch_id`,
+never a 504 - so you keep the handle to results you may already have been
+charged for.
+
+## A batch
+
+Everything is a batch, including a batch of one. There is no ceiling to discover
+between one target and fifty thousand.
+
+```python
+batch = ed.profiles_enrich(urls, external_id="crm-sync", find_emails=True)
+
+for entry in ed.results(batch.batch_id):
+    if entry.ok:
+        save(entry.data)
+    else:
+        log(entry.input, entry.error["type"])   # and credits_used is 0
+```
+
+`results()` is a generator over the cursor. Results **stream**: it yields rows
+while the batch is still processing, so a long batch starts producing
+immediately rather than after it finishes. It holds the cursor open until the
+batch reaches a terminal state, sleeping for the server's own poll interval
+between empty reads.
+
+```python
+list(ed.results(batch_id, wait=False))       # what is readable right now
+ed.wait(batch_id, timeout=600)               # the counters, not the rows
+ed.profiles_enrich.collect(urls)             # submit and drain, in one call
+```
+
+## Retries and double-billing
+
+Retries are on by default and cover exactly what is safe to repeat: `429`, `5xx`
+and a transport failure. A `4xx` is raised immediately, because repeating a
+refusal only spends the rate budget on a certain no.
+
+Every submission carries an `Idempotency-Key` that the client mints, so the
+retry is free: a retried submit resolves to the batch the first attempt created
+rather than creating a second one and charging for it. Pass your own
+`idempotency_key=` if your caller's retry needs the same guarantee.
+
+```python
+ed = EasyData(max_retries=5, timeout=180)
+ed.rate_limits.remaining     # read off the last response, including a 429
+```
+
+`rate_limits` fields are `None` when the deployment publishes no ceiling. That
+is what "no limit" looks like on the wire: an absent header, never a zero.
+
+## Errors
+
+```python
+from easydata_api import QuotaExhausted, RateLimited, InvalidRequest, EasyDataError
+
+try:
+    ed.profiles_enrich(urls)
+except InvalidRequest as e:
+    print(e.field, e.request_id)   # quote request_id at support
+except QuotaExhausted:
+    ...                            # waiting for the month is the fix
+except EasyDataError as e:
+    print(e.type, e.status)
+```
+
+One class per `error.type`, all under `EasyDataError`. An `error.type` this
+version has never heard of becomes a plain `EasyDataError` carrying that string
+rather than a crash.
+
+`EmailUnverified` is a `403` and is **not** a spent allowance: the default
+allowance is gated on somebody having confirmed their email address, and
+clicking the link fixes it.
+
+## Webhooks
+
+```python
+from easydata_api import verify, VerificationError
+
+@app.post("/webhooks/easydata")
+def hook():
+    try:
+        d = verify(SECRET, request.headers, request.get_data())
+    except VerificationError:
+        return "", 400
+
+    if seen(d.id):          # stable across every retry of the same delivery
+        return "", 200
+
+    if d.event == "batch.result":
+        handle(d.data["result"])
+    elif d.event == "batch.completed":
+        finish(d.data["batch_id"])
+    return "", 200
+```
+
+Four events: `batch.started`, `batch.result` (one per row), `batch.completed`
+and `batch.failed`. The fields are in `d.data`, one level down.
+
+Two things that are silent when you get them wrong:
+
+- **Verify against the raw body.** Re-serialising parsed JSON changes key order
+  and whitespace, and the signature will not match a body you rebuilt.
+- **Never verify against `X-EasyData-Timestamp`.** It sits outside both signed
+  messages, so a replayed delivery can set it to anything. The `t` inside the
+  signature header is the only copy that cannot be edited.
+
+For the asymmetric scheme, `webhook_id` is required - one key signs for every
+customer, so checking `wid` is what stops another customer's genuine delivery
+verifying against your receiver.
+
+```python
+from easydata_api import verify_ed25519
+d = verify_ed25519(PUBLIC_KEY, request.headers, body, webhook_id=MY_ENDPOINT_ID)
+```
+
+## Everything else
+
+```python
+ed.batch(batch_id)                                  # one batch's state
+ed.batches(status="completed", external_id="crm")   # your batches
+ed.cancel(batch_id)                                 # delivered rows stay charged
+ed.account()                                        # allowance, ceilings, secret
+ed.usage(from_="2026-09-01", to="2026-09-30")       # spend by day and operation
+```
+
+Operations are attributes: `profiles_enrich`, `profiles_activity`,
+`profiles_posts`, `profiles_comments`, `profiles_reactions`, `companies_enrich`,
+`posts_enrich`, `sales_search_people`, `sales_search_companies`.
+
+## Reference
+
+- [API reference](https://easydata.win/docs/api)
+- [The batch model](https://easydata.win/docs/batches) - what a credit is, and why
+- [OpenAPI 3.1](https://easydata.win/openapi.yaml)

easydata_api-1.0.1.dist-info/RECORD

@@ -0,0 +1,9 @@
+easydata_api/__init__.py,sha256=aIhtD0aHCZU0m_aXXlQLyRP7sbe00Gv8xU6Xf3r84G0,1735
+easydata_api/client.py,sha256=PdIarJRXe1uBKpL58EZ1j-P-2Lm8BCrntXt1mIDYq4E,23542
+easydata_api/errors.py,sha256=4uWrGe7H9wblaroGwvqFoZIiScSdangNOiIvTZdVlNA,5537
+easydata_api/webhooks.py,sha256=EfAY-zq3wNRqhOG4RPeu4Vh79zHjuOrt7seGrN9aTuM,8632
+easydata_api-1.0.1.dist-info/licenses/LICENSE,sha256=OyJwsf0avfY-R1xUYt378xny55YToozBgEFTcKeljsQ,1065
+easydata_api-1.0.1.dist-info/METADATA,sha256=2FWnwo9CVVo2-rEhbmFbyqQ-as6BjJtjAdsUhSx9Na4,6639
+easydata_api-1.0.1.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+easydata_api-1.0.1.dist-info/top_level.txt,sha256=80mJkf3GRHHzo38CaRw8dqQ62vXQILoNJiSJi5OOIUU,13
+easydata_api-1.0.1.dist-info/RECORD,,

easydata_api-1.0.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

easydata_api-1.0.1.dist-info/licenses/LICENSE

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

easydata_api-1.0.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+easydata_api