sub2api 0.1.0__tar.gz

sub2api-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+*.har
+*.py[cod]
+*.egg-info/
+.coverage
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.venv/
+build/
+dist/
+__pycache__/

sub2api-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Eight Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sub2api-0.1.0/PKG-INFO

@@ -0,0 +1,249 @@
+Metadata-Version: 2.5
+Name: sub2api
+Version: 0.1.0
+Summary: Python client for the user-facing API of Sub2API instances
+Author: Eight Labs
+License: MIT License
+        
+        Copyright (c) 2026 Eight Labs
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: ai-gateway,api,sdk,sub2api
+Classifier: Development Status :: 3 - Alpha
+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: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: curl-cffi<1,>=0.10
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: httpx<1,>=0.27; extra == 'dev'
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pytest-cov>=5; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.7; extra == 'dev'
+Requires-Dist: twine>=5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# sub2api
+
+`sub2api` is a Python client for the shared user-facing panel API exposed by Sub2API instances. One client object represents one user's in-memory dashboard session. Requests use `curl_cffi` with Chrome browser impersonation by default.
+
+The library targets operations present on standard Sub2API deployments: account balance, platform quotas, usage history and statistics, API keys, groups, subscriptions, announcements, and redemption.
+
+## Install
+
+```bash
+pip install sub2api
+```
+
+Python 3.10 or newer is required.
+
+## Authenticate with an existing session
+
+The dashboard's access token is different from an `sk-...` gateway API key. Browser deployments normally store the panel tokens under `auth_token` and `refresh_token` in local storage.
+
+```python
+import os
+
+from sub2api import Sub2API
+
+client = Sub2API(
+    "https://sub2api.example.com",
+    access_token=os.environ["SUB2API_ACCESS_TOKEN"],
+    refresh_token=os.environ.get("SUB2API_REFRESH_TOKEN"),
+)
+
+print(client.me().email)
+print(client.balance().balance)
+```
+
+Pass either the instance origin or its full `/api/v1` URL. Tokens are retained only in memory. If a refresh token is supplied, the client rotates the token pair after an authenticated `401`. Supplying `expires_at` as a Unix timestamp also enables proactive refresh.
+
+The default browser fingerprint is Chrome. Choose another `curl_cffi` fingerprint or configure proxies by supplying your own `curl_cffi.requests.Session`:
+
+```python
+from curl_cffi import requests
+
+session = requests.Session(impersonate="safari")
+client = Sub2API("https://sub2api.example.com", session=session)
+```
+
+## Log in with email and password
+
+```python
+from sub2api import Sub2API
+
+with Sub2API("https://sub2api.example.com") as client:
+    user = client.login("person@example.com", "password")
+    print(user.username)
+    print(client.is_authenticated)
+```
+
+An instance with CAPTCHA enabled requires the corresponding proof:
+
+```python
+client.login(
+    "person@example.com",
+    "password",
+    turnstile_token="captcha-proof",
+)
+```
+
+For a TOTP-enabled account, `login()` raises `TwoFactorRequired` and retains the temporary challenge in memory:
+
+```python
+from sub2api import Sub2API, TwoFactorRequired
+
+client = Sub2API("https://sub2api.example.com")
+
+try:
+    client.login("person@example.com", "password")
+except TwoFactorRequired:
+    client.complete_2fa("123456")
+```
+
+## Common operations
+
+Resources are callable for their common list operation and also expose explicit methods.
+
+```python
+balance = client.balance()
+quotas = client.account.platform_quotas()
+
+groups = client.groups()
+group_rates = client.groups.rates()
+
+first_page = client.keys(page_size=50, status="active")
+for api_key in first_page:
+    print(api_key.id, api_key.name, api_key.group.name)
+
+all_keys = client.keys.all()
+resolved = client.keys.with_group_multipliers()
+for item in resolved:
+    print(
+        item.api_key.key,
+        item.group_id,
+        item.base_multiplier,
+        item.custom_multiplier,
+        item.effective_multiplier,
+    )
+
+multiplier_by_key = client.keys.multiplier_map(key_by="key")
+multiplier_by_id = client.keys.multiplier_map(key_by="id")
+
+created = client.keys.create("automation", group_id=groups[0].id)
+client.keys.update(created.id, name="nightly automation")
+client.keys.set_status(created.id, active=False)
+client.keys.delete(created.id)
+```
+
+`all()` follows pagination until every key has been fetched. `with_group_multipliers()` joins each key to its group and reports the base, user-specific, and effective rate; the user-specific rate from `/groups/rates` takes precedence. `multiplier_map()` returns the effective rate keyed by the API key value, key ID, or name. Name collisions raise an error instead of silently overwriting an entry.
+
+API key values are available through `api_key.key`, but object representations redact fields that commonly contain credentials.
+
+## Usage history
+
+`history` and `usage` refer to the same resource.
+
+```python
+from datetime import date, timedelta
+
+end = date.today()
+start = end - timedelta(days=7)
+
+page = client.history(
+    start_date=start,
+    end_date=end,
+    page_size=100,
+    sort_by="created_at",
+    sort_order="desc",
+)
+
+for record in page:
+    print(record.created_at, record.model, record.actual_cost)
+
+for record in client.history.iter(page_size=100):
+    process(record)
+
+stats = client.usage.stats(start_date=start, end_date=end)
+dashboard = client.usage.dashboard()
+trend = client.usage.trend(start_date=start, end_date=end, granularity="day")
+models = client.usage.models(start_date=start, end_date=end)
+snapshot = client.usage.snapshot(start_date=start, end_date=end)
+```
+
+## Other shared resources
+
+```python
+active_subscriptions = client.subscriptions(active=True)
+announcements = client.announcements()
+client.announcements.mark_read(announcements[0].id)
+
+result = client.redeem("REDEMPTION-CODE")
+redemption_history = client.redeem.history()
+```
+
+## Fork-specific endpoints
+
+`request()` provides the same authentication, envelope handling, timezone parameter, refresh behavior, and error mapping for relative endpoints that are not part of the stable resource API.
+
+```python
+result = client.request("GET", "some-fork-specific-endpoint")
+```
+
+Absolute URLs and parent-path traversal are rejected so a session token cannot be redirected outside the configured API root.
+
+## Errors
+
+HTTP and Sub2API envelope failures use typed exceptions:
+
+```python
+from sub2api import AuthenticationError, RateLimitError, Sub2APIError
+
+try:
+    client.keys.create("automation")
+except RateLimitError as error:
+    print(error.retry_after)
+except AuthenticationError:
+    client.login("person@example.com", "password")
+except Sub2APIError as error:
+    print(error)
+```
+
+Remote plaintext HTTP is rejected by default because it exposes login credentials and tokens. Localhost HTTP is allowed for development; other HTTP instances require `allow_insecure=True`.
+
+## Development
+
+```bash
+python -m pip install -e '.[dev]'
+pytest
+ruff check .
+mypy
+python -m build
+twine check dist/*
+```
+
+HAR captures are ignored by Git because they can contain live session credentials.

