@frejun/oauth

FreJun OAuth 2.0 SDK for TypeScript / JavaScript. Handles the browser popup authorization flow, token management, and notifies your app of token changes via events.

Installation

npm install @frejun/oauth

Quick Start

import { FrejunOAuth } from '@frejun/oauth';

const oauth = new FrejunOAuth({
  clientId: 'YOUR_CLIENT_ID',
  clientSecret: 'YOUR_CLIENT_SECRET',
  redirectUri: 'https://yourapp.com/callback', // optional
  extraParams: { state: 'random-csrf-token' }, // optional
});

// Listen for new tokens
oauth.on('tokens', (data) => {
  console.log('Access token:', data.access_token);
  console.log('Refresh token:', data.refresh_token);
  console.log('Expires in:', data.expires_in);
});

// Listen for refreshed tokens
oauth.on('tokensRefreshed', (data) => {
  console.log('New access token:', data.access_token);
  console.log('New refresh token:', data.refresh_token);
});

// Listen for errors
oauth.on('error', (err) => {
  console.error('OAuth error:', err.message);
});

// Open the FreJun consent popup (browser only)
oauth.openAuthPopup();

API

new FrejunOAuth(config)

| Option | Type | Required | Description | |---|---|---|---| | clientId | string | Yes | Your FreJun OAuth app client ID | | clientSecret | string | Yes | Your FreJun OAuth app client secret | | redirectUri | string | No | Override the registered redirect URI | | extraParams | Record<string, string> | No | Extra query params (state, username, etc.) |

Methods

getAuthorizationUrl()

Returns the FreJun authorization URL as a string.

openAuthPopup(options?)

Opens the consent page in a popup and listens for the auth code via postMessage. By default, automatically exchanges the code for tokens. Pass { generateTokens: false } to skip token generation (useful when tokens are generated on your backend). Browser only.

createTokens(code)

Exchange an auth code for tokens. Emits 'tokens'. Returns:

{
  success: boolean;
  message: string;
  access_token: string;
  refresh_token: string;
  expires_in: number;       // seconds
  token_type: string;
  org_identifier: string;
  // On error: statusCode is also included
  statusCode?: number;
}

refreshTokens(refreshToken)

Refresh an expired access token. Emits 'tokensRefreshed'. Returns:

{
  success: boolean;
  message: string;
  access_token: string;
  refresh_token: string;
  expires_in: number;       // seconds
  org_identifier: string;
  // On error: statusCode is also included
  statusCode?: number;
}

verifyToken(token)

Check whether an access or refresh token is valid. Returns:

// Valid token
{ is_valid: true }

// Invalid token or API error
{ is_valid: false; statusCode?: number; [key: string]: unknown }

disconnect(refreshToken)

Disconnect the OAuth app from the organization. Revokes all tokens for this organization. Returns:

{
  success: boolean;
  message: string;
  // On error: statusCode is also included
  statusCode?: number;
}

destroy()

Clean up all listeners and close any open popup.

Events

| Event | Payload | When | |---|---|---| | authCode | { code, email, ...extraParams } | Auth code received from popup | | tokens | CreateTokenResponse | Tokens created from an auth code | | tokensRefreshed | RefreshTokenResponse | Tokens refreshed | | error | Error | Any error during the flow |

on(event, listener)

Subscribe to an event. The listener is called every time the event fires.

// Called on every token refresh
oauth.on('tokensRefreshed', (data) => {
  saveTokens(data.access_token, data.refresh_token);
});

once(event, listener)

Subscribe to an event, but the listener is automatically removed after it fires once.

// Only capture the first set of tokens
oauth.once('tokens', (data) => {
  console.log('Initial tokens received:', data.access_token);
});

off(event, listener)

Remove a previously registered listener.

const handler = (data) => { /* ... */ };
oauth.on('tokens', handler);
// Later, unsubscribe
oauth.off('tokens', handler);

Backend Token Generation

If you need to generate tokens on your server instead of the browser, disable automatic token exchange and listen for the authCode event:

oauth.on('authCode', async ({ code, email, ...params }) => {
  // Send the code to your backend for token generation
  await fetch('/api/auth/frejun', { // your backend endpoint
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ code, email, ...params }),
  });
});

oauth.openAuthPopup({ generateTokens: false });

Error Handling

API calls never throw for HTTP-level errors. Instead, all functions return an error object containing the API's response body merged with a statusCode field. You can detect failures by checking a success field (present on most endpoints) or is_valid for verifyToken.

const result = await oauth.verifyToken(token);
if (result.is_valid) {
  // token is valid
} else {
  // result contains { is_valid: false, statusCode, ...apiErrorFields }
  console.error('Invalid token:', result);
}

const tokens = await oauth.createTokens(code);
if (!tokens.success) {
  // tokens contains { success: false, statusCode, message, ...apiErrorFields }
  console.error('Token creation failed:', tokens.message);
}

Only network-level failures (e.g. no internet connection) will result in a thrown error or an emitted 'error' event.

Notes

• The authorization code expires in 10 minutes.