newapi-python 0.2.0__tar.gz → 0.3.0__tar.gz

newapi_python-0.3.0/.mimosa/finding-ledger/v1/events/batch-posttooluse-48aef1dee53250877e9903ca7c2b5602.json

@@ -0,0 +1,23 @@
+{
+  "schemaVersion": "mimosa-finding-ledger-batch/v1",
+  "batchId": "posttooluse-48aef1dee53250877e9903ca7c2b5602",
+  "runId": null,
+  "runStatus": "completed",
+  "coverage": {
+    "status": "complete",
+    "reasons": []
+  },
+  "source": {
+    "component": "zcode-hook",
+    "operationId": "PostToolUse"
+  },
+  "revision": null,
+  "diffHash": null,
+  "rulesVersion": null,
+  "sessionHash": "b601df6c7ab8c95836c9aa408671dade9f8500578f3b99ff004a48d719d630b4",
+  "reportRef": null,
+  "events": [],
+  "observedFindingIds": [],
+  "verifiedFiles": [],
+  "recordedAt": "2026-09-02T01:47:00.021Z"
+}

newapi_python-0.3.0/.mimosa/finding-ledger/v1/events/batch-pretooluse-6268e66558b9f7a250aa50afc99ccc21.json

@@ -0,0 +1,23 @@
+{
+  "schemaVersion": "mimosa-finding-ledger-batch/v1",
+  "batchId": "pretooluse-6268e66558b9f7a250aa50afc99ccc21",
+  "runId": null,
+  "runStatus": "completed",
+  "coverage": {
+    "status": "complete",
+    "reasons": []
+  },
+  "source": {
+    "component": "zcode-hook",
+    "operationId": "PreToolUse"
+  },
+  "revision": null,
+  "diffHash": null,
+  "rulesVersion": null,
+  "sessionHash": "b601df6c7ab8c95836c9aa408671dade9f8500578f3b99ff004a48d719d630b4",
+  "reportRef": null,
+  "events": [],
+  "observedFindingIds": [],
+  "verifiedFiles": [],
+  "recordedAt": "2026-09-02T01:46:45.535Z"
+}

newapi_python-0.3.0/.mimosa/hook-state/sess_1433cec3-1da2-46c1-88de-192e7415d559.json

@@ -0,0 +1 @@
+{"touched":["/Users/Administrator/eightlabs/newapi/src/newapi/__init__.py","/Users/Administrator/eightlabs/newapi/src/newapi/_client.py"],"bashMutation":true,"reportedFindings":["mimosa-66b5d60954ca90ad7e673501"],"findingEvents":[{"finding_id":"mimosa-66b5d60954ca90ad7e673501","file":"../../../../tmp/live_test_newapi.py","line":24,"rule_id":"security","severity":"high","category":"硬编码凭据","evidence":{"type":"static_observation","line_hash":"655080fc4deb5d7ba132e4dfa5eeff0e63181ed39fbd3b9c4a74fd5f35f100c8","source":"semgrep"},"status":"blocked","decision":"deny","at":"2026-09-02T01:46:45.217Z"},{"finding_id":"mimosa-66b5d60954ca90ad7e673501","file":"../../../../tmp/live_test_newapi.py","line":24,"rule_id":"security","severity":"high","category":"硬编码凭据","evidence":{"type":"static_observation","line_hash":"655080fc4deb5d7ba132e4dfa5eeff0e63181ed39fbd3b9c4a74fd5f35f100c8","source":"semgrep","candidate_before_line_hash":"655080fc4deb5d7ba132e4dfa5eeff0e63181ed39fbd3b9c4a74fd5f35f100c8","post_change_line_hash_at_previous_location":"67d27e371a21402ee7ba4fe1136e7650c84740034f83bec4ec36d2baf6964c0f","verification":{"method":"mimosa-posttool-static-rescan","finding_absent":true,"runtime_oracle":false}},"status":"fixed_candidate","decision":"repair_observed","at":"2026-09-02T01:46:59.695Z"},{"finding_id":"mimosa-66b5d60954ca90ad7e673501","file":"../../../../tmp/live_test_newapi.py","line":24,"rule_id":"security","severity":"high","category":"硬编码凭据","evidence":{"type":"static_observation","line_hash":"655080fc4deb5d7ba132e4dfa5eeff0e63181ed39fbd3b9c4a74fd5f35f100c8","source":"semgrep","candidate_before_line_hash":"655080fc4deb5d7ba132e4dfa5eeff0e63181ed39fbd3b9c4a74fd5f35f100c8","post_change_line_hash_at_previous_location":"67d27e371a21402ee7ba4fe1136e7650c84740034f83bec4ec36d2baf6964c0f","verification":{"method":"mimosa-posttool-static-rescan","finding_absent":true,"runtime_oracle":false}},"status":"static_verified","decision":"static_rescan_passed","at":"2026-09-02T01:46:59.695Z"}],"baseline":{"storageId":"mtjfq1ha-24876-f1aebcd4dc","createdAt":"2026-09-02T01:46:04.414Z","files":{"src/newapi/__init__.py":{"existed":true,"snapshot":"2c0a3ea4b52b71cebbbb4c27ee4939eeecbb634105d6a4ad0b51984b9dbfa04b.source"},"src/newapi/_client.py":{"existed":true,"snapshot":"1252fc55de5f372ed4dcbb82a75b61002c7dfd9076f095c21e54449336bf6ba8.source"}},"complete":false,"candidateLimit":5000,"discoveredFiles":0,"capturedFiles":2,"truncated":false,"omittedAtLeast":0,"firstOmitted":"","errors":[{"stage":"baseline-capture","target":".","reason":"global task baseline was unavailable; captured only the touched file"},{"stage":"baseline-snapshot","target":"../../../../tmp/live_test_newapi.py","reason":"file is outside project"},{"stage":"baseline-snapshot","target":"../../../../tmp/live_test_newapi.py","reason":"file is outside project"},{"stage":"baseline-snapshot","target":"../../../../tmp/live_test_newapi.py","reason":"file is outside project"},{"stage":"baseline-snapshot","target":"../../../../tmp/live_test_newapi.py","reason":"file is outside project"}]},"stateErrors":[],"omittedReportedFindings":0,"omittedFindingEvents":0,"processing":null,"updatedAt":"2026-09-02T01:47:47.717Z"}

