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.
