viberio 1.0.2__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
viberio/__init__.py ADDED
@@ -0,0 +1,24 @@
1
+ """viberio - fast, fully typed, asyncio-native Viber Bot API library."""
2
+ from . import filters as F
3
+ from .bot import Bot, UpdateResult
4
+ from .client import ViberClient
5
+ from .events import (
6
+ ConversationStarted, Delivered, Event, Failed, IncomingMessage, MessageEvent, PaymentButtonClicked, Seen,
7
+ Subscribed, UnknownEvent, Unsubscribed, parse_event,
8
+ )
9
+ from .exceptions import (
10
+ AccountError, APIError, ApiVersionError, AuthError, BadRequestError, BillingError, BroadcastError, ErrorCode,
11
+ RateLimitError, RecipientError, SignatureError, TransportError, ValidationError, ViberError,
12
+ )
13
+ from .messages import (
14
+ Button, Card, ContactMessage, FileMessage, Frame, InternalBrowser, Keyboard, LocationMessage, MapLocation,
15
+ MediaPlayer, Message, Payment, PaymentMessage, PictureMessage, RichMedia, RichMediaMessage, StickerMessage,
16
+ TextMessage, UrlMessage, VideoMessage,
17
+ )
18
+ from .models import (
19
+ AccountInfo, BillingStatus, BroadcastResult, OnlineState, OnlineStatus, SendResult, Sender, User,
20
+ )
21
+ from .server import create_app, run_webhook, serve
22
+
23
+ __version__ = "1.0.1"
24
+ __all__ = [n for n in dir() if not n.startswith("_")]
viberio/_json.py ADDED
@@ -0,0 +1,22 @@
1
+ """Fast JSON helpers (orjson if installed, stdlib otherwise)."""
2
+ from __future__ import annotations
3
+
4
+ from typing import Any
5
+
6
+ try: # pragma: no cover - optional speedup
7
+ import orjson
8
+
9
+ def dumps(obj: Any) -> bytes:
10
+ return orjson.dumps(obj)
11
+
12
+ def loads(data: bytes | str) -> Any:
13
+ return orjson.loads(data)
14
+
15
+ except ImportError: # pragma: no cover
16
+ import json
17
+
18
+ def dumps(obj: Any) -> bytes:
19
+ return json.dumps(obj, ensure_ascii=False, separators=(",", ":")).encode()
20
+
21
+ def loads(data: bytes | str) -> Any:
22
+ return json.loads(data)
viberio/bot.py ADDED
@@ -0,0 +1,269 @@
1
+ """Bot: client + event router + webhook entrypoint."""
2
+ from __future__ import annotations
3
+
4
+ import asyncio
5
+ import inspect
6
+ import logging
7
+ import re
8
+ import time
9
+ from collections import OrderedDict
10
+ from dataclasses import dataclass
11
+ from typing import Any, Awaitable, Callable, Sequence
12
+
13
+ from . import _json
14
+ from .client import ViberClient
15
+ from .events import (
16
+ ConversationStarted, Delivered, Event, Failed, MessageEvent, PaymentButtonClicked, Seen, Subscribed,
17
+ Unsubscribed, UnknownEvent, WebhookVerified, parse_event,
18
+ )
19
+ from .filters import Filter, text as text_filter
20
+ from .messages import Message
21
+ from .models import Sender
22
+
23
+ log = logging.getLogger("viberio")
24
+
25
+ Handler = Callable[[Any], Awaitable[Any]]
26
+ Middleware = Callable[[Event, Callable[[Event], Awaitable[Any]]], Awaitable[Any]]
27
+ ErrorHook = Callable[[Event, BaseException], Awaitable[None] | None]
28
+
29
+
30
+ @dataclass(slots=True)
31
+ class UpdateResult:
32
+ """What your web framework should answer to Viber."""
33
+
34
+ status: int
35
+ body: dict[str, Any] | None = None
36
+ reason: str | None = None # why the update was ignored (for logs/metrics); status is still 200 in always_ok mode
37
+
38
+ def json(self) -> bytes:
39
+ return _json.dumps(self.body if self.body is not None else {"status": 0, "status_message": "ok"})
40
+
41
+
42
+ class _Dedup:
43
+ """TTL + size bounded set, protects against Viber re-sending a callback after a slow answer."""
44
+
45
+ def __init__(self, ttl: float = 600.0, maxsize: int = 20000) -> None:
46
+ self._d: OrderedDict[Any, float] = OrderedDict()
47
+ self.ttl, self.maxsize = ttl, maxsize
48
+
49
+ def seen(self, key: Any) -> bool:
50
+ now = time.monotonic()
51
+ while self._d and (len(self._d) > self.maxsize or now - next(iter(self._d.values())) > self.ttl):
52
+ self._d.popitem(last=False)
53
+ if key in self._d:
54
+ return True
55
+ self._d[key] = now
56
+ return False
57
+
58
+
59
+ class Bot:
60
+ """Viber bot application.
61
+
62
+ >>> bot = Bot(TOKEN, name="My Bot")
63
+ >>> @bot.on_text(regex=r"^hi")
64
+ ... async def hi(ev): await ev.reply("hello!")
65
+ """
66
+
67
+ def __init__(
68
+ self,
69
+ token: str,
70
+ *,
71
+ name: str,
72
+ avatar: str | None = None,
73
+ verify_signatures: bool = True,
74
+ always_ok: bool = True,
75
+ welcome_timeout: float = 4.0,
76
+ client: ViberClient | None = None,
77
+ **client_kwargs: Any,
78
+ ) -> None:
79
+ self.client = client or ViberClient(token, sender_name=name, sender_avatar=avatar, **client_kwargs)
80
+ self.verify_signatures = verify_signatures
81
+ self.always_ok = always_ok
82
+ self.welcome_timeout = welcome_timeout
83
+ self._routes: dict[type[Event], list[tuple[tuple[Filter, ...], Handler, bool]]] = {}
84
+ self._middleware: list[Middleware] = []
85
+ self._tasks: set[asyncio.Task[Any]] = set()
86
+ self._dedup = _Dedup()
87
+ self.on_error: ErrorHook | None = None
88
+
89
+ # -- registration --------------------------------------------------------
90
+ def _register(self, kind: type[Event], filters: Sequence[Filter], block: bool) -> Callable[[Handler], Handler]:
91
+ def deco(fn: Handler) -> Handler:
92
+ if not inspect.iscoroutinefunction(fn):
93
+ raise TypeError(f"handler {fn!r} must be 'async def'")
94
+ self._routes.setdefault(kind, []).append((tuple(filters), fn, block))
95
+ return fn
96
+
97
+ return deco
98
+
99
+ def on_message(self, *filters: Filter, block: bool = True):
100
+ return self._register(MessageEvent, filters, block)
101
+
102
+ def on_text(self, pattern: str | None = None, *, equals: str | None = None, startswith: str | None = None,
103
+ regex: str | None = None, block: bool = True):
104
+ """Shortcut for text messages. A positional ``pattern`` is treated as a regex."""
105
+ return self._register(MessageEvent, [text_filter(equals=equals, startswith=startswith,
106
+ regex=regex or pattern)], block)
107
+
108
+ def on_subscribed(self, *filters: Filter, block: bool = True):
109
+ return self._register(Subscribed, filters, block)
110
+
111
+ def on_unsubscribed(self, *filters: Filter, block: bool = True):
112
+ return self._register(Unsubscribed, filters, block)
113
+
114
+ def on_conversation_started(self, *filters: Filter, block: bool = True):
115
+ """Handler may return a Message -> sent as the welcome message in the HTTP response."""
116
+ return self._register(ConversationStarted, filters, block)
117
+
118
+ def on_delivered(self, *filters: Filter, block: bool = True):
119
+ return self._register(Delivered, filters, block)
120
+
121
+ def on_seen(self, *filters: Filter, block: bool = True):
122
+ return self._register(Seen, filters, block)
123
+
124
+ def on_failed(self, *filters: Filter, block: bool = True):
125
+ return self._register(Failed, filters, block)
126
+
127
+ def on_payment_button(self, *filters: Filter, block: bool = True):
128
+ return self._register(PaymentButtonClicked, filters, block)
129
+
130
+ def middleware(self, fn: Middleware) -> Middleware:
131
+ """``async def mw(event, call_next): ... return await call_next(event)``."""
132
+ self._middleware.append(fn)
133
+ return fn
134
+
135
+ # -- dispatch ------------------------------------------------------------
136
+ @staticmethod
137
+ async def _passes(filters: Sequence[Filter], ev: Event) -> bool:
138
+ for f in filters:
139
+ r = f(ev)
140
+ if inspect.isawaitable(r):
141
+ r = await r
142
+ if not r:
143
+ return False
144
+ if isinstance(r, re.Match):
145
+ ev.match = r
146
+ return True
147
+
148
+ async def _run_handlers(self, ev: Event) -> Any:
149
+ result: Any = None
150
+ for filters, fn, block in self._routes.get(type(ev), ()):
151
+ if await self._passes(filters, ev):
152
+ result = await fn(ev)
153
+ if block:
154
+ break
155
+ return result
156
+
157
+ async def dispatch(self, ev: Event) -> Any:
158
+ """Run middleware + handlers for an already-parsed event."""
159
+ ev.bot = self
160
+ call: Callable[[Event], Awaitable[Any]] = self._run_handlers
161
+ for mw in reversed(self._middleware):
162
+ call = (lambda nxt, m: (lambda e: m(e, nxt)))(call, mw)
163
+ return await call(ev)
164
+
165
+ async def _safe_dispatch(self, ev: Event) -> Any:
166
+ try:
167
+ return await self.dispatch(ev)
168
+ except asyncio.CancelledError:
169
+ raise
170
+ except Exception as e:
171
+ log.exception("handler failed for %s", type(ev).__name__)
172
+ if self.on_error:
173
+ try:
174
+ r = self.on_error(ev, e)
175
+ if inspect.isawaitable(r):
176
+ await r
177
+ except Exception:
178
+ log.exception("on_error hook failed")
179
+ return None
180
+
181
+ def _spawn(self, coro: Awaitable[Any]) -> None:
182
+ t = asyncio.ensure_future(coro)
183
+ self._tasks.add(t)
184
+ t.add_done_callback(self._tasks.discard)
185
+
186
+ # -- webhook entrypoint --------------------------------------------------
187
+ def _reject(self, status: int, reason: str) -> UpdateResult:
188
+ """Rejected input. In ``always_ok`` mode Viber still gets 200 (so it never disables the webhook)."""
189
+ log.warning("webhook update ignored: %s", reason)
190
+ if self.always_ok:
191
+ return UpdateResult(200, None, reason)
192
+ return UpdateResult(status, {"status": 3, "status_message": reason}, reason)
193
+
194
+ async def handle_update(self, body: bytes | str, signature: str | None = None) -> UpdateResult:
195
+ """Framework-agnostic webhook handler. Returns what to answer to Viber.
196
+
197
+ With ``always_ok=True`` (default) the answer is **always HTTP 200**, whatever happens: bad signature,
198
+ malformed JSON, unknown event, handler crash or an internal error. Invalid input is logged and ignored,
199
+ never processed. Regular events are handled in the background so Viber gets its 200 immediately;
200
+ ``conversation_started`` is awaited (bounded by ``welcome_timeout``) to build the welcome message.
201
+ """
202
+ try:
203
+ return await self._handle_update(body, signature)
204
+ except asyncio.CancelledError:
205
+ raise
206
+ except Exception:
207
+ log.exception("unexpected error while handling webhook update")
208
+ if self.always_ok:
209
+ return UpdateResult(200, None, "internal error")
210
+ raise
211
+
212
+ async def _handle_update(self, body: bytes | str, signature: str | None = None) -> UpdateResult:
213
+ """Framework-agnostic webhook handler. Returns what to answer to Viber.
214
+
215
+ Regular events are processed in the background so Viber gets its 200 immediately;
216
+ ``conversation_started`` is awaited (bounded by ``welcome_timeout``) to build the welcome message.
217
+ """
218
+ raw = body.encode() if isinstance(body, str) else body
219
+ if self.verify_signatures and not self.client.verify_signature(raw, signature):
220
+ return self._reject(403, "invalid signature")
221
+ try:
222
+ payload = _json.loads(raw)
223
+ if not isinstance(payload, dict):
224
+ raise ValueError
225
+ except Exception:
226
+ return self._reject(400, "bad json")
227
+
228
+ ev = parse_event(payload)
229
+ if isinstance(ev, MessageEvent) and ev.message_token is not None:
230
+ if self._dedup.seen(("m", ev.message_token, ev.user_id)):
231
+ return UpdateResult(200)
232
+ if isinstance(ev, (WebhookVerified, UnknownEvent)):
233
+ return UpdateResult(200)
234
+
235
+ if isinstance(ev, ConversationStarted):
236
+ try:
237
+ out = await asyncio.wait_for(self._safe_dispatch(ev), self.welcome_timeout)
238
+ except asyncio.TimeoutError:
239
+ log.warning("conversation_started handler exceeded %.1fs", self.welcome_timeout)
240
+ out = None
241
+ if isinstance(out, Message):
242
+ try:
243
+ return UpdateResult(200, self.client.build_payload(out))
244
+ except Exception:
245
+ log.exception("invalid welcome message, answering 200 without it")
246
+ return UpdateResult(200)
247
+ if isinstance(out, dict):
248
+ return UpdateResult(200, out)
249
+ return UpdateResult(200)
250
+
251
+ self._spawn(self._safe_dispatch(ev))
252
+ return UpdateResult(200)
253
+
254
+ async def process(self, payload: dict[str, Any]) -> Any:
255
+ """Dispatch a pre-parsed payload synchronously (handy in tests and queue consumers)."""
256
+ return await self._safe_dispatch(parse_event(payload))
257
+
258
+ # -- lifecycle -----------------------------------------------------------
259
+ async def close(self, *, drain_timeout: float = 10.0) -> None:
260
+ """Wait for in-flight handlers, then close the HTTP session."""
261
+ if self._tasks:
262
+ await asyncio.wait(self._tasks, timeout=drain_timeout)
263
+ await self.client.close()
264
+
265
+ async def __aenter__(self) -> "Bot":
266
+ return self
267
+
268
+ async def __aexit__(self, *exc: Any) -> None:
269
+ await self.close()