feat: Add gift and number search functionality to FragmentClient

- Implemented `search_gifts` method for searching gifts in the Fragment marketplace.
- Implemented `search_numbers` method for searching anonymous Telegram numbers.
- Added new example scripts for searching gifts, numbers, and usernames.
- Updated HTML parsing logic to handle gift items and number listings.
- Added unit tests for the new search methods and updated existing tests for usernames and numbers.
- Removed obsolete test file for auction searches.

examples/search_gifts.py

@@ -0,0 +1,43 @@
+"""
+Example: search the Fragment gifts marketplace.
+
+collection filters by gift type slug (e.g. "plushpepe", "swisswatch").
+sort can be "price_desc", "price_asc", "listed", or "ending".
+filter can be "", "auction", "sale", or "sold".
+Use next_offset for pagination.
+"""
+
+import asyncio
+
+from pyfragment import FragmentClient, GiftsResult
+
+SEED = "word1 word2 ... word24"
+API_KEY = "YOUR_TONAPI_KEY"
+COOKIES = {
+    "stel_ssid": "YOUR_STEL_SSID",
+    "stel_dt": "YOUR_STEL_DT",
+    "stel_token": "YOUR_STEL_TOKEN",
+    "stel_ton_token": "YOUR_STEL_TON_TOKEN",
+}
+
+QUERY = ""  # search text — or omit for all
+COLLECTION = "plushpepe"  # gift collection slug — or omit for all
+SORT = "price_desc"  # "price_desc", "price_asc", "listed", "ending" — or omit
+FILTER = ""  # "", "auction", "sale", "sold" — or omit
+
+
+async def main() -> None:
+    async with FragmentClient(seed=SEED, api_key=API_KEY, cookies=COOKIES) as client:
+        result: GiftsResult = await client.search_gifts(QUERY, collection=COLLECTION, sort=SORT, filter=FILTER)
+
+        print(f"Found {len(result.items)} result(s):")
+        for item in result.items:
+            price = f"{item['price']} TON" if item["price"] else "n/a"
+            print(f"  {item['name']:30s}  {item['status'] or '':15s}  {price:12s}  {item['date'] or '—'}")
+
+        if result.next_offset:
+            print(f"\nMore results available — next page offset: {result.next_offset}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/search_numbers.py

@@ -0,0 +1,41 @@
+"""
+Example: search the Fragment marketplace for anonymous Telegram numbers.
+
+sort can be "price_desc", "price_asc", "listed", or "ending".
+filter can be "", "auction", "sale", or "sold".
+Use next_offset_id for pagination.
+"""
+
+import asyncio
+
+from pyfragment import FragmentClient, NumbersResult
+
+SEED = "word1 word2 ... word24"
+API_KEY = "YOUR_TONAPI_KEY"
+COOKIES = {
+    "stel_ssid": "YOUR_STEL_SSID",
+    "stel_dt": "YOUR_STEL_DT",
+    "stel_token": "YOUR_STEL_TOKEN",
+    "stel_ton_token": "YOUR_STEL_TON_TOKEN",
+}
+
+QUERY = "888"  # search term — or omit for all
+SORT = "price_asc"  # "price_desc", "price_asc", "listed", "ending" — or omit
+FILTER = ""  # "", "auction", "sale", "sold" — or omit
+
+
+async def main() -> None:
+    async with FragmentClient(seed=SEED, api_key=API_KEY, cookies=COOKIES) as client:
+        result: NumbersResult = await client.search_numbers(QUERY, sort=SORT, filter=FILTER)
+
+        print(f"Found {len(result.items)} result(s):")
+        for item in result.items:
+            price = f"{item['price']} TON" if item["price"] else "n/a"
+            print(f"  {item['name']:20s}  {item['status'] or '':15s}  {price:10s}  {item['date'] or '—'}")
+
+        if result.next_offset_id:
+            print(f"\nMore results available — next page offset: {result.next_offset_id}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/search_usernames.py

@@ -1,7 +1,6 @@
 """
-Example: search the Fragment marketplace for auction listings.
+Example: search the Fragment marketplace for Telegram usernames.
 
-type can be "usernames", "numbers", or "collectibles".
 sort can be "price_desc", "price_asc", "listed", or "ending".
 filter can be "", "auction", "sale", or "sold".
 Use next_offset_id for pagination.
@@ -9,7 +8,7 @@ Use next_offset_id for pagination.
 
 import asyncio
 
-from pyfragment import AuctionsResult, FragmentClient
+from pyfragment import FragmentClient, UsernamesResult
 
 SEED = "word1 word2 ... word24"
 API_KEY = "YOUR_TONAPI_KEY"
@@ -21,19 +20,18 @@ COOKIES = {
 }
 
 QUERY = "durov"  # search term
-TYPE = "usernames"  # "usernames", "numbers", or "collectibles" — or omit
 SORT = "price_desc"  # "price_desc", "price_asc", "listed", "ending" — or omit
 FILTER = "auction"  # "", "auction", "sale", "sold" — or omit
 
 
 async def main() -> None:
     async with FragmentClient(seed=SEED, api_key=API_KEY, cookies=COOKIES) as client:
-        result: AuctionsResult = await client.search_auctions(QUERY, type=TYPE, sort=SORT, filter=FILTER)
+        result: UsernamesResult = await client.search_usernames(QUERY, sort=SORT, filter=FILTER)
 
         print(f"Found {len(result.items)} result(s):")
         for item in result.items:
             price = f"{item['price']} TON" if item["price"] else "n/a"
-            print(f"  {item['name']:20s}  {item['status'] or '':15s}  {price:10s}  {item['ends_at'] or '—'}")
+            print(f"  {item['name']:20s}  {item['status'] or '':15s}  {price:10s}  {item['date'] or '—'}")
 
         if result.next_offset_id:
             print(f"\nMore results available — next page offset: {result.next_offset_id}")