sub2api-0.1.0/README.md

@@ -0,0 +1,200 @@
+# sub2api
+
+`sub2api` is a Python client for the shared user-facing panel API exposed by Sub2API instances. One client object represents one user's in-memory dashboard session. Requests use `curl_cffi` with Chrome browser impersonation by default.
+
+The library targets operations present on standard Sub2API deployments: account balance, platform quotas, usage history and statistics, API keys, groups, subscriptions, announcements, and redemption.
+
+## Install
+
+```bash
+pip install sub2api
+```
+
+Python 3.10 or newer is required.
+
+## Authenticate with an existing session
+
+The dashboard's access token is different from an `sk-...` gateway API key. Browser deployments normally store the panel tokens under `auth_token` and `refresh_token` in local storage.
+
+```python
+import os
+
+from sub2api import Sub2API
+
+client = Sub2API(
+    "https://sub2api.example.com",
+    access_token=os.environ["SUB2API_ACCESS_TOKEN"],
+    refresh_token=os.environ.get("SUB2API_REFRESH_TOKEN"),
+)
+
+print(client.me().email)
+print(client.balance().balance)
+```
+
+Pass either the instance origin or its full `/api/v1` URL. Tokens are retained only in memory. If a refresh token is supplied, the client rotates the token pair after an authenticated `401`. Supplying `expires_at` as a Unix timestamp also enables proactive refresh.
+
+The default browser fingerprint is Chrome. Choose another `curl_cffi` fingerprint or configure proxies by supplying your own `curl_cffi.requests.Session`:
+
+```python
+from curl_cffi import requests
+
+session = requests.Session(impersonate="safari")
+client = Sub2API("https://sub2api.example.com", session=session)
+```
+
+## Log in with email and password
+
+```python
+from sub2api import Sub2API
+
+with Sub2API("https://sub2api.example.com") as client:
+    user = client.login("person@example.com", "password")
+    print(user.username)
+    print(client.is_authenticated)
+```
+
+An instance with CAPTCHA enabled requires the corresponding proof:
+
+```python
+client.login(
+    "person@example.com",
+    "password",
+    turnstile_token="captcha-proof",
+)
+```
+
+For a TOTP-enabled account, `login()` raises `TwoFactorRequired` and retains the temporary challenge in memory:
+
+```python
+from sub2api import Sub2API, TwoFactorRequired
+
+client = Sub2API("https://sub2api.example.com")
+
+try:
+    client.login("person@example.com", "password")
+except TwoFactorRequired:
+    client.complete_2fa("123456")
+```
+
+## Common operations
+
+Resources are callable for their common list operation and also expose explicit methods.
+
+```python
+balance = client.balance()
+quotas = client.account.platform_quotas()
+
+groups = client.groups()
+group_rates = client.groups.rates()
+
+first_page = client.keys(page_size=50, status="active")
+for api_key in first_page:
+    print(api_key.id, api_key.name, api_key.group.name)
+
+all_keys = client.keys.all()
+resolved = client.keys.with_group_multipliers()
+for item in resolved:
+    print(
+        item.api_key.key,
+        item.group_id,
+        item.base_multiplier,
+        item.custom_multiplier,
+        item.effective_multiplier,
+    )
+
+multiplier_by_key = client.keys.multiplier_map(key_by="key")
+multiplier_by_id = client.keys.multiplier_map(key_by="id")
+
+created = client.keys.create("automation", group_id=groups[0].id)
+client.keys.update(created.id, name="nightly automation")
+client.keys.set_status(created.id, active=False)
+client.keys.delete(created.id)
+```
+
+`all()` follows pagination until every key has been fetched. `with_group_multipliers()` joins each key to its group and reports the base, user-specific, and effective rate; the user-specific rate from `/groups/rates` takes precedence. `multiplier_map()` returns the effective rate keyed by the API key value, key ID, or name. Name collisions raise an error instead of silently overwriting an entry.
+
+API key values are available through `api_key.key`, but object representations redact fields that commonly contain credentials.
+
+## Usage history
+
+`history` and `usage` refer to the same resource.
+
+```python
+from datetime import date, timedelta
+
+end = date.today()
+start = end - timedelta(days=7)
+
+page = client.history(
+    start_date=start,
+    end_date=end,
+    page_size=100,
+    sort_by="created_at",
+    sort_order="desc",
+)
+
+for record in page:
+    print(record.created_at, record.model, record.actual_cost)
+
+for record in client.history.iter(page_size=100):
+    process(record)
+
+stats = client.usage.stats(start_date=start, end_date=end)
+dashboard = client.usage.dashboard()
+trend = client.usage.trend(start_date=start, end_date=end, granularity="day")
+models = client.usage.models(start_date=start, end_date=end)
+snapshot = client.usage.snapshot(start_date=start, end_date=end)
+```
+
+## Other shared resources
+
+```python
+active_subscriptions = client.subscriptions(active=True)
+announcements = client.announcements()
+client.announcements.mark_read(announcements[0].id)
+
+result = client.redeem("REDEMPTION-CODE")
+redemption_history = client.redeem.history()
+```
+
+## Fork-specific endpoints
+
+`request()` provides the same authentication, envelope handling, timezone parameter, refresh behavior, and error mapping for relative endpoints that are not part of the stable resource API.
+
+```python
+result = client.request("GET", "some-fork-specific-endpoint")
+```
+
+Absolute URLs and parent-path traversal are rejected so a session token cannot be redirected outside the configured API root.
+
+## Errors
+
+HTTP and Sub2API envelope failures use typed exceptions:
+
+```python
+from sub2api import AuthenticationError, RateLimitError, Sub2APIError
+
+try:
+    client.keys.create("automation")
+except RateLimitError as error:
+    print(error.retry_after)
+except AuthenticationError:
+    client.login("person@example.com", "password")
+except Sub2APIError as error:
+    print(error)
+```
+
+Remote plaintext HTTP is rejected by default because it exposes login credentials and tokens. Localhost HTTP is allowed for development; other HTTP instances require `allow_insecure=True`.
+
+## Development
+
+```bash
+python -m pip install -e '.[dev]'
+pytest
+ruff check .
+mypy
+python -m build
+twine check dist/*
+```
+
+HAR captures are ignored by Git because they can contain live session credentials.

