beeper-sdk

Server-side TypeScript SDK for Beeper notification APIs.

Install

pnpm add beeper-sdk

Usage

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!,
});

await beeper.upsertSubscriber({
  subscriberId: "user_123",
  displayName: "John Doe",
  email: "[email protected]",
});

await beeper.triggerNotification({
  channels: ["in_app", "email"],
  subscriberIds: ["user_123"],
  templateKey: "welcome",
  category: "transactional",
  actionLabel: "Open dashboard",
  actionUrl: "https://app.example.com/dashboard",
});

await beeper.registerPushDevice({
  subscriberId: "user_123",
  pushToken: "<fcm_token>",
  platform: "web",
});

await beeper.triggerNotification({
  channels: ["push"],
  pushTokens: ["<fcm_token_1>", "<fcm_token_2>"],
  templateKey: "promo-push",
  category: "transactional",
  actionLabel: "View offer",
  actionUrl: "https://example.com/offers/spring",
});

actionLabel and actionUrl are stored in notification metadata and passed through to in-app inbox items. The inbox widget renders them as an action button/link when present.

Widget session helpers

const session = await beeper.createWidgetSession({
  subscriberId: "user_123",
  ttlSeconds: 900,
});

await beeper.revokeWidgetSessions({ subscriberId: "user_123" });

Push device helpers

await beeper.registerPushDevice({
  subscriberId: "user_123",
  pushToken: "<fcm_token>",
  platform: "web",
});

await beeper.unregisterPushDevice({
  subscriberId: "user_123",
  pushToken: "<fcm_token>",
});

const pushStats = await beeper.getPushDeviceStats();

Security

• Use this SDK only on trusted backend services.
• Never expose BEEPER_SERVER_KEY in browser/mobile client bundles.
• Rotate API keys regularly and revoke keys on suspicious activity.

Errors

Failed requests throw BeeperApiError.

import { BeeperApiError } from "beeper-sdk";

try {
  await beeper.getUsage();
} catch (error) {
  if (error instanceof BeeperApiError) {
    console.error(error.status, error.message, error.payload);
  }
}

Release checklist

pnpm -F beeper-sdk run clean
pnpm -F beeper-sdk run build
pnpm -F beeper-sdk run check-types