linkshieldai 0.2.0__py3-none-any.whl

linkshieldai/__init__.py

@@ -0,0 +1,26 @@
+from .async_client import AsyncLinkShieldAI
+from .client import LinkShieldAI
+from .errors import (
+    APIConnectionError,
+    APIResponseError,
+    APIStatusError,
+    AuthenticationError,
+    LinkShieldAIError,
+    RateLimitError,
+)
+from .types import BasicCheckResult, ChimeraResult, DetailedCheckResult, NSFWCheckResult
+
+__all__ = [
+    "APIConnectionError",
+    "APIResponseError",
+    "APIStatusError",
+    "AsyncLinkShieldAI",
+    "AuthenticationError",
+    "BasicCheckResult",
+    "ChimeraResult",
+    "DetailedCheckResult",
+    "LinkShieldAI",
+    "LinkShieldAIError",
+    "NSFWCheckResult",
+    "RateLimitError",
+]

linkshieldai/_transport.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+import json
+import logging
+import time
+from typing import Any
+
+import httpx
+
+from .errors import APIConnectionError, APIResponseError, APIStatusError, RateLimitError, error_message_from_payload
+
+
+RETRYABLE_STATUS_CODES = {429, 502, 503, 504}
+
+
+def parse_retry_after(value: str | None) -> float | None:
+    if not value:
+        return None
+    try:
+        return max(float(value), 0.0)
+    except ValueError:
+        return None
+
+
+def parse_json_response(response: httpx.Response) -> dict[str, Any]:
+    try:
+        payload = response.json()
+    except ValueError as exc:
+        content_type = response.headers.get("content-type", "")
+        preview = response.text.strip().replace("\n", " ")[:300]
+        message = "LinkShieldAI API returned invalid JSON."
+        if preview:
+            message = f"{message} Content-Type: {content_type or 'unknown'}. Body preview: {preview}"
+        raise APIResponseError(message) from exc
+    if not isinstance(payload, dict):
+        raise APIResponseError("LinkShieldAI API returned a non-object JSON response.", payload=payload)
+    return payload
+
+
+def handle_status_error(response: httpx.Response) -> None:
+    if response.status_code < 400:
+        return
+    payload = None
+    try:
+        payload = response.json()
+    except ValueError:
+        pass
+    if response.status_code == 429:
+        retry_after = parse_retry_after(response.headers.get("retry-after"))
+        raise RateLimitError(retry_after=retry_after)
+    message = error_message_from_payload(payload, f"LinkShieldAI API returned HTTP {response.status_code}.")
+    raise APIStatusError(message, status_code=response.status_code, response=response, payload=payload)
+
+
+def retry_delay(attempt: int, backoff_factor: float, response: httpx.Response | None = None) -> float:
+    if response is not None:
+        retry_after = parse_retry_after(response.headers.get("retry-after"))
+        if retry_after is not None:
+            return retry_after
+    return backoff_factor * (2 ** attempt)
+
+
+def should_retry_response(response: httpx.Response, attempt: int, max_retries: int) -> bool:
+    return attempt < max_retries and response.status_code in RETRYABLE_STATUS_CODES
+
+
+def should_retry_exception(exc: httpx.RequestError, attempt: int, max_retries: int) -> bool:
+    return attempt < max_retries and isinstance(exc, (httpx.ConnectError, httpx.ConnectTimeout, httpx.ReadTimeout, httpx.PoolTimeout))
+
+
+def log_request(logger: logging.Logger, method: str, url: str) -> None:
+    logger.debug("LinkShieldAI request: %s %s", method, url)
+
+
+def log_retry(logger: logging.Logger, attempt: int, delay: float, reason: str) -> None:
+    logger.debug("LinkShieldAI retry %s in %.2fs: %s", attempt + 1, delay, reason)

linkshieldai/_utils.py

