@opencampus/ocid-connect-js 1.0.0

package/README.md

@@ -0,0 +1,171 @@
+
+## Table of Contents
+
+- [Setup](#setup)
+- [React Integration](#react-integration)
+- [Javascript Integration](#javascript-integration)
+- [License](#license)
+
+## Setup
+
+**yarn**
+
+Install dependencies
+```bash
+yarn install
+```
+
+Compile & build project
+```bash
+yarn build
+```
+
+## React Integration
+
+Properties that can be overriden
+
+Setup Context to hook up state variables and override configuration
+
+```js
+import { OCConnect } from '@opencampus/ocid-connect-js';
+
+const opts = {
+    redirectUri: 'http://localhost:3001/redirect',
+}
+
+return (
+    <div id='app-root'>
+        <OCConnect opts={opts} sandboxMode={true}>
+            <RouterProvider router={ router } />
+        </OCConnect>
+    </div>
+)
+```
+
+OCConnect Property
+
+| Property | Description |
+| --- | --- |
+| opts | Authentication's properties that can be overriden |
+| sandboxMode | Connect to sandbox if it is set, default to live mode |
+
+Opts Property
+
+| Property | Description |
+| --- | --- |
+| redirectUri | URL to return after the login process is completed |
+
+Setup LoginCallBack to handle flow's result
+
+```js
+import { LoginCallBack } from '@opencampus/ocid-connect-js';
+
+const loginSuccess = () => {}
+const loginError = () => {}
+
+<Route path="/redirect"
+    element={ <LoginCallBack errorCallback={loginError} successCallback={loginSuccess}  /> }
+/>
+```
+
+It is possible to customize Loading & Error Page
+
+```js
+import { LoginCallBack, useOCAuth } from '@opencampus/ocid-connect-js';
+
+export default function CustomErrorComponent ()
+{
+    const { authState, ocAuth } = useOCAuth();
+
+    return (
+        <div>Error Logging in: { authState.error.message }</div>
+    );
+}
+
+export default function CustomLoadingComponent ()
+{
+    return (
+        <div>Error Logging in: { authState.error.message }</div>
+    );
+}
+
+<Route path="/redirect"
+    element={
+        <LoginCallBack
+            customErrorComponent={CustomErrorComponent}
+            customLoadingComponent={CustomLoadingComponent}
+            successCallback={loginSuccess} />
+    }
+/>
+```
+
+Use useOCAuth hook to read credentials info
+
+```js
+import { useOCAuth } from '@opencampus/ocid-connect-js';
+
+const UserTokenPage = (props) => {
+    const { authState, ocAuth } = useOCAuth();
+
+    if (authState.error !== undefined) {
+        return <div>Error: {authState.error.message}</div>;
+    } else {
+        return (
+            <div>
+                <h4>User Info</h4>
+                <pre>
+                { JSON.stringify(ocAuth.getAuthInfo(), null, 2) }
+                </pre>
+            </div>
+        );
+    }
+};
+```
+
+
+## Javascript Integration
+
+Using OCAuthSandbox for testing environment and OCAuthLive to initialize the SDK
+
+```js
+import { OCAuthSandbox } from '@opencampus/ocid-connect-js';
+const authSdk = new OCAuthSandbox();
+```
+
+Main Methods of Auth SDK
+
+| Method | Description |
+| --- | --- |
+| signInWithRedirect | Initialize the login process |
+| handleLoginRedirect | Return the auth state of the login process |
+| getAuthInfo | Return auth object { edu_username, eth_address } |
+| getAuthState | Return auth state data { accessToken, idToken, isAuthenticated } |
+
+Sample usage
+
+```js
+import { OCAuthSandbox } from '@opencampus/ocid-connect-js';
+
+const authSdk = new OCAuthSandbox()
+await authSdk.signInWithRedirect( {
+    state: 'opencampus',
+});
+```
+
+Sample usage to handle login response
+
+```js
+try {
+    const authState = await ocAuth.handleLoginRedirect();
+    if ( authState.idToken ) {
+        // login process is completed
+    } else {
+        // login process is not completed
+    }
+} catch ( e ) {
+    // there is an exception during login process
+}
+```
+
+### License
+ocid-connect-js is released under the MIT license.