NodeJS SDK

The NodeJS SDK enables you to use IntelliProves features with ease.
Requirements
NodeJS
This SDK only provides tools for back-end servers. This is due to the requirement of File IO.
Our front-end SDK can be found here: https://docs.intelliprove.com/sdk﻿
Tested on
NodeJS 16.x
NodeJS 18.x
NodeJS 19.x
Support is guaranteed for the NodeJS versions mentioned above. Other versions are most likely supported but not tested.
CommonJS & ESM 
We provide support for both CommonJS and ESM Node backends. Take note that they do require the use of a different package from NPM. Please make sure that you are installing the correct NPM package for your project.
If you have the line "type": "module" present in your packages.json file, you most likely need to use the ESM version of our SDK.
From the section Functionality onward there is no distinction between the 2 SDKs as they provide the same API and functionality.
Recommendations
We recommend the use of TypeScript as it provides type hints and a better developer experience. However, our SDK works without typescript as well.
Installation
You can find our SDK on the node package manager repository for easy installation:
CommonJS:
﻿https://www.npmjs.com/package/intelliprove-sdk 
ESM:
﻿https://www.npmjs.com/package/intelliprove-sdk-esm﻿
Shell
npm add intelliprove-sdk # CommonJS
npm add intelliprove-sdk-esm # ESM
npm add intelliprove-sdk # CommonJS
npm add intelliprove-sdk-esm # ESM
﻿
Updating the sdk
Shell
npm update intelliprove-sdk # CommonJS
npm update intelliprove-sdk-esm # ESM
npm update intelliprove-sdk # CommonJS
npm update intelliprove-sdk-esm # ESM
﻿
Authentication
More info on authentication and the API key can be found here: API docs﻿ .

Functionality
For information about the flow to perform a health scan, we recommend going through the Integration guidelines﻿ if you haven't already.
Check conditions
Check the quality of a given image before uploading.
Returns a QualityResponse object with feedback on whether your video/image is usable and why it might not be usable.
Parameters:
path: string - path to the image you want to run the quality check on
Return types:
﻿QualityResponse﻿﻿
Error options:
﻿IntelliProveAPIError﻿﻿
﻿IntelliProveSDKError﻿﻿
﻿
TypeScript
JS
const APIKEY: string = "";
const IMAGE_PATH: string = "/path/to/image.jpg";

const intelliprove = new IntelliProveSDK(APIKEY);

intelliprove.check(IMAGE_PATH)
.then(response: QualityResponse => {
  console.log(response.success());
}).catch(error => {

  if (error instanceof IntelliProveAPIError) {
    // handle API error
  } else if (error instanceof IntelliProveSDKError) {
    // handle SDK error
  } else {
    throw e; // let others bubble up
  }
  
});
const APIKEY: string = "";
const IMAGE_PATH: string = "/path/to/image.jpg";

const intelliprove = new IntelliProveSDK(APIKEY);

intelliprove.check(IMAGE_PATH)
.then(response: QualityResponse => {
  console.log(response.success());
}).catch(error => {

  if (error instanceof IntelliProveAPIError) {
    // handle API error
  } else if (error instanceof IntelliProveSDKError) {
    // handle SDK error
  } else {
    throw e; // let others bubble up
  }
  
});
﻿
﻿
Upload a video
Easily upload a video to IntelliProve for analysis of the subject's biomarkers.
Returns the uuid of the uploaded video, which can be used to get the results.
NOTE: The quality check  (above) needs to be successful before you can upload a video.
Parameters:
path: str - path to the video you want to process
quality_response: QualityResponse - the response from the quality check method
patient: string - An optional field to set the patient reference
performer: string - An optional field to set the performer reference
Return types:
uuid: string
Error options:
﻿IntelliProveAPIError﻿﻿
﻿IntelliProveSDKError﻿﻿
﻿
TypeScript
JS
const VIDEO_PATH: string = "/path/to/video.mp4";
const performer: string = "Dr. John Doe";
const patient: string = "John Doe";

intelliprove.upload(VIDEO_PATH, quality_response, performer, patient)
.then(uuid: string => {
  console.log(uuid);
}).catch(error => {

  if (error instanceof IntelliProveAPIError) {
    // handle API error
  } else if (error instanceof IntelliProveSDKError) {
    // handle SDK error
  } else {
    throw e; // let others bubble up
  }
  
});
const VIDEO_PATH: string = "/path/to/video.mp4";
const performer: string = "Dr. John Doe";
const patient: string = "John Doe";