@@ -0,0 +1,122 @@
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any, Mapping
+from urllib.parse import urlparse
+
+from .errors import APIResponseError, AuthenticationError, error_message_from_payload
+from .types import BasicCheckResult, ChimeraResult, DetailedCheckResult, NSFWCheckResult, RawJSON
+
+
+DEFAULT_BASE_URL = "https://api.linkshieldai.com"
+
+
+def normalize_base_url(base_url: str) -> str:
+    return base_url.rstrip("/")
+
+
+def resolve_api_key(api_key: str | None) -> str:
+    resolved = api_key or os.getenv("LINKSHIELDAI_API_KEY")
+    if not resolved:
+        raise AuthenticationError(
+            "LinkShieldAI API key is required. Pass api_key=... or set LINKSHIELDAI_API_KEY."
+        )
+    return resolved
+
+
+def ensure_json_payload(payload: Any) -> RawJSON:
+    if not isinstance(payload, dict):
+        raise APIResponseError("LinkShieldAI API returned a non-object JSON response.", payload=payload)
+    if payload.get("Error") or payload.get("error"):
+        raise APIResponseError(error_message_from_payload(payload), payload=payload)
+    return payload
+
+
+def is_malicious_text(result: Any) -> bool:
+    value = str(result or "").strip().lower()
+    safe_phrases = ("didn't detect", "did not detect", "no malicious", "not malicious")
+    if any(phrase in value for phrase in safe_phrases):
+        return False
+    return value in {"might be malicious", "malicious", "true"} or "malicious" in value
+
+
+def is_safe_text(result: Any) -> bool:
+    value = str(result or "").strip().lower()
+    return value in {
+        "likely safe",
+        "the system didn't detect anything malicious.",
+        "false",
+        "benign",
+    } or "safe" in value or "benign" in value
+
+
+def parse_basic(payload: Mapping[str, Any]) -> BasicCheckResult:
+    raw = dict(payload)
+    result = raw.get("result")
+    return BasicCheckResult(
+        result=str(result) if result is not None else None,
+        is_malicious=is_malicious_text(result),
+        is_safe=is_safe_text(result),
+        raw=raw,
+    )
+
+
+def parse_detailed(payload: Mapping[str, Any]) -> DetailedCheckResult:
+    raw = dict(payload)
+    result = raw.get("result")
+    screenshot_url = raw.get("screenshot url") or raw.get("screenshot_url")
+    tag = raw.get("tag")
+    return DetailedCheckResult(
+        result=str(result) if result is not None else None,
+        screenshot_url=str(screenshot_url) if screenshot_url else None,
+        tag=str(tag) if tag is not None else None,
+        is_malicious=is_malicious_text(result),
+        raw=raw,
+    )
+
+
+def parse_nsfw(payload: Mapping[str, Any]) -> NSFWCheckResult:
+    raw = dict(payload)
+    result = raw.get("result")
+    is_nsfw = str(result or "").strip().lower() == "true"
+    return NSFWCheckResult(
+        result=str(result) if result is not None else None,
+        is_nsfw=is_nsfw,
+        raw=raw,
+    )
+
+
+def parse_chimera(payload: Mapping[str, Any]) -> ChimeraResult:
+    raw = dict(payload)
+    result = raw.get("result")
+    probability = raw.get("probability")
+    matched_signatures = raw.get("matched_signatures")
+    try:
+        probability_value = float(probability) if probability is not None else None
+    except (TypeError, ValueError):
+        probability_value = None
+    try:
+        matched_value = int(matched_signatures) if matched_signatures is not None else None
+    except (TypeError, ValueError):
+        matched_value = None
+    return ChimeraResult(
+        result=str(result) if result is not None else None,
+        probability=probability_value,
+        detection_method=str(raw["detection_method"]) if raw.get("detection_method") is not None else None,
+        matched_signatures=matched_value,
+        url=str(raw["url"]) if raw.get("url") is not None else None,
+        is_malicious=is_malicious_text(result),
+        raw=raw,
+    )
+
+
+def screenshot_file_name(file_name_or_url: str) -> str:
+    parsed = urlparse(file_name_or_url)
+    if parsed.scheme and parsed.path:
+        candidate = Path(parsed.path).name
+    else:
+        candidate = Path(file_name_or_url).name
+    if not candidate:
+        raise ValueError("A screenshot file name or screenshot URL is required.")
+    return candidate

linkshieldai/async_client.py

