EthioConnect Swift SDK

Native iOS SDK for the EthioConnect platform. Built with Swift concurrency (async/await), the SDK orchestrates REST API access, WebSocket signaling, LiveKit media, and QoS telemetry into a unified RoomHandle interface.

Requirements

• iOS 16+ / macOS 13+
• Swift 5.9+
• Xcode 15+

Installation

Swift Package Manager

Add the dependency to your Package.swift:

dependencies: [
    .package(url: "https://github.com/comm-baas/commbaas-swift.git", from: "0.1.0"),
]

Or add it via Xcode: File > Add Package Dependencies, then enter the repository URL.

The SDK depends on livekit/client-sdk-swift (v2.0+) which is resolved automatically.

Quick Start

Initialize the client

import CommBaaS

let client = CommBaasClient(
    baseURL: "https://api.comm-baas.example.com/v1",
    tokenProvider: { await myAuthService.getAccessToken() }
)

Join a room

let room = try await client.joinRoom(roomId: "room-uuid")

The joinRoom method orchestrates the full flow:

1. POST /rooms/{id}/join to obtain tokens
2. Opens the signaling WebSocket and waits for the hello handshake
3. Connects the LiveKit media session
4. Starts QoS telemetry (unless disabled)
5. Returns a RoomHandle

Listen for events

for await event in room.events {
    switch event {
    case .participantJoined(let p):
        print("\(p.displayName) joined")
    case .participantLeft(let p):
        print("\(p.displayName) left")
    case .disconnected:
        print("Disconnected from room")
    default:
        break
    }
}

Leave the room

await room.leave()

Architecture

The SDK is organized into four layers:

Layer	Directory	Responsibility
HTTP	Http/	Authenticated REST client with retry and error mapping.
Signaling	Signaling/	WebSocket connection with session resume and heartbeat.
Media	Media/	LiveKit Room wrapper and QoS telemetry reporter.
Orchestration	Orchestration/	CommBaasClient and RoomHandle that ties everything together.

Key Types

Type	Description
CommBaasClient	Top-level entry point. Provides joinRoom() and direct HTTP access via getHttpClient().
RoomHandle	Room-scoped handle exposing an AsyncSequence of events and moderation actions.
SignalingConnection	WebSocket signaling with auto-reconnect and session resume.
RoomSession	LiveKit media session wrapper.
QoSReporter	Periodic QoS telemetry reporter.
HttpClient	Authenticated HTTP client with exponential backoff retry.
CommBaasError	Typed error hierarchy mirroring the server error codes.

Configuration

The CommBaasClient initializer accepts:

Parameter	Type	Description
baseURL	String	Base URL of the API (no trailing slash).
tokenProvider	@Sendable () async throws -> String	Async closure returning the current bearer token.

Join Options

let room = try await client.joinRoom(
    roomId: "room-uuid",
    options: JoinOptions(audio: true, telemetry: true)
)

Option	Type	Default	Description
audio	Bool	true	Whether to enable the microphone on join.
telemetry	Bool	true	Whether to start QoS telemetry reporting.

Error Handling

All errors are represented as CommBaasError:

do {
    let room = try await client.joinRoom(roomId: "room-uuid")
} catch let error as CommBaasError {
    switch error {
    case .authentication:
        // Token expired — refresh and retry
    case .notFound:
        // Room does not exist
    case .network(let underlying):
        // Network failure
    default:
        break
    }
}

Related

• ADR 0017 -- Mobile SDK Architecture
• Client SDK (JavaScript) — Browser equivalent