Architecture
This guide explains the architecture of the SDK, including connection lifecycle, request/response flow, and server-pushed event handling.
High-Level Architecture
Core Components
1. IWebExtensionConnection
Purpose: Manages the underlying transport layer.
Responsibilities:
- Establishes and maintains the connection
- Handles reconnection logic (timeout: 2000ms, no auto-reconnect on shutdown)
Used by: Lifecycle management (Connect, Disconnect)
const client = CreateWebExtensionClient();
const { connection } = client;
await connection.Connect();
// ... use SDK ...
await connection.Disconnect(ConnectionReason.Shuttingdown, true);
2. IWebExtensionHub
Purpose: Request/Response interface for server methods
Responsibilities:
- Calls methods synchronously (returning Promises)
- Groups methods by domain (User Info, Presence, Call Control, etc.)
- Sends structured parameters and receives typed responses
Categories:
- User Information: GetLoggedInUser
- Version and Feature Information: GetLanguage
- Phonebook: GetPhonebook
- User Presence: GetUserPresenceList
- Groups: GetUserGroups
- Call Journal: GetCallJournal
- Notification Calls: GetNotificationCalls, PickupNotificationCall
- Call Control: Dial, SendDtmfDigit, HookOff, HookOn, ActivateCall, HoldCall, TransferToLine, TransferToNumber, TransferToVoicebox, GetLineDetails, GetSelectedLine, SetSelectedLine
- Number Conversion: ConvertNumber
- User Avatar: GetAvatarBitmapLink
3. IWebExtensionHubBack
Purpose: Event subscription interface for notifications
Responsibilities:
- Subscribes to and unsubscribes from events
- Invokes callbacks when SwyxIt! sends notifications
- Manages subscription state (allows on/off/offAll patterns)
Event Categories:
- Connection State Changed — onConnectionStateChanged
- Line Selection Changed — onLineSelectionChanged
- Line State Changed — onLineStateChanged
- Number Of Lines Changed — onNumberOfLinesChanged
- Phonebook Reloaded — onPhonebookReloaded
- Line Details Changed — onLineDetailsChanged
- Notification Calls Changed — onNotificationCallsChanged
- Language Changed — onLanguageChanged
- User Presence Changed — onUserPresenceChanged
- Line Key Config Changed — onLineKeyConfigChanged
- User Redial List Changed — onUserRedialListChanged
- User Phone Call List Changed — onUserPhoneCallListChanged
- User Phone Callback List Changed — onUserPhoneCallbackListChanged
Initialization
Use CreateWebExtensionClient to wire all three components automatically.
import { CreateWebExtensionClient } from '@enreachde/swyx-web-extension-sdk';
const client = CreateWebExtensionClient();
const { connection, hub, hubBack } = client;