### Run Kabelwerk Demo Locally

Source: https://github.com/kabelwerk/sdk-js/blob/master/demo/README.md

Follow these steps to clone the project, install dependencies, and start the demo web application's development server.

```sh
git clone https://github.com/kabelwerk/sdk-js

cd sdk-js

npm install

cd demo

npm install

npm start
```

--------------------------------

### Clone Repository and Install Dependencies

Source: https://github.com/kabelwerk/sdk-js/blob/master/CONTRIBUTING.md

Commands to clone the repository, navigate into the project directory, and install necessary dependencies.

```sh
git clone https://github.com/kabelwerk/sdk-js
cd sdk-js
npm install
```

--------------------------------

### Install Kabelwerk SDK

Source: https://github.com/kabelwerk/sdk-js/blob/master/README.md

Install the SDK using npm. Refer to CHANGELOG.md for version upgrade information.

```bash
npm install kabelwerk
```

--------------------------------

### Start Local Development Server

Source: https://github.com/kabelwerk/sdk-js/blob/master/website/README.md

Starts a local development server that reflects changes live without requiring a restart.

```bash
$ yarn start
```

--------------------------------

### Install Dependencies with Yarn

Source: https://github.com/kabelwerk/sdk-js/blob/master/website/README.md

Run this command to install all project dependencies using Yarn.

```bash
$ yarn
```

--------------------------------

### Browser Notification Example

Source: https://github.com/kabelwerk/sdk-js/blob/master/docs/notifiers.md

This snippet demonstrates how to use the Kabelwerk Notifier to display browser notifications for new messages. Ensure notification permissions are handled separately.

```javascript
let notifier = Kabelwerk.openNotifier();

notifier.on('updated', ({ message }) => {
    const message = notification.message;

    new Notification(message.user.name, { body: message.text });
});

notifier.connect();
```

--------------------------------

### Get Room Markers

Source: https://github.com/kabelwerk/sdk-js/blob/master/docs/rooms.md

Retrieves the markers for the current user and the other user in the room. Either marker can be null if not set.

```APIDOC
## Get Room Markers

### Description
Retrieves the markers for the current user and the other user in the room. Either marker can be null if not set.

### Method
`room.getMarkers()`

### Returns
An array containing two elements: `[ownMarker, otherMarker]`. Each element can be a marker object or null.
```

--------------------------------

### Get Room Markers

Source: https://github.com/kabelwerk/sdk-js/blob/master/docs/rooms.md

Retrieves the user's own marker and the latest hub-side marker for the room. Either marker can be null if not yet set.

```javascript
// either pair item (including both of them) may be null
const [ownMarker, otherMarker] = room.getMarkers();
```

--------------------------------

### Initialize Kabelwerk SDK

Source: https://github.com/kabelwerk/sdk-js/blob/master/docs/kabelwerk.md

Configure the SDK with connection details and event listeners for connection status and errors. The 'ready' event fires once the connection is established and methods are available.

```javascript
import Kabelwerk from 'kabelwerk';

Kabelwerk.config({
    url: 'wss://hub.kabelwerk.io/socket/user',
    token: 'signed.jwt.token',
    refreshToken: async (token) => token,
    logging: 'info',
});

Kabelwerk.on('ready', () => {
    // this event is fired once: when the initial connection is established and
    // the other methods are ready to be used (openInbox, openRoom, etc.)
});

Kabelwerk.on('error', (error) => {
    // e.g. if the token is invalid
});

Kabelwerk.on('disconnected', () => {
    // this event is fired every time when the connection drops
});

Kabelwerk.on('connected', () => {
    // this event is fired every time when the connection is automatically
    // re-established after a disconnect
});

Kabelwerk.connect();
```

--------------------------------

### Kabelwerk Configuration and Connection

Source: https://github.com/kabelwerk/sdk-js/blob/master/website/versioned_docs/version-0.3.6/kabelwerk.md

Configure the Kabelwerk SDK with connection details and event listeners, then establish the connection.

```APIDOC
## Configuration and Connection

### Description
Configure the SDK with the WebSocket URL, authentication token, and a refresh token function. Set up event listeners for connection status and errors, then initiate the connection.

### Methods
- `Kabelwerk.config(options)`: Configures the SDK.
- `Kabelwerk.on(event, listener)`: Registers an event listener.
- `Kabelwerk.connect()`: Establishes the WebSocket connection.

### Parameters
#### `Kabelwerk.config(options)`
- **options** (object) - Required - Configuration options:
  - **url** (string) - Required - The WebSocket server URL.
  - **token** (string) - Required - The signed JWT token for authentication.
  - **refreshToken** (function) - Required - An async function that returns a new token when called.
  - **logging** (string) - Optional - Sets the logging level (e.g., 'info').

#### `Kabelwerk.on(event, listener)`
- **event** (string) - Required - The name of the event to listen for ('ready', 'error', 'disconnected', 'connected').
- **listener** (function) - Required - The callback function to execute when the event is fired.

### Events
- **ready**: Fired once when the initial connection is established and methods are ready.
- **error**: Fired when an error occurs (e.g., invalid token).
- **disconnected**: Fired every time the connection drops.
- **connected**: Fired every time the connection is automatically re-established.

### Request Example
```js
import Kabelwerk from 'kabelwerk';

Kabelwerk.config({
    url: 'wss://hub.kabelwerk.io/socket/user',
    token: 'signed.jwt.token',
    refreshToken: async (token) => token,
    logging: 'info',
});

Kabelwerk.on('ready', () => {
    console.log('Kabelwerk is ready!');
});

Kabelwerk.on('error', (error) => {
    console.error('Kabelwerk error:', error);
});

Kabelwerk.connect();
```
```

--------------------------------

### Kabelwerk.connect()

Source: https://github.com/kabelwerk/sdk-js/blob/master/docs/kabelwerk.md

Establishes a connection to the Kabelwerk server. Event listeners should be attached before invoking this method.

