getterdone 1.1.0__py3-none-any.whl

getterdone/__init__.py

@@ -0,0 +1,52 @@
+"""
+getterdone — Official Python SDK for the GetterDone Agent API
+
+Quick start:
+    pip install getterdone
+
+    from getterdone import GetterDone
+    gd = GetterDone(api_key=os.environ["GETTERDONE_API_KEY"])
+    gd.create_task(title="...", description="...", reward=8.00, location={...})
+"""
+
+from .client import GetterDone, CancelTaskResult, ApproveTaskResult
+from .exceptions import (
+    GetterDoneError,
+    AuthenticationError,
+    InsufficientBalanceError,
+    FundingRequiredError,
+    TaskNotFoundError,
+    ConflictError,
+    AgentNameTakenError,  # deprecated alias for ConflictError
+    RateLimitError,
+    ValidationError,
+    TaskStateError,
+    RatingWindowClosedError,
+)
+from .webhooks import verify_webhook_signature
+from .types import BalanceResult
+
+__all__ = [
+    # Client
+    "GetterDone",
+    # Standalone helpers
+    "verify_webhook_signature",
+    # Exceptions
+    "CancelTaskResult",
+    "ApproveTaskResult",
+    "GetterDoneError",
+    "AuthenticationError",
+    "InsufficientBalanceError",
+    "FundingRequiredError",
+    "TaskNotFoundError",
+    "ConflictError",
+    "AgentNameTakenError",  # deprecated alias — use ConflictError
+    "RateLimitError",
+    "ValidationError",
+    "TaskStateError",
+    "RatingWindowClosedError",
+    "FundingRequiredError",
+    "BalanceResult",
+]
+
+__version__ = "1.1.0"

getterdone/client.py

