beeper-inbox-react

React embeddable inbox widget for Beeper.

The widget resolves the realtime Convex backend from Beeper's /widget/config endpoint. Host apps do not pass a convexUrl.

Public API

Most host apps only need:

• projectId
• publishableKey
• subscriber

By default the provider talks to the hosted Beeper API — the origin is built into the package, so you do not need to know or configure it.

You only need baseUrl if you are overriding the API origin for local development, staging, or self-hosted routing.

Advanced: baseUrl override

The provider talks to two origins:

| What | URL | Purpose | |------|-----|--------| | Beeper Widget API | Defaults to the hosted Beeper API origin | GET/POST …/api/v1/projects/:id/widget/... (inbox, config, read, etc.) | | Session mint (default) | Your app origin, e.g. http://localhost:3001 | POST /api/beeper/widget-session — mints short-lived widget sessions using your server key |

If you override baseUrl, it must be an origin serving Beeper widget REST routes.

In this repo’s current backend architecture, that override points at the Convex HTTP deployment (…convex.site) and must support CORS preflight on /api/v1/.

Why POST /api/beeper/widget-session runs often

That call mints the short-lived x-beeper-session-token. It runs when there is no token yet, before inbox/read actions, and when refreshing an expiring session. If it runs in a tight loop, the mint endpoint is probably failing (check 503 / JSON error and server env BEEPER_SERVER_KEY, CONVEX_SITE_URL).

Install

pnpm add beeper-inbox-react beeper-sdk

Host backend session mint

Use beeper-sdk on your backend (never browser):

import { BeeperClient } from "beeper-sdk";

const beeper = new BeeperClient({
  projectId: process.env.BEEPER_PROJECT_ID!,
  apiKey: process.env.BEEPER_SERVER_KEY!,
});

export async function createWidgetSession(subscriberId: string) {
  return beeper.createWidgetSession({
    subscriberId,
    profile: {
      displayName: "John Doe",
      email: "[email protected]",
    },
  });
}

// Optional: revoke active widget sessions (all or by subscriberId)
export async function revokeWidgetSessions(subscriberId?: string) {
  return beeper.revokeWidgetSessions({ subscriberId });
}

Frontend usage

import {
  BeeperInboxProvider,
  BeeperInboxBell,
  BeeperInboxPanel,
} from "beeper-inbox-react";

function App() {
  return (
    <BeeperInboxProvider
      projectId={import.meta.env.VITE_BEEPER_PROJECT_ID}
      publishableKey={import.meta.env.VITE_BEEPER_PUBLISHABLE_KEY}
      subscriber={{ subscriberId: "user_123" }}
      theme="system"
      customization={{
        accentColor: "#f97316",
        headerTitle: "Notifications",
      }}
      onEvent={(event) => {
        // Hook into your telemetry pipeline.
        // Example events: session.refresh.error, realtime.error, api.error
        console.debug("[beeper-widget-event]", event);
      }}
    >
      <BeeperInboxBell />
      <BeeperInboxPanel />
    </BeeperInboxProvider>
  );
}

Advanced override example:

<BeeperInboxProvider
  projectId="your-project-id"
  publishableKey="your-publishable-key"
  subscriber={{ subscriberId: "user_123" }}
>
  <BeeperInboxBell />
  <BeeperInboxPanel />
</BeeperInboxProvider>

By default, the provider calls POST /api/beeper/widget-session on the same origin as the page (resolved with new URL(sessionEndpoint, window.location.origin)), with a JSON body:

{ projectId, subscriberId, profile }

Your backend should mint a token with the server API key and return either { widgetSessionToken } or { data: { widgetSessionToken } } (matching the Beeper REST shape).

Beeper web app (apps/web)

The Beeper dashboard mints sessions for its own inbox at POST /api/internal/inbox-session (named so it is not confused with the /api/beeper/widget-session route you build in your app). It serves only the dashboard's own project. Configure server env:

• BEEPER_SERVER_KEY — project API key with widget:session:create or ingest:write
• BEEPER_PROJECT_ID (or VITE_BEEPER_PROJECT_ID) — the project it mints for; the request body is ignored
• CONVEX_SITE_URL or VITE_CONVEX_SITE_URL — only needed by the server-side session proxy in this repo

BeeperInboxBell

• Default: bell icon + unread badge.
• variant="minimal" restores the text + count pill.
• renderTrigger={({ toggle, unreadCount, open, triggerRef }) => <button ref={triggerRef}>…</button>} — attach triggerRef so the panel can anchor correctly.

If your host app needs custom session behavior, use getSessionToken or sessionEndpoint.

Web push token registration (FCM)

After you obtain an FCM token in your app, pass it to the provider so the widget registers it automatically:

<BeeperInboxProvider
  {...props}
  push={{
    token: fcmToken,
    platform: "web",
    deviceLabel: "chrome-main",
    autoRegister: true,
    autoUnregister: false,
  }}
>
  <BeeperInboxBell />
  <BeeperInboxPanel />
</BeeperInboxProvider>

Manual registration is also available:

const { registerPushToken, unregisterPushToken } = useBeeperInbox();
await registerPushToken(fcmToken, { platform: "web" });
await unregisterPushToken(fcmToken);

The widget calls:

• POST /api/v1/projects/:projectId/widget/push/register
• POST /api/v1/projects/:projectId/widget/push/unregister

Security checklist

• Keep BEEPER_SERVER_KEY on your backend only. Never expose it in browser code.
• Use publishableKey only for widget initialization and widget-safe routes.
• Mint short-lived session tokens (ttlSeconds around 5-15 minutes).
• Refresh/re-mint session tokens from your backend when expired.
• Use onEvent to monitor session.refresh.error, api.error, and realtime.error.
• Rotate API keys periodically and revoke compromised keys immediately.

Package release checklist

pnpm -F beeper-inbox-react run clean
pnpm -F beeper-inbox-react run build
pnpm -F beeper-inbox-react run check-types

Then publish from packages/inbox-react using your normal npm release workflow.