# App Bridge SDK

> Every function, option, limit and error of @foodpilot/app-bridge, for the browser and for your server.

Source: https://developers-staging.foodpilot.tech/sdk/app-bridge

The reference of `@foodpilot/app-bridge` version `0.1.0`. How to use it in an embedded page is in [App Bridge](/build/app-bridge); a complete example is the [product tab tutorial](/tutorials/product-tab).

```bash
npm install @foodpilot/app-bridge jose
```

The package is on npm, under the MIT license: [@foodpilot/app-bridge](https://www.npmjs.com/package/@foodpilot/app-bridge).

Two entry points: `@foodpilot/app-bridge` for the browser, `@foodpilot/app-bridge/server` for your server (Node.js 22.22 or later, with `jose`).

## Browser: `createApp(options)`

Connects the page to the platform page that frames it, and returns an `App`.

| Option | Type | Meaning |
|---|---|---|
| `allowedHosts` | `string[]` or `(origin) => boolean` | The exact web origins of the platforms allowed to frame the app. List explicit origins, not a wildcard on a parent domain |
| `timeoutMs` | `number` | How long a request waits for the host's reply. Default `10000` |

`createApp` throws `HostOriginError` unless the page is framed, its `host` query parameter decodes to one origin, that origin is allowed, and, when the browser says who frames the page, it is the same one.

The platform opens your `app_url` with the query parameters `embedded=1`, `platform`, `locale` and `host` (the host origin in base64url).

## `App`

| Member | Returns | What it does |
|---|---|---|
| `hostOrigin` | `string` | The verified origin of the framing page. A hint only: identity comes from the session token |
| `ready()` | `Promise<void>` | Tells the host the page has loaded, so it hides its loading placeholder |
| `getSessionToken()` | `Promise<string>` | A 60-second token for the current user and organization. Send it to your server and verify it there |
| `toast({ message, kind })` | `Promise<void>` | Shows a toast. `kind` is `info`, `success` or `error` |
| `confirm({ message, confirmLabel })` | `Promise<boolean>` | Asks the user to confirm. Waits as long as the person takes |
| `navigate.app(path)` | `Promise<void>` | Goes to another page of your app: the path must stay under your `app_url` path |
| `navigate.foodpilot(path)` | `Promise<void>` | Goes to an allowed area of the platform, such as `/products` |
| `title(title)` | `Promise<void>` | Sets the page title |
| `loading(on)` | `Promise<void>` | Shows or hides the progress bar under the header |
| `resize(height)` | `Promise<void>` | Extension slots only: sets the frame height in CSS pixels, clamped to the slot's range. A full page gets `unsupported` |
| `autoResize()` | `() => void` | Extension slots only: follows the document height and resizes at most every 100 ms. Returns a function that stops it |
| `context()` | `Promise<{ slot, extensionId, productId? }>` | Extension slots only: where the page is shown. A hint only: use the session token's `slot` and `ctx` on your server |
| `destroy()` | `void` | Stops listening and rejects the pending requests |

## Limits

| What | Limit |
|---|---|
| Toast message | 200 characters |
| Confirm message | 500 characters |
| Confirm button label | 30 characters |
| Title | 100 characters |
| One message | 8 KB |
| Messages the host answers | 50 per second per app |

A request beyond a limit is rejected in your page and never sent.

## Errors

`AppBridgeError` carries a `code`:

| Code | Meaning |
|---|---|
| `unsupported` | The host does not do this here, for example `resize` on a full page |
| `invalid` | The request is malformed |
| `refused` | The host refuses it, for example a navigation outside the allowed areas |
| `throttled` | Too many messages |
| `unavailable` | The host cannot do it now |
| `timeout` | No reply within `timeoutMs` |
| `destroyed` | `destroy()` was called |
| `bad-reply` | The host's reply could not be read |

## Server: `verifySessionToken(token, options)`

```ts
```

Verifies the signature against the platform's published keys (RS256), the issuer, the audience and the time, then checks the claims against the installation you recorded. Returns the claims.

| Option | Meaning |
|---|---|
| `apiOrigin` | The API origin of the platform the installation was made on: the token's issuer and where the keys come from |
| `appOrigin` | The web origin of that platform: the token's `dest` |
| `clientId` | Your app's client id: the token's audience |
| `platform` | The platform name recorded at install |
| `installationId` | The installation id recorded at install |
| `organizationIds` | The organizations the installation covers: `coveredOrganizationIds` of `GET /api/app/v1/installation` |
| `clockToleranceSeconds` | Default `5` |

| Claim | Meaning |
|---|---|
| `sub` | The user |
| `org` | The organization the user works in |
| `inst` | The installation |
| `platform`, `locale` | The platform and the user's language |
| `jti` | Unique per token: accept it once for anything that changes data |
| `slot`, `ctx` | In an extension slot: the slot, and its context, such as `ctx.productId` |

`SessionTokenError` carries a `code`: `invalid_token`, `expired`, `claim_mismatch` (with the offending `claim`), `jwks_unavailable` or `bad_configuration`.
