Python-3xui 0.0.13__tar.gz → 0.1.3__tar.gz

python_3xui-0.1.3/PKG-INFO

@@ -0,0 +1,84 @@
+Metadata-Version: 2.4
+Name: Python-3xui
+Version: 0.1.3
+Summary: 3x-ui wrapper for python
+Project-URL: Homepage, https://github.com/Artem-Potapov/3x-py
+Project-URL: Issues, https://github.com/Artem-Potapov/3x-py/issues
+Author-email: JustMe_001 <justme001.causation755@passinbox.com>
+License-Expression: Apache-2.0
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.11
+Requires-Dist: async-lru~=2.3.0
+Requires-Dist: cachetools~=7.1.1
+Requires-Dist: httpx~=0.28.1
+Requires-Dist: pybase62~=1.0.0
+Requires-Dist: pydantic<3,~=2.12.5
+Requires-Dist: pyotp~=2.9.0
+Requires-Dist: python-dotenv==1.2.2
+Provides-Extra: testing
+Requires-Dist: pytest; extra == 'testing'
+Requires-Dist: pytest-asyncio; extra == 'testing'
+Requires-Dist: pytest-dependency; extra == 'testing'
+Requires-Dist: requests; extra == 'testing'
+Description-Content-Type: text/markdown
+
+<h1>Hi! This is my example python 3x-ui wrapper!</h1>
+<p>I'm not expecting much to be honest, so please feel free to fork it if I abandon the project and you need it!</p>
+<p>Also, if you REALLY want it I can give you the ownership if I step down, you can find my email in the pyproject.toml (I don't check it that much but trust me I do)</p>
+
+<h2>0.1.3 Release Notes</h2>
+Adds Hysteria2 support for inbounds and client provisioning.
+
+<h3>New: Hysteria2 support</h3>
+
+- `Inbound.protocol` now accepts `"hysteria"` alongside `"vless"` and `"vmess"`.
+- `SingleInboundClient` gains an `auth` field (the Hysteria2 secret). A new `model_validator`, `ensure_auth_or_id_present`, requires either `auth` (Hysteria2) or `uuid` (everything else). `uuid` now defaults to `""`, and both fields are dropped from the serialized payload when empty.
+- `create_and_add_prod_client` detects `hysteria` inbounds and emits a random per-client `auth` instead of the deterministic Telegram-ID-derived UUID it uses for VLESS/VMess.
+
+<h3>Misc</h3>
+
+- New `trust_env` constructor kwarg, forwarded to `httpx.AsyncClient`. Defaults to `True`; set `False` to make httpx ignore the environment's proxy/SSL config — handy behind a socks4 proxy httpx can't use.
+
+<h2>0.1.1r1 Release Notes</h2>
+First "middle" version. Brings 3X-UI 3.0.0+ panel support and a client-side workaround for the panel's new duplicate-email behavior.
+
+<h3>New: 3.0.0+ panel auth</h3>
+
+Three new `XUIClient` constructor kwargs:
+
+- `use_new_schema=True` — switches `login()` to the 3.0.0+ flow. Required for any 3.0.0+ panel.
+- `bearer_token=...` — long-lived API token from the panel. Required when `use_new_schema=True`; wrapped in `SecretStr` internally and sent as `Authorization: Bearer <...>` on every request.
+- `force_login=True` — additive on top of bearer. Coins a CSRF token (`/csrf-token`) and runs the cookie-login on top, for routes that still need it.
+
+`SessionCore.login()` becomes a 3-branch dispatcher; the existing 2.X.X cookie-only flow is unchanged when `use_new_schema=False`.
+
+Three new exceptions, all re-exported via `python_3xui.exceptions`:
+
+- `SchemaMismatchError` — constructor-time. `use_new_schema=True` with no `bearer_token`.
+- `InvalidBearerTokenError` — runtime. A 404 in pure-bearer mode would otherwise loop into `login()` re-setting the same (bad) header; the request now fast-fails instead.
+- `CsrfTokenNotCoined` — runtime. `/csrf-token` didn't return a usable `obj`; the panel is almost certainly down.
+
+<h3>New: client-side duplicate-email guard</h3>
+
+3X-UI 3.0.0+ silently accepts duplicate client emails on add instead of hard-rejecting them, which broke the `"duplicate email"` response-msg scan that drove `exist_ok` / `replace_if_exist` in `create_and_add_prod_client`. Workaround landed in this release:
+
+- New `guard_duplicate_emails` `XUIClient` kwarg. Defaults to `use_new_schema` (on for 3.0.0+, off for 2.X.X). Pass `True`/`False` to force.
+- New `guard_duplicates` per-call override on `create_and_add_prod_client`.
+- When active, the method burst-probes `get_client_with_email` for every production inbound's deterministic `(tgid, inbid)` email before adding. Hits become a `conflicts: dict[int, ClientStats]` map; the panel add is skipped for those inbounds.
+- `exist_ok`, `replace_if_exist`, and raise-on-default all keep their original semantics — the guard just feeds them. `replace_if_exist` even saves a round-trip vs the old path, since the guard already has the existing client's uuid.
+- Return type widens to `dict[int, Response | None]`. `None` appears only with `exist_ok=True` and no `replace_if_exist`, for the inbounds the guard short-circuited.
+
+<h3>Fixes & misc</h3>
+
+- `SchemaMismatchError` message rendered as a tuple instead of formatted; switched the call site to an f-string.
+- `tests/conftest.py` now requires `BEARER` in the env-var precheck; without it the fixture would raise `SchemaMismatchError` at construction instead of skipping cleanly.
+- Stale `FIXME` comment removed from `SessionCore.login`.
+- `cachetools` pin relaxed to `~=7.1.1`.
+- Public exception surface now also exports `CsrfTokenNotCoined`, `SchemaMismatchError`, and `InvalidBearerTokenError` via `python_3xui.exceptions`.
+
+<h2>0.0.12 Release Notes</h2>
+Mainly just bugfixes. Fix email fallback, fix adding clients, add inbound management.

python_3xui-0.1.3/README.md

@@ -0,0 +1,56 @@
+<h1>Hi! This is my example python 3x-ui wrapper!</h1>
+<p>I'm not expecting much to be honest, so please feel free to fork it if I abandon the project and you need it!</p>
+<p>Also, if you REALLY want it I can give you the ownership if I step down, you can find my email in the pyproject.toml (I don't check it that much but trust me I do)</p>
+
+<h2>0.1.3 Release Notes</h2>
+Adds Hysteria2 support for inbounds and client provisioning.
+
+<h3>New: Hysteria2 support</h3>
+
+- `Inbound.protocol` now accepts `"hysteria"` alongside `"vless"` and `"vmess"`.
+- `SingleInboundClient` gains an `auth` field (the Hysteria2 secret). A new `model_validator`, `ensure_auth_or_id_present`, requires either `auth` (Hysteria2) or `uuid` (everything else). `uuid` now defaults to `""`, and both fields are dropped from the serialized payload when empty.
+- `create_and_add_prod_client` detects `hysteria` inbounds and emits a random per-client `auth` instead of the deterministic Telegram-ID-derived UUID it uses for VLESS/VMess.
+
+<h3>Misc</h3>
+
+- New `trust_env` constructor kwarg, forwarded to `httpx.AsyncClient`. Defaults to `True`; set `False` to make httpx ignore the environment's proxy/SSL config — handy behind a socks4 proxy httpx can't use.
+
+<h2>0.1.1r1 Release Notes</h2>
+First "middle" version. Brings 3X-UI 3.0.0+ panel support and a client-side workaround for the panel's new duplicate-email behavior.
+
+<h3>New: 3.0.0+ panel auth</h3>
+
+Three new `XUIClient` constructor kwargs:
+
+- `use_new_schema=True` — switches `login()` to the 3.0.0+ flow. Required for any 3.0.0+ panel.
+- `bearer_token=...` — long-lived API token from the panel. Required when `use_new_schema=True`; wrapped in `SecretStr` internally and sent as `Authorization: Bearer <...>` on every request.
+- `force_login=True` — additive on top of bearer. Coins a CSRF token (`/csrf-token`) and runs the cookie-login on top, for routes that still need it.
+
+`SessionCore.login()` becomes a 3-branch dispatcher; the existing 2.X.X cookie-only flow is unchanged when `use_new_schema=False`.
+
+Three new exceptions, all re-exported via `python_3xui.exceptions`:
+
+- `SchemaMismatchError` — constructor-time. `use_new_schema=True` with no `bearer_token`.
+- `InvalidBearerTokenError` — runtime. A 404 in pure-bearer mode would otherwise loop into `login()` re-setting the same (bad) header; the request now fast-fails instead.
+- `CsrfTokenNotCoined` — runtime. `/csrf-token` didn't return a usable `obj`; the panel is almost certainly down.
+
+<h3>New: client-side duplicate-email guard</h3>
+
+3X-UI 3.0.0+ silently accepts duplicate client emails on add instead of hard-rejecting them, which broke the `"duplicate email"` response-msg scan that drove `exist_ok` / `replace_if_exist` in `create_and_add_prod_client`. Workaround landed in this release:
+
+- New `guard_duplicate_emails` `XUIClient` kwarg. Defaults to `use_new_schema` (on for 3.0.0+, off for 2.X.X). Pass `True`/`False` to force.
+- New `guard_duplicates` per-call override on `create_and_add_prod_client`.
+- When active, the method burst-probes `get_client_with_email` for every production inbound's deterministic `(tgid, inbid)` email before adding. Hits become a `conflicts: dict[int, ClientStats]` map; the panel add is skipped for those inbounds.
+- `exist_ok`, `replace_if_exist`, and raise-on-default all keep their original semantics — the guard just feeds them. `replace_if_exist` even saves a round-trip vs the old path, since the guard already has the existing client's uuid.
+- Return type widens to `dict[int, Response | None]`. `None` appears only with `exist_ok=True` and no `replace_if_exist`, for the inbounds the guard short-circuited.
+
+<h3>Fixes & misc</h3>
+
+- `SchemaMismatchError` message rendered as a tuple instead of formatted; switched the call site to an f-string.
+- `tests/conftest.py` now requires `BEARER` in the env-var precheck; without it the fixture would raise `SchemaMismatchError` at construction instead of skipping cleanly.
+- Stale `FIXME` comment removed from `SessionCore.login`.
+- `cachetools` pin relaxed to `~=7.1.1`.
+- Public exception surface now also exports `CsrfTokenNotCoined`, `SchemaMismatchError`, and `InvalidBearerTokenError` via `python_3xui.exceptions`.
+
+<h2>0.0.12 Release Notes</h2>
+Mainly just bugfixes. Fix email fallback, fix adding clients, add inbound management.

{python_3xui-0.0.13 → python_3xui-0.1.3}/pyproject.toml

@@ -1,13 +1,13 @@
 [project]
 name = "Python-3xui"
-version = "0.0.13"
+version = "0.1.3"
 authors = [
   { name="JustMe_001", email="justme001.causation755@passinbox.com" },
 ]
 description = "3x-ui wrapper for python"
 readme = "README.md"
 
-requires-python = ">=3.12"
+requires-python = ">=3.11"
 classifiers = [
     "Programming Language :: Python :: 3",
     "Operating System :: OS Independent",
@@ -25,7 +25,7 @@ dependencies = [
     "python-dotenv==1.2.2",
     "async_lru ~= 2.3.0",
     "pyotp ~= 2.9.0",
-    "cachetools ~= 7.7.1",
+    "cachetools ~= 7.1.1",
     "pybase62 ~= 1.0.0"
 ]
 

{python_3xui-0.0.13 → python_3xui-0.1.3}/python_3xui/__init__.py

@@ -4,7 +4,7 @@ from .api import XUIClient
 import python_3xui.custom_exceptions as exceptions
 
 __author__ = "JustMe_001"
-__version__ = "0.0.13"
+__version__ = "0.1.3"
 __email__ = ""
 
 

{python_3xui-0.0.13 → python_3xui-0.1.3}/python_3xui/api.py

@@ -49,8 +49,10 @@ class XUIClient:
     def __init__(self, base_website: str, base_port: int, base_path: str,
                  *, username: str | None = None, password: str | None = None,
                  two_fac_code: str | None = None, session_duration: int = 3600,
+                 use_new_schema: bool = False, force_login: bool = False, bearer_token: str|None=None,
+                 guard_duplicate_emails: bool | None = None,
                  custom_prod_string: str = "testing",
-                 max_retries: int = 5, retry_delay: int = 1,
+                 max_retries: int = 5, retry_delay: int = 1, trust_env: bool = True,
                  custom_sub_generator: Callable[[int], str] | Callable[[int], Awaitable[str]] = util.default_sub_from_tgid,
                  custom_uuid_generator: Callable[[int], str] | Callable[[int], Awaitable[str]] = util.get_uuid_from_tgid,
                  panel_id: Any = None
@@ -63,12 +65,24 @@ class XUIClient:
             base_path: The base path for the API (e.g., "/panel").
             username: Username for authentication.
             password: Password for authentication.
-            two_fac_code: TOTP secret for 2FA. Short one-shot codes are
-                accepted for the current login only.
+            two_fac_code: TOTP secret for 2FA. Short one-shot codes will \
+             work for the current login only.
+            use_new_schema: for 3X-UI 3.0.0 and above. Cardinally changes how logging in works.
+            force_login: Because of new schema in 3.0.0+, bearer is prevalent and login() is almost obsolete. \
+             Set to True if you need niche methods that still uses cookie-login. Omit for 2.X.X.
+            bearer_token: the bearer itself. Omit for 3X-UI 2.X.X.
+            guard_duplicate_emails: Client-side check for duplicate client emails
+                before adding (workaround for 3X-UI 3.0.0+ no longer hard-rejecting
+                duplicates). When None (default), resolves to ``use_new_schema``: on
+                for 3.0.0+ panels, off for 2.X.X. Pass True/False to force.
             session_duration: Maximum session duration in seconds. Defaults to 3600.
             custom_prod_string: Regex pattern used to select production inbounds.
             max_retries: Maximum retries for database-lock responses.
             retry_delay: Seconds to wait between database-lock retries.
+            trust_env: Forwarded to ``httpx.AsyncClient``. True (default) lets
+                httpx read proxy/SSL config from the environment (including the OS
+                proxy); set False to ignore it — e.g. behind a socks4 proxy httpx
+                cannot use.
             custom_sub_generator: Sync or async callable that receives a
                 Telegram ID and returns the subscription ID for new clients.
             custom_uuid_generator: Sync or async callable that receives a
@@ -83,8 +97,12 @@ class XUIClient:
             password=password,
             two_fac_code=two_fac_code,
             session_duration=session_duration,
+            use_new_schema=use_new_schema,
+            force_login=force_login,
+            bearer_token=bearer_token,
             max_retries=max_retries,
             retry_delay=retry_delay,
+            trust_env=trust_env,
             panel_id=panel_id,
         )
         self._identity = IdentityResolver(custom_sub_generator, custom_uuid_generator)
@@ -101,11 +119,15 @@ class XUIClient:
         )
         self.PROD_STRING = self._prod_cache.PROD_STRING
         self.get_production_inbounds = self._prod_cache.get
+        _resolved_guard = (
+            use_new_schema if guard_duplicate_emails is None else guard_duplicate_emails
+        )
         self._tg_client_service = TgIDClientService(
             self.clients_end,
             self.inbounds_end,
             self._identity,
             self._prod_cache,
+            guard_duplicate_emails=_resolved_guard,
         )
 
     @property
@@ -367,7 +389,8 @@ class XUIClient:
                                          expiry_time: int = 0,
                                          exist_ok: bool = False,
                                          replace_if_exist: bool = False,
-                                         ) -> dict[int, Response]:
+                                         guard_duplicates: bool | None = None,
+                                         ) -> dict[int, Response | None]:
         """Create and add a production client.
 
         This method creates a new client with the given Telegram ID and
@@ -380,23 +403,29 @@ class XUIClient:
             telegram_id: The Telegram ID of the client.
             additional_remark: An optional additional remark for the client.
             expiry_time: Expiry time in SECONDS as a UNIX timestamp.
-            exist_ok: If True, return API responses even when the panel reports
-                a duplicate email.
-            replace_if_exist: If True, inbounds that respond with
-                "duplicate email" will have their existing client updated
-                (via ``request_update_client``) instead of raising an error.
-                Updates are burst-shot in a second ``asyncio.gather`` for
-                minimal latency.
+            exist_ok: If True, return API responses even when a duplicate is
+                detected. Inbounds where the guard short-circuited the add
+                appear in the result dict with a ``None`` value.
+            replace_if_exist: If True, inbounds with an existing client
+                (either guard-detected or panel-reported) will have that
+                client updated via ``request_update_client`` instead of
+                raising. The guard-detected path skips
+                ``_resolve_update_client`` because the uuid is already known.
+            guard_duplicates: Per-call override for the instance-level
+                ``guard_duplicate_emails`` flag. ``None`` (default) uses the
+                instance default; ``True`` / ``False`` force the guard on
+                or off for this call.
 
         Returns:
-            Dict[int, Response]: A mapping of inbound IDs to API responses.
-            For inbounds where the add succeeded, the response is from the
-            add call. For inbounds where ``replace_if_exist`` replaced a
-            duplicate, the response is from the update call.
+            Dict[int, Response | None]: A mapping of inbound IDs to API
+            responses. ``None`` appears only when the guard short-circuited
+            the add for that inbound and ``replace_if_exist`` did not claim
+            it (reachable only with ``exist_ok=True``).
 
         Raises:
-            ClientEmailAlreadyExistsError: If a duplicate client is reported,
-                ``replace_if_exist`` is False, and ``exist_ok`` is False.
+            ClientEmailAlreadyExistsError: A duplicate was detected (by the
+                guard or by panel response) and neither ``exist_ok`` nor
+                ``replace_if_exist`` covered it.
         """
         return await self._tg_client_service.create_and_add_prod_client(
             telegram_id,
@@ -404,6 +433,7 @@ class XUIClient:
             expiry_time=expiry_time,
             exist_ok=exist_ok,
             replace_if_exist=replace_if_exist,
+            guard_duplicates=guard_duplicates,
         )
 
     async def update_client_by_tgid_only(self, telegram_id: int, prod_only: bool, /, *,
@@ -487,9 +517,10 @@ class XUIClient:
             enable: Whether the client is enabled (optional)
             sub_id: Subscription ID (optional)
             comment: Client comment/note (optional)
-            email: New client email (optional). USE WITH CAUTION BECAUSE THE XUIClient WILL NOT TRACK THE NEW EMAIL.
+            email: New client email (optional). USE WITH CAUTION BECAUSE THE XUIClient WILL **NOT** TRACK THE NEW EMAIL.
             verbose: Enables guardrails.
-            force_resolve_by_email: Whether to enable fetch-thru-email fallback when a client is not found, uses ~3 extra fetches but provides an extra layer of protection.
+            force_resolve_by_email: Whether to enable fetch-thru-email fallback when a client is not found, \
+             uses ~3 extra fetches but provides an extra layer of protection.
         Returns:
             Response from the API
         """

{python_3xui-0.0.13 → python_3xui-0.1.3}/python_3xui/api_core/client_service.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 import asyncio
 import logging
+import random
 from asyncio import Task
 from datetime import datetime, UTC
 from typing import TYPE_CHECKING, List, Literal
@@ -24,18 +25,22 @@ if TYPE_CHECKING:
 class TgIDClientService:
     """Orchestrates TGID-derived flows against panel endpoints."""
 
-    __slots__ = ("_clients", "_inbounds", "_identity", "_prod_cache")
+    __slots__ = ("_clients", "_inbounds", "_identity", "_prod_cache",
+                 "_guard_duplicate_emails")
 
     def __init__(self,
                  clients_endpoint: Clients,
                  inbounds_endpoint: Inbounds,
                  identity: IdentityResolver,
                  prod_cache: ProductionInboundCache,
+                 *,
+                 guard_duplicate_emails: bool = False,
                  ) -> None:
         self._clients = clients_endpoint
         self._inbounds = inbounds_endpoint
         self._identity = identity
         self._prod_cache = prod_cache
+        self._guard_duplicate_emails = guard_duplicate_emails
 
     async def get_client_with_tgid(self, tgid: int, inbound_id: int | None = None) -> list[ClientStats]:
         #FIXME: Implement the fallback described in the docstring (api.py)
@@ -52,19 +57,68 @@ class TgIDClientService:
                                          expiry_time: int = 0,
                                          exist_ok: bool = False,
                                          replace_if_exist: bool = False,
-                                         ) -> dict[int, Response]:
+                                         guard_duplicates: bool | None = None,
+                                         ) -> dict[int, Response | None]:
+        """Create and add a client across every production inbound.
+
+        Phase 0 (when the guard is active) probes each production inbound
+        for the deterministic ``(tgid, inbid)`` email; any hit becomes a
+        recorded conflict. Phase 1 burst-adds only non-conflicting
+        inbounds. Phase 2 (``replace_if_exist``) updates conflicting
+        inbounds in place. Phase 3 (``not exist_ok``) raises on any
+        conflict that was not claimed by Phase 2.
+
+        Args:
+            telegram_id: TG ID used to derive the client uuid and per-inbound email.
+            additional_remark: Optional remark prefix for the client's comment field.
+            expiry_time: UNIX timestamp in seconds. 0 = never expire.
+            exist_ok: When True, swallow duplicate-email conflicts; the result dict
+                will contain ``None`` for inbounds where the guard short-circuited
+                the add.
+            replace_if_exist: When True, conflicting inbounds are updated via
+                ``request_update_client`` using the existing client's uuid.
+            guard_duplicates: Per-call override for the instance-level
+                ``guard_duplicate_emails`` flag. ``None`` (default) uses the
+                instance default.
+
+        Returns:
+            Mapping of inbound id to the Response from the panel.
+            Entries are ``None`` only when the guard short-circuited the
+            add for that inbound and ``replace_if_exist`` did not claim it
+            (only reachable with ``exist_ok=True``).
+
+        Raises:
+            ClientEmailAlreadyExistsError: A duplicate was detected (by the
+                guard or by panel response) and neither ``exist_ok`` nor
+                ``replace_if_exist`` covered it.
+        """
+        guard_active = (
+            guard_duplicates if guard_duplicates is not None
+            else self._guard_duplicate_emails
+        )
+
         production_inbounds: tuple[Inbound, ...] = await self._prod_cache.get()
 
         custom_sub = await self._identity.resolve_sub(telegram_id)
-        uuid = await self._identity.resolve_uuid(telegram_id)
+        base_uuid = await self._identity.resolve_uuid(telegram_id)
 
-        # --- Phase 1: build clients and burst-add them ---
-        _to_exec: list[asyncio.Task[Response]] = []
+        # Build one client template per inbound (used by Phase 1 and Phase 2).
         clients_by_inbound: dict[int, SingleInboundClient] = {}
         for inb in production_inbounds:
             tmp_email = util.generate_email_from_tgid_inbid(telegram_id, inb.id)
-            client = SingleInboundClient(
+            if inb.protocol == "hysteria":
+                # Hysteria2 authenticates with a per-client secret, not a UUID.
+                #randomer = better, plus not to waste resources
+                auth = "".join(random.choices("ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789", k=12))
+                uuid = ""
+            else:
+                # Reset per inbound so a preceding hysteria inbound can't leak
+                # its empty UUID / random auth onto this (non-hysteria) one.
+                auth = ""
+                uuid = base_uuid
+            clients_by_inbound[inb.id] = SingleInboundClient(
                 uuid=uuid,
+                auth=auth, #the empty one gets excluded, so it's fine
                 flow="",
                 email=tmp_email,
                 limit_gb=0,
@@ -73,62 +127,117 @@ class TgIDClientService:
                 comment=f"{additional_remark + ', ' if additional_remark else ''}created at {datetime.now(UTC)}",
                 expiry_time=expiry_time,
             )
-            clients_by_inbound[inb.id] = client
-            _to_exec.append(
-                asyncio.create_task(self._clients.add_client(client, inb.id))
-            )
-
-        raw_results: list[Response] = await asyncio.gather(*_to_exec)
-
-        # Map inbound IDs to their add responses
-        responses: dict[int, Response] = {}
-        for i, inb in enumerate(production_inbounds):
-            responses[inb.id] = raw_results[i]
 
-        # --- Phase 2: replace duplicates when replace_if_exist is set ---
+        # --- Phase 0: guard lookup (parallel email probes) ---
+        conflicts: dict[int, ClientStats] = {}
+        if guard_active:
+            _probe_tasks: list[asyncio.Task[ClientStats | None]] = []
+            _probe_order: list[int] = []
+            for inb in production_inbounds:
+                tmp_email = clients_by_inbound[inb.id].email
+                _probe_tasks.append(asyncio.create_task(
+                    self._detect_email_in_inbound(tmp_email, inb.id)
+                ))
+                _probe_order.append(inb.id)
+            _probe_results: list[ClientStats | None] = await asyncio.gather(*_probe_tasks)
+            for i, inb_id in enumerate(_probe_order):
+                if _probe_results[i] is not None:
+                    conflicts[inb_id] = _probe_results[i]
+
+        # --- Phase 1: burst-add for clean inbounds; seed None for conflicts ---
+        responses: dict[int, Response | None] = {inb_id: None for inb_id in conflicts}
+
+        _add_tasks: list[asyncio.Task[Response]] = []
+        _add_order: list[int] = []
+        for inb in production_inbounds:
+            if inb.id in conflicts:
+                continue
+            _add_tasks.append(asyncio.create_task(
+                self._clients.add_client(clients_by_inbound[inb.id], inb.id)
+            ))
+            _add_order.append(inb.id)
+        if _add_tasks:
+            _add_results: list[Response] = await asyncio.gather(*_add_tasks)
+            for i, inb_id in enumerate(_add_order):
+                responses[inb_id] = _add_results[i]
+
+        # --- Phase 2: replace_if_exist (handles both guard-detected
+        # and panel-reported duplicates) ---
         if replace_if_exist:
-            _update_exec: list[asyncio.Task[Response]] = []
-            # Track which inbound each update task corresponds to via list index
-            update_inbound_ids: list[int] = []
+            _update_tasks: list[asyncio.Task[Response]] = []
+            _update_order: list[int] = []
+
+            # Guard-detected conflicts: stashed stats.uuid is the existing client's uuid.
+            for inb_id, stats in conflicts.items():
+                client = clients_by_inbound[inb_id]
+                _update_tasks.append(asyncio.create_task(
+                    self._clients.request_update_client(
+                        client, inb_id, original_uuid=stats.uuid,
+                    )
+                ))
+                _update_order.append(inb_id)
 
+            # Panel-reported duplicates from Phase 1 (still relevant on 2.X.X or
+            # any future panel that re-enables hard reject).
             for inb_id, resp in list(responses.items()):
+                if inb_id in conflicts:
+                    continue  # already queued above
+                if resp is None:
+                    continue  # only conflict-seeded entries are None at this point
                 json_resp = resp.json()
                 msg = json_resp.get("msg", "")
                 if "duplicate email" in msg.lower():
                     client = clients_by_inbound[inb_id]
-                    _update_exec.append(
-                        asyncio.create_task(
-                            self._clients.request_update_client(
-                                client, inb_id, original_uuid=client.uuid,
-                            )
+                    _update_tasks.append(asyncio.create_task(
+                        self._clients.request_update_client(
+                            client, inb_id, original_uuid=client.uuid,
                         )
-                    )
-                    update_inbound_ids.append(inb_id)
-
-            if _update_exec:
-                update_results: list[Response] = await asyncio.gather(*_update_exec)
-                _search_update_exec: list[Task] = []
-                _search_update_resp: dict[int, Task] = {}
-                for i, inb_id in enumerate(update_inbound_ids):
-                    _resp = update_results[i]
-                    _msg: str = _resp.json()["msg"]
+                    ))
+                    _update_order.append(inb_id)
+
+            if _update_tasks:
+                _update_results: list[Response] = await asyncio.gather(*_update_tasks)
+                _resolve_tasks: list[asyncio.Task[Response]] = []
+                _resolve_order: list[int] = []
+                for i, inb_id in enumerate(_update_order):
+                    _resp = _update_results[i]
+                    if inb_id in conflicts:
+                        # Guard-fed updates carried a valid uuid; no "empty client id" fallback needed.
+                        if not _resp.json().get("success", True):
+                            logging.warning(
+                                "Guard-detected update for inbound %s returned failure: %s",
+                                inb_id, _resp.json().get("msg"),
+                            )
+                        responses[inb_id] = _resp
+                        continue
+                    _msg = _resp.json().get("msg", "")
                     if "empty client id" in _msg.lower():
-                        t = asyncio.create_task(
-                            self._resolve_update_client(telegram_id, inb_id, clients_by_inbound[inb_id])
-                        )
-                        _search_update_exec.append(t)
-                        _search_update_resp[inb_id] = t
+                        _resolve_tasks.append(asyncio.create_task(
+                            self._resolve_update_client(
+                                telegram_id, inb_id, clients_by_inbound[inb_id]
+                            )
+                        ))
+                        _resolve_order.append(inb_id)
                     else:
                         responses[inb_id] = _resp
+                if _resolve_tasks:
+                    _resolve_results: list[Response] = await asyncio.gather(*_resolve_tasks)
+                    for i, inb_id in enumerate(_resolve_order):
+                        responses[inb_id] = _resolve_results[i]
 
-                if _search_update_exec:
-                    await asyncio.gather(*_search_update_exec)
-                    for inb_id, task in _search_update_resp.items():
-                        responses[inb_id] = task.result()
-
-        # --- Phase 3: raise on remaining duplicates if not exist_ok ---
+        # --- Phase 3: raise on unclaimed duplicates if not exist_ok ---
         if not exist_ok:
             for inb_id, resp in responses.items():
+                if resp is None:
+                    # Guard-detected conflict that Phase 2 did not claim.
+                    logging.error(
+                        "Client already exists in inbound %s for tgid %s (guard-detected)",
+                        inb_id, telegram_id,
+                    )
+                    raise ClientEmailAlreadyExistsError(
+                        f"Client already exists in inbound {inb_id} for "
+                        f"telegram_id {telegram_id} (guard-detected)"
+                    )
                 json_resp: dict = resp.json()
                 msg = json_resp.get("msg", "")
                 if "duplicate email" in msg.lower():
@@ -149,6 +258,28 @@ class TgIDClientService:
             inbound_client, inb_id, original_uuid=_found.uuid,
         )
 
+    async def _detect_email_in_inbound(self,
+                                       email: str,
+                                       inbound_id: int,
+                                       ) -> ClientStats | None:
+        """Return the panel's ClientStats record for ``email`` if it lives
+        in ``inbound_id``, else None. Used by the duplicate-email guard
+        before burst-add.
+
+        The returned ``ClientStats`` carries the existing client's
+        ``uuid``, which the guard's ``replace_if_exist`` branch reuses to
+        skip a round-trip through ``_resolve_update_client``.
+
+        Exceptions from ``get_client_with_email`` (network, auth,
+        validation) propagate unchanged.
+        """
+        stats = await self._clients.get_client_with_email(
+            email, raise_if_none=False
+        )
+        if stats is not None and stats.inboundId == inbound_id:
+            return stats
+        return None
+
     async def _find_client_in_inbound(self,
                                       client_uuid: str,
                                       inbound_id: int,