intelliprove.upload(VIDEO_PATH, quality_response, performer, patient)
.then(uuid: string => {
  console.log(uuid);
}).catch(error => {

  if (error instanceof IntelliProveAPIError) {
    // handle API error
  } else if (error instanceof IntelliProveSDKError) {
    // handle SDK error
  } else {
    throw e; // let others bubble up
  }
  
});
﻿
﻿
Get the results of a video
Returns the results of a processed video for a given uuid as a Biomarkers object.
NOTE: This uses long polling, when demand is high this call can take a while.
Parameters:
uuid: string - The UUID returned by the upload method
Return types:
﻿BiomarkersResponse﻿﻿
﻿UnprocessableVideoResponse﻿﻿
Error options:
﻿IntelliProveAPIError﻿﻿
﻿IntelliProveSDKError﻿﻿
﻿
TypeScript
JS
const uuid: string = "";

intelliprove.results(uuid, p)
.then(biomarkers: BiomarkersResponse | UnprocessableVideoResponse => {
  console.log(biomarkers);
}).catch(error: Error => {
  console.log(error.message);
});


// retrieving the results a second time
intelliprove.results(uuid, false)
.then(response: BiomarkersResponse | UnprocessableVideoResponse => {

  console.log(response);
  
}).catch(error: Error => {

  if (error instanceof IntelliProveAPIError) {
    // handle API error
  } else if (error instanceof IntelliProveSDKError) {
    // handle SDK error
  } else {
    throw e; // let others bubble up
  }
  
});
const uuid: string = "";

intelliprove.results(uuid, p)
.then(biomarkers: BiomarkersResponse | UnprocessableVideoResponse => {
  console.log(biomarkers);
}).catch(error: Error => {
  console.log(error.message);
});


// retrieving the results a second time
intelliprove.results(uuid, false)
.then(response: BiomarkersResponse | UnprocessableVideoResponse => {

  console.log(response);
  
}).catch(error: Error => {

  if (error instanceof IntelliProveAPIError) {
    // handle API error
  } else if (error instanceof IntelliProveSDKError) {
    // handle SDK error
  } else {
    throw e; // let others bubble up
  }
  
});
﻿
﻿
Get the current customers' info
Get the current customers' information by API key.
Return types:
﻿UserInfo﻿﻿
Error options:
﻿IntelliProveAPIError﻿﻿
﻿IntelliProveSDKError﻿﻿
﻿
TypeScript
JS
intelliprove.userInfo()
.then(userInfo: UserInfo => {
  console.log(userInfo);
});
intelliprove.userInfo()
.then(userInfo: UserInfo => {
  console.log(userInfo);
});
﻿
﻿
﻿
Models
Those are simple representations of the models accessible through the SDK and their helper functions.
All models have a .json() method to convert it to a normal JS object in case this is preferred.
QualityResponse
Describes the quality of an image.
JS
class QualityResponse {
    score: number;
    error_type: str;
    error_code: number;
    prompt: string | null;
    signature: string | null;
}
class QualityResponse {
    score: number;
    error_type: str;
    error_code: number;
    prompt: string | null;
    signature: string | null;
}
﻿
Helpers
success(): boolean - Has the quality check succeeded
BiomarkersResponse
Holds the results of an analyzed video after upload.
JS
class BiomarkersResponse {
    epoch: string;
    timestamp: Date;
    heart_rate: string;
    
    respiratory_rate: string | null;
    heart_rate_variability: string | null;
    ans_balance: string | null;
    resonant_breathing_score: string | null;
    morning_readiness: string | null;
    acute_mental_stress_score: string | null;
    mental_health_risk: string | null;
}
class BiomarkersResponse {
    epoch: string;
    timestamp: Date;
    heart_rate: string;
    
