seolyticize 0.4.0__tar.gz

seolyticize-0.4.0/LICENSE

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

seolyticize-0.4.0/PKG-INFO

@@ -0,0 +1,118 @@
+Metadata-Version: 2.4
+Name: seolyticize
+Version: 0.4.0
+Summary: Seolyticize for Python: every API tool as a method, and on-site helpers for analytics, IndexNow and deploys.
+License: MIT
+Project-URL: Homepage, https://seolyticize.com
+Project-URL: Documentation, https://seolyticize.com/docs/python-sdk
+Project-URL: Source, https://github.com/Seolyticize/sdk-python
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Internet :: WWW/HTTP :: Site Management
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Seolyticize for Python
+
+Every [Seolyticize](https://seolyticize.com) API tool (about 500 in 0.4.0) as a method, and on-site helpers for analytics, IndexNow and deploys. Standard library only, Python 3.9+.
+
+```sh
+pip install "git+https://github.com/Seolyticize/sdk-python"
+```
+
+## Quick start
+
+```python
+from seolyticize import Seolyticize
+
+client = Seolyticize()  # reads SEOLYTICIZE_API_KEY
+
+# Onboard a site: one call returns everything to deploy.
+manifest = client.onboard_site(domain="example.com", framework="html")
+# …deploy manifest["files"] and the analytics snippet, then:
+checklist = client.verify_site(client_id=manifest["clientId"])
+
+# The weekly loop.
+for item in client.get_next_steps(client_id=manifest["clientId"])["weekly"]:
+    print(item["tool"], item["why"])
+```
+
+Paid research (any domain, the AI answer index, Maps, AI Mode beside rank) takes `max_cost_micros`. Quote the exact call first:
+
+```python
+args = {"clientId": client_id, "target": "rival.com/blog/", "change": "new"}
+quote = client.estimate_cost(tool="get_ranked_keywords", arguments=args)
+ranked = client.get_ranked_keywords(
+    client_id=client_id, target="rival.com/blog/", change="new",
+    max_cost_micros=quote["estimatedMaxMicros"],
+)
+
+# Free reads over stored data:
+pages = client.get_landing_pages(client_id=client_id, tracker_id=tracker_id)
+grid = client.get_local_visibility(client_id=client_id, location_id=location_id, term="emergency plumber")
+redirects = client.plan_redirect_map(client_id=client_id, old_crawl_id=old_crawl_id, format_="csv")
+```
+
+Arguments are keyword-only and snake_case (`client_id`, `crawl_id`); Python keywords get an underscore (`from_`). Tools newer than this package are reachable with `client.call("tool_name", {"camelCase": "input"})`. `client.list_tools(group="onboarding")` lists what your key may call, with schemas.
+
+## Errors
+
+```python
+from seolyticize import RefusedError, RateLimitError
+
+try:
+    client.connect_search_console_service_account(client_id="client_…")
+except RefusedError as error:
+    print(error.code)        # "search_console_no_access" — branch on this
+    print(error.next)        # what to do next
+    print(error.request_id)  # quote it when asking for help
+```
+
+`ValidationError` (400), `AuthenticationError` (401), `PermissionError` (403), `NotFoundError` (404), `RefusedError` (422), `RateLimitError` (429), `ServerError` (5xx), `NetworkError` — all subclasses of `SeolyticizeError`. 429s are retried after `Retry-After`; server and network errors are retried only for read-only tools, since a write that failed may already have happened.
+
+## On your site
+
+```python
+from seolyticize.site import analytics_tag, indexnow_key_response, notify_deploy, track_event
+
+analytics_tag("SITE_KEY", exclude=["/account/*", "/verify"])  # the <script> for your <head>
+body, headers = indexnow_key_response("KEY")                   # serve at /KEY.txt
+notify_deploy("https://seolyticize.com/api/v1/hooks/deploy/dh_…")  # after each deploy
+track_event("SITE_KEY", "https://example.com/pricing", name="Signup")  # server-side event
+```
+
+### Server-side collection
+
+Reports page views from the server — above all the AI assistants (ChatGPT-User, Claude-User, Perplexity-User) that read pages without running the browser tag. Needs the server key from `issue_server_collect_key`; keep it in the environment.
+
+```python
+import os
+from seolyticize.collect import ASGICollector, Collector, WSGICollector, django_middleware
+
+collector = Collector("SITE_KEY", os.environ["SEOLYTICIZE_SERVER_KEY"],
+                      exclude=["/admin/*", "/api/*"],
+                      only="agents")  # with the browser tag installed too; "all" without it
+
+app.wsgi_app = WSGICollector(app.wsgi_app, collector)      # Flask
+app = ASGICollector(app, collector)                         # FastAPI / Starlette
+SeolyticizeMiddleware = django_middleware(collector)        # Django: add to MIDDLEWARE
+```
+
+Only the path and `utm_*` parameters (change with `allow_params`), the referrer's origin, the visitor's address, user agent and country are sent; Seolyticize hashes the address and user agent under a daily salt and stores neither. Bots are dropped before anything is sent. Reports go out on a background thread and never raise.
+
+To credit orders to the visit they came from, send a reference from the checkout — the tag's `seolyticize('event', 'Checkout', {ref: cartId})`, or `collector.track(checkout_url, name="Checkout", props={"ref": cart_id}, user_agent=…, ip=…)` with the visitor's own agent and address so it joins their visit — and put the same value in the order's metadata as `seolyticize_ref` (Stripe metadata, a Shopify cart attribute, Paddle `custom_data`).
+
+A conversion that happens after the visit — a payment confirmed by webhook, a trial that converts next week — is credited to the visit by its token. Ask for it while the visitor is there and keep it on your server with the account (never in a cookie or the page); the token lasts 35 days:
+
+```python
+visit = collector.track_for_visit(request.url, "Signup", user_agent=ua, ip=ip)  # returns the token
+account.seolyticize_visit = visit
+# ...days later, from the payment webhook:
+collector.track_later(account.seolyticize_visit, "Top-up", props={"value": 25})
+```
+
+Docs: [seolyticize.com/docs/python-sdk](https://seolyticize.com/docs/python-sdk) · Agent quick start: [seolyticize.com/AGENTS.md](https://seolyticize.com/AGENTS.md)
+
+The tool methods are generated from the same registry that runs the API. License: MIT.

seolyticize-0.4.0/README.md

@@ -0,0 +1,102 @@
+# Seolyticize for Python
+
+Every [Seolyticize](https://seolyticize.com) API tool (about 500 in 0.4.0) as a method, and on-site helpers for analytics, IndexNow and deploys. Standard library only, Python 3.9+.
+
+```sh
+pip install "git+https://github.com/Seolyticize/sdk-python"
+```
+
+## Quick start
+
+```python
+from seolyticize import Seolyticize
+
+client = Seolyticize()  # reads SEOLYTICIZE_API_KEY
+
+# Onboard a site: one call returns everything to deploy.
+manifest = client.onboard_site(domain="example.com", framework="html")
+# …deploy manifest["files"] and the analytics snippet, then:
+checklist = client.verify_site(client_id=manifest["clientId"])
+
+# The weekly loop.
+for item in client.get_next_steps(client_id=manifest["clientId"])["weekly"]:
+    print(item["tool"], item["why"])
+```
+
+Paid research (any domain, the AI answer index, Maps, AI Mode beside rank) takes `max_cost_micros`. Quote the exact call first:
+
+```python
+args = {"clientId": client_id, "target": "rival.com/blog/", "change": "new"}
+quote = client.estimate_cost(tool="get_ranked_keywords", arguments=args)
+ranked = client.get_ranked_keywords(
+    client_id=client_id, target="rival.com/blog/", change="new",
+    max_cost_micros=quote["estimatedMaxMicros"],
+)
+
+# Free reads over stored data:
+pages = client.get_landing_pages(client_id=client_id, tracker_id=tracker_id)
+grid = client.get_local_visibility(client_id=client_id, location_id=location_id, term="emergency plumber")
+redirects = client.plan_redirect_map(client_id=client_id, old_crawl_id=old_crawl_id, format_="csv")
+```
+
+Arguments are keyword-only and snake_case (`client_id`, `crawl_id`); Python keywords get an underscore (`from_`). Tools newer than this package are reachable with `client.call("tool_name", {"camelCase": "input"})`. `client.list_tools(group="onboarding")` lists what your key may call, with schemas.
+
+## Errors
+
+```python
+from seolyticize import RefusedError, RateLimitError
+
+try:
+    client.connect_search_console_service_account(client_id="client_…")
+except RefusedError as error:
+    print(error.code)        # "search_console_no_access" — branch on this
+    print(error.next)        # what to do next
+    print(error.request_id)  # quote it when asking for help
+```
+
+`ValidationError` (400), `AuthenticationError` (401), `PermissionError` (403), `NotFoundError` (404), `RefusedError` (422), `RateLimitError` (429), `ServerError` (5xx), `NetworkError` — all subclasses of `SeolyticizeError`. 429s are retried after `Retry-After`; server and network errors are retried only for read-only tools, since a write that failed may already have happened.
+
+## On your site
+
+```python
+from seolyticize.site import analytics_tag, indexnow_key_response, notify_deploy, track_event
+
+analytics_tag("SITE_KEY", exclude=["/account/*", "/verify"])  # the <script> for your <head>
+body, headers = indexnow_key_response("KEY")                   # serve at /KEY.txt
+notify_deploy("https://seolyticize.com/api/v1/hooks/deploy/dh_…")  # after each deploy
+track_event("SITE_KEY", "https://example.com/pricing", name="Signup")  # server-side event
+```
+
+### Server-side collection
+
+Reports page views from the server — above all the AI assistants (ChatGPT-User, Claude-User, Perplexity-User) that read pages without running the browser tag. Needs the server key from `issue_server_collect_key`; keep it in the environment.
+
+```python
+import os
+from seolyticize.collect import ASGICollector, Collector, WSGICollector, django_middleware
+
+collector = Collector("SITE_KEY", os.environ["SEOLYTICIZE_SERVER_KEY"],
+                      exclude=["/admin/*", "/api/*"],
+                      only="agents")  # with the browser tag installed too; "all" without it
+
+app.wsgi_app = WSGICollector(app.wsgi_app, collector)      # Flask
+app = ASGICollector(app, collector)                         # FastAPI / Starlette
+SeolyticizeMiddleware = django_middleware(collector)        # Django: add to MIDDLEWARE
+```
+
+Only the path and `utm_*` parameters (change with `allow_params`), the referrer's origin, the visitor's address, user agent and country are sent; Seolyticize hashes the address and user agent under a daily salt and stores neither. Bots are dropped before anything is sent. Reports go out on a background thread and never raise.
+
+To credit orders to the visit they came from, send a reference from the checkout — the tag's `seolyticize('event', 'Checkout', {ref: cartId})`, or `collector.track(checkout_url, name="Checkout", props={"ref": cart_id}, user_agent=…, ip=…)` with the visitor's own agent and address so it joins their visit — and put the same value in the order's metadata as `seolyticize_ref` (Stripe metadata, a Shopify cart attribute, Paddle `custom_data`).
+
+A conversion that happens after the visit — a payment confirmed by webhook, a trial that converts next week — is credited to the visit by its token. Ask for it while the visitor is there and keep it on your server with the account (never in a cookie or the page); the token lasts 35 days:
+
+```python
+visit = collector.track_for_visit(request.url, "Signup", user_agent=ua, ip=ip)  # returns the token
+account.seolyticize_visit = visit
+# ...days later, from the payment webhook:
+collector.track_later(account.seolyticize_visit, "Top-up", props={"value": 25})
+```
+
+Docs: [seolyticize.com/docs/python-sdk](https://seolyticize.com/docs/python-sdk) · Agent quick start: [seolyticize.com/AGENTS.md](https://seolyticize.com/AGENTS.md)
+
+The tool methods are generated from the same registry that runs the API. License: MIT.

seolyticize-0.4.0/pyproject.toml

@@ -0,0 +1,25 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "seolyticize"
+version = "0.4.0"
+description = "Seolyticize for Python: every API tool as a method, and on-site helpers for analytics, IndexNow and deploys."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.9"
+dependencies = []
+classifiers = [
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Topic :: Internet :: WWW/HTTP :: Site Management",
+]
+
+[project.urls]
+Homepage = "https://seolyticize.com"
+Documentation = "https://seolyticize.com/docs/python-sdk"
+Source = "https://github.com/Seolyticize/sdk-python"
+
+[tool.setuptools.packages.find]
+where = ["src"]

seolyticize-0.4.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

seolyticize-0.4.0/src/seolyticize/__init__.py

@@ -0,0 +1,31 @@
+"""Seolyticize: the API client, and on-site helpers in :mod:`seolyticize.site`."""
+
+from ._client import DEFAULT_BASE_URL, VERSION, Seolyticize
+from ._tools import TOOL_COUNT
+from .errors import (
+    AuthenticationError,
+    NetworkError,
+    NotFoundError,
+    PermissionError,
+    RateLimitError,
+    RefusedError,
+    SeolyticizeError,
+    ServerError,
+    ValidationError,
+)
+
+__version__ = VERSION
+__all__ = [
+    "Seolyticize",
+    "DEFAULT_BASE_URL",
+    "TOOL_COUNT",
+    "SeolyticizeError",
+    "ValidationError",
+    "AuthenticationError",
+    "PermissionError",
+    "NotFoundError",
+    "RefusedError",
+    "RateLimitError",
+    "ServerError",
+    "NetworkError",
+]

seolyticize-0.4.0/src/seolyticize/_client.py

@@ -0,0 +1,152 @@
+"""The client: one call() for any tool, and a typed method per tool on top."""
+
+from __future__ import annotations
+
+import json
+import os
+import random
+import time
+import urllib.error
+import urllib.request
+from typing import Any, Callable, Dict, Optional
+
+from ._tools import READ_ONLY_TOOLS, Tools
+from .errors import NetworkError, RateLimitError, SeolyticizeError, error_for_status
+
+DEFAULT_BASE_URL = "https://seolyticize.com"
+VERSION = "0.4.0"
+
+
+class Seolyticize(Tools):
+    """A Seolyticize API client.
+
+    >>> client = Seolyticize()  # reads SEOLYTICIZE_API_KEY
+    >>> client.get_next_steps(client_id="client_…")
+
+    Every tool is a method (``client.onboard_site(domain="example.com")``), and
+    ``client.call("tool_name", {...})`` reaches tools newer than this SDK.
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: Optional[str] = None,
+        timeout: float = 60.0,
+        max_retries: int = 2,
+        max_retry_after: float = 60.0,
+        sleep: Callable[[float], None] = time.sleep,
+    ) -> None:
+        key = api_key or os.environ.get("SEOLYTICIZE_API_KEY")
+        if not key:
+            raise SeolyticizeError(
+                "An API key is required: pass api_key or set SEOLYTICIZE_API_KEY.",
+                code="no_api_key",
+            )
+        self.api_key = key
+        self.base_url = (base_url or os.environ.get("SEOLYTICIZE_BASE_URL") or DEFAULT_BASE_URL).rstrip("/")
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self.max_retry_after = max_retry_after
+        self._sleep = sleep
+        #: The X-RateLimit-* headers from the latest response.
+        self.last_rate_limit: Dict[str, Optional[int]] = {}
+
+    # -- requests ----------------------------------------------------------
+
+    def _request(self, method: str, path: str, body: Optional[Dict[str, Any]], tool: Optional[str], retry_transient: bool) -> Any:
+        data = None if body is None else json.dumps(body).encode("utf-8")
+        attempt = 0
+        while True:
+            request = urllib.request.Request(
+                self.base_url + path,
+                data=data,
+                method=method,
+                headers={
+                    "authorization": f"Bearer {self.api_key}",
+                    "content-type": "application/json",
+                    "accept": "application/json",
+                    "user-agent": f"seolyticize-python/{VERSION}",
+                },
+            )
+            try:
+                with urllib.request.urlopen(request, timeout=self.timeout) as response:
+                    self._remember_rate(response.headers)
+                    payload = json.loads(response.read().decode("utf-8") or "{}")
+                    return payload.get("data", payload)
+            except urllib.error.HTTPError as failure:
+                self._remember_rate(failure.headers)
+                status = failure.code
+                details = _details(failure)
+                retry_after = _float(failure.headers.get("retry-after"))
+                can_retry = attempt < self.max_retries
+                if status == 429 and can_retry and (retry_after or 0) <= self.max_retry_after:
+                    self._sleep(retry_after if retry_after is not None else _backoff(attempt))
+                    attempt += 1
+                    continue
+                if status >= 500 and retry_transient and can_retry:
+                    self._sleep(_backoff(attempt))
+                    attempt += 1
+                    continue
+                extra = {"retry_after": retry_after} if status == 429 else {}
+                raise error_for_status(status, details["message"], code=details["code"], next=details["next"], request_id=details["request_id"], tool=tool, **extra) from None
+            except (urllib.error.URLError, TimeoutError, ConnectionError) as failure:
+                if retry_transient and attempt < self.max_retries:
+                    self._sleep(_backoff(attempt))
+                    attempt += 1
+                    continue
+                raise NetworkError(f"No response from {self.base_url}: {failure}", tool=tool) from None
+
+    def _remember_rate(self, headers: Any) -> None:
+        if headers is None:
+            return
+        self.last_rate_limit = {
+            "limit": _int(headers.get("x-ratelimit-limit")),
+            "remaining": _int(headers.get("x-ratelimit-remaining")),
+            "reset_seconds": _int(headers.get("x-ratelimit-reset")),
+        }
+
+    # -- public ------------------------------------------------------------
+
+    def call(self, tool: str, input: Optional[Dict[str, Any]] = None) -> Any:
+        """Calls any tool by name with a JSON-shaped input (camelCase keys, as the API takes them)."""
+        # A tool this SDK has never heard of may be a write; it is not retried
+        # on server errors, since repeating a write could do it twice.
+        return self._request("POST", f"/api/v1/tools/{tool}", input or {}, tool, tool in READ_ONLY_TOOLS)
+
+    def list_tools(self, group: Optional[str] = None) -> Dict[str, Any]:
+        """The tools this key may call, with their schemas; ``group`` narrows to one job (onboarding, weekly, technical, research, reporting)."""
+        query = f"?group={group}" if group else ""
+        return self._request("GET", f"/api/v1/tools{query}", None, None, True)
+
+
+def _details(failure: urllib.error.HTTPError) -> Dict[str, Optional[str]]:
+    try:
+        body = json.loads(failure.read().decode("utf-8") or "{}")
+    except Exception:  # an HTML error page from a proxy
+        body = {}
+    text = lambda value: value if isinstance(value, str) and value else None  # noqa: E731
+    return {
+        "message": text(body.get("error")) or f"HTTP {failure.code}",
+        "code": text(body.get("code")),
+        "next": text(body.get("next")),
+        "request_id": text(body.get("requestId")) or failure.headers.get("x-request-id"),
+    }
+
+
+def _backoff(attempt: int) -> float:
+    return min(8.0, 0.5 * (2**attempt)) * (0.5 + random.random() / 2)
+
+
+def _int(value: Optional[str]) -> Optional[int]:
+    try:
+        return int(value) if value is not None else None
+    except ValueError:
+        return None
+
+
+def _float(value: Optional[str]) -> Optional[float]:
+    try:
+        return float(value) if value is not None else None
+    except ValueError:
+        return None