@screencloud/auth-sdk

ScreenCloud Auth SDK

Usage

install package using npm npm i -S @screencloud/auth-sdk

import and configure

import { Auth } from '@screencloud/auth-sdk'

// create it once and add it to your context
export const auth = new Auth({
  service: {
    urL: 'https://auth-service.dev.next.sc:8022',
  },
  frontend: {
    urL: 'https://auth.dev.next.sc:8020',
  },
});

Methds

get()

Retrieves the current session. Will internally call refresh() periodically and on the first call.

try {
  const session = await auth.get();
  if (!session) {
    console.log(`not logged in or error occurred`);
  } else {
    const { payload, token } = session;
    console.log(`logged in as ${payload.email}`);
    // use token to talk to APIs like studio graphql
  }
} catch (e) {
  console.log('something happened, handle it!');
}

shouldRefresh() and refresh()

These functions are used internally by get() but are exposed and can be called if desired.

Use refresh() to force a refresh of the current session. This triggers the initialized-event on the first run, triggers loggedOut or loggedIn if the current user has changed or refreshed if the current user is logged in and remained unchanged.

Note: refresh() will throw in several circumstances, use get() if you want this handled.

logout()

Calls the AuthService to log out the current user. Will always return { redirectUrl: string } and swallows up all errors for resilience. Will trigger loggedOut if user is currently logged in.

Either react to the event handler or to the functions result.

fetchJson()

A helper method used internally by refresh(), logout(), etc. which is exposed to serve other use-cases such as user creation or login.

Example:

// body can contain objects, which will be JSON stringified.
const body = {
  email: '[e-mail]',
  password: 'myUnsafePass123',
};

// catch the 
const result = await auth.fetchJson('/ap/v1/user/create', { body });

Events

subscribe to events to react in real-time

auth.on('loggedIn', ({ token, claims }) => {
  console.log(`user logged in ${claims.email}`);
});

auth.on('loggedOut', ({ redirectUrl }) => {
  console.log(`user logged out, redirect to ${redirectUrl}`);
});

auth.on('refreshed', ({ token, claims }) => {
  console.log(`logged in user was refreshed ${claims.email}`);
});

auth.on('initialized', (session) => {
  if (!session) {
    console.log(`initial auth state: user is NOT logged in`);  
  } else {
    console.log(`initial auth state: user is ${session.claims.email}`);
  }
});


if (!session) {
  console.log(`not logged in or error occurred`);
} else {
  const { payload, token } = session;
  console.log(`logged in as ${payload.email}`);
  // use token to talk to APIs like studio graphql
}

Automation

The SDK offers helper functionality to automatically update it's login state and sync it between tabs.

Be aware that these are based on event listeners and that it's best to just use one instance of Auth. To allow for garbage collection of an Auth-instance ensure to deactivate these again before clearing or losing references to the instance.

AutoSync

The Auth-class can automatically sync itself across tabs on the same origin using localStorage. Any invalid values received will be ignored for resilience.

Activate either during construction

const auth = new Auth({ autoSync: true });

or on the instance itself

// enable
auth.autoSync = true;

// disable
auth.autoSync = true;

AutoRefresh

The Auth-class can automatically refresh to keep it's session from expiring and to handle login and logout happening in the background. It will call shouldRefresh() internally every 15 seconds and run refresh() if required.

Activate either during construction

const auth = new Auth({ autoRefresh: true });

or on the instance itself

// enable
auth.autoRefresh = true;

// disable
auth.autoRefresh = true;

Debug

Debug mode can be activated by either setting debug: true during construction or by setting a DEBUG_AUTH_SDK=1-cookie.

Once activated the SDK will log detailed information to console. Once activated the SDK will log detailed information to console.