Metadata-Version: 2.4
Name: nexus-vylth
Version: 1.0.1
Summary: Nexus SDK for Python — auth verification and mail API for VYLTH services
Author-email: VYLTH <nexus@vylth.com>
License: MIT
Project-URL: Homepage, https://github.com/VYLTH/nexus
Keywords: nexus,vylth,sso,mail,auth,jwt
Classifier: Development Status :: 5 - Production/Stable
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 :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.28.0
Provides-Extra: auth
Requires-Dist: PyJWT[crypto]>=2.8.0; extra == "auth"
Provides-Extra: all
Requires-Dist: PyJWT[crypto]>=2.8.0; extra == "all"

# nexus-vylth

Nexus SDK for Python — auth verification and mail API for VYLTH services.

## Install

```bash
# Mail only
pip install nexus-vylth

# Mail + Auth (JWT verification)
pip install nexus-vylth[auth]

# Everything
pip install nexus-vylth[all]
```

## Mail API

Send emails via your Nexus Mail API key (`nm_...`):

```python
from nexus_vylth import NexusMail

mail = NexusMail("nm_your_key_here")

# Single send
result = mail.send(
    to="user@example.com",
    subject="Hello",
    body_text="Hi there!",
)
print(result.from_address)  # you@vylth.com

# Batch send
results = mail.send_batch(
    recipients=["alice@example.com", "bob@example.com"],
    subject="Newsletter",
    body_html="<h1>Monthly Update</h1><p>Here's what happened...</p>",
)
```

## Auth (JWT Verification)

Verify Nexus access tokens using JWKS (auto-fetched and cached):

```python
from nexus_vylth import NexusAuth

auth = NexusAuth()

claims = auth.verify(token)
print(claims.email)         # user@vylth.com
print(claims.global_role)   # executor
print(claims.has_role("commander"))  # True
```

### FastAPI

```python
from fastapi import FastAPI, Depends
from nexus_vylth import NexusAuth

app = FastAPI()
auth = NexusAuth()

@app.get("/profile")
async def profile(claims=Depends(auth.fastapi_dependency())):
    return {"email": claims.email, "role": claims.global_role}

@app.get("/admin")
async def admin(claims=Depends(auth.fastapi_dependency("commander"))):
    return {"admin": claims.username}
```

### Flask

```python
from flask import Flask, g, jsonify
from nexus_vylth import NexusAuth

app = Flask(__name__)
auth = NexusAuth()

@app.route("/profile")
@auth.flask_decorator()
def profile():
    return jsonify({"email": g.nexus_claims.email})

@app.route("/admin")
@auth.flask_decorator("commander")
def admin():
    return jsonify({"admin": g.nexus_claims.username})
```

## Claims Fields

| Field | Type | Description |
|-------|------|-------------|
| `sub` | str | Account ID |
| `email` | str | Primary email |
| `username` | str | Username |
| `avatar` | str | Avatar URL |
| `global_role` | str | Global role (citizen/pioneer/navigator/commander/executor) |
| `email_verified` | bool | Whether email is verified |
| `affiliate_code` | str | Referral code |
| `app_roles` | dict | Per-app role overrides |
| `two_factor_verified` | bool | Whether 2FA was verified this session |
