seoscoreapi 1.6.0__tar.gz → 1.7.0__tar.gz

{seoscoreapi-1.6.0 → seoscoreapi-1.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: seoscoreapi
-Version: 1.6.0
+Version: 1.7.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
@@ -29,10 +29,11 @@ pip install seoscoreapi
 ## Quick Start
 
 ```python
-from seoscoreapi import audit, signup
+import os
+from seoscoreapi import audit
 
-# Get a free API key (2 audits/day, no credit card)
-key = signup("you@example.com")
+# Get a free API key (2 audits/day, no credit card) at https://seoscoreapi.com/#signup
+key = os.environ["SEO_SCORE_API_KEY"]
 
 # Run an audit
 result = audit("https://example.com", api_key=key)
@@ -43,9 +44,10 @@ print(f"Score: {result['score']}/100 ({result['grade']})")
 
 | Function | Description |
 |---|---|
-| `signup(email)` | Get a free API key |
-| `audit(url, api_key)` | Run SEO audit on a URL |
-| `batch_audit(urls, api_key)` | Audit up to 10 URLs in one call (paid) |
+| `signup(email)` | Start signup: the API emails a 6-digit code. Returns the API's response (`{"status": "verification_required", ...}`), not a key |
+| `verify(email, code)` | Finish signup with the emailed code. Returns the API key (shown only once) |
+| `audit(url, api_key, cwv=False)` | Run SEO audit on a URL. `cwv=True` adds measured Core Web Vitals (slower, see below) |
+| `batch_audit(urls, api_key, cwv=False)` | Audit up to 10 URLs in one call (paid). `cwv=True` adds Core Web Vitals to each |
 | `compare(urls, api_key)` | Compare 2–5 URLs with a structured diff (Basic+) |
 | `competitive_audit(url, competitor_url, keyword, api_key)` | Head-to-head audit with gap score (Pro+) |
 | `history(url, api_key, limit=100, since=None)` | Full audit timeseries + summary for a URL (Starter+) |
@@ -84,6 +86,31 @@ print(f"Score: {result['score']}/100 ({result['grade']})")
 Errors are `requests.HTTPError` (from `raise_for_status()`); the API's message is in
 `err.response.json()["detail"]`.
 
+## Get an API key from code
+
+Signup takes two calls. `signup()` emails a 6-digit code (valid for 10 minutes) and
+`verify()` trades that code for the key. You can also sign up at
+[seoscoreapi.com](https://seoscoreapi.com/#signup).
+
+```python
+import requests
+from seoscoreapi import signup, verify
+
+email = "you@example.com"
+print(signup(email)["message"])  # "Check your email for a 6-digit verification code."
+
+try:
+    key = verify(email, input("Code from the email: "))
+except requests.HTTPError as e:
+    raise SystemExit(e.response.json()["detail"])  # wrong or expired code
+
+print(key)  # save it: the key is shown only once
+```
+
+`signup()` raises `requests.HTTPError` when the address is refused (400) or already
+has an active key (409). `verify()` raises it (400) on a wrong or expired code; five
+wrong codes void the signup, so call `signup()` again.
+
 ## Historical tracking
 
 Every audit on a paid plan returns a `history` block on the `/audit` response:
@@ -111,6 +138,27 @@ add_monitor(
 
 Slack incoming-webhook URLs are auto-formatted as Block Kit messages; any other https endpoint receives the raw event JSON.
 
+## Core Web Vitals (opt-in)
+
+Audits are fast because they do not wait on Google PageSpeed Insights. Ask for measured
+Core Web Vitals when you need them:
+
+```python
+result = audit("https://example.com", api_key=key, cwv=True)
+vitals = result["core_web_vitals"]
+if vitals["status"] == "ok":
+    print(vitals["lcp_ms"], vitals["inp_ms"], vitals["cls"], vitals["source"])  # source: "field" or "lab"
+elif vitals.get("pending"):
+    print("Still measuring; audit this URL again in a minute")
+else:
+    print("No Core Web Vitals:", vitals.get("reason"))
+```
+
+The first measurement of a URL adds about 10 seconds (the API waits up to 25); it is
+cached for 24 hours, so repeats are instant. It works on every plan and never changes the
+score. Without `cwv=True` the block reads `{"status": "not_requested", ...}` with the
+metrics set to `None`.
+
 ## Accessibility audit and report files
 
 ```python

{seoscoreapi-1.6.0 → seoscoreapi-1.7.0}/README.md

@@ -11,10 +11,11 @@ pip install seoscoreapi
 ## Quick Start
 
 ```python
-from seoscoreapi import audit, signup
+import os
+from seoscoreapi import audit
 
-# Get a free API key (2 audits/day, no credit card)
-key = signup("you@example.com")
+# Get a free API key (2 audits/day, no credit card) at https://seoscoreapi.com/#signup
+key = os.environ["SEO_SCORE_API_KEY"]
 
 # Run an audit
 result = audit("https://example.com", api_key=key)
@@ -25,9 +26,10 @@ print(f"Score: {result['score']}/100 ({result['grade']})")
 
 | Function | Description |
 |---|---|
-| `signup(email)` | Get a free API key |
-| `audit(url, api_key)` | Run SEO audit on a URL |
-| `batch_audit(urls, api_key)` | Audit up to 10 URLs in one call (paid) |
+| `signup(email)` | Start signup: the API emails a 6-digit code. Returns the API's response (`{"status": "verification_required", ...}`), not a key |
+| `verify(email, code)` | Finish signup with the emailed code. Returns the API key (shown only once) |
+| `audit(url, api_key, cwv=False)` | Run SEO audit on a URL. `cwv=True` adds measured Core Web Vitals (slower, see below) |
+| `batch_audit(urls, api_key, cwv=False)` | Audit up to 10 URLs in one call (paid). `cwv=True` adds Core Web Vitals to each |
 | `compare(urls, api_key)` | Compare 2–5 URLs with a structured diff (Basic+) |
 | `competitive_audit(url, competitor_url, keyword, api_key)` | Head-to-head audit with gap score (Pro+) |
 | `history(url, api_key, limit=100, since=None)` | Full audit timeseries + summary for a URL (Starter+) |
@@ -66,6 +68,31 @@ print(f"Score: {result['score']}/100 ({result['grade']})")
 Errors are `requests.HTTPError` (from `raise_for_status()`); the API's message is in
 `err.response.json()["detail"]`.
 
+## Get an API key from code
+
+Signup takes two calls. `signup()` emails a 6-digit code (valid for 10 minutes) and
+`verify()` trades that code for the key. You can also sign up at
+[seoscoreapi.com](https://seoscoreapi.com/#signup).
+
+```python
+import requests
+from seoscoreapi import signup, verify
+
+email = "you@example.com"
+print(signup(email)["message"])  # "Check your email for a 6-digit verification code."
+
+try:
+    key = verify(email, input("Code from the email: "))
+except requests.HTTPError as e:
+    raise SystemExit(e.response.json()["detail"])  # wrong or expired code
+
+print(key)  # save it: the key is shown only once
+```
+
+`signup()` raises `requests.HTTPError` when the address is refused (400) or already
+has an active key (409). `verify()` raises it (400) on a wrong or expired code; five
+wrong codes void the signup, so call `signup()` again.
+
 ## Historical tracking
 
 Every audit on a paid plan returns a `history` block on the `/audit` response:
@@ -93,6 +120,27 @@ add_monitor(
 
 Slack incoming-webhook URLs are auto-formatted as Block Kit messages; any other https endpoint receives the raw event JSON.
 
+## Core Web Vitals (opt-in)
+
+Audits are fast because they do not wait on Google PageSpeed Insights. Ask for measured
+Core Web Vitals when you need them:
+
+```python
+result = audit("https://example.com", api_key=key, cwv=True)
+vitals = result["core_web_vitals"]
+if vitals["status"] == "ok":
+    print(vitals["lcp_ms"], vitals["inp_ms"], vitals["cls"], vitals["source"])  # source: "field" or "lab"
+elif vitals.get("pending"):
+    print("Still measuring; audit this URL again in a minute")
+else:
+    print("No Core Web Vitals:", vitals.get("reason"))
+```
+
+The first measurement of a URL adds about 10 seconds (the API waits up to 25); it is
+cached for 24 hours, so repeats are instant. It works on every plan and never changes the
+score. Without `cwv=True` the block reads `{"status": "not_requested", ...}` with the
+metrics set to `None`.
+
 ## Accessibility audit and report files
 
 ```python

{seoscoreapi-1.6.0 → seoscoreapi-1.7.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "seoscoreapi"
-version = "1.6.0"
+version = "1.7.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.6.0 → seoscoreapi-1.7.0}/seoscoreapi/__init__.py

@@ -5,10 +5,11 @@ SEO Score API - Python Client
 Audit any URL for SEO issues with one function call.
 
 Usage:
-    from seoscoreapi import audit, signup
+    from seoscoreapi import audit, signup, verify
 
-    # Get a free API key
-    key = signup("you@example.com")
+    # Get a free API key: signup() emails a 6-digit code, verify() returns the key
+    signup("you@example.com")
+    key = verify("you@example.com", input("Code from the email: "))
 
     # Run an audit
     result = audit("https://example.com", api_key=key)
@@ -34,29 +35,71 @@ 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.6.0"
+__version__ = "1.7.0"
 
 _HEADERS = {"User-Agent": f"seoscoreapi-python/{__version__}"}
 _TIMEOUT = 30  # seconds — default per-request timeout for engine calls
 
 
-def signup(email: str) -> str:
-    """Sign up for a free API key. Returns the raw key (save it — shown only once)."""
+def signup(email: str) -> dict:
+    """Start signup for a free API key. The API emails a 6-digit code to `email`.
+
+    Returns the API's response, normally
+    ``{"status": "verification_required", "message": "..."}``. No key is issued
+    yet: pass the code to :func:`verify` to get it. The code expires after 10
+    minutes. Raises ``requests.HTTPError`` on a rejected address (400) or an
+    email that already has an active key (409).
+    """
     r = requests.post(f"{BASE_URL}/signup", json={"email": email}, headers=_HEADERS)
     r.raise_for_status()
+    return r.json()
+
+
+def verify(email: str, code: str) -> str:
+    """Finish signup: exchange the emailed 6-digit code for the API key.
+
+    Returns the raw key (save it, it is shown only once). Raises
+    ``requests.HTTPError`` (400) on a wrong or expired code, or when there is no
+    pending signup for `email`; the reason is in ``e.response.json()["detail"]``.
+    Five wrong codes void the signup, so call :func:`signup` again after that.
+    """
+    r = requests.post(
+        f"{BASE_URL}/verify",
+        json={"email": email, "code": str(code).strip()},
+        headers=_HEADERS,
+    )
+    r.raise_for_status()
     return r.json()["api_key"]
 
 
-def audit(url: str, api_key: str) -> dict:
-    """Run an SEO audit on a URL. Returns score, grade, checks, and priorities."""
-    r = requests.get(f"{BASE_URL}/audit", params={"url": url}, headers={"X-API-Key": api_key, **_HEADERS})
+def audit(url: str, api_key: str, cwv: bool = False) -> dict:
+    """Run an SEO audit on a URL. Returns score, grade, checks, and priorities.
+
+    ``cwv=True`` adds measured Core Web Vitals (LCP, INP, CLS, FCP, TTFB from Google
+    PageSpeed Insights) under ``core_web_vitals``. It is off by default because the
+    first measurement of a URL adds about 10 seconds (it is then cached for 24
+    hours). Without it ``core_web_vitals["status"]`` is ``"not_requested"``; with
+    it, ``"ok"``, or ``"unavailable"`` with a ``reason`` (and ``pending: True`` when
+    the measurement is still running: audit the URL again to pick it up).
+    """
+    params = {"url": url}
+    if cwv:
+        params["cwv"] = "true"
+    r = requests.get(f"{BASE_URL}/audit", params=params, headers={"X-API-Key": api_key, **_HEADERS})
     r.raise_for_status()
     return r.json()
 
 
-def batch_audit(urls: list[str], api_key: str) -> dict:
-    """Audit multiple URLs (paid plans only). Returns list of results."""
-    r = requests.post(f"{BASE_URL}/audit/batch", json={"urls": urls}, headers={"X-API-Key": api_key, **_HEADERS})
+def batch_audit(urls: list[str], api_key: str, cwv: bool = False) -> dict:
+    """Audit multiple URLs (paid plans only). Returns list of results.
+
+    ``cwv=True`` adds measured Core Web Vitals to every result (see ``audit``). The
+    batch then takes longer: allow up to three minutes.
+    """
+    body: dict = {"urls": urls}
+    if cwv:
+        body["cwv"] = True
+    r = requests.post(f"{BASE_URL}/audit/batch", json=body, headers={"X-API-Key": api_key, **_HEADERS})
     r.raise_for_status()
     return r.json()
 

{seoscoreapi-1.6.0 → seoscoreapi-1.7.0}/seoscoreapi.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: seoscoreapi
-Version: 1.6.0
+Version: 1.7.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
@@ -29,10 +29,11 @@ pip install seoscoreapi
 ## Quick Start
 
 ```python
-from seoscoreapi import audit, signup
+import os
+from seoscoreapi import audit
 
-# Get a free API key (2 audits/day, no credit card)
-key = signup("you@example.com")
+# Get a free API key (2 audits/day, no credit card) at https://seoscoreapi.com/#signup
+key = os.environ["SEO_SCORE_API_KEY"]
 
 # Run an audit
 result = audit("https://example.com", api_key=key)
@@ -43,9 +44,10 @@ print(f"Score: {result['score']}/100 ({result['grade']})")
 
 | Function | Description |
 |---|---|
-| `signup(email)` | Get a free API key |
-| `audit(url, api_key)` | Run SEO audit on a URL |
-| `batch_audit(urls, api_key)` | Audit up to 10 URLs in one call (paid) |
+| `signup(email)` | Start signup: the API emails a 6-digit code. Returns the API's response (`{"status": "verification_required", ...}`), not a key |
+| `verify(email, code)` | Finish signup with the emailed code. Returns the API key (shown only once) |
+| `audit(url, api_key, cwv=False)` | Run SEO audit on a URL. `cwv=True` adds measured Core Web Vitals (slower, see below) |
+| `batch_audit(urls, api_key, cwv=False)` | Audit up to 10 URLs in one call (paid). `cwv=True` adds Core Web Vitals to each |
 | `compare(urls, api_key)` | Compare 2–5 URLs with a structured diff (Basic+) |
 | `competitive_audit(url, competitor_url, keyword, api_key)` | Head-to-head audit with gap score (Pro+) |
 | `history(url, api_key, limit=100, since=None)` | Full audit timeseries + summary for a URL (Starter+) |
@@ -84,6 +86,31 @@ print(f"Score: {result['score']}/100 ({result['grade']})")
 Errors are `requests.HTTPError` (from `raise_for_status()`); the API's message is in
 `err.response.json()["detail"]`.
 
+## Get an API key from code
+
+Signup takes two calls. `signup()` emails a 6-digit code (valid for 10 minutes) and
+`verify()` trades that code for the key. You can also sign up at
+[seoscoreapi.com](https://seoscoreapi.com/#signup).
+
+```python
+import requests
+from seoscoreapi import signup, verify
+
+email = "you@example.com"
+print(signup(email)["message"])  # "Check your email for a 6-digit verification code."
+
+try:
+    key = verify(email, input("Code from the email: "))
+except requests.HTTPError as e:
+    raise SystemExit(e.response.json()["detail"])  # wrong or expired code
+
+print(key)  # save it: the key is shown only once
+```
+
+`signup()` raises `requests.HTTPError` when the address is refused (400) or already
+has an active key (409). `verify()` raises it (400) on a wrong or expired code; five
+wrong codes void the signup, so call `signup()` again.
+
 ## Historical tracking
 
 Every audit on a paid plan returns a `history` block on the `/audit` response:
@@ -111,6 +138,27 @@ add_monitor(
 
 Slack incoming-webhook URLs are auto-formatted as Block Kit messages; any other https endpoint receives the raw event JSON.
 
+## Core Web Vitals (opt-in)
+
+Audits are fast because they do not wait on Google PageSpeed Insights. Ask for measured
+Core Web Vitals when you need them:
+
+```python
+result = audit("https://example.com", api_key=key, cwv=True)
+vitals = result["core_web_vitals"]
+if vitals["status"] == "ok":
+    print(vitals["lcp_ms"], vitals["inp_ms"], vitals["cls"], vitals["source"])  # source: "field" or "lab"
+elif vitals.get("pending"):
+    print("Still measuring; audit this URL again in a minute")
+else:
+    print("No Core Web Vitals:", vitals.get("reason"))
+```
+
+The first measurement of a URL adds about 10 seconds (the API waits up to 25); it is
+cached for 24 hours, so repeats are instant. It works on every plan and never changes the
+score. Without `cwv=True` the block reads `{"status": "not_requested", ...}` with the
+metrics set to `None`.
+
 ## Accessibility audit and report files
 
 ```python

{seoscoreapi-1.6.0 → seoscoreapi-1.7.0}/tests/test_deep_audit.py

@@ -32,7 +32,7 @@ def no_sleep(monkeypatch):
 
 def test_defaults_to_main_host():
     assert seo.DEEP_AUDIT_URL == "https://seoscoreapi.com"
-    assert seo.__version__ == "1.6.0"
+    assert seo.__version__ == "1.7.0"
 
 
 def test_site_audit_posts_to_main_host():

{seoscoreapi-1.6.0 → seoscoreapi-1.7.0}/tests/test_endpoints.py

@@ -202,3 +202,79 @@ def test_crawl_starts_then_polls():
         assert seo.crawl("https://e.com", "k", max_pages=5)["result"] == {"ok": 1}
     assert post.call_args[1]["json"] == {"url": "https://e.com", "max_pages": 5}
     assert get.call_args[0][0] == B + "/crawl/abc"
+
+
+# --- signup is two steps: POST /signup emails a code, POST /verify returns the key
+
+def test_signup_returns_the_verification_response_not_a_key():
+    payload = {"status": "verification_required", "message": "Check your email for a 6-digit verification code."}
+    with patched("post", payload) as m:
+        out = seo.signup("you@example.com")
+    assert out == payload
+    assert m.call_args.args[0] == f"{B}/signup"
+    assert m.call_args.kwargs["json"] == {"email": "you@example.com"}
+    assert "X-API-Key" not in m.call_args.kwargs["headers"]
+
+
+def test_signup_passes_through_a_response_that_carries_a_key():
+    with patched("post", {"api_key": "ssa_x", "tier": "free"}):
+        assert seo.signup("you@example.com")["api_key"] == "ssa_x"
+
+
+def test_signup_raises_when_the_email_already_has_a_key():
+    with patched("post", {"detail": "Email already has an active key (prefix: ssa_abc...)"}, status=409):
+        with pytest.raises(seo.requests.HTTPError):
+            seo.signup("you@example.com")
+
+
+def test_verify_returns_the_api_key():
+    payload = {"api_key": "ssa_live_key", "tier": "free", "limits": {}, "message": "Save your API key"}
+    with patched("post", payload) as m:
+        assert seo.verify("you@example.com", " 012345 ") == "ssa_live_key"
+    assert m.call_args.args[0] == f"{B}/verify"
+    assert m.call_args.kwargs["json"] == {"email": "you@example.com", "code": "012345"}
+
+
+def test_verify_accepts_an_integer_code():
+    with patched("post", {"api_key": "k"}) as m:
+        seo.verify("you@example.com", 123456)
+    assert m.call_args.kwargs["json"]["code"] == "123456"
+
+
+def test_verify_raises_on_a_bad_code():
+    with patched("post", {"detail": "Invalid verification code. 4 attempts remaining."}, status=400):
+        with pytest.raises(seo.requests.HTTPError):
+            seo.verify("you@example.com", "000000")
+
+
+# --- Core Web Vitals opt-in (1.7.0) -------------------------------------------------
+
+def test_audit_does_not_ask_for_core_web_vitals_by_default():
+    with patched("get", {"score": 90}) as get:
+        assert seo.audit("https://e.com", "k") == {"score": 90}
+    args, kwargs = get.call_args
+    assert args[0] == B + "/audit"
+    assert kwargs["params"] == {"url": "https://e.com"}
+    assert kwargs["headers"]["X-API-Key"] == "k"
+
+
+def test_audit_cwv_true_sends_the_parameter():
+    payload = {"score": 90, "core_web_vitals": {"status": "ok", "lcp_ms": 1800}}
+    with patched("get", payload) as get:
+        assert seo.audit("https://e.com", "k", cwv=True)["core_web_vitals"]["lcp_ms"] == 1800
+    assert get.call_args.kwargs["params"] == {"url": "https://e.com", "cwv": "true"}
+
+
+def test_audit_cwv_false_is_the_default_request():
+    with patched("get", {}) as get:
+        seo.audit("https://e.com", "k", cwv=False)
+    assert get.call_args.kwargs["params"] == {"url": "https://e.com"}
+
+
+def test_batch_audit_cwv():
+    with patched("post", {"count": 1, "results": []}) as post:
+        seo.batch_audit(["https://a.com"], "k")
+        assert post.call_args.kwargs["json"] == {"urls": ["https://a.com"]}
+        seo.batch_audit(["https://a.com"], "k", cwv=True)
+        assert post.call_args.kwargs["json"] == {"urls": ["https://a.com"], "cwv": True}
+    assert post.call_args.args[0] == B + "/audit/batch"