feat(pencil) Updated sdk readme

Author: alexivsn

CHANGELOG.md

@@ -27,31 +27,30 @@
 </p>
 <hr/>
 
-SecureNative Node.JS agent provides application security monitoring and protection from OWASP TOP 10 security threats at run-time through dynamic instrumentation of business logic and user behaviour.
+[SecureNative](https://www.securenative.com/) performs user monitoring by analyzing user interactions with your application and various factors such as network, devices, locations and access patterns to stop and prevent account takeover attacks.
 
-SecureNative monitors and protects applications from common security threats such as:
+## Install the SDK
 
-- Bad bots
-- 3rd party packages vulnerabilities
-- SQL/NoSQL injections
-- XSS attacks
-- Massive security scans
-- Raise of HTTP errors (40X, 50X)
-- Anomaly Usage
-- Content Scrapping
-- Adaptive Authentication, prevent ATO (Account Takeover)
+Navigate to your application project folder and enter:
 
-## Installation
+```bash
+npm i @securenative/sdk
+```
 
-Please create free account at [register](https://console.securenative.com/register) to get api key.
+Verify that `@securenative/sdk` appears in your package to your `package.json`.
 
-Install SecureNative agent:
+## Initialize the SDK
 
-```bash
-npm i @securenative/agent
-```
+To get your *API KEY*, login to your SecureNative account and go to project settings page:
+
+```js
+import { SecureNative, EventTypes } from "@securenative/sdk";
+or;
+const { SecureNative, EventTypes } = require("@securenative/sdk"); // if your using ES5
+``` 
 
-Verify that `@securenative/agent` appears in your package to your `package.json`.
+### Option 1: Initialize via Config file
+SecureNative can automatically load your config from *securenative.json* that you can add to your application folder.
 
 ```shell script
 cat > securenative.json <<EOF
@@ -62,10 +61,75 @@ cat > securenative.json <<EOF
 EOF
 ```
 
-Add SecureNative as first dependency to your main module
+### Option 2: Initialize via config options
+
+```java
+SecureNative.init({ apiKey: "Your API_KEY" });
+```
+
+## Getting SecureNative instance
+Once initialized, sdk will create a singleton instance which you can get: 
+```java
+const secureNative = SecureNative.getInstance();
+```
+
+## Tracking events
+
+Once the SDK has been initialized, tracking requests sent through the SDK
+instance. Make sure you build event with the EventBuilder:
+
+
+```js
+import { SecureNative, EventTypes, contextFromRequest } from "@securenative/sdk";
+
+secureNative.track({
+  event: EventTypes.LOG_IN,
+  userId: '1234',
+  userTraits: {
+    name: 'Your Name',
+    email: 'name@gmail.com'
+  },
+  context: contextFromRequest(req)
+});
+``` 
+
+If you don't have acess to request object you can construct the context manually:
 
 ```js
-require('securenative');
+secureNative.track({
+  event: EventTypes.LOG_IN,
+  userId: '1234',
+  userTraits: {
+    name: 'Your Name',
+    email: 'name@gmail.com'
+  },
+  context: {
+    ip: '10.0.0.0',
+    clientToken: 'Token from client',
+    headers: {
+      "user-agent": 'Mozilla/5.0 (iPad; U; CPU OS 3_2_1 like Mac OS X; en-us) AppleWebKit/531.21.10 (KHTML, like Gecko) Mobile/7B405"'
+    }
+  }
+});
+``` 
+
+## Verify events
+```js
+
+  const verifyResult = await secureNative.verify({
+    event: EventTypes.LOG_IN,
+    userId: '1234',
+    userTraits: {
+      name: 'Your Name',
+      email: 'name@gmail.com'
+    },
+    context: contextFromRequest(req)
+  })
+
+  verifyResult.riskLevel // Low, Medium, High
+  verifyResult.score  // Risk score: 0 -1 (0 - Very Low, 1 - Very High)
+  verifyResult.triggers // ["TOR", "New IP", "New City"]
+}
 ```
 
 ## Configuration
@@ -75,8 +139,7 @@ require('securenative');
 | SECURENATIVE_API_KEY            | string  | false    | none                                      | SecureNative api key                              |
 | SECURENATIVE_APP_NAME           | string  | false    | package.json                              | Name of application source                        |
 | SECURENATIVE_API_URL            | string  | true     | https://api.securenative.com/v1/collector | Default api base address                          |
-| SECURENATIVE_INTERVAL           | number  | true     | 1000                                      | Default interval for SDK to try to persist events |
-| SECURENATIVE_HEARTBEAT_INTERVAL | number  | true     | 1000                                      | Default agent hearbeat interval                   |
+| SECURENATIVE_INTERVAL           | number  | true     | 1000                                      | Default interval for SDK to try to persist events |                |
 | SECURENATIVE_MAX_EVENTS         | number  | true     | 1000                                      | Max in-memory events queue                        |
 | SECURENATIVE_TIMEOUT            | number  | true     | 1500                                      | API call timeout in ms                            |
 | SECURENATIVE_AUTO_SEND          | Boolean | true     | true                                      | Should api auto send the events                   |

README.md

@@ -1,9 +1,4 @@
 enum EventType {
-  AGENT_LOG_IN = "sn.agent.login",
-  AGENT_LOG_OUT = "sn.agent.logout",
-  AGENT_CONFIG = "sn.agent.config",
-  HEART_BEAT = "sn.agent.heartbeat",
-  ERROR = "sn.agent.error",
   LOG_IN = "sn.user.login",
   LOG_IN_CHALLENGE = "sn.user.login.challenge",
   LOG_IN_FAILURE = "sn.user.login.failure",

src/enums/event-type.ts

@@ -1,39 +1,9 @@
-import fetch from 'node-fetch';
-import ConfigurationManager from "./configuration-manager";
 import SecureNative from "./securenative";
 import EventType from './enums/event-type';
-import { Logger } from "./logger";
-import { compareVersions } from './utils/utils';
-import { Package, PackageManager } from "./package-manager";
-import { join } from "path";
-import EventManager from "./event-manager";
 import { contextFromRequest } from './utils/utils';
 
-const PACKAGE_FILE_NAME = 'package.json';
-const appPkg: Package = PackageManager.getPackage(join(process.cwd(), PACKAGE_FILE_NAME));
-const config = ConfigurationManager.getConfig();
-
-// set default app name
-if (!config.appName) {
-  ConfigurationManager.setConfigKey('appName', appPkg.name);
-}
-
-const eventManager = new EventManager(fetch, config);
-const secureNative = new SecureNative(eventManager, config);
-
-// init logger
-Logger.initLogger(config);
-Logger.debug("Loaded Configurations", JSON.stringify(config));
-
-Logger.debug('Starting version compatibility check');
-
-if (compareVersions(process.version, config.minSupportedVersion) < 0) {
-  console.warn(`This version of Node.js ${process.version} isn't supported by SecureNative, minimum required version is ${config.minSupportedVersion}`);
-  console.warn(`Visit our docs to find out more: https://docs.securenative.com/docs/integrations/sdk/#install-via-npm-javascript`);
-}
-
 export {
   contextFromRequest,
-  secureNative,
+  SecureNative,
   EventType as EventTypes
 };

src/index.ts

@@ -10,16 +10,17 @@ const expect = chai.expect;
 
 describe('SecureNative', () => {
   it('Should fail to create new instance when params are null', () => {
-    expect(() => new SecureNative(null, null)).to.throw('Unable to create SecureNative instance, invalid config provided');
+    expect(() => SecureNative.getInstance()).to.throw('You need to init sdk first!');
   });
 
   it('Should have all public methods defined', () => {
     const config = ConfigurationManager.getConfig();
     config.disable = true;
     const fetcher = fetchMock.sandbox().post('*', 200);
     const eventManager = new EventManager(fetcher, config);
-    const secureNative = new SecureNative(eventManager, config);
-
+    SecureNative.initialize(eventManager, config);
+    const secureNative = SecureNative.getInstance();
+    
     expect(secureNative).to.have.property('track');
     expect(secureNative).to.have.property('verify');
   });

src/securenative.spec.ts

@@ -3,17 +3,57 @@ import { EventOptions } from './types/event-options';
 import EventManager from './event-manager';
 import ApiManager from './api-manager';
 import VerifyResult from './types/verify-result';
+import { Logger } from './logger';
+import { PackageManager, Package } from './package-manager';
+import ConfigurationManager from './configuration-manager';
+import { join } from 'path';
+
+const PACKAGE_FILE_NAME = 'package.json';
 
 export default class SecureNative {
   private apiManager: ApiManager;
-  
-  constructor(eventManager: EventManager, options: SecureNativeOptions) {
+  private static instance = null;
+
+  private constructor(eventManager: EventManager, options: SecureNativeOptions) {
     if (!eventManager || !options) {
       throw new Error('Unable to create SecureNative instance, invalid config provided');
     }
     this.apiManager = new ApiManager(eventManager, options);
   }
 
+  public static init(options: SecureNativeOptions) {
+    const defaultOptions = ConfigurationManager.getConfig();
+    const config: SecureNativeOptions = { ...options, ...defaultOptions };
+    
+    const eventManager = new EventManager(fetch, config);
+    SecureNative.initialize(eventManager, config);
+  }
+
+  public static initialize(eventManager: EventManager, options: SecureNativeOptions) {
+    if (SecureNative.instance) {
+      throw new Error('This SDK was already initialized');
+    }
+
+    const appPkg: Package = PackageManager.getPackage(join(process.cwd(), PACKAGE_FILE_NAME));
+    // set default app name
+    if (!options.appName) {
+      ConfigurationManager.setConfigKey('appName', appPkg.name);
+    }
+
+    // init logger
+    Logger.initLogger(options);
+    Logger.debug('Loaded Configurations', JSON.stringify(options));
+
+    SecureNative.instance = new SecureNative(eventManager, options);
+  }
+
+  public static getInstance(): SecureNative {
+    if (SecureNative.instance == null) {
+      throw new Error('You need to init sdk first!');
+    }
+    return SecureNative.instance;
+  }
+
   public track(opts: EventOptions) {
     return this.apiManager.track(opts);
   }

src/securenative.ts

@@ -1,4 +1,4 @@
-import FailoveStrategy from "../enums/failover-strategy";
+import FailoveStrategy from '../enums/failover-strategy';
 
 export type SecureNativeOptions = {
   apiKey?: string;
@@ -12,4 +12,4 @@ export type SecureNativeOptions = {
   logLevel?: string;
   failoverStrategy?: FailoveStrategy;
   minSupportedVersion?: string;
-}
+};