npm package: @infomaker/im-infocaster-web-client
Description: Infomaker JS module: im-infocaster-web-client
Latest version: 2.0.0

# Infomaker im-infocaster-web-client

## Prerequisites
You need to authorize yourself as infomaker with npm using a private key located in 1Password. The key 
can be found in the file 'JumpStart .env' in the Internal vault.

## Installation
`npm install @infomaker/im-infocaster-web-client --save`

## Basic Structure
The library supplies two web clients, using `WebSocket` and `EventSource` technologies. These
clients can create normal InfoCaster sessions, and subscribe to InfoCaster Broadcasts.

When a message is received from InfoCaster to the session, or broadcast, the client will emit
an event of either `publish` or `broadcastPublish`, for normal session and broadcast respectively.

In order to send messages to a session, the source doing the sending needs the session's webhookURL, or
a broadcastId, and make simple http-requests to an InfoCaster endpoint detailed [in the InfoCaster documentation](https://infocaster.lcc.infomaker.io/documentation).

### Available Events
| Name                  | Description |
| --------------------- | ----------- |
| `sessionInit`         | Triggers when the client has successfully created a connection with the InfoCaster endpoint |
| `publish`             | Triggers when a source publishes a message to the session's `webhookUrl` |
| `broadcastPublish`    | Triggers when a source publishes a message to the subscribed broadcast's publish-endpoint |
| `error`               | Something went wrong |
| `close`               | Connection to InfoCaster was closed for some reason |

## Usage

### Subscribe/Unsubscribe to events
The client has three relevant functions for event handling: `on`, `off`, and `clearEventHandlers`.

To subscribe to an event it's as easy as `infoCasterClient.on('publish', data => console.log(data))`. In order to 
unsubscribe from an event, you need to have a named reference for your callback-function.

```javascript
const callback = (data) => {
    console.log(data)
}

infoCasterClient.on('publish', callback)

infoCasterClient.off('publish', callback)
```

### Select source
InfoCaster Web Client supports `WebSocket` and `EventSource`-sources and contain clients for both.

Communication for these clients are one-way, even on WebSocket. To send messages to the clients, use
the webhookURL generated after the session has been initialized.

```javascript
import {EventSourceClient, WebSocketClient} from '@infomaker/im-infocaster-web-client'
```

Or, if you prefer to use a different name:

```javascript
import {EventSourceClient as InfoCasterClient} from '@infomaker/im-infocaster-web-client'
```

### Override InfoCaster endpoint
By default, the clients are configured to talk to the production environment of InfoCaster, but if you want
to change the base url to something else.

```javascript
import {WebSocketClient, EventSourceClient} from '@infomaker/im-infocaster-web-client'

const infoCasterClient = new WebSocketClient('https://my-personal.lcc.infomaker.io')
const anotherClient = new EventSourceClient('https://my-personal.lcc.infomaker.io')
```

## Sessions

### Create an InfoCaster session and listen to updates
```javascript
import {WebSocketClient} from '@infomaker/im-infocaster-web-client'

const infoCasterClient = new WebSocketClient('https://infocaster.lcc.infomaker.io', 'my-publisher', 'JWT-read-token', 'JWT-write-token')

infoCasterClient.on('sessionInit', (data) => {
    // Session is now active
})

// Receive all "publish"-type messages
infoCasterClient.on('publish', (data) => {
    console.log(data)
})
```

### Publish a message to an InfoCaster session
An active session is required to publish a message.

```javascript
import {WebSocketClient} from '@infomaker/im-infocaster-web-client'

const infoCasterClient = new WebSocketClient('https://infocaster.lcc.infomaker.io', 'my-publisher', 'JWT-read-token', 'JWT-write-token')

infoCasterClient.on('sessionInit', async (data) => {    
    // Session is now active
    await infoCasterClient.publish({foo: 'bar'})    
})

// Receive all "publish"-type messages
infoCasterClient.on('publish', (data) => {
    console.log(data) // {"payload": {"foo": "bar"}}
})
```

### Fetch the current session's webhookURL
You might need to supply your backend with a way to send updates to your session; in that case,
start a session and fetch that session's webhookUrl and use it on your backend.

```javascript
import {WebSocketClient} from '@infomaker/im-infocaster-web-client'

const infoCasterClient = new WebSocketClient('https://infocaster.lcc.infomaker.io', 'my-publisher', 'JWT-read-token', 'JWT-write-token')

infoCasterClient.on('sessionInit', () => {
    console.log(infoCasterClient.webhookUrl)
})
```

### Using channel for sessions
Sometimes it might be useful to differentiate messages on a single sessions by channel, sending status updates for different
tasks on the same session connection for example. When using channels, the data supplied to the `publish`-event will contain
a `channel`-property, which you can use to filter, group, or handle however you wish.

```javascript
import {WebSocketClient} from '@infomaker/im-infocaster-web-client'

const infoCasterClient = new WebSocketClient('https://infocaster.lcc.infomaker.io', 'my-publisher', 'JWT-read-token', 'JWT-write-token')

infoCasterClient.on('sessionInit', async () => {    
    // Session is now active
    await infoCasterClient.publish({foo: 'bar'}, 'my-channel')    
})

// Receive all "publish"-type messages
infoCasterClient.on('publish', (data) => {
    console.log(data) // {"channel": "my-channel", "payload": {"foo": "bar"}}
})
```


## Broadcasts

### Subscribe to an InfoCaster Broadcast
An active session is required to subscribe to a broadcast. When a subscription is requested,
your current session will be upgraded and start listening to that broadcast. Messages from that broadcast
will trigger the `broadcastPublish`-event on the client.

```javascript
import {WebSocketClient} from '@infomaker/im-infocaster-web-client'

const infoCasterClient = new WebSocketClient('https://infocaster.lcc.infomaker.io', 'my-publisher', 'JWT-read-token', 'JWT-write-token')

infoCasterClient.on('sessionInit', async () => {
    const broadcastId = 'my-broadcast-id'
    
    await infoCasterClient.subscribe(broadcastId)
})
```

### Publish a message to an InfoCaster broadcast
An active session is required to publish a message.

```javascript
import {WebSocketClient} from '@infomaker/im-infocaster-web-client'

const infoCasterClient = new WebSocketClient('https://infocaster.lcc.infomaker.io', 'my-publisher', 'JWT-read-token', 'JWT-write-token')

infoCasterClient.on('sessionInit', async (data) => {
    const broadcastId = 'my-broadcast-id'
    
    await infoCasterClient.subscribe(broadcastId)
    await infoCasterClient.broadcastPublish({foo: 'bar'}, 'my-broadcast-id')
})

// Receive all "broadcastPublish"-type messages
infoCasterClient.on('broadcastPublish', (data) => {
    console.log(data) // {"payload": {"foo": "bar"}}
})
```

#### Change publisher-id
The clients are by default sending and receiving messages to and from the publisher-id `open`. To send/receive using
a different id, supply this id to the `subscribe`, and `broadcastPublish`-functions:
```javascript
infoCasterClient.subscribe('my-broadcast-id', 'my-publisher-id')
infoCasterClient.broadcastPublish({foo: 'bar'}, 'my-broadcast-id', 'my-publisher-id')
```