sub2api-0.1.0/pyproject.toml

@@ -0,0 +1,60 @@
+[build-system]
+requires = ["hatchling>=1.26"]
+build-backend = "hatchling.build"
+
+[project]
+name = "sub2api"
+version = "0.1.0"
+description = "Python client for the user-facing API of Sub2API instances"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { file = "LICENSE" }
+authors = [
+  { name = "Eight Labs" }
+]
+keywords = ["sub2api", "api", "sdk", "ai-gateway"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "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",
+  "Programming Language :: Python :: 3.13",
+  "Typing :: Typed"
+]
+dependencies = [
+  "curl-cffi>=0.10,<1"
+]
+
+[project.optional-dependencies]
+dev = [
+  "build>=1.2",
+  "httpx>=0.27,<1",
+  "mypy>=1.11",
+  "pytest>=8",
+  "pytest-cov>=5",
+  "ruff>=0.7",
+  "twine>=5"
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/sub2api"]
+
+[tool.pytest.ini_options]
+addopts = "-ra"
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM", "RUF"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+packages = ["sub2api"]
+mypy_path = "src"

sub2api-0.1.0/src/sub2api/__init__.py

@@ -0,0 +1,61 @@
+from ._client import Sub2API
+from ._exceptions import (
+    APIError,
+    AuthenticationError,
+    ConfigurationError,
+    ConflictError,
+    NotFoundError,
+    PermissionDeniedError,
+    ProtocolError,
+    RateLimitError,
+    Sub2APIError,
+    TransportError,
+    TwoFactorRequired,
+    ValidationError,
+)
+from ._models import (
+    Announcement,
+    APIKey,
+    Balance,
+    Group,
+    KeyGroupMultiplier,
+    Page,
+    PlatformQuota,
+    Redemption,
+    Resource,
+    SessionTokens,
+    Subscription,
+    UsageRecord,
+    User,
+)
+
+__all__ = [
+    "APIError",
+    "APIKey",
+    "Announcement",
+    "AuthenticationError",
+    "Balance",
+    "ConfigurationError",
+    "ConflictError",
+    "Group",
+    "KeyGroupMultiplier",
+    "NotFoundError",
+    "Page",
+    "PermissionDeniedError",
+    "PlatformQuota",
+    "ProtocolError",
+    "RateLimitError",
+    "Redemption",
+    "Resource",
+    "SessionTokens",
+    "Sub2API",
+    "Sub2APIError",
+    "Subscription",
+    "TransportError",
+    "TwoFactorRequired",
+    "UsageRecord",
+    "User",
+    "ValidationError",
+]
+
+__version__ = "0.1.0"