```APIDOC
## Kabelwerk.connect()

### Description
Establishes connection to the server. Usually all event listeners should be already attached when this method is invoked.

### Method
```
Kabelwerk.connect()
```
```

--------------------------------

### Kabelwerk Initialization and Configuration

Source: https://github.com/kabelwerk/sdk-js/blob/master/docs/kabelwerk.md

Configure and initialize the Kabelwerk singleton, including setting up the WebSocket URL, authentication token, and refresh token logic. It also covers event listeners for connection status and logging.

```APIDOC
## Configuration and Connection

### Description
Configure the Kabelwerk SDK with necessary details like the WebSocket URL and authentication token. Set up event listeners for connection status changes (`ready`, `error`, `disconnected`, `connected`) and initiate the connection.

### Method
`Kabelwerk.config(options)`
`Kabelwerk.on(event, listener)`
`Kabelwerk.connect()`

### Parameters
#### `Kabelwerk.config(options)`
- **options** (object) - Required - Configuration object.
  - **url** (string) - Required - The WebSocket URL for the Kabelwerk backend.
  - **token** (string) - Required - The signed JWT token for authentication.
  - **refreshToken** (function) - Required - An async function that returns a new token when called.
  - **logging** (string) - Optional - Sets the logging level (e.g., 'info').

#### `Kabelwerk.on(event, listener)`
- **event** (string) - Required - The name of the event to listen for ('ready', 'error', 'disconnected', 'connected').
- **listener** (function) - Required - The callback function to execute when the event is fired.

### Request Example
```js
import Kabelwerk from 'kabelwerk';

Kabelwerk.config({
    url: 'wss://hub.kabelwerk.io/socket/user',
    token: 'signed.jwt.token',
    refreshToken: async (token) => token,
    logging: 'info',
});

Kabelwerk.on('ready', () => {
    console.log('Kabelwerk is ready!');
});

Kabelwerk.on('error', (error) => {
    console.error('Kabelwerk error:', error);
});

Kabelwerk.connect();
```
```

--------------------------------

### Configure Kabelwerk SDK Options

Source: https://github.com/kabelwerk/sdk-js/blob/master/website/versioned_docs/version-0.3.6/config.md

Set initial connection parameters and logging level. This method can be called multiple times to update specific configuration values.

```javascript
Kabelwerk.config({
    url: 'wss://hub.kabelwerk.io/socket/user',
    token: 'initial.jwt.token',
    refreshToken: () => fetchKabelwerkToken().then((res) => res.data.token),
    ensureRooms: 'all',
    logging: 'info',
});
```

```javascript
// the method can be called multiple times — each call only updates the values
// for the given keys
Kabelwerk.config({ logging: 'silent' });
```

--------------------------------

### Run Unit Tests and Formatting

Source: https://github.com/kabelwerk/sdk-js/blob/master/CONTRIBUTING.md

Commands to execute the project's unit tests and format the code according to Prettier standards.

```sh
npm test
npm run format
```

--------------------------------

### room.connect()

Source: https://github.com/kabelwerk/sdk-js/blob/master/docs/rooms.md

Establishes a connection to the server. It's recommended to attach all event listeners before invoking this method.

```APIDOC
## room.connect()

### Description
Establishes connection to the server. Usually all event listeners should be already attached when this method is invoked.

### Method
POST

### Endpoint
/room/connect

### Response
#### Success Response (200)
- **status** (string) - Indicates the success of the connection.
```

--------------------------------

### Deploy Website using SSH

Source: https://github.com/kabelwerk/sdk-js/blob/master/website/README.md

Deploys the website using SSH. Ensure the USE_SSH environment variable is set.

```bash
$ USE_SSH=true yarn deploy
```

--------------------------------

### Room Management

Source: https://github.com/kabelwerk/sdk-js/blob/master/docs/kabelwerk.md

Create and open rooms using the Kabelwerk SDK.

```APIDOC
## Rooms

### Description
Create a new room for the connected user in a specified hub, or open an existing room by its ID. Refer to the [rooms](./rooms.md) documentation for more details.

### Methods
- `Kabelwerk.createRoom(hubIdOrSlug)`: Creates a new room.
- `Kabelwerk.openRoom(roomId)`: Opens an existing room.

### Parameters
#### `Kabelwerk.createRoom(hubIdOrSlug)`
- **hubIdOrSlug** (string | number) - Required - The ID or slug of the hub where the room should be created.

#### `Kabelwerk.openRoom(roomId)`
- **roomId** (string) - Required - The ID of the room to open.

### Request Example
```js
// To create a new room and then open it
Kabelwerk.createRoom('some-hub-id').then(({ id }) => {
    let room = Kabelwerk.openRoom(id);
    console.log('Room opened:', room);
}).catch((error) => {
    console.error('Failed to create or open room:', error);
});

// If you already have the room's ID
let existingRoom = Kabelwerk.openRoom('existing-room-id');
```

### Response
#### `createRoom` Success Response
- **id** (string) - The ID of the newly created room.
```

--------------------------------

### Configure Kabelwerk Connection and Logging

Source: https://github.com/kabelwerk/sdk-js/blob/master/docs/config.md

Set initial connection URL, authentication token, refresh token logic, room ensuring behavior, and logging level. The method can be called again to update specific settings.

```javascript
Kabelwerk.config({
    url: 'wss://hub.kabelwerk.io/socket/user',
    token: 'initial.jwt.token',
    refreshToken: () => fetchKabelwerkToken().then((res) => res.data.token),
    ensureRooms: 'all',
    logging: 'info',
});

// the method can be called multiple times — each call only updates the values
// for the given keys
Kabelwerk.config({ logging: 'silent' });
```

--------------------------------

### Connect to Kabelwerk

Source: https://github.com/kabelwerk/sdk-js/blob/master/website/versioned_docs/version-0.3.6/README.md

Configure and establish a WebSocket connection to the Kabelwerk backend. This snippet shows how to set up configuration, handle connection events, and open an inbox and a room.

