seoscoreapi 1.3.1__tar.gz → 1.4.0__tar.gz

{seoscoreapi-1.3.1 → seoscoreapi-1.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: seoscoreapi
-Version: 1.3.1
+Version: 1.4.0
 Summary: Python client for SEO Score API — audit any URL for SEO issues with one function call
 Author-email: SEO Score API <info@seoscoreapi.com>
 License: MIT
@@ -83,6 +83,35 @@ add_monitor(
 
 Slack incoming-webhook URLs are auto-formatted as Block Kit messages; any other https endpoint receives the raw event JSON.
 
+## Deep Audits (Pro/Ultra)
+
+A deep, AI-assisted audit scoring a URL across 9 dimensions (~150 AI checks). It
+runs asynchronously — submit, then poll — or use `deep_audit` to block for the result:
+
+```python
+import seoscoreapi as seo
+
+# One call, waits for the result (handles the queue + backpressure for you):
+result = seo.deep_audit(
+    "https://yoursite.com", API_KEY,
+    business_type="saas",                      # tunes which checks apply
+    on_progress=lambda s: print(s["status"], s.get("queue_position", s.get("progress"))),
+)
+print(result["scores"]["lai_score"], result["scores"]["section_scores"])
+
+# Or drive the job yourself:
+job = seo.site_audit("https://yoursite.com", API_KEY)
+status = seo.get_site_audit(job["job_id"], API_KEY)
+# status["status"] -> queued | running | completed | failed
+#   queued  -> {"queue_position", "eta_seconds"}
+#   done    -> {"result"}
+
+seo.engine_usage(API_KEY)     # remaining deep-audit + SERP quota
+```
+
+Deep audits require a **Pro** ($39/mo, 20/mo) or **Ultra** ($99/mo, 100/mo) key.
+Full engine reference: [engine.seoscoreapi.com/docs](https://engine.seoscoreapi.com/docs).
+
 ## Full Documentation
 
 [seoscoreapi.com/docs](https://seoscoreapi.com/docs)

{seoscoreapi-1.3.1 → seoscoreapi-1.4.0}/README.md

@@ -65,6 +65,35 @@ add_monitor(
 
 Slack incoming-webhook URLs are auto-formatted as Block Kit messages; any other https endpoint receives the raw event JSON.
 
+## Deep Audits (Pro/Ultra)
+
+A deep, AI-assisted audit scoring a URL across 9 dimensions (~150 AI checks). It
+runs asynchronously — submit, then poll — or use `deep_audit` to block for the result:
+
+```python
+import seoscoreapi as seo
+
+# One call, waits for the result (handles the queue + backpressure for you):
+result = seo.deep_audit(
+    "https://yoursite.com", API_KEY,
+    business_type="saas",                      # tunes which checks apply
+    on_progress=lambda s: print(s["status"], s.get("queue_position", s.get("progress"))),
+)
+print(result["scores"]["lai_score"], result["scores"]["section_scores"])
+
+# Or drive the job yourself:
+job = seo.site_audit("https://yoursite.com", API_KEY)
+status = seo.get_site_audit(job["job_id"], API_KEY)
+# status["status"] -> queued | running | completed | failed
+#   queued  -> {"queue_position", "eta_seconds"}
+#   done    -> {"result"}
+
+seo.engine_usage(API_KEY)     # remaining deep-audit + SERP quota
+```
+
+Deep audits require a **Pro** ($39/mo, 20/mo) or **Ultra** ($99/mo, 100/mo) key.
+Full engine reference: [engine.seoscoreapi.com/docs](https://engine.seoscoreapi.com/docs).
+
 ## Full Documentation
 
 [seoscoreapi.com/docs](https://seoscoreapi.com/docs)

{seoscoreapi-1.3.1 → seoscoreapi-1.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "seoscoreapi"
-version = "1.3.1"
+version = "1.4.0"
 description = "Python client for SEO Score API — audit any URL for SEO issues with one function call"
 readme = "README.md"
 license = {text = "MIT"}

{seoscoreapi-1.3.1 → seoscoreapi-1.4.0}/seoscoreapi/__init__.py

@@ -17,14 +17,19 @@ Usage:
 Full docs: https://seoscoreapi.com/docs
 """
 
-from typing import Optional
+from __future__ import annotations  # lazy annotations so `list[str]` works on Python 3.8
+
+import time
+from typing import Callable, Optional
 
 import requests
 
 BASE_URL = "https://seoscoreapi.com"
-__version__ = "1.3.1"
+ENGINE_URL = "https://engine.seoscoreapi.com"
+__version__ = "1.4.0"
 
 _HEADERS = {"User-Agent": f"seoscoreapi-python/{__version__}"}
+_TIMEOUT = 30  # seconds — default per-request timeout for engine calls
 
 
 def signup(email: str) -> str:
@@ -130,3 +135,96 @@ def history_domains(api_key: str) -> list:
     r = requests.get(f"{BASE_URL}/history/domains", headers={"X-API-Key": api_key, **_HEADERS})
     r.raise_for_status()
     return r.json()["domains"]
+
+
+# --- Deep Audits (engine.seoscoreapi.com) — Pro/Ultra -----------------------
+
+def site_audit(url: str, api_key: str, **options) -> dict:
+    """Start a Deep Audit (Pro/Ultra). Asynchronous — returns a job
+    ``{"job_id", "status", "poll"}``; poll it with :func:`get_site_audit`.
+
+    Optional keyword args: ``business_type``, ``is_local``,
+    ``connected_integrations``, ``webhook_url``.
+    """
+    r = requests.post(
+        f"{ENGINE_URL}/site-audit",
+        json={"url": url, **options},
+        headers={"X-API-Key": api_key, **_HEADERS},
+        timeout=_TIMEOUT,
+    )
+    r.raise_for_status()
+    return r.json()
+
+
+def get_site_audit(job_id: str, api_key: str) -> dict:
+    """Poll a deep audit job. Returns ``status`` plus ``queue_position``/
+    ``eta_seconds`` while queued, ``progress``/``stage`` while running, and
+    ``result`` when completed (or ``error`` when failed)."""
+    r = requests.get(
+        f"{ENGINE_URL}/site-audit/{job_id}",
+        headers={"X-API-Key": api_key, **_HEADERS},
+        timeout=_TIMEOUT,
+    )
+    r.raise_for_status()
+    return r.json()
+
+
+def deep_audit(
+    url: str,
+    api_key: str,
+    *,
+    poll_interval: float = 5.0,
+    timeout: float = 600.0,
+    on_progress: Optional[Callable[[dict], None]] = None,
+    **options,
+) -> dict:
+    """Start a deep audit and block until it finishes; return the result dict.
+
+    Handles queue backpressure (429 + ``Retry-After``) and honors the server's
+    ETA between polls. Raises ``TimeoutError`` if it doesn't finish within
+    ``timeout`` seconds, or ``RuntimeError`` if the audit fails.
+    """
+    deadline = time.monotonic() + timeout
+    while True:  # submit, retrying on backpressure
+        r = requests.post(
+            f"{ENGINE_URL}/site-audit",
+            json={"url": url, **options},
+            headers={"X-API-Key": api_key, **_HEADERS},
+            timeout=_TIMEOUT,
+        )
+        if r.status_code == 429:
+            retry = float(r.headers.get("Retry-After", 5))
+            if time.monotonic() + retry > deadline:
+                raise TimeoutError("Timed out waiting for queue capacity")
+            time.sleep(retry)
+            continue
+        r.raise_for_status()
+        job = r.json()
+        break
+
+    while True:  # poll to completion
+        if time.monotonic() > deadline:
+            raise TimeoutError("Timed out waiting for audit to complete")
+        status = get_site_audit(job["job_id"], api_key)
+        if on_progress:
+            on_progress(status)
+        state = status.get("status")
+        if state == "completed":
+            return status["result"]
+        if state == "failed":
+            raise RuntimeError(status.get("error", "Audit failed"))
+        if state == "queued" and status.get("eta_seconds"):
+            time.sleep(min(status["eta_seconds"], 15.0))
+        else:
+            time.sleep(poll_interval)
+
+
+def engine_usage(api_key: str) -> dict:
+    """Remaining engine quota (deep audits + SERP) for this key."""
+    r = requests.get(
+        f"{ENGINE_URL}/usage",
+        headers={"X-API-Key": api_key, **_HEADERS},
+        timeout=_TIMEOUT,
+    )
+    r.raise_for_status()
+    return r.json()

{seoscoreapi-1.3.1 → seoscoreapi-1.4.0}/seoscoreapi.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: seoscoreapi
-Version: 1.3.1
+Version: 1.4.0
 Summary: Python client for SEO Score API — audit any URL for SEO issues with one function call
 Author-email: SEO Score API <info@seoscoreapi.com>
 License: MIT
@@ -83,6 +83,35 @@ add_monitor(
 
 Slack incoming-webhook URLs are auto-formatted as Block Kit messages; any other https endpoint receives the raw event JSON.
 
+## Deep Audits (Pro/Ultra)
+
+A deep, AI-assisted audit scoring a URL across 9 dimensions (~150 AI checks). It
+runs asynchronously — submit, then poll — or use `deep_audit` to block for the result:
+
+```python
+import seoscoreapi as seo
+
+# One call, waits for the result (handles the queue + backpressure for you):
+result = seo.deep_audit(
+    "https://yoursite.com", API_KEY,
+    business_type="saas",                      # tunes which checks apply
+    on_progress=lambda s: print(s["status"], s.get("queue_position", s.get("progress"))),
+)
+print(result["scores"]["lai_score"], result["scores"]["section_scores"])
+
+# Or drive the job yourself:
+job = seo.site_audit("https://yoursite.com", API_KEY)
+status = seo.get_site_audit(job["job_id"], API_KEY)
+# status["status"] -> queued | running | completed | failed
+#   queued  -> {"queue_position", "eta_seconds"}
+#   done    -> {"result"}
+
+seo.engine_usage(API_KEY)     # remaining deep-audit + SERP quota
+```
+
+Deep audits require a **Pro** ($39/mo, 20/mo) or **Ultra** ($99/mo, 100/mo) key.
+Full engine reference: [engine.seoscoreapi.com/docs](https://engine.seoscoreapi.com/docs).
+
 ## Full Documentation
 
 [seoscoreapi.com/docs](https://seoscoreapi.com/docs)