@meso-network/post-message-bus NPM

`@meso-network/post-message-bus`

post-message-bus is a Meso-specific library for sending strongly typed messages across frames (iframes and parent windows) using postMessage.

It is currently unavailable for standalone use.

View the CHANGELOG or read the meso-js docs.

@meso-network/post-message-bus
- Usage
  - From a parent frame (window)
  - From inside an iframe
- Reference

Usage

From a parent frame (window)

import { createPostMessageBus } from "@meso-network/post-message-bus";

// Initialize the bus by providing an origin of the iframe to communicate with.
const bus = createPostMessageBus("https://iframe.origin");

// Listen for events
bus.on("CLOSE", () => {
  console.log("close event called");
});

From inside an iframe

import { createPostMessageBus } from "@meso-network/post-message-bus";

// Initialize the bus by providing an origin of the parent frame to communicate with.
const bus = createPostMessageBus(window.location.ancestorOrigins[0]);

// Listen for events
bus.on("RETURN_SIGNED_MESSAGE_RESULT", (message) => {
  console.log(message); // { payload: { signedMessage: "some-string" }}
});

// Emit events
bus.emit("REQUEST_SIGNED_MESSAGE", {
  payload: {
    messageToSign: "a message to be signed",
  },
});

Reference

You can view the full type definitions here.

`createPostMessageBus`

The createPostMessageBus function accepts target origin to establish postMessage communication.

The origin must be valid (<protocol>://<domain>) and cannot be *.

The function returns either postMessageBus object or an initialization error.

`PostMessageBus`

type PostMessageBus = {
  /**
   * Subscribe to an event using the message kind (name).
   *
   * The attached handler will be invoked each time this event is seen until the event handler is detached.
   */
  on: (eventKind: MessageKind, handler: PostMessageHandlerFn) => PostMessageBus;

  /**
   * Send a message to a specific [origin](https://developer.mozilla.org/en-US/docs/Web/API/Location/origin). If the `targetOrigin` is omitted, the message will be broadcast to all origins (`*`).
   */
  emit: (message: Message, targetOrigin?: string) => PostMessageBus;

  /**
   * Detach event handlers and end post message communications.
   */
  destroy: () => void;
};

`PostMessageBusInitializationError`

type PostMessageBusInitializationError = {
  /**
   * A _developer_ friendly message containing details of the error.
   */
  message: string;
};

Subscribe to events

You can subscribe to message events by using the .on method from the returned instance.

The method takes two arguments:

eventKind: MessageKind – which message you'd like to subscribe to
- REQUEST_SIGNED_MESSAGE: Request from Meso experience to parent window to initiate signing.
- RETURN_SIGNED_MESSAGE_RESULT: Dispatch the result of a signature request from the parent window to the Meso experience.
- CLOSE: Dispatch a message from the Meso experience to the parent window to close the experience.
- TRANSFER_UPDATE: Dispatch a message from the Meso experience to the Partner Window when the transfer has been updated.
- ERROR: Dispatch an error message from the Meso experience to the parent window.
handler: PostMessageHandlerFn – a callback that accepts two arguments:
- message: Message – a strongly typed message (see types)
- reply: (message: Message) => void – an optional reply callback to that the handler in the other frame can call with a structured message (see types).