nexalayer 0.1.0__tar.gz

nexalayer-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 NexaLayer
+
+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.

nexalayer-0.1.0/PKG-INFO

@@ -0,0 +1,211 @@
+Metadata-Version: 2.4
+Name: nexalayer
+Version: 0.1.0
+Summary: NexaLayer SDK — The Network Execution Layer for AI Agents
+Author: NexaLayer
+License-Expression: MIT
+Project-URL: Documentation, https://docs.nexalayer.net
+Project-URL: Repository, https://github.com/NexaLayer/nexalayer-sdk
+Project-URL: Issues, https://github.com/NexaLayer/nexalayer-sdk/issues
+Keywords: proxy,agent,session,nexalayer
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.28
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: pytest-cov>=4; extra == "dev"
+Dynamic: license-file
+
+# NexaLayer SDK
+
+Managed network sessions for Playwright, Browser Use, AI agents, and automation scripts.
+
+**Keep using proxies. Stop managing them.**  
+中文：代理继续使用，代理管理交给 NexaLayer。
+
+This repository contains the Python and Node/TypeScript SDK source. Release automation publishes signed release artifacts to PyPI and npm after registry ownership and secrets are configured.
+
+## Status
+
+| Runtime | Source | Package registry status |
+| --- | --- | --- |
+| Python | `python/` | Package name `nexalayer`; release workflow configured |
+| Node / TypeScript | `node/` | Package name `@nexalayer/sdk`; release workflow configured |
+
+## Installation
+
+Python from repository root:
+
+```bash
+python3 -m venv .venv
+. .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+Node from repository root:
+
+```bash
+cd node
+npm install
+npm run build
+```
+
+## Authentication
+
+```bash
+export NEXALAYER_BASE_URL=https://api.nexalayer.net/v1
+export NEXALAYER_API_KEY=agk_your_key
+```
+
+The SDK uses `X-API-Key` for Agent requests.
+
+## 60-second Python example
+
+This example auto-selects a dynamic product, creates a session, reports telemetry, reads health, and terminates the session in cleanup.
+
+```python
+import os
+import time
+import uuid
+
+import requests
+from nexalayer import NexaLayerClient
+
+api_key = os.environ["NEXALAYER_API_KEY"]
+client = NexaLayerClient(api_key=api_key)
+session_id = None
+
+def data(resp):
+    return resp.get("data", resp)
+
+try:
+    products = data(client.get_products(type="dynamic"))
+    product = next(p for p in products.get("items", []) if p.get("product_no"))
+
+    session = client.create_session(
+        session_type="dynamic",
+        product_no=product["product_no"],
+        quantity=1,
+        protocol="socks5",
+        rotation_mode="on_demand",
+        idempotency_key=f"py-{uuid.uuid4()}",
+    )
+    session_id = session.session_id
+
+    for _ in range(60):
+        current = data(client.get_session(session_id))
+        if current.get("status") == "active":
+            proxy_url = current["proxy"]["full_url"]
+            break
+        time.sleep(2)
+    else:
+        raise TimeoutError("Session did not become active")
+
+    res = requests.get(
+        "https://httpbin.org/ip",
+        proxies={"http": proxy_url, "https": proxy_url},
+        timeout=30,
+    )
+    client.report_event(
+        session_id,
+        event_type="success" if res.ok else "http_error",
+        status_code=res.status_code,
+        target_host="httpbin.org",
+    )
+    print(client.get_session_health(session_id))
+finally:
+    if session_id:
+        client.terminate_session(session_id)
+```
+
+## Dynamic Session
+
+Use a dynamic session when your automation can rotate after errors such as timeout, 403, 429, or explicit blocks.
+
+```python
+session = client.create_session(
+    session_type="dynamic",
+    product_no="selected_from_products_api",
+    quantity=1,
+    protocol="socks5",
+    rotation_mode="on_demand",
+)
+```
+
+## Static Session
+
+Use a static session when you need fixed network identity for a longer-lived task.
+
+```python
+session = client.create_session(
+    session_type="static",
+    product_no="selected_from_products_api",
+    quantity=1,
+    duration=30,
+    protocol="socks5",
+)
+```
+
+## Telemetry
+
+```python
+client.report_event(
+    session_id,
+    event_type="timeout",
+    status_code=0,
+    target_host="example.com",
+)
+```
+
+## Health
+
+```python
+health = client.get_session_health(session_id)
+```
+
+`timeout`, `captcha`, `block`, and repeated HTTP errors are not neutral noise; report them so NexaLayer can score the session and recommend rotate or pause.
+
+## Cleanup
+
+Always terminate sessions you no longer need:
+
+```python
+try:
+    ...
+finally:
+    if session_id:
+        client.terminate_session(session_id)
+```
+
+## Playwright
+
+Use the public Playwright examples:
+
+- Chinese: https://github.com/NexaLayer/nexalayer-examples/tree/main/playwright/basic-session
+- English: https://github.com/NexaLayer/nexalayer-examples/tree/main/playwright/basic-session
+
+## 中文文档
+
+- 中文快速开始: https://docs.nexalayer.net/zh/quick-start
+- Playwright 中文 Demo: https://docs.nexalayer.net/zh/examples
+- API 文档: https://docs.nexalayer.net/api-reference/openapi
+
+## Error handling
+
+- Check `backend_ready=true` before creating paid sessions after registration.
+- Use `Idempotency-Key` for create, rotate, renew, and recharge operations.
+- Do not log `proxy.full_url` in production without redaction because it can contain proxy credentials.
+- Respect target website terms and applicable law.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Security
+
+Do not open public issues with API keys, cookies, account passwords, proxy credentials, or target-site secrets. See [SECURITY.md](SECURITY.md).

nexalayer-0.1.0/README.md

@@ -0,0 +1,188 @@
+# NexaLayer SDK
+
+Managed network sessions for Playwright, Browser Use, AI agents, and automation scripts.
+
+**Keep using proxies. Stop managing them.**  
+中文：代理继续使用，代理管理交给 NexaLayer。
+
+This repository contains the Python and Node/TypeScript SDK source. Release automation publishes signed release artifacts to PyPI and npm after registry ownership and secrets are configured.
+
+## Status
+
+| Runtime | Source | Package registry status |
+| --- | --- | --- |
+| Python | `python/` | Package name `nexalayer`; release workflow configured |
+| Node / TypeScript | `node/` | Package name `@nexalayer/sdk`; release workflow configured |
+
+## Installation
+
+Python from repository root:
+
+```bash
+python3 -m venv .venv
+. .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+Node from repository root:
+
+```bash
+cd node
+npm install
+npm run build
+```
+
+## Authentication
+
+```bash
+export NEXALAYER_BASE_URL=https://api.nexalayer.net/v1
+export NEXALAYER_API_KEY=agk_your_key
+```
+
+The SDK uses `X-API-Key` for Agent requests.
+
+## 60-second Python example
+
+This example auto-selects a dynamic product, creates a session, reports telemetry, reads health, and terminates the session in cleanup.
+
+```python
+import os
+import time
+import uuid
+
+import requests
+from nexalayer import NexaLayerClient
+
+api_key = os.environ["NEXALAYER_API_KEY"]
+client = NexaLayerClient(api_key=api_key)
+session_id = None
+
+def data(resp):
+    return resp.get("data", resp)
+
+try:
+    products = data(client.get_products(type="dynamic"))
+    product = next(p for p in products.get("items", []) if p.get("product_no"))
+
+    session = client.create_session(
+        session_type="dynamic",
+        product_no=product["product_no"],
+        quantity=1,
+        protocol="socks5",
+        rotation_mode="on_demand",
+        idempotency_key=f"py-{uuid.uuid4()}",
+    )
+    session_id = session.session_id
+
+    for _ in range(60):
+        current = data(client.get_session(session_id))
+        if current.get("status") == "active":
+            proxy_url = current["proxy"]["full_url"]
+            break
+        time.sleep(2)
+    else:
+        raise TimeoutError("Session did not become active")
+
+    res = requests.get(
+        "https://httpbin.org/ip",
+        proxies={"http": proxy_url, "https": proxy_url},
+        timeout=30,
+    )
+    client.report_event(
+        session_id,
+        event_type="success" if res.ok else "http_error",
+        status_code=res.status_code,
+        target_host="httpbin.org",
+    )
+    print(client.get_session_health(session_id))
+finally:
+    if session_id:
+        client.terminate_session(session_id)
+```
+
+## Dynamic Session
+
+Use a dynamic session when your automation can rotate after errors such as timeout, 403, 429, or explicit blocks.
+
+```python
+session = client.create_session(
+    session_type="dynamic",
+    product_no="selected_from_products_api",
+    quantity=1,
+    protocol="socks5",
+    rotation_mode="on_demand",
+)
+```
+
+## Static Session
+
+Use a static session when you need fixed network identity for a longer-lived task.
+
+```python
+session = client.create_session(
+    session_type="static",
+    product_no="selected_from_products_api",
+    quantity=1,
+    duration=30,
+    protocol="socks5",
+)
+```
+
+## Telemetry
+
+```python
+client.report_event(
+    session_id,
+    event_type="timeout",
+    status_code=0,
+    target_host="example.com",
+)
+```
+
+## Health
+
+```python
+health = client.get_session_health(session_id)
+```
+
+`timeout`, `captcha`, `block`, and repeated HTTP errors are not neutral noise; report them so NexaLayer can score the session and recommend rotate or pause.
+
+## Cleanup
+
+Always terminate sessions you no longer need:
+
+```python
+try:
+    ...
+finally:
+    if session_id:
+        client.terminate_session(session_id)
+```
+
+## Playwright
+
+Use the public Playwright examples:
+
+- Chinese: https://github.com/NexaLayer/nexalayer-examples/tree/main/playwright/basic-session
+- English: https://github.com/NexaLayer/nexalayer-examples/tree/main/playwright/basic-session
+
+## 中文文档
+
+- 中文快速开始: https://docs.nexalayer.net/zh/quick-start
+- Playwright 中文 Demo: https://docs.nexalayer.net/zh/examples
+- API 文档: https://docs.nexalayer.net/api-reference/openapi
+
+## Error handling
+
+- Check `backend_ready=true` before creating paid sessions after registration.
+- Use `Idempotency-Key` for create, rotate, renew, and recharge operations.
+- Do not log `proxy.full_url` in production without redaction because it can contain proxy credentials.
+- Respect target website terms and applicable law.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Security
+
+Do not open public issues with API keys, cookies, account passwords, proxy credentials, or target-site secrets. See [SECURITY.md](SECURITY.md).

