Tradeshift / io

Tradeshift App Messaging Library
Other
3 stars 7 forks source link
api api-client api-server docs javascript messaging-library npm-module tradeshift

npm Github

ts.io

Tradeshift App Messaging Library

This is the standard way for apps on the client-side of the Tradeshift Platform to

Why?

Limitations

Installation

npm install @tradeshift/io

Usage

import io from '@tradeshift/io';

// Create the App and connect to the Hub
const app = io();

// Spawn an App:
(async () => {
  // Do the actual spawn call
  const [err, data] = await app.spawn(targetApp, targetData);

  if (err) {
    // Something went horribly wrong while spawning app
  } else {
    doSomethingWith(data);
  }
})();

// Allow your app to be spawned by others:
app.define({
  async spawn(data) {
    // Wait for user input here...
    const userData = await myPrompt();

    // Send response back to parent
    return userData;
  }
});

ts.io API reference (quick overview)

Spawning another app

import io from '@tradeshift/io';
const app = io();

const [err, data] = await app.spawn(targetApp, targetData);

Defining app lifecycle when others spawn your app

To handle the request from other apps, an app needs to define a spawn handler. The recommended API uses promises to allow an async/await style handler, and makes it possible to do a series of async transitions before returning the value to the parent app.

import io from '@tradeshift/io';
const app = io();

app.define({
  async spawn(data) {
    // CODE HERE: Animate opening your UI and wait for user input.

    // Wait for user input here...
    const userData = await myPrompt();

    // CODE HERE: Animate closing your UI.

    // Send response back to parent
    return userData;
  }
});

Callback based Spawn handler if you prefer:

app.define({
  spawn(data, submit, parent) {
    // Send response back to parent
    submit(userData);
  }
});

Talking to other apps w/ events

import io from '@tradeshift/io';
const app = io();

// Events
/*
 * IMPORTANT!
 * You can register as many handlers as you'd like,
 * but if multiples match the same topic,
 * they all will be called, in the order they were registered.
 */

// Listen to all events sent to my App
app.on('*', (event) => {});

// Listen to events for a specific topic (sent to my App)
const myListener = (event) => {};
const myTopic = 'my-topic';
const unlisten = app.on(myTopic, myListener);
// Stop listening
unlisten();
// OR
app.off(myTopic, myListener); // nice to have

// This listener will only be called once
app.once(myTopic, myListener); // nice to have

// Send events to other Apps
// app.emit(topic[, data], app);
app.emit('fly-high', { flameColor: 'red' }, 'Tradeshift.FlamingSkull');

Experimental request API

(async () => {
  const [err, response] = await app1.emit('topic-with-request', 'App2', data);
  if (err) {
    // Something went horribly wrong while emitting
  } else {
    doSomethingWith(response);
  }
})();
app1.emit('topic-with-request', 'App2', data);
app1.emit('topic-without-request', 'App2', data);

app2.on('topic-with-request', (event) => {
  return 'my-response';
});

app2.on('topic-without-request', (event) => {});