App Bridge SDK
The reference of @foodpilot/app-bridge version 0.1.0. How to use it in an embedded page is in App Bridge; a complete example is the product tab tutorial.
npm install @foodpilot/app-bridge jose
The package is on npm, under the MIT license: @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)
import { verifySessionToken, SessionTokenError } from '@foodpilot/app-bridge/server';
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.