nexalayer-0.1.0/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["setuptools>=61", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "nexalayer"
+version = "0.1.0"
+description = "NexaLayer SDK — The Network Execution Layer for AI Agents"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+authors = [{ name = "NexaLayer" }]
+keywords = ["proxy", "agent", "session", "nexalayer"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+]
+dependencies = [
+    "requests>=2.28",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7",
+    "pytest-cov>=4",
+]
+
+[project.urls]
+Documentation = "https://docs.nexalayer.net"
+Repository = "https://github.com/NexaLayer/nexalayer-sdk"
+Issues = "https://github.com/NexaLayer/nexalayer-sdk/issues"
+
+[tool.setuptools.packages.find]
+where = ["python"]
+exclude = ["tests*"]
+
+[tool.pytest.ini_options]
+testpaths = ["python/tests"]
+pythonpath = ["python"]
+
+[tool.black]
+line-length = 88
+target-version = ["py39", "py310", "py311"]

nexalayer-0.1.0/python/nexalayer/__init__.py

@@ -0,0 +1,28 @@
+"""NexaLayer SDK — The Network Execution Layer for AI Agents."""
+
+from nexalayer.client import NexaLayerClient
+from nexalayer.session import Session
+from nexalayer.errors import (
+    NexaLayerError,
+    AuthError,
+    APIError,
+    SessionError,
+)
+from nexalayer.types import (
+    SessionConfig,
+    SessionCreateResponse,
+    TokenResponse,
+)
+
+__version__ = "0.1.0"
+__all__ = [
+    "NexaLayerClient",
+    "Session",
+    "NexaLayerError",
+    "AuthError",
+    "APIError",
+    "SessionError",
+    "SessionConfig",
+    "SessionCreateResponse",
+    "TokenResponse",
+]

nexalayer-0.1.0/python/nexalayer/client.py

@@ -0,0 +1,240 @@
+"""NexaLayer API client — auth, account, billing, products, sessions, stats."""
+
+from typing import Any, Optional, Union
+from urllib.parse import urlencode
+
+import requests
+
+from nexalayer.errors import APIError, AuthError
+from nexalayer.session import Session
+from nexalayer.types import SessionConfig, SessionCreateResponse, TokenResponse
+
+DEFAULT_BASE_URL = "https://api.nexalayer.net/v1"
+
+
+class NexaLayerClient:
+    """HTTP client for NexaLayer API with auth header injection."""
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        bearer_token: Optional[str] = None,
+        api_secret: Optional[str] = None,
+        base_url: str = DEFAULT_BASE_URL,
+    ):
+        self.base_url = base_url.rstrip("/")
+        self._api_key = api_key
+        self._bearer_token = bearer_token
+        self._api_secret = api_secret
+        self._session = requests.Session()
+        if bearer_token:
+            self._session.headers["Authorization"] = f"Bearer {bearer_token}"
+        elif api_key:
+            self._session.headers["X-API-Key"] = api_key
+
+    def _headers(self) -> dict:
+        h = {"Content-Type": "application/json", "Accept": "application/json"}
+        if self._bearer_token:
+            h["Authorization"] = f"Bearer {self._bearer_token}"
+        elif self._api_key:
+            h["X-API-Key"] = self._api_key
+        return h
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        json: Optional[dict] = None,
+        headers: Optional[dict] = None,
+        **kwargs: Any,
+    ) -> dict:
+        url = f"{self.base_url}{path}"
+        request_headers = self._headers()
+        if headers:
+            request_headers.update(headers)
+        resp = self._session.request(
+            method,
+            url,
+            json=json,
+            headers=request_headers,
+            timeout=kwargs.get("timeout", 30),
+        )
+        if resp.status_code >= 400:
+            raise APIError(
+                f"API error: {resp.status_code}",
+                status_code=resp.status_code,
+                body=resp.text,
+            )
+        return resp.json() if resp.content else {}
+
+    def get_token(self, api_key: Optional[str] = None, api_secret: Optional[str] = None) -> TokenResponse:
+        """POST /auth/token — obtain Bearer token from API Key/Secret."""
+        # TODO: call real POST /auth/token when backend is available
+        key = api_key or self._api_key
+        secret = api_secret or self._api_secret
+        if not key or not secret:
+            raise AuthError("api_key and api_secret required for get_token")
+        payload = {"api_key": key, "api_secret": secret}
+        data = self._request("POST", "/auth/token", json=payload)
+        # Placeholder; replace with real response parsing
+        token = data.get("data", {}).get("access_token") or "mock-token"
+        return TokenResponse(access_token=token)
+
+    def register(
+        self,
+        name: str,
+        contact_email: str,
+        referral_code: Optional[str] = None,
+        **kwargs: Any,
+    ) -> dict:
+        """POST /account/register."""
+        # TODO: implement real call
+        payload: dict = {"name": name, "contact_email": contact_email, **kwargs}
+        if referral_code is not None:
+            payload["referral_code"] = referral_code
+        return self._request("POST", "/account/register", json=payload)
+
+    def request_api_key(self, email: str, referral_code: Optional[str] = None) -> dict:
+        """POST /account/request-api-key; first-time emails receive trial credit."""
+        payload = {"email": email}
+        if referral_code:
+            payload["referral_code"] = referral_code
+        return self._request("POST", "/account/request-api-key", json=payload)
+
+    def get_balance(self) -> dict:
+        """GET /billing/balance."""
+        # TODO: implement real call
+        return self._request("GET", "/billing/balance")
+
+    def recharge(
+        self,
+        amount: float,
+        currency: str = "USD",
+        idempotency_key: Optional[str] = None,
+        **kwargs: Any,
+    ) -> dict:
+        """POST /billing/recharge."""
+        # TODO: implement real call
+        payload = {"amount": amount, "currency": currency, **kwargs}
+        headers = {"Idempotency-Key": idempotency_key} if idempotency_key else None
+        return self._request("POST", "/billing/recharge", json=payload, headers=headers)
+
+    def get_budget(self) -> dict:
+        """GET /account/budget."""
+        return self._request("GET", "/account/budget")
+
+    def set_budget(
+        self,
+        *,
+        idempotency_key: str,
+        key_limit_usd: Optional[float] = None,
+        daily_limit_usd: Optional[float] = None,
+        pause_on_exceed: bool = True,
+        alert_thresholds: Optional[list] = None,
+        paused: Optional[bool] = None,
+    ) -> dict:
+        """PUT /account/budget."""
+        if not idempotency_key:
+            raise ValueError("idempotency_key is required")
+        payload = {
+            "key_limit_usd": key_limit_usd,
+            "daily_limit_usd": daily_limit_usd,
+            "pause_on_exceed": pause_on_exceed,
+            "alert_thresholds": alert_thresholds or [50, 80, 100],
+        }
+        if paused is not None:
+            payload["paused"] = paused
+        return self._request(
+            "PUT",
+            "/account/budget",
+            json=payload,
+            headers={"Idempotency-Key": idempotency_key},
+        )
+
+    def get_usage_alerts(self) -> dict:
+        """GET /account/usage-alerts."""
+        return self._request("GET", "/account/usage-alerts")
+
+    def get_products(self, type: str = "all", country_code: Optional[str] = None) -> dict:
+        """GET /products."""
+        query = {"type": type}
+        if country_code:
+            query["country_code"] = country_code
+        return self._request("GET", f"/products?{urlencode(query)}")
+
+    def recommend_products(self, criteria: dict) -> dict:
+        """POST /products/recommend."""
+        # TODO: implement real call
+        return self._request("POST", "/products/recommend", json=criteria)
+
+    def create_session(
+        self,
+        type: Optional[str] = None,
+        session_type: Optional[str] = None,
+        product_no: Optional[str] = None,
+        config: Optional[Union[dict, SessionConfig]] = None,
+        idempotency_key: Optional[str] = None,
+        **kwargs: Any,
+    ) -> Session:
+        """POST /sessions — create a session and return a Session object."""
+        cfg = config.to_dict() if isinstance(config, SessionConfig) else (config or {})
+        resolved_type = session_type or type or cfg.pop("session_type", "dynamic")
+        resolved_product = product_no or cfg.pop("product_no", None)
+        if not resolved_product:
+            raise APIError("product_no is required")
+        payload = {
+            "session_type": resolved_type,
+            "product_no": resolved_product,
+            **cfg,
+            **kwargs,
+        }
+        headers = {"Idempotency-Key": idempotency_key} if idempotency_key else None
+        data = self._request("POST", "/sessions", json=payload, headers=headers)
+        inner = data.get("data", data)
+        session_id = inner.get("session_id")
+        if not session_id:
+            raise APIError(f"Session create response missing session_id: {data}")
+        status = inner.get("status") or "creating"
+        proxy_config = inner.get("proxy") or inner.get("proxy_config") or {}
+        resp = SessionCreateResponse(
+            session_id=session_id,
+            status=status,
+            proxy_config=proxy_config,
+        )
+        return Session(
+            client=self,
+            session_id=resp.session_id,
+            proxy_config=resp.proxy_config,
+        )
+
+    def get_session(self, session_id: str) -> dict:
+        """GET /sessions/{session_id}."""
+        # TODO: implement real call
+        return self._request("GET", f"/sessions/{session_id}")
+
+    def rotate_session(self, session_id: str, idempotency_key: Optional[str] = None) -> dict:
+        """POST /sessions/{session_id}/rotate."""
+        headers = {"Idempotency-Key": idempotency_key} if idempotency_key else None
+        return self._request("POST", f"/sessions/{session_id}/rotate", headers=headers)
+
+    def terminate_session(self, session_id: str) -> dict:
+        """DELETE /sessions/{session_id}."""
+        return self._request("DELETE", f"/sessions/{session_id}")
+
+    def report_event(self, session_id: str, **event: Any) -> dict:
+        """POST /sessions/{session_id}/report-event."""
+        return self._request("POST", f"/sessions/{session_id}/report-event", json=event)
+
+    def get_session_health(self, session_id: str) -> dict:
+        """GET /sessions/{session_id}/health."""
+        return self._request("GET", f"/sessions/{session_id}/health")
+
+    def get_session_usage(self, session_id: str) -> dict:
+        """GET /sessions/{session_id}/usage."""
+        # TODO: implement real call
+        return self._request("GET", f"/sessions/{session_id}/usage")
+
+    def get_stats_overview(self) -> dict:
+        """GET /stats/overview."""
+        # TODO: implement real call
+        return self._request("GET", "/stats/overview")