    respiratory_rate: string | null;
    heart_rate_variability: string | null;
    ans_balance: string | null;
    resonant_breathing_score: string | null;
    morning_readiness: string | null;
    acute_mental_stress_score: string | null;
    mental_health_risk: string | null;
}
﻿
UserInfo
Contains information about the current user.
JS
class UserInfo {
    email: string;
    group: string;
    customer: string;
}
class UserInfo {
    email: string;
    group: string;
    customer: string;
}
﻿
Helpers
hasEmail(): boolean - Does the have customer a valid email
isAdmin(): boolean - Is the current customer an administrator for their organization
isContributor(): boolean - Is the current customer a contributor
isUser(): boolean - Is the current customer a regular user
﻿
UnprocessableVideoResponse
This response gets returned by getResults in case your video failed to process and/or we detected an issue with your video. Please refer to the result outcomes﻿ for more information about the different types of errors.
﻿
JS
class UnprocessableVideoResponse {
    errorCode: number;
    errorType: string;
    errorDescription: string;
    userPrompt: string | null;
}
class UnprocessableVideoResponse {
    errorCode: number;
    errorType: string;
    errorDescription: string;
    userPrompt: string | null;
}
﻿
﻿
﻿
Exceptions
Our SDK throws 2 types of exceptions, IntelliProveSDKError and IntelliProveAPIError. All of our exceptions inherit from the base JavaScript Error class.
IntelliProveAPIError
Thrown when a request to our API has failed or is invalid (lower level)
Includes a message about what failed
Includes the HTTP status code
Eg. Invalid Authentication (401)
The body property may be used to provide extra information about the error message.
JS
class IntelliProveAPIError extends Error {
    status_code: number;
    body: Object | null;
}
class IntelliProveAPIError extends Error {
    status_code: number;
    body: Object | null;
}
﻿
IntelliProveSDKError
Thrown for top-level errors such as wrong parameters, connection errors, etc.
Includes a message about what went wrong
Includes ErrorType
Eg. You do not have an internet connection 
JS
const ErrorType = {
  Api: 0,
  Configuration: 1,
  SDK: 2,
  File: 3,
  Other: 99
}

class IntelliProveSDKError extends Error {
    error_type: number;  // ErrorType
}
const ErrorType = {
  Api: 0,
  Configuration: 1,
  SDK: 2,
  File: 3,
  Other: 99
}

class IntelliProveSDKError extends Error {
    error_type: number;  // ErrorType
}
﻿
﻿
Example usage
Provided with a valid API key and a valid image and video path, this code snippet runs from start to finish and prints out each intermediate result to the console.
CommonJS
ESM
const IntelliProveSDK = require('intelliprove-sdk').default;

const APIKEY = "";

const IMAGE_PATH = "/path/to/image.jpg";
const VIDEO_PATH = "/path/to/video.mp4";

const intelliprove = new IntelliProveSDK(APIKEY);

// Wrap in async function
(async () => {
  try {
      // Do a quality check on an image saved to disk
      const quality_response = await intelliprove.check(IMAGE_PATH);
      // Upload a video for processing
      const uuid = await intelliprove.upload(VIDEO_PATH, quality_response);
      
      // Get the results of the uploaded video for the first time
      const results = await intelliprove.results(uuid);
      console.log(results);
  
      // Get the current user/customer by authentication credentials
      const user = await intelliprove.userInfo();
      console.log(user);
  
  } catch (error) {
      console.error(error);
  }
})()
const IntelliProveSDK = require('intelliprove-sdk').default;

const APIKEY = "";

const IMAGE_PATH = "/path/to/image.jpg";
const VIDEO_PATH = "/path/to/video.mp4";

const intelliprove = new IntelliProveSDK(APIKEY);

// Wrap in async function
(async () => {
  try {
      // Do a quality check on an image saved to disk
      const quality_response = await intelliprove.check(IMAGE_PATH);
      // Upload a video for processing
      const uuid = await intelliprove.upload(VIDEO_PATH, quality_response);
      
      // Get the results of the uploaded video for the first time
      const results = await intelliprove.results(uuid);
      console.log(results);
  
      // Get the current user/customer by authentication credentials
      const user = await intelliprove.userInfo();
      console.log(user);
  
  } catch (error) {
      console.error(error);
  }
})()
﻿
An example using then and catch 
CommonJS
ESM
const IntelliProveSDK = require('intelliprove-sdk').default;

const APIKEY = "";

const IMAGE_PATH = "/path/to/image.jpg";
const VIDEO_PATH = "/path/to/video.mp4";
const uuid = ""; // A uuid from a processed video

const intelliprove = new IntelliProveSDK(APIKEY);

// You can also use 'then' and 'catch'
intelliprove.results(uuid).then(biomarkers => {
console.log(biomarkers);
}).catch(err => {
console.error(err);
});
const IntelliProveSDK = require('intelliprove-sdk').default;

const APIKEY = "";

const IMAGE_PATH = "/path/to/image.jpg";
const VIDEO_PATH = "/path/to/video.mp4";
const uuid = ""; // A uuid from a processed video

const intelliprove = new IntelliProveSDK(APIKEY);

// You can also use 'then' and 'catch'
intelliprove.results(uuid).then(biomarkers => {
console.log(biomarkers);
}).catch(err => {
console.error(err);
});
﻿
﻿
Python SDK