linkshieldai 0.2.0__tar.gz

linkshieldai-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,36 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install package
+        run: python -m pip install -e ".[dev]"
+      - name: Run tests
+        run: python -m pytest
+
+  package:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install build tools
+        run: python -m pip install build twine
+      - name: Build package
+        run: python -m build
+      - name: Check package
+        run: python -m twine check dist/*

linkshieldai-0.2.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.venv/
+venv/
+dist/
+build/
+*.egg-info/
+.env
+screenshot.png

linkshieldai-0.2.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,228 @@
+# 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/examples/async_usage.py

@@ -0,0 +1,12 @@
+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())

linkshieldai-0.2.0/examples/basic_check.py

@@ -0,0 +1,8 @@
+from linkshieldai import LinkShieldAI
+
+
+client = LinkShieldAI(api_key="test-key")
+result = client.basic_check("https://example.com")
+
+print(result.result)
+print("malicious:", result.is_malicious)

linkshieldai-0.2.0/examples/chimera_check.py

@@ -0,0 +1,9 @@
+from linkshieldai import LinkShieldAI
+
+
+client = LinkShieldAI(api_key="test-key")
+result = client.chimera("https://google.com")
+
+print("result:", result.result)
+print("probability:", result.probability)
+print("method:", result.detection_method)

linkshieldai-0.2.0/examples/detailed_with_screenshot.py

@@ -0,0 +1,13 @@
+from linkshieldai import LinkShieldAI
+
+
+client = LinkShieldAI(api_key="test-key")
+result = client.detailed_check("https://example.com")
+
+print("result:", result.result)
+print("tag:", result.tag)
+print("screenshot:", result.screenshot_url)
+
+if result.screenshot_url:
+    client.get_screenshot(result.screenshot_url, "screenshot.png")
+    print("saved screenshot.png")

linkshieldai-0.2.0/examples/nsfw_check.py

@@ -0,0 +1,7 @@
+from linkshieldai import LinkShieldAI
+
+
+client = LinkShieldAI(api_key="test-key")
+result = client.nsfw_check("https://example.com")
+
+print("nsfw:", result.is_nsfw)

linkshieldai-0.2.0/pyproject.toml

@@ -0,0 +1,48 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "linkshieldai"
+version = "0.2.0"
+description = "Python SDK for the LinkShieldAI URL safety API."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [
+    { name = "LinkShieldAI" }
+]
+keywords = ["linkshieldai", "phishing", "url-safety", "security", "sdk"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Security",
+    "Topic :: Software Development :: Libraries :: Python Modules"
+]
+dependencies = [
+    "httpx>=0.27.0,<1"
+]
+
+[project.scripts]
+linkshieldai = "linkshieldai.cli:main"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.23.0",
+    "build>=1.2.0",
+    "twine>=5.0.0"
+]
+
+[project.urls]
+Homepage = "https://linkshieldai.com"
+Documentation = "https://docs.linkshieldai.com"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"

linkshieldai-0.2.0/src/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",
+]