Frame Link is a promise-based API built on `window.postMessage`. It allows a two-way communication between a parent page and a child `iframe`.

- [Features](#features)
- [Installing](#installing)
- [Glossary](#glossary)
- [Usage](#usage)
- [API](#api)

---

## Features

- Promise-based API for elegant and simple communication.
- Two-way parent <-> child handshake, with message validation.
- Provides capability to invoke aiWARE functionality from the child frame

## Installing

`npm install aiware-frame-link`

## Glossary

- **`Parent`**: The **top level** aiWARE Desktop application that embeds an onboarded application in an `<iframe ... />`, creating a `Child`.
- **`Child`**: The **bottom level** web page loaded within the `<iframe ... />`.
- **`Handshake`**: The process of initialization of the FrameLink inside both `Parent` and `Child` by the end of which both instances exchange _initiation_ packets and kick off heartbeat sending/monitoring process that allows `Parent` to handle scenarios when the `Child` frame cannot be loaded (e.g.: `503`) or its application freezes.

## Usage

- `Child` is expected to have headers that allow porting the application via iframe. This means that potential attackers can port the onboarded app anywhere posting messages to the child frame at any rate. Implement throttling and rate-limiting mechanisms to prevent abuse and excessive message sending.
- The `Child` begins communication with the `Parent`. A handshake is started when the `Child` sends a heartbeat and requests the initial context.
- Upon receiving request for initial context `Parent` completes its initialization and sends a response with the context requested
- `Parent` validates messages from the `Child` by checking sender's URL against registry of known applications. `Child` does not have means to validate messages from the `Parent` since `Parent` can be deployed on multiple domains and such domains can change without or on a short notice.
- **It is strongly advised that `Child` does not provide any sensitive information such as authentication tokens, etc to the message sender.**

---

### Example

**desktop.us-1.veritone.com**

```javascript
// create FrameLink instance in the top-level component
const [frameLink, setFrameLink] = useState(null);

// error action that will be invoked in the Desktop Application
const errorAction = (message: string) => {
  dispatch(
    showMessage({
      content: message,
      severity: MessageSeverity.Error,
    })
  );
};

// listen to the child application URL changes
useEffect(() => {
  if (childApplicationUrl) {
    // initiate FrameLink if a child app was selected from the App Switcher
    AiwareFrameLink.init({
      origin: childApplicationUrl, // pass the URL of the child app as the 'origin'
      errorAction, // pass a function that will take error message string as a param if you wish to handle errors
    }).then(link => {
      setFrameLink(link); // set FrameLink instance in the state
    });
  } else {
    // if the child application was closed, reset FrameLink instance to 'null'
    setFrameLink(null);
  }
}, [childApplicationUrl]);
```

**child-app.com**

```javascript
import { isIFrame, TContext, AiwareFrameLink } from 'aiware-frame-link'
...
const TopLevelComponent = () => {

  const [link, setLink] = useState<typeof AiwareFrameLink>();

  // subscriber functions will receive argument of type TContext
  const subscriberFunc = (context: TContext) => {
      // do something with aiWARE context
  }


  useEffect(() => {
  // when component renders for the first time
    if (isIFrame()) { // check if the app is running inside the iframe using provided helper function
      AiwareFrameLink.init({
        // pass subscriber functions
        subscribers: [subscriberFunc]
      })
      .then((link: typeof AiwareFrameLink) => {
        setLink(link) // set FrameLink instance in the component state
      }
      )
    }
  }, [])
}
```

This library exports `AiwareFrameLinkContext: React.Context<AiwareFrameLink>` to allow passing FrameLink instance down the component tree in applications that use `React` library

---

## API

> ## `AiwareFrameLink.init`

```javascript
// Parent
AiwareFrameLink.init({
  origin: 'https://child-app.com',
  errorAction,
  intl,
  store,
});

// Child
AiwareFrameLink.init({
  subscribers,
  errorAction,
});
```

| Name           | Type                                 | Description                                                                                                                                                  |
| -------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `origin?`      | `string`                             | _Child application URL. This parameter is only passed when initiating in Parent_                                                                             |
| `errorAction?` | `(errorMessage: String) => unknown)` | _Function that is invoked when error occurs_                                                                                                                 |
| `subscribers?` | `((context: TContext) => unknown)[]` | _Array of functions that are invoked when a child app receives aiWARE context. Passed only in Child initialization_                                          |
| `intl?`        | `IntlShape`                          | _Instance of 'react-intl' to support. Passed only in parent initialization as Child apps are expected to handle their own error message translations if any_ |
| `store?`       | `IModuleStore<unknown>`              | _Parent application store for scenarios where its data is needed to communicate with a Child. Passed only in parent initialization_                          |

#### FrameLink Context

To allow Child frame communicate with aiWARE API Parent frame provides `context: TContext` upon establishing handshake. Such context contains the following properties that should be sufficient to authenticate/interact with aiWARE API services:

```javascript
// example context:
const context = {
  environment: 'us-1',
  baseUrl: 'https://api.us-1.veritone.com/v3/graphql',
  authToken: 'a5c09131-v51a-4991-b830-e5860e0087f2',
  theme: 'light',
  language: 'en',
  userId: 'a5c09131-v51a-4991-b830-e5860e0087f2',
  organizationId: '1',
};
```

---

> ## `AiwareFrameLink.on`

```javascript
// Parent
AiwareFrameLink.on(event, callback);
```

| Name       | Type                             | Description                                                                                                                                |
| ---------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `event`    | `EFrameLinkEvents`               | _Name of a supported event_                                                                                                                |
| `callback` | `(payload?: unknown) => unknown` | _Callback function executed when event is emitted. Function take an optional payload supplied by the event handler logic in the FrameLink_ |

#### Supported events

- `init` - currently Parent event only, emitted when parent is initialized and receives a heartbeat + initial context request from a Child

---

> ## `AiwareFrameLink.postMessage`

```javascript
// Child
AiwareFrameLink.postMessage(message, payload);
```

| Name       | Type            | Description                                                                                  |
| ---------- | --------------- | -------------------------------------------------------------------------------------------- |
| `message`  | `EMessageTypes` | _supported message or event name that invokes respective logic in the AiWareFrameLink class_ |
| `payload?` | `any`           | _optional payload for a message_                                                             |

#### Supported messages

```javascript
enum EMessageTypes {
  getInitContext = 'getInitContext',
  initContext = 'initContext',
  updateContext = 'updateContext',
  reportActivity = 'reportActivity',
  response = 'response',
  utility = 'utility',
  error = 'error',
  heartbeat = 'heartbeat',
}
```

---

> ## `AiwareFrameLink.useUtility`

```javascript
// Child
AiwareFrameLink.useUtility(Utilities.filePicker, data);
```

| Name      | Type        | Description                                 |
| --------- | ----------- | ------------------------------------------- |
| `utility` | `Utilities` | _one of the supported utilities_            |
| `data?`   | `any`       | _optional payload for a utility invokation_ |

#### Supported Utilities

- `filePicker` - opens File Importer panel allowing to select files to upload. Upon uploading files to the Data Center this utility returns a response with a list of created TDO IDs to the Child frame `{ requestId: string, data: { tdoIds: string[] } }`

---

> ## `AiwareFrameLink.subscribe`

```javascript
// Child
AiwareFrameLink.subscribe(subscriberFunction);
```

| Name                 | Type                             | Description                                                                                     |
| -------------------- | -------------------------------- | ----------------------------------------------------------------------------------------------- |
| `subscriberFunction` | `(context: TContext) => unknown` | Subscriber function that is invoked when a child app receives initial or updated aiWARE context |

---

## Troubleshooting/FAQ

### General

#### The child does not respond to communication from the Parent

> _Make sure that you have initialized Frame Link in your child page and that your application was onboarded to aiWARE platform._

#### I want to retrieve information from the parent by the child

> _By design FrameLink is restrictive in its communication between frames allowing only specific types of messages or requests. Future versions of the Frame Link will have new types of messages and utilities enabled for the `Child` to send or invoke._

#### I cannot send a message from Child to Parent

> _Frame Link comes with a guard around messages that can be sent only one-way. E.g.: `initialContext` can only be send from `Parent` to `Child`._

#### How do I make sure that incoming message is from a valid parent?

> _`Parent` is secured by validating message sender comparing its URL against the list of onboarded applications. Senders from unknown destantions will be ignored. But once `Child` allows porting itself via iframe it can be technically ported into any application. This is why we strongly advise to avoid sharing any sensitive information in responses to the `Parent`. Frame Link was intended to allow `Child` become a consumer of the parent information/methods. `Parent` does not expect any authentication or other sensitive information from the `Child`._

#### How can I secure my application if it's ported via attacker's iframe?

> _We strongly advise to sanitize data you receive in communication with `Parent` to prevent injection attacks or other security vulnerabilities._