```javascript
import Kabelwerk from 'kabelwerk';

Kabelwerk.config({ url, token });

Kabelwerk.on('ready', () => {
    // this event is fired once when the initial connection is established
    let inbox = Kabelwerk.openInbox();
    let room = Kabelwerk.openRoom();
});

Kabelwerk.on('error', (error) => {
    // e.g. when the token is invalid
});

Kabelwerk.connect();
```

--------------------------------

### Build Static Website Content

Source: https://github.com/kabelwerk/sdk-js/blob/master/website/README.md

Generates static content for the website into the 'build' directory, ready for hosting.

```bash
$ yarn build
```

--------------------------------

### Open and Connect to a Room

Source: https://github.com/kabelwerk/sdk-js/blob/master/docs/rooms.md

Initializes a room object using its ID and connects to it. The 'ready' event fires once when the room is loaded.

```javascript
let room = Kabelwerk.openRoom(roomId);

room.on('ready', ({ messages, markers }) => {
    // this event is fired once when the room is loaded
});

// make it live
room.connect();
```

--------------------------------

### Kabelwerk.config(options)

Source: https://github.com/kabelwerk/sdk-js/blob/master/docs/kabelwerk.md

Sets the configuration for the Kabelwerk SDK. This method must be called before Kabelwerk.connect() and is used to set authentication tokens.

```APIDOC
## Kabelwerk.config(options)

### Description
Sets the configuration for the Kabelwerk SDK. This method should be called at least once before invoking `Kabelwerk.connect()` in order to set an authentication token.

### Method
```
Kabelwerk.config(options)
```

### Parameters
#### Request Body
- **options** (object) - Required - Configuration options, including an authentication token.
```

--------------------------------

### Open or Create a Room

Source: https://github.com/kabelwerk/sdk-js/blob/master/docs/kabelwerk.md

Create a new room within a specified hub and then open it, or open an existing room if its ID is known.

```javascript
// to create a new room for the connected user in the given hub
Kabelwerk.createRoom(hubIdOrSlug).then(({ id }) => {
    let room = Kabelwerk.openRoom(id);
});

// if you already have the room's id
let room = Kabelwerk.openRoom(roomId);
```

--------------------------------

### Kabelwerk.openInbox(params)

Source: https://github.com/kabelwerk/sdk-js/blob/master/docs/kabelwerk.md

Initializes and returns an inbox object with the specified parameters.

```APIDOC
## Kabelwerk.openInbox(params)

### Description
Initialises and returns an [inbox object](./inboxes.md) with the given parameters.

### Method
```
Kabelwerk.openInbox(params)
```

### Parameters
#### Request Body
- **params** (object) - Required - Parameters for the inbox.
```

--------------------------------

### inbox.connect()

Source: https://github.com/kabelwerk/sdk-js/blob/master/docs/inboxes.md

Establishes a connection to the server. It's recommended to attach all event listeners before invoking this method.

```APIDOC
## inbox.connect()

### Description
Establishes connection to the server. Usually all event listeners should be already attached when this method is invoked.

### Method
`inbox.connect()`
```

--------------------------------

### Load Hub Information with Kabelwerk.loadHubInfo()

Source: https://github.com/kabelwerk/sdk-js/blob/master/docs/kabelwerk.md

Use this method to retrieve information about the connected user's hub. It's only available on the hub side and returns an object with hub details. Handle potential errors, such as when the connected user is not a hub user.

```javascript
Kabelwerk.loadHubInfo()
    .then(() => {
        // { id, name, users }
    })
    .catch((error) => {
        // e.g. if the connected user is not a hub user
    });
```

--------------------------------

### Kabelwerk.on(event, listener)

Source: https://github.com/kabelwerk/sdk-js/blob/master/docs/kabelwerk.md

Attaches an event listener to the Kabelwerk client. Returns a string identifying the listener for later removal.

```APIDOC
## Kabelwerk.on(event, listener)

### Description
Attaches an event listener. See [list of events](#list-of-events) for a list of available events. Returns a short string identifying the attached listener — which string can be then used to remove that event listener via the `Kabelwerk.off(event, ref)` method.

### Method
```
Kabelwerk.on(event, listener)
```

### Parameters
#### Query Parameters
- **event** (string) - Required - The event to listen for.
- **listener** (function) - Required - The callback function to execute when the event is triggered.
```

--------------------------------

### Kabelwerk.openNotifier()

Source: https://github.com/kabelwerk/sdk-js/blob/master/docs/kabelwerk.md

Initializes and returns a notifier object.

```APIDOC
## Kabelwerk.openNotifier()

### Description
Initialises and returns a [notifier object](./notifiers.md).

### Method
```
Kabelwerk.openNotifier()
```
```

--------------------------------

### Kabelwerk.loadHubInfo()

Source: https://github.com/kabelwerk/sdk-js/blob/master/docs/kabelwerk.md

Loads information about the connected user's hub. This method is only available on the hub side and returns a Promise resolving with hub details.

```APIDOC
## Kabelwerk.loadHubInfo()

### Description
Loads info about the connected user's hub. Returns a Promise resolving into an `{ id, name, users }` object. This method is only available on the hub side.

### Method
```
Kabelwerk.loadHubInfo()
```

### Returns
- Promise<{ id: string, name: string, users: Array<object> }>
```

--------------------------------

### Room Management

Source: https://github.com/kabelwerk/sdk-js/blob/master/website/versioned_docs/version-0.3.6/kabelwerk.md

Create and open rooms for communication.

```APIDOC
## Room Management

### Description
Create new rooms or open existing ones for communication.

### Methods
- `Kabelwerk.createRoom(hubIdOrSlug)`: Creates a new room in the specified hub.
- `Kabelwerk.openRoom(roomId)`: Opens an existing room by its ID.

### Parameters
#### `Kabelwerk.createRoom(hubIdOrSlug)`
- **hubIdOrSlug** (string | number) - Required - The ID or slug of the hub where the room should be created.

#### `Kabelwerk.openRoom(roomId)`
- **roomId** (string) - Required - The ID of the room to open.

### Response
#### `Kabelwerk.createRoom` Success Response
- **{ id: string }**: An object containing the ID of the newly created room.

### Request Example
```js
// To create a new room and then open it:
Kabelwerk.createRoom('some-hub-id').then(({ id }) => {
    let room = Kabelwerk.openRoom(id);
    console.log('Room opened:', room);
}).catch((error) => {
    console.error('Failed to create or open room:', error);
});

