Docs: Add async examples and update CHANGELOG for v0.2.0

Author: Chocapikk

CHANGELOG.md

@@ -8,6 +8,16 @@ and this project adheres to
 
 ## [Unreleased]
 
+### Added
+
+- AsyncClient with full async/await support using httpx
+- Simple `search()` API accepting raw query strings
+- `get_domain()` method for domain lookups
+- `get_api_status()` and `is_pro()` methods for account info
+- Streaming `bulk_export_stream()` for memory-efficient exports
+- `serialize_queries()` helper to reduce query serialization duplication
+- Async example in `example/example_async_client.py`
+
 ### Changed
 
 - Updated l9format requirement from =1.3.2 to =1.4.0 ([ae676d9])

example/example_async_client.py

@@ -0,0 +1,38 @@
+import asyncio
+
+import decouple
+
+from leakix import AsyncClient, Scope
+
+API_KEY = decouple.config("API_KEY")
+
+
+async def example_search():
+    """Simple async search using query string syntax."""
+    async with AsyncClient(api_key=API_KEY) as client:
+        response = await client.search("+plugin:GitConfigHttpPlugin", scope=Scope.LEAK)
+        if response.is_success():
+            for event in response.json():
+                print(event.ip, event.host)
+
+
+async def example_get_host():
+    """Async host lookup."""
+    async with AsyncClient(api_key=API_KEY) as client:
+        response = await client.get_host("8.8.8.8")
+        if response.is_success():
+            print("Services:", response.json()["services"])
+            print("Leaks:", response.json()["leaks"])
+
+
+async def example_get_domain():
+    """Async domain lookup."""
+    async with AsyncClient(api_key=API_KEY) as client:
+        response = await client.get_domain("example.com")
+        if response.is_success():
+            print("Services:", response.json()["services"])
+            print("Leaks:", response.json()["leaks"])
+
+
+if __name__ == "__main__":
+    asyncio.run(example_search())

example/example_client.py

@@ -2,7 +2,7 @@
 
 import decouple
 
-from leakix import Client
+from leakix import Client, Scope
 from leakix.field import CountryField, Operator, PluginField, TimeField
 from leakix.plugin import Plugin
 from leakix.query import MustNotQuery, MustQuery, RawQuery
@@ -118,6 +118,36 @@ def example_get_subdomains():
     print(response.json())
 
 
+def example_search_simple():
+    """Simple search using query string syntax (same as the website)."""
+    response = CLIENT.search("+plugin:GitConfigHttpPlugin", scope=Scope.LEAK)
+    for event in response.json():
+        print(event.ip)
+
+
+def example_search_service():
+    """Search for services with multiple filters."""
+    response = CLIENT.search("+country:FR +port:22", scope=Scope.SERVICE)
+    for event in response.json():
+        print(event.ip, event.port)
+
+
+def example_get_domain():
+    """Get services and leaks for a domain."""
+    response = CLIENT.get_domain("example.com")
+    if response.is_success():
+        print("Services:", response.json()["services"])
+        print("Leaks:", response.json()["leaks"])
+
+
+def example_bulk_export_stream():
+    """Streaming bulk export - memory efficient for large datasets."""
+    query = MustQuery(field=PluginField(Plugin.GitConfigHttpPlugin))
+    for aggregation in CLIENT.bulk_export_stream(queries=[query]):
+        for event in aggregation.events:
+            print(event.ip)
+
+
 if __name__ == "__main__":
     example_get_host_filter_plugin()
     example_get_service_filter_plugin()
@@ -131,3 +161,7 @@ def example_get_subdomains():
     example_bulk_service()
     example_bulk_export_last_event()
     example_get_subdomains()
+    example_search_simple()
+    example_search_service()
+    example_get_domain()
+    example_bulk_export_stream()