Device Intelligence SDK

This README explains how to integrate the Device Intelligence SDK into your application.
It covers setup, authentication flows, risk-aware transactions, account activity tracking, and clearly highlights where your application logic should be applied.

Table of Contents

1. Installation / Prerequisites
2. Quick Setup (sdk-utils.js)
3. App Integration (app.js)
4. Sign-in Flow (Risk-aware)
5. Sign-up Flow (Async Risk Check)
6. Transaction Flow (Detailed Risk Payload)
7. Account Activity Tracking
8. Action Types & Decision Handling
9. API Reference
10. Troubleshooting & Tips

Installation / Prerequisites

Install the SDK from the private registry:

npm install device-intelligence-sdk --registry http://10.10.10.97:4873

Requirements

• Application must support ES Modules
• serverUrl must be reachable
• SDK must be instantiated once (singleton pattern)

Example Environment

• React (hooks)
• Device Intelligence WebSocket server http://localhost:8010?EIO=4&transport=websocket

Quick Setup (sdk-utils.js)

Create a shared SDK instance and export it.

// sdk-utils.js
import { DeviceIntelligenceSDK } from "device-intelligence-sdk";

export const devIntelligenceSdk = DeviceIntelligenceSDK({
  productId: "proj_456",
  serverUrl: "http://localhost:8010?EIO=4&transport=websocket",
});

⚠️ Always export a single instance to avoid duplicate alerts and connections.

App Integration (app.js)

Start the SDK once and subscribe to global alerts.

import { useEffect } from "react";
import { devIntelligenceSdk } from "./sdk-utils";

useEffect(() => {
  let subscription;

  devIntelligenceSdk.start()
    .then(() => {
      subscription = devIntelligenceSdk
        .getGlobalAlertListener()
        .subscribe((data) => {
          console.log("Global Alert:", data);

          // CUSTOM LOGIC PLACE
          // Example: toast, modal, audit log, UI restriction
        });
    })
    .catch(console.error);

  return () => subscription?.unsubscribe?.();
}, []);

Sign-in Flow (Risk-aware)

Each login attempt is evaluated and returns a decision.

const signin = async () => {
  const resp = await devIntelligenceSdk.trackLoginAsync({ userId: email });

  if (resp.action === "Flag/Risk") {
    alert(
      `Risk detected: ${resp.casesPassed[0]?.condition?.left?.name} → ${resp.casesPassed[0]?.actual}`
    );

    // CUSTOM LOGIC PLACE
    // Example: CAPTCHA, OTP, warning banner
    devIntelligenceSdk.trackLoginSuccess({ token: "1234" });
    navigate("/dashboard");

  } else if (resp.action === "Block Action") {
    alert("Login blocked due to high risk");

    devIntelligenceSdk.trackLoginFail({ reason: "Block Detected" });
    return;
  }

  // NO_ACTION
  devIntelligenceSdk.trackLoginSuccess({ token: "1234" });
  navigate("/dashboard");
};

Sign-up Flow (Async Risk Check)

Signup attempts are evaluated before allowing account creation.

const signup = async () => {
  devIntelligenceSdk.updateUserId(email);

  const resp = await devIntelligenceSdk.trackSignupAsync({
    promoCodeUsed: promoCode,
    referredBy,
  });

  if (resp.action === "Flag/Risk") {
    alert("Signup flagged but allowed to continue");

    // CUSTOM LOGIC PLACE
    // Example: email verification, KYC review
  } 
  else if (resp.action === "Block Action") {
    alert("Signup blocked");

    devIntelligenceSdk.trackSignUpFail({
      reason: "Risk detected",
      promoCodeUsed: promoCode,
      referredBy,
    });
    return;
  }

  devIntelligenceSdk.trackSignUpSuccess({
    promoCodeUsed: promoCode,
    referredBy,
  });

  navigate("/dashboard");
};

Transaction Flow (Detailed Risk Payload)

Transactions support rich contextual metadata and interactive confirmations.

Transaction Payload

{
  txnId,
  transactionType,        // DEBIT | CREDIT
  amount,
  receiverUniqueHash,
  senderUniqueHash,
  reason,
  isPep,                  // boolean
  accountCreationDate,
  lastTransactionDate,
  mode,                   // UPI | IMPS | NEFT | RTGS | CASH | CHEQUE | ATM
  beneficiaryType,        // DOMESTIC | INTERNATIONAL
  receiverCountry,
  businessKycType,        // e.g. NGO
  counterPartyBankName
}

Handling Decisions

const resp = await devIntelligenceSdk.trackTransactionAsync(payload);

if (resp.eventType === "NO_ACTION") {
  devIntelligenceSdk.trackTransactionSuccess(payload);
  Swal.fire("Transaction Successful");

} else if (resp.action === "Flag/Risk") {
  Swal.fire({
    title: "Risk detected",
    text: resp.message,
    showCancelButton: true,
  }).then((result) => {
    if (result.isConfirmed) {
      devIntelligenceSdk.trackTransactionSuccess(payload);
    } else {
      devIntelligenceSdk.trackTransactionFail(payload);
    }
  });

} else if (resp.action === "Block Action") {
  Swal.fire("Transaction Blocked", resp.message, "error");
  devIntelligenceSdk.trackTransactionFail(payload);
}

Account Activity Tracking

Track non-monetary but risk-relevant user actions.

devIntelligenceSdk.updateUserId("123434356");

devIntelligenceSdk.trackAccountActivity({
  beneficiaryUniqueHash: "abc123",
  activityType: "BENEFICIARY_ADDED",
});

Example Activity Types

• BENEFICIARY_ADDED
• BENEFICIARY_REMOVED
• PROFILE_UPDATED
• PASSWORD_CHANGED

Action Types & Decision Handling

| Action / EventType | Meaning | Expected App Behavior | | --------------------- | ------------------- | --------------------- | | NO_ACTION | Low risk | Auto-allow | | Flag/Risk | Medium risk | Warn user / confirm | | Block Action | High risk | Block operation | | eventType=NO_ACTION | Transaction allowed | Commit transaction |

⚠️ The SDK does not enforce UI or business logic. Your application is responsible for final decisions.

API Reference

| Function | Description | | ------------------------------- | --------------------------- | | DeviceIntelligenceSDK(config) | Create SDK instance | | start() | Start SDK connection | | updateUserId(userId) | Set active user | | getGlobalAlertListener() | Subscribe to alerts | | trackLoginAsync() | Login risk evaluation | | trackLoginSuccess() | Notify login success | | trackLoginFail() | Notify login failure | | trackSignupAsync() | Signup risk evaluation | | trackSignUpSuccess() | Notify signup success | | trackSignUpFail() | Notify signup failure | | trackTransactionAsync() | Transaction risk evaluation | | trackTransactionSuccess() | Confirm transaction | | trackTransactionFail() | Fail transaction | | trackAccountActivity() | Track non-monetary activity |

Troubleshooting & Tips

• SDK not starting → verify WebSocket URL
• No alerts → subscribe after start()
• Duplicate alerts → ensure singleton SDK
• Blocked flows → always call track*Fail
• Security → productId is safe to expose
• Debugging → log full SDK response objects

Custom Logic Summary

| Area | Application Responsibility | | ---------------- | --------------------------------- | | Login | OTP, CAPTCHA, allow-with-risk | | Signup | Verification, onboarding decision | | Transactions | Confirm / cancel flows | | Account activity | Silent risk signals | | Global alerts | UI warnings, audit logs |

Device Intelligence SDK provides risk signals — your application owns the final decision.