// If you already have the room's ID:
let existingRoomId = 'existing-room-id';
let room = Kabelwerk.openRoom(existingRoomId);
console.log('Existing room opened:', room);
```
```

--------------------------------

### Kabelwerk.ping(callback)

Source: https://github.com/kabelwerk/sdk-js/blob/master/website/versioned_docs/version-0.3.6/kabelwerk.md

Pings the Kabelwerk server and invokes the callback with the round-trip time in milliseconds.

```APIDOC
## Kabelwerk.ping(callback)

### Description
Pings the Kabelwerk server and invokes the given callback with the round-trip time in milliseconds when the response is received.

### Method
```
Kabelwerk.ping(callback)
```

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **callback** (function) - Required - The function to invoke with the round-trip time in milliseconds.
```

--------------------------------

### Kabelwerk.once(event, listener)

Source: https://github.com/kabelwerk/sdk-js/blob/master/docs/kabelwerk.md

Attaches an event listener that will be invoked at most once.

```APIDOC
## Kabelwerk.once(event, listener)

### Description
The same as the `Kabelwerk.on(event, listener)` method, except that the listener will be automatically removed after being invoked — i.e. the listener is invoked at most once.

### Method
```
Kabelwerk.once(event, listener)
```

### Parameters
#### Query Parameters
- **event** (string) - Required - The event to listen for.
- **listener** (function) - Required - The callback function to execute when the event is triggered.
```

--------------------------------

### Create and Open a New Room

Source: https://github.com/kabelwerk/sdk-js/blob/master/docs/rooms.md

Creates a new room if it doesn't exist and then opens it. Handles potential errors, such as a room already existing.

```javascript
Kabelwerk.createRoom(hubIdOrSlug)
    .then(({ id }) => {
        let room = Kabelwerk.openRoom(id);
        room.connect();
    })
    .catch((error) => {
        // e.g. if there already exists a room for this user and hub
    });
```

--------------------------------

### Kabelwerk.openRoom(roomId)

Source: https://github.com/kabelwerk/sdk-js/blob/master/docs/kabelwerk.md

Initializes and returns a room object for the specified chat room ID. If no ID is provided, it opens one of the user's rooms.

```APIDOC
## Kabelwerk.openRoom(roomId)

### Description
Initialises and returns a [room object](./rooms.md) for the chat room with the given ID. Alternatively, the method can be called without a parameter, in which case one of the rooms belonging to the connected user will be opened — useful when you have a single hub.

### Method
```
Kabelwerk.openRoom(roomId)
```

### Parameters
#### Path Parameters
- **roomId** (string) - Optional - The ID of the chat room to open.
```

--------------------------------

### room.postUpload(file)

Source: https://github.com/kabelwerk/sdk-js/blob/master/website/versioned_docs/version-0.3.6/rooms.md

Uploads a file to the chat room. Accepts a File object or a platform-specific equivalent. Returns a Promise resolving to an upload object, whose ID can be used for posting messages.

```APIDOC
## room.postUpload(file)

### Description
Uploads a file in the chat room. The parameter is expected to be a [File](https://developer.mozilla.org/en-US/docs/Web/API/File) object or a platform-specific equivalent (e.g. an object with an `uri` attribute in the case of React Native). Returns a Promise which resolves into an [upload object](./uploads.md) (the ID of which can be then used to post an image or attachment message).

### Parameters
#### Path Parameters
- **file** (File | object) - Required - The file to upload.
```

--------------------------------

### room.postUpload(file)

Source: https://github.com/kabelwerk/sdk-js/blob/master/docs/rooms.md

Uploads a file to the chat room. Returns a Promise resolving to an upload object, whose ID can be used to post the file as a message.

```APIDOC
## room.postUpload(file)

### Description
Uploads a file in the chat room. The parameter is expected to be a [File](https://developer.mozilla.org/en-US/docs/Web/API/File) object or a platform-specific equivalent (e.g. an object with an `uri` attribute in the case of React Native). Returns a Promise which resolves into an [upload object](./uploads.md) (the ID of which can be then used to post an image or attachment message).

### Method
POST

### Endpoint
/room/uploads

### Parameters
#### Request Body
- **file** (File | object) - Required - The file to upload. Can be a File object or a platform-specific equivalent.
```

--------------------------------

### Deploy Website without SSH

Source: https://github.com/kabelwerk/sdk-js/blob/master/website/README.md

Deploys the website without using SSH. Replace <Your GitHub username> with your actual GitHub username.

```bash
$ GIT_USER=<Your GitHub username> yarn deploy
```

--------------------------------

### Kabelwerk.ping(callback)

Source: https://github.com/kabelwerk/sdk-js/blob/master/docs/kabelwerk.md

Pings the Kabelwerk server and invokes a callback with the round-trip time.

```APIDOC
## Kabelwerk.ping(callback)

### Description
Pings the Kabelwerk server and invokes the given callback with the round-trip time in milliseconds when the response is received. Returns a boolean indicating whether the ping has been sent.

### Method
```
Kabelwerk.ping(callback)
```

### Parameters
#### Query Parameters
- **callback** (function) - Required - The function to call with the round-trip time in milliseconds.
```

--------------------------------

### User Management

Source: https://github.com/kabelwerk/sdk-js/blob/master/docs/kabelwerk.md

Retrieve and update the connected user's information using the Kabelwerk SDK.

