Condo Bridge is a JS library that allows the frontend of your mini-application to communicate with the main application frontend.
Installation
To install the library, just run the following command according to your package manager:
npm
yarn
pnpm
bashnpm i @open-condo/bridge
Basic usage example
You can use bridge either within your frontend framework or directly in the browser environment:
JS
<script/>
typescriptimport bridge from '@open-condo/bridge' // Send event bridge.send('<event-name>') // Send event with args bridge.send('<event-name>', { someArg: 'some value' }) // Send event and process response bridge.send('<event-name>', { someArg: 'some value' }) .then((response) => { // successful state processing }).catch((error) => { // error processing })
API Reference
bridge.send(method[, params])
Sends a message to main client and returns the
Promise object with response dataParameters
method(required) The method of Condo Bridgeparams(optional) Object containing method args
Example
typescript// Sending event to client bridge .send('CondoWebAppResizeWindow', { height: 800 }) .then(data => { // Handling response console.log(data.height) }) .catch(error => { // Handling an error });
Since
bridge.send returns a Promise you can use async / await flow for handling events:typescripttry { const response = await bridge.send('CondoWebAppResizeWindow', { height: 800 }) // Handling response console.log(response.height) } catch (err) { // Handling error }
bridge.subscribe(listener)
Subscribes listener to all incoming events and responses.
If method "<method-name>" is called, the handler will receive event with type "<method-name>Error" in case of an error,
and with type "<method-name>Result" in case of successful execution.
This is common behavior for all Condo Bridge methods.
Parameters
listener(required) Function handling events
Example
typescript// Subscribing to receive events bridge.subscribe((event) => { const { type, data } = event if (type === 'CondoWebAppResizeWindowResult') { // Processing event result console.log(data.height) } else if (type === 'CondoWebAppResizeWindowError') { // Processing event error const { errorType, errorMessage } = data } })
bridge.unsubscribe(listener)
Unsubscribes a function from event listening
Parameters
listener(required) Function handling events
Example
typescriptimport bridge, { type CondoBridgeSubscriptionListener } from '@open-condo/bridge' const myListener: CondoBridgeSubscriptionListener = (event) => { logger.info(event) } // Subscribing bridge.subscribe(myListener) // Unsubscribing bridge.unsubscribe(myListener)
bridge.supports(method)
Checks if the main client (runtime environment) supports this method
Parameters
method(required) The method of Condo Bridge
Example
typescript// Checking if event is available if (bridge.supports('CondoWebAppResizeWindow')) { // Then sending actual event bridge.send('CondoWebAppResizeWindow', { height: document.body.scrollHeight }) }
Error types
Each error in Condo Bridge has the following structure::
typescripttype ClientErrorResponseData<Reason extends ErrorReason> = { errorType: 'client', errorReason: Reason errorCode: ErrorCode<Reason>, errorMessage: string }
The error details can be found in the
errorMessage field and the error can be processed by its code / cause:| Error Reason | Error Code | Erro description |
|---|---|---|
| ACCESS_DENIED | 0 | Your application has no access to execute this method |
| UNKNOWN_ERROR | 1 | Something went wrong on the Condo side, which is probably a bug |
| UNKNOWN_METHOD | 2 | Application was tried to call unknown or unsupported method for current platform |
| INVALID_PARAMETERS | 3 | Invalid method parameters was passed |
| HANDLER_ERROR | 4 | Error was thrown during handler execution |
| TIMEOUT_REACHED | 5 | Response / error was not received in specified timeout |