# Event System

## Purpose and Scope

The Event System is the reactive communication layer that enables bidirectional messaging between the embedded WebView content and native Android code in the Mesh Connect SDK. This system processes JSON messages from JavaScript, converts them into type-safe Kotlin events, and provides real-time feedback to host applications during financial linking workflows.

For information about the underlying WebView communication mechanism, see [WebView Communication](/content/FrontFin/mesh-android-sdk/3.1-webview-communication/index.html). For details about message filtering and broadcasting, see [Message Broadcasting System](/content/FrontFin/mesh-android-sdk/3.2-message-broadcasting-system/index.html).

## System Architecture

The Event System operates as a message processing pipeline that transforms raw JSON messages from the WebView into structured `LinkEvent` objects that can be consumed by the host application.

### Event Processing Pipeline

```
Event Types

WebView JavaScript

JSBridge.onJsonReceived()

DeserializeLinkMessageUseCase.launch()

JsType enum matching

LinkEvent creation

LinkViewModel event emission

Host Application

Simple Events
Done, Close, ShowClose, Loaded

Payload Events
AccessToken, TransferFinished, DelayedAuth

Special Events
TrueAuth, Error
```

Sources: [link/src/main/java/com/meshconnect/link/usecase/DeserializeLinkMessageUseCase.kt1-46](https://github.com/FrontFin/mesh-android-sdk/blob/e01c1f6c/link/src/main/java/com/meshconnect/link/usecase/DeserializeLinkMessageUseCase.kt#L1-L46) [link/src/main/java/com/meshconnect/link/entity/LinkEvent.kt1-15](https://github.com/FrontFin/mesh-android-sdk/blob/e01c1f6c/link/src/main/java/com/meshconnect/link/entity/LinkEvent.kt#L1-L15)

## Event Types and Message Mapping

The system defines a comprehensive set of event types that map JavaScript message types to native Kotlin sealed interface implementations.

### JavaScript to Native Type Mapping

| JavaScript Type | Native LinkEvent | Purpose |
| --- | --- | --- |
| `done` | `LinkEvent.Done` | Flow completion |
| `close` | `LinkEvent.Close` | User-initiated close |
| `showClose` | `LinkEvent.ShowClose` | Show close button |
| `loaded` | `LinkEvent.Loaded` | WebView content loaded |
| `brokerageAccountAccessToken` | `LinkEvent.Payload(AccessTokenPayload)` | Account authentication |
| `transferFinished` | `LinkEvent.Payload(TransferFinishedPayload)` | Transfer completion |
| `delayedAuthentication` | `LinkEvent.Payload(DelayedAuthPayload)` | Delayed auth flow |
| `openTrueAuth` | `LinkEvent.TrueAuth(link)` | External authentication |
| `error` | Exception thrown | Error handling |

### Type System Implementation

```
"maps to"

«enumeration»
Type

+brokerageAccountAccessToken

+error

+close

+done

+showClose

+transferFinished

+loaded

+delayedAuthentication

+openTrueAuth

«sealed interface»
LinkEvent

«data object»
Done

«data object»
Close

«data object»
ShowClose

«data object»
Loaded

TrueAuth

+link: String

Payload

+payload: LinkPayload
```

Sources: [link/src/main/java/com/meshconnect/link/entity/JsType.kt8-18](https://github.com/FrontFin/mesh-android-sdk/blob/e01c1f6c/link/src/main/java/com/meshconnect/link/entity/JsType.kt#L8-L18) [link/src/main/java/com/meshconnect/link/entity/LinkEvent.kt3-15](https://github.com/FrontFin/mesh-android-sdk/blob/e01c1f6c/link/src/main/java/com/meshconnect/link/entity/LinkEvent.kt#L3-L15)

## Message Deserialization Process

The `DeserializeLinkMessageUseCase` class serves as the central message processor that converts JSON strings into `LinkEvent` objects through a type-based dispatch mechanism.

### Deserialization Logic Flow

```
close

done

showClose

loaded

brokerageAccountAccessToken

transferFinished

delayedAuthentication

openTrueAuth

error

null/unknown

Raw JSON Message

JsonConverter.fromJson(json, JsType::class.java)

Extract type field

Type Switch

LinkEvent.Close

LinkEvent.Done

LinkEvent.ShowClose

LinkEvent.Loaded

AccessTokenResponse

TransferFinishedResponse

DelayedAuthResponse

LinkEvent.Payload(AccessTokenPayload)

LinkEvent.Payload(TransferFinishedPayload)

LinkEvent.Payload(DelayedAuthPayload)

JsonConverter.toMap()

LinkEvent.TrueAuth(link)

JsError parsing

throw IllegalStateException

return null
```

Sources: [link/src/main/java/com/meshconnect/link/usecase/DeserializeLinkMessageUseCase.kt15-45](https://github.com/FrontFin/mesh-android-sdk/blob/e01c1f6c/link/src/main/java/com/meshconnect/link/usecase/DeserializeLinkMessageUseCase.kt#L15-L45)

## Result Handling and Final Outcomes

The Event System culminates in `LinkResult` objects that represent the final state of the linking flow, providing a clean interface for host applications to handle success and failure scenarios.

### Result Type Hierarchy

```
```

Sources: [link/src/main/java/com/meshconnect/link/ui/LinkResult.kt7-15](https://github.com/FrontFin/mesh-android-sdk/blob/e01c1f6c/link/src/main/java/com/meshconnect/link/ui/LinkResult.kt#L7-L15)

## Event Processing Test Coverage

The Event System includes comprehensive test coverage that validates the correct mapping and processing of all message types, ensuring reliable event handling across different scenarios.

### Test Scenarios Coverage

| Test Case | Validates | Expected Outcome |
| --- | --- | --- |
| `test done` | Simple event mapping | `LinkEvent.Done` |
| `test close` | User close action | `LinkEvent.Close` |
| `test showClose` | UI state change | `LinkEvent.ShowClose` |
| `test brokerageAccountAccessToken` | Payload deserialization | `LinkEvent.Payload(AccessTokenPayload)` |
| `test transferFinished` | Transfer completion | `LinkEvent.Payload(TransferFinishedPayload)` |
| `test delayedAuthentication` | Auth flow handling | `LinkEvent.Payload(DelayedAuthPayload)` |
| `test openTrueAuth` | External auth link | `LinkEvent.TrueAuth(link)` |
| `test error` | Error message handling | `IllegalStateException` thrown |
| `test Undefined` | Unknown message type | `null` return |

Sources: [link/src/test/kotlin/com/meshconnect/link/usecase/DeserializeLinkMessageUseCaseTest.kt39-134](https://github.com/FrontFin/mesh-android-sdk/blob/e01c1f6c/link/src/test/kotlin/com/meshconnect/link/usecase/DeserializeLinkMessageUseCaseTest.kt#L39-L134)

## Integration Patterns

Host applications integrate with the Event System by observing `LinkEvent` emissions from the `LinkViewModel` and handling the resulting `LinkResult` outcomes when the linking flow completes.

The Event System provides both real-time event streaming for intermediate states and final result handling for completed flows, enabling flexible integration patterns that can accommodate various UI requirements and business logic needs.

Sources: [link/src/main/java/com/meshconnect/link/entity/LinkEvent.kt1-15](https://github.com/FrontFin/mesh-android-sdk/blob/e01c1f6c/link/src/main/java/com/meshconnect/link/entity/LinkEvent.kt#L1-L15) [link/src/main/java/com/meshconnect/link/ui/LinkResult.kt1-15](https://github.com/FrontFin/mesh-android-sdk/blob/e01c1f6c/link/src/main/java/com/meshconnect/link/ui/LinkResult.kt#L1-L15)