clawpro 0.1.0__py3-none-any.whl

clawpro/__init__.py

@@ -0,0 +1,304 @@
+"""Official Python SDK for the ClawPro Instagram outbound API.
+
+    from clawpro import ClawPro
+    clawpro = ClawPro(api_key="sk_live_...")
+    for account in clawpro.accounts.list():
+        print(account["username"], account["status"])
+"""
+from __future__ import annotations
+
+import random
+import time
+from typing import Any, Dict, Iterator, List, Optional, TypedDict
+
+import httpx
+
+__version__ = "0.1.0"
+__all__ = ["ClawPro", "ClawProError"]
+
+DEFAULT_BASE_URL = "https://api.tryclawpro.com"
+
+
+# ─────────────────────────────── Types ───────────────────────────────────────
+class Account(TypedDict, total=False):
+    id: str
+    username: str
+    status: str
+    warmupTier: int
+    dailyDmCap: int
+
+
+class Campaign(TypedDict, total=False):
+    id: str
+    accountId: str
+    name: str
+    status: str
+    targets: List[Dict[str, Any]]
+    offer: str
+    icpCriteria: str
+    dailyDmTarget: int
+
+
+class Lead(TypedDict, total=False):
+    id: str
+    igUsername: str
+    fullName: Optional[str]
+    sourceTargetUsername: str
+    engagementType: str
+    score: Optional[int]
+    scoreReason: Optional[str]
+    status: str
+    messages: List[Dict[str, Any]]
+
+
+class Webhook(TypedDict, total=False):
+    id: str
+    label: str
+    url: str
+    type: str
+    events: List[str]
+    active: bool
+    lastStatus: Optional[int]
+    secret: str
+
+
+class ApiKey(TypedDict, total=False):
+    id: str
+    name: str
+    environment: str
+    access: str
+    keyPrefix: str
+    createdAt: str
+    expiresAt: Optional[str]
+    lastUsedAt: Optional[str]
+
+
+class UsageSummary(TypedDict):
+    callsThisMonth: int
+    calls24h: int
+    errors: int
+    avgLatencyMs: int
+
+
+class RequestLog(TypedDict, total=False):
+    id: str
+    requestId: str
+    method: str
+    path: str
+    status: int
+    latencyMs: int
+    error: Optional[str]
+    createdAt: str
+    keyName: Optional[str]
+    keyPrefix: Optional[str]
+
+
+class ClawProError(Exception):
+    """Raised for any non-2xx API response."""
+
+    def __init__(self, message: str, status: int, code: str = "error", request_id: Optional[str] = None):
+        super().__init__(message)
+        self.status = status
+        self.code = code
+        self.request_id = request_id
+
+
+# ───────────────────────────── Resources ─────────────────────────────────────
+class _Resource:
+    def __init__(self, client: "ClawPro") -> None:
+        self._c = client
+
+
+class _Accounts(_Resource):
+    def list(self) -> List[Account]:
+        return self._c._request("GET", "/accounts")["accounts"]
+
+    def create(self, username: str, *, country: Optional[str] = None, proxy_type: Optional[str] = None,
+               proxy_url: Optional[str] = None, timezone: Optional[str] = None) -> Account:
+        body: Dict[str, Any] = {"username": username}
+        if country:
+            body["country"] = country
+        if proxy_type:
+            body["proxyType"] = proxy_type
+        if proxy_url:
+            body["proxyUrl"] = proxy_url
+        if timezone:
+            body["timezone"] = timezone
+        return self._c._request("POST", "/accounts", json=body)["account"]
+
+    def delete(self, account_id: str) -> None:
+        self._c._request("DELETE", f"/accounts/{account_id}")
+
+
+class _Campaigns(_Resource):
+    def list(self) -> List[Campaign]:
+        return self._c._request("GET", "/campaigns")["campaigns"]
+
+    def create(self, *, account_id: str, name: str, targets: List[str], offer: Optional[str] = None,
+               icp_criteria: Optional[str] = None, daily_dm_target: Optional[int] = None) -> Campaign:
+        body: Dict[str, Any] = {"accountId": account_id, "name": name, "targets": targets}
+        if offer is not None:
+            body["offer"] = offer
+        if icp_criteria is not None:
+            body["icpCriteria"] = icp_criteria
+        if daily_dm_target is not None:
+            body["dailyDmTarget"] = daily_dm_target
+        return self._c._request("POST", "/campaigns", json=body)["campaign"]
+
+    def run(self, campaign_id: str) -> Dict[str, int]:
+        return self._c._request("POST", f"/campaigns/{campaign_id}/run")
+
+    def leads(self, campaign_id: str, *, status: Optional[str] = None) -> List[Lead]:
+        params = {"status": status} if status else None
+        return self._c._request("GET", f"/campaigns/{campaign_id}/leads", params=params)["leads"]
+
+    def inbox(self, campaign_id: str) -> List[Lead]:
+        return self._c._request("GET", f"/campaigns/{campaign_id}/inbox")["threads"]
+
+
+class _Leads(_Resource):
+    def update(self, lead_id: str, *, status: str) -> Lead:
+        """Advance a lead, e.g. status='booked' (fires the lead.booked webhook)."""
+        return self._c._request("PATCH", f"/leads/{lead_id}", json={"status": status})["lead"]
+
+
+class _Webhooks(_Resource):
+    def events(self) -> List[str]:
+        return self._c._request("GET", "/webhooks/events")["events"]
+
+    def list(self) -> List[Webhook]:
+        return self._c._request("GET", "/webhooks")["webhooks"]
+
+    def create(self, url: str, *, events: Optional[List[str]] = None, type: str = "generic",
+               label: Optional[str] = None) -> Webhook:
+        body: Dict[str, Any] = {"url": url, "type": type, "events": events or ["*"]}
+        if label:
+            body["label"] = label
+        return self._c._request("POST", "/webhooks", json=body)["webhook"]
+
+    def delete(self, webhook_id: str) -> None:
+        self._c._request("DELETE", f"/webhooks/{webhook_id}")
+
+    def test(self, webhook_id: str) -> Any:
+        return self._c._request("POST", f"/webhooks/{webhook_id}/test")
+
+
+class _Keys(_Resource):
+    def list(self) -> List[ApiKey]:
+        return self._c._request("GET", "/keys")["keys"]
+
+    def create(self, name: str, *, environment: Optional[str] = None, access: Optional[str] = None,
+               expires_at: Optional[str] = None) -> Dict[str, Any]:
+        """Returns {"secret": ..., "key": ApiKey}. The secret is shown only here."""
+        body: Dict[str, Any] = {"name": name}
+        if environment:
+            body["environment"] = environment
+        if access:
+            body["access"] = access
+        if expires_at:
+            body["expiresAt"] = expires_at
+        return self._c._request("POST", "/keys", json=body)
+
+    def revoke(self, key_id: str) -> None:
+        self._c._request("DELETE", f"/keys/{key_id}")
+
+
+class _Usage(_Resource):
+    def summary(self) -> UsageSummary:
+        return self._c._request("GET", "/usage")
+
+    def logs(self, *, key: Optional[str] = None, method: Optional[str] = None, status: Optional[str] = None,
+             from_: Optional[str] = None, to: Optional[str] = None, endpoint: Optional[str] = None,
+             request_id: Optional[str] = None, search: Optional[str] = None,
+             limit: Optional[int] = None, offset: Optional[int] = None) -> List[RequestLog]:
+        params = {
+            "key": key, "method": method, "status": status, "from": from_, "to": to,
+            "endpoint": endpoint, "requestId": request_id, "search": search,
+            "limit": limit, "offset": offset,
+        }
+        params = {k: v for k, v in params.items() if v is not None}
+        return self._c._request("GET", "/logs", params=params)["logs"]
+
+    def iterate_logs(self, *, page_size: int = 100, **filters: Any) -> Iterator[RequestLog]:
+        """Auto-paginate every matching log."""
+        offset = 0
+        while True:
+            page = self.logs(limit=page_size, offset=offset, **filters)
+            for row in page:
+                yield row
+            if len(page) < page_size:
+                return
+            offset += page_size
+
+
+# ─────────────────────────────── Client ──────────────────────────────────────
+class ClawPro:
+    """ClawPro API client.
+
+    Args:
+        api_key: A ``sk_live_…`` / ``sk_test_…`` key (sent as ``X-API-Key``).
+        base_url: API origin (override for staging/self-hosted).
+        max_retries: Retries for transient failures (network, 429, 5xx). Default 2.
+        timeout: Per-request timeout (seconds).
+    """
+
+    def __init__(self, api_key: str, *, base_url: str = DEFAULT_BASE_URL,
+                 max_retries: int = 2, timeout: float = 30.0) -> None:
+        if not api_key:
+            raise ValueError("ClawPro: api_key is required")
+        self._base = base_url.rstrip("/") + "/api/instagram"
+        self._max_retries = max_retries
+        self._http = httpx.Client(
+            timeout=timeout,
+            headers={"X-API-Key": api_key, "Accept": "application/json"},
+        )
+        self.accounts = _Accounts(self)
+        self.campaigns = _Campaigns(self)
+        self.leads = _Leads(self)
+        self.webhooks = _Webhooks(self)
+        self.keys = _Keys(self)
+        self.usage = _Usage(self)
+
+    @staticmethod
+    def _backoff(attempt: int) -> float:
+        return (0.25 * (2 ** attempt)) * (0.8 + random.random() * 0.4)
+
+    def _request(self, method: str, path: str, *, params: Optional[Dict[str, Any]] = None,
+                 json: Optional[Dict[str, Any]] = None) -> Any:
+        url = self._base + path
+        idempotent = method in ("GET", "DELETE", "PUT")
+        attempt = 0
+        while True:
+            try:
+                resp = self._http.request(method, url, params=params, json=json)
+            except httpx.TransportError as exc:
+                if idempotent and attempt < self._max_retries:
+                    time.sleep(self._backoff(attempt))
+                    attempt += 1
+                    continue
+                raise ClawProError(f"Network error: {exc}", 0, "network_error")
+
+            transient = resp.status_code == 429 or resp.status_code >= 500
+            if transient and (resp.status_code == 429 or idempotent) and attempt < self._max_retries:
+                retry_after = resp.headers.get("retry-after")
+                wait = float(retry_after) if retry_after and retry_after.isdigit() else self._backoff(attempt)
+                time.sleep(wait)
+                attempt += 1
+                continue
+
+            data = resp.json() if resp.content else None
+            if resp.status_code >= 400:
+                body = data if isinstance(data, dict) else {}
+                message = body.get("message") or body.get("error") or f"HTTP {resp.status_code}"
+                raise ClawProError(message, resp.status_code, body.get("error", "error"),
+                                   resp.headers.get("x-request-id"))
+            return data
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> "ClawPro":
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()

