Skip to main content

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.

OptionTypeMeaning
allowedHostsstring[] or (origin) => booleanThe exact web origins of the platforms allowed to frame the app. List explicit origins, not a wildcard on a parent domain
timeoutMsnumberHow 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​

MemberReturnsWhat it does
hostOriginstringThe 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()() => voidExtension 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()voidStops listening and rejects the pending requests

Limits​

WhatLimit
Toast message200 characters
Confirm message500 characters
Confirm button label30 characters
Title100 characters
One message8 KB
Messages the host answers50 per second per app

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

Errors​

AppBridgeError carries a code:

CodeMeaning
unsupportedThe host does not do this here, for example resize on a full page
invalidThe request is malformed
refusedThe host refuses it, for example a navigation outside the allowed areas
throttledToo many messages
unavailableThe host cannot do it now
timeoutNo reply within timeoutMs
destroyeddestroy() was called
bad-replyThe 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.

OptionMeaning
apiOriginThe API origin of the platform the installation was made on: the token's issuer and where the keys come from
appOriginThe web origin of that platform: the token's dest
clientIdYour app's client id: the token's audience
platformThe platform name recorded at install
installationIdThe installation id recorded at install
organizationIdsThe organizations the installation covers: coveredOrganizationIds of GET /api/app/v1/installation
clockToleranceSecondsDefault 5
ClaimMeaning
subThe user
orgThe organization the user works in
instThe installation
platform, localeThe platform and the user's language
jtiUnique per token: accept it once for anything that changes data
slot, ctxIn 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.