@engageo/notifications

Engageo browser SDK for Firebase notification device registration.

The SDK creates a Firebase Cloud Messaging (FCM) registration token in the browser and POSTs it to your backend, which then registers the device with Engageo using a private eng_live_* API key. The browser never sees that private key, never decides which user owns the token, and never calls Engageo directly.

Install

npm install @engageo/notifications
# or
yarn add @engageo/notifications
# or
bun add @engageo/notifications

Quick start

1. Add the Firebase service worker

Web FCM requires a service worker on the customer origin. Copy the ready-to-use worker shipped with the SDK into your app's public/ folder:

cp node_modules/@engageo/notifications/public/firebase-messaging-sw.js public/

It must be served from the same origin as your app at /firebase-messaging-sw.js. The file is self-contained — it loads Firebase from Google's gstatic CDN and is preconfigured for Engageo's Firebase project.

If you want to customize background notification rendering, edit your local copy after copying.

2. Create the backend proxy endpoint

The browser sends only the FCM token. The backend resolves the authenticated user and calls Engageo with the private API key.

// app/api/engageo/register-device/route.ts
import { NextResponse } from "next/server";
import { auth } from "@/auth";

export async function POST(request: Request) {
  const session = await auth();
  if (!session?.user?.id) {
    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
  }

  const body = await request.json();

  const response = await fetch(
    `${process.env.ENGAGEO_BASE_URL}/api/notifications/devices`,
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        Authorization: `Bearer ${process.env.ENGAGEO_NOTIFICATIONS_API_KEY}`,
      },
      body: JSON.stringify({
        externalUserId: `my-app:user:${session.user.id}`,
        platform: "web",
        token: body.token,
        appVersion: body.appVersion,
      }),
    }
  );

  const result = await response.json();
  return NextResponse.json(result, { status: response.status });
}

3. Register the device from the browser

import { registerDevice } from "@engageo/notifications";

async function onEnableNotificationsClick() {
  const permission = await Notification.requestPermission();
  if (permission !== "granted") return;

  const result = await registerDevice({
    registerEndpoint: "/api/engageo/register-device",
    appVersion: "1.0.0",
  });

  if (!result.ok) {
    console.error("Engageo registration failed", result);
    return;
  }

  console.log("Device registered:", result.deviceId);
}

API

registerDevice(options)

const result = await registerDevice({
  registerEndpoint: "/api/engageo/register-device",
  appVersion: "1.0.0",
  serviceWorkerRegistration: undefined,
  fetcher: undefined,
});

Options:

| name | type | description | | --- | --- | --- | | registerEndpoint | string (required) | URL of the customer backend proxy | | appVersion | string | Optional app version forwarded to Engageo | | serviceWorkerRegistration | ServiceWorkerRegistration | Provide an existing registration (useful for local dev) | | fetcher | typeof fetch | Inject a custom fetch — defaults to globalThis.fetch |

Returns a discriminated union — never throws for expected failure states:

type RegisterDeviceResult =
  | { ok: true; deviceId: string }
  | {
      ok: false;
      code:
        | "unsupported"
        | "permission_not_granted"
        | "service_worker_unavailable"
        | "token_unavailable"
        | "registration_failed";
      message: string;
      status?: number;
    };

registerDevice() will not call Notification.requestPermission() — your app keeps full control of the permission UX.

getNotificationPermission()

import { getNotificationPermission } from "@engageo/notifications";

const state = getNotificationPermission();
// "granted" | "denied" | "default" | "unsupported"

createEngageoNotifications(defaults)

Convenience wrapper for apps that register from multiple places:

import { createEngageoNotifications } from "@engageo/notifications";

const notifications = createEngageoNotifications({
  registerEndpoint: "/api/engageo/register-device",
  appVersion: "1.0.0",
});

await notifications.registerDevice();

Security notes

• The SDK only contains browser-safe values: Firebase web config and the Web Push VAPID public key. Per Firebase docs, these identify the project, not authorize access.
• Never put eng_live_* keys, Firebase Admin private keys, or any send-capable credentials in browser code.
• The customer backend resolves the authenticated user — the browser must not send externalUserId.

License

MIT