@1ecomm/app-bridge

The client SDK for building embedded apps on the 1ecomm commerce platform. It runs inside your app's sandboxed iframe and speaks a versioned, origin-validated postMessage protocol to the platform host, which holds your signed installation context and proxies scope-enforced API calls.

Zero dependencies, framework-agnostic, ~2 kB. Works with any stack that renders a page — React, Angular, Vue, or plain HTML.

Install

npm install @1ecomm/app-bridge

Quickstart

import { createAppBridge } from '@1ecomm/app-bridge';

const bridge = createAppBridge({ hostOrigin: 'https://developer.1ecomm.com' });

// Signed context: who installed you, where you're mounted, what you're granted.
const ctx = await bridge.getContext(); // { installationId, appId, siteId, accountId, userId, surfaceKey, grantedScopes, locale? }

// Scope-enforced platform data — the host attaches your session token.
const products = await bridge.apiFetch('/products', { query: { limit: '20' } });

// Writes take a JSON body.
await bridge.apiFetch(`/products/${id}/metafields/myapp/rating`, {
  method: 'PUT',
  body: { value: 5 },
});

// Host UI affordances.
bridge.resize(document.body.scrollHeight); // keep the iframe fitted
bridge.toast('Saved');
await bridge.modal({ title: 'Delete?', message: 'This cannot be undone.', variant: 'danger' });
bridge.navigate('/studio/apps'); // in-app host paths only

How it works

• Handshake. The SDK announces ready; the host answers with your signed AppBridgeContext. getContext() resolves then (or immediately once received).
• Origin validation. Every inbound message is checked against hostOrigin and the protocol channel/version; anything else is dropped.
• Nonce-matched requests. Every call is a promise matched to a host response by request id, with a timeout (timeoutMs, default 10 s).
• Scopes are server-enforced. apiFetch is proxied with your installation's session token; calls outside your granted scopes return a 403 naming the missing scope. Never store platform cookies or tokens yourself — the bridge is the only credential path you need.
• Cleanup. Call destroy() when your surface unmounts to detach the listener and reject in-flight requests.

API

| Member | Purpose | | --- | --- | | createAppBridge(options) | Create a bridge. hostOrigin is required; window/host/generateId are injectable for tests. | | bridge.getContext() | Resolves with the signed AppBridgeContext after the host handshake. | | bridge.getSessionToken() | Exchange the context for a scoped session token (for calling the platform API directly). | | bridge.apiFetch(path, init?) | Proxied, scope-enforced API call. init: { method?, query?, body? }. | | bridge.resize(height) | Fit the host iframe to your content. | | bridge.navigate(path) | Ask the host to navigate (in-app paths only). | | bridge.toast(text) / bridge.modal(options) | Host-rendered notifications and dialogs. | | bridge.destroy() | Detach listeners, reject pending requests. |

Docs

Full platform documentation — manifest reference, scopes and events catalogs, review rules, and the Studio IDE — lives at developer.1ecomm.com/docs.

License

MIT © Digitrend