npm package: @finqu/app-link
Description: AppLink for Finqu Apps.
Author: Finqu
Latest version: 4.1.3

# 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

```bash
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.

```typescript
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:

```typescript
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:

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

## Usage examples

**Dialog (show and close):**

```typescript
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):**

```typescript
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](https://developers.finqu.com)**

## License

MIT © [Finqu](https://github.com/finqu)