Metadata-Version: 2.4
Name: licencore-sdk-python
Version: 0.1.0
Summary: Simple Python SDK to verify licences against a Licencore server (Django supported).
Author-email: CyberHuginn <contact@cyberhuginn.com>
Maintainer: Fardad Noavar
License-Expression: MIT
Project-URL: Homepage, https://fardadnoavar.ir
Project-URL: Author, https://cyberhuginn.com
Keywords: licence,license,licencore,sdk,django
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Framework :: Django
Classifier: Intended Audience :: Developers
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: django
Requires-Dist: Django>=3.2; extra == "django"
Dynamic: license-file

# licencore-sdk-python

**English** | [فارسی](#فارسی)

A tiny Python SDK that checks your licence against a Licencore server.
Zero dependencies. Works in any Python app and has built-in Django support.

## Install

```bash
pip install licencore-sdk-python
```

## Settings

| Name | Required | Default | Description |
|---|---|---|---|
| `SERVER_URL` | yes | – | Full URL of the licence check endpoint |
| `ACCESS_KEY` | yes | – | Your access key |
| `HEADER_KEY` | no | `X-Access-Key` | Header name used to send the key |
| `CHECK_INTERVAL_HOURS` | no | `6` | How often the server is contacted (hours) |
| `OFFLINE_GRACE_HOURS` | no | `24` | If the server is unreachable, keep trusting the last valid answer for this long |
| `TIMEOUT` | no | `10` | HTTP timeout in seconds |

Settings are read from environment variables (or Django `settings.py`).
You may use the `LICENCORE_` prefix (e.g. `LICENCORE_SERVER_URL`) to avoid name clashes.

```bash
export SERVER_URL="https://licence.example.com/api/check"
export HEADER_KEY="X-Access-Key"
export ACCESS_KEY="your-key"
```

## Usage

```python
import licencore

if licencore.is_valid():
    print("Licence OK")

status = licencore.status()
print(status.status, status.remaining_seconds, status.expires_at)

licencore.require()   # raises licencore.LicenceInvalid if not valid
```

Or pass settings in code:

```python
from licencore import LicenceClient

client = LicenceClient(
    server_url="https://licence.example.com/api/check",
    access_key="your-key",
    check_interval_hours=12,
)
client.require()
```

### How checking works

You don't need a scheduler. The SDK caches the answer and only calls the server
when the cache is older than `CHECK_INTERVAL_HOURS` (default: every 6 hours,
i.e. about 4 times a day). `remaining_seconds` is counted down locally between
checks. If the licence is invalid, or the server is down, it retries every
5 minutes, so a renewal is noticed quickly. Call `licencore.status(force=True)`
to force an immediate check.

## Django

```python
# settings.py
MIDDLEWARE = [
    # ...
    "licencore.django_support.LicenceMiddleware",
]

LICENCORE_SERVER_URL = "https://licence.example.com/api/check"
LICENCORE_ACCESS_KEY = "your-key"
LICENCORE_HEADER_KEY = "X-Access-Key"          # optional
LICENCORE_CHECK_INTERVAL_HOURS = 6             # optional
LICENCORE_EXEMPT_PATHS = ["/health/"]          # optional, paths that skip the check
```

When the licence is invalid, every request gets a `403` JSON response.
The status is available as `request.licence` in your views.

To protect only specific views:

```python
from licencore.django_support import licence_required

@licence_required
def my_view(request):
    ...
```

## Licence status fields

`valid`, `status`, `starts_at`, `expires_at`, `remaining_seconds`,
`starts_in_seconds`, `project_id`, `server_time`, plus `offline` (answer came
from cache because the server was unreachable) and `error`.

## Credits

Built by **CyberHuginn** for **Fardad Noavar** — [fardadnoavar.ir](https://fardadnoavar.ir)

---

<div id="فارسی"></div>

# فارسی

یک SDK خیلی ساده پایتون برای چک کردن لایسنس از سرور Licencore.
بدون وابستگی (dependency) و با پشتیبانی داخلی از Django.

## نصب

```bash
pip install licencore-sdk-python
```

## تنظیمات

| نام | اجباری | پیش‌فرض | توضیح |
|---|---|---|---|
| `SERVER_URL` | بله | – | آدرس کامل endpoint چک لایسنس |
| `ACCESS_KEY` | بله | – | کلید دسترسی |
| `HEADER_KEY` | خیر | `X-Access-Key` | نام هدری که کلید داخلش فرستاده میشه |
| `CHECK_INTERVAL_HOURS` | خیر | `6` | هر چند ساعت یک بار از سرور چک بشه |
| `OFFLINE_GRACE_HOURS` | خیر | `24` | اگه سرور در دسترس نبود، تا این مدت به آخرین جواب معتبر اعتماد کن |
| `TIMEOUT` | خیر | `10` | تایم‌اوت درخواست (ثانیه) |

تنظیمات از متغیرهای محیطی (یا `settings.py` جنگو) خونده میشن.
می‌تونید پیشوند `LICENCORE_` هم بذارید (مثلاً `LICENCORE_SERVER_URL`) تا با متغیرهای دیگه تداخل نکنه.

```bash
export SERVER_URL="https://licence.example.com/api/check"
export HEADER_KEY="X-Access-Key"
export ACCESS_KEY="your-key"
```

## استفاده

```python
import licencore

if licencore.is_valid():
    print("لایسنس معتبره")

status = licencore.status()
print(status.status, status.remaining_seconds, status.expires_at)

licencore.require()   # اگه معتبر نباشه licencore.LicenceInvalid پرتاب میشه
```

یا تنظیمات رو مستقیم تو کد بدید:

```python
from licencore import LicenceClient

client = LicenceClient(
    server_url="https://licence.example.com/api/check",
    access_key="your-key",
    check_interval_hours=12,
)
client.require()
```

### چک کردن چطور کار می‌کنه؟

نیازی به scheduler نیست. SDK جواب رو کش می‌کنه و فقط وقتی کش از
`CHECK_INTERVAL_HOURS` قدیمی‌تر باشه به سرور درخواست می‌زنه
(پیش‌فرض: هر ۶ ساعت، یعنی حدود ۴ بار در روز).
`remaining_seconds` بین دو چک به‌صورت محلی کم میشه.
اگه لایسنس نامعتبر باشه یا سرور در دسترس نباشه، هر ۵ دقیقه دوباره تلاش می‌کنه
تا تمدید لایسنس سریع شناسایی بشه. برای چک فوری از `licencore.status(force=True)` استفاده کنید.

## جنگو (Django)

```python
# settings.py
MIDDLEWARE = [
    # ...
    "licencore.django_support.LicenceMiddleware",
]

LICENCORE_SERVER_URL = "https://licence.example.com/api/check"
LICENCORE_ACCESS_KEY = "your-key"
LICENCORE_HEADER_KEY = "X-Access-Key"          # اختیاری
LICENCORE_CHECK_INTERVAL_HOURS = 6             # اختیاری
LICENCORE_EXEMPT_PATHS = ["/health/"]          # اختیاری، مسیرهایی که چک نمیشن
```

اگه لایسنس نامعتبر باشه، همه درخواست‌ها جواب `403` (JSON) می‌گیرن.
وضعیت لایسنس تو view ها از `request.licence` در دسترسه.

برای محافظت از چند view خاص:

```python
from licencore.django_support import licence_required

@licence_required
def my_view(request):
    ...
```

## فیلدهای وضعیت

`valid`، `status`، `starts_at`، `expires_at`، `remaining_seconds`،
`starts_in_seconds`، `project_id`، `server_time` و همچنین `offline`
(یعنی چون سرور در دسترس نبود از کش جواب داده شده) و `error`.

## توسعه‌دهنده

ساخته‌شده توسط **CyberHuginn** برای شرکت **فرداد نوآور** — [fardadnoavar.ir](https://fardadnoavar.ir)

## License

MIT