nexalayer-0.1.0/python/nexalayer/errors.py

@@ -0,0 +1,30 @@
+"""NexaLayer SDK error classes."""
+
+from typing import Optional
+
+
+class NexaLayerError(Exception):
+    """Base exception for NexaLayer SDK."""
+
+    def __init__(
+        self,
+        message: str,
+        status_code: Optional[int] = None,
+        body: Optional[str] = None,
+    ):
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.body = body
+
+
+class AuthError(NexaLayerError):
+    """Authentication or authorization failed."""
+
+
+class APIError(NexaLayerError):
+    """API returned an error (4xx/5xx)."""
+
+
+class SessionError(NexaLayerError):
+    """Session operation failed (create, rotate, get, etc.)."""

nexalayer-0.1.0/python/nexalayer/session.py

@@ -0,0 +1,46 @@
+"""Session abstraction for NexaLayer managed sessions."""
+
+from typing import TYPE_CHECKING, Any, Optional
+
+import requests
+
+from nexalayer.errors import SessionError
+
+if TYPE_CHECKING:
+    from nexalayer.client import NexaLayerClient
+
+
+class Session:
+    """Represents a NexaLayer proxy session; use get/post to send traffic via proxy."""
+
+    def __init__(
+        self,
+        client: "NexaLayerClient",
+        session_id: str,
+        proxy_config: Optional[dict] = None,
+    ):
+        self.client = client
+        self.session_id = session_id
+        self.proxy_config = proxy_config or {}
+        self._session = requests.Session()
+        # Transport helpers are intentionally minimal. Production integrations
+        # should use proxy.full_url or host/port credentials from GET /sessions.
+        # self._session.proxies = {"http": ..., "https": ...}
+
+    def get(self, url: str, **kwargs: Any) -> requests.Response:
+        """Perform GET with the local requests session."""
+        # TODO: use proxy_config to route via proxy when available
+        return self._session.get(url, timeout=kwargs.get("timeout", 30))
+
+    def post(self, url: str, data: Any = None, json: Any = None, **kwargs: Any) -> requests.Response:
+        """Perform POST with the local requests session."""
+        # TODO: use proxy_config to route via proxy when available
+        return self._session.post(url, data=data, json=json, timeout=kwargs.get("timeout", 30))
+
+    def rotate(self) -> dict:
+        """POST /sessions/{session_id}/rotate — rotate proxy for this session."""
+        return self.client.rotate_session(self.session_id)
+
+    def usage(self) -> dict:
+        """GET /sessions/{session_id}/usage."""
+        return self.client.get_session_usage(self.session_id)

