npm package: @studio.sandbox/stdio-post-message
Description: A small API built on top of `postMessage` to allow secure bi-directional communication between multiple children (iframes) and their parent.
Author: Hannes Stein
Latest version: 1.2.2

# StdioPostMessage

**Caution: This library is in early development and not finished or officially published yet! - internal preview build**

> _StdioPostMessage_ is a small API built on top of `postMessage` to allow secure bi-directional communication between multiple children (iframes) and their parent.

## Features

    ✓ Communicate with children (iframes) or your parent window using [postMessage](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage)<br>
    ✓ Uses [promises](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) to enable message acknowledgement<br>
    ✓ Has a rate-limit such that your website cannot be spammed with events<br>
    ✓ No dependencies<br>
    ✓ Works with multiple iframe tags<br>
    ✓ Up to 10 message retries<br>

## Requirements

This library uses ES2015+ features (e.x.: Array.prototype.includes, Promises, Spread-Operator) which you might need to polyfill depending on the targeted browser versions for your application when using bundlers. The umd dist file is compatible with IE11 and all other more modern browsers by default (polyfills included).

## Example

Please check the `/examples` folder to view the most basic implementation.

## Installing & Setup

```bash
$ npm install @studio.sandbox/stdio-post-message --save
```

```javascript
import StdioPostMessage from 'stdio-post-message'
const pm = new StdioPostMessage()
```

### App ready event

An event sent from the app, to let know the studio client that an app is completely loaded, meaning it has load
all it's ajax request, DOM is loaded, and it's ready to be used.
In order to emit this event, use the `emitToParent` event and set `APP_READY` as the event name.
There is no need to send anything in the payload, since the studio client will be tracking the timestamp itself.

## API

<!-- Generated by documentation.js. Update this documentation by updating the source code. -->

#### Table of Contents

-   [pmUtility](#pmutility)
-   [StdioPostMessage](#stdiopostmessage)
    -   [emitToChild](#emittochild)
    -   [emitToParent](#emittoparent)
    -   [setMessageListener](#setmessagelistener)
    -   [destroyMessageListener](#destroymessagelistener)
    -   [addAllowedOrigin](#addallowedorigin)
    -   [sendPerformanceObservations](#sendperformanceobservations)
-   [metricsCollected](#metricscollected)
-   [destroyPerformanceObserver](#destroyperformanceobserver)

### pmUtility

Copyright 2018 trivago N.V.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

     http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS-IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

Note: This is an unfinished lib still wip.

### StdioPostMessage

A helper to allow iframe communication using postMessage

**Parameters**

-   `config` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** the complete configuration object (optional, default `{}`)
    -   `config.methods` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** contains functions which are allowed to be called by others (optional, default `DEFAULT_METHODS`)
    -   `config.debug` **[Boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** logs information into the console (optional, default `DEFAULT_DEBUG`)
    -   `config.allowedOrigins` **[Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)&lt;[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)>** origin urls which are allowed to be communicated with (optional, default `DEFAULT_ALLOWED_ORIGINS`)
    -   `config.maxEventPerMinute` **[Number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)** rate limit of events one can receive per minute (optional, default `MAX_EVENTS_PER_MINUTE`)

#### emitToChild

Emit an event to a child (through an iframe)

**Parameters**

-   `data` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** the complete data object being handed over (optional, default `{}`)
    -   `data.payload` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** the data being handed over (optional, default `{}`)
    -   `data.event` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** the event name (optional, default `''`)
    -   `data.selector` **([String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) \| [Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object))** the css selector or element object of the iframe (optional, default `''`)
    -   `data.guaranteedDelivery` **[Boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** require a message acknowledgement (optional, default `true`)
    -   `data.retries` **[Number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)** amount of retries (if "guaranteedDelivery" is set to "true") (optional, default `1`)
    -   `data.messageTimeout` **[Number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)** amount of miliseconds after which you expect an acknowledgement (optional, default `MESSAGE_TIMEOUT`)

Returns **[Promise](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)** 

#### emitToParent

Emit an event to the parent (if you are within an iframe)

**Parameters**

-   `data` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** the complete data object being handed over (optional, default `{}`)
    -   `data.payload` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** the data being handed over (optional, default `{}`)
    -   `data.event` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** the event name (optional, default `''`)
    -   `data.url` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** the url of the parent you want to send the event to (optional, default `''`)
    -   `data.guaranteedDelivery` **[Boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** require a message acknowledgement (optional, default `true`)
    -   `data.retries` **[Number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)** amount of retries (if "guaranteedDelivery" is set to "true") (optional, default `1`)
    -   `data.messageTimeout` **[Number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)** amount of miliseconds after which you expect an acknowledgement (optional, default `MESSAGE_TIMEOUT`)

Returns **[Promise](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)** 

#### setMessageListener

Set global 'message' event listener

#### destroyMessageListener

Destroy global 'message' event listener

#### addAllowedOrigin

Add a new url to the allowed origins

**Parameters**

-   `url` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** a complete url (optional, default `false`)

#### sendPerformanceObservations

Send an event to parent along with the recorded performanceMetrics

**Parameters**

-   `payload` **[object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** the observed result by PerformanceObserver

### metricsCollected

Initializing performanceObserver
Metrics to observe: 'navigation', 'paint'
Send back the result to parent using emitToParent function

### destroyPerformanceObserver

Disconnect the performance observer to not have any further performance impact