Add wallet event stream, preimage and serviceFee fields

- Add events.stream() for real-time wallet-level SSE events (sync + async)
- Add preimage field to InvoiceResponse and PaymentResponse
- Add service_fee field to PaymentResponse
- Add WalletEvent, WalletEventType types
- Bump version to 0.4.0

Made-with: Cursor

Author: realbub

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "lnbot"
-version = "0.3.0"
+version = "0.4.0"
 description = "Official Python SDK for LnBot — Bitcoin for AI Agents. Send and receive sats over Lightning with a few lines of code."
 readme = "README.md"
 license = "MIT"

src/lnbot/__init__.py

@@ -27,6 +27,8 @@
     PaymentEvent,
     PaymentResponse,
     PaymentStatus,
+    WalletEvent,
+    WalletEventType,
     RecoveryBackupResponse,
     RecoveryRestoreResponse,
     RestorePasskeyBeginResponse,
@@ -60,6 +62,8 @@
     "PaymentResponse",
     "PaymentStatus",
     "PaymentEvent",
+    "WalletEvent",
+    "WalletEventType",
     "AddressResponse",
     "TransferAddressResponse",
     "TransactionResponse",

src/lnbot/client.py

@@ -28,6 +28,7 @@
     InvoiceResponse,
     PaymentEvent,
     PaymentResponse,
+    WalletEvent,
     RecoveryBackupResponse,
     RecoveryRestoreResponse,
     RestorePasskeyBeginResponse,
@@ -269,6 +270,34 @@ def delete(self, webhook_id: str) -> None:
         self._c._delete(f"/v1/webhooks/{webhook_id}")
 
 
+class EventsResource:
+    """Real-time wallet event stream."""
+
+    def __init__(self, client: LnBot) -> None:
+        self._c = client
+
+    def stream(self) -> Iterator[WalletEvent]:
+        """Stream all wallet events via SSE."""
+        headers = {"Accept": "text/event-stream", "User-Agent": _USER_AGENT}
+        if self._c._api_key:
+            headers["Authorization"] = f"Bearer {self._c._api_key}"
+        with self._c._http.stream("GET", f"{self._c._base_url}/v1/events", headers=headers) as resp:
+            _raise_for_status(resp)
+            for line in resp.iter_lines():
+                if line.startswith("data:"):
+                    raw = line[5:].strip()
+                    if raw:
+                        try:
+                            data = json.loads(raw)
+                            yield WalletEvent(
+                                event=data.get("event", ""),
+                                created_at=data.get("createdAt", ""),
+                                data=data.get("data", {}),
+                            )
+                        except (json.JSONDecodeError, TypeError):
+                            pass
+
+
 class BackupResource:
     """Wallet backup via recovery passphrase or passkey."""
 
@@ -337,6 +366,7 @@ def __init__(
         self.addresses = AddressesResource(self)
         self.transactions = TransactionsResource(self)
         self.webhooks = WebhooksResource(self)
+        self.events = EventsResource(self)
         self.backup = BackupResource(self)
         self.restore = RestoreResource(self)
 
@@ -561,6 +591,34 @@ async def delete(self, webhook_id: str) -> None:
         await self._c._delete(f"/v1/webhooks/{webhook_id}")
 
 
+class AsyncEventsResource:
+    """Real-time wallet event stream (async)."""
+
+    def __init__(self, client: AsyncLnBot) -> None:
+        self._c = client
+
+    async def stream(self) -> AsyncIterator[WalletEvent]:
+        """Stream all wallet events via SSE."""
+        headers = {"Accept": "text/event-stream", "User-Agent": _USER_AGENT}
+        if self._c._api_key:
+            headers["Authorization"] = f"Bearer {self._c._api_key}"
+        async with self._c._http.stream("GET", f"{self._c._base_url}/v1/events", headers=headers) as resp:
+            _raise_for_status(resp)
+            async for line in resp.aiter_lines():
+                if line.startswith("data:"):
+                    raw = line[5:].strip()
+                    if raw:
+                        try:
+                            data = json.loads(raw)
+                            yield WalletEvent(
+                                event=data.get("event", ""),
+                                created_at=data.get("createdAt", ""),
+                                data=data.get("data", {}),
+                            )
+                        except (json.JSONDecodeError, TypeError):
+                            pass
+
+
 class AsyncBackupResource:
     """Wallet backup via recovery passphrase or passkey (async)."""
 
@@ -629,6 +687,7 @@ def __init__(
         self.addresses = AsyncAddressesResource(self)
         self.transactions = AsyncTransactionsResource(self)
         self.webhooks = AsyncWebhooksResource(self)
+        self.events = AsyncEventsResource(self)
         self.backup = AsyncBackupResource(self)
         self.restore = AsyncRestoreResource(self)
 

src/lnbot/types.py

@@ -65,6 +65,7 @@ class InvoiceResponse:
     bolt11: str
     reference: str | None = None
     memo: str | None = None
+    preimage: str | None = None
     tx_number: int | None = None
     created_at: str | None = None
     settled_at: str | None = None
@@ -92,9 +93,11 @@ class PaymentResponse:
     status: PaymentStatus
     amount: int
     max_fee: int
+    service_fee: int
     address: str
     actual_fee: int | None = None
     reference: str | None = None
+    preimage: str | None = None
     tx_number: int | None = None
     failure_reason: str | None = None
     created_at: str | None = None
@@ -211,6 +214,22 @@ class PaymentEvent:
     data: PaymentResponse
 
 
+WalletEventType = Literal[
+    "invoice.created",
+    "invoice.settled",
+    "payment.created",
+    "payment.settled",
+    "payment.failed",
+]
+
+
+@dataclass(frozen=True)
+class WalletEvent:
+    event: WalletEventType
+    created_at: str
+    data: dict[str, Any]
+
+
 # ---------------------------------------------------------------------------
 # JSON key mapping (snake_case <-> camelCase)
 # ---------------------------------------------------------------------------