seoscoreapi 1.4.0__tar.gz → 1.5.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: seoscoreapi
-Version: 1.4.0
+Version: 1.5.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,10 +83,11 @@ 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)
+## Deep Site Audit (Pro/Ultra, or credits)
 
-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:
+A deep, AI-assisted audit scoring a URL across 9 dimensions (thousands of catalog
+checks plus up to 150 AI checks). It runs asynchronously, so start a job and poll it,
+or use `deep_audit` to block for the result:
 
 ```python
 import seoscoreapi as seo
@@ -100,17 +101,26 @@ result = seo.deep_audit(
 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)
+job = seo.site_audit("https://yoursite.com", API_KEY)       # POST /site-audit
+status = seo.get_site_audit(job["job_id"], API_KEY)         # GET  /site-audit/{job_id}
 # status["status"] -> queued | running | completed | failed
-#   queued  -> {"queue_position", "eta_seconds"}
-#   done    -> {"result"}
+#   queued    -> {"queue_position", "eta_seconds"}
+#   completed -> {"result"}
+result = seo.wait_for_site_audit(job["job_id"], API_KEY, timeout=600)
 
-seo.engine_usage(API_KEY)     # remaining deep-audit + SERP quota
+seo.deep_audit_usage(API_KEY)   # GET /deep-audit/usage -> {"site_audit": {"used", "remaining"}, ...}
 ```
 
-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).
+Deep audits are included on **Pro** ($39/mo, 20/mo) and **Ultra** ($99/mo, 100/mo);
+any other key can run them on purchased credits.
+
+Since 1.5.0 the SDK calls the main host, `https://seoscoreapi.com`, like every other
+endpoint. To point Deep Audit somewhere else (a proxy, staging, or the legacy
+`engine.seoscoreapi.com` host, which still works), pass `base_url=` to any Deep Audit
+function, assign `seoscoreapi.DEEP_AUDIT_URL`, or set `SEOSCORE_DEEP_AUDIT_URL`.
+`engine_usage()` is kept as an alias of `deep_audit_usage()`.
+
+Docs: [seoscoreapi.com/docs](https://seoscoreapi.com/docs) (Deep Site Audit section).
 
 ## Full Documentation
 

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

@@ -65,10 +65,11 @@ 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)
+## Deep Site Audit (Pro/Ultra, or credits)
 
-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:
+A deep, AI-assisted audit scoring a URL across 9 dimensions (thousands of catalog
+checks plus up to 150 AI checks). It runs asynchronously, so start a job and poll it,
+or use `deep_audit` to block for the result:
 
 ```python
 import seoscoreapi as seo
@@ -82,17 +83,26 @@ result = seo.deep_audit(
 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)
+job = seo.site_audit("https://yoursite.com", API_KEY)       # POST /site-audit
+status = seo.get_site_audit(job["job_id"], API_KEY)         # GET  /site-audit/{job_id}
 # status["status"] -> queued | running | completed | failed
-#   queued  -> {"queue_position", "eta_seconds"}
-#   done    -> {"result"}
+#   queued    -> {"queue_position", "eta_seconds"}
+#   completed -> {"result"}
+result = seo.wait_for_site_audit(job["job_id"], API_KEY, timeout=600)
 
-seo.engine_usage(API_KEY)     # remaining deep-audit + SERP quota
+seo.deep_audit_usage(API_KEY)   # GET /deep-audit/usage -> {"site_audit": {"used", "remaining"}, ...}
 ```
 