newapi_python-0.2.0/src/newapi/_client.py → newapi_python-0.3.0/.mimosa/hook-state/sess_1433cec3-1da2-46c1-88de-192e7415d559.mtjfq1ha-24876-f1aebcd4dc.baseline/1252fc55de5f372ed4dcbb82a75b61002c7dfd9076f095c21e54449336bf6ba8.source

@@ -218,6 +218,12 @@ class NewAPI:
     ) -> int | None:
         if access_token and session_token:
             raise ConfigurationError("pass either access_token or session_token, not both")
+        if access_token and user_id is None:
+            raise ConfigurationError(
+                "user_id is required when authenticating with an access_token; "
+                "new-api instances reject such requests with 401 "
+                "'Unauthorized, New-Api-User header not provided'"
+            )
         if not session_token or user_id is not None:
             return user_id
         try:
@@ -342,6 +348,8 @@ class NewAPI:
             return
         refresh_token = self._tokens.refresh_token
         headers: dict[str, str] = {"Origin": self._origin()}
+        if self._tokens.user_id is not None:
+            headers[_USER_ID_HEADER] = str(self._tokens.user_id)
         if self._tokens.access_token:
             headers["Authorization"] = f"{self._tokens.token_type} {self._tokens.access_token}"
         try:
@@ -510,14 +518,15 @@ class NewAPI:
             "Accept-Language": self.language,
             "User-Agent": "newapi-python/0.2.0",
         }
-        if authenticated and self._tokens.session_token:
-            request_headers["Cookie"] = f"{self._session_cookie}={self._tokens.session_token}"
+        if authenticated:
             if self._tokens.user_id is not None:
                 request_headers[_USER_ID_HEADER] = str(self._tokens.user_id)
-        elif authenticated and self._tokens.access_token:
-            request_headers["Authorization"] = (
-                f"{self._tokens.token_type} {self._tokens.access_token}"
-            )
+            if self._tokens.session_token:
+                request_headers["Cookie"] = f"{self._session_cookie}={self._tokens.session_token}"
+            elif self._tokens.access_token:
+                request_headers["Authorization"] = (
+                    f"{self._tokens.token_type} {self._tokens.access_token}"
+                )
         if refresh_cookie and not self._session_has_refresh_cookie():
             request_headers["Cookie"] = f"{_REFRESH_COOKIE}={refresh_cookie}"
         if headers:
@@ -677,12 +686,19 @@ class NewAPI:
         if isinstance(session, Mapping):
             raw_session_id = session.get("sid")
             session_id = raw_session_id if isinstance(raw_session_id, str) else None
+        user_id = self._tokens.user_id
+        user_data = auth.get("user")
+        if isinstance(user_data, Mapping):
+            raw_user_id = user_data.get("id")
+            if isinstance(raw_user_id, int) and not isinstance(raw_user_id, bool):
+                user_id = raw_user_id
         return SessionTokens(
             access_token=str(auth["access_token"]),
             refresh_token=refresh_token,
             expires_at=expires_at,
             token_type=str(token_type) if token_type else "Bearer",
             session_id=session_id,
+            user_id=user_id,
         )
 
     def _resolve_quota_per_unit(self) -> float:

newapi_python-0.3.0/.mimosa/hook-status/sess_1433cec3-1da2-46c1-88de-192e7415d559-b601df6c7a.json

@@ -0,0 +1,14 @@
+{
+  "schemaVersion": "mimosa-hook-status/v1",
+  "recordedAt": "2026-09-02T01:47:48.400Z",
+  "sessionId": "sess_1433cec3-1da2-46c1-88de-192e7415d559",
+  "event": "PostToolUse",
+  "toolName": "Edit",
+  "file": "/tmp/live_test_newapi.py",
+  "outcome": "inconclusive",
+  "coverage": "partial",
+  "findingCount": 0,
+  "durationMs": 4,
+  "hostState": "hook_complete",
+  "reportHint": ".mimosa/reports/"
+}

