@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.

How baseUrl works (two different servers)

The provider talks to two origins:

| What | URL | Purpose | |------|-----|--------| | baseUrl | Convex HTTP deployment, e.g. https://<deployment>.convex.site | 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 — proxies to Convex with the server API key |

• Use the .convex.site URL from the Convex dashboard (HTTP actions), not the …convex.cloud client URL.
• The browser calls baseUrl cross-origin; the Convex deployment must return CORS headers on /api/v1 (this repo’s backend does).
• Deploy requirement: Convex http.ts must register OPTIONS for /api/v1/ (preflight). If OPTIONS is missing, the edge router returns 404 and the browser reports a CORS error even though the real bug is “no route for preflight”.

If baseUrl is wrong, you’ll see non-JSON errors, 404 HTML, or CORS failures and the inbox stays empty.

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({
  baseUrl: process.env.BEEPER_BASE_URL!,
  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
      baseUrl={import.meta.env.VITE_BEEPER_BASE_URL}
      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>
  );
}

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)

This repo includes a dev proxy at POST /api/beeper/widget-session. Configure server env:

• BEEPER_SERVER_KEY — project API key with widget:session:create or ingest:write
• BEEPER_PROJECT_ID — optional default if you omit projectId in the body (the provider sends projectId automatically)
• CONVEX_SITE_URL or VITE_CONVEX_SITE_URL — Convex site URL for REST

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.