feat: New response codes

Author: RAZKOM

AGENTS.md

@@ -11,7 +11,7 @@ AuthForge is a license key validation service. Your app sends a license key + ha
 
 - **1 `login()` or `validate_license()` = 1 credit** (one `/auth/validate` debit each).
 - **10 heartbeats = 1 credit** (billed on every 10th successful heartbeat per license).
-- Any `heartbeat_interval` is safe — from `1` (server apps) to `900` (15 min, desktop apps). Revocations always take effect on the **next** heartbeat regardless of interval.
+- Keep `heartbeat_interval` at `>= 10` seconds (`900` / 15 min is the typical desktop default). `/auth/heartbeat` is limited to 6 requests/minute per license key, and revocations still take effect on the **next** heartbeat.
 
 ## Installation
 
@@ -61,7 +61,7 @@ if __name__ == "__main__":
 | `app_id` | `str` | yes | — | Application ID |
 | `app_secret` | `str` | yes | — | Application secret |
 | `heartbeat_mode` | `str` | yes | — | `"SERVER"` or `"LOCAL"` (case-insensitive) |
-| `heartbeat_interval` | `int` | no | `900` | Seconds between heartbeats (any value ≥ 1) |
+| `heartbeat_interval` | `int` | no | `900` | Seconds between heartbeats (minimum `10`) |
 | `api_base_url` | `str` | no | `https://auth.authforge.cc` | API base URL |
 | `on_failure` | `Callable[[str, Optional[Exception]], None] \| None` | no | `None` | Called on login/heartbeat/network failure; if omitted, process exits via `os._exit(1)` (not used by `validate_license`) |
 | `request_timeout` | `int` | no | `15` | HTTP timeout (seconds) |
@@ -87,7 +87,7 @@ For Telegram/Discord bot flows, prefer immutable IDs (`tg:<user_id>`, `discord:<
 invalid_app, invalid_key, expired, revoked, hwid_mismatch, no_credits, blocked, rate_limited, replay_detected, session_expired, app_disabled, bad_request
 
 Notes:
-- `rate_limited` and `replay_detected` can only be returned from `/auth/validate`. Heartbeats are not IP rate-limited and do not enforce nonce replay.
+- `replay_detected` is validate-only. `rate_limited` can be returned by `/auth/validate` and `/auth/heartbeat` (heartbeat is license-limited at 6/min and has no app-layer IP limit).
 
 ## Common patterns
 

README.md

@@ -46,7 +46,7 @@ else:
 | `app_secret` | str | required | Your application secret from the AuthForge dashboard |
 | `public_key` | str | required | App Ed25519 public key (base64) from dashboard |
 | `heartbeat_mode` | str | required | `"SERVER"` or `"LOCAL"` (see below) |
-| `heartbeat_interval` | int | `900` | Seconds between heartbeat checks (any value ≥ 1; default 15 min) |
+| `heartbeat_interval` | int | `900` | Seconds between heartbeat checks (minimum `10`; default 15 min) |
 | `api_base_url` | str | `https://auth.authforge.cc` | API endpoint |
 | `on_failure` | callable | `None` | Callback `(reason: str, exc: Exception | None)` on auth failure |
 | `request_timeout` | int | `15` | HTTP request timeout in seconds |
@@ -70,7 +70,7 @@ client = AuthForgeClient(
 - **1 `login()` or `validate_license()` call = 1 credit** (one `/auth/validate` debit each).
 - **10 heartbeats on the same license = 1 credit** (billed every 10th successful heartbeat).
 
-A desktop app running 6h/day at a 15-minute interval burns ~3–4 credits/day. A server app running 24/7 at a 1-minute interval burns ~145 credits/day — pick the interval based on how fast you need revocations to propagate (they always land on the **next** heartbeat).
+A desktop app running 6h/day at a 15-minute interval burns ~3–4 credits/day. The server enforces `/auth/heartbeat` at 6 requests/minute per license key, so keep intervals at 10 seconds or higher and pick the interval based on how fast you need revocations to propagate (they always land on the **next** heartbeat).
 
 ## Methods
 
@@ -98,7 +98,7 @@ If authentication fails (login rejected, heartbeat fails, signature mismatch, et
 **`validate_license()`** does not trigger `on_failure` or `os._exit` — check `result["valid"]` and `result["code"]`.
 
 Recognized server errors:
-`invalid_app`, `invalid_key`, `expired`, `revoked`, `hwid_mismatch`, `no_credits`, `blocked`, `rate_limited`, `replay_detected`, `app_disabled`, `session_expired`, `revoke_requires_session`, `bad_request`
+`invalid_app`, `invalid_key`, `expired`, `revoked`, `hwid_mismatch`, `no_credits`, `blocked`, `rate_limited`, `replay_detected`, `app_disabled`, `session_expired`, `revoke_requires_session`, `bad_request`, `malformed_request`, `system_error`
 
 Request retries are automatic inside the internal HTTP layer:
 - `rate_limited`: retry after 2s, then 5s (max 3 attempts total)

authforge.py

@@ -63,6 +63,7 @@ class ValidateLicenseFailure(TypedDict):
     "session_expired",
     "revoke_requires_session",
     "bad_request",
+    "malformed_request",
     "system_error",
 }
 
@@ -93,8 +94,8 @@ def __init__(
         mode = (heartbeat_mode or "").upper()
         if mode not in {"LOCAL", "SERVER"}:
             raise ValueError("heartbeat_mode must be LOCAL or SERVER")
-        if heartbeat_interval <= 0:
-            raise ValueError("heartbeat_interval must be > 0")
+        if heartbeat_interval < 10:
+            raise ValueError("heartbeat_interval must be >= 10")
 
         self.app_id = app_id
         self.app_secret = app_secret

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "authforge-sdk"
-version = "1.0.7"
+version = "1.0.8"
 description = "Official Python SDK for AuthForge — credit-based license key authentication with Ed25519-verified responses."
 readme = "README.md"
 requires-python = ">=3.9"