Add unit tests for FragmentClient methods

- Implement tests for Stars methods: purchase_stars and giveaway_stars, including validation and success scenarios.
- Add tests for Premium methods: purchase_premium and giveaway_premium, covering validation and success cases.
- Create tests for topup_ton functionality, validating input and mocking successful operations.
- Introduce wallet tests to verify get_wallet() functionality, ensuring correct wallet info retrieval.
- Add tests for FragmentClient.call() method, validating API response handling and data merging.
- Implement tests for anonymous number methods, including login codes and session management.
- Create recharge_ads tests for self-service Telegram Ads recharge, validating input and success scenarios.
- Add username search tests for the Fragment marketplace, ensuring correct result parsing and parameter forwarding.
- Implement number search tests for the Fragment marketplace, validating result parsing and parameter handling.
- Create gift search tests for the Fragment gifts marketplace, ensuring correct result parsing and parameter forwarding.
- Add cookie extraction tests for get_cookies_from_browser(), validating successful extraction and error handling.

examples/auctions/search_gifts.py

@@ -11,9 +11,15 @@ import asyncio
 import json
 
 from pyfragment import FragmentClient, GiftsResult
+from pyfragment.utils import get_cookies_from_browser  # noqa: F401
 
 SEED = "word1 word2 ... word24"
 API_KEY = "YOUR_TONAPI_KEY"