@@ -0,0 +1,113 @@
+from __future__ import annotations
+
+import asyncio
+import logging
+from pathlib import Path
+
+import httpx
+
+from ._utils import (
+    DEFAULT_BASE_URL,
+    normalize_base_url,
+    parse_basic,
+    parse_chimera,
+    parse_detailed,
+    parse_nsfw,
+    resolve_api_key,
+    screenshot_file_name,
+)
+from ._transport import handle_status_error, log_request, log_retry, parse_json_response, retry_delay, should_retry_exception, should_retry_response
+from .errors import APIConnectionError
+from .types import BasicCheckResult, ChimeraResult, DetailedCheckResult, NSFWCheckResult
+
+
+class AsyncLinkShieldAI:
+    """Asynchronous client for the LinkShieldAI API."""
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float | httpx.Timeout = 10.0,
+        max_retries: int = 2,
+        backoff_factor: float = 0.5,
+        logger: logging.Logger | None = None,
+        client: httpx.AsyncClient | None = None,
+    ) -> None:
+        self.api_key = resolve_api_key(api_key)
+        self.base_url = normalize_base_url(base_url)
+        self.max_retries = max(0, max_retries)
+        self.backoff_factor = max(0.0, backoff_factor)
+        self.logger = logger or logging.getLogger("linkshieldai")
+        self._owns_client = client is None
+        self._client = client or httpx.AsyncClient(timeout=timeout)
+
+    async def close(self) -> None:
+        if self._owns_client:
+            await self._client.aclose()
+
+    async def __aenter__(self) -> "AsyncLinkShieldAI":
+        return self
+
+    async def __aexit__(self, *args: object) -> None:
+        await self.close()
+
+    async def basic_check(self, url: str) -> BasicCheckResult:
+        payload = await self._get_json("/", params={"key": self.api_key, "url": url})
+        return parse_basic(payload)
+
+    async def detailed_check(self, url: str) -> DetailedCheckResult:
+        payload = await self._get_json("/classify_link", params={"key": self.api_key, "url": url})
+        return parse_detailed(payload)
+
+    async def nsfw_check(self, url: str) -> NSFWCheckResult:
+        payload = await self._get_json("/nsfw/site", params={"key": self.api_key, "url": url})
+        return parse_nsfw(payload)
+
+    async def chimera(self, url: str) -> ChimeraResult:
+        payload = await self._get_json("/chimera", params={"key": self.api_key, "url": url})
+        return parse_chimera(payload)
+
+    async def is_malicious(self, url: str) -> bool:
+        return (await self.basic_check(url)).is_malicious
+
+    async def is_nsfw(self, url: str) -> bool:
+        return (await self.nsfw_check(url)).is_nsfw
+
+    async def get_screenshot(self, file_name_or_url: str, output_path: str | Path | None = None) -> bytes:
+        file_name = screenshot_file_name(file_name_or_url)
+        response = await self._request("GET", f"/screenshot/{file_name}")
+        content = response.content
+        if output_path is not None:
+            Path(output_path).write_bytes(content)
+        return content
+
+    async def _get_json(self, path: str, *, params: dict[str, object]) -> dict[str, object]:
+        response = await self._request("GET", path, params=params)
+        payload = parse_json_response(response)
+        from ._utils import ensure_json_payload
+
+        return ensure_json_payload(payload)
+
+    async def _request(self, method: str, path: str, **kwargs: object) -> httpx.Response:
+        url = f"{self.base_url}{path}"
+        for attempt in range(self.max_retries + 1):
+            log_request(self.logger, method, url)
+            try:
+                response = await self._client.request(method, url, **kwargs)
+            except httpx.RequestError as exc:
+                if should_retry_exception(exc, attempt, self.max_retries):
+                    delay = retry_delay(attempt, self.backoff_factor)
+                    log_retry(self.logger, attempt, delay, str(exc))
+                    await asyncio.sleep(delay)
+                    continue
+                raise APIConnectionError(f"Could not connect to LinkShieldAI API: {exc}") from exc
+            if should_retry_response(response, attempt, self.max_retries):
+                delay = retry_delay(attempt, self.backoff_factor, response)
+                log_retry(self.logger, attempt, delay, f"HTTP {response.status_code}")
+                await asyncio.sleep(delay)
+                continue
+            handle_status_error(response)
+            return response
+        raise APIConnectionError("Could not connect to LinkShieldAI API after retries.")

linkshieldai/cli.py

