@overdriveiot/ow-nodejs-sdk v1.0.7

OVERDRIVE IOT OW-NODEJS-SDK

Installation

OW-NODEJS-SDK requires npm v8+ and Node.js v14 to run.

# Using Yarn:
yarn add @overdriveiot/ow-nodejs-sdk

# Or, using NPM:
npm install @overdriveiot/ow-nodejs-sdk

Usage

First of all, it`s necessary to initialize the sdk with OW API base address in order to use its methods.

import * as OW from '@overdriveiot/ow-nodejs-sdk';

OW.initialize('https://ws.dev.overdrive.asia/');

# ...and then you can use the methods you need as it`s shown below

const signOut = async () => {
    return await OW.authn.signOut().run();
}

Methods

Authentication:

• signIn
• resendSignIn
• verify
• resendVerification
• generateSignInToken
• renewToken
• removeToken
• inspect
• signOut

Devices:

• load

Messages:

• loadFields
• latest

signIn

Authentication is performed in steps. The signIn request accepts a "petition" object as a parameter and returns a "resolution" object in the response. The petition may contain some credentials or be empty at all. If credentials are wrong or insufficient, there is a "challenge" object in the resolution. The challenge contains an occurred error info and credential type that is required for a successful authentication. The petition submitted in response to resolution with sessionId attribute set must include sessionId field with the same value, the credential supplied in response to challenge with challengeNo attribute set must include challengeNo field with the same value.

Once sign-in succeeded, client session is established and the resolution returned in the response does not contain challenge and may contain verification token required for some sensitive operations. Client application can choose to obtain sign-in token which, until expired, can be used to sign in instead of password or other credentials configured for user account.

The example of the authentication performed in one step:

import * as OW from '@overdriveiot/ow-nodejs-sdk';

const signInPayload = {
    petition: {
        credentials: [
            { credentialType: 'loginName', value: 'your@loign.name' },
            { credentialType: 'password', value: 'your password' }
        ]
    }
}

const signIn = async (signInPayload) => {
    try {
        const { resolution } = await OW.authn.signIn(petition).run();
        
        if (resolution?.challenge?.error) {
            throw new Error(resolution.challenge.error);
        }
        
         # here functionality to handle response goes;
    } catch (error) {
        console.log(error);
    }
}

The example of the authentication performed in several steps. Here we have a two-step form: the first step is responsible for sending a login name and second one is responsible for sending a password. At the first step we send the petition containing our login name. In response we get a resolution which contains a challenge because we have to send additional info to sign in successfully. This challenge contains sessionId, challengeNo and credentialType fields. The field "credentialType" is set to "password" what apparently means that we need to send our password too. So, at the second step we send the petition containing sessionId and the credentials' info that contains password and challengeNo.

import * as OW from '@overdriveiot/ow-nodejs-sdk';

const sendLogin = async () => {
    const payload = {
        petition: {
            credentials: [
                { credentialType: 'loginName', value: 'your@loign.name' },
            ]
        }
    }
    
    try {
        const { resolution } = await OW.authn.signIn(payload).run();
        
        if (resolution?.challenge?.error) {
            throw new Error(resolution.challenge.error);
        }
        
        return {
            sessionId: resolution?.challenge?.sessionId,
            challengeNo: resolution?.challenge?.challengeNo
        }
    } catch (error) {
        console.log(error);
    }
}

const sendPassword = async ({ sessionId, challengeNo }) => {
    const payload = {
        petition: {
            sessionId,
            credentials: [
                { credentialType: 'password', value: 'your password', challengeNo },
            ]
        }
    }
    
    try {
        const { resolution } = await OW.authn.signIn(payload).run();
        
        if (resolution?.challenge?.error) {
            throw new Error(resolution.challenge.error);
        }
        
        console.log(resolution);
    } catch (error) {
        console.log(error);
    }
}

resendSignIn

Requests to re-generate previously dispatched re-sendable sign-in challenge. It`s possible to re-generate only those challenges that have field "resendable" equal to true.

const resendSignIn = async (challengeNo) => {
    try {
        const { challenge } = await OW.authn.resendSignIn(challengeNo).run();
        console.log(challenge);
    } catch (error) {
        console.log(error);
    }
}

verify

The method is similar to sign-in request but it does not affect session authentication status. It should be used to re-generate expired verification token which is required for some sensitive operations.

const payload = {
    petition: {
        credentials: [
            { credentialType: 'loginName', value: 'your@loign.name' },
            { credentialType: 'password', value: 'your password' }
        ]
    }
}

const verify = async (payload) => {
    try {
        const { resolution } = await OW.authn.verify(petition).run();
        console.log(resolution);
    } catch (error) {
        console.log(error);
    }
}

resendVerification

Requests to re-generate previously dispatched re-sendable verification challenge.

const resendVerification = async (challengeNo) => {
    try {
        const { challenge } = await OW.authn.resendVerification(challengeNo).run();
        console.log(challenge);
    } catch (error) {
        console.log(error);
    }
}

generateSignInToken

Generates token that can be used as a credential to sign in.

const generateSignInToken = async () => {
    try {
        const { token } = await OW.authn.generateSignInToken().run();
        console.log(token);
    } catch (error) {
        console.log(error);
    }
}

renewToken

Refreshes the current token by generating a new one.

const renewToken = async (currentToken) => {
    try {
        const { token } = await OW.authn.renewToken(currentToken).run();
        console.log(token);
    } catch (error) {
        console.log(error);
    }
}

removeToken

Removes current token.

const removeToken = async (currentToken) => {
    try {
        await OW.authn.removeToken(currentToken).run();
    } catch (error) {
        console.log(error);
    }
}

inspect

Re-establishes authentication context of the current session on behalf of another user. The current user must have privilege to access context of another user. The request requires a valid verification token.

const payload = {
    inspectionRequest: {
        loginName: 'your@loign.name'
    }
}

const inspect = async (payload) => {
    try {
        const { ack } = await OW.authn.inspect(payload).run();
        console.log(ack);
    } catch (error) {
        console.log(error);
    }
}

signOut

Ends current session.

const signOut = async () => {
    try {
        await OW.authn.signOut().run();
    } catch (error) {
        console.log(error);
    }
}

load

Retrieves user`s devices.

const getUserDevices = async () => {
    try {
        const { devices } = await OW.device.load().run();
    } catch (error) {
        console.log(error);
    }
}

loadFields

Retrieves message fields' meta-data. The data returned describe fields and its values that can be presented in a device`s message.

const getMessageMetadata = async () => {
    try {
        const { messageFields } = await OW.message.loadFields().run();
    } catch (error) {
        console.log(error);
    }
}

latest

Retrieves the latest device's message.

const getDeviceLatestMessage = async (deviceUri) => {
    try {
        const { messageDetails } = await OW.message.latest(deviceUri).run();
    } catch (error) {
        console.log(error);
    }
}