```APIDOC
## User Management

### Description
Get the current user object and update its properties. The changes are persisted by calling `updateUser`.

### Methods
- `Kabelwerk.getUser()`: Retrieves the current user object.
- `Kabelwerk.updateUser(user)`: Updates the user object on the server.

### Parameters
#### `Kabelwerk.updateUser(user)`
- **user** (object) - Required - The user object to update.

### Request Example
```js
let user = Kabelwerk.getUser();
user.name = 'Nana';

Kabelwerk.updateUser(user)
    .then((updatedUser) => {
        console.log('User updated:', updatedUser);
    })
    .catch((error) => {
        console.error('Failed to update user:', error);
    });
```

### Response
#### Success Response
- **user** (object) - The updated user object.
```

--------------------------------

### Kabelwerk.createRoom(hubIdOrSlug)

Source: https://github.com/kabelwerk/sdk-js/blob/master/docs/kabelwerk.md

Creates a chat room between the connected user and a hub. Returns a Promise that resolves with the ID of the newly created room.

```APIDOC
## Kabelwerk.createRoom(hubIdOrSlug)

### Description
Creates a chat room between the connected user and a hub. Returns a Promise resolving into an `{ id }` object holding the ID of the newly created room. This method is intended to be used on the end side.

### Method
```
Kabelwerk.createRoom(hubIdOrSlug)
```

### Parameters
#### Path Parameters
- **hubIdOrSlug** (string) - Required - The ID or slug of the hub to create a room with.
```

--------------------------------

### Open and Connect to an Inbox

Source: https://github.com/kabelwerk/sdk-js/blob/master/website/versioned_docs/version-0.3.6/inboxes.md

Opens a new inbox, attaches event listeners for initial loading and updates, and then connects to the service. Use this to display a list of recent conversations.

```javascript
let inbox = Kabelwerk.openInbox();

inbox.on('ready', ({ items }) => {
    // this event is fired once when the initial list of inbox items is loaded
});

inbox.on('updated', ({ items }) => {
    // whenever a new message is posted, the list of inbox items is updated
    // accordingly and this event is fired
});

// bring it to life, preferably after attaching the desired event listeners
inbox.connect();
```

--------------------------------

### Kabelwerk.getUser()

Source: https://github.com/kabelwerk/sdk-js/blob/master/docs/kabelwerk.md

Retrieves information about the currently connected user.

```APIDOC
## Kabelwerk.getUser()

### Description
Returns the connected user, as an `{ id, key, name }` object.

### Method
```
Kabelwerk.getUser()
```

### Returns
- object: An object containing the user's id, key, and name.
```

--------------------------------

### Inbox Management

Source: https://github.com/kabelwerk/sdk-js/blob/master/docs/kabelwerk.md

Open a new inbox using the Kabelwerk SDK.

```APIDOC
## Inboxes

### Description
Open a new inbox. Refer to the [inboxes](./inboxes.md) documentation for more details.

### Method
`Kabelwerk.openInbox()`

### Request Example
```js
let inbox = Kabelwerk.openInbox();
```
```

--------------------------------

### Open and Manage Inbox

Source: https://github.com/kabelwerk/sdk-js/blob/master/docs/inboxes.md

Opens an inbox, attaches event listeners for 'ready' and 'updated' states, connects to the service, and demonstrates loading more items. Use this to display a list of recent conversations.

```javascript
let inbox = Kabelwerk.openInbox();

inbox.on('ready', ({ items }) => {
    // this event is fired once when the initial list of inbox items is loaded
});

inbox.on('updated', ({ items }) => {
    // whenever a new message is posted, the list of inbox items is updated
    // accordingly and this event is fired
});

// bring it to life, preferably after attaching the desired event listeners
inbox.connect();

inbox
    .loadMore()
    .then(({ items }) => {
        // resolves into the expanded list of inbox items
    })
    .catch((error) => {
        // if there are no more items, you will get an empty list, not an error
    });
```

--------------------------------

### Kabelwerk.getState()

Source: https://github.com/kabelwerk/sdk-js/blob/master/docs/kabelwerk.md

Retrieves the current connection state of the Kabelwerk client.

```APIDOC
## Kabelwerk.getState()

### Description
Returns the current connection state.

### Method
```
Kabelwerk.getState()
```

### Returns
- string: The current connection state (e.g., CONNECTING, ONLINE, INACTIVE).
```

--------------------------------

### Kabelwerk.updateDevice(attributes)

Source: https://github.com/kabelwerk/sdk-js/blob/master/docs/kabelwerk.md

Sets and/or updates push notification settings for the currently connected device.

```APIDOC
## Kabelwerk.updateDevice(attributes)

### Description
Sets and/or updates push notifications settings for the currently connected device. Expects a `{ pushNotificationsToken, pushNotificationsEnabled }` object where the token is a [Firebase registration token](https://firebase.google.com/docs/cloud-messaging) and the other value is a boolean allowing you to toggle the sending of push notifications to the currently connected device. Returns a Promise. If you do not want to have push notifications, you can safely ignore this method — in which case also no information about the currently connected device will be stored in the Kabelwerk database.

### Method
```
Kabelwerk.updateDevice(attributes)
```

### Parameters
#### Request Body
- **attributes** (object) - Required - An object containing push notification settings.
  - **pushNotificationsToken** (string) - Optional - The Firebase registration token for push notifications.
  - **pushNotificationsEnabled** (boolean) - Optional - A boolean to enable or disable push notifications.
```

--------------------------------

### Manage Inboxes

Source: https://github.com/kabelwerk/sdk-js/blob/master/website/versioned_docs/version-0.3.6/README.md

Open an inbox to view and manage rooms ordered by message recency. This code demonstrates how to connect to an inbox and listen for updates.

```javascript
let inbox = Kabelwerk.openInbox();

inbox.on('ready', ({ items }) => {
    // this event is fired once when the initial list of inbox items is loaded
});

inbox.on('updated', ({ items }) => {
    // whenever a new message is posted, the list of inbox items is updated
    // accordingly and this event is fired
});

inbox.connect();
```

--------------------------------

