# App API

This page is a reference for the App instance returned by `App.create()`. All methods are available after you have called `App.create(appName, origin)`.

## App.create(appName, origin?)

Creates and initializes an app. Call it once at startup.

**Parameters:**

- `appName` (string): Your app’s identifier.
- `origin` (string, optional): Target origin for PostMessage. Defaults to `'*'`. For Finqu Commerce admin iframes, set this to your admin URL (e.g. `https://my-admin-url.myfinqu.com`) so only the admin can communicate with your app.

**Returns:** An `App` instance.

**Example:**

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

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

## app.ready(fn)

Runs a callback when the app has been initialized by the host (or immediately if the app is already initialized). Use this before relying on `getId()` or `getSessionId()`.

**Parameters:**

- `fn` (function): Callback with no arguments. Called once when the host has sent the Initialize message (or right away if initialization already happened).

**Example:**

```typescript
app.ready(() => {
  const id = app.getId();
  const sessionId = app.getSessionId();
  // Safe to use id and sessionId here
});
```

## app.getId()

Returns the app instance id assigned by the host, or `null` if not yet initialized.

**Returns:** `string | null`

**Example:**

```typescript
app.ready(() => {
  const appId = app.getId();
  if (appId) {
    console.log('Instance ID:', appId);
  }
});
```

## app.getSessionId()

Returns the current session id from the host, or `null` if not yet initialized.

**Returns:** `string | null`

**Example:**

```typescript
app.ready(() => {
  const sessionId = app.getSessionId();
  // Use sessionId for API calls or logging
});
```

## app.dispatch(message)

Sends a message to the host. The app link will set `message.clientId` and `message.sessionId` from the current app state, and will ensure `message.payload` is an object (defaulting to `{}`).

**Parameters:**

- `message` (IMessage): A message object. You must set at least `component`, `action`, and typically `payload`. See [Messaging](messaging.mdx) for the `IMessage` shape.

**Returns:** `boolean` (true if the message was sent via PostMessage).

**Example:**

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

// After building a valid IMessage (e.g. from a component or helper):
app.dispatch(myMessage);
```

For building messages that the host understands (e.g. Dialog, Resource), you usually use the component APIs on the host side. From the app, you often subscribe to messages and optionally send callbacks. See [Messaging](messaging.mdx) and [Component groups and resources](component-groups-and-resources.mdx).

## app.subscribe(group?, callback)

Subscribes to messages from the host. You can subscribe to all messages or only those for a specific component group.

**Parameters:**

- `group` (ComponentGroup, optional): If provided, only messages whose `message.component.group` matches this value are passed to the callback. Omit to receive all messages.
- `callback` (function): Called with one argument, the `IMessage` object. Signature: `(message: IMessage) => void`.

**Returns:** A function that unsubscribes this listener when called.

**Examples:**

Subscribe to all messages:

```typescript
const unsubscribe = app.subscribe((message) => {
  console.log('Received:', message.action, message.component.group, message.payload);
});
// Later: unsubscribe();
```

Subscribe only to Dialog messages:

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

const unsubscribe = app.subscribe(ComponentGroup.Dialog, (message) => {
  if (message.action === 'Confirm') {
    // User confirmed a dialog
  }
});
```

Subscribe only to Resource messages:

```typescript
const unsub = app.subscribe(ComponentGroup.Resource, (msg) => {
  console.log('Resource action:', msg.action, msg.payload);
});
```

## app.unsubscribe(fn)

Removes a subscription that was added with `subscribe`. You can also use the function returned by `subscribe()` instead.

**Parameters:**

- `fn` (function): The same callback function you passed to `subscribe`.

**Example:**

```typescript
const handler = (message) => console.log(message);
app.subscribe(handler);
// Later:
app.unsubscribe(handler);
```

## app.getResizer()

Returns the iframe-resizer API when your app runs inside a resizable iframe (when the host uses iframe-resizer), or `null` otherwise. You can use this to e.g. send height updates to the parent.

**Returns:** The `parentIFrame` object from iframe-resizer, or `null`.

**Example:**

```typescript
app.ready(() => {
  const resizer = app.getResizer();
  if (resizer && typeof resizer.size === 'function') {
    resizer.size(400);
  }
});
```

## Summary

| Method | Description |
|--------|-------------|
| `App.create(appName, origin?)` | Create and initialize the app. `origin` defaults to `'*'`; use admin URL for Commerce 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.unsubscribe(fn)` | Remove a subscription. |
| `app.getResizer()` | Get the iframe-resizer API when in a resizable iframe, or `null`. |

Next: [Messaging](messaging.mdx) for the `IMessage` shape and patterns for subscribing and dispatching.