@cerebruminc/auth-sdk-react

Auth SDK for React

This SDK contains hooks for login, register, session info, logout and recovery flow.

flow: flow means whenever user initiate any of the action mentioned above will be indicated as flow. each and every flow has unique id and contains information related to what fields/inputs to render and after submitting form if there is any error then it also contains error messages.

nodes: fields/inputs to render on screen

Installation & usage

As this is private package, you need to setup .npmrc file in the repo where you want to use it. Define CEREBRUM_NPM_TOKEN system wide env variable and then update .npmrc with below contents.

//registry.npmjs.org/:_authToken=${CEREBRUM_NPM_TOKEN}

Contact Cerebrum team for getting CEREBRUM_NPM_TOKEN.

then you can install using

yarn add @cerebruminc/auth-sdk-react

OR

npm install @cerebruminc/auth-sdk-react

then at top level of the app setup AuthSdkProvider.

import { AuthSdkProvider } from '@cerebruminc/auth-sdk-react';
...
...

return (
  <AuthSdkProvider
    kratosUrl="KRATOS_URL_BASED_ON_ENV"
    neuronUrl="NEURON_URL_BASED_ON_ENV">
    <App />
  </AuthSdkProvider>
)

hooks & usage

here are some of the common variables

flow: flow object
loading: if hook is fetching flow information from api
onSubmit: call this function on some form submission
initalValues: inital values to render forms
submitting: if submit actions is in progress

useApiLoginFlow

const { flow, loading, onSubmit, initalValues, submitting } = useApiLoginFlow();

useApiRegisterFlow

const { flow, loading, onSubmit, initalValues, submitting } = useApiRegisterFlow();

useApiLogoutFlow

const logoutFn = useApiLogoutFlow(sessionToken);

useApiSession

const { loading, session, refetch } = useApiSession(sessionToken);

useApiRecoveryFlow

const { loading, onSubmit, flow, submitting } = useApiRecoveryFlow();

useApiVerificationFlow

const { loading, onSubmit, flow, submitting } = useApiVerificationFlow();

useApiSettingsFlow

Settings flow is useful to render elements in settings screen after user is logged in. These elements are email, password, 2FA related information. This flow is also used to update email, password & 2FA related information.

useApiSettingsFlow accepts sessionToken which is required to fetch user information and flowId which is optional and only useful if you have already flowId avaiable.

const { loading, onSubmit, flow, submitting, initialValues } = useApiSettingsFlow({
  sessionToken: '', // required
  flowId: '', // optional
});

flow.ui.nodes contains all possible elements to render.

onSubmit method needs to be called on your form submission. onSubmit method accepts method field and other fields based on provided method.

1. If you want to update email then method will be profile and other field will be { traits: { email: "" } }

const res = await onSubmit({
  method: 'profile',
  traits: { email: 'new_email' },
});

2. If you want to update password then method will be password and other field will be { password: "" }

const res = await onSubmit({
  method: 'password',
  password: 'new_password',
});

You can see example code here example/src/flows/Settings.tsx.

When there is an error you can get error messages from flow?.ui?.messages or you can catch error from onSubmit method and render it on UI. refer renderMessages utils functions in example/src/utils/index.tsx for more info.

utility methods

group parameter is optional in all utility methods. group can be 'default' | 'oidc' | 'password' | 'profile' | 'totp' | 'webauthn' | 'link' | 'lookup_secret'

getInitialValues

this function returns initial values based on nodes

const values = getInitialValues(flow?.ui?.nodes, 'group');

getValidationSchema

this function returns yup validation schema

const yupSchema = getValidationSchema(flow?.ui?.nodes, 'group');

getFormElements

this function returns fields/inputs to render based on given node and group ( optional )

const fields = getFormElements(flow?.ui?.nodes, 'group');