### Interact with Rooms

Source: https://github.com/kabelwerk/sdk-js/blob/master/website/versioned_docs/version-0.3.6/README.md

Open a specific chat room to post and retrieve messages. This snippet shows how to connect to a room, handle new messages, and load earlier messages.

```javascript
let room = Kabelwerk.openRoom(roomId);

room.on('ready', ({ messages }) => {
    // this event is fired once when the room is loaded
});

room.on('message_posted', (message) => {
    // this event is fired every time a new message is posted in this room
});

room.connect();

room.postMessage({ text })
    .then((message) => {
        // you will also get the same message via the `message_posted` event
    })
    .catch((error) => {
        // e.g. when the server rejects the message
    });

room.loadEarlier()
    .then(({ messages }) => {
        // resolves into the list of messages which come right before the earliest
        // message seen by the room object
    })
    .catch((error) => {
        // if there are no more messages, you will get an empty list, not an error
    });
```

--------------------------------

### Notifier Methods

Source: https://github.com/kabelwerk/sdk-js/blob/master/docs/notifiers.md

This section details the methods available on the Notifier object for managing connections and event listeners.

```APIDOC
## notifier.connect()

### Description
Establishes connection to the server. It's recommended to attach all event listeners before invoking this method.

### Method
notifier.connect()

## notifier.disconnect()

### Description
Removes all previously attached event listeners and closes the connection to the server.

### Method
notifier.disconnect()

## notifier.off(event, ref)

### Description
Removes one or more previously attached event listeners. Both parameters are optional. If no `ref` is given, all listeners for the specified `event` are removed. If no `event` is given, all event listeners attached to the notifier object are removed.

### Method
notifier.off(event, ref)

## notifier.on(event, listener)

### Description
Attaches an event listener. Returns a short string identifying the attached listener, which can be used later to remove the listener via `notifier.off(event, ref)`. See the 'List of events' section for available events.

### Method
notifier.on(event, listener)

## notifier.once(event, listener)

### Description
Similar to `notifier.on(event, listener)`, but the listener is automatically removed after being invoked once.

### Method
notifier.once(event, listener)
```

--------------------------------

### room.once(event, listener)

Source: https://github.com/kabelwerk/sdk-js/blob/master/docs/rooms.md

Attaches an event listener that will be invoked at most once.

```APIDOC
## room.once(event, listener)

### Description
The same as the `room.on(event, listener)` method, except that the listener will be automatically removed after being invoked — i.e. the listener is invoked at most once.

### Method
POST

### Endpoint
/room/event-listener/once

### Parameters
#### Request Body
- **event** (string) - Required - The name of the event to listen for.
- **listener** (function) - Required - The callback function to execute when the event is triggered.
```

--------------------------------

### Manage Custom Room Attributes

Source: https://github.com/kabelwerk/sdk-js/blob/master/docs/rooms.md

Use `getAttributes` to retrieve custom attributes and `updateAttributes` to set or update them. The `updateAttributes` method returns a promise that resolves with the updated attributes.

```javascript
// use this method to inspect the room's custom attributes
let attributes = room.getAttributes();

// the returned object is just a local copy
attributes.country = 'DE';

// use this method to set/update the custom attributes
room.updateAttributes(attributes)
    .then((attributes) => {
        // the resolved value will be identical as room.getAttributes() here
        console.assert(attributes.country == 'DE');
        console.assert(room.getAttributes().country == 'DE');
    })
    .catch((error) => {
        // e.g. if the server times out
    });

```

--------------------------------

### Open an Inbox

Source: https://github.com/kabelwerk/sdk-js/blob/master/docs/kabelwerk.md

Open a new inbox. Refer to the inboxes documentation for more details.

```javascript
let inbox = Kabelwerk.openInbox();
```

--------------------------------

### Handle New Messages in a Room

Source: https://github.com/kabelwerk/sdk-js/blob/master/docs/rooms.md

Listens for new messages posted in a room. The 'message_posted' event is fired for every new message.

```javascript
room.on('message_posted', (message) => {
    // this event is fired every time a new message is posted in this room
});
```

--------------------------------

### Manage User Information

Source: https://github.com/kabelwerk/sdk-js/blob/master/docs/kabelwerk.md

Retrieve the current user's information and update their details. The update is reflected immediately in the local user object and confirmed by the server.

```javascript
let user = Kabelwerk.getUser();
user.name = 'Nana';

Kabelwerk.updateUser(user)
    .then((user) => {
        console.assert(user.name == 'Nana');
        console.assert(kabel.getUser().name == 'Nana');
    })
    .catch((error) => {
        // e.g. if the server times out
    });
```

--------------------------------

### Listen for Marker Moves

Source: https://github.com/kabelwerk/sdk-js/blob/master/docs/rooms.md

Subscribes to the 'marker_moved' event, which is triggered whenever any marker in the room is updated, including automatically after a message is posted.

```javascript
// this event is fired every time a marker in the room is moved,
// including after a message_posted event
room.on('marker_moved', (marker) => {});
```

--------------------------------

### room.postMessage(params)

Source: https://github.com/kabelwerk/sdk-js/blob/master/docs/rooms.md

Posts a new message to the chat room, either as text or as an image/attachment using an upload ID. Returns a Promise resolving to the newly added message.

```APIDOC
## room.postMessage(params)

### Description
Posts a new message in the chat room. The parameter should be either a `{ text }` object if you want to create a text message or an `{ uploadId }` object if you want to create a message of type "image" or "attachment" (inferred from the upload's MIME type). Returns a Promise which resolves into the newly added [message](./messages.md).

### Method
POST

### Endpoint
/room/messages

### Parameters
#### Request Body
- **params** (object) - Required - An object containing either a `text` field for text messages or an `uploadId` field for image/attachment messages.
  - **text** (string) - Optional - The content of the text message.
  - **uploadId** (string) - Optional - The ID of the upload to be posted as a message.
```

--------------------------------

### inbox.search(params)