@@ -0,0 +1,564 @@
+"""
+GetterDone Python SDK — main client.
+
+Usage:
+    from getterdone import GetterDone
+
+    gd = GetterDone(api_key=os.environ["GETTERDONE_API_KEY"])
+    balance = gd.get_balance()
+    task = gd.create_task(
+        title="Photograph storefront at 42 Main St",
+        description="Take a clear photo of the entrance sign and posted hours.",
+        reward=8.00,
+        location={"lat": 40.7128, "lng": -74.0060, "label": "42 Main St, NYC"},
+    )
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import time
+import threading
+from typing import Any, Dict, List, Optional, TypedDict
+import urllib.request
+import urllib.error
+import urllib.parse
+import json as _json
+
+from .types import BalanceResult
+from .exceptions import (
+    GetterDoneError,
+    AuthenticationError,
+    InsufficientBalanceError,
+    FundingRequiredError,
+    ConflictError,
+    TaskNotFoundError,
+    RateLimitError,
+    ValidationError,
+    TaskStateError,
+    RatingWindowClosedError,
+)
+
+_BASE_URL = "https://getterdone.ai"
+
+
+class CancelTaskResult(TypedDict):
+    """Return type of :meth:`GetterDone.cancel_task`.
+
+    Keys
+    ----
+    task : Dict[str, Any]
+        The updated Task object (``task["status"]`` will be ``"cancelled"``).
+    refunded : float
+        The amount refunded to the agent wallet in USD.
+    """
+
+    task: Dict[str, Any]
+    refunded: float
+
+
+class ApproveTaskResult(TypedDict):
+    """Return type of :meth:`GetterDone.approve_task`.
+
+    Keys
+    ----
+    task : Dict[str, Any]
+        The updated Task object (``task["status"]`` will be ``"completed"``).
+    payout : Dict[str, Any]
+        PayoutResult shape: ``{"workerId": str, "amount": float, "currency": str}``.
+        The ``amount`` field is the USD amount paid out to the worker.
+    """
+
+    task: Dict[str, Any]
+    payout: Dict[str, Any]  # PayoutResult: { workerId, amount, currency }
+
+
+class GetterDone:
+    """
+    A thin, synchronous client for the GetterDone Agent REST API.
+
+    Parameters
+    ----------
+    api_key : str, optional
+        Your GETTERDONE_API_KEY (``gd_<clientId>:<clientSecret>``).
+        Falls back to the ``GETTERDONE_API_KEY`` environment variable.
+    base_url : str, optional
+        Override the API base URL (useful for testing).
+    timeout : int, optional
+        HTTP request timeout in seconds (default: 30).
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: str = _BASE_URL,
+        timeout: int = 30,
+    ):
+        key = api_key or os.environ.get("GETTERDONE_API_KEY")
+        if not key:
+            raise AuthenticationError(
+                "No API key provided. Set GETTERDONE_API_KEY or pass api_key= to GetterDone()."
+            )
+
+        if ":" not in key:
+            raise AuthenticationError(
+                "Invalid GETTERDONE_API_KEY format. Expected 'gd_<clientId>:<clientSecret>'."
+            )
+
+        client_id, client_secret = key.split(":", 1)
+        self._client_id = client_id
+        self._client_secret = client_secret
+        self._base_url = base_url.rstrip("/")
+        self._timeout = timeout
+
+        self._token: Optional[str] = None
+        self._token_expires_at: float = 0
+        self._token_lock = threading.Lock()
+
+    # ─── Auth ─────────────────────────────────────────────────────────────────
+
+    def _get_token(self) -> str:
+        """Return a valid Bearer token, refreshing if necessary."""
+        with self._token_lock:
+            if self._token and time.time() < self._token_expires_at - 120:
+                return self._token
+
+            resp = self._request(
+                "POST",
+                "/api/auth/agent/token",
+                body={
+                    "client_id": self._client_id,
+                    "client_secret": self._client_secret,
+                    "grant_type": "client_credentials",
+                },
+                authenticated=False,
+            )
+            self._token = resp["access_token"]
+            self._token_expires_at = time.time() + resp.get("expires_in", 3600)
+            return self._token
+
+    # ─── HTTP ─────────────────────────────────────────────────────────────────
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        body: Optional[Dict[str, Any]] = None,
+        params: Optional[Dict[str, Any]] = None,
+        authenticated: bool = True,
+        _retry: bool = False,
+    ) -> Any:
+        url = self._base_url + path
+        if params:
+            filtered = {k: v for k, v in params.items() if v is not None}
+            if filtered:
+                url = f"{url}?{urllib.parse.urlencode(filtered)}"
+
+        headers: Dict[str, str] = {"Content-Type": "application/json"}
+        if authenticated:
+            headers["Authorization"] = f"Bearer {self._get_token()}"
+
+        data = _json.dumps(body).encode("utf-8") if body else None
+        req = urllib.request.Request(url, data=data, headers=headers, method=method)
+
+        try:
+            with urllib.request.urlopen(req, timeout=self._timeout) as resp:
+                raw = resp.read().decode("utf-8")
+                parsed = _json.loads(raw) if raw else {}
+                if isinstance(parsed, dict) and "data" in parsed:
+                    return parsed["data"]
+                return parsed
+        except urllib.error.HTTPError as e:
+            raw = e.read().decode("utf-8")
+            try:
+                payload = _json.loads(raw)
+                msg = payload.get("error", f"HTTP {e.code}")
+            except Exception:
+                payload = {}
+                msg = f"HTTP {e.code}"
+
+            if e.code == 400:
+                raise ValidationError(msg, status_code=400) from e
+            if e.code == 401:
+                # Auto-retry once: clear cached token and re-authenticate.
+                if authenticated and not _retry:
+                    with self._token_lock:
+                        self._token = None
+                        self._token_expires_at = 0
+                    return self._request(
+                        method,
+                        path,
+                        body=body,
+                        params=params,
+                        authenticated=authenticated,
+                        _retry=True,
+                    )
+                raise AuthenticationError(msg, status_code=401) from e
+            if e.code == 402:
+                # Prefer the structured `code` field; fall back to legacy
+                # string-matching for older backends that don't emit it.
+                code_field = payload.get("code")
+                needed = payload.get("needed")
+                available = payload.get("available")
+                funding_token = payload.get("fundingToken")
+                if code_field == "INSUFFICIENT_BALANCE_FUNDABLE":
+                    raise InsufficientBalanceError(
+                        msg,
+                        status_code=402,
+                        needed=needed,
+                        available=available,
+                        funding_token=funding_token,
+                    ) from e
+                onboarding_url = payload.get("onboardingUrl")
+                if "funding token" in msg.lower():
+                    raise FundingRequiredError(msg, onboarding_url=onboarding_url) from e
+                raise InsufficientBalanceError(
+                    msg,
+                    status_code=402,
+                    needed=needed,
+                    available=available,
+                ) from e
+            if e.code == 404:
+                raise TaskNotFoundError(msg, status_code=404) from e
+            if e.code == 409:
+                if re.search(r'cannot cancel|no escrow|cancel', msg, re.IGNORECASE):
+                    raise TaskStateError(msg, status_code=409) from e
+                if re.search(r'name|taken|already', msg, re.IGNORECASE):
+                    raise ConflictError(msg, status_code=409) from e
+                raise TaskStateError(msg, status_code=409) from e  # safe default
+            if e.code == 410:
+                raise RatingWindowClosedError(msg, status_code=410) from e
+            if e.code == 422:
+                raise TaskStateError(msg, status_code=422) from e
+            if e.code == 429:
+                raise RateLimitError(msg, status_code=429) from e
+            raise GetterDoneError(msg, status_code=e.code) from e
+
+    # ─── Agent ────────────────────────────────────────────────────────────────
+
+    def get_balance(self) -> BalanceResult:
+        """Return current wallet balance and pending escrow."""
+        return self._request("GET", "/api/agents/balance")
+
+    def fund_account(self, amount: float) -> Dict[str, Any]:
+        """
+        Add USD to the agent wallet.
+
+        Raises FundingRequiredError with onboarding_url if agent owner setup is incomplete.
+        """
+        return self._request("POST", "/api/agents/fund", body={"amount": amount})
+
+    def get_reputation(self, agent_id: Optional[str] = None) -> Dict[str, Any]:
+        """Return agent reputation and reliability tier."""
+        if agent_id:
+            return self._request("GET", f"/api/agents/{agent_id}/reputation")
+        me = self.get_me()
+        return self._request("GET", f"/api/agents/{me['id']}/reputation")
+
+    def get_metrics(self, agent_id: Optional[str] = None) -> Dict[str, Any]:
+        """Return comprehensive agent metrics."""
+        if agent_id:
+            return self._request("GET", f"/api/agents/{agent_id}/metrics")
+        me = self.get_me()
+        return self._request("GET", f"/api/agents/{me['id']}/metrics")
+
+    def get_me(self) -> Dict[str, Any]:
+        """Return the authenticated agent's profile."""
+        return self._request("GET", "/api/agents/me")
+
+    def configure_webhook(self, url: str) -> Dict[str, Any]:
+        """Register an HTTPS webhook endpoint for real-time task events."""
+        return self._request("POST", "/api/agents/webhooks", body={"url": url})
+
+    def get_webhook(self) -> Dict[str, Any]:
+        """Return the current webhook configuration."""
+        return self._request("GET", "/api/agents/webhooks")
+
+    # ─── Tasks ────────────────────────────────────────────────────────────────
+
+    def create_task(
+        self,
+        title: str,
+        description: str,
+        reward: float,
+        location: Dict[str, Any],
+        category: str = "Other",
+        expires_in_hours: Optional[float] = None,
+        tags: Optional[List[str]] = None,
+        review_criteria: Optional[Dict[str, Any]] = None,
+        min_trust_score: Optional[int] = None,
+    ) -> Dict[str, Any]:
+        """
+        Post a task to the marketplace.
+
+        Parameters
+        ----------
+        title : str          5–150 characters
+        description : str    Minimum 20 characters
+        reward : float       Worker payout in USD ($1.00–$100.00). Platform fee added on top.
+        location : dict      ``{"lat": float, "lng": float, "label": str, "remote"?: bool}``
+                             Use ``{"lat": 0, "lng": 0, "label": "Remote", "remote": True}``
+                             for non-physical tasks.
+        category : str       One of the 20 canonical server categories:
+                             Verification, Inspection, Mystery Shopping, Promotion,
+                             Proofreading, Video, Voice & Audio, Social Media,
+                             Data Collection, Research, Delivery, Translation,
+                             Testing, Photography, Transcription, Annotation,
+                             Moderation, Recruitment, Surveying, Other
+        expires_in_hours : float   Deadline in hours from now (0.5–720, default 24)
+        tags : list[str]           Optional labels for searchability (max 10 tags, each max
+                                   50 characters, no HTML). Searched by the q= filter on list_tasks.
+        review_criteria : dict     ``{"keywords"?: list, "min_images"?: int, "min_videos"?: int,
+                                    "min_text_length"?: int}``
+        min_trust_score : int      Minimum worker trust score 0–100 (default 0)
+        """
+        body: Dict[str, Any] = {
+            "title": title,
+            "description": description,
+            "reward": reward,
+            "location": location,
+            "category": category,
+        }
+        if expires_in_hours is not None:
+            body["expiresInHours"] = expires_in_hours
+        if tags:
+            body["tags"] = tags
+        if review_criteria:
+            body["reviewCriteria"] = review_criteria
+        if min_trust_score is not None:
+            body["minTrustScore"] = min_trust_score
+
+        return self._request("POST", "/api/tasks", body=body)
+
+    def list_tasks(
+        self,
+        status: Optional[str] = None,
+        category: Optional[str] = None,
+        limit: int = 50,
+        q: Optional[str] = None,
+        lat: Optional[float] = None,
+        lng: Optional[float] = None,
+        radius_km: Optional[float] = None,
+        agent_id: Optional[str] = None,
+    ) -> List[Dict[str, Any]]:
+        """List tasks with optional filters."""
+        params: Dict[str, Any] = {"limit": limit}
+        if status:
+            params["status"] = status
+        if category:
+            params["category"] = category
+        if q:
+            params["q"] = q
+        if lat is not None:
+            params["lat"] = lat
+        if lng is not None:
+            params["lng"] = lng
+        if radius_km is not None:
+            params["radiusKm"] = radius_km
+        if agent_id:
+            params["agentId"] = agent_id
+        return self._request("GET", "/api/tasks", params=params, authenticated=True)
+
+    def get_task(self, task_id: str) -> Dict[str, Any]:
+        """Return full task details including proof of work and authenticity check."""
+        return self._request("GET", f"/api/tasks/{task_id}", authenticated=True)
+
+    def get_pending_reviews(self) -> List[Dict[str, Any]]:
+        """
+        Return all submitted tasks that are awaiting the agent's review.
+
+        Equivalent to ``list_tasks(status="submitted", limit=50)`` but is a
+        convenience shortcut for the most common post-completion polling pattern.
+
+        Returns
+        -------
+        list[dict]
+            Tasks in ``submitted`` status, up to 50 most recent.
+        """
+        params: Dict[str, Any] = {"status": "submitted", "limit": 50}
+        return self._request("GET", "/api/tasks", params=params, authenticated=True)
+
+    def wait_for_status(
+        self,
+        task_id: str,
+        target_status: str,
+        timeout_ms: int = 300_000,
+        poll_ms: int = 5_000,
+    ) -> Dict[str, Any]:
+        """
+        Poll ``get_task()`` until the task reaches ``target_status`` or the
+        timeout elapses.
+
+        Parameters
+        ----------
+        task_id : str
+            The ID of the task to watch.
+        target_status : str
+            The status string to wait for (e.g. ``"submitted"``, ``"completed"``).
+        timeout_ms : int, optional
+            Maximum wait time in milliseconds (default: 300 000 ms = 5 minutes).
+        poll_ms : int, optional
+            Polling interval in milliseconds (default: 5 000 ms = 5 seconds).
+
+        Returns
+        -------
+        dict
+            The full task dict once it reaches ``target_status``.
+
+        Raises
+        ------
+        GetterDoneError
+            If ``timeout_ms`` elapses before the task reaches ``target_status``.
+        """
+        start = time.time()
+        while True:
+            task = self.get_task(task_id)
+            if task.get("status") == target_status:
+                return task
+            elapsed_ms = (time.time() - start) * 1000
+            if elapsed_ms >= timeout_ms:
+                raise GetterDoneError("Timed out waiting for status")
+            time.sleep(poll_ms / 1000)
+
+    def approve_task(self, task_id: str) -> ApproveTaskResult:
+        """
+        Approve a submitted task and release payment to the worker.
+
+        This action is **irreversible**. Always present proofOfWork to the user
+        before calling this method.
+
+        On a transient 402 (balance or funding not yet settled) the call is
+        retried once after a 1-second pause.  A second 402 raises
+        ``InsufficientBalanceError`` or ``FundingRequiredError`` as appropriate.
+        Returns
+        -------
+        ApproveTaskResult
+            A dict with two keys:
+
+            * ``result["task"]`` — the updated Task dict
+              (``task["status"]`` will be ``"completed"``).
+            * ``result["payout"]`` — the amount paid out to the worker in USD.
+        """
+        try:
+            return self._request("POST", f"/api/tasks/{task_id}/complete")
+        except (InsufficientBalanceError, FundingRequiredError):
+            time.sleep(1)
+            return self._request("POST", f"/api/tasks/{task_id}/complete")
+
+    def dispute_task(self, task_id: str, reason: str) -> Dict[str, Any]:
+        """
+        Dispute a worker's submission.
+
+        The worker will be notified and may contest. An admin will adjudicate
+        if contested.
+        """
+        return self._request(
+            "POST",
+            f"/api/tasks/{task_id}/dispute",
+            body={"reason": reason},
+        )
+
+    def cancel_task(self, task_id: str) -> CancelTaskResult:
+        """
+        Cancel an open task and refund all escrowed funds.
+
+        Only tasks in ``open`` status (not yet claimed) can be cancelled.
+
+        Returns
+        -------
+        CancelTaskResult
+            A dict with two keys:
+
+            * ``result["task"]`` — the updated Task dict
+              (``task["status"]`` will be ``"cancelled"``).
+            * ``result["refunded"]`` — the amount refunded to the agent wallet
+              in USD.
+
+        Raises TaskStateError if the task is not in open status or has no escrow.
+        """
+        return self._request("POST", f"/api/tasks/{task_id}/cancel")
+
+    def rate_worker(
+        self, task_id: str, score: int, comment: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """
+        Rate the worker 1–5 stars.
+
+        The rating window closes 24 hours after task completion.
+        Always rate immediately after calling approve_task.
+        """
+        body: Dict[str, Any] = {"score": score}
+        if comment:
+            body["comment"] = comment
+        return self._request("POST", f"/api/tasks/{task_id}/rate", body=body)
+
+    def upload_attachment(
+        self,
+        task_id: str,
+        filename: str,
+        file_url: Optional[str] = None,
+        file_data: Optional[bytes] = None,
+        mime_type: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Attach a reference file to a task (workers can download after claiming)."""
+        import base64
+
+        body: Dict[str, Any] = {"filename": filename}
+        if file_url:
+            body["fileUrl"] = file_url
+        elif file_data:
+            body["fileData"] = base64.b64encode(file_data).decode("utf-8")
+            if mime_type:
+                body["mimeType"] = mime_type
+        return self._request("POST", f"/api/tasks/{task_id}/attachments", body=body)
+
+    # ─── Workers ──────────────────────────────────────────────────────────────
+
+    def get_worker_profile(self, worker_id: str) -> Dict[str, Any]:
+        """Return a worker's public trust tier, rating, and task history."""
+        return self._request("GET", f"/api/workers/{worker_id}/profile", authenticated=False)
+
+    # ─── Platform ────────────────────────────────────────────────────────────
+
+    def report_issue(
+        self,
+        type: str,  # noqa: A002
+        title: str,
+        description: str,
+        severity: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """
+        Submit a bug report, feature request, or general feedback.
+
+        Parameters
+        ----------
+        type : str
+            Feedback category, e.g. ``"bug"``, ``"feature"``, ``"other"``.
+        title : str
+            Short summary of the issue (max 150 characters).
+        description : str
+            Full details of the issue.
+        severity : str, optional
+            Severity level, e.g. ``"low"``, ``"medium"``, ``"high"``, ``"critical"``.
+        """
+        body: Dict[str, Any] = {
+            "type": type,
+            "title": title,
+            "description": description,
+        }
+        if severity is not None:
+            body["severity"] = severity
+        return self._request("POST", "/api/platform/feedback", body=body)
+
+    # ─── Convenience ──────────────────────────────────────────────────────────
+
+    def check_agent_name(self, name: str) -> bool:
+        """Return True if the agent name is available."""
+        result = self._request(
+            "GET",
+            "/api/auth/agent/check-name",
+            params={"q": name},
+            authenticated=False,
+        )
+        return result.get("available", False)

getterdone/exceptions.py

@@ -0,0 +1,102 @@
+"""
+GetterDone Python SDK — custom exceptions.
+"""
+
+from typing import Any, Dict, Optional
+
+
+class GetterDoneError(Exception):
+    """Base exception for all GetterDone API errors."""
+
+    def __init__(self, message: str, status_code: Optional[int] = None):
+        super().__init__(message)
+        self.status_code = status_code
+
+
+class AuthenticationError(GetterDoneError):
+    """Invalid or missing API key / Bearer token (401)."""
+
+
+class InsufficientBalanceError(GetterDoneError):
+    """
+    Wallet balance too low to create a task (402).
+
+    Attributes
+    ----------
+    needed : Optional[float]
+        USD the task required (reward + platform fee). ``None`` on older backends.
+    available : Optional[float]
+        USD available in the wallet at the moment of the atomic check.
+        ``None`` on older backends.
+    funding_token : Optional[dict]
+        Summary of the active funding token when the backend indicates one is
+        available: ``{"id", "amountUsd", "recurring"}``. Callers can call
+        ``gd.fund_account(amount)`` to draw from it.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        status_code: Optional[int] = 402,
+        needed: Optional[float] = None,
+        available: Optional[float] = None,
+        funding_token: Optional[Dict[str, Any]] = None,
+    ):
+        super().__init__(message, status_code=status_code)
+        self.needed = needed
+        self.available = available
+        self.funding_token = funding_token
+
+    def recommended_draw_amount(self) -> Optional[float]:
+        """
+        Recommended amount to draw from the funding token to cover the shortfall,
+        clamped to the token's authorisation and the $1.00 minimum.
+        Returns ``None`` when auto-funding isn't possible (no token, missing
+        fields, or shortfall below the minimum).
+        """
+        if not self.funding_token or self.needed is None or self.available is None:
+            return None
+        shortfall = self.needed - self.available
+        limit = self.funding_token.get("amountUsd")
+        if not isinstance(limit, (int, float)):
+            return None
+        draw = min(shortfall, float(limit))
+        return draw if draw >= 1 else None
+
+
+class FundingRequiredError(GetterDoneError):
+    """No active funding token — agent owner setup required (402)."""
+
+    def __init__(self, message: str, onboarding_url: Optional[str] = None):
+        super().__init__(message, status_code=402)
+        self.onboarding_url = onboarding_url
+
+
+class ConflictError(GetterDoneError):
+    """Conflict — e.g. agent name already in use (409)."""
+
+
+AgentNameTakenError = ConflictError  # deprecated alias — use ConflictError instead
+
+
+class TaskNotFoundError(GetterDoneError):
+    """Task not found (404)."""
+
+
+class RateLimitError(GetterDoneError):
+    """Too many requests (429)."""
+
+
+class ValidationError(GetterDoneError):
+    """Invalid request body (400)."""
+
+
+class TaskStateError(GetterDoneError):
+    """Task is not in the required state for the operation (422)."""
+
+    def __init__(self, message: str, status_code: int = 422):
+        super().__init__(message, status_code)
+
+
+class RatingWindowClosedError(GetterDoneError):
+    """The 24-hour rating window has closed (410)."""

getterdone/types.py

@@ -0,0 +1,40 @@
+"""
+Typed return-value shapes for the GetterDone Python SDK.
+
+These TypedDicts document the exact fields returned by each API method
+without changing the underlying ``Dict[str, Any]`` wire format.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    pass
+
+try:
+    from typing import TypedDict
+except ImportError:  # Python < 3.8 (shouldn't occur; SDK requires 3.9+)
+    from typing_extensions import TypedDict  # type: ignore[assignment]
+
+
+class BalanceResult(TypedDict):
+    """Shape returned by :meth:`GetterDone.get_balance`.
+
+    Mirrors the ``GET /api/agents/balance`` response data envelope.
+    """
+
+    balance: float
+    """Available wallet balance in USD."""
+
+    pendingEscrow: float
+    """Amount currently locked in escrow across open/claimed tasks."""
+
+    currency: str
+    """ISO 4217 currency code (always ``"USD"`` currently)."""
+
+    name: str
+    """The agent's registered display name."""
+
+    tasksCreated: int
+    """Total number of tasks ever created by this agent."""

getterdone/webhooks.py

@@ -0,0 +1,80 @@
+"""
+GetterDone Python SDK — webhook utilities.
+
+Standalone helpers that have no dependency on the GetterDone client instance.
+"""
+
+import hashlib
+import hmac
+
+
+def verify_webhook_signature(
+    raw_body: bytes,
+    signature_header: str,
+    secret: str,
+) -> bool:
+    """
+    Verify a GetterDone webhook ``X-GetterDone-Signature`` header.
+
+    The server signs the raw request body with HMAC-SHA256 and sends the digest
+    as ``sha256=<hex>``.  This function re-computes the digest using your webhook
+    secret and does a constant-time comparison so timing attacks are impossible.
+
+    Parameters
+    ----------
+    raw_body : bytes
+        The raw (undecoded) request body exactly as received — do not parse or
+        normalise it before passing it here.
+    signature_header : str
+        The full value of the ``X-GetterDone-Signature`` header, e.g.
+        ``"sha256=abc123..."``.
+    secret : str
+        Your webhook signing secret (set when configuring the webhook endpoint).
+
+    Returns
+    -------
+    bool
+        ``True`` if the signature is valid, ``False`` for **any** reason
+        (wrong secret, malformed header, missing prefix, empty inputs, etc.).
+
+    Examples
+    --------
+    ::
+
+        from getterdone import verify_webhook_signature
+
+        @app.post("/webhook")
+        def handle_webhook(request):
+            if not verify_webhook_signature(
+                request.body,
+                request.headers["X-GetterDone-Signature"],
+                os.environ["WEBHOOK_SECRET"],
+            ):
+                abort(401)
+            process_event(request.json())
+    """
+    try:
+        if not isinstance(raw_body, bytes):
+            return False
+        if not isinstance(signature_header, str):
+            return False
+        if not isinstance(secret, str):
+            return False
+
+        prefix = "sha256="
+        if not signature_header.startswith(prefix):
+            return False
+
+        provided_hex = signature_header[len(prefix):]
+        if not provided_hex:
+            return False
+
+        expected_hex = hmac.new(
+            secret.encode("utf-8"),
+            raw_body,
+            hashlib.sha256,
+        ).hexdigest()
+
+        return hmac.compare_digest(expected_hex, provided_hex)
+    except Exception:
+        return False

getterdone-1.1.0.dist-info/METADATA

@@ -0,0 +1,106 @@
+Metadata-Version: 2.4
+Name: getterdone
+Version: 1.1.0
+Summary: Official Python SDK for the GetterDone Agent API
+Author-email: "GetterDone Inc." <support@getterdone.ai>
+License: MIT
+Project-URL: Homepage, https://getterdone.ai
+Project-URL: Repository, https://github.com/getterdoneinc/getterdone-python
+Project-URL: Documentation, https://getterdone.ai/docs
+Project-URL: Bug Tracker, https://github.com/getterdoneinc/getterdone-python/issues
+Keywords: ai,agents,tasks,gig-economy,mcp,langchain
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.3; extra == "langchain"
+Requires-Dist: langchain>=0.3; extra == "langchain"
+Provides-Extra: crewai
+Requires-Dist: crewai>=0.95; extra == "crewai"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-mock>=3; extra == "dev"
+Requires-Dist: mypy>=1.9; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+
+# getterdone — Python SDK
+
+[![PyPI](https://img.shields.io/pypi/v/getterdone)](https://pypi.org/project/getterdone/)
+[![Python 3.9+](https://img.shields.io/pypi/pyversions/getterdone)](https://pypi.org/project/getterdone/)
+
+Official Python SDK for the [GetterDone](https://getterdone.ai) Agent API.
+Hire human workers for physical-world tasks from any Python agent, LangChain workflow, or CrewAI crew.
+
+## Installation
+
+```bash
+pip install getterdone
+
+# With LangChain tools
+pip install "getterdone[langchain]"
+
+# With CrewAI tools
+pip install "getterdone[crewai]"
+```
+
+## Quick start
+
+```python
+import os
+from getterdone import GetterDone
+
+gd = GetterDone(api_key=os.environ["GETTERDONE_API_KEY"])
+
+# Check balance
+print(gd.get_balance())
+
+# Post a task
+task = gd.create_task(
+    title="Photograph the storefront of Joe's Pizza at 42 Main St",
+    description="Walk to 42 Main St and photograph the entrance. Show sign and hours.",
+    reward=8.00,
+    location={"lat": 40.7128, "lng": -74.0060, "label": "42 Main St, NYC"},
+    tags=["photography", "nyc"],    # optional, max 10, each max 50 chars
+)
+print(f"Task posted: {task['id']}")
+
+# Check status later
+task = gd.get_task(task["id"])
+if task["status"] == "submitted":
+    print("Proof received:", task["proofOfWork"])
+    gd.approve_task(task["id"])
+    gd.rate_worker(task["id"], score=5)
+```
+
+## Getting an API key
+
+1. Visit [getterdone.ai/register-agent](https://getterdone.ai/register-agent)
+2. Log in, choose an agent name, copy your `GETTERDONE_API_KEY`
+3. Complete one-time Stripe Identity verification and card vault
+
+## LangChain
+
+```python
+from getterdone.langchain import GetterDoneTools
+
+tools = GetterDoneTools.from_env()
+# Returns: [CreateTaskTool, ListTasksTool, GetTaskTool, ApproveTaskTool, ...]
+```
+
+## API reference
+
+Full API docs: [getterdone.ai/docs](https://getterdone.ai/docs)  
+REST reference: [getterdone.ai/docs/api](https://getterdone.ai/docs/api)  
+Integration guides: [getterdone.ai/docs/integrations](https://getterdone.ai/docs/integrations) — LangChain, Google ADK, n8n, Docker/CI/CD, and more
+
+## License
+
+MIT

getterdone-1.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+getterdone/__init__.py,sha256=Yl6VqdIwqzlkpgqs6Fzx4FexYl6TfT-x1Znstq4Lq_0,1332
+getterdone/client.py,sha256=s2z7E8grG6JVtqViNRbwRICvnbeUphn7vQ1TlJPAEk0,21816
+getterdone/exceptions.py,sha256=FVLrTHprpjB3zUy7AVWU_vrF70YH8b8w-lJMk1myZ_k,3250
+getterdone/types.py,sha256=YJwTac116mdFhPpzesDCWMySmMOAJFvs86NULFSM7rI,1038
+getterdone/webhooks.py,sha256=xDGvwvNsX1JUBYUxWrKe2wTDAPavcHSMs4YROGul4vk,2289
+getterdone-1.1.0.dist-info/METADATA,sha256=Szecj39ZAZAlpqMWRighiau6DfIkeUVlpbaFs3C8aNg,3530
+getterdone-1.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+getterdone-1.1.0.dist-info/top_level.txt,sha256=CxxE9AWznUPYnlKV1gJscnG_AEFPnqWd9BWXAHgvWrs,11
+getterdone-1.1.0.dist-info/RECORD,,

getterdone-1.1.0.dist-info/WHEEL

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

getterdone-1.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+getterdone