How its-vrxxdev/zlapi works
Project Type and Purpose
• Type: Open-source Python SDK / library
• Purpose: Provide both synchronous (“simple”) and asynchronous (“Async”) Python interfaces to interact with Zalo’s web endpoints—supporting login via cookies, sending/receiving messages, managing groups, listening for events in real time (WebSocket or polling).
High-Level Components
a. User Application
– Your bot script or application imports zlapi or zlapi.Async/zlapi.simple, instantiates ZaloAPI, registers handlers, then calls .listen().
b. Public API Layer
– zlapi/Async/__init__.py & zlapi/simple/__init__.py
– These expose ZaloAPI classes: one async (uses asyncio + WebSockets), one “simple” (thread-based + requests).
c. Core Client and Session Management
– zlapi/_client.py
– zlapi/_core.py
– Manage HTTP session (cookies, IMEI header), authentication, endpoint URLs.
d. State Management
– zlapi/_state.py + zlapi/Async/_state.py + zlapi/simple/_state.py
– Track tokens, user info, thread info, pending events.
e. Event & Message Parsing
– zlapi/_parse_message.py, zlapi/_message.py, zlapi/_aevents.py
– Convert raw JSON or WebSocket frames into Python Message, EventObject, Mention, MessageStyle, etc.
f. Threads & Concurrency
– zlapi/_threads.py (for “requests” polling)
– Async/_async.py (for event loop + WebSocket)
g. Utilities & Logging
– zlapi/_util.py (HTTP helpers, retry logic)
– zlapi/logging.py (internal logging wrappers)
h. Models & Exceptions
– zlapi/models.py (data classes: ThreadType, EventType)
– zlapi/_exception.py (custom exceptions)
External Services
• Zalo Web Endpoints (HTTP REST + WebSocket)
• Browser Extension (for IMEI & Cookies acquisition) – optional, not part of library code but depicted as external input source.
Data Flows & Interactions
1. Initialization
– User code → instantiates ZaloAPI, passing cookies & IMEI → Core Client sets up session state.
2. Listen / Receive
– For Async: websocket.connect → incoming frames → _parse_message → emit onMessage/onEvent to user handlers.
– For Simple: polling thread calls HTTP endpoints → receives JSON → same pipeline.
3. API Calls (send/modify)
– User calls .sendMessage(), .createGroup(), etc. → Public API → Core Client (_client) → HTTP POST → Zalo.
– Response flows back → State module updates if needed → returns to user.
Architectural Patterns & Principles
• Modular Package Structure: separation between API layer, client logic, state, parsing, and models.
• Strategy for Concurrency: two parallel strategies (asyncio vs thread/polling) under a unified interface pattern.
• Event-Driven: user-provided callbacks are invoked via an internal dispatcher.
• Adapter / Facade: ZaloAPI classes adapt raw HTTP/WebSocket to Pythonic methods.