{newapi_python-0.2.0 → newapi_python-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: newapi-python
-Version: 0.2.0
+Version: 0.3.0
 Summary: Python client for the user-facing dashboard API of new-api instances
 Author: Eight Labs
 License-Expression: MIT
@@ -55,10 +55,13 @@ client = NewAPI(
     "https://newapi.example.com",
     access_token=os.environ["NEWAPI_ACCESS_TOKEN"],
     refresh_token=os.environ.get("NEWAPI_REFRESH_TOKEN"),
+    user_id=int(os.environ["NEWAPI_USER_ID"]),
 )
 ```
 
-Pass either the instance origin or its full `/api` URL. Tokens are retained only in memory. If a refresh token is supplied, the client sends it as the `new_api_refresh` cookie, rotates the pair after an authenticated `401`, and refreshes proactively when `expires_at` is known. Users can also generate a long-lived system access token from the dashboard and pass it as `access_token` alone; such tokens cannot refresh browser sessions.
+Pass either the instance origin or its full `/api` URL. Tokens are retained only in memory. If a refresh token is supplied, the client sends it as the `new_api_refresh` cookie, rotates the pair after an authenticated `401`, and refreshes proactively when `expires_at` is known.
+
+Users can also generate a long-lived system access token from the dashboard and pass it as `access_token`. Access-token authentication additionally requires `user_id`: new-api instances verify the numeric `New-Api-User` header on every authenticated request and reject requests without it with `401 Unauthorized, New-Api-User header not provided`. The client sends the header automatically from `user_id`, and `login()` and `refresh()` capture the id from the instance's responses. Such tokens cannot refresh browser sessions on their own.
 
 The default browser fingerprint is Chrome. Choose another `curl_cffi` fingerprint or configure proxies by supplying your own `curl_cffi.requests.Session`:
 

{newapi_python-0.2.0 → newapi_python-0.3.0}/README.md

@@ -25,10 +25,13 @@ client = NewAPI(
     "https://newapi.example.com",
     access_token=os.environ["NEWAPI_ACCESS_TOKEN"],
     refresh_token=os.environ.get("NEWAPI_REFRESH_TOKEN"),
+    user_id=int(os.environ["NEWAPI_USER_ID"]),
 )
 ```
 
-Pass either the instance origin or its full `/api` URL. Tokens are retained only in memory. If a refresh token is supplied, the client sends it as the `new_api_refresh` cookie, rotates the pair after an authenticated `401`, and refreshes proactively when `expires_at` is known. Users can also generate a long-lived system access token from the dashboard and pass it as `access_token` alone; such tokens cannot refresh browser sessions.
+Pass either the instance origin or its full `/api` URL. Tokens are retained only in memory. If a refresh token is supplied, the client sends it as the `new_api_refresh` cookie, rotates the pair after an authenticated `401`, and refreshes proactively when `expires_at` is known.
+
+Users can also generate a long-lived system access token from the dashboard and pass it as `access_token`. Access-token authentication additionally requires `user_id`: new-api instances verify the numeric `New-Api-User` header on every authenticated request and reject requests without it with `401 Unauthorized, New-Api-User header not provided`. The client sends the header automatically from `user_id`, and `login()` and `refresh()` capture the id from the instance's responses. Such tokens cannot refresh browser sessions on their own.
 
 The default browser fingerprint is Chrome. Choose another `curl_cffi` fingerprint or configure proxies by supplying your own `curl_cffi.requests.Session`:
 

{newapi_python-0.2.0 → newapi_python-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "newapi-python"
-version = "0.2.0"
+version = "0.3.0"
 description = "Python client for the user-facing dashboard API of new-api instances"
 readme = "README.md"
 requires-python = ">=3.10"

newapi_python-0.3.0/src/newapi/__init__.py

@@ -0,0 +1,75 @@
+from ._client import NewAPI
+from ._exceptions import (
+    APIError,
+    AuthenticationError,
+    ConfigurationError,
+    ConflictError,
+    NewAPIError,
+    NotFoundError,
+    PermissionDeniedError,
+    ProtocolError,
+    RateLimitError,
+    TransportError,
+    TwoFactorRequired,
+    ValidationError,
+)
+from ._models import (
+    Announcement,
+    APIKey,
+    Balance,
+    CheckinResult,
+    CheckinStatus,
+    Group,
+    Log,
+    LoginSession,
+    Page,
+    PaymentConfig,
+    PaymentLink,
+    Redemption,
+    Resource,
+    SessionTokens,
+    Subscription,
+    SubscriptionPlan,
+    Token,
+    TopUpOrder,
+    UsageRecord,
+    User,
+)
+
+__all__ = [
+    "APIError",
+    "APIKey",
+    "Announcement",
+    "AuthenticationError",
+    "Balance",
+    "CheckinResult",
+    "CheckinStatus",
+    "ConfigurationError",
+    "ConflictError",
+    "Group",
+    "Log",
+    "LoginSession",
+    "NewAPI",
+    "NewAPIError",
+    "NotFoundError",
+    "Page",
+    "PaymentConfig",
+    "PaymentLink",
+    "PermissionDeniedError",
+    "ProtocolError",
+    "RateLimitError",
+    "Redemption",
+    "Resource",
+    "SessionTokens",
+    "Subscription",
+    "SubscriptionPlan",
+    "Token",
+    "TopUpOrder",
+    "TransportError",
+    "TwoFactorRequired",
+    "UsageRecord",
+    "User",
+    "ValidationError",
+]
+
+__version__ = "0.3.0"

newapi_python-0.3.0/src/newapi/_client.py

@@ -0,0 +1,707 @@
+from __future__ import annotations
+
+import re
+import threading
+from collections.abc import Mapping
+from dataclasses import replace
+from typing import Any, cast
+from urllib.parse import unquote, urlsplit, urlunsplit
+
+from curl_cffi import requests as curl_requests
+
+from ._crypto import rsa_oaep_sha256_encrypt
+from ._exceptions import (
+    APIError,
+    AuthenticationError,
+    ConfigurationError,
+    ConflictError,
+    NotFoundError,
+    PermissionDeniedError,
+    ProtocolError,
+    RateLimitError,
+    TransportError,
+    TwoFactorRequired,
+    ValidationError,
+)
+from ._models import Balance, Resource, SessionTokens, User
+from ._resources import (
+    AccountResource,
+    DashboardResource,
+    GroupsResource,
+    LogsResource,
+    PaymentResource,
+    SubscriptionResource,
+    TokensResource,
+    TopUpResource,
+)
+from ._session_blob import decode_session_blob
+
+_ERROR_TYPES: dict[int, type[APIError]] = {
+    400: ValidationError,
+    401: AuthenticationError,
+    403: PermissionDeniedError,
+    404: NotFoundError,
+    409: ConflictError,
+    422: ValidationError,
+    429: RateLimitError,
+}
+_LOCAL_HOSTS = frozenset({"localhost", "127.0.0.1", "::1"})
+_REFRESH_COOKIE = "new_api_refresh"
+_REFRESH_COOKIE_PATTERN = re.compile(rf"(?:^|[;,\s]){_REFRESH_COOKIE}=([^;\s]+)")
+_DEFAULT_SESSION_COOKIE = "session"
+_USER_ID_HEADER = "New-Api-User"
+_DEFAULT_QUOTA_PER_UNIT = 500000.0
+
+
+def _api_base_url(value: str, allow_insecure: bool) -> str:
+    candidate = value.strip()
+    if not candidate:
+        raise ConfigurationError("base_url must not be empty")
+    if "://" not in candidate:
+        candidate = f"https://{candidate}"
+    parsed = urlsplit(candidate)
+    if parsed.scheme not in {"http", "https"} or not parsed.hostname:
+        raise ConfigurationError("base_url must be an HTTP or HTTPS instance URL")
+    if parsed.username or parsed.password:
+        raise ConfigurationError("base_url must not contain credentials")
+    if parsed.query or parsed.fragment:
+        raise ConfigurationError("base_url must not contain a query string or fragment")
+    local = parsed.hostname in _LOCAL_HOSTS or parsed.hostname.endswith(".localhost")
+    if parsed.scheme == "http" and not local and not allow_insecure:
+        raise ConfigurationError(
+            "remote HTTP would expose credentials; use HTTPS or set allow_insecure=True"
+        )
+    path = parsed.path.rstrip("/")
+    if not path.endswith("/api"):
+        path = f"{path}/api"
+    return urlunsplit((parsed.scheme, parsed.netloc, path, "", ""))
+
+
+def _request_path(value: str) -> str:
+    parsed = urlsplit(value)
+    if parsed.scheme or parsed.netloc or parsed.fragment:
+        raise ConfigurationError("request path must be relative to the configured instance")
+    if parsed.query:
+        raise ConfigurationError("request path must not contain a query string; use params instead")
+    path = unquote(parsed.path).lstrip("/")
+    if path == "api":
+        path = ""
+    elif path.startswith("api/"):
+        path = path[len("api/") :]
+    if any(segment in {"..", "."} for segment in path.split("/")):
+        raise ConfigurationError("request path must not contain parent traversal")
+    if not path:
+        raise ConfigurationError("request path must identify an endpoint")
+    return path
+
+
+def _query_value(value: Any) -> Any:
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    return value
+
+
+def _query(params: Mapping[str, Any] | None) -> dict[str, Any] | None:
+    if params is None:
+        return None
+    return {
+        str(key): _query_value(value)
+        for key, value in params.items()
+        if value is not None and value != ""
+    }
+
+
+def _success(response: Any) -> bool:
+    return 200 <= int(response.status_code) < 300
+
+
+def _retry_after(response: Any) -> float | None:
+    value = response.headers.get("Retry-After")
+    if value is None:
+        return None
+    try:
+        return max(0.0, float(value))
+    except ValueError:
+        return None
+
+
+def _set_cookie_values(response: Any) -> list[str]:
+    headers = response.headers
+    get_list = getattr(headers, "get_list", None)
+    if callable(get_list):
+        return [str(value) for value in get_list("set-cookie")]
+    raw = headers.get("set-cookie")
+    if raw is None:
+        return []
+    if isinstance(raw, str):
+        return [raw]
+    return [str(value) for value in raw]
+
+
+class NewAPI:
+    """An authenticated user session for one new-api instance."""
+
+    def __init__(
+        self,
+        base_url: str,
+        *,
+        access_token: str | None = None,
+        refresh_token: str | None = None,
+        expires_at: float | None = None,
+        session_id: str | None = None,
+        session_token: str | None = None,
+        user_id: int | None = None,
+        session_cookie: str = _DEFAULT_SESSION_COOKIE,
+        timeout: float | tuple[float, float] = 30.0,
+        language: str = "en",
+        allow_insecure: bool = False,
+        impersonate: str | None = "chrome",
+        session: Any | None = None,
+    ) -> None:
+        self.base_url = _api_base_url(base_url, allow_insecure)
+        self.language = language
+        self._session_cookie = session_cookie
+        self._session_cookie_pattern = re.compile(
+            rf"(?:^|[;,\s]){re.escape(session_cookie)}=([^;\s]+)"
+        )
+        resolved_user_id = self._resolve_session_user_id(access_token, session_token, user_id)
+        self._tokens = SessionTokens(
+            access_token=access_token,
+            refresh_token=refresh_token,
+            expires_at=expires_at,
+            session_id=session_id,
+            session_token=session_token,
+            user_id=resolved_user_id,
+        )
+        self._refresh_lock = threading.RLock()
+        self._pending_2fa_token: str | None = None
+        self.timeout = timeout
+        self.impersonate = impersonate
+        self._quota_per_unit: float | None = None
+        self._owns_http_client = session is None
+        if session is None:
+            if impersonate:
+                self._http: Any = cast(Any, curl_requests.Session)(impersonate=impersonate)
+            else:
+                self._http = cast(Any, curl_requests.Session)()
+        else:
+            self._http = session
+        self.account = AccountResource(self)
+        self.tokens = TokensResource(self)
+        self.keys = self.tokens
+        self.logs = LogsResource(self)
+        self.usage = self.logs
+        self.history = self.logs
+        self.groups = GroupsResource(self)
+        self.dashboard = DashboardResource(self)
+        self.topup = TopUpResource(self)
+        self.payment = PaymentResource(self)
+        self.subscriptions = SubscriptionResource(self)
+
+    @property
+    def session(self) -> SessionTokens:
+        return self._tokens
+
+    @property
+    def is_authenticated(self) -> bool:
+        return self._tokens.authenticated
+
+    @property
+    def quota_per_unit(self) -> float | None:
+        return self._quota_per_unit
+
+    def _resolve_session_user_id(
+        self,
+        access_token: str | None,
+        session_token: str | None,
+        user_id: int | None,
+    ) -> int | None:
+        if access_token and session_token:
+            raise ConfigurationError("pass either access_token or session_token, not both")
+        if access_token and user_id is None:
+            raise ConfigurationError(
+                "user_id is required when authenticating with an access_token; "
+                "new-api instances reject such requests with 401 "
+                "'Unauthorized, New-Api-User header not provided'"
+            )
+        if not session_token or user_id is not None:
+            return user_id
+        try:
+            fields = decode_session_blob(session_token)
+        except ValueError as error:
+            raise ConfigurationError(
+                "session_token is not a decodable browser session cookie; "
+                "pass user_id alongside it for instances with opaque cookies"
+            ) from error
+        embedded_id = fields.get("id")
+        if not isinstance(embedded_id, int) or isinstance(embedded_id, bool):
+            raise ConfigurationError(
+                "session_token does not embed a user id; pass user_id explicitly"
+            )
+        return embedded_id
+
+    def login(
+        self,
+        username: str,
+        password: str,
+        *,
+        turnstile_token: str | None = None,
+        encrypt_password: bool = True,
+    ) -> User:
+        if not username.strip() or not password:
+            raise ValueError("username and password are required")
+        payload: dict[str, Any] = {"username": username}
+        key = self._password_encryption_key() if encrypt_password else None
+        if key is not None:
+            payload["password_encrypted"] = rsa_oaep_sha256_encrypt(
+                password.encode(), key["public_key"]
+            )
+            payload["encryption_key_id"] = key["kid"]
+        else:
+            payload["password"] = password
+        params = {"turnstile": turnstile_token} if turnstile_token else None
+        data, response = self._request_with_response(
+            "POST",
+            "user/login",
+            params=params,
+            json=payload,
+            authenticated=False,
+            allow_refresh=False,
+        )
+        auth = self._auth_mapping(data, "login")
+        if auth.get("require_2fa") is True:
+            flow_token = auth.get("flow_token")
+            if not isinstance(flow_token, str) or not flow_token:
+                raise ProtocolError("2FA login response did not contain a flow token")
+            self._pending_2fa_token = flow_token
+            expires_at = auth.get("expires_at")
+            raise TwoFactorRequired(
+                flow_token,
+                float(expires_at) if isinstance(expires_at, (int, float)) else None,
+            )
+        return self._accept_auth(auth, response)
+
+    def complete_2fa(self, code: str, *, flow_token: str | None = None) -> User:
+        token = flow_token or self._pending_2fa_token
+        if not token:
+            raise ValueError("flow_token is required when no 2FA login is pending")
+        if not code.strip():
+            raise ValueError("code must not be empty")
+        data, response = self._request_with_response(
+            "POST",
+            "user/login/2fa",
+            json={"code": code, "flow_token": token},
+            authenticated=False,
+            allow_refresh=False,
+        )
+        user = self._accept_auth(self._auth_mapping(data, "2FA login"), response)
+        self._pending_2fa_token = None
+        return user
+
+    def refresh(self) -> SessionTokens:
+        if self._tokens.session_token and not self._tokens.refresh_token:
+            raise AuthenticationError(
+                "Session-cookie authentication has no refresh flow; "
+                "extract a fresh browser session cookie instead",
+                status_code=401,
+                code="SESSION_COOKIE_NO_REFRESH",
+            )
+        with self._refresh_lock:
+            refresh_token = self._tokens.refresh_token
+            if not refresh_token:
+                raise AuthenticationError(
+                    "No refresh token is available",
+                    status_code=401,
+                    code="NO_REFRESH_TOKEN",
+                )
+            try:
+                data, response = self._request_with_response(
+                    "POST",
+                    "user/auth/refresh",
+                    refresh_cookie=refresh_token,
+                    authenticated=False,
+                    allow_refresh=False,
+                )
+                auth = self._auth_mapping(data, "token refresh")
+                access_token = auth.get("access_token")
+                if not isinstance(access_token, str) or not access_token:
+                    raise ProtocolError("token refresh did not return an access token")
+                rotated = self._harvest_refresh_token(response) or refresh_token
+                self._tokens = self._tokens_from_auth(auth, rotated)
+                return self._tokens
+            except APIError as error:
+                if 400 <= error.status_code < 500:
+                    self.clear_auth()
+                raise
+
+    def logout(self) -> None:
+        if self._tokens.session_token and not self._tokens.access_token:
+            try:
+                self._request(
+                    "POST",
+                    "user/logout",
+                    authenticated=True,
+                    allow_refresh=False,
+                )
+            finally:
+                self.clear_auth()
+            return
+        refresh_token = self._tokens.refresh_token
+        headers: dict[str, str] = {"Origin": self._origin()}
+        if self._tokens.user_id is not None:
+            headers[_USER_ID_HEADER] = str(self._tokens.user_id)
+        if self._tokens.access_token:
+            headers["Authorization"] = f"{self._tokens.token_type} {self._tokens.access_token}"
+        try:
+            self._request(
+                "POST",
+                "user/auth/logout",
+                refresh_cookie=refresh_token,
+                headers=headers,
+                authenticated=False,
+                allow_refresh=False,
+            )
+        finally:
+            self.clear_auth()
+
+    def clear_auth(self) -> None:
+        self._tokens = SessionTokens()
+        self._pending_2fa_token = None
+
+    def me(self) -> User:
+        return self.account.profile()
+
+    def balance(self) -> Balance:
+        profile = self.account.profile()
+        quota_per_unit = self._resolve_quota_per_unit()
+        try:
+            return Balance(
+                quota=int(profile.get("quota", 0)),
+                used_quota=int(profile.get("used_quota", 0)),
+                aff_quota=int(profile.get("aff_quota", 0)),
+                quota_per_unit=quota_per_unit,
+            )
+        except (TypeError, ValueError) as error:
+            raise ProtocolError("profile response did not contain valid quota values") from error
+
+    def status(self) -> Resource:
+        data = self._request(
+            "GET",
+            "status",
+            authenticated=False,
+            allow_refresh=False,
+        )
+        if not isinstance(data, Mapping):
+            raise ProtocolError("status returned a non-object response")
+        quota_per_unit = data.get("quota_per_unit")
+        if isinstance(quota_per_unit, (int, float)) and quota_per_unit > 0:
+            self._quota_per_unit = float(quota_per_unit)
+        return Resource(data)
+
+    def notice(self) -> Any:
+        return self._request("GET", "notice", authenticated=False, allow_refresh=False)
+
+    def about(self) -> Any:
+        return self._request("GET", "about", authenticated=False, allow_refresh=False)
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Mapping[str, Any] | None = None,
+        json: Any = None,
+        headers: Mapping[str, str] | None = None,
+        authenticated: bool = True,
+    ) -> Any:
+        return self._request(
+            method,
+            path,
+            params=params,
+            json=json,
+            headers=headers,
+            authenticated=authenticated,
+            allow_refresh=True,
+        )
+
+    def close(self) -> None:
+        if self._owns_http_client:
+            self._http.close()
+
+    def __enter__(self) -> NewAPI:
+        return self
+
+    def __exit__(self, exc_type: Any, exc_value: Any, traceback: Any) -> None:
+        self.close()
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Mapping[str, Any] | None = None,
+        json: Any = None,
+        headers: Mapping[str, str] | None = None,
+        authenticated: bool,
+        allow_refresh: bool,
+        refresh_cookie: str | None = None,
+    ) -> Any:
+        return self._request_with_response(
+            method,
+            path,
+            params=params,
+            json=json,
+            headers=headers,
+            authenticated=authenticated,
+            allow_refresh=allow_refresh,
+            refresh_cookie=refresh_cookie,
+        )[0]
+
+    def _request_with_response(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Mapping[str, Any] | None = None,
+        json: Any = None,
+        headers: Mapping[str, str] | None = None,
+        authenticated: bool,
+        allow_refresh: bool,
+        refresh_cookie: str | None = None,
+    ) -> tuple[Any, Any]:
+        normalized_method = method.upper()
+        if authenticated and allow_refresh:
+            self._refresh_if_expiring()
+        failed_token = self._tokens.access_token
+        response = self._send(
+            normalized_method,
+            path,
+            params=params,
+            json=json,
+            headers=headers,
+            authenticated=authenticated,
+            refresh_cookie=refresh_cookie,
+        )
+        if authenticated and self._tokens.session_token:
+            self._harvest_session_cookie(response)
+        if (
+            response.status_code == 401
+            and authenticated
+            and allow_refresh
+            and self._tokens.refresh_token
+        ):
+            self._refresh_after_unauthorized(failed_token)
+            response = self._send(
+                normalized_method,
+                path,
+                params=params,
+                json=json,
+                headers=headers,
+                authenticated=authenticated,
+            )
+        return self._decode(response), response
+
+    def _send(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Mapping[str, Any] | None,
+        json: Any,
+        headers: Mapping[str, str] | None,
+        authenticated: bool,
+        refresh_cookie: str | None = None,
+    ) -> Any:
+        relative_path = _request_path(path)
+        request_headers = {
+            "Accept": "application/json",
+            "Accept-Language": self.language,
+            "User-Agent": "newapi-python/0.3.0",
+        }
+        if authenticated:
+            if self._tokens.user_id is not None:
+                request_headers[_USER_ID_HEADER] = str(self._tokens.user_id)
+            if self._tokens.session_token:
+                request_headers["Cookie"] = f"{self._session_cookie}={self._tokens.session_token}"
+            elif self._tokens.access_token:
+                request_headers["Authorization"] = (
+                    f"{self._tokens.token_type} {self._tokens.access_token}"
+                )
+        if refresh_cookie and not self._session_has_refresh_cookie():
+            request_headers["Cookie"] = f"{_REFRESH_COOKIE}={refresh_cookie}"
+        if headers:
+            request_headers.update(headers)
+        try:
+            return cast(Any, self._http).request(
+                method,
+                f"{self.base_url}/{relative_path}",
+                params=_query(params),
+                json=json,
+                headers=request_headers,
+                timeout=self.timeout,
+                allow_redirects=False,
+            )
+        except curl_requests.RequestsError as error:
+            raise TransportError(f"{method} request to the new-api instance failed") from error
+
+    def _decode(self, response: Any) -> Any:
+        if not response.content:
+            if _success(response):
+                return None
+            self._raise_api_error(response, {})
+        try:
+            payload = response.json()
+        except ValueError as error:
+            if not _success(response):
+                raise ProtocolError(
+                    f"new-api returned non-JSON HTTP {response.status_code}"
+                ) from error
+            raise ProtocolError("new-api returned a non-JSON success response") from error
+        if not _success(response):
+            self._raise_api_error(response, payload)
+        if isinstance(payload, Mapping):
+            if "success" in payload:
+                if payload.get("success") is not True:
+                    self._raise_api_error(response, payload)
+                return payload.get("data")
+            if "message" in payload:
+                if payload.get("message") != "success":
+                    self._raise_api_error(response, payload)
+                return payload
+        return payload
+
+    def _raise_api_error(self, response: Any, payload: Any) -> None:
+        data = payload if isinstance(payload, Mapping) else {}
+        code = data.get("code")
+        fallback_message = (
+            getattr(response, "reason_phrase", None)
+            or getattr(response, "reason", None)
+            or f"HTTP {response.status_code}"
+        )
+        message: Any = data.get("message")
+        detail = data.get("data")
+        if not isinstance(message, str) or message == "" or message == "error":
+            message = detail if isinstance(detail, str) and detail else fallback_message
+        status_code = response.status_code
+        error_type = _ERROR_TYPES.get(status_code, APIError)
+        raise error_type(
+            str(message),
+            status_code=status_code,
+            code=code if isinstance(code, (int, str)) else None,
+            retry_after=_retry_after(response),
+        )
+
+    def _origin(self) -> str:
+        parsed = urlsplit(self.base_url)
+        return urlunsplit((parsed.scheme, parsed.netloc, "", "", ""))
+
+    def _password_encryption_key(self) -> Resource | None:
+        data = self._request(
+            "GET",
+            "user/login/encryption-key",
+            authenticated=False,
+            allow_refresh=False,
+        )
+        if not isinstance(data, Mapping):
+            raise ProtocolError("login encryption key response was not an object")
+        key = Resource(data)
+        if not key.get("enabled"):
+            return None
+        if not key.get("kid") or not key.get("public_key"):
+            raise ProtocolError("login encryption key response was incomplete")
+        return key
+
+    def _harvest_refresh_token(self, response: Any) -> str | None:
+        for value in _set_cookie_values(response):
+            match = _REFRESH_COOKIE_PATTERN.search(value)
+            if match:
+                return match.group(1)
+        jar = getattr(self._http, "cookies", None)
+        if jar is not None:
+            try:
+                stored = jar.get(_REFRESH_COOKIE)
+            except Exception:
+                stored = None
+            if isinstance(stored, str) and stored:
+                return stored
+        return None
+
+    def _harvest_session_cookie(self, response: Any) -> None:
+        for value in _set_cookie_values(response):
+            match = self._session_cookie_pattern.search(value)
+            if match:
+                rotated = match.group(1)
+                if rotated and rotated != self._tokens.session_token:
+                    self._tokens = replace(self._tokens, session_token=rotated)
+                return
+
+    def _session_has_refresh_cookie(self) -> bool:
+        jar = getattr(self._http, "cookies", None)
+        if jar is None:
+            return False
+        try:
+            stored = jar.get(_REFRESH_COOKIE)
+        except Exception:
+            return False
+        return isinstance(stored, str) and bool(stored)
+
+    def _refresh_if_expiring(self) -> None:
+        with self._refresh_lock:
+            if self._tokens.needs_refresh():
+                self.refresh()
+
+    def _refresh_after_unauthorized(self, failed_token: str | None) -> None:
+        with self._refresh_lock:
+            if self._tokens.access_token and self._tokens.access_token != failed_token:
+                return
+            self.refresh()
+
+    def _auth_mapping(self, data: Any, operation: str) -> Mapping[str, Any]:
+        if not isinstance(data, Mapping):
+            raise ProtocolError(f"{operation} returned a non-object response")
+        return data
+
+    def _accept_auth(self, auth: Mapping[str, Any], response: Any) -> User:
+        access_token = auth.get("access_token")
+        if not isinstance(access_token, str) or not access_token:
+            raise ProtocolError("login did not return an access token")
+        user_data = auth.get("user")
+        if not isinstance(user_data, Mapping):
+            raise ProtocolError("login did not return a user profile")
+        self._tokens = self._tokens_from_auth(auth, self._harvest_refresh_token(response))
+        return User(user_data)
+
+    def _tokens_from_auth(
+        self,
+        auth: Mapping[str, Any],
+        refresh_token: str | None,
+    ) -> SessionTokens:
+        expires_at = None
+        raw_expires_at = auth.get("access_expires_at")
+        if isinstance(raw_expires_at, (int, float)) and not isinstance(raw_expires_at, bool):
+            expires_at = float(raw_expires_at)
+        token_type = auth.get("token_type")
+        session = auth.get("session")
+        session_id = None
+        if isinstance(session, Mapping):
+            raw_session_id = session.get("sid")
+            session_id = raw_session_id if isinstance(raw_session_id, str) else None
+        user_id = self._tokens.user_id
+        user_data = auth.get("user")
+        if isinstance(user_data, Mapping):
+            raw_user_id = user_data.get("id")
+            if isinstance(raw_user_id, int) and not isinstance(raw_user_id, bool):
+                user_id = raw_user_id
+        return SessionTokens(
+            access_token=str(auth["access_token"]),
+            refresh_token=refresh_token,
+            expires_at=expires_at,
+            token_type=str(token_type) if token_type else "Bearer",
+            session_id=session_id,
+            user_id=user_id,
+        )
+
+    def _resolve_quota_per_unit(self) -> float:
+        if self._quota_per_unit is None:
+            self.status()
+        return self._quota_per_unit if self._quota_per_unit is not None else _DEFAULT_QUOTA_PER_UNIT