@@ -0,0 +1,86 @@
+from __future__ import annotations
+
+import argparse
+import dataclasses
+import json
+import logging
+import sys
+from typing import Any
+
+from .client import LinkShieldAI
+from .errors import LinkShieldAIError
+
+
+def result_to_jsonable(value: Any) -> Any:
+    if dataclasses.is_dataclass(value):
+        return dataclasses.asdict(value)
+    if isinstance(value, bytes):
+        return {"bytes": len(value)}
+    return value
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="linkshieldai", description="Command line client for the LinkShieldAI API.")
+    parser.add_argument("--api-key", help="LinkShieldAI API key. Defaults to LINKSHIELDAI_API_KEY.")
+    parser.add_argument("--base-url", default="https://api.linkshieldai.com", help="API base URL.")
+    parser.add_argument("--timeout", type=float, default=10.0, help="Request timeout in seconds.")
+    parser.add_argument("--max-retries", type=int, default=2, help="Retry attempts for transient failures.")
+    parser.add_argument("--debug", action="store_true", help="Enable debug logging.")
+
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    basic = subparsers.add_parser("basic", help="Run a basic URL safety check.")
+    basic.add_argument("url")
+
+    detailed = subparsers.add_parser("detailed", help="Run a detailed URL safety check.")
+    detailed.add_argument("url")
+
+    nsfw = subparsers.add_parser("nsfw", help="Run an NSFW URL check.")
+    nsfw.add_argument("url")
+
+    chimera = subparsers.add_parser("chimera", help="Run Chimera AI classification.")
+    chimera.add_argument("url")
+
+    screenshot = subparsers.add_parser("screenshot", help="Download a screenshot by file name or screenshot URL.")
+    screenshot.add_argument("file_name_or_url")
+    screenshot.add_argument("--output", "-o", required=True, help="Output image path.")
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    logging.basicConfig(level=logging.DEBUG if args.debug else logging.WARNING)
+
+    try:
+        with LinkShieldAI(
+            api_key=args.api_key,
+            base_url=args.base_url,
+            timeout=args.timeout,
+            max_retries=args.max_retries,
+        ) as client:
+            if args.command == "basic":
+                result = client.basic_check(args.url)
+            elif args.command == "detailed":
+                result = client.detailed_check(args.url)
+            elif args.command == "nsfw":
+                result = client.nsfw_check(args.url)
+            elif args.command == "chimera":
+                result = client.chimera(args.url)
+            elif args.command == "screenshot":
+                client.get_screenshot(args.file_name_or_url, args.output)
+                result = {"saved": args.output}
+            else:
+                parser.error(f"Unknown command: {args.command}")
+                return 2
+    except LinkShieldAIError as exc:
+        print(json.dumps({"error": str(exc)}, indent=2), file=sys.stderr)
+        return 1
+
+    print(json.dumps(result_to_jsonable(result), indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

linkshieldai/client.py

@@ -0,0 +1,113 @@
+from __future__ import annotations
+
+import logging
+import time
+from pathlib import Path
+
+import httpx
+
+from ._utils import (
+    DEFAULT_BASE_URL,
+    normalize_base_url,
+    parse_basic,
+    parse_chimera,
+    parse_detailed,
+    parse_nsfw,
+    resolve_api_key,
+    screenshot_file_name,
+)
+from ._transport import handle_status_error, log_request, log_retry, parse_json_response, retry_delay, should_retry_exception, should_retry_response
+from .errors import APIConnectionError
+from .types import BasicCheckResult, ChimeraResult, DetailedCheckResult, NSFWCheckResult
+
+
+class LinkShieldAI:
+    """Synchronous client for the LinkShieldAI API."""
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float | httpx.Timeout = 10.0,
+        max_retries: int = 2,
+        backoff_factor: float = 0.5,
+        logger: logging.Logger | None = None,
+        client: httpx.Client | None = None,
+    ) -> None:
+        self.api_key = resolve_api_key(api_key)
+        self.base_url = normalize_base_url(base_url)
+        self.max_retries = max(0, max_retries)
+        self.backoff_factor = max(0.0, backoff_factor)
+        self.logger = logger or logging.getLogger("linkshieldai")
+        self._owns_client = client is None
+        self._client = client or httpx.Client(timeout=timeout)
+
+    def close(self) -> None:
+        if self._owns_client:
+            self._client.close()
+
+    def __enter__(self) -> "LinkShieldAI":
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()
+
+    def basic_check(self, url: str) -> BasicCheckResult:
+        payload = self._get_json("/", params={"key": self.api_key, "url": url})
+        return parse_basic(payload)
+
+    def detailed_check(self, url: str) -> DetailedCheckResult:
+        payload = self._get_json("/classify_link", params={"key": self.api_key, "url": url})
+        return parse_detailed(payload)
+
+    def nsfw_check(self, url: str) -> NSFWCheckResult:
+        payload = self._get_json("/nsfw/site", params={"key": self.api_key, "url": url})
+        return parse_nsfw(payload)
+
+    def chimera(self, url: str) -> ChimeraResult:
+        payload = self._get_json("/chimera", params={"key": self.api_key, "url": url})
+        return parse_chimera(payload)
+
+    def is_malicious(self, url: str) -> bool:
+        return self.basic_check(url).is_malicious
+
+    def is_nsfw(self, url: str) -> bool:
+        return self.nsfw_check(url).is_nsfw
+
+    def get_screenshot(self, file_name_or_url: str, output_path: str | Path | None = None) -> bytes:
+        file_name = screenshot_file_name(file_name_or_url)
+        response = self._request("GET", f"/screenshot/{file_name}")
+        content = response.content
+        if output_path is not None:
+            Path(output_path).write_bytes(content)
+        return content
+
+    def _get_json(self, path: str, *, params: dict[str, object]) -> dict[str, object]:
+        response = self._request("GET", path, params=params)
+        payload = parse_json_response(response)
+        from ._utils import ensure_json_payload
+
+        return ensure_json_payload(payload)
+
+    def _request(self, method: str, path: str, **kwargs: object) -> httpx.Response:
+        url = f"{self.base_url}{path}"
+        for attempt in range(self.max_retries + 1):
+            log_request(self.logger, method, url)
+            try:
+                response = self._client.request(method, url, **kwargs)
+            except httpx.RequestError as exc:
+                if should_retry_exception(exc, attempt, self.max_retries):
+                    delay = retry_delay(attempt, self.backoff_factor)
+                    log_retry(self.logger, attempt, delay, str(exc))
+                    time.sleep(delay)
+                    continue
+                raise APIConnectionError(f"Could not connect to LinkShieldAI API: {exc}") from exc
+            if should_retry_response(response, attempt, self.max_retries):
+                delay = retry_delay(attempt, self.backoff_factor, response)
+                log_retry(self.logger, attempt, delay, f"HTTP {response.status_code}")
+                time.sleep(delay)
+                continue
+            handle_status_error(response)
+            return response
+        raise APIConnectionError("Could not connect to LinkShieldAI API after retries.")

linkshieldai/errors.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+from typing import Any, Optional
+
+
+class LinkShieldAIError(Exception):
+    """Base exception for all SDK errors."""
+
+
+class AuthenticationError(LinkShieldAIError):
+    """Raised when an API key is missing or rejected."""
+
+
+class RateLimitError(LinkShieldAIError):
+    """Raised when the API reports a rate limit response."""
+
+    def __init__(self, message: str = "LinkShieldAI API rate limit exceeded.", *, retry_after: float | None = None) -> None:
+        super().__init__(message)
+        self.retry_after = retry_after
+
+
+class APIConnectionError(LinkShieldAIError):
+    """Raised when the SDK cannot connect to the API."""
+
+
+class APIStatusError(LinkShieldAIError):
+    """Raised for non-success HTTP responses."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int,
+        response: Any | None = None,
+        payload: Any | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.response = response
+        self.payload = payload
+
+
+class APIResponseError(LinkShieldAIError):
+    """Raised when the API returns a JSON error payload."""
+
+    def __init__(self, message: str, *, payload: Any | None = None) -> None:
+        super().__init__(message)
+        self.payload = payload
+
+
+def error_message_from_payload(payload: Any, fallback: Optional[str] = None) -> str:
+    if isinstance(payload, dict):
+        for key in ("Error", "error", "message", "detail"):
+            value = payload.get(key)
+            if value:
+                return str(value)
+    return fallback or "LinkShieldAI API request failed."

linkshieldai/types.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Dict, Optional
+
+
+RawJSON = Dict[str, Any]
+
+
+@dataclass(frozen=True)
+class BasicCheckResult:
+    result: Optional[str]
+    is_malicious: bool
+    is_safe: bool
+    raw: RawJSON
+
+
+@dataclass(frozen=True)
+class DetailedCheckResult:
+    result: Optional[str]
+    screenshot_url: Optional[str]
+    tag: Optional[str]
+    is_malicious: bool
+    raw: RawJSON
+
+
+@dataclass(frozen=True)
+class NSFWCheckResult:
+    result: Optional[str]
+    is_nsfw: bool
+    raw: RawJSON
+
+
+@dataclass(frozen=True)
+class ChimeraResult:
+    result: Optional[str]
+    probability: Optional[float]
+    detection_method: Optional[str]
+    matched_signatures: Optional[int]
+    url: Optional[str]
+    is_malicious: bool
+    raw: RawJSON

linkshieldai-0.2.0.dist-info/METADATA

@@ -0,0 +1,255 @@
+Metadata-Version: 2.4
+Name: linkshieldai
+Version: 0.2.0
+Summary: Python SDK for the LinkShieldAI URL safety API.
+Project-URL: Homepage, https://linkshieldai.com
+Project-URL: Documentation, https://docs.linkshieldai.com
+Author: LinkShieldAI
+License: MIT
+Keywords: linkshieldai,phishing,sdk,security,url-safety
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: httpx<1,>=0.27.0
+Provides-Extra: dev
+Requires-Dist: build>=1.2.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: twine>=5.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# LinkShieldAI Python SDK
+
+Python wrapper for the LinkShieldAI API at `https://api.linkshieldai.com`.
+
+The SDK supports:
+
+- Basic URL safety checks
+- Detailed checks with screenshot URL and detected tag
+- Screenshot download
+- NSFW site checks
+- Chimera AI classification
+- Sync and async clients
+- Retry/backoff for transient API failures
+- A small command-line tool
+
+## Install
+
+From this folder:
+
+```bash
+python -m pip install -e .
+```
+
+For tests:
+
+```bash
+python -m pip install -e ".[dev]"
+python -m pytest
+```
+
+## Authentication
+
+The API uses a query parameter named `key`.
+
+Pass the API key directly:
+
+```python
+from linkshieldai import LinkShieldAI
+
+client = LinkShieldAI(api_key="YOUR_API_KEY")
+```
+
+Or set an environment variable:
+
+```powershell
+$env:LINKSHIELDAI_API_KEY = "YOUR_API_KEY"
+```
+
+```python
+from linkshieldai import LinkShieldAI
+
+client = LinkShieldAI()
+```
+
+## Basic Check
+
+Wraps:
+
+```text
+GET https://api.linkshieldai.com/?key={key}&url={url}
+```
+
+```python
+from linkshieldai import LinkShieldAI
+
+client = LinkShieldAI()
+result = client.basic_check("https://example.com")
+
+print(result.result)
+print(result.is_malicious)
+print(result.raw)
+```
+
+## Detailed Check
+
+Wraps:
+
+```text
+GET https://api.linkshieldai.com/classify_link?key={key}&url={url}
+```
+
+```python
+result = client.detailed_check("https://example.com")
+
+print(result.result)
+print(result.screenshot_url)
+print(result.tag)
+```
+
+The API field `"screenshot url"` is normalized to `screenshot_url`.
+
+## Download Screenshot
+
+Wraps:
+
+```text
+GET https://api.linkshieldai.com/screenshot/{file_name}
+```
+
+```python
+image_bytes = client.get_screenshot("05046f.png")
+client.get_screenshot("https://api.linkshieldai.com/screenshot/05046f.png", "site.png")
+```
+
+## NSFW Check
+
+Wraps:
+
+```text
+GET https://api.linkshieldai.com/nsfw/site?key={key}&url={url}
+```
+
+```python
+result = client.nsfw_check("https://example.com")
+print(result.is_nsfw)
+```
+
+## Chimera Check
+
+Wraps:
+
+```text
+GET https://api.linkshieldai.com/chimera?key={key}&url={url}
+```
+
+```python
+result = client.chimera("https://google.com")
+
+print(result.result)
+print(result.probability)
+print(result.detection_method)
+print(result.matched_signatures)
+```
+
+## Async Usage
+
+```python
+import asyncio
+from linkshieldai import AsyncLinkShieldAI
+
+
+async def main():
+    async with AsyncLinkShieldAI() as client:
+        result = await client.chimera("https://google.com")
+        print(result.result, result.probability)
+
+
+asyncio.run(main())
+```
+
+## Custom API Host
+
+The default host is:
+
+```text
+https://api.linkshieldai.com
+```
+
+You can override it for staging or testing:
+
+```python
+client = LinkShieldAI(base_url="https://api.linkshieldai.com")
+```
+
+## Timeouts, Retries, and Logging
+
+By default the SDK uses:
+
+- `timeout=10.0`
+- `max_retries=2`
+- `backoff_factor=0.5`
+
+Retries are applied to temporary connection failures and HTTP `429`, `502`, `503`, and `504`.
+
+```python
+import logging
+from linkshieldai import LinkShieldAI
+
+logging.basicConfig(level=logging.DEBUG)
+
+client = LinkShieldAI(
+    timeout=15.0,
+    max_retries=3,
+    backoff_factor=1.0,
+)
+```
+
+## CLI
+
+After installation, use:
+
+```bash
+linkshieldai --api-key YOUR_API_KEY basic https://example.com
+linkshieldai --api-key YOUR_API_KEY detailed https://example.com
+linkshieldai --api-key YOUR_API_KEY nsfw https://example.com
+linkshieldai --api-key YOUR_API_KEY chimera https://google.com
+linkshieldai --api-key YOUR_API_KEY screenshot 05046f.png --output site.png
+```
+
+You can omit `--api-key` if `LINKSHIELDAI_API_KEY` is set.
+
+## Errors
+
+```python
+from linkshieldai import (
+    APIConnectionError,
+    APIResponseError,
+    APIStatusError,
+    AuthenticationError,
+    RateLimitError,
+)
+```
+
+- `AuthenticationError`: missing API key.
+- `RateLimitError`: HTTP 429.
+- `APIStatusError`: non-success HTTP status.
+- `APIResponseError`: malformed JSON or API payload with `Error` / `error`.
+- `APIConnectionError`: timeout, DNS, or connection failure.
+
+Raw API payloads are preserved on result objects through `.raw`.
+
+## Production Notes
+
+- Keep API keys server-side. Do not expose them in browser JavaScript.
+- Use `max_retries` with a small non-zero value for bots, moderation pipelines, and web apps.
+- Catch `RateLimitError` when running near the documented limits.
+- Tests are mocked by default and do not call the live API.
+- For live smoke tests, set `LINKSHIELDAI_API_KEY` and call the examples manually.

linkshieldai-0.2.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+linkshieldai/__init__.py,sha256=cTxC4q2jNRR5uiUUDiYnmp-6MGCBIvSGuAPrmtqbHKE,625
+linkshieldai/_transport.py,sha256=LyCnfwVGcgiC_WL2zdFYqFDY0jJ8q-BOnT19Y3FCU20,2759
+linkshieldai/_utils.py,sha256=XqKx8GUIpIL5kTxTYL6xI645qe2WLA8_qj02twaV4pA,4182
+linkshieldai/async_client.py,sha256=iWkR8sTmT8notU8e_vTrQ3NX2-VlkPzxWp4_VV-OrQU,4544
+linkshieldai/cli.py,sha256=tXKhAM75Hac3PbSYBZZGVvW2YsBovRpqsoS_7YUIZX0,3197
+linkshieldai/client.py,sha256=YKd3RvLN0ich4Vqt2IDWAQlcB935T_MnPGKMnmvGNwM,4357
+linkshieldai/errors.py,sha256=4zxfgMPqXOGtXhJNFthFtUXez6NJX3XwWKu9BLrgzSk,1653
+linkshieldai/types.py,sha256=MyLZBuv77LkNS6TZG0urNnwx--B6oi-kDh8Z5UcDaOI,799
+linkshieldai-0.2.0.dist-info/METADATA,sha256=Ys_I5uKZav3qeFaHV7NWtK1zaNm3aJY518bkWp5FYLk,5471
+linkshieldai-0.2.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+linkshieldai-0.2.0.dist-info/entry_points.txt,sha256=eiLlQC042-M3wJASaUsPhM5KQ6ij6Hh0--zqRrMySW4,55
+linkshieldai-0.2.0.dist-info/RECORD,,

linkshieldai-0.2.0.dist-info/WHEEL

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

linkshieldai-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+linkshieldai = linkshieldai.cli:main