@byorouter/js

Lightweight frontend helpers for the BYORouter Connect flow.

Installation

npm install @byorouter/js

Usage

Initiate Connect Flow

import { buildConnectUrl, generateState } from '@byorouter/js';

function handleConnectClick() {
  // Generate and store state for CSRF protection
  const state = generateState();
  sessionStorage.setItem('byorouter_state', state);

  // Build the Connect URL
  const url = buildConnectUrl({
    clientId: 'byor_xxx',
    redirectUri: window.location.origin + '/settings',
    state,
  });

  // Redirect to BYORouter Connect
  window.location.href = url;
}

Handle Callback

import { parseCallback, clearCallbackParams } from '@byorouter/js';

// On your settings page (or wherever redirect_uri points)
useEffect(() => {
  const { code, state, error, errorDescription } = parseCallback();

  if (error) {
    toast.error(`Connect failed: ${errorDescription || error}`);
    clearCallbackParams();
    return;
  }

  if (code) {
    // Verify state matches
    const savedState = sessionStorage.getItem('byorouter_state');
    if (state !== savedState) {
      toast.error('Security error: state mismatch');
      clearCallbackParams();
      return;
    }

    // Exchange code on your backend
    fetch('/api/byorouter/exchange', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ code }),
    })
      .then(() => {
        toast.success('Connected!');
        clearCallbackParams();
      })
      .catch((err) => {
        toast.error('Failed to connect');
      });
  }
}, []);

API Reference

buildConnectUrl(options, baseURL?)

Build the URL to redirect users to the BYORouter Connect flow.

| Option | Type | Required | Description | |--------|------|----------|-------------| | clientId | string | Yes | Your BYORouter client ID (byor_xxx) | | redirectUri | string | Yes | Where to redirect after connect | | state | string | No | CSRF protection token | | provider | string | No | Focus on a specific provider | | connectionId | string | No | Update existing connection |

parseCallback(urlOrSearch?)

Parse the callback URL parameters. Returns:

{
  code: string | null;        // Auth code to exchange
  state: string | null;       // State for verification
  error: string | null;       // Error code if failed
  errorDescription: string | null;
}

generateState()

Generate a cryptographically random state string for CSRF protection.

clearCallbackParams()

Remove callback parameters from the URL without reloading.

License

MIT