{newapi_python-0.2.0 → newapi_python-0.3.0}/tests/test_client.py

@@ -232,6 +232,7 @@ def test_unauthorized_request_refreshes_once_with_cookie_and_rotates() -> None:
         "https://example.test",
         access_token="access-old",
         refresh_token="refresh-old",
+        user_id=1,
         session=session,
     )
 
@@ -276,6 +277,7 @@ def test_proactive_refresh_uses_expiration_timestamp() -> None:
         access_token="expired",
         refresh_token="refresh",
         expires_at=time.time() - 1,
+        user_id=1,
         session=session,
     )
 
@@ -287,7 +289,7 @@ def test_proactive_refresh_uses_expiration_timestamp() -> None:
 def test_refresh_without_cookie_header_when_jar_lacks_it() -> None:
     def handler(request: httpx.Request) -> httpx.Response:
         assert request.url.path.endswith("/user/auth/refresh")
-        assert request.headers.get("cookie") == "new_api_refresh=manual-refresh"
+        assert request.headers.get("cookie") == "new_api_refresh=fixture-refresh"
         return httpx.Response(
             200,
             json={
@@ -305,15 +307,16 @@ def test_refresh_without_cookie_header_when_jar_lacks_it() -> None:
     client = NewAPI(
         "https://example.test",
         access_token="expired",
-        refresh_token="manual-refresh",
+        refresh_token="fixture-refresh",
         expires_at=time.time() - 1,
+        user_id=5,
         session=TestSession(handler),
     )
 
     tokens = client.refresh()
 
     assert tokens.access_token == "fresh"
-    assert tokens.refresh_token == "manual-refresh"
+    assert tokens.refresh_token == "fixture-refresh"
 
 
 def test_business_error_envelope_raises_api_error() -> None:
@@ -376,6 +379,7 @@ def test_remote_plaintext_and_unsafe_request_urls_are_rejected() -> None:
     client = NewAPI(
         "https://example.test/api",
         access_token="secret",
+        user_id=1,
         session=TestSession(lambda request: envelope({})),
     )
 
@@ -408,6 +412,7 @@ def test_refresh_rejection_clears_authentication() -> None:
         "https://example.test",
         access_token="access",
         refresh_token="refresh",
+        user_id=1,
         session=TestSession(handler),
     )
 
@@ -423,12 +428,14 @@ def test_logout_sends_bearer_and_clears_auth() -> None:
         assert request.url.path.endswith("/user/auth/logout")
         assert request.headers["Authorization"] == "Bearer access-one"
         assert request.headers["Origin"] == "https://example.test"
+        assert request.headers["New-Api-User"] == "1"
         return envelope({"revoked_sid": "sid-1"})
 
     client = NewAPI(
         "https://example.test",
         access_token="access-one",
         refresh_token="refresh-one",
+        user_id=1,
         session=TestSession(handler),
     )
 
@@ -449,6 +456,7 @@ def test_balance_uses_status_quota_per_unit() -> None:
     client = NewAPI(
         "https://example.test",
         access_token="token",
+        user_id=1,
         session=TestSession(handler),
     )
 
@@ -585,3 +593,43 @@ def test_session_cookie_is_redacted_from_representations() -> None:
 
     assert token not in repr(client.session)
     assert decode_session_blob(client.session.session_token)["id"] == 42
+
+
+def test_access_token_without_user_id_is_rejected() -> None:
+    with pytest.raises(ConfigurationError) as caught:
+        NewAPI("https://example.test", access_token="access")
+
+    assert "New-Api-User" in str(caught.value)
+
+
+def test_access_token_auth_sends_new_api_user_header() -> None:
+    def handler(request: httpx.Request) -> httpx.Response:
+        assert request.headers["Authorization"] == "Bearer token"
+        assert request.headers["New-Api-User"] == "42"
+        return envelope({"id": 42, "username": "root"})
+
+    client = NewAPI(
+        "https://example.test",
+        access_token="token",
+        user_id=42,
+        session=TestSession(handler),
+    )
+
+    assert client.me().id == 42
+
+
+def test_login_captures_user_id_for_new_api_user_header() -> None:
+    def handler(request: httpx.Request) -> httpx.Response:
+        if request.url.path.endswith("/user/login/encryption-key"):
+            return no_encryption(request)
+        if request.url.path.endswith("/user/login"):
+            return login_response()
+        assert request.headers.get("New-Api-User") == "1"
+        return envelope({"id": 1, "quota": 0})
+
+    client = NewAPI("https://example.test", session=TestSession(handler))
+
+    client.login("root", "secret")
+
+    assert client.me().id == 1
+    assert client.session.user_id == 1

{newapi_python-0.2.0 → newapi_python-0.3.0}/tests/test_resources.py

@@ -32,6 +32,7 @@ def client(handler: Any) -> NewAPI:
     return NewAPI(
         "https://example.test",
         access_token="token",
+        user_id=1,
         session=TestSession(handler),
     )