+
+# Option A: extract cookies directly from your browser (no manual copy-paste needed)
+# COOKIES = get_cookies_from_browser("chrome")  # or "firefox", "edge", "brave", ...
+
+# Option B: provide cookies manually
 COOKIES = {
     "stel_ssid": "YOUR_STEL_SSID",
     "stel_dt": "YOUR_STEL_DT",

examples/auctions/search_numbers.py

@@ -10,9 +10,15 @@ import asyncio
 import json
 
 from pyfragment import FragmentClient, NumbersResult
+from pyfragment.utils import get_cookies_from_browser  # noqa: F401
 
 SEED = "word1 word2 ... word24"
 API_KEY = "YOUR_TONAPI_KEY"
+
+# Option A: extract cookies directly from your browser (no manual copy-paste needed)
+# COOKIES = get_cookies_from_browser("chrome")  # or "firefox", "edge", "brave", ...
+
+# Option B: provide cookies manually
 COOKIES = {
     "stel_ssid": "YOUR_STEL_SSID",
     "stel_dt": "YOUR_STEL_DT",

examples/auctions/search_usernames.py

@@ -10,9 +10,15 @@ import asyncio
 import json
 
 from pyfragment import FragmentClient, UsernamesResult
+from pyfragment.utils import get_cookies_from_browser  # noqa: F401
 
 SEED = "word1 word2 ... word24"
 API_KEY = "YOUR_TONAPI_KEY"
+
+# Option A: extract cookies directly from your browser (no manual copy-paste needed)
+# COOKIES = get_cookies_from_browser("chrome")  # or "firefox", "edge", "brave", ...
+
+# Option B: provide cookies manually
 COOKIES = {
     "stel_ssid": "YOUR_STEL_SSID",
     "stel_dt": "YOUR_STEL_DT",

examples/client/raw_api_call.py

@@ -12,9 +12,15 @@ Defaults to the Fragment base URL.
 import asyncio
 
 from pyfragment import FragmentClient
+from pyfragment.utils import get_cookies_from_browser  # noqa: F401
 
 SEED = "word1 word2 ... word24"
 API_KEY = "YOUR_TONAPI_KEY"
+
+# Option A: extract cookies directly from your browser (no manual copy-paste needed)
+# COOKIES = get_cookies_from_browser("chrome")  # or "firefox", "edge", "brave", ...
+
+# Option B: provide cookies manually
 COOKIES = {
     "stel_ssid": "YOUR_STEL_SSID",
     "stel_dt": "YOUR_STEL_DT",

examples/client/wallet_info.py

@@ -8,9 +8,15 @@ wallet_version defaults to "V5R1" — change to "V4R2" for older wallets.
 import asyncio
 
 from pyfragment import FragmentClient
+from pyfragment.utils import get_cookies_from_browser  # noqa: F401
 
 SEED = "word1 word2 ... word24"
 API_KEY = "YOUR_TONAPI_KEY"
+
+# Option A: extract cookies directly from your browser (no manual copy-paste needed)
+# COOKIES = get_cookies_from_browser("chrome")  # or "firefox", "edge", "brave", ...
+
+# Option B: provide cookies manually
 COOKIES = {
     "stel_ssid": "YOUR_STEL_SSID",
     "stel_dt": "YOUR_STEL_DT",

examples/numbers/manage_number.py

@@ -9,9 +9,15 @@ Use terminate_sessions() to forcefully end all active Telegram sessions.
 import asyncio
 
 from pyfragment import AnonymousNumberError, FragmentClient
+from pyfragment.utils import get_cookies_from_browser  # noqa: F401
 
 SEED = "word1 word2 ... word24"
 API_KEY = "YOUR_TONAPI_KEY"
+
+# Option A: extract cookies directly from your browser (no manual copy-paste needed)
+# COOKIES = get_cookies_from_browser("chrome")  # or "firefox", "edge", "brave", ...
+
+# Option B: provide cookies manually
 COOKIES = {
     "stel_ssid": "YOUR_STEL_SSID",
     "stel_dt": "YOUR_STEL_DT",

examples/purchase/recharge_ads_balance.py

@@ -13,9 +13,15 @@ from pyfragment import (
     FragmentClient,
     WalletError,
 )
+from pyfragment.utils import get_cookies_from_browser  # noqa: F401
 
 SEED = "word1 word2 ... word24"
 API_KEY = "YOUR_TONAPI_KEY"
+
+# Option A: extract cookies directly from your browser (no manual copy-paste needed)
+# COOKIES = get_cookies_from_browser("chrome")  # or "firefox", "edge", "brave", ...
+
+# Option B: provide cookies manually
 COOKIES = {
     "stel_ssid": "YOUR_STEL_SSID",
     "stel_dt": "YOUR_STEL_DT",

examples/purchase/run_premium_giveaway.py

@@ -8,9 +8,15 @@ months (Premium duration per winner) must be 3, 6, or 12.
 import asyncio
 
 from pyfragment import ConfigurationError, FragmentClient, UserNotFoundError
+from pyfragment.utils import get_cookies_from_browser  # noqa: F401
 
 SEED = "word1 word2 ... word24"
 API_KEY = "YOUR_TONAPI_KEY"
+
+# Option A: extract cookies directly from your browser (no manual copy-paste needed)
+# COOKIES = get_cookies_from_browser("chrome")  # or "firefox", "edge", "brave", ...
+
+# Option B: provide cookies manually
 COOKIES = {
     "stel_ssid": "YOUR_STEL_SSID",
     "stel_dt": "YOUR_STEL_DT",

examples/purchase/run_stars_giveaway.py

@@ -8,9 +8,15 @@ amount (stars per winner) must be an integer between 500 and 1 000 000.
 import asyncio
 
 from pyfragment import ConfigurationError, FragmentClient, UserNotFoundError
+from pyfragment.utils import get_cookies_from_browser  # noqa: F401
 
 SEED = "word1 word2 ... word24"
 API_KEY = "YOUR_TONAPI_KEY"
+
+# Option A: extract cookies directly from your browser (no manual copy-paste needed)
+# COOKIES = get_cookies_from_browser("chrome")  # or "firefox", "edge", "brave", ...
+
+# Option B: provide cookies manually
 COOKIES = {
     "stel_ssid": "YOUR_STEL_SSID",
     "stel_dt": "YOUR_STEL_DT",

examples/purchase/send_premium.py

@@ -8,9 +8,15 @@ Set show_sender=False to send anonymously.
 import asyncio
 
 from pyfragment import ConfigurationError, FragmentClient, UserNotFoundError
+from pyfragment.utils import get_cookies_from_browser  # noqa: F401
 
 SEED = "word1 word2 ... word24"
 API_KEY = "YOUR_TONAPI_KEY"
+
+# Option A: extract cookies directly from your browser (no manual copy-paste needed)
+# COOKIES = get_cookies_from_browser("chrome")  # or "firefox", "edge", "brave", ...
+
+# Option B: provide cookies manually
 COOKIES = {
     "stel_ssid": "YOUR_STEL_SSID",
     "stel_dt": "YOUR_STEL_DT",

examples/purchase/send_stars.py

@@ -8,9 +8,15 @@ Set show_sender=False to send anonymously.
 import asyncio
 
 from pyfragment import ConfigurationError, FragmentClient, UserNotFoundError
+from pyfragment.utils import get_cookies_from_browser  # noqa: F401
 
 SEED = "word1 word2 ... word24"
 API_KEY = "YOUR_TONAPI_KEY"
+
+# Option A: extract cookies directly from your browser (no manual copy-paste needed)
+# COOKIES = get_cookies_from_browser("chrome")  # or "firefox", "edge", "brave", ...
+
+# Option B: provide cookies manually
 COOKIES = {
     "stel_ssid": "YOUR_STEL_SSID",
     "stel_dt": "YOUR_STEL_DT",

examples/purchase/topup_ton_balance.py

@@ -1,10 +1,10 @@
 """
-Example: Topup ton to recipient's Telegram balance.
+Example: top up TON to a recipient's Telegram balance.
 
-For adding TON to  Telegram Ads account, use recharge_ads() instead.
+For adding TON to a Telegram Ads account, use recharge_ads() instead.
 
 Amount must be an integer between 1 and 1 000 000 000 TON.
-Your wallet must hold at least the topup amount + ~0.056 TON for gas.
+Your wallet must hold at least the top-up amount + ~0.056 TON for gas.
 """
 
 import asyncio
@@ -15,9 +15,15 @@ from pyfragment import (
     UserNotFoundError,
     WalletError,
 )
+from pyfragment.utils import get_cookies_from_browser  # noqa: F401
 
 SEED = "word1 word2 ... word24"
 API_KEY = "YOUR_TONAPI_KEY"
+
+# Option A: extract cookies directly from your browser (no manual copy-paste needed)
+# COOKIES = get_cookies_from_browser("chrome")  # or "firefox", "edge", "brave", ...
+
+# Option B: provide cookies manually
 COOKIES = {
     "stel_ssid": "YOUR_STEL_SSID",
     "stel_dt": "YOUR_STEL_DT",

pyfragment/__init__.py

@@ -34,14 +34,12 @@ from pyfragment.types import (
     WalletError,
     WalletInfo,
 )
-from pyfragment.utils.cookies import get_cookies_from_browser
 
 __version__: str = version("pyfragment")
 
 __all__ = [
     "__version__",
     "FragmentClient",
-    "get_cookies_from_browser",
     "AdsRechargeResult",
     "AdsTopupResult",
     "GiftsResult",

pyfragment/client.py

@@ -123,7 +123,7 @@ class FragmentClient:
         return f"FragmentClient(wallet_version='{self.wallet_version}', cookies={len(self.cookies)} keys)"
 
     async def purchase_premium(self, username: str, months: int, show_sender: bool = True) -> PremiumResult:
-        """Purchase Telegram Premium for a user.
+        """Gift Telegram Premium to a user.
 
         Args:
             username: Recipient's Telegram username (with or without ``@``).
@@ -136,7 +136,7 @@ class FragmentClient:
         return await purchase_premium(self, username, months, show_sender)
 
     async def purchase_stars(self, username: str, amount: int, show_sender: bool = True) -> StarsResult:
-        """Purchase Telegram Stars for a user.
+        """Send Telegram Stars to a user.
 
         Args:
             username: Recipient's Telegram username (with or without ``@``).
@@ -149,7 +149,7 @@ class FragmentClient:
         return await purchase_stars(self, username, amount, show_sender)
 
     async def topup_ton(self, username: str, amount: int, show_sender: bool = True) -> AdsTopupResult:
-        """Topup ton to recipient's Telegram balance.
+        """Top up TON to a recipient's Telegram balance.
 
         Args:
             username: Recipient's Telegram username (with or without ``@``).

pyfragment/methods/topup_ton.py

@@ -18,7 +18,7 @@ if TYPE_CHECKING:
 
 
 async def topup_ton(client: "FragmentClient", username: str, amount: int, show_sender: bool = True) -> AdsTopupResult:
-    """Topup ton to recipient's Telegram balance.
+    """Top up TON to a recipient's Telegram balance.
 
     Args:
         client: Authenticated :class:`FragmentClient` instance.
@@ -31,7 +31,7 @@ async def topup_ton(client: "FragmentClient", username: str, amount: int, show_s
 
     Raises:
         ConfigurationError: If ``amount`` is not an integer between 1 and 1 000 000 000.
-        UserNotFoundError: If the recipient is not found on Fragment.
+        UserNotFoundError: If the recipient is not found on Telegram.
         FragmentAPIError: If the Fragment API returns an error.
         UnexpectedError: For any other unexpected failure.
     """

tests/003_test_hash.py

@@ -1,18 +0,0 @@
-"""Tests for get_fragment_hash() — API hash extraction from Fragment page source."""
-
-import re
-
-import pytest
-
-from pyfragment.types.constants import BASE_HEADERS, STARS_PAGE
-from pyfragment.utils import get_fragment_hash
-
-# Hash integration tests
-
-
-@pytest.mark.asyncio
-async def test_hash_is_valid_hex(cookies: dict) -> None:
-    result = await get_fragment_hash(cookies, BASE_HEADERS, STARS_PAGE)
-    assert isinstance(result, str)
-    assert len(result) >= 10, f"hash too short: {result!r}"
-    assert re.fullmatch(r"[a-f0-9]+", result), f"not a hex string: {result!r}"

tests/014_test_cookies.py

@@ -4,9 +4,9 @@ from unittest.mock import MagicMock, patch
 
 import pytest
 
-from pyfragment import get_cookies_from_browser
 from pyfragment.types import CookieError
 from pyfragment.types.constants import REQUIRED_COOKIE_KEYS
+from pyfragment.utils import get_cookies_from_browser
 
 FAKE_JAR = [
     {"name": "stel_ssid", "value": "abc123", "domain": "fragment.com"},