Finqu AppLink

AppLink lets Finqu Apps talk to Finqu services over PostMessage. Use it to build embedded admin UIs, dialogs, and resource views that run inside the Finqu Commerce administration.

Installation

npm install @finqu/app-link

Quick start

Create an app instance with your app id and (for admin views) the administration origin. The origin is used to validate PostMessage communication. You can fetch the admin URL from the OAuth 2.0 resource.

import { App } from '@finqu/app-link';

const app = App.create('my-app-id', 'https://my-admin-url.myfinqu.com');

Run your logic once the app is ready:

app.ready(() => {
  console.log('App ID:', app.getId());
  console.log('Session ID:', app.getSessionId());
});

Core API

| Method | Description | | --------------------------------- | -------------------------------------------------------------------------------------------------------------- | | App.create(appName, origin?) | Create and initialize an app. origin defaults to '*'; set it to your admin URL for Commerce admin iframes. | | app.ready(fn) | Run a callback when the app is initialized (or immediately if already initialized). | | app.getId() | Get the app instance id from the host. | | app.getSessionId() | Get the current session id. | | app.dispatch(message) | Send a message to the host. | | app.subscribe(group?, callback) | Subscribe to messages; optionally filter by ComponentGroup. Returns an unsubscribe function. | | app.getResizer() | Get the iframe-resizer API when running inside a resizable iframe, or null. |

Features

• App and lifecycle — App.create(), app.ready(), app.getId(), app.getSessionId().
• Component groups — Filter messages with app.subscribe(ComponentGroup.Dialog, callback).
• Dialogs — Dialog, Confirm, ConfirmRemove, Loader for modal UI.
• Navigation — History, Redirect for routing and navigation.
• Resources — Resource with ResourceType for product, order, customer, etc.
• Feature — Feature for host-driven feature flags (subscribe to NEW, UPDATE, REMOVE).

Import components and types from the main package:

import { App, ComponentGroup, Dialog, ResourceType } from '@finqu/app-link';

Usage examples

Dialog (show and close):

const dialog = Dialog.create(app, {
  title: 'My Dialog',
  content: 'Hello',
  buttons: { confirm: 'OK', close: 'Cancel' },
});
await dialog.show();
const result = await dialog.done();

Resource (dispatch and subscribe):

const resource = Resource.create(app);
resource.dispatch(Resource.Action.SAVE, {
  id: '123',
  type: ResourceType.PRODUCT,
  data: { name: 'Foo' },
});
resource.subscribe(Resource.Action.DONE, (payload) =>
  console.log('Saved', payload),
);

Host API (parent page): use Host, Client, ComponentRef, and bootstrap from the same package to register iframes and handle component creation. See JSDoc on those classes for examples.

Documentation

Full documentation: Finqu Developers

License

MIT © Finqu