Source: https://github.com/kabelwerk/sdk-js/blob/master/docs/inboxes.md

Performs a server-side search within the inbox based on user key and/or room names. It expects an object containing a `query` string, and optionally `limit` and `offset` for pagination. Returns a Promise resolving to an `{items}` object with matching inbox items.

```APIDOC
## inbox.search(params)

### Description
Performs a server-side search by user key and/or name of the rooms in the inbox. Expects an object that contains at least a `query` string, and optionally a `limit` and an `offset` for results pagination. Returns a Promise which resolves into a `{items}` object containing a (possibly empty) list of inbox items that match the search query. This method is only available on the hub side.

### Method
`inbox.search(params)`

### Parameters
#### Path Parameters
- **params** (object) - Required - An object containing search parameters.
  - **query** (string) - Required - The search query string.
  - **limit** (number) - Optional - The maximum number of results to return.
  - **offset** (number) - Optional - The number of results to skip.
```

--------------------------------

### Archive and Unarchive Rooms

Source: https://github.com/kabelwerk/sdk-js/blob/master/docs/rooms.md

Rooms can be archived using the `archive` method and restored using the `unarchive` method. Both methods return promises that resolve upon successful completion. Check the room's archived status with `isArchived()`.

```javascript
// rooms can be archived
room.archive()
    .then(() => {
        // the room is now marked as archived
        console.assert(room.isArchived() == true);

        // now let us move it back out of the archive
        return room.unarchive();
    })
    .then(() => {
        // the room is now not marked as archived
        console.assert(room.isArchived() == false);
    })
    .catch((error) => {
        // e.g. if the server times out
    });

```

--------------------------------

### room.getUser()

Source: https://github.com/kabelwerk/sdk-js/blob/master/docs/rooms.md

Retrieves the user associated with the room, returning their ID, key, and name.

```APIDOC
## room.getUser()

### Description
Returns the room's user, as an `{ id, key, name }` object.

### Method
GET

### Endpoint
/room/user

### Response
#### Success Response (200)
- **user** (object) - An object containing the user's id, key, and name.
```

--------------------------------

### room.on(event, listener)

Source: https://github.com/kabelwerk/sdk-js/blob/master/docs/rooms.md

Attaches an event listener to the room. Returns a string identifier for the listener that can be used with `room.off()`.

```APIDOC
## room.on(event, listener)

### Description
Attaches an event listener. See [list of events](#list-of-events) for a list of available events. Returns a short string identifying the attached listener — which string can be then used to remove that event listener via the `room.off(event, ref)` method.

### Method
POST

### Endpoint
/room/event-listener

### Parameters
#### Request Body
- **event** (string) - Required - The name of the event to listen for.
- **listener** (function) - Required - The callback function to execute when the event is triggered.
```

--------------------------------

### User Management

Source: https://github.com/kabelwerk/sdk-js/blob/master/website/versioned_docs/version-0.3.6/kabelwerk.md

Retrieve and update the connected user's information.

```APIDOC
## User Management

### Description
Access and modify the currently connected user's profile information.

### Methods
- `Kabelwerk.getUser()`: Retrieves the current user object.
- `Kabelwerk.updateUser(user)`: Updates the current user's information on the server.

### Parameters
#### `Kabelwerk.updateUser(user)`
- **user** (object) - Required - The user object with updated properties.

### Response
#### Success Response (200)
- **user** (object) - The updated user object.

### Request Example
```js
let user = Kabelwerk.getUser();
user.name = 'Nana';

Kabelwerk.updateUser(user)
    .then((updatedUser) => {
        console.assert(updatedUser.name == 'Nana');
        console.assert(Kabelwerk.getUser().name == 'Nana');
    })
    .catch((error) => {
        console.error('Failed to update user:', error);
    });
```
```

--------------------------------

### room.once(event, listener)

Source: https://github.com/kabelwerk/sdk-js/blob/master/website/versioned_docs/version-0.3.6/rooms.md

Attaches an event listener that will be invoked only once. The listener is automatically removed after its first invocation.

```APIDOC
## room.once(event, listener)

### Description
The same as the `room.on(event, listener)` method, except that the listener will be automatically removed after being invoked — i.e. the listener is invoked at most once.

### Parameters
#### Path Parameters
- **event** (string) - Required - The name of the event to listen for.
- **listener** (function) - Required - The callback function to execute when the event is triggered.
```

--------------------------------

### Kabelwerk.updateUser(attributes)

Source: https://github.com/kabelwerk/sdk-js/blob/master/docs/kabelwerk.md

Updates the connected user's name. Returns a Promise.

```APIDOC
## Kabelwerk.updateUser(attributes)

### Description
Updates the connected user's name. Expects a `{ name }` object and returns a Promise.

### Method
```
Kabelwerk.updateUser(attributes)
```

### Parameters
#### Request Body
- **attributes** (object) - Required - An object containing the user's name.
  - **name** (string) - Required - The new name for the user.
```

--------------------------------

### Open Inbox with Filter Parameters

Source: https://github.com/kabelwerk/sdk-js/blob/master/docs/inboxes.md

Use filter parameters when opening an inbox to select specific rooms. This is useful for isolating archived, assigned, or attribute-filtered rooms.

```javascript
const params = {
    // select only archived rooms
    archived: true,

    // select only rooms assigned to the connected user
    assignedTo: Kabelwerk.getUser().id,

    // select only unassigned rooms
    assignedTo: null,

    // select only rooms with the specified attributes
    // (attributes are usually set on the end user side)
    attributes: {
        country: 'DE',
    },
};

let inbox = Kabelwerk.openInbox(params);

inbox.on('ready', ({ items }) => {
    // all rooms are archived, unassigned, and belong to users from Germany
});

inbox.on('updated', ({ items }) => {
    // only fired for inbox items the rooms of which meet the criteria set by
    // the params
});

inbox.connect();
```

--------------------------------

### Update Room Custom Attributes

Source: https://github.com/kabelwerk/sdk-js/blob/master/website/versioned_docs/version-0.3.6/rooms.md

