@widget-kit/rpc

Establishes connection between two windows allowing both to send and handle requests.

Install

``bash
$ npm install --save @widget-kit/rpc
`

Usage

`js
// Main window:
const hostConnection = createConnection(
iframe.contentWindow,
'https://remote.example.com'
);

hostConnection.handle('ping', (respond) => {
respond('pong');
});

// Iframe (loaded from https://remote.example.com):
const widgetConnection = createConnection(window.parent);
const pingRequest = createRequest('ping');
widgetConnection.send(pingRequest, (response) => {
console.log(response.payload); // prints 'pong'
});
`

API Reference

$3

Returns Connection object with send and handle methods.

- targetWindow: a reference to remote window.
- targetOrigin: allows to restrict windows communication by origin. If targetWindow origin does not match no request would be sent nor accepted from it.

$3

Sends prepared request.

- request: a plain object containing request method, arguments list and set of service fields. Use createRequest helper to create proper request object.
- onResponse: response handler. Accepts Response object with payload and optional error fields.

$3

Registers request handler for a given method.

- method: an unique method identifier. It's recommended to have prefix with your app name for custom methods (like myAwesomeApp.analytics.sendEvent).
- handler: a handler function that accepts response callback and method arguments. You can call response callback at any time passing to it result or error.

Example:

`js
connection.handle('myapp.divide', (respond, a, b) => {
if (b === 0) {
respond(null, 'Whoops, you\'re trying to divide by zero!');
} else {
respond(a / b);
}
});
`

$3

Creates request object that could be sent later.

- method: a name of the called method.
- args: arguments that would be passed to method handler.

Example:

`js
// We can make own "request creator" helper
const sum = (a, b) => createRequest('myapp.sum', a, b);

// And then send this request with different arguments easily
connection.send(sum(1, 1));
connection.send(sum(5, 5));
``