-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).
+Deep audits are included on **Pro** ($39/mo, 20/mo) and **Ultra** ($99/mo, 100/mo);
+any other key can run them on purchased credits.
+
+Since 1.5.0 the SDK calls the main host, `https://seoscoreapi.com`, like every other
+endpoint. To point Deep Audit somewhere else (a proxy, staging, or the legacy
+`engine.seoscoreapi.com` host, which still works), pass `base_url=` to any Deep Audit
+function, assign `seoscoreapi.DEEP_AUDIT_URL`, or set `SEOSCORE_DEEP_AUDIT_URL`.
+`engine_usage()` is kept as an alias of `deep_audit_usage()`.
+
+Docs: [seoscoreapi.com/docs](https://seoscoreapi.com/docs) (Deep Site Audit section).
 
 ## Full Documentation
 

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "seoscoreapi"
-version = "1.4.0"
+version = "1.5.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.4.0 → seoscoreapi-1.5.0}/seoscoreapi/__init__.py

@@ -19,14 +19,22 @@ Full docs: https://seoscoreapi.com/docs
 
 from __future__ import annotations  # lazy annotations so `list[str]` works on Python 3.8
 
+import os
 import time
 from typing import Callable, Optional
 
 import requests
 
 BASE_URL = "https://seoscoreapi.com"
+# Deep Site Audit is served on the main host (POST /site-audit,
+# GET /site-audit/{job_id}, GET /deep-audit/usage). Override per call with
+# ``base_url=``, globally by assigning ``seoscoreapi.DEEP_AUDIT_URL``, or with the
+# ``SEOSCORE_DEEP_AUDIT_URL`` environment variable.
+DEEP_AUDIT_URL = os.environ.get("SEOSCORE_DEEP_AUDIT_URL") or BASE_URL
+# Legacy dedicated engine host. Still serves the same endpoints (its quota
+# endpoint is plain ``/usage``); pass it as ``base_url`` if you need it.
 ENGINE_URL = "https://engine.seoscoreapi.com"
-__version__ = "1.4.0"
+__version__ = "1.5.0"
 
 _HEADERS = {"User-Agent": f"seoscoreapi-python/{__version__}"}
 _TIMEOUT = 30  # seconds — default per-request timeout for engine calls
@@ -137,31 +145,47 @@ def history_domains(api_key: str) -> list:
     return r.json()["domains"]
 
 
-# --- Deep Audits (engine.seoscoreapi.com) — Pro/Ultra -----------------------
+# --- Deep Site Audit (Pro/Ultra, or credits) ---------------------------------
 
-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`.
+def _deep_base(base_url: Optional[str]) -> str:
+    return (base_url or DEEP_AUDIT_URL).rstrip("/")
 
-    Optional keyword args: ``business_type``, ``is_local``,
-    ``connected_integrations``, ``webhook_url``.
-    """
-    r = requests.post(
-        f"{ENGINE_URL}/site-audit",
+
+def _usage_path(base: str) -> str:
+    # The main host serves the engine's quota at /deep-audit/usage (its own
+    # /usage is the per-URL audit allowance); the legacy engine host uses /usage.
+    return "/usage" if base.split("://", 1)[-1].startswith("engine.") else "/deep-audit/usage"
+
+
+def _start(url: str, api_key: str, base: str, options: dict) -> requests.Response:
+    return requests.post(
+        f"{base}/site-audit",
         json={"url": url, **options},
         headers={"X-API-Key": api_key, **_HEADERS},
         timeout=_TIMEOUT,
     )
+
+
+def site_audit(url: str, api_key: str, *, base_url: Optional[str] = None, **options) -> dict:
+    """Start a Deep Site Audit. Asynchronous: returns a job
+    ``{"job_id", "status", "poll"}``; poll it with :func:`get_site_audit` or
+    block on it with :func:`wait_for_site_audit`.
+
+    Optional keyword args are sent to the API as-is: ``business_type``
+    (saas | local_service | ecommerce | storefront | blog | publisher),
+    ``is_local``, ``webhook_url``.
+    """
+    r = _start(url, api_key, _deep_base(base_url), options)
     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``/
+def get_site_audit(job_id: str, api_key: str, *, base_url: Optional[str] = None) -> dict:
+    """Poll a Deep Site 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}",
+        f"{_deep_base(base_url)}/site-audit/{job_id}",
         headers={"X-API-Key": api_key, **_HEADERS},
         timeout=_TIMEOUT,
     )
@@ -169,6 +193,38 @@ def get_site_audit(job_id: str, api_key: str) -> dict:
     return r.json()
 
 
+def wait_for_site_audit(
+    job_id: str,
+    api_key: str,
+    *,
+    poll_interval: float = 5.0,
+    timeout: float = 600.0,
+    on_progress: Optional[Callable[[dict], None]] = None,
+    base_url: Optional[str] = None,
+) -> dict:
+    """Poll an existing Deep Site Audit job until it finishes; return its result.
+
+    Honors the server's ETA while queued. Raises ``TimeoutError`` if it isn't
+    done within ``timeout`` seconds, or ``RuntimeError`` if the audit fails.
+    """
+    deadline = time.monotonic() + timeout
+    while True:
+        if time.monotonic() > deadline:
+            raise TimeoutError("Timed out waiting for audit to complete")
+        status = get_site_audit(job_id, api_key, base_url=base_url)
+        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(float(status["eta_seconds"]), 15.0))
+        else:
+            time.sleep(poll_interval)
+
+
 def deep_audit(
     url: str,
     api_key: str,
@@ -176,22 +232,19 @@ def deep_audit(
     poll_interval: float = 5.0,
     timeout: float = 600.0,
     on_progress: Optional[Callable[[dict], None]] = None,
+    base_url: Optional[str] = None,
     **options,
 ) -> dict:
-    """Start a deep audit and block until it finishes; return the result dict.
+    """Start a Deep Site 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.
+    Retries the submit on queue backpressure (429 + ``Retry-After``), then
+    polls with :func:`wait_for_site_audit`. Raises ``TimeoutError`` if it
+    doesn't finish within ``timeout`` seconds, or ``RuntimeError`` if it fails.
     """
+    base = _deep_base(base_url)
     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,
-        )
+        r = _start(url, api_key, base, options)
         if r.status_code == 429:
             retry = float(r.headers.get("Retry-After", 5))
             if time.monotonic() + retry > deadline:
@@ -201,30 +254,29 @@ def deep_audit(
         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)
+    return wait_for_site_audit(
+        job["job_id"],
+        api_key,
+        poll_interval=poll_interval,
+        timeout=max(deadline - time.monotonic(), 0.0),
+        on_progress=on_progress,
+        base_url=base,
+    )
 
 
-def engine_usage(api_key: str) -> dict:
-    """Remaining engine quota (deep audits + SERP) for this key."""
+def deep_audit_usage(api_key: str, *, base_url: Optional[str] = None) -> dict:
+    """Deep Site Audits used/remaining this month for this key
+    (``{"tier", "site_audit": {"used", "remaining"}, ...}``)."""
+    base = _deep_base(base_url)
     r = requests.get(
-        f"{ENGINE_URL}/usage",
+        f"{base}{_usage_path(base)}",
         headers={"X-API-Key": api_key, **_HEADERS},
         timeout=_TIMEOUT,
     )
     r.raise_for_status()
     return r.json()
+
+
+def engine_usage(api_key: str, *, base_url: Optional[str] = None) -> dict:
+    """Deprecated alias of :func:`deep_audit_usage` (kept for 1.4 callers)."""
+    return deep_audit_usage(api_key, base_url=base_url)

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: seoscoreapi
-Version: 1.4.0
+Version: 1.5.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,10 +83,11 @@ 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)
+## Deep Site Audit (Pro/Ultra, or credits)
 
-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:
+A deep, AI-assisted audit scoring a URL across 9 dimensions (thousands of catalog
+checks plus up to 150 AI checks). It runs asynchronously, so start a job and poll it,
+or use `deep_audit` to block for the result:
 
 ```python
 import seoscoreapi as seo
@@ -100,17 +101,26 @@ result = seo.deep_audit(
 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)
+job = seo.site_audit("https://yoursite.com", API_KEY)       # POST /site-audit
+status = seo.get_site_audit(job["job_id"], API_KEY)         # GET  /site-audit/{job_id}
 # status["status"] -> queued | running | completed | failed
-#   queued  -> {"queue_position", "eta_seconds"}
-#   done    -> {"result"}
+#   queued    -> {"queue_position", "eta_seconds"}
+#   completed -> {"result"}
+result = seo.wait_for_site_audit(job["job_id"], API_KEY, timeout=600)
 
-seo.engine_usage(API_KEY)     # remaining deep-audit + SERP quota
+seo.deep_audit_usage(API_KEY)   # GET /deep-audit/usage -> {"site_audit": {"used", "remaining"}, ...}
 ```
 
-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).
+Deep audits are included on **Pro** ($39/mo, 20/mo) and **Ultra** ($99/mo, 100/mo);
+any other key can run them on purchased credits.
+
+Since 1.5.0 the SDK calls the main host, `https://seoscoreapi.com`, like every other
+endpoint. To point Deep Audit somewhere else (a proxy, staging, or the legacy
+`engine.seoscoreapi.com` host, which still works), pass `base_url=` to any Deep Audit
+function, assign `seoscoreapi.DEEP_AUDIT_URL`, or set `SEOSCORE_DEEP_AUDIT_URL`.
+`engine_usage()` is kept as an alias of `deep_audit_usage()`.
+
+Docs: [seoscoreapi.com/docs](https://seoscoreapi.com/docs) (Deep Site Audit section).
 
 ## Full Documentation
 

{seoscoreapi-1.4.0 → seoscoreapi-1.5.0}/seoscoreapi.egg-info/SOURCES.txt

@@ -5,4 +5,5 @@ seoscoreapi.egg-info/PKG-INFO
 seoscoreapi.egg-info/SOURCES.txt
 seoscoreapi.egg-info/dependency_links.txt
 seoscoreapi.egg-info/requires.txt
-seoscoreapi.egg-info/top_level.txt
+seoscoreapi.egg-info/top_level.txt
+tests/test_deep_audit.py

seoscoreapi-1.5.0/tests/test_deep_audit.py

@@ -0,0 +1,114 @@
+"""Deep Site Audit client tests. No network: requests.get/post are patched."""
+
+import sys
+from pathlib import Path
+from unittest import mock
+
+import pytest
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+
+import seoscoreapi as seo  # noqa: E402
+
+
+class FakeResponse:
+    def __init__(self, payload=None, status=200, headers=None):
+        self._payload = payload or {}
+        self.status_code = status
+        self.headers = headers or {}
+
+    def json(self):
+        return self._payload
+
+    def raise_for_status(self):
+        if self.status_code >= 400:
+            raise seo.requests.HTTPError(f"HTTP {self.status_code}")
+
+
+@pytest.fixture(autouse=True)
+def no_sleep(monkeypatch):
+    monkeypatch.setattr(seo.time, "sleep", lambda s: None)
+
+
+def test_defaults_to_main_host():
+    assert seo.DEEP_AUDIT_URL == "https://seoscoreapi.com"
+    assert seo.__version__ == "1.5.0"
+
+
+def test_site_audit_posts_to_main_host():
+    with mock.patch.object(seo.requests, "post", return_value=FakeResponse({"job_id": "abc", "status": "queued"})) as post:
+        job = seo.site_audit("https://example.com", "k", business_type="saas")
+    assert job["job_id"] == "abc"
+    args, kwargs = post.call_args
+    assert args[0] == "https://seoscoreapi.com/site-audit"
+    assert kwargs["json"] == {"url": "https://example.com", "business_type": "saas"}
+    assert kwargs["headers"]["X-API-Key"] == "k"
+
+
+def test_get_site_audit_url():
+    with mock.patch.object(seo.requests, "get", return_value=FakeResponse({"status": "running"})) as get:
+        seo.get_site_audit("abc", "k")
+    assert get.call_args[0][0] == "https://seoscoreapi.com/site-audit/abc"
+
+
+def test_base_url_override_per_call():
+    with mock.patch.object(seo.requests, "post", return_value=FakeResponse({"job_id": "x"})) as post:
+        seo.site_audit("https://example.com", "k", base_url="http://localhost:9000/")
+    assert post.call_args[0][0] == "http://localhost:9000/site-audit"
+    assert "base_url" not in post.call_args[1]["json"]
+
+
+def test_module_override(monkeypatch):
+    monkeypatch.setattr(seo, "DEEP_AUDIT_URL", "https://staging.example")
+    with mock.patch.object(seo.requests, "get", return_value=FakeResponse({})) as get:
+        seo.get_site_audit("abc", "k")
+    assert get.call_args[0][0] == "https://staging.example/site-audit/abc"
+
+
+def test_usage_main_host_path():
+    with mock.patch.object(seo.requests, "get", return_value=FakeResponse({"tier": "pro"})) as get:
+        assert seo.deep_audit_usage("k") == {"tier": "pro"}
+    assert get.call_args[0][0] == "https://seoscoreapi.com/deep-audit/usage"
+
+
+def test_usage_legacy_engine_path_and_alias():
+    with mock.patch.object(seo.requests, "get", return_value=FakeResponse({})) as get:
+        seo.engine_usage("k", base_url=seo.ENGINE_URL)
+    assert get.call_args[0][0] == "https://engine.seoscoreapi.com/usage"
+
+
+def test_wait_for_site_audit_completes():
+    seq = [
+        FakeResponse({"status": "queued", "eta_seconds": 30}),
+        FakeResponse({"status": "running", "progress": 50}),
+        FakeResponse({"status": "completed", "result": {"scores": {"lai_score": 3.2}}}),
+    ]
+    seen = []
+    with mock.patch.object(seo.requests, "get", side_effect=seq):
+        result = seo.wait_for_site_audit("abc", "k", on_progress=lambda s: seen.append(s["status"]))
+    assert result == {"scores": {"lai_score": 3.2}}
+    assert seen == ["queued", "running", "completed"]
+
+
+def test_wait_for_site_audit_failed():
+    with mock.patch.object(seo.requests, "get", return_value=FakeResponse({"status": "failed", "error": "boom"})):
+        with pytest.raises(RuntimeError, match="boom"):
+            seo.wait_for_site_audit("abc", "k")
+
+
+def test_wait_for_site_audit_timeout():
+    with mock.patch.object(seo.requests, "get", return_value=FakeResponse({"status": "running"})):
+        with pytest.raises(TimeoutError):
+            seo.wait_for_site_audit("abc", "k", timeout=0)
+
+
+def test_deep_audit_retries_backpressure_then_polls():
+    posts = [
+        FakeResponse(status=429, headers={"Retry-After": "1"}),
+        FakeResponse({"job_id": "abc", "status": "queued"}),
+    ]
+    with mock.patch.object(seo.requests, "post", side_effect=posts) as post, \
+         mock.patch.object(seo.requests, "get", return_value=FakeResponse({"status": "completed", "result": {"ok": 1}})) as get:
+        assert seo.deep_audit("https://example.com", "k") == {"ok": 1}
+    assert post.call_count == 2
+    assert get.call_args[0][0] == "https://seoscoreapi.com/site-audit/abc"