API Reference

Complete reference for all exports from rpalert-sdk.

Choosing the right API

Use RPAlertProvider (recommended for most cases)

Wrap your root app/layout.tsx once and all pages are monitored automatically. Navigation events are detected via usePathname — no extra setup needed.

// app/layout.tsx — done. All pages monitored automatically.
<RPAlertProvider apiKey="...">
  {children}
</RPAlertProvider>

Use the Functional API when:

• You're on the Pages Router (no App Router / usePathname available)
• You want to monitor only specific pages, not the entire app
• You need to start or stop monitoring based on custom logic (e.g. user consent)

// Start monitoring only on a specific page
import { start, stop } from "rpalert-sdk";

useEffect(() => {
  start("your_api_key");
  return () => stop();
}, []);

Do not use RPAlertProvider and the Functional API together. Calling stop() manually will halt the monitoring that RPAlertProvider manages, and it will not restart. Calling onNavigate() manually alongside RPAlertProvider may also cause duplicate metrics to be sent.

---

RPAlertProvider (React component)

Import from rpalert-sdk/react. Place in your root layout to monitor all pages.

import { RPAlertProvider } from "rpalert-sdk/react";

Props

Prop	Type	Required	Default	Description
apiKey	string	✓	—	Your RPAlert API key from the dashboard
endpoint	string		"https://rpalert.dev/api/metrics"	Metrics destination URL
debug	boolean		false	Log SDK activity to the browser console
children	ReactNode	✓	—	Your component tree

---

Functional API

Low-level API for direct SDK control. Import from rpalert-sdk.

import { start, stop, onNavigate, setDebug } from "rpalert-sdk";

start(apiKey, config?)

Start performance monitoring.

function start(apiKey: string, config?: Partial<RPAlertConfig>): void

No-ops in SSR (non-browser) environments. Ignored if already running. Registers PerformanceObservers for LCP, FCP, CLS, Long Tasks, and INP.

start("your_api_key", { debug: true, batchInterval: 15000, onError: (err) => console.error(err) });

---

stop()

Stop performance monitoring.

function stop(): void

Disconnects all PerformanceObservers and clears the batch timer. Once stopped, monitoring does not restart automatically — you must call start() again.

---

onNavigate(pathname)

Call on SPA navigation. Flushes current page metrics and resets for the next page.

function onNavigate(pathname: string): void

Duplicate calls within 200ms or to the same path are ignored. Use this when managing navigation events manually (e.g. Pages Router with router.events).

---

setDebug(enabled)

Toggle debug logging at runtime.

function setDebug(enabled: boolean): void

setDebug(true);   // enable console logs
setDebug(false);  // disable console logs

---

RPAlertConfig type

interface RPAlertConfig {
  apiKey: string;
  endpoint?: string;        // Default: "https://rpalert.dev/api/metrics"
  debug?: boolean;          // Default: false
  batchInterval?: number;   // Default: 30000 (ms). Minimum: 1000
  onError?: (error: RPAlertError) => void;
}

Note: batchInterval is available via the Functional API (start()) but not as a prop on RPAlertProvider.

---

RPAlertError type

interface RPAlertError {
  type: 'network' | 'validation' | 'config' | 'quota';
  message: string;
}

The onError callback is called when the SDK encounters an error. Error types:

• network — Failed to send metrics after retries
• validation — Invalid metrics payload rejected by server
• config — Configuration issue (e.g. insecure HTTP endpoint)
• quota — Notification quota exhausted (see Quota Management)

Collected Metrics

Metric	Description
lcp	Largest Contentful Paint (seconds)
fcp	First Contentful Paint (seconds)
cls	Cumulative Layout Shift (score)
long_tasks	Number of tasks longer than 50ms
inp	Interaction to Next Paint — worst-case interaction latency (ms)
navigation_time	SPA navigation duration (ms), measured on route change
page	Pathname of the measured page

---

Quota Management

The SDK automatically manages notification quota to prevent excessive alerts. When your plan's notification limit is reached, the SDK pauses metric collection and attempts recovery automatically.

State transitions

  ┌──────────┐   remaining=0   ┌──────────┐   30 min elapsed   ┌──────────┐
  │  ACTIVE  │ ──────────────▶ │ STOPPED  │ ─────────────────▶ │  PROBE   │
  └──────────┘                 └──────────┘                    └──────────┘
       ▲                                                            │
       │              remaining > 0                                 │
       └────────────────────────────────────────────────────────────┘

• ACTIVE — Normal operation. Metrics are collected and sent at each batch interval.
• STOPPED — Quota exhausted. Metric batches are skipped. The onError callback fires with type: 'quota'.
• PROBE — After 30 minutes in STOPPED, the SDK sends a single probe batch. If the server responds with remaining > 0 (e.g. quota reset or plan upgrade), the SDK returns to ACTIVE. Otherwise it goes back to STOPPED for another 30 minutes.

This cycle is fully automatic — no user intervention needed.