nexalayer-0.1.0/python/nexalayer/types.py

@@ -0,0 +1,59 @@
+"""Lightweight request/response types for NexaLayer API."""
+
+from typing import Any, Optional
+
+
+class SessionConfig:
+    """Configuration for creating a session (dynamic or static)."""
+
+    def __init__(
+        self,
+        product_no: Optional[str] = None,
+        traffic_gb: Optional[float] = None,
+        protocol: Optional[str] = None,
+        country: Optional[str] = None,
+        **kwargs: Any,
+    ):
+        self.product_no = product_no
+        self.traffic_gb = traffic_gb
+        self.protocol = protocol
+        self.country = country
+        self.extra = kwargs
+
+    def to_dict(self) -> dict:
+        out = {}
+        if self.product_no is not None:
+            out["product_no"] = self.product_no
+        if self.traffic_gb is not None:
+            out["traffic_gb"] = self.traffic_gb
+        if self.protocol is not None:
+            out["protocol"] = self.protocol
+        if self.country is not None:
+            out["country"] = self.country
+        out.update(self.extra)
+        return out
+
+
+class TokenResponse:
+    """Response from POST /auth/token."""
+
+    def __init__(self, access_token: str, token_type: str = "Bearer", **kwargs: Any):
+        self.access_token = access_token
+        self.token_type = token_type
+        self.extra = kwargs
+
+
+class SessionCreateResponse:
+    """Response from POST /sessions."""
+
+    def __init__(
+        self,
+        session_id: str,
+        status: str,
+        proxy_config: Optional[dict] = None,
+        **kwargs: Any,
+    ):
+        self.session_id = session_id
+        self.status = status
+        self.proxy_config = proxy_config or {}
+        self.extra = kwargs