Use `getAttributes` to retrieve custom attributes, modify them locally, and then use `updateAttributes` to persist the changes. The resolved value of `updateAttributes` is a copy of the updated attributes.

```javascript
let attributes = room.getAttributes();
attributes.country = 'DE';
room.updateAttributes(attributes)
    .then((attributes) => {
        console.assert(attributes.country == 'DE');
        console.assert(room.getAttributes().country == 'DE');
    })
    .catch((error) => {
    });

```

--------------------------------

### inbox.loadMore()

Source: https://github.com/kabelwerk/sdk-js/blob/master/docs/inboxes.md

Loads additional inbox items. This method returns a Promise that resolves into an `{items}` object containing the updated list of inbox items.

```APIDOC
## inbox.loadMore()

### Description
Loads more items. Returns a Promise which resolves into a `{items}` object containing the updated list of inbox items.

### Method
`inbox.loadMore()`
```

--------------------------------

### Inbox Management

Source: https://github.com/kabelwerk/sdk-js/blob/master/website/versioned_docs/version-0.3.6/kabelwerk.md

Open a new inbox for the connected user.

```APIDOC
## Inbox Management

### Description
Open a new inbox for the currently connected user.

### Method
- `Kabelwerk.openInbox()`: Opens a new inbox.

### Response
- The method returns an inbox object. Refer to the [inboxes](./inboxes.md) documentation for details.

### Request Example
```js
let inbox = Kabelwerk.openInbox();
```
```

--------------------------------

### Kabelwerk.disconnect()

Source: https://github.com/kabelwerk/sdk-js/blob/master/docs/kabelwerk.md

Removes all event listeners and closes the connection to the Kabelwerk server.

```APIDOC
## Kabelwerk.disconnect()

### Description
Removes all previously attached event listeners and closes the connection to the server.

### Method
```
Kabelwerk.disconnect()
```
```

--------------------------------

### room.getMarkers()

Source: https://github.com/kabelwerk/sdk-js/blob/master/website/versioned_docs/version-0.3.6/rooms.md

Retrieves the room's markers, which indicate user positions in the chat history. Returns an object containing user and hub markers or null values.

```APIDOC
## room.getMarkers()

### Description
Returns the room's pair of markers; the first item of the pair is the connected user's marker and the second item — either the latest hub-side marker or the end user's marker, depending on whether the connected user is an end user or a hub user, respectively. Each pair item is either a `{ messageId, updatedAt, userId }` object or `null` if the respective marker does not exist.
```

--------------------------------

### Archive and Unarchive Room

Source: https://github.com/kabelwerk/sdk-js/blob/master/website/versioned_docs/version-0.3.6/rooms.md

Rooms can be archived and unarchived using the `archive` and `unarchive` methods respectively. These methods return promises that resolve when the operation is complete.

```javascript
room.archive()
    .then(() => {
        console.assert(room.isArchived() == true);
        return room.unarchive();
    })
    .then(() => {
        console.assert(room.isArchived() == false);
    })
    .catch((error) => {
    });

```

--------------------------------

### Notifier Events

Source: https://github.com/kabelwerk/sdk-js/blob/master/docs/notifiers.md

This section describes the events that the Notifier object can emit.

```APIDOC
## Events

### error

Fired when there is a problem establishing a connection to the server (e.g., due to a timeout). Attached listeners are called with an extended Error instance.

### ready

Fired at most once when the connection to the server is first established. Attached listeners are called with a `{messages}` object containing a list of messages not yet marked by the connected user. This event can be used to display a potentially large number of notifications upon opening the client.

### updated

Fired when a new message is posted in any of the rooms the connected user has access to. Also fired upon reconnecting for each message posted while the websocket was disconnected. Attached listeners are called with an `{message}` object.
```

--------------------------------

### room.getMarkers()

Source: https://github.com/kabelwerk/sdk-js/blob/master/docs/rooms.md

Retrieves the room's markers, which indicate the user's position in the chat history. Returns an object with the connected user's marker and the latest hub-side or end-user marker.

```APIDOC
## room.getMarkers()

### Description
Returns the room's pair of markers; the first item of the pair is the connected user's marker and the second item — either the latest hub-side marker or the end user's marker, depending on whether the connected user is an end user or a hub user, respectively. Each pair item is either a `{ messageId, updatedAt, userId }` object or `null` if the respective marker does not exist.

### Method
GET

### Endpoint
/room/markers

### Response
#### Success Response (200)
- **markers** (array) - An array containing two marker objects, representing the connected user's marker and the other relevant marker.
```

--------------------------------

### Kabelwerk.off(event, ref)

Source: https://github.com/kabelwerk/sdk-js/blob/master/docs/kabelwerk.md

Removes one or more previously attached event listeners. Both parameters are optional.

```APIDOC
## Kabelwerk.off(event, ref)

### Description
Removes one or more previously attached event listeners. Both parameters are optional: if no `ref` is given, all listeners for the given `event` are removed; if no `event` is given, then all event listeners attached to the Kabelwerk object are removed.

### Method
```
Kabelwerk.off(event, ref)
```

### Parameters
#### Query Parameters
- **event** (string) - Optional - The event to remove listeners from.
- **ref** (string) - Optional - The reference of the specific listener to remove.
```

--------------------------------

### Assign and Unassign Room to Hub User

Source: https://github.com/kabelwerk/sdk-js/blob/master/website/versioned_docs/version-0.3.6/rooms.md

Rooms can be assigned to a specific hub user using `updateHubUser` with the user's ID, or unassigned by passing `null`. The `getHubUser` method can be used to check the current assignment.

```javascript
room.updateHubUser(Kabelwerk.getUser().id)
    .then(() => {
        console.assert(room.getHubUser().id == Kabelwerk.getUser().id);
        return room.updateHubUser(null);
    })
    .then(() => {
        console.assert(room.getHubUser() == null);
    })
    .catch((error) => {
    });

```