@kherel/app-bridge

@kherel/app-bridge

SDK for Tribe Mini Apps — the postMessage bridge between a mini-app iframe and the Tribe host shell.

npm install @kherel/app-bridge

Quick start

import { bridge } from '@kherel/app-bridge';

// Handshake with Tribe host — resolves once the host is ready to
// receive further messages.
await bridge.send('TribeAppInit');

// Who's using the mini app (no server round-trip — data comes from
// the signed launch params).
const me = await bridge.send('TribeAppGetUserInfo');
console.log(`Hi, ${me.firstName}!`);

// Gate premium features on Tribe-side subscription. `subscriptionExpiresAt`
// is an ISO datetime when the user's Tribe subscription expires, or `null`
// if they have no active subscription.
if (me.subscriptionExpiresAt && new Date(me.subscriptionExpiresAt) > new Date()) {
  // user has an active Tribe subscription right now
}

// Grab the raw signed launch params. Mini-app backends use this to
// verify identity (the signature is HMAC-SHA256 over a canonical
// query string keyed on the app's own secret).
const { rawQuery } = await bridge.send('TribeAppGetLaunchParams');

// Call your OWN backend directly — not through Tribe. Pass the
// signed params as a header; your backend verifies the signature
// and extracts `tribe_user_id`.
const res = await fetch('https://my-mini-app.example.com/contacts', {
  headers: { 'X-Tribe-Signed-Params': rawQuery },
});

// Track an analytics event — surfaces in the developer's Cabinet
// > Analytics tab. Frontend-only API; mini-app backends must NOT
// write events.
bridge.trackEvent('button_clicked', { id: 'cta-checkout' });

Methods

Analytics

bridge.trackEvent(name, properties?) writes a single event to the mini-app's analytics stream. The host attaches the viewer's identity and app_id from the signed launch params before forwarding to the Tribe backend, so the mini-app frontend doesn't need any URL, token, or auth state of its own.

Frontend-only. Mini-app backends (Edge Functions, your own server) MUST NOT call this endpoint directly — the trust path runs through the host on purpose, and writing from the server bypasses session identity and double-counts. Track from React, not from your handlers.

import { bridge } from '@kherel/app-bridge';

// Common pattern: emit `app_open` once at mount.
useEffect(() => {
  bridge.trackEvent('app_open');
}, []);

// Feature-level events with custom properties.
function onCheckout() {
  bridge.trackEvent('checkout_started', { tier: 'lifetime', amountEur: 19 });
  // …
}

Constraints: event name ≤120 chars; serialized properties ≤1KB; batches of up to 20 per request. Per-(user, app) sliding-window cap of 120 events/min. Calls are non-blocking — failure surfaces as a rejected promise but does not throw; analytics SHOULD NOT block UX.

Authentication model

Mini apps bring their own backend. Tribe signs launch params with a per-app HMAC secret (stored in Tribe's mini_apps.secret_key); the mini-app backend holds the same secret and verifies the signature on every request. Tribe's API gateway is not in the data path between the mini-app frontend and its backend, except for analytics (TribeAppTrackEvent) and other host-managed methods like billing.

License

UNLICENSED — internal to Tribe until further notice.