clawpro-0.1.0.dist-info/METADATA

@@ -0,0 +1,83 @@
+Metadata-Version: 2.4
+Name: clawpro
+Version: 0.1.0
+Summary: Official Python SDK for the ClawPro Instagram outbound API.
+Project-URL: Homepage, https://tryclawpro.com
+Project-URL: Repository, https://github.com/Bojale-Labs/clawpro-python
+Author: ClawPro
+License-Expression: MIT
+License-File: LICENSE
+Keywords: clawpro,dm,instagram,outbound,sdk,tryclawpro
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.8
+Requires-Dist: httpx>=0.24
+Description-Content-Type: text/markdown
+
+# clawpro
+
+Official Python SDK for the **ClawPro** Instagram outbound API — connect sending accounts, run competitor-audience campaigns, score leads, manage webhooks, and read usage.
+
+```bash
+pip install clawpro
+```
+
+Python 3.8+. Get an API key from the [developer portal](https://tryclawpro.com) → **API & Developers → API Keys**.
+
+## Quick start
+
+```python
+import os
+from clawpro import ClawPro, ClawProError
+
+clawpro = ClawPro(api_key=os.environ["CLAWPRO_API_KEY"])
+
+account = clawpro.accounts.create(username="burner_account", country="gb")
+
+campaign = clawpro.campaigns.create(
+    account_id=account["id"],
+    name="Founders engaging with X",
+    targets=["@influencer1"],
+    offer="We help B2B founders book demos via Instagram outbound.",
+    daily_dm_target=20,
+)
+clawpro.campaigns.run(campaign["id"])
+
+# Warm replies → mark a lead booked (fires the lead.booked webhook)
+inbox = clawpro.campaigns.inbox(campaign["id"])
+if inbox:
+    clawpro.leads.update(inbox[0]["id"], status="booked")
+
+print(clawpro.usage.summary())
+
+# Auto-paginate the request log
+for log in clawpro.usage.iterate_logs(page_size=100):
+    ...
+```
+
+## Resources
+
+`accounts`, `campaigns`, `leads`, `webhooks`, `keys`, `usage` — mirroring the REST API. Requests authenticate with `X-API-Key`; transient failures (network, `429` honoring `Retry-After`, `5xx`) are retried with exponential backoff for idempotent calls.
+
+## Errors
+
+```python
+try:
+    clawpro.accounts.create(username="taken_handle")
+except ClawProError as err:
+    print(err.status, err, err.request_id)  # 409 "@taken_handle is already connected"
+```
+
+## Configuration
+
+```python
+ClawPro(api_key="...", base_url="https://api.tryclawpro.com", max_retries=3, timeout=30.0)
+```
+
+It's also a context manager (`with ClawPro(...) as clawpro: ...`) and exposes `.close()`.
+
+## License
+
+MIT

clawpro-0.1.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+clawpro/__init__.py,sha256=FYV1Kr0zwXFFBYxuMxRyQGMGZBCGN0Qf8m7fiYybNKs,10993
+clawpro/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+clawpro-0.1.0.dist-info/METADATA,sha256=oGWiS4CDZLoESjL1li4djnNCv1ZXqttHKkzK80SVdlA,2457
+clawpro-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+clawpro-0.1.0.dist-info/licenses/LICENSE,sha256=_Zx7znszRomQxl_Nhx2gfeUQ11PtgGZQqWplFJa5IvE,1064
+clawpro-0.1.0.dist-info/RECORD,,

clawpro-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

clawpro-0.1.0.dist-info/licenses/LICENSE

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