nexalayer-0.1.0/python/nexalayer.egg-info/PKG-INFO

@@ -0,0 +1,211 @@
+Metadata-Version: 2.4
+Name: nexalayer
+Version: 0.1.0
+Summary: NexaLayer SDK — The Network Execution Layer for AI Agents
+Author: NexaLayer
+License-Expression: MIT
+Project-URL: Documentation, https://docs.nexalayer.net
+Project-URL: Repository, https://github.com/NexaLayer/nexalayer-sdk
+Project-URL: Issues, https://github.com/NexaLayer/nexalayer-sdk/issues
+Keywords: proxy,agent,session,nexalayer
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.28
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: pytest-cov>=4; extra == "dev"
+Dynamic: license-file
+
+# NexaLayer SDK
+
+Managed network sessions for Playwright, Browser Use, AI agents, and automation scripts.
+
+**Keep using proxies. Stop managing them.**  
+中文：代理继续使用，代理管理交给 NexaLayer。
+
+This repository contains the Python and Node/TypeScript SDK source. Release automation publishes signed release artifacts to PyPI and npm after registry ownership and secrets are configured.
+
+## Status
+
+| Runtime | Source | Package registry status |
+| --- | --- | --- |
+| Python | `python/` | Package name `nexalayer`; release workflow configured |
+| Node / TypeScript | `node/` | Package name `@nexalayer/sdk`; release workflow configured |
+
+## Installation
+
+Python from repository root:
+
+```bash
+python3 -m venv .venv
+. .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+Node from repository root:
+
+```bash
+cd node
+npm install
+npm run build
+```
+
+## Authentication
+
+```bash
+export NEXALAYER_BASE_URL=https://api.nexalayer.net/v1
+export NEXALAYER_API_KEY=agk_your_key
+```
+
+The SDK uses `X-API-Key` for Agent requests.
+
+## 60-second Python example
+
+This example auto-selects a dynamic product, creates a session, reports telemetry, reads health, and terminates the session in cleanup.
+
+```python
+import os
+import time
+import uuid
+
+import requests
+from nexalayer import NexaLayerClient
+
+api_key = os.environ["NEXALAYER_API_KEY"]
+client = NexaLayerClient(api_key=api_key)
+session_id = None
+
+def data(resp):
+    return resp.get("data", resp)
+
+try:
+    products = data(client.get_products(type="dynamic"))
+    product = next(p for p in products.get("items", []) if p.get("product_no"))
+
+    session = client.create_session(
+        session_type="dynamic",
+        product_no=product["product_no"],
+        quantity=1,
+        protocol="socks5",
+        rotation_mode="on_demand",
+        idempotency_key=f"py-{uuid.uuid4()}",
+    )
+    session_id = session.session_id
+
+    for _ in range(60):
+        current = data(client.get_session(session_id))
+        if current.get("status") == "active":
+            proxy_url = current["proxy"]["full_url"]
+            break
+        time.sleep(2)
+    else:
+        raise TimeoutError("Session did not become active")
+
+    res = requests.get(
+        "https://httpbin.org/ip",
+        proxies={"http": proxy_url, "https": proxy_url},
+        timeout=30,
+    )
+    client.report_event(
+        session_id,
+        event_type="success" if res.ok else "http_error",
+        status_code=res.status_code,
+        target_host="httpbin.org",
+    )
+    print(client.get_session_health(session_id))
+finally:
+    if session_id:
+        client.terminate_session(session_id)
+```
+
+## Dynamic Session
+
+Use a dynamic session when your automation can rotate after errors such as timeout, 403, 429, or explicit blocks.
+
+```python
+session = client.create_session(
+    session_type="dynamic",
+    product_no="selected_from_products_api",
+    quantity=1,
+    protocol="socks5",
+    rotation_mode="on_demand",
+)
+```
+
+## Static Session
+
+Use a static session when you need fixed network identity for a longer-lived task.
+
+```python
+session = client.create_session(
+    session_type="static",
+    product_no="selected_from_products_api",
+    quantity=1,
+    duration=30,
+    protocol="socks5",
+)
+```
+
+## Telemetry
+
+```python
+client.report_event(
+    session_id,
+    event_type="timeout",
+    status_code=0,
+    target_host="example.com",
+)
+```
+
+## Health
+
+```python
+health = client.get_session_health(session_id)
+```
+
+`timeout`, `captcha`, `block`, and repeated HTTP errors are not neutral noise; report them so NexaLayer can score the session and recommend rotate or pause.
+
+## Cleanup
+
+Always terminate sessions you no longer need:
+
+```python
+try:
+    ...
+finally:
+    if session_id:
+        client.terminate_session(session_id)
+```
+
+## Playwright
+
+Use the public Playwright examples:
+
+- Chinese: https://github.com/NexaLayer/nexalayer-examples/tree/main/playwright/basic-session
+- English: https://github.com/NexaLayer/nexalayer-examples/tree/main/playwright/basic-session
+
+## 中文文档
+
+- 中文快速开始: https://docs.nexalayer.net/zh/quick-start
+- Playwright 中文 Demo: https://docs.nexalayer.net/zh/examples
+- API 文档: https://docs.nexalayer.net/api-reference/openapi
+
+## Error handling
+
+- Check `backend_ready=true` before creating paid sessions after registration.
+- Use `Idempotency-Key` for create, rotate, renew, and recharge operations.
+- Do not log `proxy.full_url` in production without redaction because it can contain proxy credentials.
+- Respect target website terms and applicable law.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Security
+
+Do not open public issues with API keys, cookies, account passwords, proxy credentials, or target-site secrets. See [SECURITY.md](SECURITY.md).

nexalayer-0.1.0/python/nexalayer.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE
+README.md
+pyproject.toml
+python/nexalayer/__init__.py
+python/nexalayer/client.py
+python/nexalayer/errors.py
+python/nexalayer/session.py
+python/nexalayer/types.py
+python/nexalayer.egg-info/PKG-INFO
+python/nexalayer.egg-info/SOURCES.txt
+python/nexalayer.egg-info/dependency_links.txt
+python/nexalayer.egg-info/requires.txt
+python/nexalayer.egg-info/top_level.txt

nexalayer-0.1.0/python/nexalayer.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

nexalayer-0.1.0/python/nexalayer.egg-info/requires.txt

@@ -0,0 +1,5 @@
+requests>=2.28
+
+[dev]
+pytest>=7
+pytest-cov>=4

nexalayer-0.1.0/python/nexalayer.egg-info/top_level.txt

@@ -0,0 +1 @@
+nexalayer

nexalayer-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+